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 */
13enum 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 */
23enum 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 */
45struct counter_component {
46	__u8 type;
47	__u8 scope;
48	__u8 parent;
49	__u8 id;
50};
51
52/* Event type definitions */
53enum 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 */
77struct 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 */
111struct counter_event {
112	__aligned_u64 timestamp;
113	__aligned_u64 value;
114	struct counter_watch watch;
115	__u8 status;
116};
117
118/* Count direction values */
119enum counter_count_direction {
120	COUNTER_COUNT_DIRECTION_FORWARD,
121	COUNTER_COUNT_DIRECTION_BACKWARD,
122};
123
124/* Count mode values */
125enum 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 */
139enum 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 */
151enum counter_signal_level {
152	COUNTER_SIGNAL_LEVEL_LOW,
153	COUNTER_SIGNAL_LEVEL_HIGH,
154};
155
156/* Action mode values */
157enum 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 */
165enum counter_signal_polarity {
166	COUNTER_SIGNAL_POLARITY_POSITIVE,
167	COUNTER_SIGNAL_POLARITY_NEGATIVE,
168};
169
170#endif /* _UAPI_COUNTER_H_ */
171