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