/* * Copyright (c) 2019-2020 Nordic Semiconductor ASA * Copyright (c) 2019 Piotr Mienkowski * Copyright (c) 2017 ARM Ltd * Copyright (c) 2015-2016 Intel Corporation. * * SPDX-License-Identifier: Apache-2.0 */ /** * @file * @brief Public APIs for GPIO drivers */ #ifndef ZEPHYR_INCLUDE_DRIVERS_GPIO_H_ #define ZEPHYR_INCLUDE_DRIVERS_GPIO_H_ #include #include #include #include #include #include #ifdef __cplusplus extern "C" { #endif /** * @brief GPIO Driver APIs * @defgroup gpio_interface GPIO Driver APIs * @ingroup io_interfaces * @{ */ /** * @name GPIO input/output configuration flags * @{ */ /** Enables pin as input. */ #define GPIO_INPUT (1U << 8) /** Enables pin as output, no change to the output state. */ #define GPIO_OUTPUT (1U << 9) /** Disables pin for both input and output. */ #define GPIO_DISCONNECTED 0 /** @cond INTERNAL_HIDDEN */ /* Initializes output to a low state. */ #define GPIO_OUTPUT_INIT_LOW (1U << 10) /* Initializes output to a high state. */ #define GPIO_OUTPUT_INIT_HIGH (1U << 11) /* Initializes output based on logic level */ #define GPIO_OUTPUT_INIT_LOGICAL (1U << 12) /** @endcond */ /** Configures GPIO pin as output and initializes it to a low state. */ #define GPIO_OUTPUT_LOW (GPIO_OUTPUT | GPIO_OUTPUT_INIT_LOW) /** Configures GPIO pin as output and initializes it to a high state. */ #define GPIO_OUTPUT_HIGH (GPIO_OUTPUT | GPIO_OUTPUT_INIT_HIGH) /** Configures GPIO pin as output and initializes it to a logic 0. */ #define GPIO_OUTPUT_INACTIVE (GPIO_OUTPUT | \ GPIO_OUTPUT_INIT_LOW | \ GPIO_OUTPUT_INIT_LOGICAL) /** Configures GPIO pin as output and initializes it to a logic 1. */ #define GPIO_OUTPUT_ACTIVE (GPIO_OUTPUT | \ GPIO_OUTPUT_INIT_HIGH | \ GPIO_OUTPUT_INIT_LOGICAL) /** @} */ /** * @name GPIO interrupt configuration flags * The `GPIO_INT_*` flags are used to specify how input GPIO pins will trigger * interrupts. The interrupts can be sensitive to pin physical or logical level. * Interrupts sensitive to pin logical level take into account GPIO_ACTIVE_LOW * flag. If a pin was configured as Active Low, physical level low will be * considered as logical level 1 (an active state), physical level high will * be considered as logical level 0 (an inactive state). * @{ */ /** Disables GPIO pin interrupt. */ #define GPIO_INT_DISABLE (1U << 13) /** @cond INTERNAL_HIDDEN */ /* Enables GPIO pin interrupt. */ #define GPIO_INT_ENABLE (1U << 14) /* GPIO interrupt is sensitive to logical levels. * * This is a component flag that should be combined with other * `GPIO_INT_*` flags to produce a meaningful configuration. */ #define GPIO_INT_LEVELS_LOGICAL (1U << 15) /* GPIO interrupt is edge sensitive. * * Note: by default interrupts are level sensitive. * * This is a component flag that should be combined with other * `GPIO_INT_*` flags to produce a meaningful configuration. */ #define GPIO_INT_EDGE (1U << 16) /* Trigger detection when input state is (or transitions to) physical low or * logical 0 level. * * This is a component flag that should be combined with other * `GPIO_INT_*` flags to produce a meaningful configuration. */ #define GPIO_INT_LOW_0 (1U << 17) /* Trigger detection on input state is (or transitions to) physical high or * logical 1 level. * * This is a component flag that should be combined with other * `GPIO_INT_*` flags to produce a meaningful configuration. */ #define GPIO_INT_HIGH_1 (1U << 18) /** @endcond */ /** Configures GPIO interrupt to be triggered on pin rising edge and enables it. */ #define GPIO_INT_EDGE_RISING (GPIO_INT_ENABLE | \ GPIO_INT_EDGE | \ GPIO_INT_HIGH_1) /** Configures GPIO interrupt to be triggered on pin falling edge and enables * it. */ #define GPIO_INT_EDGE_FALLING (GPIO_INT_ENABLE | \ GPIO_INT_EDGE | \ GPIO_INT_LOW_0) /** Configures GPIO interrupt to be triggered on pin rising or falling edge and * enables it. */ #define GPIO_INT_EDGE_BOTH (GPIO_INT_ENABLE | \ GPIO_INT_EDGE | \ GPIO_INT_LOW_0 | \ GPIO_INT_HIGH_1) /** Configures GPIO interrupt to be triggered on pin physical level low and * enables it. */ #define GPIO_INT_LEVEL_LOW (GPIO_INT_ENABLE | \ GPIO_INT_LOW_0) /** Configures GPIO interrupt to be triggered on pin physical level high and * enables it. */ #define GPIO_INT_LEVEL_HIGH (GPIO_INT_ENABLE | \ GPIO_INT_HIGH_1) /** Configures GPIO interrupt to be triggered on pin state change to logical * level 0 and enables it. */ #define GPIO_INT_EDGE_TO_INACTIVE (GPIO_INT_ENABLE | \ GPIO_INT_LEVELS_LOGICAL | \ GPIO_INT_EDGE | \ GPIO_INT_LOW_0) /** Configures GPIO interrupt to be triggered on pin state change to logical * level 1 and enables it. */ #define GPIO_INT_EDGE_TO_ACTIVE (GPIO_INT_ENABLE | \ GPIO_INT_LEVELS_LOGICAL | \ GPIO_INT_EDGE | \ GPIO_INT_HIGH_1) /** Configures GPIO interrupt to be triggered on pin logical level 0 and enables * it. */ #define GPIO_INT_LEVEL_INACTIVE (GPIO_INT_ENABLE | \ GPIO_INT_LEVELS_LOGICAL | \ GPIO_INT_LOW_0) /** Configures GPIO interrupt to be triggered on pin logical level 1 and enables * it. */ #define GPIO_INT_LEVEL_ACTIVE (GPIO_INT_ENABLE | \ GPIO_INT_LEVELS_LOGICAL | \ GPIO_INT_HIGH_1) /** @} */ /** Enable GPIO pin debounce. * * @note Drivers that do not support a debounce feature should ignore * this flag rather than rejecting the configuration with -ENOTSUP. */ #define GPIO_INT_DEBOUNCE (1U << 19) /** * @name GPIO drive strength flags * The `GPIO_DS_*` flags are used with `gpio_pin_configure` to specify the drive * strength configuration of a GPIO pin. * * The drive strength of individual pins can be configured * independently for when the pin output is low and high. * * The `GPIO_DS_*_LOW` enumerations define the drive strength of a pin * when output is low. * The `GPIO_DS_*_HIGH` enumerations define the drive strength of a pin * when output is high. * * The interface supports two different drive strengths: * `DFLT` - The lowest drive strength supported by the HW * `ALT` - The highest drive strength supported by the HW * * On hardware that supports only one standard drive strength, both * `DFLT` and `ALT` have the same behavior. * @{ */ /** @cond INTERNAL_HIDDEN */ #define GPIO_DS_LOW_POS 20 #define GPIO_DS_LOW_MASK (0x3U << GPIO_DS_LOW_POS) /** @endcond */ /** Default drive strength standard when GPIO pin output is low. */ #define GPIO_DS_DFLT_LOW (0x0U << GPIO_DS_LOW_POS) /** Alternative drive strength when GPIO pin output is low. * For hardware that does not support configurable drive strength * use the default drive strength. */ #define GPIO_DS_ALT_LOW (0x1U << GPIO_DS_LOW_POS) /** @cond INTERNAL_HIDDEN */ #define GPIO_DS_HIGH_POS 22 #define GPIO_DS_HIGH_MASK (0x3U << GPIO_DS_HIGH_POS) /** @endcond */ /** Default drive strength when GPIO pin output is high. */ #define GPIO_DS_DFLT_HIGH (0x0U << GPIO_DS_HIGH_POS) /** Alternative drive strength when GPIO pin output is high. * For hardware that does not support configurable drive strengths * use the default drive strength. */ #define GPIO_DS_ALT_HIGH (0x1U << GPIO_DS_HIGH_POS) /** @} */ /** @cond INTERNAL_HIDDEN */ #define GPIO_DIR_MASK (GPIO_INPUT | GPIO_OUTPUT) /** @endcond */ /** * @brief Identifies a set of pins associated with a port. * * The pin with index n is present in the set if and only if the bit * identified by (1U << n) is set. */ typedef uint32_t gpio_port_pins_t; /** * @brief Provides values for a set of pins associated with a port. * * The value for a pin with index n is high (physical mode) or active * (logical mode) if and only if the bit identified by (1U << n) is set. * Otherwise the value for the pin is low (physical mode) or inactive * (logical mode). * * Values of this type are often paired with a `gpio_port_pins_t` value * that specifies which encoded pin values are valid for the operation. */ typedef uint32_t gpio_port_value_t; /** * @brief Provides a type to hold a GPIO pin index. * * This reduced-size type is sufficient to record a pin number, * e.g. from a devicetree GPIOS property. */ typedef uint8_t gpio_pin_t; /** * @brief Provides a type to hold GPIO devicetree flags. * * All GPIO flags that can be expressed in devicetree fit in the low 8 * bits of the full flags field, so use a reduced-size type to record * that part of a GPIOS property. */ typedef uint8_t gpio_dt_flags_t; /** * @brief Provides a type to hold GPIO configuration flags. * * This type is sufficient to hold all flags used to control GPIO * configuration, whether pin or interrupt. */ typedef uint32_t gpio_flags_t; /** * @brief Maximum number of pins that are supported by `gpio_port_pins_t`. */ #define GPIO_MAX_PINS_PER_PORT (sizeof(gpio_port_pins_t) * __CHAR_BIT__) /** * This structure is common to all GPIO drivers and is expected to be * the first element in the object pointed to by the config_info field * in the device structure. */ struct gpio_driver_config { /* Mask identifying pins supported by the controller. * * Initialization of this mask is the responsibility of device * instance generation in the driver. */ gpio_port_pins_t port_pin_mask; }; /** * This structure is common to all GPIO drivers and is expected to be the first * element in the driver's struct driver_data declaration. */ struct gpio_driver_data { /* Mask identifying pins that are configured as active low. * * Management of this mask is the responsibility of the * wrapper functions in this header. */ gpio_port_pins_t invert; }; struct gpio_callback; /** * @typedef gpio_callback_handler_t * @brief Define the application callback handler function signature * * @param port Device struct for the GPIO device. * @param cb Original struct gpio_callback owning this handler * @param pins Mask of pins that triggers the callback handler * * Note: cb pointer can be used to retrieve private data through * CONTAINER_OF() if original struct gpio_callback is stored in * another private structure. */ typedef void (*gpio_callback_handler_t)(struct device *port, struct gpio_callback *cb, gpio_port_pins_t pins); /** * @brief GPIO callback structure * * Used to register a callback in the driver instance callback list. * As many callbacks as needed can be added as long as each of them * are unique pointers of struct gpio_callback. * Beware such structure should not be allocated on stack. * * Note: To help setting it, see gpio_init_callback() below */ struct gpio_callback { /** This is meant to be used in the driver and the user should not * mess with it (see drivers/gpio/gpio_utils.h) */ sys_snode_t node; /** Actual callback function being called when relevant. */ gpio_callback_handler_t handler; /** A mask of pins the callback is interested in, if 0 the callback * will never be called. Such pin_mask can be modified whenever * necessary by the owner, and thus will affect the handler being * called or not. The selected pins must be configured to trigger * an interrupt. */ gpio_port_pins_t pin_mask; }; /** * @cond INTERNAL_HIDDEN * * For internal use only, skip these in public documentation. */ /* Used by driver api function pin_interrupt_configure, these are defined * in terms of the public flags so we can just mask and pass them * through to the driver api */ enum gpio_int_mode { GPIO_INT_MODE_DISABLED = GPIO_INT_DISABLE, GPIO_INT_MODE_LEVEL = GPIO_INT_ENABLE, GPIO_INT_MODE_EDGE = GPIO_INT_ENABLE | GPIO_INT_EDGE, }; enum gpio_int_trig { /* Trigger detection when input state is (or transitions to) * physical low. (Edge Failing or Active Low) */ GPIO_INT_TRIG_LOW = GPIO_INT_LOW_0, /* Trigger detection when input state is (or transitions to) * physical high. (Edge Rising or Active High) */ GPIO_INT_TRIG_HIGH = GPIO_INT_HIGH_1, /* Trigger detection on pin rising or falling edge. */ GPIO_INT_TRIG_BOTH = GPIO_INT_LOW_0 | GPIO_INT_HIGH_1, }; __subsystem struct gpio_driver_api { int (*pin_configure)(struct device *port, gpio_pin_t pin, gpio_flags_t flags); int (*port_get_raw)(struct device *port, gpio_port_value_t *value); int (*port_set_masked_raw)(struct device *port, gpio_port_pins_t mask, gpio_port_value_t value); int (*port_set_bits_raw)(struct device *port, gpio_port_pins_t pins); int (*port_clear_bits_raw)(struct device *port, gpio_port_pins_t pins); int (*port_toggle_bits)(struct device *port, gpio_port_pins_t pins); int (*pin_interrupt_configure)(struct device *port, gpio_pin_t pin, enum gpio_int_mode, enum gpio_int_trig); int (*manage_callback)(struct device *port, struct gpio_callback *cb, bool set); uint32_t (*get_pending_int)(struct device *dev); }; __syscall int gpio_config(struct device *port, gpio_pin_t pin, gpio_flags_t flags); static inline int z_impl_gpio_config(struct device *port, gpio_pin_t pin, gpio_flags_t flags) { const struct gpio_driver_api *api = (const struct gpio_driver_api *)port->driver_api; return api->pin_configure(port, pin, flags); } /** * @endcond */ /** * @brief Configure pin interrupt. * * @note This function can also be used to configure interrupts on pins * not controlled directly by the GPIO module. That is, pins which are * routed to other modules such as I2C, SPI, UART. * * @param port Pointer to device structure for the driver instance. * @param pin Pin number. * @param flags Interrupt configuration flags as defined by GPIO_INT_*. * * @retval 0 If successful. * @retval -ENOTSUP If any of the configuration options is not supported * (unless otherwise directed by flag documentation). * @retval -EINVAL Invalid argument. * @retval -EBUSY Interrupt line required to configure pin interrupt is * already in use. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ __syscall int gpio_pin_interrupt_configure(struct device *port, gpio_pin_t pin, gpio_flags_t flags); static inline int z_impl_gpio_pin_interrupt_configure(struct device *port, gpio_pin_t pin, gpio_flags_t flags) { const struct gpio_driver_api *api = (const struct gpio_driver_api *)port->driver_api; const struct gpio_driver_config *const cfg = (const struct gpio_driver_config *)port->config_info; const struct gpio_driver_data *const data = (const struct gpio_driver_data *)port->driver_data; enum gpio_int_trig trig; enum gpio_int_mode mode; __ASSERT_NO_MSG((flags & GPIO_INT_DEBOUNCE) == 0); __ASSERT((flags & (GPIO_INT_DISABLE | GPIO_INT_ENABLE)) != (GPIO_INT_DISABLE | GPIO_INT_ENABLE), "Cannot both enable and disable interrupts"); __ASSERT((flags & (GPIO_INT_DISABLE | GPIO_INT_ENABLE)) != 0U, "Must either enable or disable interrupts"); __ASSERT(((flags & GPIO_INT_ENABLE) == 0) || ((flags & GPIO_INT_EDGE) != 0) || ((flags & (GPIO_INT_LOW_0 | GPIO_INT_HIGH_1)) != (GPIO_INT_LOW_0 | GPIO_INT_HIGH_1)), "Only one of GPIO_INT_LOW_0, GPIO_INT_HIGH_1 can be " "enabled for a level interrupt."); __ASSERT(((flags & GPIO_INT_ENABLE) == 0) || ((flags & (GPIO_INT_LOW_0 | GPIO_INT_HIGH_1)) != 0), "At least one of GPIO_INT_LOW_0, GPIO_INT_HIGH_1 has to be " "enabled."); (void)cfg; __ASSERT((cfg->port_pin_mask & (gpio_port_pins_t)BIT(pin)) != 0U, "Unsupported pin"); if (((flags & GPIO_INT_LEVELS_LOGICAL) != 0) && ((data->invert & (gpio_port_pins_t)BIT(pin)) != 0)) { /* Invert signal bits */ flags ^= (GPIO_INT_LOW_0 | GPIO_INT_HIGH_1); } trig = (enum gpio_int_trig)(flags & (GPIO_INT_LOW_0 | GPIO_INT_HIGH_1)); mode = (enum gpio_int_mode)(flags & (GPIO_INT_EDGE | GPIO_INT_DISABLE | GPIO_INT_ENABLE)); return api->pin_interrupt_configure(port, pin, mode, trig); } /** * @brief Configure a single pin. * * @param port Pointer to device structure for the driver instance. * @param pin Pin number to configure. * @param flags Flags for pin configuration: 'GPIO input/output configuration * flags', 'GPIO drive strength flags', 'GPIO pin drive flags', 'GPIO pin * bias flags', GPIO_INT_DEBOUNCE. * * @retval 0 If successful. * @retval -ENOTSUP if any of the configuration options is not supported * (unless otherwise directed by flag documentation). * @retval -EINVAL Invalid argument. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ static inline int gpio_pin_configure(struct device *port, gpio_pin_t pin, gpio_flags_t flags) { const struct gpio_driver_api *api = (const struct gpio_driver_api *)port->driver_api; const struct gpio_driver_config *const cfg = (const struct gpio_driver_config *)port->config_info; struct gpio_driver_data *data = (struct gpio_driver_data *)port->driver_data; int ret; __ASSERT((flags & (GPIO_PULL_UP | GPIO_PULL_DOWN)) != (GPIO_PULL_UP | GPIO_PULL_DOWN), "Pull Up and Pull Down should not be enabled simultaneously"); __ASSERT((flags & GPIO_OUTPUT) != 0 || (flags & GPIO_SINGLE_ENDED) == 0, "Output needs to be enabled for 'Open Drain', 'Open Source' " "mode to be supported"); __ASSERT_NO_MSG((flags & GPIO_SINGLE_ENDED) != 0 || (flags & GPIO_LINE_OPEN_DRAIN) == 0); __ASSERT((flags & (GPIO_OUTPUT_INIT_LOW | GPIO_OUTPUT_INIT_HIGH)) == 0 || (flags & GPIO_OUTPUT) != 0, "Output needs to be enabled to be initialized low or high"); __ASSERT((flags & (GPIO_OUTPUT_INIT_LOW | GPIO_OUTPUT_INIT_HIGH)) != (GPIO_OUTPUT_INIT_LOW | GPIO_OUTPUT_INIT_HIGH), "Output cannot be initialized low and high"); if (((flags & GPIO_OUTPUT_INIT_LOGICAL) != 0) && ((flags & (GPIO_OUTPUT_INIT_LOW | GPIO_OUTPUT_INIT_HIGH)) != 0) && ((flags & GPIO_ACTIVE_LOW) != 0)) { flags ^= GPIO_OUTPUT_INIT_LOW | GPIO_OUTPUT_INIT_HIGH | GPIO_OUTPUT_INIT_LOGICAL; } (void)cfg; __ASSERT((cfg->port_pin_mask & (gpio_port_pins_t)BIT(pin)) != 0U, "Unsupported pin"); ret = gpio_config(port, pin, flags); if (ret != 0) { return ret; } if ((flags & GPIO_ACTIVE_LOW) != 0) { data->invert |= (gpio_port_pins_t)BIT(pin); } else { data->invert &= ~(gpio_port_pins_t)BIT(pin); } if (((flags & (GPIO_INT_DISABLE | GPIO_INT_ENABLE)) != 0U) && (api->pin_interrupt_configure != NULL)) { flags &= ~GPIO_INT_DEBOUNCE; ret = z_impl_gpio_pin_interrupt_configure(port, pin, flags); } return ret; } /** * @brief Get physical level of all input pins in a port. * * A low physical level on the pin will be interpreted as value 0. A high * physical level will be interpreted as value 1. This function ignores * GPIO_ACTIVE_LOW flag. * * Value of a pin with index n will be represented by bit n in the returned * port value. * * @param port Pointer to the device structure for the driver instance. * @param value Pointer to a variable where pin values will be stored. * * @retval 0 If successful. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ __syscall int gpio_port_get_raw(struct device *port, gpio_port_value_t *value); static inline int z_impl_gpio_port_get_raw(struct device *port, gpio_port_value_t *value) { const struct gpio_driver_api *api = (const struct gpio_driver_api *)port->driver_api; return api->port_get_raw(port, value); } /** * @brief Get logical level of all input pins in a port. * * Get logical level of an input pin taking into account GPIO_ACTIVE_LOW flag. * If pin is configured as Active High, a low physical level will be interpreted * as logical value 0. If pin is configured as Active Low, a low physical level * will be interpreted as logical value 1. * * Value of a pin with index n will be represented by bit n in the returned * port value. * * @param port Pointer to the device structure for the driver instance. * @param value Pointer to a variable where pin values will be stored. * * @retval 0 If successful. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ static inline int gpio_port_get(struct device *port, gpio_port_value_t *value) { const struct gpio_driver_data *const data = (const struct gpio_driver_data *)port->driver_data; int ret; ret = gpio_port_get_raw(port, value); if (ret == 0) { *value ^= data->invert; } return ret; } /** * @brief Set physical level of output pins in a port. * * Writing value 0 to the pin will set it to a low physical level. Writing * value 1 will set it to a high physical level. This function ignores * GPIO_ACTIVE_LOW flag. * * Pin with index n is represented by bit n in mask and value parameter. * * @param port Pointer to the device structure for the driver instance. * @param mask Mask indicating which pins will be modified. * @param value Value assigned to the output pins. * * @retval 0 If successful. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ __syscall int gpio_port_set_masked_raw(struct device *port, gpio_port_pins_t mask, gpio_port_value_t value); static inline int z_impl_gpio_port_set_masked_raw(struct device *port, gpio_port_pins_t mask, gpio_port_value_t value) { const struct gpio_driver_api *api = (const struct gpio_driver_api *)port->driver_api; return api->port_set_masked_raw(port, mask, value); } /** * @brief Set logical level of output pins in a port. * * Set logical level of an output pin taking into account GPIO_ACTIVE_LOW flag. * Value 0 sets the pin in logical 0 / inactive state. Value 1 sets the pin in * logical 1 / active state. If pin is configured as Active High, the default, * setting it in inactive state will force the pin to a low physical level. If * pin is configured as Active Low, setting it in inactive state will force the * pin to a high physical level. * * Pin with index n is represented by bit n in mask and value parameter. * * @param port Pointer to the device structure for the driver instance. * @param mask Mask indicating which pins will be modified. * @param value Value assigned to the output pins. * * @retval 0 If successful. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ static inline int gpio_port_set_masked(struct device *port, gpio_port_pins_t mask, gpio_port_value_t value) { const struct gpio_driver_data *const data = (const struct gpio_driver_data *)port->driver_data; value ^= data->invert; return gpio_port_set_masked_raw(port, mask, value); } /** * @brief Set physical level of selected output pins to high. * * @param port Pointer to the device structure for the driver instance. * @param pins Value indicating which pins will be modified. * * @retval 0 If successful. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ __syscall int gpio_port_set_bits_raw(struct device *port, gpio_port_pins_t pins); static inline int z_impl_gpio_port_set_bits_raw(struct device *port, gpio_port_pins_t pins) { const struct gpio_driver_api *api = (const struct gpio_driver_api *)port->driver_api; return api->port_set_bits_raw(port, pins); } /** * @brief Set logical level of selected output pins to active. * * @param port Pointer to the device structure for the driver instance. * @param pins Value indicating which pins will be modified. * * @retval 0 If successful. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ static inline int gpio_port_set_bits(struct device *port, gpio_port_pins_t pins) { return gpio_port_set_masked(port, pins, pins); } /** * @brief Set physical level of selected output pins to low. * * @param port Pointer to the device structure for the driver instance. * @param pins Value indicating which pins will be modified. * * @retval 0 If successful. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ __syscall int gpio_port_clear_bits_raw(struct device *port, gpio_port_pins_t pins); static inline int z_impl_gpio_port_clear_bits_raw(struct device *port, gpio_port_pins_t pins) { const struct gpio_driver_api *api = (const struct gpio_driver_api *)port->driver_api; return api->port_clear_bits_raw(port, pins); } /** * @brief Set logical level of selected output pins to inactive. * * @param port Pointer to the device structure for the driver instance. * @param pins Value indicating which pins will be modified. * * @retval 0 If successful. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ static inline int gpio_port_clear_bits(struct device *port, gpio_port_pins_t pins) { return gpio_port_set_masked(port, pins, 0); } /** * @brief Toggle level of selected output pins. * * @param port Pointer to the device structure for the driver instance. * @param pins Value indicating which pins will be modified. * * @retval 0 If successful. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ __syscall int gpio_port_toggle_bits(struct device *port, gpio_port_pins_t pins); static inline int z_impl_gpio_port_toggle_bits(struct device *port, gpio_port_pins_t pins) { const struct gpio_driver_api *api = (const struct gpio_driver_api *)port->driver_api; return api->port_toggle_bits(port, pins); } /** * @brief Set physical level of selected output pins. * * @param port Pointer to the device structure for the driver instance. * @param set_pins Value indicating which pins will be set to high. * @param clear_pins Value indicating which pins will be set to low. * * @retval 0 If successful. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ static inline int gpio_port_set_clr_bits_raw(struct device *port, gpio_port_pins_t set_pins, gpio_port_pins_t clear_pins) { __ASSERT((set_pins & clear_pins) == 0, "Set and Clear pins overlap"); return gpio_port_set_masked_raw(port, set_pins | clear_pins, set_pins); } /** * @brief Set logical level of selected output pins. * * @param port Pointer to the device structure for the driver instance. * @param set_pins Value indicating which pins will be set to active. * @param clear_pins Value indicating which pins will be set to inactive. * * @retval 0 If successful. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ static inline int gpio_port_set_clr_bits(struct device *port, gpio_port_pins_t set_pins, gpio_port_pins_t clear_pins) { __ASSERT((set_pins & clear_pins) == 0, "Set and Clear pins overlap"); return gpio_port_set_masked(port, set_pins | clear_pins, set_pins); } /** * @brief Get physical level of an input pin. * * A low physical level on the pin will be interpreted as value 0. A high * physical level will be interpreted as value 1. This function ignores * GPIO_ACTIVE_LOW flag. * * @param port Pointer to the device structure for the driver instance. * @param pin Pin number. * * @retval 1 If pin physical level is high. * @retval 0 If pin physical level is low. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ static inline int gpio_pin_get_raw(struct device *port, gpio_pin_t pin) { const struct gpio_driver_config *const cfg = (const struct gpio_driver_config *)port->config_info; gpio_port_value_t value; int ret; (void)cfg; __ASSERT((cfg->port_pin_mask & (gpio_port_pins_t)BIT(pin)) != 0U, "Unsupported pin"); ret = gpio_port_get_raw(port, &value); if (ret == 0) { ret = (value & (gpio_port_pins_t)BIT(pin)) != 0 ? 1 : 0; } return ret; } /** * @brief Get logical level of an input pin. * * Get logical level of an input pin taking into account GPIO_ACTIVE_LOW flag. * If pin is configured as Active High, a low physical level will be interpreted * as logical value 0. If pin is configured as Active Low, a low physical level * will be interpreted as logical value 1. * * Note: If pin is configured as Active High, the default, gpio_pin_get() * function is equivalent to gpio_pin_get_raw(). * * @param port Pointer to the device structure for the driver instance. * @param pin Pin number. * * @retval 1 If pin logical value is 1 / active. * @retval 0 If pin logical value is 0 / inactive. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ static inline int gpio_pin_get(struct device *port, gpio_pin_t pin) { const struct gpio_driver_config *const cfg = (const struct gpio_driver_config *)port->config_info; gpio_port_value_t value; int ret; (void)cfg; __ASSERT((cfg->port_pin_mask & (gpio_port_pins_t)BIT(pin)) != 0U, "Unsupported pin"); ret = gpio_port_get(port, &value); if (ret == 0) { ret = (value & (gpio_port_pins_t)BIT(pin)) != 0 ? 1 : 0; } return ret; } /** * @brief Set physical level of an output pin. * * Writing value 0 to the pin will set it to a low physical level. Writing any * value other than 0 will set it to a high physical level. This function * ignores GPIO_ACTIVE_LOW flag. * * @param port Pointer to the device structure for the driver instance. * @param pin Pin number. * @param value Value assigned to the pin. * * @retval 0 If successful. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ static inline int gpio_pin_set_raw(struct device *port, gpio_pin_t pin, int value) { const struct gpio_driver_config *const cfg = (const struct gpio_driver_config *)port->config_info; int ret; (void)cfg; __ASSERT((cfg->port_pin_mask & (gpio_port_pins_t)BIT(pin)) != 0U, "Unsupported pin"); if (value != 0) { ret = gpio_port_set_bits_raw(port, (gpio_port_pins_t)BIT(pin)); } else { ret = gpio_port_clear_bits_raw(port, (gpio_port_pins_t)BIT(pin)); } return ret; } /** * @brief Set logical level of an output pin. * * Set logical level of an output pin taking into account GPIO_ACTIVE_LOW flag. * Value 0 sets the pin in logical 0 / inactive state. Any value other than 0 * sets the pin in logical 1 / active state. If pin is configured as Active * High, the default, setting it in inactive state will force the pin to a low * physical level. If pin is configured as Active Low, setting it in inactive * state will force the pin to a high physical level. * * Note: If pin is configured as Active High, gpio_pin_set() function is * equivalent to gpio_pin_set_raw(). * * @param port Pointer to the device structure for the driver instance. * @param pin Pin number. * @param value Value assigned to the pin. * * @retval 0 If successful. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ static inline int gpio_pin_set(struct device *port, gpio_pin_t pin, int value) { const struct gpio_driver_config *const cfg = (const struct gpio_driver_config *)port->config_info; const struct gpio_driver_data *const data = (const struct gpio_driver_data *)port->driver_data; (void)cfg; __ASSERT((cfg->port_pin_mask & (gpio_port_pins_t)BIT(pin)) != 0U, "Unsupported pin"); if (data->invert & (gpio_port_pins_t)BIT(pin)) { value = (value != 0) ? 0 : 1; } return gpio_pin_set_raw(port, pin, value); } /** * @brief Toggle pin level. * * @param port Pointer to the device structure for the driver instance. * @param pin Pin number. * * @retval 0 If successful. * @retval -EIO I/O error when accessing an external GPIO chip. * @retval -EWOULDBLOCK if operation would block. */ static inline int gpio_pin_toggle(struct device *port, gpio_pin_t pin) { const struct gpio_driver_config *const cfg = (const struct gpio_driver_config *)port->config_info; (void)cfg; __ASSERT((cfg->port_pin_mask & (gpio_port_pins_t)BIT(pin)) != 0U, "Unsupported pin"); return gpio_port_toggle_bits(port, (gpio_port_pins_t)BIT(pin)); } /** * @brief Helper to initialize a struct gpio_callback properly * @param callback A valid Application's callback structure pointer. * @param handler A valid handler function pointer. * @param pin_mask A bit mask of relevant pins for the handler */ static inline void gpio_init_callback(struct gpio_callback *callback, gpio_callback_handler_t handler, gpio_port_pins_t pin_mask) { __ASSERT(callback, "Callback pointer should not be NULL"); __ASSERT(handler, "Callback handler pointer should not be NULL"); callback->handler = handler; callback->pin_mask = pin_mask; } /** * @brief Add an application callback. * @param port Pointer to the device structure for the driver instance. * @param callback A valid Application's callback structure pointer. * @return 0 if successful, negative errno code on failure. * * @note Callbacks may be added to the device from within a callback * handler invocation, but whether they are invoked for the current * GPIO event is not specified. * * Note: enables to add as many callback as needed on the same port. */ static inline int gpio_add_callback(struct device *port, struct gpio_callback *callback) { const struct gpio_driver_api *api = (const struct gpio_driver_api *)port->driver_api; if (api->manage_callback == NULL) { return -ENOTSUP; } return api->manage_callback(port, callback, true); } /** * @brief Remove an application callback. * @param port Pointer to the device structure for the driver instance. * @param callback A valid application's callback structure pointer. * @return 0 if successful, negative errno code on failure. * * @warning It is explicitly permitted, within a callback handler, to * remove the registration for the callback that is running, i.e. @p * callback. Attempts to remove other registrations on the same * device may result in undefined behavior, including failure to * invoke callbacks that remain registered and unintended invocation * of removed callbacks. * * Note: enables to remove as many callbacks as added through * gpio_add_callback(). */ static inline int gpio_remove_callback(struct device *port, struct gpio_callback *callback) { const struct gpio_driver_api *api = (const struct gpio_driver_api *)port->driver_api; if (api->manage_callback == NULL) { return -ENOTSUP; } return api->manage_callback(port, callback, false); } /** * @brief Function to get pending interrupts * * The purpose of this function is to return the interrupt * status register for the device. * This is especially useful when waking up from * low power states to check the wake up source. * * @param dev Pointer to the device structure for the driver instance. * * @retval status != 0 if at least one gpio interrupt is pending. * @retval 0 if no gpio interrupt is pending. */ __syscall int gpio_get_pending_int(struct device *dev); static inline int z_impl_gpio_get_pending_int(struct device *dev) { const struct gpio_driver_api *api = (const struct gpio_driver_api *)dev->driver_api; if (api->get_pending_int == NULL) { return -ENOTSUP; } return api->get_pending_int(dev); } /** * @} */ #ifdef __cplusplus } #endif #include #endif /* ZEPHYR_INCLUDE_DRIVERS_GPIO_H_ */