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