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
iio_buffer_get(struct iio_buffer * buffer)148 static inline void iio_buffer_get(struct iio_buffer *buffer) {}
iio_buffer_put(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_ */
153