Line data Source code
1 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 1 : struct input_event {
48 : /** Device generating the event or NULL. */
49 1 : const struct device *dev;
50 : /** Sync flag. */
51 1 : uint8_t sync;
52 : /** Event type (see @ref INPUT_EV_CODES). */
53 1 : 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 1 : uint16_t code;
59 : /** Event value. */
60 1 : 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 negative if @kconfig{CONFIG_INPUT_MODE_THREAD} is enabled and the
79 : * message failed to be enqueued.
80 : */
81 1 : 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 : */
91 1 : 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 : */
103 1 : 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 : */
115 1 : 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 1 : bool input_queue_empty(void);
130 :
131 : /**
132 : * @brief Input callback structure.
133 : */
134 1 : struct input_callback {
135 : /** @ref device pointer or NULL. */
136 1 : const struct device *dev;
137 : /** The callback function. */
138 1 : void (*callback)(struct input_event *evt, void *user_data);
139 : /** User data pointer. */
140 1 : 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 1 : #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 1 : #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_ */
|
