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  * struct iio_ring_access_funcs - access functions for ring buffers.
  20  * @mark_in_use:        reference counting, typically to prevent module removal
  21  * @unmark_in_use:      reduce reference count when no longer using ring buffer
  22  * @store_to:           actually store stuff to the ring buffer
  23  * @read_last:          get the last element stored
  24  * @read_first_n:       try to get a specified number of elements (must exist)
  25  * @mark_param_change:  notify ring that some relevant parameter has changed
  26  *                      Often this means the underlying storage may need to
  27  *                      change.
  28  * @request_update:     if a parameter change has been marked, update underlying
  29  *                      storage.
  30  * @get_bytes_per_datum:get current bytes per datum
  31  * @set_bytes_per_datum:set number of bytes per datum
  32  * @get_length:         get number of datums in ring
  33  * @set_length:         set number of datums in ring
  34  * @is_enabled:         query if ring is currently being used
  35  * @enable:             enable the ring
  36  *
  37  * The purpose of this structure is to make the ring buffer element
  38  * modular as event for a given driver, different usecases may require
  39  * different ring designs (space efficiency vs speed for example).
  40  *
  41  * It is worth noting that a given ring implementation may only support a small
  42  * proportion of these functions.  The core code 'should' cope fine with any of
  43  * them not existing.
  44  **/
  45 struct iio_ring_access_funcs {
  46         void (*mark_in_use)(struct iio_ring_buffer *ring);
  47         void (*unmark_in_use)(struct iio_ring_buffer *ring);
  48
  49         int (*store_to)(struct iio_ring_buffer *ring, u8 *data, s64 timestamp);
  50         int (*read_last)(struct iio_ring_buffer *ring, u8 *data);
  51         int (*read_first_n)(struct iio_ring_buffer *ring,
  52                             size_t n,
  53                             char __user *buf);
  54
  55         int (*mark_param_change)(struct iio_ring_buffer *ring);
  56         int (*request_update)(struct iio_ring_buffer *ring);
  57
  58         int (*get_bytes_per_datum)(struct iio_ring_buffer *ring);
  59         int (*set_bytes_per_datum)(struct iio_ring_buffer *ring, size_t bpd);
  60         int (*get_length)(struct iio_ring_buffer *ring);
  61         int (*set_length)(struct iio_ring_buffer *ring, int length);
  62
  63         int (*is_enabled)(struct iio_ring_buffer *ring);
  64         int (*enable)(struct iio_ring_buffer *ring);
  65 };
  66
  67 struct iio_ring_setup_ops {
  68         int                             (*preenable)(struct iio_dev *);
  69         int                             (*postenable)(struct iio_dev *);
  70         int                             (*predisable)(struct iio_dev *);
  71         int                             (*postdisable)(struct iio_dev *);
  72 };
  73
  74 /**
  75  * struct iio_ring_buffer - general ring buffer structure
  76  * @dev:                ring buffer device struct
  77  * @indio_dev:          industrial I/O device structure
  78  * @owner:              module that owns the ring buffer (for ref counting)
  79  * @length:             [DEVICE] number of datums in ring
  80  * @bytes_per_datum:    [DEVICE] size of individual datum including timestamp
  81  * @bpe:                [DEVICE] size of individual channel value
  82  * @scan_el_attrs:      [DRIVER] control of scan elements if that scan mode
  83  *                      control method is used
  84  * @scan_count: [INTERN] the number of elements in the current scan mode
  85  * @scan_mask:          [INTERN] bitmask used in masking scan mode elements
  86  * @scan_timestamp:     [INTERN] does the scan mode include a timestamp
  87  * @access_handler:     [INTERN] chrdev access handling
  88  * @access:             [DRIVER] ring access functions associated with the
  89  *                      implementation.
  90  * @preenable:          [DRIVER] function to run prior to marking ring enabled
  91  * @postenable:         [DRIVER] function to run after marking ring enabled
  92  * @predisable:         [DRIVER] function to run prior to marking ring disabled
  93  * @postdisable:        [DRIVER] function to run after marking ring disabled
  94  **/
  95 struct iio_ring_buffer {
  96         struct device                           dev;
  97         struct iio_dev                          *indio_dev;
  98         struct module                           *owner;
  99         int                                     length;
 100         int                                     bytes_per_datum;
 101         int                                     bpe;
 102         struct attribute_group                  *scan_el_attrs;
 103         int                                     scan_count;
 104         unsigned long                           scan_mask;
 105         bool                                    scan_timestamp;
 106         struct iio_handler                      access_handler;
 107         const struct iio_ring_access_funcs      *access;
 108         const struct iio_ring_setup_ops         *setup_ops;
 109         struct list_head                        scan_el_dev_attr_list;
 110
 111         wait_queue_head_t                       pollq;
 112         bool                                    stufftoread;
 113 };
 114
 115 /**
 116  * iio_ring_buffer_init() - Initialize the buffer structure
 117  * @ring: buffer to be initialized
 118  * @dev_info: the iio device the buffer is assocated with
 119  **/
 120 void iio_ring_buffer_init(struct iio_ring_buffer *ring,
 121                           struct iio_dev *dev_info);
 122
 123 /**
 124  * __iio_update_ring_buffer() - update common elements of ring buffers
 125  * @ring:               ring buffer that is the event source
 126  * @bytes_per_datum:    size of individual datum including timestamp
 127  * @length:             number of datums in ring
 128  **/
 129 static inline void __iio_update_ring_buffer(struct iio_ring_buffer *ring,
 130                                             int bytes_per_datum, int length)
 131 {
 132         ring->bytes_per_datum = bytes_per_datum;
 133         ring->length = length;
 134 }
 135
 136 /*
 137  * These are mainly provided to allow for a change of implementation if a device
 138  * has a large number of scan elements
 139  */
 140 #define IIO_MAX_SCAN_LENGTH 31
 141
 142 /* note 0 used as error indicator as it doesn't make sense. */
 143 static inline u32 iio_scan_mask_match(u32 *av_masks, u32 mask)
 144 {
 145         while (*av_masks) {
 146                 if (!(~*av_masks & mask))
 147                         return *av_masks;
 148                 av_masks++;
 149         }
 150         return 0;
 151 }
 152
 153 static inline int iio_scan_mask_query(struct iio_ring_buffer *ring, int bit)
 154 {
 155         struct iio_dev *dev_info = ring->indio_dev;
 156         u32 mask;
 157
 158         if (bit > IIO_MAX_SCAN_LENGTH)
 159                 return -EINVAL;
 160
 161         if (!ring->scan_mask)
 162                 return 0;
 163
 164         if (dev_info->available_scan_masks)
 165                 mask = iio_scan_mask_match(dev_info->available_scan_masks,
 166                                         ring->scan_mask);
 167         else
 168                 mask = ring->scan_mask;
 169
 170         if (!mask)
 171                 return -EINVAL;
 172
 173         return !!(mask & (1 << bit));
 174 };
 175
 176 /**
 177  * iio_scan_mask_set() - set particular bit in the scan mask
 178  * @ring: the ring buffer whose scan mask we are interested in
 179  * @bit: the bit to be set.
 180  **/
 181 static inline int iio_scan_mask_set(struct iio_ring_buffer *ring, int bit)
 182 {
 183         struct iio_dev *dev_info = ring->indio_dev;
 184         u32 mask;
 185         u32 trialmask = ring->scan_mask | (1 << bit);
 186
 187         if (bit > IIO_MAX_SCAN_LENGTH)
 188                 return -EINVAL;
 189         if (dev_info->available_scan_masks) {
 190                 mask = iio_scan_mask_match(dev_info->available_scan_masks,
 191                                         trialmask);
 192                 if (!mask)
 193                         return -EINVAL;
 194         }
 195         ring->scan_mask = trialmask;
 196         ring->scan_count++;
 197
 198         return 0;
 199 };
 200
 201 /**
 202  * iio_put_ring_buffer() - notify done with buffer
 203  * @ring: the buffer we are done with.
 204  **/
 205 static inline void iio_put_ring_buffer(struct iio_ring_buffer *ring)
 206 {
 207         put_device(&ring->dev);
 208 };
 209
 210 #define to_iio_ring_buffer(d)                           \
 211         container_of(d, struct iio_ring_buffer, dev)
 212
 213 /**
 214  * iio_ring_buffer_register_ex() - register the buffer with IIO core
 215  * @ring: the buffer to be registered
 216  * @id: the id of the buffer (typically 0)
 217  **/
 218 int iio_ring_buffer_register_ex(struct iio_ring_buffer *ring, int id,
 219                                 const struct iio_chan_spec *channels,
 220                                 int num_channels);
 221
 222 void iio_ring_access_release(struct device *dev);
 223
 224 /**
 225  * iio_ring_buffer_unregister() - unregister the buffer from IIO core
 226  * @ring: the buffer to be unregistered
 227  **/
 228 void iio_ring_buffer_unregister(struct iio_ring_buffer *ring);
 229
 230 /**
 231  * iio_read_ring_length() - attr func to get number of datums in the buffer
 232  **/
 233 ssize_t iio_read_ring_length(struct device *dev,
 234                              struct device_attribute *attr,
 235                              char *buf);
 236 /**
 237  * iio_write_ring_length() - attr func to set number of datums in the buffer
 238  **/
 239 ssize_t iio_write_ring_length(struct device *dev,
 240                               struct device_attribute *attr,
 241                               const char *buf,
 242                               size_t len);
 243 /**
 244  * iio_read_ring_bytes_per_datum() - attr for number of bytes in whole datum
 245  **/
 246 ssize_t iio_read_ring_bytes_per_datum(struct device *dev,
 247                           struct device_attribute *attr,
 248                           char *buf);
 249 /**
 250  * iio_store_ring_enable() - attr to turn the buffer on
 251  **/
 252 ssize_t iio_store_ring_enable(struct device *dev,
 253                               struct device_attribute *attr,
 254                               const char *buf,
 255                               size_t len);
 256 /**
 257  * iio_show_ring_enable() - attr to see if the buffer is on
 258  **/
 259 ssize_t iio_show_ring_enable(struct device *dev,
 260                              struct device_attribute *attr,
 261                              char *buf);
 262 #define IIO_RING_LENGTH_ATTR DEVICE_ATTR(length, S_IRUGO | S_IWUSR,     \
 263                                          iio_read_ring_length,          \
 264                                          iio_write_ring_length)
 265 #define IIO_RING_BYTES_PER_DATUM_ATTR DEVICE_ATTR(bytes_per_datum, S_IRUGO | S_IWUSR,   \
 266                                       iio_read_ring_bytes_per_datum, NULL)
 267 #define IIO_RING_ENABLE_ATTR DEVICE_ATTR(enable, S_IRUGO | S_IWUSR, \
 268                                          iio_show_ring_enable,          \
 269                                          iio_store_ring_enable)
 270
 271 int iio_sw_ring_preenable(struct iio_dev *indio_dev);
 272
 273 #else /* CONFIG_IIO_RING_BUFFER */
 274
 275 static inline int iio_ring_buffer_register_ex(struct iio_ring_buffer *ring,
 276                                               int id,
 277                                               struct iio_chan_spec *channels,
 278                                               int num_channels)
 279 {
 280         return 0;
 281 }
 282
 283 static inline void iio_ring_buffer_unregister(struct iio_ring_buffer *ring)
 284 {};
 285
 286 #endif /* CONFIG_IIO_RING_BUFFER */
 287
 288 #endif /* _IIO_RING_GENERIC_H_ */