From e5ed5c6517506585497e1248d3457df818e42aca Mon Sep 17 00:00:00 2001 From: Peter Bigot Date: Tue, 17 Sep 2019 08:42:29 -0500 Subject: [PATCH 1/2] gpio: put back deprecation comments The comments identifying replacement API were inadvertently removed along with the flag that triggers deprecation warnings. Signed-off-by: Peter Bigot --- include/drivers/gpio.h | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/include/drivers/gpio.h b/include/drivers/gpio.h index cc8297fbbda8a..dfaa8f9de2216 100644 --- a/include/drivers/gpio.h +++ b/include/drivers/gpio.h @@ -1055,6 +1055,8 @@ static inline int gpio_pin_toggle(struct device *port, unsigned int pin) * @param pin Pin number where the data is written. * @param value Value set on the pin. * @return 0 if successful, negative errno code on failure. + * + * @deprecated Replace with gpio_pin_set_raw() or gpio_pin_set(). */ static inline int gpio_pin_write(struct device *port, u32_t pin, u32_t value) @@ -1071,6 +1073,8 @@ static inline int gpio_pin_write(struct device *port, u32_t pin, * @param pin Pin number where data is read. * @param value Integer pointer to receive the data values from the pin. * @return 0 if successful, negative errno code on failure. + * + * @deprecated Replace with gpio_pin_get_raw() or gpio_pin_get(). */ static inline int gpio_pin_read(struct device *port, u32_t pin, u32_t *value) @@ -1158,6 +1162,9 @@ static inline int gpio_remove_callback(struct device *port, * Note: Depending on the driver implementation, this function will enable * the pin to trigger an interruption. So as a semantic detail, if no * callback is registered, of course none will be called. + * + * @deprecated Replace with ``gpio_pin_interrupt_configure()`` with + * ``GPIO_INT_ENABLE`` along with other interrupt configuration flags. */ static inline int gpio_pin_enable_callback(struct device *port, u32_t pin) { @@ -1169,6 +1176,9 @@ static inline int gpio_pin_enable_callback(struct device *port, u32_t pin) * @param port Pointer to the device structure for the driver instance. * @param pin Pin number where the callback function is disabled. * @return 0 if successful, negative errno code on failure. + * + * @deprecated Replace with ``gpio_pin_interrupt_configure()`` with + * ``GPIO_INT_DISABLE``. */ static inline int gpio_pin_disable_callback(struct device *port, u32_t pin) { From dc20b2b3c54fc7d4f773dce214e1ce710f86b9b5 Mon Sep 17 00:00:00 2001 From: Peter Bigot Date: Tue, 17 Sep 2019 09:09:41 -0500 Subject: [PATCH 2/2] gpio: add error return when blocking might occur External GPIO drivers may not be supported from interrupt context because they involve blocking bus transactions. Describe the return value for this situation, and add the I/O error to operations where it was missing. Signed-off-by: Peter Bigot --- include/drivers/gpio.h | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/include/drivers/gpio.h b/include/drivers/gpio.h index dfaa8f9de2216..8557b384feaf5 100644 --- a/include/drivers/gpio.h +++ b/include/drivers/gpio.h @@ -584,6 +584,8 @@ static inline int z_impl_gpio_disable_callback(struct device *port, * @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, unsigned int pin, unsigned int flags); @@ -629,6 +631,8 @@ static inline int z_impl_gpio_pin_interrupt_configure(struct device *port, * @retval 0 If successful. * @retval -ENOTSUP if any of the configuration options is not supported. * @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, u32_t pin, unsigned int flags) @@ -679,6 +683,7 @@ static inline int gpio_pin_configure(struct device *port, u32_t pin, * * @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); @@ -707,6 +712,7 @@ static inline int z_impl_gpio_port_get_raw(struct device *port, * * @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) { @@ -737,6 +743,7 @@ static inline int gpio_port_get(struct device *port, gpio_port_value_t *value) * * @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); @@ -768,6 +775,7 @@ static inline int z_impl_gpio_port_set_masked_raw(struct device *port, * * @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) @@ -788,6 +796,7 @@ static inline int gpio_port_set_masked(struct device *port, * * @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); @@ -809,6 +818,7 @@ static inline int z_impl_gpio_port_set_bits_raw(struct device *port, * * @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) { @@ -823,6 +833,7 @@ static inline int gpio_port_set_bits(struct device *port, gpio_port_pins_t 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_clear_bits_raw(struct device *port, gpio_port_pins_t pins); @@ -844,6 +855,7 @@ static inline int z_impl_gpio_port_clear_bits_raw(struct device *port, * * @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) @@ -859,6 +871,7 @@ static inline int gpio_port_clear_bits(struct device *port, * * @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); @@ -880,6 +893,7 @@ static inline int z_impl_gpio_port_toggle_bits(struct device *port, * * @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) @@ -898,6 +912,7 @@ static inline int gpio_port_set_clr_bits_raw(struct device *port, * * @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) @@ -920,6 +935,7 @@ static inline int gpio_port_set_clr_bits(struct device *port, * @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, unsigned int pin) { @@ -953,6 +969,7 @@ static inline int gpio_pin_get_raw(struct device *port, unsigned int pin) * @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, unsigned int pin) { @@ -982,6 +999,7 @@ static inline int gpio_pin_get(struct device *port, unsigned int 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, unsigned int pin, int value) @@ -1018,6 +1036,7 @@ static inline int gpio_pin_set_raw(struct device *port, unsigned int 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, unsigned int pin, int value) { @@ -1041,6 +1060,7 @@ static inline int gpio_pin_set(struct device *port, unsigned int pin, int value) * * @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, unsigned int pin) {