uapi/linux/counter.h

0001 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
0002 /*
0003  * Userspace ABI for Counter character devices
0004  * Copyright (C) 2020 William Breathitt Gray
0005  */
0006 #ifndef _UAPI_COUNTER_H_
0007 #define _UAPI_COUNTER_H_
0008
0009 #include <linux/ioctl.h>
0010 #include <linux/types.h>
0011
0012 /* Component type definitions */
0013 enum counter_component_type {
0014     COUNTER_COMPONENT_NONE,
0015     COUNTER_COMPONENT_SIGNAL,
0016     COUNTER_COMPONENT_COUNT,
0017     COUNTER_COMPONENT_FUNCTION,
0018     COUNTER_COMPONENT_SYNAPSE_ACTION,
0019     COUNTER_COMPONENT_EXTENSION,
0020 };
0021
0022 /* Component scope definitions */
0023 enum counter_scope {
0024     COUNTER_SCOPE_DEVICE,
0025     COUNTER_SCOPE_SIGNAL,
0026     COUNTER_SCOPE_COUNT,
0027 };
0028
0029 /**
0030  * struct counter_component - Counter component identification
0031  * @type: component type (one of enum counter_component_type)
0032  * @scope: component scope (one of enum counter_scope)
0033  * @parent: parent ID (matching the ID suffix of the respective parent sysfs
0034  *          path as described by the ABI documentation file
0035  *          Documentation/ABI/testing/sysfs-bus-counter)
0036  * @id: component ID (matching the ID provided by the respective *_component_id
0037  *      sysfs attribute of the desired component)
0038  *
0039  * For example, if the Count 2 ceiling extension of Counter device 4 is desired,
0040  * set type equal to COUNTER_COMPONENT_EXTENSION, scope equal to
0041  * COUNTER_COUNT_SCOPE, parent equal to 2, and id equal to the value provided by
0042  * the respective /sys/bus/counter/devices/counter4/count2/ceiling_component_id
0043  * sysfs attribute.
0044  */
0045 struct counter_component {
0046     __u8 type;
0047     __u8 scope;
0048     __u8 parent;
0049     __u8 id;
0050 };
0051
0052 /* Event type definitions */
0053 enum counter_event_type {
0054     /* Count value increased past ceiling */
0055     COUNTER_EVENT_OVERFLOW,
0056     /* Count value decreased past floor */
0057     COUNTER_EVENT_UNDERFLOW,
0058     /* Count value increased past ceiling, or decreased past floor */
0059     COUNTER_EVENT_OVERFLOW_UNDERFLOW,
0060     /* Count value reached threshold */
0061     COUNTER_EVENT_THRESHOLD,
0062     /* Index signal detected */
0063     COUNTER_EVENT_INDEX,
0064     /* State of counter is changed */
0065     COUNTER_EVENT_CHANGE_OF_STATE,
0066 };
0067
0068 /**
0069  * struct counter_watch - Counter component watch configuration
0070  * @component: component to watch when event triggers
0071  * @event: event that triggers (one of enum counter_event_type)
0072  * @channel: event channel (typically 0 unless the device supports concurrent
0073  *       events of the same type)
0074  */
0075 struct counter_watch {
0076     struct counter_component component;
0077     __u8 event;
0078     __u8 channel;
0079 };
0080
0081 /*
0082  * Queues a Counter watch for the specified event.
0083  *
0084  * The queued watches will not be applied until COUNTER_ENABLE_EVENTS_IOCTL is
0085  * called.
0086  */
0087 #define COUNTER_ADD_WATCH_IOCTL _IOW(0x3E, 0x00, struct counter_watch)
0088 /*
0089  * Enables monitoring the events specified by the Counter watches that were
0090  * queued by COUNTER_ADD_WATCH_IOCTL.
0091  *
0092  * If events are already enabled, the new set of watches replaces the old one.
0093  * Calling this ioctl also has the effect of clearing the queue of watches added
0094  * by COUNTER_ADD_WATCH_IOCTL.
0095  */
0096 #define COUNTER_ENABLE_EVENTS_IOCTL _IO(0x3E, 0x01)
0097 /*
0098  * Stops monitoring the previously enabled events.
0099  */
0100 #define COUNTER_DISABLE_EVENTS_IOCTL _IO(0x3E, 0x02)
0101
0102 /**
0103  * struct counter_event - Counter event data
0104  * @timestamp: best estimate of time of event occurrence, in nanoseconds
0105  * @value: component value
0106  * @watch: component watch configuration
0107  * @status: return status (system error number)
0108  */
0109 struct counter_event {
0110     __aligned_u64 timestamp;
0111     __aligned_u64 value;
0112     struct counter_watch watch;
0113     __u8 status;
0114 };
0115
0116 /* Count direction values */
0117 enum counter_count_direction {
0118     COUNTER_COUNT_DIRECTION_FORWARD,
0119     COUNTER_COUNT_DIRECTION_BACKWARD,
0120 };
0121
0122 /* Count mode values */
0123 enum counter_count_mode {
0124     COUNTER_COUNT_MODE_NORMAL,
0125     COUNTER_COUNT_MODE_RANGE_LIMIT,
0126     COUNTER_COUNT_MODE_NON_RECYCLE,
0127     COUNTER_COUNT_MODE_MODULO_N,
0128 };
0129
0130 /* Count function values */
0131 enum counter_function {
0132     COUNTER_FUNCTION_INCREASE,
0133     COUNTER_FUNCTION_DECREASE,
0134     COUNTER_FUNCTION_PULSE_DIRECTION,
0135     COUNTER_FUNCTION_QUADRATURE_X1_A,
0136     COUNTER_FUNCTION_QUADRATURE_X1_B,
0137     COUNTER_FUNCTION_QUADRATURE_X2_A,
0138     COUNTER_FUNCTION_QUADRATURE_X2_B,
0139     COUNTER_FUNCTION_QUADRATURE_X4,
0140 };
0141
0142 /* Signal values */
0143 enum counter_signal_level {
0144     COUNTER_SIGNAL_LEVEL_LOW,
0145     COUNTER_SIGNAL_LEVEL_HIGH,
0146 };
0147
0148 /* Action mode values */
0149 enum counter_synapse_action {
0150     COUNTER_SYNAPSE_ACTION_NONE,
0151     COUNTER_SYNAPSE_ACTION_RISING_EDGE,
0152     COUNTER_SYNAPSE_ACTION_FALLING_EDGE,
0153     COUNTER_SYNAPSE_ACTION_BOTH_EDGES,
0154 };
0155
0156 #endif /* _UAPI_COUNTER_H_ */