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 )

◆ CREATE_LOCK

#define CREATE_LOCK	(	name,
		lock_id
	)

Value:

  rtems_semaphore_create(   \
  name,                                                      \
  1,                                                         \
  MUTEX_ATTRIBUTES,                                          \
  0,                                                         \
  lock_id                                                    \
)

◆ MUTEX_ATTRIBUTES

#define MUTEX_ATTRIBUTES

Value:

  (     \
  RTEMS_LOCAL                  \
  | RTEMS_PRIORITY             \
  | RTEMS_BINARY_SEMAPHORE     \
  | RTEMS_INHERIT_PRIORITY     \
  | RTEMS_NO_PRIORITY_CEILING  \
)

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.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ ACQUIRE_LOCK

◆ CREATE_LOCK

◆ MUTEX_ATTRIBUTES

Function Documentation

◆ rtems_gpio_clear()

◆ rtems_gpio_create_pin_group()

◆ rtems_gpio_debounce_switch()

◆ rtems_gpio_disable_interrupt()

◆ rtems_gpio_get_value()

◆ rtems_gpio_group_bsp_specific_operation()

◆ rtems_gpio_initialize()

◆ rtems_gpio_interrupt_handler_install()

◆ rtems_gpio_interrupt_handler_remove()

◆ rtems_gpio_multi_clear()

◆ rtems_gpio_multi_read()

◆ rtems_gpio_multi_set()

◆ rtems_gpio_read_group()

◆ rtems_gpio_release_configuration()

◆ rtems_gpio_release_pin()

◆ rtems_gpio_release_pin_group()

◆ rtems_gpio_request_configuration()

◆ rtems_gpio_resistor_mode()

◆ rtems_gpio_set()

◆ rtems_gpio_update_configuration()

◆ rtems_gpio_write_group()