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                         char __user *buf,
  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 /**
 297  * IIO_CONST_ATTR_SCAN_EL_TYPE_WITH_SHIFT - attr to specify the data format of a scan el
 298  * @name: the scan el name (may be more general and cover a set of scan elements
 299  * @_sign: either s or u for signed or unsigned
 300  * @_bits: number of actual bits occuplied by the value
 301  * @_storagebits: number of bits _bits is padded to when read out of buffer
 302  * @_shiftbits: number of bits _shiftbits the result must be shifted
 303  **/
 304 #define IIO_CONST_ATTR_SCAN_EL_TYPE_WITH_SHIFT(_name, _sign, _bits, \
 305                                                _storagebits, _shiftbits) \
 306         IIO_CONST_ATTR(_name##_type, #_sign#_bits"/"#_storagebits \
 307                        ">>"#_shiftbits);
 308
 309 #define IIO_SCAN_EL_TYPE_SIGNED         's'
 310 #define IIO_SCAN_EL_TYPE_UNSIGNED       'u'
 311
 312 /*
 313  * These are mainly provided to allow for a change of implementation if a device
 314  * has a large number of scan elements
 315  */
 316 #define IIO_MAX_SCAN_LENGTH 31
 317
 318 /* note 0 used as error indicator as it doesn't make sense. */
 319 static inline u32 iio_scan_mask_match(u32 *av_masks, u32 mask)
 320 {
 321         while (*av_masks) {
 322                 if (!(~*av_masks & mask))
 323                         return *av_masks;
 324                 av_masks++;
 325         }
 326         return 0;
 327 }
 328
 329 static inline int iio_scan_mask_query(struct iio_ring_buffer *ring, int bit)
 330 {
 331         struct iio_dev *dev_info = ring->indio_dev;
 332         u32 mask;
 333
 334         if (bit > IIO_MAX_SCAN_LENGTH)
 335                 return -EINVAL;
 336
 337         if (!ring->scan_mask)
 338                 return 0;
 339
 340         if (dev_info->available_scan_masks)
 341                 mask = iio_scan_mask_match(dev_info->available_scan_masks,
 342                                         ring->scan_mask);
 343         else
 344                 mask = ring->scan_mask;
 345
 346         if (!mask)
 347                 return -EINVAL;
 348
 349         return !!(mask & (1 << bit));
 350 };
 351
 352 /**
 353  * iio_scan_mask_set() - set particular bit in the scan mask
 354  * @ring: the ring buffer whose scan mask we are interested in
 355  * @bit: the bit to be set.
 356  **/
 357 static inline int iio_scan_mask_set(struct iio_ring_buffer *ring, int bit)
 358 {
 359         struct iio_dev *dev_info = ring->indio_dev;
 360         u32 mask;
 361         u32 trialmask = ring->scan_mask | (1 << bit);
 362
 363         if (bit > IIO_MAX_SCAN_LENGTH)
 364                 return -EINVAL;
 365         if (dev_info->available_scan_masks) {
 366                 mask = iio_scan_mask_match(dev_info->available_scan_masks,
 367                                         trialmask);
 368                 if (!mask)
 369                         return -EINVAL;
 370         }
 371         ring->scan_mask = trialmask;
 372         ring->scan_count++;
 373
 374         return 0;
 375 };
 376
 377 /**
 378  * iio_scan_mask_clear() - clear a particular element from the scan mask
 379  * @ring: the ring buffer whose scan mask we are interested in
 380  * @bit: the bit to clear
 381  **/
 382 static inline int iio_scan_mask_clear(struct iio_ring_buffer *ring, int bit)
 383 {
 384         if (bit > IIO_MAX_SCAN_LENGTH)
 385                 return -EINVAL;
 386         ring->scan_mask &= ~(1 << bit);
 387         ring->scan_count--;
 388         return 0;
 389 };
 390
 391 /**
 392  * iio_scan_mask_count_to_right() - how many scan elements occur before here
 393  * @ring: the ring buffer whose scan mask we interested in
 394  * @bit: which number scan element is this
 395  **/
 396 static inline int iio_scan_mask_count_to_right(struct iio_ring_buffer *ring,
 397                                                 int bit)
 398 {
 399         int count = 0;
 400         int mask = (1 << bit);
 401         if (bit > IIO_MAX_SCAN_LENGTH)
 402                 return -EINVAL;
 403         while (mask) {
 404                 mask >>= 1;
 405                 if (mask & ring->scan_mask)
 406                         count++;
 407         }
 408
 409         return count;
 410 }
 411
 412 /**
 413  * iio_put_ring_buffer() - notify done with buffer
 414  * @ring: the buffer we are done with.
 415  **/
 416 static inline void iio_put_ring_buffer(struct iio_ring_buffer *ring)
 417 {
 418         put_device(&ring->dev);
 419 };
 420
 421 #define to_iio_ring_buffer(d)                   \
 422         container_of(d, struct iio_ring_buffer, dev)
 423 #define access_dev_to_iio_ring_buffer(d)                        \
 424         container_of(d, struct iio_ring_buffer, access_dev)
 425
 426 /**
 427  * iio_ring_buffer_register() - register the buffer with IIO core
 428  * @ring: the buffer to be registered
 429  * @id: the id of the buffer (typically 0)
 430  **/
 431 int iio_ring_buffer_register(struct iio_ring_buffer *ring, int id);
 432
 433 /**
 434  * iio_ring_buffer_unregister() - unregister the buffer from IIO core
 435  * @ring: the buffer to be unregistered
 436  **/
 437 void iio_ring_buffer_unregister(struct iio_ring_buffer *ring);
 438
 439 /**
 440  * iio_read_ring_length() - attr func to get number of datums in the buffer
 441  **/
 442 ssize_t iio_read_ring_length(struct device *dev,
 443                              struct device_attribute *attr,
 444                              char *buf);
 445 /**
 446  * iio_write_ring_length() - attr func to set number of datums in the buffer
 447  **/
 448 ssize_t iio_write_ring_length(struct device *dev,
 449                               struct device_attribute *attr,
 450                               const char *buf,
 451                               size_t len);
 452 /**
 453  * iio_read_ring_bytes_per_datum() - attr for number of bytes in whole datum
 454  **/
 455 ssize_t iio_read_ring_bytes_per_datum(struct device *dev,
 456                           struct device_attribute *attr,
 457                           char *buf);
 458 /**
 459  * iio_store_ring_enable() - attr to turn the buffer on
 460  **/
 461 ssize_t iio_store_ring_enable(struct device *dev,
 462                               struct device_attribute *attr,
 463                               const char *buf,
 464                               size_t len);
 465 /**
 466  * iio_show_ring_enable() - attr to see if the buffer is on
 467  **/
 468 ssize_t iio_show_ring_enable(struct device *dev,
 469                              struct device_attribute *attr,
 470                              char *buf);
 471 #define IIO_RING_LENGTH_ATTR DEVICE_ATTR(length, S_IRUGO | S_IWUSR,     \
 472                                          iio_read_ring_length,          \
 473                                          iio_write_ring_length)
 474 #define IIO_RING_BYTES_PER_DATUM_ATTR DEVICE_ATTR(bytes_per_datum, S_IRUGO | S_IWUSR,   \
 475                                       iio_read_ring_bytes_per_datum, NULL)
 476 #define IIO_RING_ENABLE_ATTR DEVICE_ATTR(enable, S_IRUGO | S_IWUSR, \
 477                                          iio_show_ring_enable,          \
 478                                          iio_store_ring_enable)
 479 #else /* CONFIG_IIO_RING_BUFFER */
 480 static inline int iio_ring_buffer_register(struct iio_ring_buffer *ring, int id)
 481 {
 482         return 0;
 483 };
 484 static inline void iio_ring_buffer_unregister(struct iio_ring_buffer *ring)
 485 {};
 486
 487 #endif /* CONFIG_IIO_RING_BUFFER */
 488
 489 #endif /* _IIO_RING_GENERIC_H_ */