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_first_n:       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_first_n)(struct iio_buffer *buffer,
  49                             size_t n,
  50                             char __user *buf);
  51         size_t (*data_available)(struct iio_buffer *buffer);
  52
  53         int (*request_update)(struct iio_buffer *buffer);
  54
  55         int (*set_bytes_per_datum)(struct iio_buffer *buffer, size_t bpd);
  56         int (*set_length)(struct iio_buffer *buffer, int length);
  57
  58         int (*enable)(struct iio_buffer *buffer, struct iio_dev *indio_dev);
  59         int (*disable)(struct iio_buffer *buffer, struct iio_dev *indio_dev);
  60
  61         void (*release)(struct iio_buffer *buffer);
  62
  63         unsigned int modes;
  64         unsigned int flags;
  65 };
  66
  67 /**
  68  * struct iio_buffer - general buffer structure
  69  *
  70  * Note that the internals of this structure should only be of interest to
  71  * those writing new buffer implementations.
  72  */
  73 struct iio_buffer {
  74         /** @length: Number of datums in buffer. */
  75         int length;
  76
  77         /**  @bytes_per_datum: Size of individual datum including timestamp. */
  78         int bytes_per_datum;
  79
  80         /**
  81          * @access: Buffer access functions associated with the
  82          * implementation.
  83          */
  84         const struct iio_buffer_access_funcs *access;
  85
  86         /** @scan_mask: Bitmask used in masking scan mode elements. */
  87         long *scan_mask;
  88
  89         /** @demux_list: List of operations required to demux the scan. */
  90         struct list_head demux_list;
  91
  92         /** @pollq: Wait queue to allow for polling on the buffer. */
  93         wait_queue_head_t pollq;
  94
  95         /** @watermark: Number of datums to wait for poll/read. */
  96         unsigned int watermark;
  97
  98         /* private: */
  99         /*
 100          * @scan_el_attrs: Control of scan elements if that scan mode
 101          * control method is used.
 102          */
 103         struct attribute_group *scan_el_attrs;
 104
 105         /* @scan_timestamp: Does the scan mode include a timestamp. */
 106         bool scan_timestamp;
 107
 108         /* @scan_el_dev_attr_list: List of scan element related attributes. */
 109         struct list_head scan_el_dev_attr_list;
 110
 111         /* @buffer_group: Attributes of the buffer group. */
 112         struct attribute_group buffer_group;
 113
 114         /*
 115          * @scan_el_group: Attribute group for those attributes not
 116          * created from the iio_chan_info array.
 117          */
 118         struct attribute_group scan_el_group;
 119
 120         /* @stufftoread: Flag to indicate new data. */
 121         bool stufftoread;
 122
 123         /* @attrs: Standard attributes of the buffer. */
 124         const struct attribute **attrs;
 125
 126         /* @demux_bounce: Buffer for doing gather from incoming scan. */
 127         void *demux_bounce;
 128
 129         /* @buffer_list: Entry in the devices list of current buffers. */
 130         struct list_head buffer_list;
 131
 132         /* @ref: Reference count of the buffer. */
 133         struct kref ref;
 134 };
 135
 136 /**
 137  * iio_update_buffers() - add or remove buffer from active list
 138  * @indio_dev:          device to add buffer to
 139  * @insert_buffer:      buffer to insert
 140  * @remove_buffer:      buffer_to_remove
 141  *
 142  * Note this will tear down the all buffering and build it up again
 143  */
 144 int iio_update_buffers(struct iio_dev *indio_dev,
 145                        struct iio_buffer *insert_buffer,
 146                        struct iio_buffer *remove_buffer);
 147
 148 /**
 149  * iio_buffer_init() - Initialize the buffer structure
 150  * @buffer:             buffer to be initialized
 151  **/
 152 void iio_buffer_init(struct iio_buffer *buffer);
 153
 154 struct iio_buffer *iio_buffer_get(struct iio_buffer *buffer);
 155 void iio_buffer_put(struct iio_buffer *buffer);
 156
 157 #else /* CONFIG_IIO_BUFFER */
 158
 159 static inline void iio_buffer_get(struct iio_buffer *buffer) {}
 160 static inline void iio_buffer_put(struct iio_buffer *buffer) {}
 161
 162 #endif /* CONFIG_IIO_BUFFER */
 163 #endif /* _IIO_BUFFER_GENERIC_IMPL_H_ */