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_ */