UART Tx RTOS Driver#

This driver can be used to instantiate and control an UART Tx I/O interface on xCORE in an RTOS application.

UART Tx API#

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

typedef struct rtos_uart_tx_struct rtos_uart_tx_t#

Typedef to the RTOS UART tx driver instance struct.

inline void rtos_uart_tx_write(rtos_uart_tx_t *ctx, const uint8_t buf[], size_t n)#

Writes data to an initialized and started UART instance. Unlike the UART rx, an xcore logical core is not reserved. The UART transmission is a function call and the the function blocks until the stop bit of the last byte to be transmittted has completed. Interrupts are masked during this time to avoid stretching of the waveform. Consequently, the tx consumes cycles from the caller thread.

Parameters:

  • ctx – A pointer to the UART Tx driver instance to use.

  • buf – The buffer containing data to write.

  • n – The number of bytes to write.

void rtos_uart_tx_init(rtos_uart_tx_t *ctx, const port_t tx_port, const uint32_t baud_rate, const uint8_t num_data_bits, const uart_parity_t parity, const uint8_t stop_bits, hwtimer_t tmr)#

Initialises an RTOS UART tx 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 calling rtos_uart_tx_start() or any of the core UART tx driver functions with this instance.

Parameters:

  • ctx – A pointer to the UART tx driver instance to initialise.

  • tx_port – The port containing the transmit pin

  • baud_rate – The baud rate of the UART in bits per second.

  • num_data_bits – The number of data bits per frame sent.

  • parity – The type of parity used. See uart_parity_t above.

  • stop_bits – The number of stop bits asserted at the of the frame.

  • tmr – The resource id of the timer to be used by the UART tx.

void rtos_uart_tx_start(rtos_uart_tx_t *ctx)#

Starts an RTOS UART tx 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 UART tx driver functions are called with this instance.

rtos_uart_tx_init() must be called on this UART tx driver instance prior to calling this.

Parameters:

  • ctx – A pointer to the UART tx driver instance to start.

struct rtos_uart_tx_struct#
#include <rtos_uart_tx.h>

Struct representing an RTOS UART tx driver instance.

The members in this struct should not be accessed directly.

UART Tx RPC Initialization API#

The following functions may be used to share a UART Tx 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_uart_tx_rpc_client_init(rtos_uart_tx_t *uart_tx_ctx, rtos_driver_rpc_t *rpc_config, rtos_intertile_t *host_intertile_ctx)#

Initializes an RTOS UART tx 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_uart_tx_init(). The host tile that owns the actual instance must simultaneously call rtos_uart_tx_rpc_host_init().

Parameters:

  • uart_tx_ctx – A pointer to the UART tx driver instance to initialize.

  • rpc_config – A pointer to an RPC config struct. This must have the same scope as uart_tx_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 uart_tx_ctx.

void rtos_uart_tx_rpc_host_init(rtos_uart_tx_t *uart_tx_ctx, rtos_driver_rpc_t *rpc_config, rtos_intertile_t *client_intertile_ctx[], size_t remote_client_count)#

Performs additional initialization on an UART tx driver instance to allow client tiles to use the UART tx driver instance. Each client tile that will use this instance must simultaneously call rtos_uart_tx_rpc_client_init().

Parameters:

  • uart_tx_ctx – A pointer to the UART tx driver instance to share with clients.

  • rpc_config – A pointer to an RPC config struct. This must have the same scope as uart_tx_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 uart_tx_ctx.

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

void rtos_uart_tx_rpc_config(rtos_uart_tx_t *uart_tx_ctx, unsigned intertile_port, unsigned host_task_priority)#

Configures the RPC for an UART tx 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_uart_tx_rpc_client_init(). After calling this, the client tile may immediately begin to call the core UART tx functions on this driver instance. It does not need to wait for the host to call rtos_uart_tx_start().

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

Parameters:

  • uart_tx_ctx – A pointer to the UART tx 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.