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(_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         static IIO_CONST_ATTR(_name##_index, #_number)
 248
 249 #define IIO_SCAN_EL_C(_name, _number, _label, _controlfunc)     \
 250         __IIO_SCAN_EL_C(_name, _number, _label, _controlfunc)
 251
 252 #define __IIO_SCAN_NAMED_EL_C(_name, _string, _number, _label, _cf)     \
 253         struct iio_scan_el iio_scan_el_##_name = {                      \
 254                 .dev_attr = __ATTR(_string##_en,                        \
 255                                    S_IRUGO | S_IWUSR,                   \
 256                                    iio_scan_el_show,                    \
 257                                    iio_scan_el_store),                  \
 258                 .number =  _number,                                     \
 259                 .label = _label,                                        \
 260                 .set_state = _cf,                                       \
 261         };                                                              \
 262         static struct iio_const_attr iio_const_attr_##_name##_index = { \
 263                 .string = #_number,                                     \
 264                 .dev_attr = __ATTR(_string##_index,                     \
 265                                    S_IRUGO, iio_read_const_attr, NULL)  \
 266         }
 267
 268
 269 #define IIO_SCAN_NAMED_EL_C(_name, _string, _number, _label, _cf) \
 270         __IIO_SCAN_NAMED_EL_C(_name, _string, _number, _label, _cf)
 271 /**
 272  * IIO_SCAN_EL_TIMESTAMP - declare a special scan element for timestamps
 273  * @number: specify where in the scan order this is stored.
 274  *
 275  * Odd one out. Handled slightly differently from other scan elements.
 276  **/
 277 #define IIO_SCAN_EL_TIMESTAMP(number)                           \
 278         struct iio_scan_el iio_scan_el_timestamp = {            \
 279                 .dev_attr = __ATTR(timestamp_en,                \
 280                                    S_IRUGO | S_IWUSR,           \
 281                                    iio_scan_el_ts_show,         \
 282                                    iio_scan_el_ts_store),       \
 283         };                                                      \
 284         static IIO_CONST_ATTR(timestamp_index, #number)
 285
 286 /**
 287  * IIO_CONST_ATTR_SCAN_EL_TYPE - attr to specify the data format of a scan el
 288  * @name: the scan el name (may be more general and cover a set of scan elements
 289  * @_sign: either s or u for signed or unsigned
 290  * @_bits: number of actual bits occuplied by the value
 291  * @_storagebits: number of bits _bits is padded to when read out of buffer
 292  **/
 293 #define IIO_CONST_ATTR_SCAN_EL_TYPE(_name, _sign, _bits, _storagebits) \
 294         IIO_CONST_ATTR(_name##_type, #_sign#_bits"/"#_storagebits);
 295 /*
 296  * These are mainly provided to allow for a change of implementation if a device
 297  * has a large number of scan elements
 298  */
 299 #define IIO_MAX_SCAN_LENGTH 31
 300
 301 /* note 0 used as error indicator as it doesn't make sense. */
 302 static inline u32 iio_scan_mask_match(u32 *av_masks, u32 mask)
 303 {
 304         while (*av_masks) {
 305                 if (!(~*av_masks & mask))
 306                         return *av_masks;
 307                 av_masks++;
 308         }
 309         return 0;
 310 }
 311
 312 static inline int iio_scan_mask_query(struct iio_ring_buffer *ring, int bit)
 313 {
 314         struct iio_dev *dev_info = ring->indio_dev;
 315         u32 mask;
 316
 317         if (bit > IIO_MAX_SCAN_LENGTH)
 318                 return -EINVAL;
 319
 320         if (!ring->scan_mask)
 321                 return 0;
 322
 323         if (dev_info->available_scan_masks)
 324                 mask = iio_scan_mask_match(dev_info->available_scan_masks,
 325                                         ring->scan_mask);
 326         else
 327                 mask = ring->scan_mask;
 328
 329         if (!mask)
 330                 return -EINVAL;
 331
 332         return !!(mask & (1 << bit));
 333 };
 334
 335 /**
 336  * iio_scan_mask_set() - set particular bit in the scan mask
 337  * @ring: the ring buffer whose scan mask we are interested in
 338  * @bit: the bit to be set.
 339  **/
 340 static inline int iio_scan_mask_set(struct iio_ring_buffer *ring, int bit)
 341 {
 342         struct iio_dev *dev_info = ring->indio_dev;
 343         u32 mask;
 344         u32 trialmask = ring->scan_mask | (1 << bit);
 345
 346         if (bit > IIO_MAX_SCAN_LENGTH)
 347                 return -EINVAL;
 348         if (dev_info->available_scan_masks) {
 349                 mask = iio_scan_mask_match(dev_info->available_scan_masks,
 350                                         trialmask);
 351                 if (!mask)
 352                         return -EINVAL;
 353         }
 354         ring->scan_mask = trialmask;
 355         ring->scan_count++;
 356
 357         return 0;
 358 };
 359
 360 /**
 361  * iio_scan_mask_clear() - clear a particular element from the scan mask
 362  * @ring: the ring buffer whose scan mask we are interested in
 363  * @bit: the bit to clear
 364  **/
 365 static inline int iio_scan_mask_clear(struct iio_ring_buffer *ring, int bit)
 366 {
 367         if (bit > IIO_MAX_SCAN_LENGTH)
 368                 return -EINVAL;
 369         ring->scan_mask &= ~(1 << bit);
 370         ring->scan_count--;
 371         return 0;
 372 };
 373
 374 /**
 375  * iio_scan_mask_count_to_right() - how many scan elements occur before here
 376  * @ring: the ring buffer whose scan mask we interested in
 377  * @bit: which number scan element is this
 378  **/
 379 static inline int iio_scan_mask_count_to_right(struct iio_ring_buffer *ring,
 380                                                 int bit)
 381 {
 382         int count = 0;
 383         int mask = (1 << bit);
 384         if (bit > IIO_MAX_SCAN_LENGTH)
 385                 return -EINVAL;
 386         while (mask) {
 387                 mask >>= 1;
 388                 if (mask & ring->scan_mask)
 389                         count++;
 390         }
 391
 392         return count;
 393 }
 394
 395 /**
 396  * iio_put_ring_buffer() - notify done with buffer
 397  * @ring: the buffer we are done with.
 398  **/
 399 static inline void iio_put_ring_buffer(struct iio_ring_buffer *ring)
 400 {
 401         put_device(&ring->dev);
 402 };
 403
 404 #define to_iio_ring_buffer(d)                   \
 405         container_of(d, struct iio_ring_buffer, dev)
 406 #define access_dev_to_iio_ring_buffer(d)                        \
 407         container_of(d, struct iio_ring_buffer, access_dev)
 408
 409 /**
 410  * iio_ring_buffer_register() - register the buffer with IIO core
 411  * @ring: the buffer to be registered
 412  * @id: the id of the buffer (typically 0)
 413  **/
 414 int iio_ring_buffer_register(struct iio_ring_buffer *ring, int id);
 415
 416 /**
 417  * iio_ring_buffer_unregister() - unregister the buffer from IIO core
 418  * @ring: the buffer to be unregistered
 419  **/
 420 void iio_ring_buffer_unregister(struct iio_ring_buffer *ring);
 421
 422 /**
 423  * iio_read_ring_length() - attr func to get number of datums in the buffer
 424  **/
 425 ssize_t iio_read_ring_length(struct device *dev,
 426                              struct device_attribute *attr,
 427                              char *buf);
 428 /**
 429  * iio_write_ring_length() - attr func to set number of datums in the buffer
 430  **/
 431 ssize_t iio_write_ring_length(struct device *dev,
 432                               struct device_attribute *attr,
 433                               const char *buf,
 434                               size_t len);
 435 /**
 436  * iio_read_ring_bytes_per_datum() - attr for number of bytes in whole datum
 437  **/
 438 ssize_t iio_read_ring_bytes_per_datum(struct device *dev,
 439                           struct device_attribute *attr,
 440                           char *buf);
 441 /**
 442  * iio_store_ring_enable() - attr to turn the buffer on
 443  **/
 444 ssize_t iio_store_ring_enable(struct device *dev,
 445                               struct device_attribute *attr,
 446                               const char *buf,
 447                               size_t len);
 448 /**
 449  * iio_show_ring_enable() - attr to see if the buffer is on
 450  **/
 451 ssize_t iio_show_ring_enable(struct device *dev,
 452                              struct device_attribute *attr,
 453                              char *buf);
 454 #define IIO_RING_LENGTH_ATTR DEVICE_ATTR(length, S_IRUGO | S_IWUSR,     \
 455                                          iio_read_ring_length,          \
 456                                          iio_write_ring_length)
 457 #define IIO_RING_BYTES_PER_DATUM_ATTR DEVICE_ATTR(bytes_per_datum, S_IRUGO | S_IWUSR,   \
 458                                       iio_read_ring_bytes_per_datum, NULL)
 459 #define IIO_RING_ENABLE_ATTR DEVICE_ATTR(enable, S_IRUGO | S_IWUSR, \
 460                                          iio_show_ring_enable,          \
 461                                          iio_store_ring_enable)
 462 #else /* CONFIG_IIO_RING_BUFFER */
 463 static inline int iio_ring_buffer_register(struct iio_ring_buffer *ring, int id)
 464 {
 465         return 0;
 466 };
 467 static inline void iio_ring_buffer_unregister(struct iio_ring_buffer *ring)
 468 {};
 469
 470 #endif /* CONFIG_IIO_RING_BUFFER */
 471
 472 #endif /* _IIO_RING_GENERIC_H_ */