Line data Source code
1 0 : /*
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 1 : struct input_event {
37 : /** Device generating the event or NULL. */
38 1 : const struct device *dev;
39 : /** Sync flag. */
40 1 : uint8_t sync;
41 : /** Event type (see @ref INPUT_EV_CODES). */
42 1 : 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 1 : uint16_t code;
48 : /** Event value. */
49 1 : 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 1 : 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 : */
80 1 : 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 : */
92 1 : 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 : */
104 1 : 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 1 : bool input_queue_empty(void);
119 :
120 : /**
121 : * @brief Input callback structure.
122 : */
123 1 : struct input_callback {
124 : /** @ref device pointer or NULL. */
125 1 : const struct device *dev;
126 : /** The callback function. */
127 1 : void (*callback)(struct input_event *evt, void *user_data);
128 : /** User data pointer. */
129 1 : 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 1 : #define INPUT_CALLBACK_DEFINE_NAMED(_dev, _callback, _user_data, name) \
140 : static const STRUCT_SECTION_ITERABLE(input_callback, \
141 : _input_callback__##name) = { \
142 : .dev = _dev, \
143 : .callback = _callback, \
144 : .user_data = _user_data, \
145 : }
146 :
147 : /**
148 : * @brief Register a callback structure for input events.
149 : *
150 : * The @p _dev field can be used to only invoke callback for events generated
151 : * by a specific device. Setting dev to NULL causes callback to be invoked for
152 : * every event.
153 : *
154 : * @param _dev @ref device pointer or NULL.
155 : * @param _callback The callback function.
156 : * @param _user_data Pointer to user specified data.
157 : */
158 1 : #define INPUT_CALLBACK_DEFINE(_dev, _callback, _user_data) \
159 : INPUT_CALLBACK_DEFINE_NAMED(_dev, _callback, _user_data, _callback)
160 :
161 : #ifdef __cplusplus
162 : }
163 : #endif
164 :
165 : /** @} */
166 :
167 : #endif /* ZEPHYR_INCLUDE_INPUT_H_ */
|
