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