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 | /** | |
6f2dfb31 | 137 | * __iio_update_ring_buffer() - update common elements of ring buffers |
4c572605 RD |
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 | 141 | **/ |
6f2dfb31 JC |
142 | static inline void __iio_update_ring_buffer(struct iio_ring_buffer *ring, |
143 | int bytes_per_datum, int length) | |
7026ea4b JC |
144 | { |
145 | ring->bpd = bytes_per_datum; | |
146 | ring->length = length; | |
147 | ring->loopcount = 0; | |
7026ea4b JC |
148 | } |
149 | ||
150 | /** | |
151 | * struct iio_scan_el - an individual element of a scan | |
152 | * @dev_attr: control attribute (if directly controllable) | |
153 | * @number: unique identifier of element (used for bit mask) | |
154 | * @bit_count: number of bits in scan element | |
155 | * @label: useful data for the scan el (often reg address) | |
156 | * @set_state: for some devices datardy signals are generated | |
157 | * for any enabled lines. This allows unwanted lines | |
158 | * to be disabled and hence not get in the way. | |
159 | **/ | |
160 | struct iio_scan_el { | |
161 | struct device_attribute dev_attr; | |
162 | unsigned int number; | |
163 | int bit_count; | |
164 | unsigned int label; | |
165 | ||
166 | int (*set_state)(struct iio_scan_el *scanel, | |
167 | struct iio_dev *dev_info, | |
168 | bool state); | |
169 | }; | |
170 | ||
171 | #define to_iio_scan_el(_dev_attr) \ | |
172 | container_of(_dev_attr, struct iio_scan_el, dev_attr); | |
173 | ||
174 | /** | |
4c572605 RD |
175 | * iio_scan_el_store() - sysfs scan element selection interface |
176 | * @dev: the target device | |
177 | * @attr: the device attribute that is being processed | |
178 | * @buf: input from userspace | |
179 | * @len: length of input | |
7026ea4b JC |
180 | * |
181 | * A generic function used to enable various scan elements. In some | |
182 | * devices explicit read commands for each channel mean this is merely | |
183 | * a software switch. In others this must actively disable the channel. | |
184 | * Complexities occur when this interacts with data ready type triggers | |
185 | * which may not reset unless every channel that is enabled is explicitly | |
186 | * read. | |
187 | **/ | |
188 | ssize_t iio_scan_el_store(struct device *dev, struct device_attribute *attr, | |
189 | const char *buf, size_t len); | |
190 | /** | |
191 | * iio_scal_el_show() - sysfs interface to query whether a scan element is | |
4c572605 RD |
192 | * is enabled or not |
193 | * @dev: the target device | |
194 | * @attr: the device attribute that is being processed | |
195 | * @buf: output buffer | |
7026ea4b JC |
196 | **/ |
197 | ssize_t iio_scan_el_show(struct device *dev, struct device_attribute *attr, | |
198 | char *buf); | |
7026ea4b JC |
199 | |
200 | ssize_t iio_scan_el_ts_store(struct device *dev, struct device_attribute *attr, | |
201 | const char *buf, size_t len); | |
202 | ||
203 | ssize_t iio_scan_el_ts_show(struct device *dev, struct device_attribute *attr, | |
204 | char *buf); | |
205 | /** | |
4c572605 | 206 | * IIO_SCAN_EL_C - declare and initialize a scan element with a control func |
7026ea4b | 207 | * |
4c572605 | 208 | * @_name: identifying name. Resulting struct is iio_scan_el_##_name, |
1722762c | 209 | * sysfs element, _name##_en. |
4c572605 RD |
210 | * @_number: unique id number for the scan element. |
211 | * @_bits: number of bits in the scan element result (used in mixed bit | |
212 | * length devices). | |
213 | * @_label: indentification variable used by drivers. Often a reg address. | |
7026ea4b JC |
214 | * @_controlfunc: function used to notify hardware of whether state changes |
215 | **/ | |
216 | #define IIO_SCAN_EL_C(_name, _number, _bits, _label, _controlfunc) \ | |
217 | struct iio_scan_el iio_scan_el_##_name = { \ | |
1722762c | 218 | .dev_attr = __ATTR(_number##_##_name##_en, \ |
7026ea4b JC |
219 | S_IRUGO | S_IWUSR, \ |
220 | iio_scan_el_show, \ | |
221 | iio_scan_el_store), \ | |
222 | .number = _number, \ | |
223 | .bit_count = _bits, \ | |
224 | .label = _label, \ | |
225 | .set_state = _controlfunc, \ | |
226 | } | |
1722762c JC |
227 | |
228 | #define IIO_SCAN_NAMED_EL_C(_name, _string, _number, _bits, _label, _cf) \ | |
229 | struct iio_scan_el iio_scan_el_##_name = { \ | |
230 | .dev_attr = __ATTR(_number##_##_string##_en, \ | |
231 | S_IRUGO | S_IWUSR, \ | |
232 | iio_scan_el_show, \ | |
233 | iio_scan_el_store), \ | |
234 | .number = _number, \ | |
235 | .bit_count = _bits, \ | |
236 | .label = _label, \ | |
237 | .set_state = _cf, \ | |
238 | } | |
239 | ||
7026ea4b | 240 | /** |
4c572605 | 241 | * IIO_SCAN_EL_TIMESTAMP - declare a special scan element for timestamps |
7026ea4b JC |
242 | * |
243 | * Odd one out. Handled slightly differently from other scan elements. | |
244 | **/ | |
f3fb0011 | 245 | #define IIO_SCAN_EL_TIMESTAMP(number) \ |
7026ea4b | 246 | struct iio_scan_el iio_scan_el_timestamp = { \ |
f3fb0011 | 247 | .dev_attr = __ATTR(number##_timestamp_en, \ |
7026ea4b JC |
248 | S_IRUGO | S_IWUSR, \ |
249 | iio_scan_el_ts_show, \ | |
250 | iio_scan_el_ts_store), \ | |
251 | } | |
252 | ||
253 | static inline void iio_put_ring_buffer(struct iio_ring_buffer *ring) | |
254 | { | |
255 | put_device(&ring->dev); | |
256 | }; | |
257 | ||
258 | #define to_iio_ring_buffer(d) \ | |
259 | container_of(d, struct iio_ring_buffer, dev) | |
260 | #define access_dev_to_iio_ring_buffer(d) \ | |
261 | container_of(d, struct iio_ring_buffer, access_dev) | |
758d988c | 262 | int iio_ring_buffer_register(struct iio_ring_buffer *ring, int id); |
7026ea4b JC |
263 | void iio_ring_buffer_unregister(struct iio_ring_buffer *ring); |
264 | ||
265 | ssize_t iio_read_ring_length(struct device *dev, | |
266 | struct device_attribute *attr, | |
267 | char *buf); | |
268 | ssize_t iio_write_ring_length(struct device *dev, | |
269 | struct device_attribute *attr, | |
270 | const char *buf, | |
271 | size_t len); | |
272 | ssize_t iio_read_ring_bps(struct device *dev, | |
273 | struct device_attribute *attr, | |
274 | char *buf); | |
275 | ssize_t iio_store_ring_enable(struct device *dev, | |
276 | struct device_attribute *attr, | |
277 | const char *buf, | |
278 | size_t len); | |
279 | ssize_t iio_show_ring_enable(struct device *dev, | |
280 | struct device_attribute *attr, | |
281 | char *buf); | |
282 | #define IIO_RING_LENGTH_ATTR DEVICE_ATTR(length, S_IRUGO | S_IWUSR, \ | |
283 | iio_read_ring_length, \ | |
284 | iio_write_ring_length) | |
285 | #define IIO_RING_BPS_ATTR DEVICE_ATTR(bps, S_IRUGO | S_IWUSR, \ | |
286 | iio_read_ring_bps, NULL) | |
287 | #define IIO_RING_ENABLE_ATTR DEVICE_ATTR(ring_enable, S_IRUGO | S_IWUSR, \ | |
288 | iio_show_ring_enable, \ | |
289 | iio_store_ring_enable) | |
290 | ||
291 | #endif /* _IIO_RING_GENERIC_H_ */ |