1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
2 /*
3  * Userspace ABI for Counter character devices
4  * Copyright (C) 2020 William Breathitt Gray
5  */
6 #ifndef _UAPI_COUNTER_H_
7 #define _UAPI_COUNTER_H_
8 
9 #include <linux/ioctl.h>
10 #include <linux/types.h>
11 
12 /* Component type definitions */
13 enum counter_component_type {
14 	COUNTER_COMPONENT_NONE,
15 	COUNTER_COMPONENT_SIGNAL,
16 	COUNTER_COMPONENT_COUNT,
17 	COUNTER_COMPONENT_FUNCTION,
18 	COUNTER_COMPONENT_SYNAPSE_ACTION,
19 	COUNTER_COMPONENT_EXTENSION,
20 };
21 
22 /* Component scope definitions */
23 enum counter_scope {
24 	COUNTER_SCOPE_DEVICE,
25 	COUNTER_SCOPE_SIGNAL,
26 	COUNTER_SCOPE_COUNT,
27 };
28 
29 /**
30  * struct counter_component - Counter component identification
31  * @type: component type (one of enum counter_component_type)
32  * @scope: component scope (one of enum counter_scope)
33  * @parent: parent ID (matching the ID suffix of the respective parent sysfs
34  *          path as described by the ABI documentation file
35  *          Documentation/ABI/testing/sysfs-bus-counter)
36  * @id: component ID (matching the ID provided by the respective *_component_id
37  *      sysfs attribute of the desired component)
38  *
39  * For example, if the Count 2 ceiling extension of Counter device 4 is desired,
40  * set type equal to COUNTER_COMPONENT_EXTENSION, scope equal to
41  * COUNTER_COUNT_SCOPE, parent equal to 2, and id equal to the value provided by
42  * the respective /sys/bus/counter/devices/counter4/count2/ceiling_component_id
43  * sysfs attribute.
44  */
45 struct counter_component {
46 	__u8 type;
47 	__u8 scope;
48 	__u8 parent;
49 	__u8 id;
50 };
51 
52 /* Event type definitions */
53 enum counter_event_type {
54 	/* Count value increased past ceiling */
55 	COUNTER_EVENT_OVERFLOW,
56 	/* Count value decreased past floor */
57 	COUNTER_EVENT_UNDERFLOW,
58 	/* Count value increased past ceiling, or decreased past floor */
59 	COUNTER_EVENT_OVERFLOW_UNDERFLOW,
60 	/* Count value reached threshold */
61 	COUNTER_EVENT_THRESHOLD,
62 	/* Index signal detected */
63 	COUNTER_EVENT_INDEX,
64 };
65 
66 /**
67  * struct counter_watch - Counter component watch configuration
68  * @component: component to watch when event triggers
69  * @event: event that triggers (one of enum counter_event_type)
70  * @channel: event channel (typically 0 unless the device supports concurrent
71  *	     events of the same type)
72  */
73 struct counter_watch {
74 	struct counter_component component;
75 	__u8 event;
76 	__u8 channel;
77 };
78 
79 /*
80  * Queues a Counter watch for the specified event.
81  *
82  * The queued watches will not be applied until COUNTER_ENABLE_EVENTS_IOCTL is
83  * called.
84  */
85 #define COUNTER_ADD_WATCH_IOCTL _IOW(0x3E, 0x00, struct counter_watch)
86 /*
87  * Enables monitoring the events specified by the Counter watches that were
88  * queued by COUNTER_ADD_WATCH_IOCTL.
89  *
90  * If events are already enabled, the new set of watches replaces the old one.
91  * Calling this ioctl also has the effect of clearing the queue of watches added
92  * by COUNTER_ADD_WATCH_IOCTL.
93  */
94 #define COUNTER_ENABLE_EVENTS_IOCTL _IO(0x3E, 0x01)
95 /*
96  * Stops monitoring the previously enabled events.
97  */
98 #define COUNTER_DISABLE_EVENTS_IOCTL _IO(0x3E, 0x02)
99 
100 /**
101  * struct counter_event - Counter event data
102  * @timestamp: best estimate of time of event occurrence, in nanoseconds
103  * @value: component value
104  * @watch: component watch configuration
105  * @status: return status (system error number)
106  */
107 struct counter_event {
108 	__aligned_u64 timestamp;
109 	__aligned_u64 value;
110 	struct counter_watch watch;
111 	__u8 status;
112 };
113 
114 /* Count direction values */
115 enum counter_count_direction {
116 	COUNTER_COUNT_DIRECTION_FORWARD,
117 	COUNTER_COUNT_DIRECTION_BACKWARD,
118 };
119 
120 /* Count mode values */
121 enum counter_count_mode {
122 	COUNTER_COUNT_MODE_NORMAL,
123 	COUNTER_COUNT_MODE_RANGE_LIMIT,
124 	COUNTER_COUNT_MODE_NON_RECYCLE,
125 	COUNTER_COUNT_MODE_MODULO_N,
126 };
127 
128 /* Count function values */
129 enum counter_function {
130 	COUNTER_FUNCTION_INCREASE,
131 	COUNTER_FUNCTION_DECREASE,
132 	COUNTER_FUNCTION_PULSE_DIRECTION,
133 	COUNTER_FUNCTION_QUADRATURE_X1_A,
134 	COUNTER_FUNCTION_QUADRATURE_X1_B,
135 	COUNTER_FUNCTION_QUADRATURE_X2_A,
136 	COUNTER_FUNCTION_QUADRATURE_X2_B,
137 	COUNTER_FUNCTION_QUADRATURE_X4,
138 };
139 
140 /* Signal values */
141 enum counter_signal_level {
142 	COUNTER_SIGNAL_LEVEL_LOW,
143 	COUNTER_SIGNAL_LEVEL_HIGH,
144 };
145 
146 /* Action mode values */
147 enum counter_synapse_action {
148 	COUNTER_SYNAPSE_ACTION_NONE,
149 	COUNTER_SYNAPSE_ACTION_RISING_EDGE,
150 	COUNTER_SYNAPSE_ACTION_FALLING_EDGE,
151 	COUNTER_SYNAPSE_ACTION_BOTH_EDGES,
152 };
153 
154 #endif /* _UAPI_COUNTER_H_ */
155