GNU Linux-libre 6.9.2-gnu
[releases.git] / include / uapi / linux / counter.h
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_SCOPE_COUNT, 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         /* State of counter is changed */
65         COUNTER_EVENT_CHANGE_OF_STATE,
66         /* Count value captured */
67         COUNTER_EVENT_CAPTURE,
68 };
69
70 /**
71  * struct counter_watch - Counter component watch configuration
72  * @component: component to watch when event triggers
73  * @event: event that triggers (one of enum counter_event_type)
74  * @channel: event channel (typically 0 unless the device supports concurrent
75  *           events of the same type)
76  */
77 struct counter_watch {
78         struct counter_component component;
79         __u8 event;
80         __u8 channel;
81 };
82
83 /*
84  * Queues a Counter watch for the specified event.
85  *
86  * The queued watches will not be applied until COUNTER_ENABLE_EVENTS_IOCTL is
87  * called.
88  */
89 #define COUNTER_ADD_WATCH_IOCTL _IOW(0x3E, 0x00, struct counter_watch)
90 /*
91  * Enables monitoring the events specified by the Counter watches that were
92  * queued by COUNTER_ADD_WATCH_IOCTL.
93  *
94  * If events are already enabled, the new set of watches replaces the old one.
95  * Calling this ioctl also has the effect of clearing the queue of watches added
96  * by COUNTER_ADD_WATCH_IOCTL.
97  */
98 #define COUNTER_ENABLE_EVENTS_IOCTL _IO(0x3E, 0x01)
99 /*
100  * Stops monitoring the previously enabled events.
101  */
102 #define COUNTER_DISABLE_EVENTS_IOCTL _IO(0x3E, 0x02)
103
104 /**
105  * struct counter_event - Counter event data
106  * @timestamp: best estimate of time of event occurrence, in nanoseconds
107  * @value: component value
108  * @watch: component watch configuration
109  * @status: return status (system error number)
110  */
111 struct counter_event {
112         __aligned_u64 timestamp;
113         __aligned_u64 value;
114         struct counter_watch watch;
115         __u8 status;
116 };
117
118 /* Count direction values */
119 enum counter_count_direction {
120         COUNTER_COUNT_DIRECTION_FORWARD,
121         COUNTER_COUNT_DIRECTION_BACKWARD,
122 };
123
124 /* Count mode values */
125 enum counter_count_mode {
126         COUNTER_COUNT_MODE_NORMAL,
127         COUNTER_COUNT_MODE_RANGE_LIMIT,
128         COUNTER_COUNT_MODE_NON_RECYCLE,
129         COUNTER_COUNT_MODE_MODULO_N,
130         COUNTER_COUNT_MODE_INTERRUPT_ON_TERMINAL_COUNT,
131         COUNTER_COUNT_MODE_HARDWARE_RETRIGGERABLE_ONESHOT,
132         COUNTER_COUNT_MODE_RATE_GENERATOR,
133         COUNTER_COUNT_MODE_SQUARE_WAVE_MODE,
134         COUNTER_COUNT_MODE_SOFTWARE_TRIGGERED_STROBE,
135         COUNTER_COUNT_MODE_HARDWARE_TRIGGERED_STROBE,
136 };
137
138 /* Count function values */
139 enum counter_function {
140         COUNTER_FUNCTION_INCREASE,
141         COUNTER_FUNCTION_DECREASE,
142         COUNTER_FUNCTION_PULSE_DIRECTION,
143         COUNTER_FUNCTION_QUADRATURE_X1_A,
144         COUNTER_FUNCTION_QUADRATURE_X1_B,
145         COUNTER_FUNCTION_QUADRATURE_X2_A,
146         COUNTER_FUNCTION_QUADRATURE_X2_B,
147         COUNTER_FUNCTION_QUADRATURE_X4,
148 };
149
150 /* Signal values */
151 enum counter_signal_level {
152         COUNTER_SIGNAL_LEVEL_LOW,
153         COUNTER_SIGNAL_LEVEL_HIGH,
154 };
155
156 /* Action mode values */
157 enum counter_synapse_action {
158         COUNTER_SYNAPSE_ACTION_NONE,
159         COUNTER_SYNAPSE_ACTION_RISING_EDGE,
160         COUNTER_SYNAPSE_ACTION_FALLING_EDGE,
161         COUNTER_SYNAPSE_ACTION_BOTH_EDGES,
162 };
163
164 /* Signal polarity values */
165 enum counter_signal_polarity {
166         COUNTER_SIGNAL_POLARITY_POSITIVE,
167         COUNTER_SIGNAL_POLARITY_NEGATIVE,
168 };
169
170 #endif /* _UAPI_COUNTER_H_ */