RTEMS: bsps/shared/dev/gpio/gpio-support.c File Reference

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
Data Structures | Macros | Functions
gpio-support.c File Reference

RTEMS GPIO API implementation. More...

`#include <rtems/score/atomic.h>`
`#include <rtems/chain.h>`
`#include <bsp/irq-generic.h>`
`#include <bsp/gpio.h>`
`#include <assert.h>`
`#include <stdlib.h>`

## Data Structures
struct | rtems_gpio_group
| Object containing relevant information about a GPIO group. More...
struct | gpio_handler_node
| Object containing relevant information to a list of user-defined interrupt handlers. More...
struct | gpio_pin_interrupt_state
| Object containing relevant information of a pin's interrupt configuration/state. More...
struct | gpio_pin
| Object containing information on a GPIO pin. More...
struct | gpio_bank
| Object containing relevant information regarding a GPIO bank state. More...

## Macros
#define | MUTEX_ATTRIBUTES
| GPIO API mutex attributes.
#define | CREATE_LOCK(name, lock_id)
#define | ACQUIRE_LOCK(m)
#define | RELEASE_LOCK(m) assert ( rtems_semaphore_release(m) == RTEMS_SUCCESSFUL )
#define | BANK_NUMBER(pin_number) pin_number / BSP_GPIO_PINS_PER_BANK
#define | PIN_NUMBER(pin_number) pin_number % BSP_GPIO_PINS_PER_BANK

## Functions
rtems_status_code | rtems_gpio_initialize (void)
| Initializes the GPIO API.
rtems_gpio_group * | rtems_gpio_create_pin_group (void)
| Instantiates a GPIO pin group. To define the group.
rtems_status_code | rtems_gpio_define_pin_group (const rtems_gpio_group_definition *group_definition, rtems_gpio_group *group)
rtems_status_code | rtems_gpio_write_group (uint32_t data, rtems_gpio_group *group)
| Writes a value to the group's digital outputs. The pins order is as defined in the group definition.
uint32_t | rtems_gpio_read_group (rtems_gpio_group *group)
| Reads the value/level of the group's digital inputs. The pins order is as defined in the group definition.
rtems_status_code | rtems_gpio_group_bsp_specific_operation (rtems_gpio_group *group, void *arg)
| Performs a BSP specific operation on a group of pins. The pins order is as defined in the group definition.
rtems_status_code | rtems_gpio_multi_select (const rtems_gpio_pin_conf *pins, uint8_t pin_count)
rtems_status_code | rtems_gpio_request_configuration (const rtems_gpio_pin_conf *conf)
| Requests a GPIO pin configuration.
rtems_status_code | rtems_gpio_update_configuration (const rtems_gpio_pin_conf *conf)
| Updates the current configuration of a GPIO pin .
rtems_status_code | rtems_gpio_multi_set (uint32_t *pin_numbers, uint32_t pin_count)
| Sets multiple output GPIO pins with the logical high.
rtems_status_code | rtems_gpio_multi_clear (uint32_t *pin_numbers, uint32_t pin_count)
| Sets multiple output GPIO pins with the logical low.
uint32_t | rtems_gpio_multi_read (uint32_t *pin_numbers, uint32_t pin_count)
| Returns the value (level) of multiple GPIO input pins.
rtems_status_code | rtems_gpio_set (uint32_t pin_number)
| Sets an output GPIO pin with the logical high.
rtems_status_code | rtems_gpio_clear (uint32_t pin_number)
| Sets an output GPIO pin with the logical low.
int | rtems_gpio_get_value (uint32_t pin_number)
| Returns the value (level) of a GPIO input pin.
rtems_status_code | rtems_gpio_request_pin (uint32_t pin_number, rtems_gpio_function function, bool output_enabled, bool logic_invert, void *bsp_specific)
rtems_status_code | rtems_gpio_resistor_mode (uint32_t pin_number, rtems_gpio_pull_mode mode)
| Configures a single GPIO pin pull resistor.
rtems_status_code | rtems_gpio_release_pin (uint32_t pin_number)
| Releases a GPIO pin, making it available to be used again.
rtems_status_code | rtems_gpio_release_configuration (const rtems_gpio_pin_conf *conf)
| Releases a GPIO pin, making it available to be used again.
rtems_status_code | rtems_gpio_release_multiple_pins (const rtems_gpio_pin_conf *pins, uint32_t pin_count)
rtems_status_code | rtems_gpio_release_pin_group (rtems_gpio_group *group)
| Releases a GPIO pin group, making the pins used available to be repurposed.
rtems_status_code | rtems_gpio_debounce_switch (uint32_t pin_number, int ticks)
| Attaches a debouncing function to a given pin/switch. Debouncing is done by requiring a certain number of clock ticks to pass between interrupts. Any interrupt fired too close to the last will be ignored as it is probably the result of an involuntary switch/button bounce after being released.
rtems_status_code | rtems_gpio_interrupt_handler_install (uint32_t pin_number, rtems_gpio_irq_state(*handler)(void *arg), void *arg)
| Connects a new user-defined interrupt handler to a given pin.
rtems_status_code | rtems_gpio_enable_interrupt (uint32_t pin_number, rtems_gpio_interrupt interrupt, rtems_gpio_handler_flag flag, bool threaded_handling, rtems_gpio_irq_state(*handler)(void *arg), void *arg)
rtems_status_code | rtems_gpio_interrupt_handler_remove (uint32_t pin_number, rtems_gpio_irq_state(*handler)(void *arg), void *arg)
| Disconnects an user-defined interrupt handler from the given pin. If in the end there are no more user-defined handlers connected to the pin, interrupts are disabled on the given pin.
rtems_status_code | rtems_gpio_disable_interrupt (uint32_t pin_number)
| Stops interrupts from being generated on a given GPIO pin and removes the corresponding handler.

## Detailed Description

RTEMS GPIO API implementation.

## Macro Definition Documentation

## ◆ ACQUIRE_LOCK

#define ACQUIRE_LOCK | ( |  | m | ) |

Value:
assert ( rtems_semaphore_obtain(m, \
RTEMS_WAIT, \
RTEMS_NO_TIMEOUT \
) == RTEMS_SUCCESSFUL )
RTEMS_WAIT
#define RTEMS_WAIT
Definition: options.h:53
rtems_semaphore_obtain
rtems_status_code rtems_semaphore_obtain(rtems_id id, rtems_option option_set, rtems_interval timeout)
RTEMS Obtain Semaphore.
Definition: semobtain.c:51
RTEMS_SUCCESSFUL
@ RTEMS_SUCCESSFUL
Definition: status.h:47
RTEMS_NO_TIMEOUT
#define RTEMS_NO_TIMEOUT
Constant for indefinite wait.
Definition: rtems.h:174

## ◆ CREATE_LOCK

#define CREATE_LOCK | ( |  | name,
|  |  | lock_id
| ) |  |

Value:
rtems_semaphore_create( \
name, \
1, \
MUTEX_ATTRIBUTES, \
0, \
lock_id \
)
MUTEX_ATTRIBUTES
#define MUTEX_ATTRIBUTES
GPIO API mutex attributes.
Definition: gpio-support.c:27
rtems_semaphore_create
rtems_status_code rtems_semaphore_create(rtems_name name, uint32_t count, rtems_attribute attribute_set, rtems_task_priority priority_ceiling, rtems_id *id)
rtems_semaphore_create
Definition: semcreate.c:34

## ◆ MUTEX_ATTRIBUTES

#define MUTEX_ATTRIBUTES

Value:
( \
RTEMS_LOCAL \
| RTEMS_PRIORITY \
| RTEMS_BINARY_SEMAPHORE \
| RTEMS_INHERIT_PRIORITY \
| RTEMS_NO_PRIORITY_CEILING \
)
RTEMS_LOCAL
#define RTEMS_LOCAL
Definition: attr.h:50
RTEMS_INHERIT_PRIORITY
#define RTEMS_INHERIT_PRIORITY
Definition: attr.h:123
RTEMS_BINARY_SEMAPHORE
#define RTEMS_BINARY_SEMAPHORE
Definition: attr.h:103
RTEMS_PRIORITY
#define RTEMS_PRIORITY
Definition: attr.h:67
RTEMS_NO_PRIORITY_CEILING
#define RTEMS_NO_PRIORITY_CEILING
Definition: attr.h:129

GPIO API mutex attributes.

## Function Documentation

## ◆ rtems_gpio_clear()

rtems_status_code rtems_gpio_clear | ( | uint32_t | pin_number | ) |

Sets an output GPIO pin with the logical low.

Parameters

  [in] | pin_number | GPIO pin number.

Return values

  RTEMS_SUCCESSFUL | Pin was cleared successfully.
  RTEMS_INVALID_ID | Pin number is invalid.
  RTEMS_NOT_CONFIGURED | The received pin is not configured as a digital output.
  RTEMS_UNSATISFIED | Could not clear the GPIO pin.

## ◆ rtems_gpio_create_pin_group()

rtems_gpio_group * rtems_gpio_create_pin_group | ( | void |  | ) |

Instantiates a GPIO pin group. To define the group.

See also
  rtems_gpio_define_pin_group().

Return values

  rtems_gpio_group | pointer.

## ◆ rtems_gpio_debounce_switch()

rtems_status_code rtems_gpio_debounce_switch | ( | uint32_t | pin_number,
|  | int | ticks
| ) |  |

Attaches a debouncing function to a given pin/switch. Debouncing is done by requiring a certain number of clock ticks to pass between interrupts. Any interrupt fired too close to the last will be ignored as it is probably the result of an involuntary switch/button bounce after being released.

Parameters

  [in] | pin_number | GPIO pin number.
  [in] | ticks | Minimum number of clock ticks that must pass between interrupts so it can be considered a legitimate interrupt.

Return values

  RTEMS_SUCCESSFUL | Debounce function successfully attached to the pin.
  RTEMS_INVALID_ID | Pin number is invalid.
  RTEMS_NOT_CONFIGURED | The current pin is not configured as a digital input, hence it can not be connected to a switch, or interrupts are not enabled for this pin.

## ◆ rtems_gpio_disable_interrupt()

rtems_status_code rtems_gpio_disable_interrupt | ( | uint32_t | pin_number | ) |

Stops interrupts from being generated on a given GPIO pin and removes the corresponding handler.

Parameters

  [in] | pin_number | GPIO pin number.

Return values

  RTEMS_SUCCESSFUL | Interrupt successfully disabled for this pin.
  RTEMS_INVALID_ID | Pin number is invalid.
  RTEMS_NOT_CONFIGURED | Pin has no active interrupts.
  RTEMS_UNSATISFIED | Could not remove the current interrupt handler, could not recognize the current active interrupt on this pin or could not disable interrupts on this pin.

## ◆ rtems_gpio_get_value()

int rtems_gpio_get_value | ( | uint32_t | pin_number | ) |

Returns the value (level) of a GPIO input pin.

Parameters

  [in] | pin_number | GPIO pin number.

Return values

  The | function returns 0 or 1 depending on the pin current logical value.
  -1 | Pin number is invalid, or not a digital input pin.

## ◆ rtems_gpio_group_bsp_specific_operation()

rtems_status_code rtems_gpio_group_bsp_specific_operation | ( | rtems_gpio_group * | group,
|  | void * | arg
| ) |  |

Performs a BSP specific operation on a group of pins. The pins order is as defined in the group definition.

Parameters

  [in] | group | Reference to the group.
  [in] | arg | Pointer to a BSP defined structure with BSP-specific data. This field is handled by the BSP.

Return values

  RTEMS_SUCCESSFUL | Operation completed with success.
  RTEMS_NOT_DEFINED | Group has no BSP specific pins, or the BSP does not support BSP specific operations for groups.
  RTEMS_UNSATISFIED | Could not operate on at least one of the pins.

## ◆ rtems_gpio_initialize()

rtems_status_code rtems_gpio_initialize | ( | void |  | ) |

Initializes the GPIO API.

Return values

  RTEMS_SUCCESSFUL | API successfully initialized.
  * |

See also
  rtems_semaphore_create().

## ◆ rtems_gpio_interrupt_handler_install()

rtems_status_code rtems_gpio_interrupt_handler_install | ( | uint32_t | pin_number,
|  | rtems_gpio_irq_state(*)(void *arg) | handler,
|  | void * | arg
| ) |  |

Connects a new user-defined interrupt handler to a given pin.

Parameters

  [in] | pin_number | GPIO pin number.
  [in] | handler | Pointer to a function that will be called every time the enabled interrupt for the given pin is generated. This function must return information about its handled/unhandled state.
  [in] | arg | Void pointer to the arguments of the user-defined handler.

Return values

  RTEMS_SUCCESSFUL | Handler successfully connected to this pin.
  RTEMS_NO_MEMORY | Could not connect more user-defined handlers to the given pin.
  RTEMS_NOT_CONFIGURED | The given pin has no interrupt configured.
  RTEMS_INVALID_ID | Pin number is invalid.
  RTEMS_TOO_MANY | The pin's current handler is set as unique.
  RTEMS_RESOURCE_IN_USE | The current user-defined handler for this pin is unique.

## ◆ rtems_gpio_interrupt_handler_remove()

rtems_status_code rtems_gpio_interrupt_handler_remove | ( | uint32_t | pin_number,
|  | rtems_gpio_irq_state(*)(void *arg) | handler,
|  | void * | arg
| ) |  |

Disconnects an user-defined interrupt handler from the given pin. If in the end there are no more user-defined handlers connected to the pin, interrupts are disabled on the given pin.

Parameters

  [in] | pin_number | GPIO pin number.
  [in] | handler | Pointer to the user-defined handler
  [in] | arg | Void pointer to the arguments of the user-defined handler.

Return values

  RTEMS_SUCCESSFUL | Handler successfully disconnected from this pin.
  RTEMS_INVALID_ID | Pin number is invalid.
  RTEMS_NOT_CONFIGURED | Pin has no active interrupts.
  * |

See also
  rtems_gpio_disable_interrupt()

## ◆ rtems_gpio_multi_clear()

rtems_status_code rtems_gpio_multi_clear | ( | uint32_t * | pin_numbers,
|  | uint32_t | pin_count
| ) |  |

Sets multiple output GPIO pins with the logical low.

Parameters

  [in] | pin_numbers | Array with the GPIO pin numbers to clear.
  [in] | count | Number of GPIO pins to clear.

Return values

  RTEMS_SUCCESSFUL | All pins were cleared successfully.
  RTEMS_INVALID_ID | At least one pin number is invalid.
  RTEMS_NOT_CONFIGURED | At least one of the received pins is not configured as a digital output.
  RTEMS_UNSATISFIED | Could not clear the GPIO pins.

## ◆ rtems_gpio_multi_read()

uint32_t rtems_gpio_multi_read | ( | uint32_t * | pin_numbers,
|  | uint32_t | pin_count
| ) |  |

Returns the value (level) of multiple GPIO input pins.

Parameters

  [in] | pin_numbers | Array with the GPIO pin numbers to read.
  [in] | count | Number of GPIO pins to read.

Return values

  Bitmask | with the values of the corresponding pins. 0 for logical low and 1 for logical high.
  GPIO_INPUT_ERROR | Could not read at least one pin level.

## ◆ rtems_gpio_multi_set()

rtems_status_code rtems_gpio_multi_set | ( | uint32_t * | pin_numbers,
|  | uint32_t | pin_count
| ) |  |

Sets multiple output GPIO pins with the logical high.

Parameters

  [in] | pin_numbers | Array with the GPIO pin numbers to set.
  [in] | count | Number of GPIO pins to set.

Return values

  RTEMS_SUCCESSFUL | All pins were set successfully.
  RTEMS_INVALID_ID | At least one pin number is invalid.
  RTEMS_NOT_CONFIGURED | At least one of the received pins is not configured as a digital output.
  RTEMS_UNSATISFIED | Could not set the GPIO pins.

## ◆ rtems_gpio_read_group()

uint32_t rtems_gpio_read_group | ( | rtems_gpio_group * | group | ) |

Reads the value/level of the group's digital inputs. The pins order is as defined in the group definition.

Parameters

  [in] | group | Reference to the group.

Return values

  The | function returns a 32-bit bitmask with the group's input pins current logical values.
  GPIO_INPUT_ERROR | Group has no input pins.

## ◆ rtems_gpio_release_configuration()

rtems_status_code rtems_gpio_release_configuration | ( | const rtems_gpio_pin_conf * | conf | ) |

Releases a GPIO pin, making it available to be used again.

Parameters

  [in] | conf | GPIO pin configuration to be released.

Return values

  RTEMS_SUCCESSFUL | Pin successfully disabled.
  RTEMS_UNSATISFIED | Pin configuration is NULL.
  * |

See also
  rtems_gpio_release_pin().

## ◆ rtems_gpio_release_pin()

rtems_status_code rtems_gpio_release_pin | ( | uint32_t | pin_number | ) |

Releases a GPIO pin, making it available to be used again.

Parameters

  [in] | pin_number | GPIO pin number.

Return values

  RTEMS_SUCCESSFUL | Pin successfully disabled.
  RTEMS_INVALID_ID | Pin number is invalid.
  * | Could not disable an active interrupt on this pin,

See also
  rtems_gpio_disable_interrupt().

## ◆ rtems_gpio_release_pin_group()

rtems_status_code rtems_gpio_release_pin_group | ( | rtems_gpio_group * | group | ) |

Releases a GPIO pin group, making the pins used available to be repurposed.

Parameters

  [in] | conf | GPIO pin configuration to be released.

Return values

  RTEMS_SUCCESSFUL | Pins successfully disabled.
  * |

See also
  rtems_gpio_release_pin(),
  rtems_semaphore_delete() or
  rtems_semaphore_flush().

## ◆ rtems_gpio_request_configuration()

rtems_status_code rtems_gpio_request_configuration | ( | const rtems_gpio_pin_conf * | conf | ) |

Requests a GPIO pin configuration.

Parameters

  [in] | conf | rtems_gpio_pin_conf structure filled with the pin information and desired configurations.

Return values

  RTEMS_SUCCESSFUL | Pin was configured successfully.
  RTEMS_UNSATISFIED | Could not satisfy the given configuration.

## ◆ rtems_gpio_resistor_mode()

rtems_status_code rtems_gpio_resistor_mode | ( | uint32_t | pin_number,
|  | rtems_gpio_pull_mode | mode
| ) |  |

Configures a single GPIO pin pull resistor.

Parameters

  [in] | pin_number | GPIO pin number.
  [in] | mode | The pull resistor mode.

Return values

  RTEMS_SUCCESSFUL | Pull resistor successfully configured.
  RTEMS_INVALID_ID | Pin number is invalid.
  RTEMS_UNSATISFIED | Could not set the pull mode.

## ◆ rtems_gpio_set()

rtems_status_code rtems_gpio_set | ( | uint32_t | pin_number | ) |

Sets an output GPIO pin with the logical high.

Parameters

  [in] | pin_number | GPIO pin number.

Return values

  RTEMS_SUCCESSFUL | Pin was set successfully.
  RTEMS_INVALID_ID | Pin number is invalid.
  RTEMS_NOT_CONFIGURED | The received pin is not configured as a digital output.
  RTEMS_UNSATISFIED | Could not set the GPIO pin.

## ◆ rtems_gpio_update_configuration()

rtems_status_code rtems_gpio_update_configuration | ( | const rtems_gpio_pin_conf * | conf | ) |

Updates the current configuration of a GPIO pin .

Parameters

  [in] | conf | rtems_gpio_pin_conf structure filled with the pin information and desired configurations.

Return values

  RTEMS_SUCCESSFUL | Pin configuration was updated successfully.
  RTEMS_INVALID_ID | Pin number is invalid.
  RTEMS_NOT_CONFIGURED | The pin is not being used.
  RTEMS_UNSATISFIED | Could not update the pin's configuration.

## ◆ rtems_gpio_write_group()

rtems_status_code rtems_gpio_write_group | ( | uint32_t | data,
|  | rtems_gpio_group * | group
| ) |  |

Writes a value to the group's digital outputs. The pins order is as defined in the group definition.

Parameters

  [in] | data | Data to write/send.
  [in] | group | Reference to the group.

Return values

  RTEMS_SUCCESSFUL | Data successfully written.
  RTEMS_NOT_DEFINED | Group has no output pins.
  RTEMS_UNSATISFIED | Could not operate on at least one of the pins.