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 | ||
14 | struct iio_handler; | |
15 | struct iio_ring_buffer; | |
16 | struct iio_dev; | |
17 | ||
18 | /** | |
19 | * iio_push_ring_event() - ring buffer specific push to event chrdev | |
20 | * @ring_buf: ring buffer that is the event source | |
21 | * @event_code: event indentification code | |
22 | * @timestamp: time of event | |
23 | **/ | |
24 | int iio_push_ring_event(struct iio_ring_buffer *ring_buf, | |
25 | int event_code, | |
26 | s64 timestamp); | |
27 | /** | |
4c572605 RD |
28 | * iio_push_or_escallate_ring_event() - escalate or add as appropriate |
29 | * @ring_buf: ring buffer that is the event source | |
30 | * @event_code: event indentification code | |
31 | * @timestamp: time of event | |
7026ea4b | 32 | * |
4c572605 | 33 | * Typical usecase is to escalate a 50% ring full to 75% full if noone has yet |
7026ea4b JC |
34 | * read the first event. Clearly the 50% full is no longer of interest in |
35 | * typical use case. | |
36 | **/ | |
37 | int iio_push_or_escallate_ring_event(struct iio_ring_buffer *ring_buf, | |
38 | int event_code, | |
39 | s64 timestamp); | |
40 | ||
41 | /** | |
42 | * struct iio_ring_access_funcs - access functions for ring buffers. | |
7026ea4b JC |
43 | * @mark_in_use: reference counting, typically to prevent module removal |
44 | * @unmark_in_use: reduce reference count when no longer using ring buffer | |
45 | * @store_to: actually store stuff to the ring buffer | |
46 | * @read_last: get the last element stored | |
47 | * @rip_lots: try to get a specified number of elements (must exist) | |
48 | * @mark_param_change: notify ring that some relevant parameter has changed | |
49 | * Often this means the underlying storage may need to | |
50 | * change. | |
51 | * @request_update: if a parameter change has been marked, update underlying | |
52 | * storage. | |
53 | * @get_bpd: get current bytes per datum | |
54 | * @set_bpd: set number of bytes per datum | |
55 | * @get_length: get number of datums in ring | |
56 | * @set_length: set number of datums in ring | |
57 | * @is_enabled: query if ring is currently being used | |
58 | * @enable: enable the ring | |
59 | * | |
60 | * The purpose of this structure is to make the ring buffer element | |
61 | * modular as event for a given driver, different usecases may require | |
4c572605 | 62 | * different ring designs (space efficiency vs speed for example). |
7026ea4b JC |
63 | * |
64 | * It is worth noting that a given ring implementation may only support a small | |
65 | * proportion of these functions. The core code 'should' cope fine with any of | |
66 | * them not existing. | |
67 | **/ | |
68 | struct iio_ring_access_funcs { | |
69 | void (*mark_in_use)(struct iio_ring_buffer *ring); | |
70 | void (*unmark_in_use)(struct iio_ring_buffer *ring); | |
71 | ||
72 | int (*store_to)(struct iio_ring_buffer *ring, u8 *data, s64 timestamp); | |
73 | int (*read_last)(struct iio_ring_buffer *ring, u8 *data); | |
74 | int (*rip_lots)(struct iio_ring_buffer *ring, | |
75 | size_t count, | |
76 | u8 **data, | |
77 | int *dead_offset); | |
78 | ||
79 | int (*mark_param_change)(struct iio_ring_buffer *ring); | |
80 | int (*request_update)(struct iio_ring_buffer *ring); | |
81 | ||
82 | int (*get_bpd)(struct iio_ring_buffer *ring); | |
83 | int (*set_bpd)(struct iio_ring_buffer *ring, size_t bpd); | |
84 | int (*get_length)(struct iio_ring_buffer *ring); | |
85 | int (*set_length)(struct iio_ring_buffer *ring, int length); | |
86 | ||
87 | int (*is_enabled)(struct iio_ring_buffer *ring); | |
88 | int (*enable)(struct iio_ring_buffer *ring); | |
89 | }; | |
90 | ||
91 | /** | |
92 | * struct iio_ring_buffer - general ring buffer structure | |
4c572605 RD |
93 | * @dev: ring buffer device struct |
94 | * @access_dev: system device struct for the chrdev | |
95 | * @indio_dev: industrial I/O device structure | |
96 | * @owner: module that owns the ring buffer (for ref counting) | |
97 | * @id: unique id number | |
98 | * @access_id: device id number | |
99 | * @length: [DEVICE] number of datums in ring | |
100 | * @bpd: [DEVICE] size of individual datum including timestamp | |
101 | * @loopcount: [INTERN] number of times the ring has looped | |
102 | * @access_handler: [INTERN] chrdev access handling | |
103 | * @ev_int: [INTERN] chrdev interface for the event chrdev | |
104 | * @shared_ev_pointer: [INTERN] the shared event pointer to allow escalation of | |
7026ea4b | 105 | * events |
4c572605 | 106 | * @access: [DRIVER] ring access functions associated with the |
7026ea4b | 107 | * implementation. |
4c572605 RD |
108 | * @preenable: [DRIVER] function to run prior to marking ring enabled |
109 | * @postenable: [DRIVER] function to run after marking ring enabled | |
110 | * @predisable: [DRIVER] function to run prior to marking ring disabled | |
111 | * @postdisable: [DRIVER] function to run after marking ring disabled | |
7026ea4b JC |
112 | **/ |
113 | struct iio_ring_buffer { | |
114 | struct device dev; | |
115 | struct device access_dev; | |
116 | struct iio_dev *indio_dev; | |
117 | struct module *owner; | |
118 | int id; | |
119 | int access_id; | |
120 | int length; | |
121 | int bpd; | |
122 | int loopcount; | |
123 | struct iio_handler access_handler; | |
124 | struct iio_event_interface ev_int; | |
125 | struct iio_shared_ev_pointer shared_ev_pointer; | |
126 | struct iio_ring_access_funcs access; | |
127 | int (*preenable)(struct iio_dev *); | |
128 | int (*postenable)(struct iio_dev *); | |
129 | int (*predisable)(struct iio_dev *); | |
130 | int (*postdisable)(struct iio_dev *); | |
131 | ||
132 | }; | |
133 | void iio_ring_buffer_init(struct iio_ring_buffer *ring, | |
134 | struct iio_dev *dev_info); | |
135 | ||
136 | /** | |
4c572605 RD |
137 | * __iio_init_ring_buffer() - initialize common elements of ring buffers |
138 | * @ring: ring buffer that is the event source | |
139 | * @bytes_per_datum: size of individual datum including timestamp | |
140 | * @length: number of datums in ring | |
7026ea4b JC |
141 | **/ |
142 | static inline void __iio_init_ring_buffer(struct iio_ring_buffer *ring, | |
143 | int bytes_per_datum, int length) | |
144 | { | |
145 | ring->bpd = bytes_per_datum; | |
146 | ring->length = length; | |
147 | ring->loopcount = 0; | |
148 | ring->shared_ev_pointer.ev_p = 0; | |
c852ab66 | 149 | spin_lock_init(&ring->shared_ev_pointer.lock); |
7026ea4b JC |
150 | } |
151 | ||
152 | /** | |
153 | * struct iio_scan_el - an individual element of a scan | |
154 | * @dev_attr: control attribute (if directly controllable) | |
155 | * @number: unique identifier of element (used for bit mask) | |
156 | * @bit_count: number of bits in scan element | |
157 | * @label: useful data for the scan el (often reg address) | |
158 | * @set_state: for some devices datardy signals are generated | |
159 | * for any enabled lines. This allows unwanted lines | |
160 | * to be disabled and hence not get in the way. | |
161 | **/ | |
162 | struct iio_scan_el { | |
163 | struct device_attribute dev_attr; | |
164 | unsigned int number; | |
165 | int bit_count; | |
166 | unsigned int label; | |
167 | ||
168 | int (*set_state)(struct iio_scan_el *scanel, | |
169 | struct iio_dev *dev_info, | |
170 | bool state); | |
171 | }; | |
172 | ||
173 | #define to_iio_scan_el(_dev_attr) \ | |
174 | container_of(_dev_attr, struct iio_scan_el, dev_attr); | |
175 | ||
176 | /** | |
4c572605 RD |
177 | * iio_scan_el_store() - sysfs scan element selection interface |
178 | * @dev: the target device | |
179 | * @attr: the device attribute that is being processed | |
180 | * @buf: input from userspace | |
181 | * @len: length of input | |
7026ea4b JC |
182 | * |
183 | * A generic function used to enable various scan elements. In some | |
184 | * devices explicit read commands for each channel mean this is merely | |
185 | * a software switch. In others this must actively disable the channel. | |
186 | * Complexities occur when this interacts with data ready type triggers | |
187 | * which may not reset unless every channel that is enabled is explicitly | |
188 | * read. | |
189 | **/ | |
190 | ssize_t iio_scan_el_store(struct device *dev, struct device_attribute *attr, | |
191 | const char *buf, size_t len); | |
192 | /** | |
193 | * iio_scal_el_show() - sysfs interface to query whether a scan element is | |
4c572605 RD |
194 | * is enabled or not |
195 | * @dev: the target device | |
196 | * @attr: the device attribute that is being processed | |
197 | * @buf: output buffer | |
7026ea4b JC |
198 | **/ |
199 | ssize_t iio_scan_el_show(struct device *dev, struct device_attribute *attr, | |
200 | char *buf); | |
201 | /** | |
4c572605 | 202 | * IIO_SCAN_EL - declare and initialize a scan element without control func |
7026ea4b JC |
203 | * @_name: identifying name. Resulting struct is iio_scan_el_##_name, |
204 | * sysfs element, scan_en_##_name. | |
205 | * @_number: unique id number for the scan element. | |
206 | * @_bits: number of bits in the scan element result (used in mixed bit | |
207 | * length devices). | |
208 | * @_label: indentification variable used by drivers. Often a reg address. | |
209 | **/ | |
210 | #define IIO_SCAN_EL(_name, _number, _bits, _label) \ | |
211 | struct iio_scan_el iio_scan_el_##_name = { \ | |
212 | .dev_attr = __ATTR(scan_en_##_name, \ | |
213 | S_IRUGO | S_IWUSR, \ | |
214 | iio_scan_el_show, \ | |
215 | iio_scan_el_store), \ | |
216 | .mask = (1 << _number), \ | |
217 | .bit_count = _bits, \ | |
218 | .label = _label, \ | |
219 | } | |
220 | ||
221 | ssize_t iio_scan_el_ts_store(struct device *dev, struct device_attribute *attr, | |
222 | const char *buf, size_t len); | |
223 | ||
224 | ssize_t iio_scan_el_ts_show(struct device *dev, struct device_attribute *attr, | |
225 | char *buf); | |
226 | /** | |
4c572605 | 227 | * IIO_SCAN_EL_C - declare and initialize a scan element with a control func |
7026ea4b | 228 | * |
4c572605 RD |
229 | * @_name: identifying name. Resulting struct is iio_scan_el_##_name, |
230 | * sysfs element, scan_en_##_name. | |
231 | * @_number: unique id number for the scan element. | |
232 | * @_bits: number of bits in the scan element result (used in mixed bit | |
233 | * length devices). | |
234 | * @_label: indentification variable used by drivers. Often a reg address. | |
7026ea4b JC |
235 | * @_controlfunc: function used to notify hardware of whether state changes |
236 | **/ | |
237 | #define IIO_SCAN_EL_C(_name, _number, _bits, _label, _controlfunc) \ | |
238 | struct iio_scan_el iio_scan_el_##_name = { \ | |
239 | .dev_attr = __ATTR(scan_en_##_name, \ | |
240 | S_IRUGO | S_IWUSR, \ | |
241 | iio_scan_el_show, \ | |
242 | iio_scan_el_store), \ | |
243 | .number = _number, \ | |
244 | .bit_count = _bits, \ | |
245 | .label = _label, \ | |
246 | .set_state = _controlfunc, \ | |
247 | } | |
248 | /** | |
4c572605 | 249 | * IIO_SCAN_EL_TIMESTAMP - declare a special scan element for timestamps |
7026ea4b JC |
250 | * |
251 | * Odd one out. Handled slightly differently from other scan elements. | |
252 | **/ | |
253 | #define IIO_SCAN_EL_TIMESTAMP \ | |
254 | struct iio_scan_el iio_scan_el_timestamp = { \ | |
255 | .dev_attr = __ATTR(scan_en_timestamp, \ | |
256 | S_IRUGO | S_IWUSR, \ | |
257 | iio_scan_el_ts_show, \ | |
258 | iio_scan_el_ts_store), \ | |
259 | } | |
260 | ||
261 | static inline void iio_put_ring_buffer(struct iio_ring_buffer *ring) | |
262 | { | |
263 | put_device(&ring->dev); | |
264 | }; | |
265 | ||
266 | #define to_iio_ring_buffer(d) \ | |
267 | container_of(d, struct iio_ring_buffer, dev) | |
268 | #define access_dev_to_iio_ring_buffer(d) \ | |
269 | container_of(d, struct iio_ring_buffer, access_dev) | |
270 | int iio_ring_buffer_register(struct iio_ring_buffer *ring); | |
271 | void iio_ring_buffer_unregister(struct iio_ring_buffer *ring); | |
272 | ||
273 | ssize_t iio_read_ring_length(struct device *dev, | |
274 | struct device_attribute *attr, | |
275 | char *buf); | |
276 | ssize_t iio_write_ring_length(struct device *dev, | |
277 | struct device_attribute *attr, | |
278 | const char *buf, | |
279 | size_t len); | |
280 | ssize_t iio_read_ring_bps(struct device *dev, | |
281 | struct device_attribute *attr, | |
282 | char *buf); | |
283 | ssize_t iio_store_ring_enable(struct device *dev, | |
284 | struct device_attribute *attr, | |
285 | const char *buf, | |
286 | size_t len); | |
287 | ssize_t iio_show_ring_enable(struct device *dev, | |
288 | struct device_attribute *attr, | |
289 | char *buf); | |
290 | #define IIO_RING_LENGTH_ATTR DEVICE_ATTR(length, S_IRUGO | S_IWUSR, \ | |
291 | iio_read_ring_length, \ | |
292 | iio_write_ring_length) | |
293 | #define IIO_RING_BPS_ATTR DEVICE_ATTR(bps, S_IRUGO | S_IWUSR, \ | |
294 | iio_read_ring_bps, NULL) | |
295 | #define IIO_RING_ENABLE_ATTR DEVICE_ATTR(ring_enable, S_IRUGO | S_IWUSR, \ | |
296 | iio_show_ring_enable, \ | |
297 | iio_store_ring_enable) | |
298 | ||
299 | #endif /* _IIO_RING_GENERIC_H_ */ |