GPIO RTOS Driver

This driver can be used to operate GPIO ports on xcore in an RTOS application.

Initialization API

The following structures and functions are used to initialize and start a GPIO driver instance.

enum rtos_gpio_port_id_t

Enumerator type representing each available GPIO port.

To be used with the RTOS GPIO driver functions.

Values:

enumerator rtos_gpio_port_none
enumerator rtos_gpio_port_1A
enumerator rtos_gpio_port_1B
enumerator rtos_gpio_port_1C
enumerator rtos_gpio_port_1D
enumerator rtos_gpio_port_1E
enumerator rtos_gpio_port_1F
enumerator rtos_gpio_port_1G
enumerator rtos_gpio_port_1H
enumerator rtos_gpio_port_1I
enumerator rtos_gpio_port_1J
enumerator rtos_gpio_port_1K
enumerator rtos_gpio_port_1L
enumerator rtos_gpio_port_1M
enumerator rtos_gpio_port_1N
enumerator rtos_gpio_port_1O
enumerator rtos_gpio_port_1P
enumerator rtos_gpio_port_4A
enumerator rtos_gpio_port_4B
enumerator rtos_gpio_port_4C
enumerator rtos_gpio_port_4D
enumerator rtos_gpio_port_4E
enumerator rtos_gpio_port_4F
enumerator rtos_gpio_port_8A
enumerator rtos_gpio_port_8B
enumerator rtos_gpio_port_8C
enumerator rtos_gpio_port_8D
enumerator rtos_gpio_port_16A
enumerator rtos_gpio_port_16B
enumerator rtos_gpio_port_16C
enumerator rtos_gpio_port_16D
enumerator rtos_gpio_port_32A
enumerator rtos_gpio_port_32B
enumerator RTOS_GPIO_TOTAL_PORT_CNT

Total number of I/O ports

typedef struct rtos_gpio_struct rtos_gpio_t

Typedef to the RTOS GPIO driver instance struct.

typedef void (*rtos_gpio_isr_cb_t)(rtos_gpio_t *ctx, void *app_data, rtos_gpio_port_id_t port_id, uint32_t value)

Function pointer type for application provided RTOS GPIO interrupt callback functions.

These callback functions are called when there is a GPIO port interrupt.

Note

this is the latched value that triggered the interrupt, not the current value.

Parameters

  • ctx – A pointer to the associated GPIO driver instance.

  • app_data – A pointer to application specific data provided by the application. Used to share data between this callback function and the application.

  • port_id – The GPIO port that triggered the interrupt.

  • value – The value on the GPIO port that caused the interrupt.

inline rtos_gpio_port_id_t rtos_gpio_port(port_t p)

Helper function to convert an xcore I/O port resource ID to an RTOS GPIO driver port ID.

Parameters

p – An xcore I/O port resource ID.

Returns

the equivalent RTOS GPIO driver port ID.

void rtos_gpio_start(rtos_gpio_t *ctx)

Starts an RTOS GPIO driver instance. This must only be called by the tile that owns the driver instance. It may be called either before or after starting the RTOS, but must be called before any of the core GPIO driver functions are called with this instance.

rtos_gpio_init() must be called on this GPIO driver instance prior to calling this.

Parameters

ctx – A pointer to the GPIO driver instance to start.

void rtos_gpio_init(rtos_gpio_t *ctx)

Initializes an RTOS GPIO driver instance. There should only be one per tile. This instance represents all the GPIO ports owned by the calling tile. This must only be called by the tile that owns the driver instance. It may be called either before or after starting the RTOS, but must be called before calling rtos_gpio_start() or any of the core GPIO driver functions with this instance.

Parameters

ctx – A pointer to the GPIO driver instance to initialize.

RTOS_GPIO_ISR_CALLBACK_ATTR

This attribute must be specified on all RTOS GPIO interrupt callback functions provided by the application.

struct rtos_gpio_isr_info_t
#include <rtos_gpio.h>

Struct to hold interrupt state data for GPIO ports.

The members in this struct should not be accessed directly.

struct rtos_gpio_struct
#include <rtos_gpio.h>

Struct representing an RTOS GPIO driver instance.

The members in this struct should not be accessed directly.

Core API

The following functions are the core GPIO driver functions that are used after it has been initialized and started.

inline void rtos_gpio_port_enable(rtos_gpio_t *ctx, rtos_gpio_port_id_t port_id)

Enables a GPIO port. This must be called on a port before using it with any other GPIO driver function.

Parameters

  • ctx – A pointer to the GPIO driver instance to use.

  • port_id – The GPIO port to enable.

inline uint32_t rtos_gpio_port_in(rtos_gpio_t *ctx, rtos_gpio_port_id_t port_id)

Inputs the value present on a GPIO port’s pins.

Parameters

  • ctx – A pointer to the GPIO driver instance to use.

  • port_id – The GPIO port to read from.

Returns

the value on the port’s pins.

inline void rtos_gpio_port_out(rtos_gpio_t *ctx, rtos_gpio_port_id_t port_id, uint32_t value)

Outputs a value to a GPIO port’s pins.

Parameters

  • ctx – A pointer to the GPIO driver instance to use.

  • port_id – The GPIO port to write to.

  • value – The value to write to the GPIO port.

inline void rtos_gpio_isr_callback_set(rtos_gpio_t *ctx, rtos_gpio_port_id_t port_id, rtos_gpio_isr_cb_t cb, void *app_data)

Sets the application callback function to be called when there is an interrupt on a GPIO port.

This must be called prior to enabling interrupts on port_id. It is also safe to be called while interrupts are enabled on it.

Parameters

  • ctx – A pointer to the GPIO driver instance to use.

  • port_id – Interrupts triggered by this port will call the application callback function cb.

  • cb – The application callback function to call when there is an interrupt triggered by the port port_id.

  • app_data – A pointer to application specific data to pass to the application callback function cb.

inline void rtos_gpio_interrupt_enable(rtos_gpio_t *ctx, rtos_gpio_port_id_t port_id)

Enables interrupts on a GPIO port. Interrupts are triggered whenever the value on the port changes.

Parameters

  • ctx – A pointer to the GPIO driver instance to use.

  • port_id – The GPIO port to enable interrupts on.

inline void rtos_gpio_interrupt_disable(rtos_gpio_t *ctx, rtos_gpio_port_id_t port_id)

Disables interrupts on a GPIO port.

Parameters

  • ctx – A pointer to the GPIO driver instance to use.

  • port_id – The GPIO port to disable interrupts on.

inline void rtos_gpio_port_drive(rtos_gpio_t *ctx, rtos_gpio_port_id_t port_id)

Configures a port in drive mode. Output values will be driven on the pins. This is the default drive state of a port. This has the side effect of disabling the port’s internal pull-up and pull down resistors.

Parameters

  • ctx – A pointer to the GPIO driver instance to use.

  • port_id – The GPIO port to set to drive mode.

inline void rtos_gpio_port_drive_low(rtos_gpio_t *ctx, rtos_gpio_port_id_t port_id)

Configures a port in drive low mode. When the output value is 0 the pin is driven low, otherwise no value is driven. This has the side effect of enabled the port’s internal pull-up resistor.

Parameters

  • ctx – A pointer to the GPIO driver instance to use.

  • port_id – The GPIO port to set to drive mode low.

inline void rtos_gpio_port_drive_high(rtos_gpio_t *ctx, rtos_gpio_port_id_t port_id)

Configures a port in drive high mode. When the output value is 1 the pin is driven high, otherwise no value is driven. This has the side effect of enabled the port’s internal pull-down resistor.

Parameters

  • ctx – A pointer to the GPIO driver instance to use.

  • port_id – The GPIO port to set to drive mode high.

inline void rtos_gpio_port_pull_none(rtos_gpio_t *ctx, rtos_gpio_port_id_t port_id)

Disables the port’s internal pull-up and pull down resistors.

Parameters

  • ctx – A pointer to the GPIO driver instance to use.

  • port_id – The GPIO port to set to pull none mode.

inline void rtos_gpio_port_pull_up(rtos_gpio_t *ctx, rtos_gpio_port_id_t port_id)

Enables the port’s internal pull-up resistor.

Parameters

  • ctx – A pointer to the GPIO driver instance to use.

  • port_id – The GPIO port to set to pull up mode.

inline void rtos_gpio_port_pull_down(rtos_gpio_t *ctx, rtos_gpio_port_id_t port_id)

Enables the port’s internal pull-down resistor.

Parameters

  • ctx – A pointer to the GPIO driver instance to use.

  • port_id – The GPIO port to set to pull down mode.

inline void rtos_gpio_write_control_word(rtos_gpio_t *ctx, rtos_gpio_port_id_t port_id, uint32_t value)

Configures the port control word value

Parameters

  • ctx – A pointer to the GPIO driver instance to use.

  • port_id – The GPIO port to modify

  • value – The value to set the control word to

RPC Initialization API

The following functions may be used to share a GPIO driver instance with other xcore tiles. Tiles that the driver instance is shared with may call any of the core functions listed above.

void rtos_gpio_rpc_client_init(rtos_gpio_t *gpio_ctx, rtos_driver_rpc_t *rpc_config, rtos_intertile_t *host_intertile_ctx)

Initializes an RTOS GPIO driver instance on a client tile. This allows a tile that does not own the actual driver instance to use a driver instance on another tile. This will be called instead of rtos_gpio_init(). The host tile that owns the actual instance must simultaneously call rtos_gpio_rpc_host_init().

Parameters

  • gpio_ctx – A pointer to the GPIO driver instance to initialize.

  • rpc_config – A pointer to an RPC config struct. This must have the same scope as gpio_ctx.

  • host_intertile_ctx – A pointer to the intertile driver instance to use for performing the communication between the client and host tiles. This must have the same scope as gpio_ctx.

void rtos_gpio_rpc_host_init(rtos_gpio_t *gpio_ctx, rtos_driver_rpc_t *rpc_config, rtos_intertile_t *client_intertile_ctx[], size_t remote_client_count)

Performs additional initialization on a GPIO driver instance to allow client tiles to use the GPIO driver instance. Each client tile that will use this instance must simultaneously call rtos_gpio_rpc_client_init().

Parameters

  • gpio_ctx – A pointer to the GPIO driver instance to share with clients.

  • rpc_config – A pointer to an RPC config struct. This must have the same scope as gpio_ctx.

  • client_intertile_ctx – An array of pointers to the intertile driver instances to use for performing the communication between the host tile and each client tile. This must have the same scope as gpio_ctx.

  • remote_client_count – The number of client tiles to share this driver instance with.

void rtos_gpio_rpc_config(rtos_gpio_t *gpio_ctx, unsigned intertile_port, unsigned host_task_priority)

Configures the RPC for a GPIO driver instance. This must be called by both the host tile and all client tiles.

On the client tiles this must be called after calling rtos_gpio_rpc_client_init(). After calling this, the client tile may immediately begin to call the core GPIO functions on this driver instance. It does not need to wait for the host to call rtos_gpio_start().

On the host tile this must be called both after calling rtos_gpio_rpc_host_init() and before calling rtos_gpio_start().

Parameters

  • gpio_ctx – A pointer to the GPIO driver instance to configure the RPC for.

  • intertile_port – The port number on the intertile channel to use for transferring the RPC requests and responses for this driver instance. This port must not be shared by any other functions. The port must be the same for the host and all its clients.

  • host_task_priority – The priority to use for the task on the host tile that handles RPC requests from the clients.