include/linux/iio/buffer_impl.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 #ifndef _IIO_BUFFER_GENERIC_IMPL_H_
   3 #define _IIO_BUFFER_GENERIC_IMPL_H_
   4 #include <linux/sysfs.h>
   5 #include <linux/kref.h>
   6
   7 #ifdef CONFIG_IIO_BUFFER
   8
   9 #include <uapi/linux/iio/buffer.h>
  10 #include <linux/iio/buffer.h>
  11
  12 struct iio_dev;
  13 struct iio_buffer;
  14
  15 /**
  16  * INDIO_BUFFER_FLAG_FIXED_WATERMARK - Watermark level of the buffer can not be
  17  *   configured. It has a fixed value which will be buffer specific.
  18  */
  19 #define INDIO_BUFFER_FLAG_FIXED_WATERMARK BIT(0)
  20
  21 /**
  22  * struct iio_buffer_access_funcs - access functions for buffers.
  23  * @store_to:           actually store stuff to the buffer
  24  * @read:               try to get a specified number of bytes (must exist)
  25  * @data_available:     indicates how much data is available for reading from
  26  *                      the buffer.
  27  * @remove_from:        remove scan from buffer. Drivers should calls this to
  28  *                      remove a scan from a buffer.
  29  * @write:              try to write a number of bytes
  30  * @space_available:    returns the amount of bytes available in a buffer
  31  * @request_update:     if a parameter change has been marked, update underlying
  32  *                      storage.
  33  * @set_bytes_per_datum:set number of bytes per datum
  34  * @set_length:         set number of datums in buffer
  35  * @enable:             called if the buffer is attached to a device and the
  36  *                      device starts sampling. Calls are balanced with
  37  *                      @disable.
  38  * @disable:            called if the buffer is attached to a device and the
  39  *                      device stops sampling. Calles are balanced with @enable.
  40  * @release:            called when the last reference to the buffer is dropped,
  41  *                      should free all resources allocated by the buffer.
  42  * @modes:              Supported operating modes by this buffer type
  43  * @flags:              A bitmask combination of INDIO_BUFFER_FLAG_*
  44  *
  45  * The purpose of this structure is to make the buffer element
  46  * modular as event for a given driver, different usecases may require
  47  * different buffer designs (space efficiency vs speed for example).
  48  *
  49  * It is worth noting that a given buffer implementation may only support a
  50  * small proportion of these functions.  The core code 'should' cope fine with
  51  * any of them not existing.
  52  **/
  53 struct iio_buffer_access_funcs {
  54         int (*store_to)(struct iio_buffer *buffer, const void *data);
  55         int (*read)(struct iio_buffer *buffer, size_t n, char __user *buf);
  56         size_t (*data_available)(struct iio_buffer *buffer);
  57         int (*remove_from)(struct iio_buffer *buffer, void *data);
  58         int (*write)(struct iio_buffer *buffer, size_t n, const char __user *buf);
  59         size_t (*space_available)(struct iio_buffer *buffer);
  60
  61         int (*request_update)(struct iio_buffer *buffer);
  62
  63         int (*set_bytes_per_datum)(struct iio_buffer *buffer, size_t bpd);
  64         int (*set_length)(struct iio_buffer *buffer, unsigned int length);
  65
  66         int (*enable)(struct iio_buffer *buffer, struct iio_dev *indio_dev);
  67         int (*disable)(struct iio_buffer *buffer, struct iio_dev *indio_dev);
  68
  69         void (*release)(struct iio_buffer *buffer);
  70
  71         unsigned int modes;
  72         unsigned int flags;
  73 };
  74
  75 /**
  76  * struct iio_buffer - general buffer structure
  77  *
  78  * Note that the internals of this structure should only be of interest to
  79  * those writing new buffer implementations.
  80  */
  81 struct iio_buffer {
  82         /** @length: Number of datums in buffer. */
  83         unsigned int length;
  84
  85         /** @flags: File ops flags including busy flag. */
  86         unsigned long flags;
  87
  88         /**  @bytes_per_datum: Size of individual datum including timestamp. */
  89         size_t bytes_per_datum;
  90
  91         /* @direction: Direction of the data stream (in/out). */
  92         enum iio_buffer_direction direction;
  93
  94         /**
  95          * @access: Buffer access functions associated with the
  96          * implementation.
  97          */
  98         const struct iio_buffer_access_funcs *access;
  99
 100         /** @scan_mask: Bitmask used in masking scan mode elements. */
 101         long *scan_mask;
 102
 103         /** @demux_list: List of operations required to demux the scan. */
 104         struct list_head demux_list;
 105
 106         /** @pollq: Wait queue to allow for polling on the buffer. */
 107         wait_queue_head_t pollq;
 108
 109         /** @watermark: Number of datums to wait for poll/read. */
 110         unsigned int watermark;
 111
 112         /* private: */
 113         /* @scan_timestamp: Does the scan mode include a timestamp. */
 114         bool scan_timestamp;
 115
 116         /* @buffer_attr_list: List of buffer attributes. */
 117         struct list_head buffer_attr_list;
 118
 119         /*
 120          * @buffer_group: Attributes of the new buffer group.
 121          * Includes scan elements attributes.
 122          */
 123         struct attribute_group buffer_group;
 124
 125         /* @attrs: Standard attributes of the buffer. */
 126         const struct iio_dev_attr **attrs;
 127
 128         /* @demux_bounce: Buffer for doing gather from incoming scan. */
 129         void *demux_bounce;
 130
 131         /* @attached_entry: Entry in the devices list of buffers attached by the driver. */
 132         struct list_head attached_entry;
 133
 134         /* @buffer_list: Entry in the devices list of current buffers. */
 135         struct list_head buffer_list;
 136
 137         /* @ref: Reference count of the buffer. */
 138         struct kref ref;
 139 };
 140
 141 /**
 142  * iio_update_buffers() - add or remove buffer from active list
 143  * @indio_dev:          device to add buffer to
 144  * @insert_buffer:      buffer to insert
 145  * @remove_buffer:      buffer_to_remove
 146  *
 147  * Note this will tear down the all buffering and build it up again
 148  */
 149 int iio_update_buffers(struct iio_dev *indio_dev,
 150                        struct iio_buffer *insert_buffer,
 151                        struct iio_buffer *remove_buffer);
 152
 153 /**
 154  * iio_buffer_init() - Initialize the buffer structure
 155  * @buffer:             buffer to be initialized
 156  **/
 157 void iio_buffer_init(struct iio_buffer *buffer);
 158
 159 struct iio_buffer *iio_buffer_get(struct iio_buffer *buffer);
 160 void iio_buffer_put(struct iio_buffer *buffer);
 161
 162 #else /* CONFIG_IIO_BUFFER */
 163
 164 static inline void iio_buffer_get(struct iio_buffer *buffer) {}
 165 static inline void iio_buffer_put(struct iio_buffer *buffer) {}
 166
 167 #endif /* CONFIG_IIO_BUFFER */
 168 #endif /* _IIO_BUFFER_GENERIC_IMPL_H_ */