drivers/staging/iio/ring_generic.h

   1 /* The industrial I/O core - generic ring buffer interfaces.
   2  *
   3  * Copyright (c) 2008 Jonathan Cameron
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 as published by
   7  * the Free Software Foundation.
   8  */
   9
  10 #ifndef _IIO_RING_GENERIC_H_
  11 #define _IIO_RING_GENERIC_H_
  12 #include "iio.h"
  13
  14 #ifdef CONFIG_IIO_RING_BUFFER
  15
  16 struct iio_ring_buffer;
  17
  18 /**
  19  * iio_push_ring_event() - ring buffer specific push to event chrdev
  20  * @ring_buf:           ring buffer that is the event source
  21  * @event_code:         event indentification code
  22  * @timestamp:          time of event
  23  **/
  24 int iio_push_ring_event(struct iio_ring_buffer *ring_buf,
  25                         int event_code,
  26                         s64 timestamp);
  27 /**
  28  * iio_push_or_escallate_ring_event() - escalate or add as appropriate
  29  * @ring_buf:           ring buffer that is the event source
  30  * @event_code:         event indentification code
  31  * @timestamp:          time of event
  32  *
  33  * Typical usecase is to escalate a 50% ring full to 75% full if noone has yet
  34  * read the first event. Clearly the 50% full is no longer of interest in
  35  * typical use case.
  36  **/
  37 int iio_push_or_escallate_ring_event(struct iio_ring_buffer *ring_buf,
  38                                      int event_code,
  39                                      s64 timestamp);
  40
  41 /**
  42  * struct iio_ring_access_funcs - access functions for ring buffers.
  43  * @mark_in_use:        reference counting, typically to prevent module removal
  44  * @unmark_in_use:      reduce reference count when no longer using ring buffer
  45  * @store_to:           actually store stuff to the ring buffer
  46  * @read_last:          get the last element stored
  47  * @rip_lots:           try to get a specified number of elements (must exist)
  48  * @mark_param_change:  notify ring that some relevant parameter has changed
  49  *                      Often this means the underlying storage may need to
  50  *                      change.
  51  * @request_update:     if a parameter change has been marked, update underlying
  52  *                      storage.
  53  * @get_bytes_per_datum:get current bytes per datum
  54  * @set_bytes_per_datum:set number of bytes per datum
  55  * @get_length:         get number of datums in ring
  56  * @set_length:         set number of datums in ring
  57  * @is_enabled:         query if ring is currently being used
  58  * @enable:             enable the ring
  59  *
  60  * The purpose of this structure is to make the ring buffer element
  61  * modular as event for a given driver, different usecases may require
  62  * different ring designs (space efficiency vs speed for example).
  63  *
  64  * It is worth noting that a given ring implementation may only support a small
  65  * proportion of these functions.  The core code 'should' cope fine with any of
  66  * them not existing.
  67  **/
  68 struct iio_ring_access_funcs {
  69         void (*mark_in_use)(struct iio_ring_buffer *ring);
  70         void (*unmark_in_use)(struct iio_ring_buffer *ring);
  71
  72         int (*store_to)(struct iio_ring_buffer *ring, u8 *data, s64 timestamp);
  73         int (*read_last)(struct iio_ring_buffer *ring, u8 *data);
  74         int (*rip_lots)(struct iio_ring_buffer *ring,
  75                         size_t count,
  76                         u8 **data,
  77                         int *dead_offset);
  78
  79         int (*mark_param_change)(struct iio_ring_buffer *ring);
  80         int (*request_update)(struct iio_ring_buffer *ring);
  81
  82         int (*get_bytes_per_datum)(struct iio_ring_buffer *ring);
  83         int (*set_bytes_per_datum)(struct iio_ring_buffer *ring, size_t bpd);
  84         int (*get_length)(struct iio_ring_buffer *ring);
  85         int (*set_length)(struct iio_ring_buffer *ring, int length);
  86
  87         int (*is_enabled)(struct iio_ring_buffer *ring);
  88         int (*enable)(struct iio_ring_buffer *ring);
  89 };
  90
  91 /**
  92  * struct iio_ring_buffer - general ring buffer structure
  93  * @dev:                ring buffer device struct
  94  * @access_dev:         system device struct for the chrdev
  95  * @indio_dev:          industrial I/O device structure
  96  * @owner:              module that owns the ring buffer (for ref counting)
  97  * @id:                 unique id number
  98  * @access_id:          device id number
  99  * @length:             [DEVICE] number of datums in ring
 100  * @bytes_per_datum:    [DEVICE] size of individual datum including timestamp
 101  * @bpe:                [DEVICE] size of individual channel value
 102  * @loopcount:          [INTERN] number of times the ring has looped
 103  * @scan_el_attrs:      [DRIVER] control of scan elements if that scan mode
 104  *                      control method is used
 105  * @scan_count: [INTERN] the number of elements in the current scan mode
 106  * @scan_mask:          [INTERN] bitmask used in masking scan mode elements
 107  * @scan_timestamp:     [INTERN] does the scan mode include a timestamp
 108  * @access_handler:     [INTERN] chrdev access handling
 109  * @ev_int:             [INTERN] chrdev interface for the event chrdev
 110  * @shared_ev_pointer:  [INTERN] the shared event pointer to allow escalation of
 111  *                      events
 112  * @access:             [DRIVER] ring access functions associated with the
 113  *                      implementation.
 114  * @preenable:          [DRIVER] function to run prior to marking ring enabled
 115  * @postenable:         [DRIVER] function to run after marking ring enabled
 116  * @predisable:         [DRIVER] function to run prior to marking ring disabled
 117  * @postdisable:        [DRIVER] function to run after marking ring disabled
 118   **/
 119 struct iio_ring_buffer {
 120         struct device dev;
 121         struct device access_dev;
 122         struct iio_dev *indio_dev;
 123         struct module *owner;
 124         int                             id;
 125         int                             access_id;
 126         int                             length;
 127         int                             bytes_per_datum;
 128         int                             bpe;
 129         int                             loopcount;
 130         struct attribute_group          *scan_el_attrs;
 131         int                             scan_count;
 132         u32                             scan_mask;
 133         bool                            scan_timestamp;
 134         struct iio_handler              access_handler;
 135         struct iio_event_interface      ev_int;
 136         struct iio_shared_ev_pointer    shared_ev_pointer;
 137         struct iio_ring_access_funcs    access;
 138         int                             (*preenable)(struct iio_dev *);
 139         int                             (*postenable)(struct iio_dev *);
 140         int                             (*predisable)(struct iio_dev *);
 141         int                             (*postdisable)(struct iio_dev *);
 142
 143 };
 144
 145 /**
 146  * iio_ring_buffer_init() - Initialize the buffer structure
 147  * @ring: buffer to be initialized
 148  * @dev_info: the iio device the buffer is assocated with
 149  **/
 150 void iio_ring_buffer_init(struct iio_ring_buffer *ring,
 151                           struct iio_dev *dev_info);
 152
 153 /**
 154  * __iio_update_ring_buffer() - update common elements of ring buffers
 155  * @ring:               ring buffer that is the event source
 156  * @bytes_per_datum:    size of individual datum including timestamp
 157  * @length:             number of datums in ring
 158  **/
 159 static inline void __iio_update_ring_buffer(struct iio_ring_buffer *ring,
 160                                             int bytes_per_datum, int length)
 161 {
 162         ring->bytes_per_datum = bytes_per_datum;
 163         ring->length = length;
 164         ring->loopcount = 0;
 165 }
 166
 167 /**
 168  * struct iio_scan_el - an individual element of a scan
 169  * @dev_attr:           control attribute (if directly controllable)
 170  * @number:             unique identifier of element (used for bit mask)
 171  * @bit_count:          number of bits in scan element
 172  * @label:              useful data for the scan el (often reg address)
 173  * @set_state:          for some devices datardy signals are generated
 174  *                      for any enabled lines.  This allows unwanted lines
 175  *                      to be disabled and hence not get in the way.
 176  **/
 177 struct iio_scan_el {
 178         struct device_attribute         dev_attr;
 179         unsigned int                    number;
 180         int                             bit_count;
 181         unsigned int                    label;
 182
 183         int (*set_state)(struct iio_scan_el *scanel,
 184                          struct iio_dev *dev_info,
 185                          bool state);
 186 };
 187
 188 #define to_iio_scan_el(_dev_attr)                               \
 189         container_of(_dev_attr, struct iio_scan_el, dev_attr);
 190
 191 /**
 192  * iio_scan_el_store() - sysfs scan element selection interface
 193  * @dev: the target device
 194  * @attr: the device attribute that is being processed
 195  * @buf: input from userspace
 196  * @len: length of input
 197  *
 198  * A generic function used to enable various scan elements.  In some
 199  * devices explicit read commands for each channel mean this is merely
 200  * a software switch.  In others this must actively disable the channel.
 201  * Complexities occur when this interacts with data ready type triggers
 202  * which may not reset unless every channel that is enabled is explicitly
 203  * read.
 204  **/
 205 ssize_t iio_scan_el_store(struct device *dev, struct device_attribute *attr,
 206                           const char *buf, size_t len);
 207 /**
 208  * iio_scan_el_show() - sysfs interface to query whether a scan element
 209  *                      is enabled or not
 210  * @dev: the target device
 211  * @attr: the device attribute that is being processed
 212  * @buf: output buffer
 213  **/
 214 ssize_t iio_scan_el_show(struct device *dev, struct device_attribute *attr,
 215                          char *buf);
 216
 217 /**
 218  * iio_scan_el_ts_store() - sysfs interface to set whether a timestamp is included
 219  *                          in the scan.
 220  **/
 221 ssize_t iio_scan_el_ts_store(struct device *dev, struct device_attribute *attr,
 222                              const char *buf, size_t len);
 223 /**
 224  * iio_scan_el_ts_show() - sysfs interface to query if a timestamp is included
 225  *                         in the scan.
 226  **/
 227 ssize_t iio_scan_el_ts_show(struct device *dev, struct device_attribute *attr,
 228                             char *buf);
 229 /**
 230  * IIO_SCAN_EL_C - declare and initialize a scan element with a control func
 231  *
 232  * @_name:      identifying name. Resulting struct is iio_scan_el_##_name,
 233  *              sysfs element, _name##_en.
 234  * @_number:    unique id number for the scan element.
 235  * @_bits:      number of bits in the scan element result (used in mixed bit
 236  *              length devices).
 237  * @_label:     indentification variable used by drivers.  Often a reg address.
 238  * @_controlfunc: function used to notify hardware of whether state changes
 239  **/
 240 #define __IIO_SCAN_EL_C(_name, _number, _bits, _label, _controlfunc)    \
 241         struct iio_scan_el iio_scan_el_##_name = {                      \
 242                 .dev_attr = __ATTR(_number##_##_name##_en,              \
 243                                    S_IRUGO | S_IWUSR,                   \
 244                                    iio_scan_el_show,                    \
 245                                    iio_scan_el_store),                  \
 246                 .number =  _number,                                     \
 247                 .bit_count = _bits,                                     \
 248                 .label = _label,                                        \
 249                 .set_state = _controlfunc,                              \
 250         }
 251
 252 #define IIO_SCAN_EL_C(_name, _number, _bits, _label, _controlfunc)      \
 253         __IIO_SCAN_EL_C(_name, _number, _bits, _label, _controlfunc)
 254
 255 #define __IIO_SCAN_NAMED_EL_C(_name, _string, _number, _bits, _label, _cf) \
 256         struct iio_scan_el iio_scan_el_##_name = {                      \
 257                 .dev_attr = __ATTR(_number##_##_string##_en,            \
 258                                    S_IRUGO | S_IWUSR,                   \
 259                                    iio_scan_el_show,                    \
 260                                    iio_scan_el_store),                  \
 261                 .number =  _number,                                     \
 262                 .bit_count = _bits,                                     \
 263                 .label = _label,                                        \
 264                 .set_state = _cf,                                       \
 265         }
 266 #define IIO_SCAN_NAMED_EL_C(_name, _string, _number, _bits, _label, _cf) \
 267         __IIO_SCAN_NAMED_EL_C(_name, _string, _number, _bits, _label, _cf)
 268 /**
 269  * IIO_SCAN_EL_TIMESTAMP - declare a special scan element for timestamps
 270  * @number: specify where in the scan order this is stored.
 271  *
 272  * Odd one out. Handled slightly differently from other scan elements.
 273  **/
 274 #define IIO_SCAN_EL_TIMESTAMP(number)                           \
 275         struct iio_scan_el iio_scan_el_timestamp = {            \
 276                 .dev_attr = __ATTR(number##_timestamp_en,       \
 277                                    S_IRUGO | S_IWUSR,           \
 278                                    iio_scan_el_ts_show,         \
 279                                    iio_scan_el_ts_store),       \
 280         }
 281
 282 /**
 283  * IIO_CONST_ATTR_SCAN_EL_TYPE - attr to specify the data format of a scan el
 284  * @name: the scan el name (may be more general and cover a set of scan elements
 285  * @_sign: either s or u for signed or unsigned
 286  * @_bits: number of actual bits occuplied by the value
 287  * @_storagebits: number of bits _bits is padded to when read out of buffer
 288  **/
 289 #define IIO_CONST_ATTR_SCAN_EL_TYPE(_name, _sign, _bits, _storagebits) \
 290         IIO_CONST_ATTR(_name##_type, #_sign#_bits"/"#_storagebits);
 291 /*
 292  * These are mainly provided to allow for a change of implementation if a device
 293  * has a large number of scan elements
 294  */
 295 #define IIO_MAX_SCAN_LENGTH 31
 296
 297 /* note 0 used as error indicator as it doesn't make sense. */
 298 static inline u32 iio_scan_mask_match(u32 *av_masks, u32 mask)
 299 {
 300         while (*av_masks) {
 301                 if (!(~*av_masks & mask))
 302                         return *av_masks;
 303                 av_masks++;
 304         }
 305         return 0;
 306 }
 307
 308 static inline int iio_scan_mask_query(struct iio_ring_buffer *ring, int bit)
 309 {
 310         struct iio_dev *dev_info = ring->indio_dev;
 311         u32 mask;
 312
 313         if (bit > IIO_MAX_SCAN_LENGTH)
 314                 return -EINVAL;
 315
 316         if (!ring->scan_mask)
 317                 return 0;
 318
 319         if (dev_info->available_scan_masks)
 320                 mask = iio_scan_mask_match(dev_info->available_scan_masks,
 321                                         ring->scan_mask);
 322         else
 323                 mask = ring->scan_mask;
 324
 325         if (!mask)
 326                 return -EINVAL;
 327
 328         return !!(mask & (1 << bit));
 329 };
 330
 331 /**
 332  * iio_scan_mask_set() - set particular bit in the scan mask
 333  * @ring: the ring buffer whose scan mask we are interested in
 334  * @bit: the bit to be set.
 335  **/
 336 static inline int iio_scan_mask_set(struct iio_ring_buffer *ring, int bit)
 337 {
 338         struct iio_dev *dev_info = ring->indio_dev;
 339         u32 mask;
 340         u32 trialmask = ring->scan_mask | (1 << bit);
 341
 342         if (bit > IIO_MAX_SCAN_LENGTH)
 343                 return -EINVAL;
 344         if (dev_info->available_scan_masks) {
 345                 mask = iio_scan_mask_match(dev_info->available_scan_masks,
 346                                         trialmask);
 347                 if (!mask)
 348                         return -EINVAL;
 349         }
 350         ring->scan_mask = trialmask;
 351         ring->scan_count++;
 352
 353         return 0;
 354 };
 355
 356 /**
 357  * iio_scan_mask_clear() - clear a particular element from the scan mask
 358  * @ring: the ring buffer whose scan mask we are interested in
 359  * @bit: the bit to clear
 360  **/
 361 static inline int iio_scan_mask_clear(struct iio_ring_buffer *ring, int bit)
 362 {
 363         if (bit > IIO_MAX_SCAN_LENGTH)
 364                 return -EINVAL;
 365         ring->scan_mask &= ~(1 << bit);
 366         ring->scan_count--;
 367         return 0;
 368 };
 369
 370 /**
 371  * iio_scan_mask_count_to_right() - how many scan elements occur before here
 372  * @ring: the ring buffer whose scan mask we interested in
 373  * @bit: which number scan element is this
 374  **/
 375 static inline int iio_scan_mask_count_to_right(struct iio_ring_buffer *ring,
 376                                                 int bit)
 377 {
 378         int count = 0;
 379         int mask = (1 << bit);
 380         if (bit > IIO_MAX_SCAN_LENGTH)
 381                 return -EINVAL;
 382         while (mask) {
 383                 mask >>= 1;
 384                 if (mask & ring->scan_mask)
 385                         count++;
 386         }
 387
 388         return count;
 389 }
 390
 391 /**
 392  * iio_put_ring_buffer() - notify done with buffer
 393  * @ring: the buffer we are done with.
 394  **/
 395 static inline void iio_put_ring_buffer(struct iio_ring_buffer *ring)
 396 {
 397         put_device(&ring->dev);
 398 };
 399
 400 #define to_iio_ring_buffer(d)                   \
 401         container_of(d, struct iio_ring_buffer, dev)
 402 #define access_dev_to_iio_ring_buffer(d)                        \
 403         container_of(d, struct iio_ring_buffer, access_dev)
 404
 405 /**
 406  * iio_ring_buffer_register() - register the buffer with IIO core
 407  * @ring: the buffer to be registered
 408  * @id: the id of the buffer (typically 0)
 409  **/
 410 int iio_ring_buffer_register(struct iio_ring_buffer *ring, int id);
 411
 412 /**
 413  * iio_ring_buffer_unregister() - unregister the buffer from IIO core
 414  * @ring: the buffer to be unregistered
 415  **/
 416 void iio_ring_buffer_unregister(struct iio_ring_buffer *ring);
 417
 418 /**
 419  * iio_read_ring_length() - attr func to get number of datums in the buffer
 420  **/
 421 ssize_t iio_read_ring_length(struct device *dev,
 422                              struct device_attribute *attr,
 423                              char *buf);
 424 /**
 425  * iio_write_ring_length() - attr func to set number of datums in the buffer
 426  **/
 427 ssize_t iio_write_ring_length(struct device *dev,
 428                               struct device_attribute *attr,
 429                               const char *buf,
 430                               size_t len);
 431 /**
 432  * iio_read_ring_bytes_per_datum() - attr for number of bytes in whole datum
 433  **/
 434 ssize_t iio_read_ring_bytes_per_datum(struct device *dev,
 435                           struct device_attribute *attr,
 436                           char *buf);
 437 /**
 438  * iio_store_ring_enable() - attr to turn the buffer on
 439  **/
 440 ssize_t iio_store_ring_enable(struct device *dev,
 441                               struct device_attribute *attr,
 442                               const char *buf,
 443                               size_t len);
 444 /**
 445  * iio_show_ring_enable() - attr to see if the buffer is on
 446  **/
 447 ssize_t iio_show_ring_enable(struct device *dev,
 448                              struct device_attribute *attr,
 449                              char *buf);
 450 #define IIO_RING_LENGTH_ATTR DEVICE_ATTR(length, S_IRUGO | S_IWUSR,     \
 451                                          iio_read_ring_length,          \
 452                                          iio_write_ring_length)
 453 #define IIO_RING_BYTES_PER_DATUM_ATTR DEVICE_ATTR(bytes_per_datum, S_IRUGO | S_IWUSR,   \
 454                                       iio_read_ring_bytes_per_datum, NULL)
 455 #define IIO_RING_ENABLE_ATTR DEVICE_ATTR(enable, S_IRUGO | S_IWUSR, \
 456                                          iio_show_ring_enable,          \
 457                                          iio_store_ring_enable)
 458 #else /* CONFIG_IIO_RING_BUFFER */
 459 static inline int iio_ring_buffer_register(struct iio_ring_buffer *ring, int id)
 460 {
 461         return 0;
 462 };
 463 static inline void iio_ring_buffer_unregister(struct iio_ring_buffer *ring)
 464 {};
 465
 466 #endif /* CONFIG_IIO_RING_BUFFER */
 467
 468 #endif /* _IIO_RING_GENERIC_H_ */