Commit | Line | Data |
---|---|---|
7026ea4b JC |
1 | /* The industrial I/O core - generic ring buffer interfaces. |
2 | * | |
3 | * Copyright (c) 2008 Jonathan Cameron | |
4 | * | |
5 | * This program is free software; you can redistribute it and/or modify it | |
6 | * under the terms of the GNU General Public License version 2 as published by | |
7 | * the Free Software Foundation. | |
8 | */ | |
9 | ||
10 | #ifndef _IIO_RING_GENERIC_H_ | |
11 | #define _IIO_RING_GENERIC_H_ | |
12 | #include "iio.h" | |
13 | ||
2662051e JC |
14 | #ifdef CONFIG_IIO_RING_BUFFER |
15 | ||
7026ea4b | 16 | struct iio_ring_buffer; |
7026ea4b | 17 | |
7026ea4b JC |
18 | /** |
19 | * struct iio_ring_access_funcs - access functions for ring buffers. | |
7026ea4b JC |
20 | * @mark_in_use: reference counting, typically to prevent module removal |
21 | * @unmark_in_use: reduce reference count when no longer using ring buffer | |
22 | * @store_to: actually store stuff to the ring buffer | |
23 | * @read_last: get the last element stored | |
b4281733 | 24 | * @read_first_n: try to get a specified number of elements (must exist) |
7026ea4b JC |
25 | * @mark_param_change: notify ring that some relevant parameter has changed |
26 | * Often this means the underlying storage may need to | |
27 | * change. | |
28 | * @request_update: if a parameter change has been marked, update underlying | |
29 | * storage. | |
c3e5d410 JC |
30 | * @get_bytes_per_datum:get current bytes per datum |
31 | * @set_bytes_per_datum:set number of bytes per datum | |
7026ea4b JC |
32 | * @get_length: get number of datums in ring |
33 | * @set_length: set number of datums in ring | |
34 | * @is_enabled: query if ring is currently being used | |
35 | * @enable: enable the ring | |
36 | * | |
37 | * The purpose of this structure is to make the ring buffer element | |
38 | * modular as event for a given driver, different usecases may require | |
4c572605 | 39 | * different ring designs (space efficiency vs speed for example). |
7026ea4b JC |
40 | * |
41 | * It is worth noting that a given ring implementation may only support a small | |
42 | * proportion of these functions. The core code 'should' cope fine with any of | |
43 | * them not existing. | |
44 | **/ | |
45 | struct iio_ring_access_funcs { | |
46 | void (*mark_in_use)(struct iio_ring_buffer *ring); | |
47 | void (*unmark_in_use)(struct iio_ring_buffer *ring); | |
48 | ||
49 | int (*store_to)(struct iio_ring_buffer *ring, u8 *data, s64 timestamp); | |
50 | int (*read_last)(struct iio_ring_buffer *ring, u8 *data); | |
b4281733 JC |
51 | int (*read_first_n)(struct iio_ring_buffer *ring, |
52 | size_t n, | |
b26a2188 | 53 | char __user *buf); |
7026ea4b JC |
54 | |
55 | int (*mark_param_change)(struct iio_ring_buffer *ring); | |
56 | int (*request_update)(struct iio_ring_buffer *ring); | |
57 | ||
ffcab07a MS |
58 | int (*get_bytes_per_datum)(struct iio_ring_buffer *ring); |
59 | int (*set_bytes_per_datum)(struct iio_ring_buffer *ring, size_t bpd); | |
7026ea4b JC |
60 | int (*get_length)(struct iio_ring_buffer *ring); |
61 | int (*set_length)(struct iio_ring_buffer *ring, int length); | |
62 | ||
63 | int (*is_enabled)(struct iio_ring_buffer *ring); | |
64 | int (*enable)(struct iio_ring_buffer *ring); | |
65 | }; | |
66 | ||
5565a450 JC |
67 | struct iio_ring_setup_ops { |
68 | int (*preenable)(struct iio_dev *); | |
69 | int (*postenable)(struct iio_dev *); | |
70 | int (*predisable)(struct iio_dev *); | |
71 | int (*postdisable)(struct iio_dev *); | |
72 | }; | |
73 | ||
7026ea4b JC |
74 | /** |
75 | * struct iio_ring_buffer - general ring buffer structure | |
4c572605 | 76 | * @dev: ring buffer device struct |
4c572605 RD |
77 | * @indio_dev: industrial I/O device structure |
78 | * @owner: module that owns the ring buffer (for ref counting) | |
79 | * @id: unique id number | |
4c572605 | 80 | * @length: [DEVICE] number of datums in ring |
c3e5d410 | 81 | * @bytes_per_datum: [DEVICE] size of individual datum including timestamp |
ad577f8d | 82 | * @bpe: [DEVICE] size of individual channel value |
4c572605 | 83 | * @loopcount: [INTERN] number of times the ring has looped |
bf32963c MS |
84 | * @scan_el_attrs: [DRIVER] control of scan elements if that scan mode |
85 | * control method is used | |
86 | * @scan_count: [INTERN] the number of elements in the current scan mode | |
87 | * @scan_mask: [INTERN] bitmask used in masking scan mode elements | |
88 | * @scan_timestamp: [INTERN] does the scan mode include a timestamp | |
4c572605 | 89 | * @access_handler: [INTERN] chrdev access handling |
4c572605 | 90 | * @access: [DRIVER] ring access functions associated with the |
7026ea4b | 91 | * implementation. |
4c572605 RD |
92 | * @preenable: [DRIVER] function to run prior to marking ring enabled |
93 | * @postenable: [DRIVER] function to run after marking ring enabled | |
94 | * @predisable: [DRIVER] function to run prior to marking ring disabled | |
95 | * @postdisable: [DRIVER] function to run after marking ring disabled | |
7026ea4b JC |
96 | **/ |
97 | struct iio_ring_buffer { | |
98 | struct device dev; | |
7026ea4b JC |
99 | struct iio_dev *indio_dev; |
100 | struct module *owner; | |
101 | int id; | |
7026ea4b | 102 | int length; |
ffcab07a | 103 | int bytes_per_datum; |
ad577f8d | 104 | int bpe; |
7026ea4b | 105 | int loopcount; |
bf32963c MS |
106 | struct attribute_group *scan_el_attrs; |
107 | int scan_count; | |
108 | u32 scan_mask; | |
109 | bool scan_timestamp; | |
7026ea4b | 110 | struct iio_handler access_handler; |
5565a450 JC |
111 | const struct iio_ring_access_funcs *access; |
112 | const struct iio_ring_setup_ops *setup_ops; | |
1d892719 | 113 | struct list_head scan_el_dev_attr_list; |
a7348347 JC |
114 | |
115 | wait_queue_head_t pollq; | |
116 | bool stufftoread; | |
7026ea4b | 117 | }; |
c3e5d410 JC |
118 | |
119 | /** | |
120 | * iio_ring_buffer_init() - Initialize the buffer structure | |
121 | * @ring: buffer to be initialized | |
122 | * @dev_info: the iio device the buffer is assocated with | |
123 | **/ | |
7026ea4b JC |
124 | void iio_ring_buffer_init(struct iio_ring_buffer *ring, |
125 | struct iio_dev *dev_info); | |
126 | ||
127 | /** | |
6f2dfb31 | 128 | * __iio_update_ring_buffer() - update common elements of ring buffers |
4c572605 RD |
129 | * @ring: ring buffer that is the event source |
130 | * @bytes_per_datum: size of individual datum including timestamp | |
131 | * @length: number of datums in ring | |
7026ea4b | 132 | **/ |
6f2dfb31 JC |
133 | static inline void __iio_update_ring_buffer(struct iio_ring_buffer *ring, |
134 | int bytes_per_datum, int length) | |
7026ea4b | 135 | { |
ffcab07a | 136 | ring->bytes_per_datum = bytes_per_datum; |
7026ea4b JC |
137 | ring->length = length; |
138 | ring->loopcount = 0; | |
7026ea4b JC |
139 | } |
140 | ||
7026ea4b | 141 | /** |
4c572605 RD |
142 | * iio_scan_el_store() - sysfs scan element selection interface |
143 | * @dev: the target device | |
144 | * @attr: the device attribute that is being processed | |
145 | * @buf: input from userspace | |
146 | * @len: length of input | |
7026ea4b JC |
147 | * |
148 | * A generic function used to enable various scan elements. In some | |
149 | * devices explicit read commands for each channel mean this is merely | |
150 | * a software switch. In others this must actively disable the channel. | |
151 | * Complexities occur when this interacts with data ready type triggers | |
152 | * which may not reset unless every channel that is enabled is explicitly | |
153 | * read. | |
154 | **/ | |
155 | ssize_t iio_scan_el_store(struct device *dev, struct device_attribute *attr, | |
156 | const char *buf, size_t len); | |
157 | /** | |
c3e5d410 | 158 | * iio_scan_el_show() - sysfs interface to query whether a scan element |
4c572605 RD |
159 | * is enabled or not |
160 | * @dev: the target device | |
161 | * @attr: the device attribute that is being processed | |
162 | * @buf: output buffer | |
7026ea4b JC |
163 | **/ |
164 | ssize_t iio_scan_el_show(struct device *dev, struct device_attribute *attr, | |
165 | char *buf); | |
7026ea4b | 166 | |
c3e5d410 JC |
167 | /** |
168 | * iio_scan_el_ts_store() - sysfs interface to set whether a timestamp is included | |
169 | * in the scan. | |
170 | **/ | |
7026ea4b JC |
171 | ssize_t iio_scan_el_ts_store(struct device *dev, struct device_attribute *attr, |
172 | const char *buf, size_t len); | |
c3e5d410 JC |
173 | /** |
174 | * iio_scan_el_ts_show() - sysfs interface to query if a timestamp is included | |
175 | * in the scan. | |
176 | **/ | |
7026ea4b JC |
177 | ssize_t iio_scan_el_ts_show(struct device *dev, struct device_attribute *attr, |
178 | char *buf); | |
e968d095 | 179 | |
bf32963c MS |
180 | /* |
181 | * These are mainly provided to allow for a change of implementation if a device | |
182 | * has a large number of scan elements | |
183 | */ | |
184 | #define IIO_MAX_SCAN_LENGTH 31 | |
185 | ||
186 | /* note 0 used as error indicator as it doesn't make sense. */ | |
187 | static inline u32 iio_scan_mask_match(u32 *av_masks, u32 mask) | |
188 | { | |
189 | while (*av_masks) { | |
190 | if (!(~*av_masks & mask)) | |
191 | return *av_masks; | |
192 | av_masks++; | |
193 | } | |
194 | return 0; | |
195 | } | |
196 | ||
197 | static inline int iio_scan_mask_query(struct iio_ring_buffer *ring, int bit) | |
198 | { | |
199 | struct iio_dev *dev_info = ring->indio_dev; | |
200 | u32 mask; | |
201 | ||
202 | if (bit > IIO_MAX_SCAN_LENGTH) | |
203 | return -EINVAL; | |
204 | ||
205 | if (!ring->scan_mask) | |
206 | return 0; | |
207 | ||
208 | if (dev_info->available_scan_masks) | |
209 | mask = iio_scan_mask_match(dev_info->available_scan_masks, | |
210 | ring->scan_mask); | |
211 | else | |
212 | mask = ring->scan_mask; | |
213 | ||
214 | if (!mask) | |
215 | return -EINVAL; | |
216 | ||
217 | return !!(mask & (1 << bit)); | |
218 | }; | |
219 | ||
c3e5d410 JC |
220 | /** |
221 | * iio_scan_mask_set() - set particular bit in the scan mask | |
222 | * @ring: the ring buffer whose scan mask we are interested in | |
223 | * @bit: the bit to be set. | |
224 | **/ | |
bf32963c MS |
225 | static inline int iio_scan_mask_set(struct iio_ring_buffer *ring, int bit) |
226 | { | |
227 | struct iio_dev *dev_info = ring->indio_dev; | |
228 | u32 mask; | |
229 | u32 trialmask = ring->scan_mask | (1 << bit); | |
230 | ||
231 | if (bit > IIO_MAX_SCAN_LENGTH) | |
232 | return -EINVAL; | |
233 | if (dev_info->available_scan_masks) { | |
234 | mask = iio_scan_mask_match(dev_info->available_scan_masks, | |
235 | trialmask); | |
236 | if (!mask) | |
237 | return -EINVAL; | |
238 | } | |
239 | ring->scan_mask = trialmask; | |
240 | ring->scan_count++; | |
241 | ||
242 | return 0; | |
243 | }; | |
244 | ||
c3e5d410 JC |
245 | /** |
246 | * iio_scan_mask_clear() - clear a particular element from the scan mask | |
247 | * @ring: the ring buffer whose scan mask we are interested in | |
248 | * @bit: the bit to clear | |
249 | **/ | |
bf32963c MS |
250 | static inline int iio_scan_mask_clear(struct iio_ring_buffer *ring, int bit) |
251 | { | |
252 | if (bit > IIO_MAX_SCAN_LENGTH) | |
253 | return -EINVAL; | |
254 | ring->scan_mask &= ~(1 << bit); | |
255 | ring->scan_count--; | |
256 | return 0; | |
257 | }; | |
258 | ||
259 | /** | |
260 | * iio_scan_mask_count_to_right() - how many scan elements occur before here | |
c3e5d410 | 261 | * @ring: the ring buffer whose scan mask we interested in |
bf32963c MS |
262 | * @bit: which number scan element is this |
263 | **/ | |
264 | static inline int iio_scan_mask_count_to_right(struct iio_ring_buffer *ring, | |
265 | int bit) | |
266 | { | |
267 | int count = 0; | |
268 | int mask = (1 << bit); | |
269 | if (bit > IIO_MAX_SCAN_LENGTH) | |
270 | return -EINVAL; | |
271 | while (mask) { | |
272 | mask >>= 1; | |
273 | if (mask & ring->scan_mask) | |
274 | count++; | |
275 | } | |
276 | ||
277 | return count; | |
278 | } | |
279 | ||
c3e5d410 JC |
280 | /** |
281 | * iio_put_ring_buffer() - notify done with buffer | |
282 | * @ring: the buffer we are done with. | |
283 | **/ | |
7026ea4b JC |
284 | static inline void iio_put_ring_buffer(struct iio_ring_buffer *ring) |
285 | { | |
286 | put_device(&ring->dev); | |
287 | }; | |
288 | ||
289 | #define to_iio_ring_buffer(d) \ | |
290 | container_of(d, struct iio_ring_buffer, dev) | |
c3e5d410 JC |
291 | |
292 | /** | |
293 | * iio_ring_buffer_register() - register the buffer with IIO core | |
294 | * @ring: the buffer to be registered | |
295 | * @id: the id of the buffer (typically 0) | |
296 | **/ | |
758d988c | 297 | int iio_ring_buffer_register(struct iio_ring_buffer *ring, int id); |
c3e5d410 | 298 | |
1d892719 JC |
299 | /** iio_ring_buffer_register_ex() - register the buffer with IIO core |
300 | * @ring: the buffer to be registered | |
301 | * @id: the id of the buffer (typically 0) | |
302 | **/ | |
303 | int iio_ring_buffer_register_ex(struct iio_ring_buffer *ring, int id, | |
304 | const struct iio_chan_spec *channels, | |
305 | int num_channels); | |
306 | ||
3feb0797 JC |
307 | void iio_ring_access_release(struct device *dev); |
308 | ||
c3e5d410 JC |
309 | /** |
310 | * iio_ring_buffer_unregister() - unregister the buffer from IIO core | |
311 | * @ring: the buffer to be unregistered | |
312 | **/ | |
7026ea4b JC |
313 | void iio_ring_buffer_unregister(struct iio_ring_buffer *ring); |
314 | ||
c3e5d410 JC |
315 | /** |
316 | * iio_read_ring_length() - attr func to get number of datums in the buffer | |
317 | **/ | |
7026ea4b JC |
318 | ssize_t iio_read_ring_length(struct device *dev, |
319 | struct device_attribute *attr, | |
320 | char *buf); | |
c3e5d410 JC |
321 | /** |
322 | * iio_write_ring_length() - attr func to set number of datums in the buffer | |
323 | **/ | |
7026ea4b JC |
324 | ssize_t iio_write_ring_length(struct device *dev, |
325 | struct device_attribute *attr, | |
326 | const char *buf, | |
327 | size_t len); | |
c3e5d410 JC |
328 | /** |
329 | * iio_read_ring_bytes_per_datum() - attr for number of bytes in whole datum | |
330 | **/ | |
ffcab07a | 331 | ssize_t iio_read_ring_bytes_per_datum(struct device *dev, |
7026ea4b JC |
332 | struct device_attribute *attr, |
333 | char *buf); | |
c3e5d410 JC |
334 | /** |
335 | * iio_store_ring_enable() - attr to turn the buffer on | |
336 | **/ | |
7026ea4b JC |
337 | ssize_t iio_store_ring_enable(struct device *dev, |
338 | struct device_attribute *attr, | |
339 | const char *buf, | |
340 | size_t len); | |
c3e5d410 JC |
341 | /** |
342 | * iio_show_ring_enable() - attr to see if the buffer is on | |
343 | **/ | |
7026ea4b JC |
344 | ssize_t iio_show_ring_enable(struct device *dev, |
345 | struct device_attribute *attr, | |
346 | char *buf); | |
347 | #define IIO_RING_LENGTH_ATTR DEVICE_ATTR(length, S_IRUGO | S_IWUSR, \ | |
348 | iio_read_ring_length, \ | |
349 | iio_write_ring_length) | |
ffcab07a MS |
350 | #define IIO_RING_BYTES_PER_DATUM_ATTR DEVICE_ATTR(bytes_per_datum, S_IRUGO | S_IWUSR, \ |
351 | iio_read_ring_bytes_per_datum, NULL) | |
352 | #define IIO_RING_ENABLE_ATTR DEVICE_ATTR(enable, S_IRUGO | S_IWUSR, \ | |
7026ea4b JC |
353 | iio_show_ring_enable, \ |
354 | iio_store_ring_enable) | |
5565a450 JC |
355 | |
356 | int iio_sw_ring_preenable(struct iio_dev *indio_dev); | |
357 | ||
2662051e JC |
358 | #else /* CONFIG_IIO_RING_BUFFER */ |
359 | static inline int iio_ring_buffer_register(struct iio_ring_buffer *ring, int id) | |
360 | { | |
361 | return 0; | |
362 | }; | |
1d892719 JC |
363 | |
364 | static inline int iio_ring_buffer_register_ex(struct iio_ring_buffer *ring, | |
365 | int id, | |
366 | struct iio_chan_spec *channels, | |
367 | int num_channels) | |
368 | { | |
369 | return 0; | |
370 | } | |
371 | ||
2662051e JC |
372 | static inline void iio_ring_buffer_unregister(struct iio_ring_buffer *ring) |
373 | {}; | |
374 | ||
375 | #endif /* CONFIG_IIO_RING_BUFFER */ | |
7026ea4b JC |
376 | |
377 | #endif /* _IIO_RING_GENERIC_H_ */ |