Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[TOPIC-GPIO] miscellaneous API documentation updates #19252

Merged
merged 2 commits into from
Oct 1, 2019
Merged

[TOPIC-GPIO] miscellaneous API documentation updates #19252

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e5ed5c6
gpio: put back deprecation comments
pabigot Sep 17, 2019
dc20b2b
gpio: add error return when blocking might occur
pabigot Sep 17, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions include/drivers/gpio.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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);

Expand Down Expand Up @@ -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)
{
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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)
Expand All @@ -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);
Expand All @@ -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)
{
Expand All @@ -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);
Expand All @@ -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)
Expand All @@ -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);

Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -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)
{
Expand Down Expand Up @@ -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)
{
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
{
Expand All @@ -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)
{
Expand All @@ -1055,6 +1075,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)
Expand All @@ -1071,6 +1093,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)
Expand Down Expand Up @@ -1158,6 +1182,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)
{
Expand All @@ -1169,6 +1196,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)
{
Expand Down