linux/iio/buffer_impl.h

0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 #ifndef _IIO_BUFFER_GENERIC_IMPL_H_
0003 #define _IIO_BUFFER_GENERIC_IMPL_H_
0004 #include <linux/sysfs.h>
0005 #include <linux/kref.h>
0006
0007 #ifdef CONFIG_IIO_BUFFER
0008
0009 #include <uapi/linux/iio/buffer.h>
0010 #include <linux/iio/buffer.h>
0011
0012 struct iio_dev;
0013 struct iio_buffer;
0014
0015 /**
0016  * INDIO_BUFFER_FLAG_FIXED_WATERMARK - Watermark level of the buffer can not be
0017  *   configured. It has a fixed value which will be buffer specific.
0018  */
0019 #define INDIO_BUFFER_FLAG_FIXED_WATERMARK BIT(0)
0020
0021 /**
0022  * struct iio_buffer_access_funcs - access functions for buffers.
0023  * @store_to:       actually store stuff to the buffer
0024  * @read:       try to get a specified number of bytes (must exist)
0025  * @data_available: indicates how much data is available for reading from
0026  *          the buffer.
0027  * @remove_from:    remove scan from buffer. Drivers should calls this to
0028  *          remove a scan from a buffer.
0029  * @write:      try to write a number of bytes
0030  * @space_available:    returns the amount of bytes available in a buffer
0031  * @request_update: if a parameter change has been marked, update underlying
0032  *          storage.
0033  * @set_bytes_per_datum:set number of bytes per datum
0034  * @set_length:     set number of datums in buffer
0035  * @enable:             called if the buffer is attached to a device and the
0036  *                      device starts sampling. Calls are balanced with
0037  *                      @disable.
0038  * @disable:            called if the buffer is attached to a device and the
0039  *                      device stops sampling. Calles are balanced with @enable.
0040  * @release:        called when the last reference to the buffer is dropped,
0041  *          should free all resources allocated by the buffer.
0042  * @modes:      Supported operating modes by this buffer type
0043  * @flags:      A bitmask combination of INDIO_BUFFER_FLAG_*
0044  *
0045  * The purpose of this structure is to make the buffer element
0046  * modular as event for a given driver, different usecases may require
0047  * different buffer designs (space efficiency vs speed for example).
0048  *
0049  * It is worth noting that a given buffer implementation may only support a
0050  * small proportion of these functions.  The core code 'should' cope fine with
0051  * any of them not existing.
0052  **/
0053 struct iio_buffer_access_funcs {
0054     int (*store_to)(struct iio_buffer *buffer, const void *data);
0055     int (*read)(struct iio_buffer *buffer, size_t n, char __user *buf);
0056     size_t (*data_available)(struct iio_buffer *buffer);
0057     int (*remove_from)(struct iio_buffer *buffer, void *data);
0058     int (*write)(struct iio_buffer *buffer, size_t n, const char __user *buf);
0059     size_t (*space_available)(struct iio_buffer *buffer);
0060
0061     int (*request_update)(struct iio_buffer *buffer);
0062
0063     int (*set_bytes_per_datum)(struct iio_buffer *buffer, size_t bpd);
0064     int (*set_length)(struct iio_buffer *buffer, unsigned int length);
0065
0066     int (*enable)(struct iio_buffer *buffer, struct iio_dev *indio_dev);
0067     int (*disable)(struct iio_buffer *buffer, struct iio_dev *indio_dev);
0068
0069     void (*release)(struct iio_buffer *buffer);
0070
0071     unsigned int modes;
0072     unsigned int flags;
0073 };
0074
0075 /**
0076  * struct iio_buffer - general buffer structure
0077  *
0078  * Note that the internals of this structure should only be of interest to
0079  * those writing new buffer implementations.
0080  */
0081 struct iio_buffer {
0082     /** @length: Number of datums in buffer. */
0083     unsigned int length;
0084
0085     /** @flags: File ops flags including busy flag. */
0086     unsigned long flags;
0087
0088     /**  @bytes_per_datum: Size of individual datum including timestamp. */
0089     size_t bytes_per_datum;
0090
0091     /* @direction: Direction of the data stream (in/out). */
0092     enum iio_buffer_direction direction;
0093
0094     /**
0095      * @access: Buffer access functions associated with the
0096      * implementation.
0097      */
0098     const struct iio_buffer_access_funcs *access;
0099
0100     /** @scan_mask: Bitmask used in masking scan mode elements. */
0101     long *scan_mask;
0102
0103     /** @demux_list: List of operations required to demux the scan. */
0104     struct list_head demux_list;
0105
0106     /** @pollq: Wait queue to allow for polling on the buffer. */
0107     wait_queue_head_t pollq;
0108
0109     /** @watermark: Number of datums to wait for poll/read. */
0110     unsigned int watermark;
0111
0112     /* private: */
0113     /* @scan_timestamp: Does the scan mode include a timestamp. */
0114     bool scan_timestamp;
0115
0116     /* @buffer_attr_list: List of buffer attributes. */
0117     struct list_head buffer_attr_list;
0118
0119     /*
0120      * @buffer_group: Attributes of the new buffer group.
0121      * Includes scan elements attributes.
0122      */
0123     struct attribute_group buffer_group;
0124
0125     /* @attrs: Standard attributes of the buffer. */
0126     const struct attribute **attrs;
0127
0128     /* @demux_bounce: Buffer for doing gather from incoming scan. */
0129     void *demux_bounce;
0130
0131     /* @attached_entry: Entry in the devices list of buffers attached by the driver. */
0132     struct list_head attached_entry;
0133
0134     /* @buffer_list: Entry in the devices list of current buffers. */
0135     struct list_head buffer_list;
0136
0137     /* @ref: Reference count of the buffer. */
0138     struct kref ref;
0139 };
0140
0141 /**
0142  * iio_update_buffers() - add or remove buffer from active list
0143  * @indio_dev:      device to add buffer to
0144  * @insert_buffer:  buffer to insert
0145  * @remove_buffer:  buffer_to_remove
0146  *
0147  * Note this will tear down the all buffering and build it up again
0148  */
0149 int iio_update_buffers(struct iio_dev *indio_dev,
0150                struct iio_buffer *insert_buffer,
0151                struct iio_buffer *remove_buffer);
0152
0153 /**
0154  * iio_buffer_init() - Initialize the buffer structure
0155  * @buffer:     buffer to be initialized
0156  **/
0157 void iio_buffer_init(struct iio_buffer *buffer);
0158
0159 struct iio_buffer *iio_buffer_get(struct iio_buffer *buffer);
0160 void iio_buffer_put(struct iio_buffer *buffer);
0161
0162 #else /* CONFIG_IIO_BUFFER */
0163
0164 static inline void iio_buffer_get(struct iio_buffer *buffer) {}
0165 static inline void iio_buffer_put(struct iio_buffer *buffer) {}
0166
0167 #endif /* CONFIG_IIO_BUFFER */
0168 #endif /* _IIO_BUFFER_GENERIC_IMPL_H_ */