History

counter: Introduce the Generic Counter interface

This patch introduces the Generic Counter interface for supporting counter devices. In the context of the Generic Counter interface, a counter is defined as a device that reports one or more "counts" based on the state changes of one or more "signals" as evaluated by a defined "count function." Driver callbacks should be provided to communicate with the device: to read and write various Signals and Counts, and to set and get the "action mode" and "count function" for various Synapses and Counts respectively. To support a counter device, a driver must first allocate the available Counter Signals via counter_signal structures. These Signals should be stored as an array and set to the signals array member of an allocated counter_device structure before the Counter is registered to the system. Counter Counts may be allocated via counter_count structures, and respective Counter Signal associations (Synapses) made via counter_synapse structures. Associated counter_synapse structures are stored as an array and set to the the synapses array member of the respective counter_count structure. These counter_count structures are set to the counts array member of an allocated counter_device structure before the Counter is registered to the system. A counter device is registered to the system by passing the respective initialized counter_device structure to the counter_register function; similarly, the counter_unregister function unregisters the respective Counter. The devm_counter_register and devm_counter_unregister functions serve as device memory-managed versions of the counter_register and counter_unregister functions respectively.

William Breathitt Gray committed 7 years ago

Commit 0040a391 parent 7df95298 files · +2148 −0Browse files

Showing the changes to include/linux (2 of 8 files). Show all

Unified · Split

2 files
  1. include/linux/counter.h +510 −0
  2. include/linux/counter_enum.h +45 −0
include/linux/counter.h+510−0
@@ -0,0 +1,510 @@
1+/* SPDX-License-Identifier: GPL-2.0 */
2+/*
3+ * Counter interface
4+ * Copyright (C) 2018 William Breathitt Gray
5+ */
6+#ifndef _COUNTER_H_
7+#define _COUNTER_H_
8+
9+#include <linux/counter_enum.h>
10+#include <linux/device.h>
11+#include <linux/types.h>
12+
13+enum counter_count_direction {
14+ COUNTER_COUNT_DIRECTION_FORWARD = 0,
15+ COUNTER_COUNT_DIRECTION_BACKWARD
16+};
17+extern const char *const counter_count_direction_str[2];
18+
19+enum counter_count_mode {
20+ COUNTER_COUNT_MODE_NORMAL = 0,
21+ COUNTER_COUNT_MODE_RANGE_LIMIT,
22+ COUNTER_COUNT_MODE_NON_RECYCLE,
23+ COUNTER_COUNT_MODE_MODULO_N
24+};
25+extern const char *const counter_count_mode_str[4];
26+
27+struct counter_device;
28+struct counter_signal;
29+
30+/**
31+ * struct counter_signal_ext - Counter Signal extensions
32+ * @name: attribute name
33+ * @read: read callback for this attribute; may be NULL
34+ * @write: write callback for this attribute; may be NULL
35+ * @priv: data private to the driver
36+ */
37+struct counter_signal_ext {
38+ const char *name;
39+ ssize_t (*read)(struct counter_device *counter,
40+ struct counter_signal *signal, void *priv, char *buf);
41+ ssize_t (*write)(struct counter_device *counter,
42+ struct counter_signal *signal, void *priv,
43+ const char *buf, size_t len);
44+ void *priv;
45+};
46+
47+/**
48+ * struct counter_signal - Counter Signal node
49+ * @id: unique ID used to identify signal
50+ * @name: device-specific Signal name; ideally, this should match the name
51+ * as it appears in the datasheet documentation
52+ * @ext: optional array of Counter Signal extensions
53+ * @num_ext: number of Counter Signal extensions specified in @ext
54+ * @priv: optional private data supplied by driver
55+ */
56+struct counter_signal {
57+ int id;
58+ const char *name;
59+
60+ const struct counter_signal_ext *ext;
61+ size_t num_ext;
62+
63+ void *priv;
64+};
65+
66+/**
67+ * struct counter_signal_enum_ext - Signal enum extension attribute
68+ * @items: Array of strings
69+ * @num_items: Number of items specified in @items
70+ * @set: Set callback function; may be NULL
71+ * @get: Get callback function; may be NULL
72+ *
73+ * The counter_signal_enum_ext structure can be used to implement enum style
74+ * Signal extension attributes. Enum style attributes are those which have a set
75+ * of strings that map to unsigned integer values. The Generic Counter Signal
76+ * enum extension helper code takes care of mapping between value and string, as
77+ * well as generating a "_available" file which contains a list of all available
78+ * items. The get callback is used to query the currently active item; the index
79+ * of the item within the respective items array is returned via the 'item'
80+ * parameter. The set callback is called when the attribute is updated; the
81+ * 'item' parameter contains the index of the newly activated item within the
82+ * respective items array.
83+ */
84+struct counter_signal_enum_ext {
85+ const char * const *items;
86+ size_t num_items;
87+ int (*get)(struct counter_device *counter,
88+ struct counter_signal *signal, size_t *item);
89+ int (*set)(struct counter_device *counter,
90+ struct counter_signal *signal, size_t item);
91+};
92+
93+/**
94+ * COUNTER_SIGNAL_ENUM() - Initialize Signal enum extension
95+ * @_name: Attribute name
96+ * @_e: Pointer to a counter_signal_enum_ext structure
97+ *
98+ * This should usually be used together with COUNTER_SIGNAL_ENUM_AVAILABLE()
99+ */
100+#define COUNTER_SIGNAL_ENUM(_name, _e) \
101+{ \
102+ .name = (_name), \
103+ .read = counter_signal_enum_read, \
104+ .write = counter_signal_enum_write, \
105+ .priv = (_e) \
106+}
107+
108+/**
109+ * COUNTER_SIGNAL_ENUM_AVAILABLE() - Initialize Signal enum available extension
110+ * @_name: Attribute name ("_available" will be appended to the name)
111+ * @_e: Pointer to a counter_signal_enum_ext structure
112+ *
113+ * Creates a read only attribute that lists all the available enum items in a
114+ * newline separated list. This should usually be used together with
115+ * COUNTER_SIGNAL_ENUM()
116+ */
117+#define COUNTER_SIGNAL_ENUM_AVAILABLE(_name, _e) \
118+{ \
119+ .name = (_name "_available"), \
120+ .read = counter_signal_enum_available_read, \
121+ .priv = (_e) \
122+}
123+
124+enum counter_synapse_action {
125+ COUNTER_SYNAPSE_ACTION_NONE = 0,
126+ COUNTER_SYNAPSE_ACTION_RISING_EDGE,
127+ COUNTER_SYNAPSE_ACTION_FALLING_EDGE,
128+ COUNTER_SYNAPSE_ACTION_BOTH_EDGES
129+};
130+
131+/**
132+ * struct counter_synapse - Counter Synapse node
133+ * @action: index of current action mode
134+ * @actions_list: array of available action modes
135+ * @num_actions: number of action modes specified in @actions_list
136+ * @signal: pointer to associated signal
137+ */
138+struct counter_synapse {
139+ size_t action;
140+ const enum counter_synapse_action *actions_list;
141+ size_t num_actions;
142+
143+ struct counter_signal *signal;
144+};
145+
146+struct counter_count;
147+
148+/**
149+ * struct counter_count_ext - Counter Count extension
150+ * @name: attribute name
151+ * @read: read callback for this attribute; may be NULL
152+ * @write: write callback for this attribute; may be NULL
153+ * @priv: data private to the driver
154+ */
155+struct counter_count_ext {
156+ const char *name;
157+ ssize_t (*read)(struct counter_device *counter,
158+ struct counter_count *count, void *priv, char *buf);
159+ ssize_t (*write)(struct counter_device *counter,
160+ struct counter_count *count, void *priv,
161+ const char *buf, size_t len);
162+ void *priv;
163+};
164+
165+enum counter_count_function {
166+ COUNTER_COUNT_FUNCTION_INCREASE = 0,
167+ COUNTER_COUNT_FUNCTION_DECREASE,
168+ COUNTER_COUNT_FUNCTION_PULSE_DIRECTION,
169+ COUNTER_COUNT_FUNCTION_QUADRATURE_X1_A,
170+ COUNTER_COUNT_FUNCTION_QUADRATURE_X1_B,
171+ COUNTER_COUNT_FUNCTION_QUADRATURE_X2_A,
172+ COUNTER_COUNT_FUNCTION_QUADRATURE_X2_B,
173+ COUNTER_COUNT_FUNCTION_QUADRATURE_X4
174+};
175+
176+/**
177+ * struct counter_count - Counter Count node
178+ * @id: unique ID used to identify Count
179+ * @name: device-specific Count name; ideally, this should match
180+ * the name as it appears in the datasheet documentation
181+ * @function: index of current function mode
182+ * @functions_list: array available function modes
183+ * @num_functions: number of function modes specified in @functions_list
184+ * @synapses: array of synapses for initialization
185+ * @num_synapses: number of synapses specified in @synapses
186+ * @ext: optional array of Counter Count extensions
187+ * @num_ext: number of Counter Count extensions specified in @ext
188+ * @priv: optional private data supplied by driver
189+ */
190+struct counter_count {
191+ int id;
192+ const char *name;
193+
194+ size_t function;
195+ const enum counter_count_function *functions_list;
196+ size_t num_functions;
197+
198+ struct counter_synapse *synapses;
199+ size_t num_synapses;
200+
201+ const struct counter_count_ext *ext;
202+ size_t num_ext;
203+
204+ void *priv;
205+};
206+
207+/**
208+ * struct counter_count_enum_ext - Count enum extension attribute
209+ * @items: Array of strings
210+ * @num_items: Number of items specified in @items
211+ * @set: Set callback function; may be NULL
212+ * @get: Get callback function; may be NULL
213+ *
214+ * The counter_count_enum_ext structure can be used to implement enum style
215+ * Count extension attributes. Enum style attributes are those which have a set
216+ * of strings that map to unsigned integer values. The Generic Counter Count
217+ * enum extension helper code takes care of mapping between value and string, as
218+ * well as generating a "_available" file which contains a list of all available
219+ * items. The get callback is used to query the currently active item; the index
220+ * of the item within the respective items array is returned via the 'item'
221+ * parameter. The set callback is called when the attribute is updated; the
222+ * 'item' parameter contains the index of the newly activated item within the
223+ * respective items array.
224+ */
225+struct counter_count_enum_ext {
226+ const char * const *items;
227+ size_t num_items;
228+ int (*get)(struct counter_device *counter, struct counter_count *count,
229+ size_t *item);
230+ int (*set)(struct counter_device *counter, struct counter_count *count,
231+ size_t item);
232+};
233+
234+/**
235+ * COUNTER_COUNT_ENUM() - Initialize Count enum extension
236+ * @_name: Attribute name
237+ * @_e: Pointer to a counter_count_enum_ext structure
238+ *
239+ * This should usually be used together with COUNTER_COUNT_ENUM_AVAILABLE()
240+ */
241+#define COUNTER_COUNT_ENUM(_name, _e) \
242+{ \
243+ .name = (_name), \
244+ .read = counter_count_enum_read, \
245+ .write = counter_count_enum_write, \
246+ .priv = (_e) \
247+}
248+
249+/**
250+ * COUNTER_COUNT_ENUM_AVAILABLE() - Initialize Count enum available extension
251+ * @_name: Attribute name ("_available" will be appended to the name)
252+ * @_e: Pointer to a counter_count_enum_ext structure
253+ *
254+ * Creates a read only attribute that lists all the available enum items in a
255+ * newline separated list. This should usually be used together with
256+ * COUNTER_COUNT_ENUM()
257+ */
258+#define COUNTER_COUNT_ENUM_AVAILABLE(_name, _e) \
259+{ \
260+ .name = (_name "_available"), \
261+ .read = counter_count_enum_available_read, \
262+ .priv = (_e) \
263+}
264+
265+/**
266+ * struct counter_device_attr_group - internal container for attribute group
267+ * @attr_group: Counter sysfs attributes group
268+ * @attr_list: list to keep track of created Counter sysfs attributes
269+ * @num_attr: number of Counter sysfs attributes
270+ */
271+struct counter_device_attr_group {
272+ struct attribute_group attr_group;
273+ struct list_head attr_list;
274+ size_t num_attr;
275+};
276+
277+/**
278+ * struct counter_device_state - internal state container for a Counter device
279+ * @id: unique ID used to identify the Counter
280+ * @dev: internal device structure
281+ * @groups_list: attribute groups list (for Signals, Counts, and ext)
282+ * @num_groups: number of attribute groups containers
283+ * @groups: Counter sysfs attribute groups (to populate @dev.groups)
284+ */
285+struct counter_device_state {
286+ int id;
287+ struct device dev;
288+ struct counter_device_attr_group *groups_list;
289+ size_t num_groups;
290+ const struct attribute_group **groups;
291+};
292+
293+/**
294+ * struct counter_signal_read_value - Opaque Signal read value
295+ * @buf: string representation of Signal read value
296+ * @len: length of string in @buf
297+ */
298+struct counter_signal_read_value {
299+ char *buf;
300+ size_t len;
301+};
302+
303+/**
304+ * struct counter_count_read_value - Opaque Count read value
305+ * @buf: string representation of Count read value
306+ * @len: length of string in @buf
307+ */
308+struct counter_count_read_value {
309+ char *buf;
310+ size_t len;
311+};
312+
313+/**
314+ * struct counter_count_write_value - Opaque Count write value
315+ * @buf: string representation of Count write value
316+ */
317+struct counter_count_write_value {
318+ const char *buf;
319+};
320+
321+/**
322+ * struct counter_ops - Callbacks from driver
323+ * @signal_read: optional read callback for Signal attribute. The read
324+ * value of the respective Signal should be passed back via
325+ * the val parameter. val points to an opaque type which
326+ * should be set only by calling the
327+ * counter_signal_read_value_set function from within the
328+ * signal_read callback.
329+ * @count_read: optional read callback for Count attribute. The read
330+ * value of the respective Count should be passed back via
331+ * the val parameter. val points to an opaque type which
332+ * should be set only by calling the
333+ * counter_count_read_value_set function from within the
334+ * count_read callback.
335+ * @count_write: optional write callback for Count attribute. The write
336+ * value for the respective Count is passed in via the val
337+ * parameter. val points to an opaque type which should be
338+ * accessed only by calling the
339+ * counter_count_write_value_get function.
340+ * @function_get: function to get the current count function mode. Returns
341+ * 0 on success and negative error code on error. The index
342+ * of the respective Count's returned function mode should
343+ * be passed back via the function parameter.
344+ * @function_set: function to set the count function mode. function is the
345+ * index of the requested function mode from the respective
346+ * Count's functions_list array.
347+ * @action_get: function to get the current action mode. Returns 0 on
348+ * success and negative error code on error. The index of
349+ * the respective Signal's returned action mode should be
350+ * passed back via the action parameter.
351+ * @action_set: function to set the action mode. action is the index of
352+ * the requested action mode from the respective Synapse's
353+ * actions_list array.
354+ */
355+struct counter_ops {
356+ int (*signal_read)(struct counter_device *counter,
357+ struct counter_signal *signal,
358+ struct counter_signal_read_value *val);
359+ int (*count_read)(struct counter_device *counter,
360+ struct counter_count *count,
361+ struct counter_count_read_value *val);
362+ int (*count_write)(struct counter_device *counter,
363+ struct counter_count *count,
364+ struct counter_count_write_value *val);
365+ int (*function_get)(struct counter_device *counter,
366+ struct counter_count *count, size_t *function);
367+ int (*function_set)(struct counter_device *counter,
368+ struct counter_count *count, size_t function);
369+ int (*action_get)(struct counter_device *counter,
370+ struct counter_count *count,
371+ struct counter_synapse *synapse, size_t *action);
372+ int (*action_set)(struct counter_device *counter,
373+ struct counter_count *count,
374+ struct counter_synapse *synapse, size_t action);
375+};
376+
377+/**
378+ * struct counter_device_ext - Counter device extension
379+ * @name: attribute name
380+ * @read: read callback for this attribute; may be NULL
381+ * @write: write callback for this attribute; may be NULL
382+ * @priv: data private to the driver
383+ */
384+struct counter_device_ext {
385+ const char *name;
386+ ssize_t (*read)(struct counter_device *counter, void *priv, char *buf);
387+ ssize_t (*write)(struct counter_device *counter, void *priv,
388+ const char *buf, size_t len);
389+ void *priv;
390+};
391+
392+/**
393+ * struct counter_device_enum_ext - Counter enum extension attribute
394+ * @items: Array of strings
395+ * @num_items: Number of items specified in @items
396+ * @set: Set callback function; may be NULL
397+ * @get: Get callback function; may be NULL
398+ *
399+ * The counter_device_enum_ext structure can be used to implement enum style
400+ * Counter extension attributes. Enum style attributes are those which have a
401+ * set of strings that map to unsigned integer values. The Generic Counter enum
402+ * extension helper code takes care of mapping between value and string, as well
403+ * as generating a "_available" file which contains a list of all available
404+ * items. The get callback is used to query the currently active item; the index
405+ * of the item within the respective items array is returned via the 'item'
406+ * parameter. The set callback is called when the attribute is updated; the
407+ * 'item' parameter contains the index of the newly activated item within the
408+ * respective items array.
409+ */
410+struct counter_device_enum_ext {
411+ const char * const *items;
412+ size_t num_items;
413+ int (*get)(struct counter_device *counter, size_t *item);
414+ int (*set)(struct counter_device *counter, size_t item);
415+};
416+
417+/**
418+ * COUNTER_DEVICE_ENUM() - Initialize Counter enum extension
419+ * @_name: Attribute name
420+ * @_e: Pointer to a counter_device_enum_ext structure
421+ *
422+ * This should usually be used together with COUNTER_DEVICE_ENUM_AVAILABLE()
423+ */
424+#define COUNTER_DEVICE_ENUM(_name, _e) \
425+{ \
426+ .name = (_name), \
427+ .read = counter_device_enum_read, \
428+ .write = counter_device_enum_write, \
429+ .priv = (_e) \
430+}
431+
432+/**
433+ * COUNTER_DEVICE_ENUM_AVAILABLE() - Initialize Counter enum available extension
434+ * @_name: Attribute name ("_available" will be appended to the name)
435+ * @_e: Pointer to a counter_device_enum_ext structure
436+ *
437+ * Creates a read only attribute that lists all the available enum items in a
438+ * newline separated list. This should usually be used together with
439+ * COUNTER_DEVICE_ENUM()
440+ */
441+#define COUNTER_DEVICE_ENUM_AVAILABLE(_name, _e) \
442+{ \
443+ .name = (_name "_available"), \
444+ .read = counter_device_enum_available_read, \
445+ .priv = (_e) \
446+}
447+
448+/**
449+ * struct counter_device - Counter data structure
450+ * @name: name of the device as it appears in the datasheet
451+ * @parent: optional parent device providing the counters
452+ * @device_state: internal device state container
453+ * @ops: callbacks from driver
454+ * @signals: array of Signals
455+ * @num_signals: number of Signals specified in @signals
456+ * @counts: array of Counts
457+ * @num_counts: number of Counts specified in @counts
458+ * @ext: optional array of Counter device extensions
459+ * @num_ext: number of Counter device extensions specified in @ext
460+ * @priv: optional private data supplied by driver
461+ */
462+struct counter_device {
463+ const char *name;
464+ struct device *parent;
465+ struct counter_device_state *device_state;
466+
467+ const struct counter_ops *ops;
468+
469+ struct counter_signal *signals;
470+ size_t num_signals;
471+ struct counter_count *counts;
472+ size_t num_counts;
473+
474+ const struct counter_device_ext *ext;
475+ size_t num_ext;
476+
477+ void *priv;
478+};
479+
480+enum counter_signal_level {
481+ COUNTER_SIGNAL_LEVEL_LOW = 0,
482+ COUNTER_SIGNAL_LEVEL_HIGH
483+};
484+
485+enum counter_signal_value_type {
486+ COUNTER_SIGNAL_LEVEL = 0
487+};
488+
489+enum counter_count_value_type {
490+ COUNTER_COUNT_POSITION = 0,
491+};
492+
493+void counter_signal_read_value_set(struct counter_signal_read_value *const val,
494+ const enum counter_signal_value_type type,
495+ void *const data);
496+void counter_count_read_value_set(struct counter_count_read_value *const val,
497+ const enum counter_count_value_type type,
498+ void *const data);
499+int counter_count_write_value_get(void *const data,
500+ const enum counter_count_value_type type,
501+ const struct counter_count_write_value *const val);
502+
503+int counter_register(struct counter_device *const counter);
504+void counter_unregister(struct counter_device *const counter);
505+int devm_counter_register(struct device *dev,
506+ struct counter_device *const counter);
507+void devm_counter_unregister(struct device *dev,
508+ struct counter_device *const counter);
509+
510+#endif /* _COUNTER_H_ */
include/linux/counter_enum.h+45−0
@@ -0,0 +1,45 @@
1+/* SPDX-License-Identifier: GPL-2.0 */
2+/*
3+ * Counter interface enum functions
4+ * Copyright (C) 2018 William Breathitt Gray
5+ */
6+#ifndef _COUNTER_ENUM_H_
7+#define _COUNTER_ENUM_H_
8+
9+#include <linux/types.h>
10+
11+struct counter_device;
12+struct counter_signal;
13+struct counter_count;
14+
15+ssize_t counter_signal_enum_read(struct counter_device *counter,
16+ struct counter_signal *signal, void *priv,
17+ char *buf);
18+ssize_t counter_signal_enum_write(struct counter_device *counter,
19+ struct counter_signal *signal, void *priv,
20+ const char *buf, size_t len);
21+
22+ssize_t counter_signal_enum_available_read(struct counter_device *counter,
23+ struct counter_signal *signal,
24+ void *priv, char *buf);
25+
26+ssize_t counter_count_enum_read(struct counter_device *counter,
27+ struct counter_count *count, void *priv,
28+ char *buf);
29+ssize_t counter_count_enum_write(struct counter_device *counter,
30+ struct counter_count *count, void *priv,
31+ const char *buf, size_t len);
32+
33+ssize_t counter_count_enum_available_read(struct counter_device *counter,
34+ struct counter_count *count,
35+ void *priv, char *buf);
36+
37+ssize_t counter_device_enum_read(struct counter_device *counter, void *priv,
38+ char *buf);
39+ssize_t counter_device_enum_write(struct counter_device *counter, void *priv,
40+ const char *buf, size_t len);
41+
42+ssize_t counter_device_enum_available_read(struct counter_device *counter,
43+ void *priv, char *buf);
44+
45+#endif /* _COUNTER_ENUM_H_ */

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t