LCOV - code coverage report
Current view: top level - zephyr/input - input.h Coverage Total Hit
Test: new.info Lines: 100.0 % 18 18
Test Date: 2025-09-05 16:43:28

            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 Input Interface
      18              :  * @defgroup input_interface Input Interface
      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_ */
        

Generated by: LCOV version 2.0-1