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