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  * @label:              useful data for the scan el (often reg address)
 172  * @set_state:          for some devices datardy signals are generated
 173  *                      for any enabled lines.  This allows unwanted lines
 174  *                      to be disabled and hence not get in the way.
 175  **/
 176 struct iio_scan_el {
 177         struct device_attribute         dev_attr;
 178         unsigned int                    number;
 179         unsigned int                    label;
 180
 181         int (*set_state)(struct iio_scan_el *scanel,
 182                          struct iio_dev *dev_info,
 183                          bool state);
 184 };
 185
 186 #define to_iio_scan_el(_dev_attr)                               \
 187         container_of(_dev_attr, struct iio_scan_el, dev_attr);
 188
 189 /**
 190  * iio_scan_el_store() - sysfs scan element selection interface
 191  * @dev: the target device
 192  * @attr: the device attribute that is being processed
 193  * @buf: input from userspace
 194  * @len: length of input
 195  *
 196  * A generic function used to enable various scan elements.  In some
 197  * devices explicit read commands for each channel mean this is merely
 198  * a software switch.  In others this must actively disable the channel.
 199  * Complexities occur when this interacts with data ready type triggers
 200  * which may not reset unless every channel that is enabled is explicitly
 201  * read.
 202  **/
 203 ssize_t iio_scan_el_store(struct device *dev, struct device_attribute *attr,
 204                           const char *buf, size_t len);
 205 /**
 206  * iio_scan_el_show() - sysfs interface to query whether a scan element
 207  *                      is enabled or not
 208  * @dev: the target device
 209  * @attr: the device attribute that is being processed
 210  * @buf: output buffer
 211  **/
 212 ssize_t iio_scan_el_show(struct device *dev, struct device_attribute *attr,
 213                          char *buf);
 214
 215 /**
 216  * iio_scan_el_ts_store() - sysfs interface to set whether a timestamp is included
 217  *                          in the scan.
 218  **/
 219 ssize_t iio_scan_el_ts_store(struct device *dev, struct device_attribute *attr,
 220                              const char *buf, size_t len);
 221 /**
 222  * iio_scan_el_ts_show() - sysfs interface to query if a timestamp is included
 223  *                         in the scan.
 224  **/
 225 ssize_t iio_scan_el_ts_show(struct device *dev, struct device_attribute *attr,
 226                             char *buf);
 227 /**
 228  * IIO_SCAN_EL_C - declare and initialize a scan element with a control func
 229  *
 230  * @_name:      identifying name. Resulting struct is iio_scan_el_##_name,
 231  *              sysfs element, _name##_en.
 232  * @_number:    unique id number for the scan element.
 233  *              length devices).
 234  * @_label:     indentification variable used by drivers.  Often a reg address.
 235  * @_controlfunc: function used to notify hardware of whether state changes
 236  **/
 237 #define __IIO_SCAN_EL_C(_name, _number, _label, _controlfunc)   \
 238         struct iio_scan_el iio_scan_el_##_name = {                      \
 239                 .dev_attr = __ATTR(_number##_##_name##_en,              \
 240                                    S_IRUGO | S_IWUSR,                   \
 241                                    iio_scan_el_show,                    \
 242                                    iio_scan_el_store),                  \
 243                 .number =  _number,                                     \
 244                 .label = _label,                                        \
 245                 .set_state = _controlfunc,                              \
 246         }
 247
 248 #define IIO_SCAN_EL_C(_name, _number, _label, _controlfunc)     \
 249         __IIO_SCAN_EL_C(_name, _number, _label, _controlfunc)
 250
 251 #define __IIO_SCAN_NAMED_EL_C(_name, _string, _number, _label, _cf) \
 252         struct iio_scan_el iio_scan_el_##_name = {                      \
 253                 .dev_attr = __ATTR(_number##_##_string##_en,            \
 254                                    S_IRUGO | S_IWUSR,                   \
 255                                    iio_scan_el_show,                    \
 256                                    iio_scan_el_store),                  \
 257                 .number =  _number,                                     \
 258                 .label = _label,                                        \
 259                 .set_state = _cf,                                       \
 260         }
 261 #define IIO_SCAN_NAMED_EL_C(_name, _string, _number, _label, _cf) \
 262         __IIO_SCAN_NAMED_EL_C(_name, _string, _number, _label, _cf)
 263 /**
 264  * IIO_SCAN_EL_TIMESTAMP - declare a special scan element for timestamps
 265  * @number: specify where in the scan order this is stored.
 266  *
 267  * Odd one out. Handled slightly differently from other scan elements.
 268  **/
 269 #define IIO_SCAN_EL_TIMESTAMP(number)                           \
 270         struct iio_scan_el iio_scan_el_timestamp = {            \
 271                 .dev_attr = __ATTR(number##_timestamp_en,       \
 272                                    S_IRUGO | S_IWUSR,           \
 273                                    iio_scan_el_ts_show,         \
 274                                    iio_scan_el_ts_store),       \
 275         }
 276
 277 /**
 278  * IIO_CONST_ATTR_SCAN_EL_TYPE - attr to specify the data format of a scan el
 279  * @name: the scan el name (may be more general and cover a set of scan elements
 280  * @_sign: either s or u for signed or unsigned
 281  * @_bits: number of actual bits occuplied by the value
 282  * @_storagebits: number of bits _bits is padded to when read out of buffer
 283  **/
 284 #define IIO_CONST_ATTR_SCAN_EL_TYPE(_name, _sign, _bits, _storagebits) \
 285         IIO_CONST_ATTR(_name##_type, #_sign#_bits"/"#_storagebits);
 286 /*
 287  * These are mainly provided to allow for a change of implementation if a device
 288  * has a large number of scan elements
 289  */
 290 #define IIO_MAX_SCAN_LENGTH 31
 291
 292 /* note 0 used as error indicator as it doesn't make sense. */
 293 static inline u32 iio_scan_mask_match(u32 *av_masks, u32 mask)
 294 {
 295         while (*av_masks) {
 296                 if (!(~*av_masks & mask))
 297                         return *av_masks;
 298                 av_masks++;
 299         }
 300         return 0;
 301 }
 302
 303 static inline int iio_scan_mask_query(struct iio_ring_buffer *ring, int bit)
 304 {
 305         struct iio_dev *dev_info = ring->indio_dev;
 306         u32 mask;
 307
 308         if (bit > IIO_MAX_SCAN_LENGTH)
 309                 return -EINVAL;
 310
 311         if (!ring->scan_mask)
 312                 return 0;
 313
 314         if (dev_info->available_scan_masks)
 315                 mask = iio_scan_mask_match(dev_info->available_scan_masks,
 316                                         ring->scan_mask);
 317         else
 318                 mask = ring->scan_mask;
 319
 320         if (!mask)
 321                 return -EINVAL;
 322
 323         return !!(mask & (1 << bit));
 324 };
 325
 326 /**
 327  * iio_scan_mask_set() - set particular bit in the scan mask
 328  * @ring: the ring buffer whose scan mask we are interested in
 329  * @bit: the bit to be set.
 330  **/
 331 static inline int iio_scan_mask_set(struct iio_ring_buffer *ring, int bit)
 332 {
 333         struct iio_dev *dev_info = ring->indio_dev;
 334         u32 mask;
 335         u32 trialmask = ring->scan_mask | (1 << bit);
 336
 337         if (bit > IIO_MAX_SCAN_LENGTH)
 338                 return -EINVAL;
 339         if (dev_info->available_scan_masks) {
 340                 mask = iio_scan_mask_match(dev_info->available_scan_masks,
 341                                         trialmask);
 342                 if (!mask)
 343                         return -EINVAL;
 344         }
 345         ring->scan_mask = trialmask;
 346         ring->scan_count++;
 347
 348         return 0;
 349 };
 350
 351 /**
 352  * iio_scan_mask_clear() - clear a particular element from the scan mask
 353  * @ring: the ring buffer whose scan mask we are interested in
 354  * @bit: the bit to clear
 355  **/
 356 static inline int iio_scan_mask_clear(struct iio_ring_buffer *ring, int bit)
 357 {
 358         if (bit > IIO_MAX_SCAN_LENGTH)
 359                 return -EINVAL;
 360         ring->scan_mask &= ~(1 << bit);
 361         ring->scan_count--;
 362         return 0;
 363 };
 364
 365 /**
 366  * iio_scan_mask_count_to_right() - how many scan elements occur before here
 367  * @ring: the ring buffer whose scan mask we interested in
 368  * @bit: which number scan element is this
 369  **/
 370 static inline int iio_scan_mask_count_to_right(struct iio_ring_buffer *ring,
 371                                                 int bit)
 372 {
 373         int count = 0;
 374         int mask = (1 << bit);
 375         if (bit > IIO_MAX_SCAN_LENGTH)
 376                 return -EINVAL;
 377         while (mask) {
 378                 mask >>= 1;
 379                 if (mask & ring->scan_mask)
 380                         count++;
 381         }
 382
 383         return count;
 384 }
 385
 386 /**
 387  * iio_put_ring_buffer() - notify done with buffer
 388  * @ring: the buffer we are done with.
 389  **/
 390 static inline void iio_put_ring_buffer(struct iio_ring_buffer *ring)
 391 {
 392         put_device(&ring->dev);
 393 };
 394
 395 #define to_iio_ring_buffer(d)                   \
 396         container_of(d, struct iio_ring_buffer, dev)
 397 #define access_dev_to_iio_ring_buffer(d)                        \
 398         container_of(d, struct iio_ring_buffer, access_dev)
 399
 400 /**
 401  * iio_ring_buffer_register() - register the buffer with IIO core
 402  * @ring: the buffer to be registered
 403  * @id: the id of the buffer (typically 0)
 404  **/
 405 int iio_ring_buffer_register(struct iio_ring_buffer *ring, int id);
 406
 407 /**
 408  * iio_ring_buffer_unregister() - unregister the buffer from IIO core
 409  * @ring: the buffer to be unregistered
 410  **/
 411 void iio_ring_buffer_unregister(struct iio_ring_buffer *ring);
 412
 413 /**
 414  * iio_read_ring_length() - attr func to get number of datums in the buffer
 415  **/
 416 ssize_t iio_read_ring_length(struct device *dev,
 417                              struct device_attribute *attr,
 418                              char *buf);
 419 /**
 420  * iio_write_ring_length() - attr func to set number of datums in the buffer
 421  **/
 422 ssize_t iio_write_ring_length(struct device *dev,
 423                               struct device_attribute *attr,
 424                               const char *buf,
 425                               size_t len);
 426 /**
 427  * iio_read_ring_bytes_per_datum() - attr for number of bytes in whole datum
 428  **/
 429 ssize_t iio_read_ring_bytes_per_datum(struct device *dev,
 430                           struct device_attribute *attr,
 431                           char *buf);
 432 /**
 433  * iio_store_ring_enable() - attr to turn the buffer on
 434  **/
 435 ssize_t iio_store_ring_enable(struct device *dev,
 436                               struct device_attribute *attr,
 437                               const char *buf,
 438                               size_t len);
 439 /**
 440  * iio_show_ring_enable() - attr to see if the buffer is on
 441  **/
 442 ssize_t iio_show_ring_enable(struct device *dev,
 443                              struct device_attribute *attr,
 444                              char *buf);
 445 #define IIO_RING_LENGTH_ATTR DEVICE_ATTR(length, S_IRUGO | S_IWUSR,     \
 446                                          iio_read_ring_length,          \
 447                                          iio_write_ring_length)
 448 #define IIO_RING_BYTES_PER_DATUM_ATTR DEVICE_ATTR(bytes_per_datum, S_IRUGO | S_IWUSR,   \
 449                                       iio_read_ring_bytes_per_datum, NULL)
 450 #define IIO_RING_ENABLE_ATTR DEVICE_ATTR(enable, S_IRUGO | S_IWUSR, \
 451                                          iio_show_ring_enable,          \
 452                                          iio_store_ring_enable)
 453 #else /* CONFIG_IIO_RING_BUFFER */
 454 static inline int iio_ring_buffer_register(struct iio_ring_buffer *ring, int id)
 455 {
 456         return 0;
 457 };
 458 static inline void iio_ring_buffer_unregister(struct iio_ring_buffer *ring)
 459 {};
 460
 461 #endif /* CONFIG_IIO_RING_BUFFER */
 462
 463 #endif /* _IIO_RING_GENERIC_H_ */