1 /*
2 * Copyright 2023 Google LLC
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 #ifndef ZEPHYR_INCLUDE_INPUT_H_
8 #define ZEPHYR_INCLUDE_INPUT_H_
9
10 /**
11 * @brief Input Interface
12 * @defgroup input_interface Input Interface
13 * @ingroup io_interfaces
14 * @{
15 */
16
17 #include <stdint.h>
18 #include <zephyr/device.h>
19 #include <zephyr/dt-bindings/input/input-event-codes.h>
20 #include <zephyr/kernel.h>
21 #include <zephyr/sys/iterable_sections.h>
22
23 #ifdef __cplusplus
24 extern "C" {
25 #endif
26
27 /**
28 * @brief Input event structure.
29 *
30 * This structure represents a single input event, for example a key or button
31 * press for a single button, or an absolute or relative coordinate for a
32 * single axis.
33 */
34 struct input_event {
35 /** Device generating the event or NULL. */
36 const struct device *dev;
37 /** Sync flag. */
38 uint8_t sync;
39 /** Event type (see @ref INPUT_EV_CODES). */
40 uint8_t type;
41 /**
42 * Event code (see @ref INPUT_KEY_CODES, @ref INPUT_BTN_CODES,
43 * @ref INPUT_ABS_CODES, @ref INPUT_REL_CODES, @ref INPUT_MSC_CODES).
44 */
45 uint16_t code;
46 /** Event value. */
47 int32_t value;
48 };
49
50 /**
51 * @brief Report a new input event.
52 *
53 * This causes all the listeners for the specified device to be triggered,
54 * either synchronously or through the input thread if utilized.
55 *
56 * @param dev Device generating the event or NULL.
57 * @param type Event type (see @ref INPUT_EV_CODES).
58 * @param code Event code (see @ref INPUT_KEY_CODES, @ref INPUT_BTN_CODES,
59 * @ref INPUT_ABS_CODES, @ref INPUT_REL_CODES, @ref INPUT_MSC_CODES).
60 * @param value Event value.
61 * @param sync Set the synchronization bit for the event.
62 * @param timeout Timeout for reporting the event, ignored if
63 * @kconfig{CONFIG_INPUT_MODE_SYNCHRONOUS} is used.
64 * @retval 0 if the message has been processed.
65 * @retval negative if @kconfig{CONFIG_INPUT_MODE_THREAD} is enabled and the
66 * message failed to be enqueued.
67 */
68 int input_report(const struct device *dev,
69 uint8_t type, uint16_t code, int32_t value, bool sync,
70 k_timeout_t timeout);
71
72 /**
73 * @brief Report a new @ref INPUT_EV_KEY input event, note that value is
74 * converted to either 0 or 1.
75 *
76 * @see input_report() for more details.
77 */
input_report_key(const struct device * dev,uint16_t code,int32_t value,bool sync,k_timeout_t timeout)78 static inline int input_report_key(const struct device *dev,
79 uint16_t code, int32_t value, bool sync,
80 k_timeout_t timeout)
81 {
82 return input_report(dev, INPUT_EV_KEY, code, !!value, sync, timeout);
83 }
84
85 /**
86 * @brief Report a new @ref INPUT_EV_REL input event.
87 *
88 * @see input_report() for more details.
89 */
input_report_rel(const struct device * dev,uint16_t code,int32_t value,bool sync,k_timeout_t timeout)90 static inline int input_report_rel(const struct device *dev,
91 uint16_t code, int32_t value, bool sync,
92 k_timeout_t timeout)
93 {
94 return input_report(dev, INPUT_EV_REL, code, value, sync, timeout);
95 }
96
97 /**
98 * @brief Report a new @ref INPUT_EV_ABS input event.
99 *
100 * @see input_report() for more details.
101 */
input_report_abs(const struct device * dev,uint16_t code,int32_t value,bool sync,k_timeout_t timeout)102 static inline int input_report_abs(const struct device *dev,
103 uint16_t code, int32_t value, bool sync,
104 k_timeout_t timeout)
105 {
106 return input_report(dev, INPUT_EV_ABS, code, value, sync, timeout);
107 }
108
109 /**
110 * @brief Returns true if the input queue is empty.
111 *
112 * This can be used to batch input event processing until the whole queue has
113 * been emptied. Always returns true if @kconfig{CONFIG_INPUT_MODE_SYNCHRONOUS}
114 * is enabled.
115 */
116 bool input_queue_empty(void);
117
118 /**
119 * @brief Input listener callback structure.
120 */
121 struct input_listener {
122 /** @ref device pointer or NULL. */
123 const struct device *dev;
124 /** The callback function. */
125 void (*callback)(struct input_event *evt);
126 };
127
128 /**
129 * @brief Register a callback structure for input events.
130 *
131 * The @p _dev field can be used to only invoke callback for events generated
132 * by a specific device. Setting dev to NULL causes callback to be invoked for
133 * every event.
134 *
135 * @param _dev @ref device pointer or NULL.
136 * @param _callback The callback function.
137 */
138 #define INPUT_CALLBACK_DEFINE(_dev, _callback) \
139 static const STRUCT_SECTION_ITERABLE(input_listener, \
140 _input_listener__##_callback) = { \
141 .dev = _dev, \
142 .callback = _callback, \
143 }
144
145 #ifdef __cplusplus
146 }
147 #endif
148
149 /** @} */
150
151 #endif /* ZEPHYR_INCLUDE_INPUT_H_ */
152
