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