Line data    Source code

       1           1 : /*
       2             :  * Copyright (c) 2020 Friedt Professional Engineering Services, Inc
       3             :  *
       4             :  * SPDX-License-Identifier: Apache-2.0
       5             :  */
       6             : 
       7             : /**
       8             :  * @file
       9             :  * @brief Backend API for emulated GPIO
      10             :  */
      11             : 
      12             : #ifndef ZEPHYR_INCLUDE_DRIVERS_GPIO_GPIO_EMUL_H_
      13             : #define ZEPHYR_INCLUDE_DRIVERS_GPIO_GPIO_EMUL_H_
      14             : 
      15             : #include <zephyr/types.h>
      16             : #include <zephyr/drivers/gpio.h>
      17             : 
      18             : #ifdef __cplusplus
      19             : extern "C" {
      20             : #endif
      21             : 
      22             : /**
      23             :  * @brief Emulated GPIO backend API
      24             :  * @defgroup gpio_emul Emulated GPIO
      25             :  * @ingroup gpio_interface
      26             :  * @{
      27             :  *
      28             :  * Behaviour of emulated GPIO is application-defined. As-such, each
      29             :  * application may
      30             :  *
      31             :  * - define a Device Tree overlay file to indicate the number of GPIO
      32             :  *   controllers as well as the number of pins for each controller
      33             :  * - register a callback with the GPIO controller using
      34             :  *   @ref gpio_add_callback to emulate "wiring"
      35             :  * - asynchronously call @ref gpio_emul_input_set and / or
      36             :  *   @ref gpio_emul_input_set_masked in order to emulate GPIO events
      37             :  *
      38             :  * An example of an appropriate Device Tree overlay file is in
      39             :  * tests/drivers/gpio/gpio_basic_api/boards/native_sim.overlay.
      40             :  *
      41             :  * An example of registering a callback to emulate "wiring" as well as
      42             :  * an example of calling @ref gpio_emul_input_set is in the file
      43             :  * tests/drivers/gpio/gpio_basic_api/src/main.c .
      44             :  */
      45             : 
      46             : /**
      47             :  * @brief Modify the values of one or more emulated GPIO input @p pins
      48             :  *
      49             :  * @param port The emulated GPIO port
      50             :  * @param pins The mask of pins that have changed
      51             :  * @param values New values to assign to @p pins
      52             :  *
      53             :  * @return 0 on success
      54             :  * @return -EINVAL if an invalid argument is provided
      55             :  */
      56           1 : int gpio_emul_input_set_masked(const struct device *port, gpio_port_pins_t pins,
      57             :                               gpio_port_value_t values);
      58             : 
      59             : /**
      60             :  * @brief Modify the value of one emulated GPIO input @p pin
      61             :  *
      62             :  * @param port The emulated GPIO port
      63             :  * @param pin The pin to modify
      64             :  * @param value New values to assign to @p pin
      65             :  *
      66             :  * @return 0 on success
      67             :  * @return -EINVAL if an invalid argument is provided
      68             :  */
      69           1 : static inline int gpio_emul_input_set(const struct device *port, gpio_pin_t pin,
      70             :                                      int value)
      71             : {
      72             :         return gpio_emul_input_set_masked(port, BIT(pin), value ? BIT(pin) : 0);
      73             : }
      74             : 
      75             : /**
      76             :  * @brief Read the value of one or more emulated GPIO output @p pins
      77             :  *
      78             :  * @param port The emulated GPIO port
      79             :  * @param pins The mask of pins that have changed
      80             :  * @param values A pointer to where the value of @p pins will be stored
      81             :  *
      82             :  * @return 0 on success
      83             :  * @return -EINVAL if an invalid argument is provided
      84             :  */
      85           1 : int gpio_emul_output_get_masked(const struct device *port, gpio_port_pins_t pins,
      86             :                                gpio_port_value_t *values);
      87             : 
      88             : /**
      89             :  * @brief Read the value of one emulated GPIO output @p pin
      90             :  *
      91             :  * @param port The emulated GPIO port
      92             :  * @param pin The pin to read
      93             :  *
      94             :  * @return 0 or 1 on success
      95             :  * @return -EINVAL if an invalid argument is provided
      96             :  */
      97           1 : static inline int gpio_emul_output_get(const struct device *port, gpio_pin_t pin)
      98             : {
      99             :         int ret;
     100             :         gpio_port_value_t values;
     101             : 
     102             :         ret = gpio_emul_output_get_masked(port, BIT(pin), &values);
     103             :         if (ret == 0) {
     104             :                 ret = (values & BIT(pin)) ? 1 : 0;
     105             :         }
     106             : 
     107             :         return ret;
     108             : }
     109             : 
     110             : /**
     111             :  * @brief Get @p flags for a given emulated GPIO @p pin
     112             :  *
     113             :  * For more information on available flags, see @ref gpio_interface.
     114             :  *
     115             :  * @param port The emulated GPIO port
     116             :  * @param pin The pin to retrieve @p flags for
     117             :  * @param flags a pointer to where the flags for @p pin will be stored
     118             :  *
     119             :  * @return 0 on success
     120             :  * @return -EINVAL if an invalid argument is provided
     121             :  */
     122           1 : int gpio_emul_flags_get(const struct device *port, gpio_pin_t pin, gpio_flags_t *flags);
     123             : 
     124             : /**
     125             :  * @}
     126             :  */
     127             : 
     128             : #ifdef __cplusplus
     129             : }
     130             : #endif
     131             : 
     132             : #endif /* ZEPHYR_INCLUDE_DRIVERS_GPIO_GPIO_EMUL_H_ */