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