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