UART

group UART

UART Universal Asynchronous Receiver Transmitter.

This API provides support for transferring data between an external UART device and the processor running this driver.

Typedefs

typedef struct pi_uart_conf pi_uart_conf_t

IMPLEM struct pi_cl_uart_req_s pi_cl_uart_req_t

UART cluster request structure.

CLUSTER SIDE FUNCTIONS

This structure is used by the runtime to manage a cluster remote copy with the UART. It must be instantiated once for each copy and must be kept alive until the copy is finished. It can be instantiated as a normal variable, for example as a global variable, a local one on the stack, or through a memory allocator.

Enums

enum pi_uart_stop_bits

Stop bits enum.

Values:

enumerator PI_UART_STOP_BITS_ONE = 0: One stop bit.

enumerator PI_UART_STOP_BITS_TWO = 1: Two stop bits.

enum pi_uart_parity_mode

Parity mode enum.

Values:

enumerator PI_UART_PARITY_DISABLE = 0: Disable parity mode.

enumerator PI_UART_PARITY_ENABLE = 1: Enable parity mode.

enum pi_uart_word_size

Bit length of each word.

Values:

enumerator PI_UART_WORD_SIZE_5_BITS = 0: 5 bits length.

enumerator PI_UART_WORD_SIZE_6_BITS = 1: 6 bits length.

enumerator PI_UART_WORD_SIZE_7_BITS = 2: 7 bits length.

enumerator PI_UART_WORD_SIZE_8_BITS = 3: 8 bits length.

enum pi_uart_clk_src

Clock source enum.

Values:

enumerator PI_UART_CLK_FROM_FLL = 0: Use FLL (Scaleble clock) as uart clk source.

enumerator PI_UART_CLK_FROM_REF_FAST = 1: Use Ref clock fast (static) as uart clk source.

enum pi_uart_ioctl_cmd

UART ioctl commands.

UART ioctl commands to configure, enable device.

Values:

enumerator PI_UART_IOCTL_CONF_SETUP = 0

Setup UART device.

Setup UART with given conf. The parameter for this command is a struct pi_uart_conf.

Param conf:: Pointer to struct pi_uart_conf.

enumerator PI_UART_IOCTL_ABORT_RX = 1

Abort RX transfers.

Disable RX channel, abort current RX transfert, and flush all pending transferts.

Note

This function disables reception channel after clearing UDMA channels. In order to send again data, the reception channel must re-enabled.

enumerator PI_UART_IOCTL_ABORT_TX = 2

Abort TX transfers.

Disable TX channel, abort current TX transfert, and flush all pending transferts.

Note

This function disables transmission channel after clearing UDMA channels. In order to send again data, the transmission channel must re-enabled.

enumerator PI_UART_IOCTL_ENABLE_RX = 3

Enable reception.

This command enables reception on UART device.

enumerator PI_UART_IOCTL_ENABLE_TX = 4

Enable transmission.

This command enables transmission on UART device.

enumerator PI_UART_IOCTL_ENABLE_FLOW_CONTROL = 5

Enable flow control.

This command enables flow control on UART device.

Note

On GAP8, flow control is emulated using a PWM device(Timer0, channel2) and two GPIOs(PI_GPIO_A1_PAD_9_B3, PI_GPIO_A0_PAD_8_A4).

Note

On GAP9 this will disable and re-enable TX and RX.

enumerator PI_UART_IOCTL_DISABLE_FLOW_CONTROL = 6

Disable flow control.

This command disables flow control on UART device.

enumerator PI_UART_IOCTL_FLUSH = 7

Flush UART TX.

This command will wait until all pending buffers are flushed outside

enumerator PI_UART_IOCTL_ATTACH_TIMEOUT_RX = 8

Attach UDMA timer.

This command attaches a UDMA timer channel to UDMA reception channel.

Param timeout_id:: UDMA timeout channel ID.

enumerator PI_UART_IOCTL_DETACH_TIMEOUT_RX = 9

Detach UDMA timer.

This command removes a UDMA timer channel attached to UDMA reception channel.

Param timeout_id:: UDMA timeout channel ID.

enumerator PI_UART_IOCTL_ATTACH_TIMEOUT_TX = 10

Attach UDMA timer.

This command attaches a UDMA timer channel to UDMA transmission channel.

Param timeout_id:: UDMA timeout channel ID.

enumerator PI_UART_IOCTL_DETACH_TIMEOUT_TX = 11

Detach UDMA timer.

This command removes a UDMA timer channel attached to UDMA transmission channel.

Param timeout_id:: UDMA timeout channel ID.

enumerator PI_UART_IOCTL_RESUME_TX = 12

Detach UDMA timer.

This command removes a UDMA timer channel attached to UDMA transmission channel.

Param timeout_id:: UDMA timeout channel ID.

enumerator PI_UART_IOCTL_RESUME_RX = 13

Detach UDMA timer.

This command removes a UDMA timer channel attached to UDMA transmission channel.

Param timeout_id:: UDMA timeout channel ID.

enumerator PI_UART_IOCTL_DEVICE_GET = 14

Get UART device from its id.

This command attachs the UART device of the given id to the given reference.

Param device:: Reference to attach the UART device.
Param id:: UART device ID.

enumerator PI_UART_IOCTL_CLK_SRC_SET = 15

Set the clock source of UART device.

This command set the clock source (FLL or Ref clk fast) of the UART interface BEWARE, please be careful when using this command:

Please make sure stop the uart transaction before using this command
Please make sure the ref clk fast is enabled before using this command
Please note that, FLL is a scaleble clock source, which may be changed by software at anytime.
FLL jitters may cause random uart transaction issue.

Param device:: Reference to attach the UART device.
Param CLK:: source: PI_UART_CLK_FROM_FLL = 0 PI_UART_CLK_FROM_REF_FAST = 1

enumerator PI_UART_IOCTL_CHIP_WAKEUP_UART_RX = 16

Set chip wake up on uart rx pad.

This command set the RX pad of the UART as the wake up source

Param device:: Referance to attach the UART device.
Param wakeup_pad:: RX pad used to wake up GAP.

enumerator PI_UART_IOCTL_RESET_RX = 17

Reset the uart rx channel.

This command reset the RX channel, and uart fifo

enum pi_uart_timeout_flags

Values:

enumerator PI_UART_TIMEOUT_FLAG_HW = 1: Use hw based timeout.

enumerator PI_UART_TIMEOUT_FLAG_SW = 2: Use SW based timeout.

enumerator PI_UART_TIMEOUT_FLAG_SW_HW = 3: Use SW based timeout + HW Use the same timeout_us.

Functions

void pi_uart_conf_init(struct pi_uart_conf *conf)

Initialize a UART configuration with default values.

This function can be called to get default values for all parameters before setting some of them. The structure containing the configuration must be kept alive until the uart device is opened.

Parameters:

conf – Pointer to the UART configuration.

int32_t pi_uart_open(pi_device_t *device)

Open a UART device.

This function must be called before the UART device can be used. It will do all the needed configuration to make it usable and initialize the handle used to refer to this opened device when calling other functions.

Note

This structure is allocated by the called and must be kept alive until the device is closed.

Parameters:

device – Pointer to device structure of the device to open.

Return values:

0 – If the operation is successfull.
ERRNO – An error code otherwise.

int32_t pi_uart_close(pi_device_t *device)

Close an opened UART device.

This function can be called to close an opened UART device once it is not needed anymore, in order to free all allocated resources. Once this function is called, the device is not accessible anymore and must be opened again before being used.

Parameters:

device – Pointer to device structure of the device to close.

int32_t pi_uart_ioctl(pi_device_t *device, uint32_t cmd, void *arg)

Dynamically change device configuration.

This function allows to send different commands to UART device. The commands are listed above, cf. enum pi_uart_ioctl_cmd.

Parameters:

device – Pointer to device descriptor of the UART device.
cmd – Ioctl command.
arg – Ioctl command args.

Return values:

-1 – If wrong ioctl command.
Value – Otherwise return value depending on ioctl command.

int32_t pi_uart_write_async(pi_device_t *device, void *buffer, uint32_t size, pi_evt_t *callback)

Write data to an UART asynchronously.

WRITE FUNCTIONS

This writes data to the specified UART asynchronously. An event must be specified in order to specify how the caller should be notified when the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – Pointer to device descriptor of the UART device.
buffer – Pointer to data buffer.
size – Size of data to copy in bytes.
callback – Event used to notify the end of transfer. See the documentation of pi_evt_t for more details.

Return values:

0 – If operation is successfull.
ERRNO – An error code otherwise.

int32_t pi_uart_write(pi_device_t *device, void *buffer, uint32_t size)

Write data to an UART.

This writes data to the specified UART. The caller is blocked until the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – Pointer to device descriptor of the UART device.
buffer – Pointer to data buffer.
size – Size of data to copy in bytes.

Return values:

0 – If operation is successfull.
ERRNO – An error code otherwise.

int32_t pi_uart_write_byte_async(pi_device_t *device, uint8_t *byte, pi_evt_t *callback)

Write a byte to an UART asynchronously.

This writes a byte to the specified UART asynchronously. An event must be specified in order to specify how the caller should be notified when the transfer is finished.

Parameters:

device – Pointer to device descriptor of the UART device.
byte – Pointer to data buffer.
callback – Event used to notify the end of transfer. See the documentation of pi_evt_t for more details.

Return values:

0 – If operation is successfull.
ERRNO – An error code otherwise.

int32_t pi_uart_write_byte(pi_device_t *device, uint8_t *byte)

Write a byte to an UART.

This writes a byte to the specified UART. The caller is blocked until the transfer is finished.

Parameters:

device – Pointer to device descriptor of the UART device.
byte – Pointer to data buffer.

Return values:

0 – If operation is successfull.
ERRNO – An error code otherwise.

int32_t pi_uart_write_timeout_async(pi_device_t *device, void *buffer, uint32_t size, uint32_t timeout_us, pi_evt_t *timeout_evt, pi_uart_timeout_flags flags, void *args)

Write data from an UART asynchronously, with timeout.

This function is the same as pi_uart_write_async(), with timeout feat enabled. This timeout value is used to abort/cancel a transfer when timeout is reached.

The timeout can be used to advertise the user that no byte has been written, however it does NOT guaranty the data incoming once timeout has occured. The user should abort and restart, or deals with it.

Note

To use this feature, a UDMA timeout channel must be allocated before a call to this function :

pi_udma_timeout_alloc()
pi_uart_ioctl() //PI_UART_IOCTL_ATTACH_TIMEOUT_RX
pi_uart_write_timeout()

Note

Once timeout_evt is pushed, use pi_evt_status_get() to know if the timeout has been reached (status == PI_ERR_TIMEOUT).

Warning

* timeout_evt MUST be initialized! Holds the timeout status and works as the callback of the function

Once timeout_evt is pushed, if you use the software timeout, please CALL pi_evt_cancel_delayed_us() with the sw_timeout_evt that you have created!

Parameters:

device – Pointer to device descriptor of the UART device.
buffer – Pointer to data buffer.
size – Size of data to copy in bytes.
timeout_us – Timeout value in us.
timeout_evt – Event which will be used to hold the timeout status, and for callback.
flags – Flags to configure actual timeout.
args – When using software timeout, arguments for it. See uart_sw_timeout_arg_t structure.

Return values:

0 – If operation is successfull.
ERRNO – An error code otherwise.

Returns:

Opeartion status.

int32_t pi_uart_write_timeout(pi_device_t *device, void *buffer, uint32_t size, uint32_t timeout_us, pi_evt_t *timeout_evt, pi_uart_timeout_flags flags)

Write data to an UART synchronously, with timeout.

This function is the same as pi_uart_write(), with timeout feat enabled. This timeout value is used to abort/cancel a transfer when timeout is reached.

Note

To use this feature, a UDMA timeout channel must be allocated before a call to this functions :

pi_udma_timeout_alloc()
pi_uart_ioctl() //PI_UART_IOCTL_ATTACH_TIMEOUT_TX
pi_uart_write_timeout()

Warning

timeout_evt MUST NOT be initialized

Parameters:

device – Pointer to device descriptor of the UART device.
buffer – Pointer to data buffer.
size – Size of data to copy in bytes.
timeout_us – Timeout value in us.
timeout_evt – Event which will be used to hold the timeout status.
flags – Flags to specify the timeout type.

Return values:

0 – If operation is successfull.
ERRNO – An error code otherwise.

int32_t pi_uart_read_async(pi_device_t *device, void *buffer, uint32_t size, pi_evt_t *callback)

Read data from an UART asynchronously.

READ FUNCTIONS

This reads data from the specified UART asynchronously. An event must be specified in order to specify how the caller should be notified when the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – Pointer to device descriptor of the UART device.
buffer – Pointer to data buffer.
size – Size of data to copy in bytes.
callback – Event used to notify the end of transfer. See the documentation of pi_evt_t for more details.

Return values:

0 – If operation is successfull.
ERRNO – An error code otherwise.

int32_t pi_uart_read(pi_device_t *device, void *buffer, uint32_t size)

Read data from an UART.

This reads data from the specified UART. The caller is blocked until the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

device – Pointer to device descriptor of the UART device.
buffer – Pointer to data buffer.
size – Size of data to copy in bytes.

Return values:

0 – If operation is successfull.
ERRNO – An error code otherwise.

int32_t pi_uart_read_byte(pi_device_t *device, uint8_t *byte)

Read a byte from an UART.

This reads a byte from the specified UART. The caller is blocked until the transfer is finished.

Parameters:

device – Pointer to device descriptor of the UART device.
byte – Pointer to data buffer.

Return values:

0 – If operation is successfull.
ERRNO – An error code otherwise.

int32_t pi_uart_read_timeout_async(pi_device_t *device, void *buffer, uint32_t size, uint32_t timeout_us, pi_evt_t *timeout_evt, pi_uart_timeout_flags flags, void *args)

Read data from an UART asynchronously, with timeout.

This function is the same as pi_uart_read_async(), with timeout feat enabled. This timeout value is used to abort/cancel a transfer when timeout is reached.

Note

To use this feature, a UDMA timeout channel must be allocated before a call to this function :

pi_udma_timeout_alloc()
pi_uart_ioctl() //PI_UART_IOCTL_ATTACH_TIMEOUT_RX
pi_uart_read_timeout()

Note

Once timeout_evt is pushed, use pi_evt_status_get() to know if the timeout has been reached (status == PI_ERR_TIMEOUT).

Warning

* timeout_evt MUST be initialized! Holds the timeout status and works as the callback of the function

Once timeout_evt is pushed, if you use the software timeout, please CALL pi_evt_cancel_delayed_us() with the sw_timeout_evt that you have created!

Parameters:

device – Pointer to device descriptor of the UART device.
buffer – Pointer to data buffer.
size – Size of data to read in bytes.
timeout_us – Timeout value in us.
timeout_evt – Event which will be used to hold the timeout status, and for callback.
flags – Flags to configure actual timeout.
args – When using software timeout, arguments for it. See uart_sw_timeout_arg_t structure.

Return values:

0 – If operation is successfull.
ERRNO – An error code otherwise.

Returns:

Opeartion status.

int32_t pi_uart_read_timeout(pi_device_t *device, void *buffer, uint32_t size, uint32_t timeout_us, pi_evt_t *timeout_evt, pi_uart_timeout_flags flags)

Read data from an UART synchronously, with timeout.

This function is the same as pi_uart_read(), with timeout feat enabled. This timeout value is used to abort/cancel a transfer when timeout is reached.

Note

To use this feature, a UDMA timeout channel must be allocated before a call to this function :

pi_udma_timeout_alloc()
pi_uart_ioctl() //PI_UART_IOCTL_ATTACH_TIMEOUT_RX
pi_uart_read_timeout()

Warning

timeout_evt MUST NOT be initialized

Parameters:

device – Pointer to device descriptor of the UART device.
buffer – Pointer to data buffer.
size – Size of data to read in bytes.
timeout_us – Timeout value in us.
timeout_evt – Event which will be used to hold the timeout status.
flags – Flags to configure actual timeout.

Return values:

0 – If operation is successfull.
PI_ERR_TIMEOUT – Error code if timeout has been reached.
ERRNO – An error code otherwise.

Returns:

Operation status.

int32_t pi_cl_uart_write(pi_device_t *device, void *buffer, uint32_t size, pi_cl_uart_req_t *req)

Write data to an UART from cluster side.

This function implements the same feature as pi_uart_write but can be called from cluster side in order to expose the feature on the cluster. A pointer to a request structure must be provided so that the runtime can properly do the remote call.

Parameters:

device – Pointer to device descriptor of the UART device.
buffer – Pointer to data buffer.
size – Size of data to copy in bytes.
req – Request structure used for termination.

Return values:

0 – If operation is successfull.
ERRNO – An error code otherwise.

int32_t pi_cl_uart_write_byte(pi_device_t *device, uint8_t *byte, pi_cl_uart_req_t *req)

Write a byte to an UART from cluster side.

This function implements the same feature as pi_uart_write_byte but can be called from cluster side in order to expose the feature on the cluster. A pointer to a request structure must be provided so that the runtime can properly do the remote call.

Parameters:

device – Pointer to device descriptor of the UART device.
byte – Pointer to data buffer.
req – Request structure used for termination.

Return values:

0 – If operation is successfull.
ERRNO – An error code otherwise.

int32_t pi_cl_uart_read(pi_device_t *device, void *buffer, uint32_t size, pi_cl_uart_req_t *req)

Read a byte from an UART from cluster side.

This function implements the same feature as pi_uart_read_byte but can be called from cluster side in order to expose the feature on the cluster. A pointer to a request structure must be provided so that the runtime can properly do the remote call.

Parameters:

device – Pointer to device descriptor of the UART device.
buffer – Pointer to data buffer.
size – Size of data to copy in bytes.
req – Request structure used for termination.

Return values:

0 – If operation is successfull.
ERRNO – An error code otherwise.

int32_t pi_cl_uart_read_byte(pi_device_t *device, uint8_t *byte, pi_cl_uart_req_t *req)

Read a byte from an UART.

This reads a byte from the specified UART. The caller is blocked until the transfer is finished.

Parameters:

device – Pointer to device descriptor of the UART device.
byte – Pointer to data buffer.
req – Request structure used for termination.

Return values:

0 – If operation is successfull.
ERRNO – An error code otherwise.

IMPLEM int32_t pi_uart_pause (pi_device_t *device, int32_t channel, pi_evt_t *event)

Pause the current uart transfer.

PAUSE FUNCTIONS

This blocks the driver from executing any transfer until a resume happens.

Warning

To use this function, uart control flow MUST be enabled !

Parameters:

device – Uart device structure.
channel – Channel (RX_CHANNEL or TX_CHANNEL).
event – Event that will be filled with necessary info to resume the transfer.

Return values:

0 – If operation is successfull.

Returns:

Operation status

void pi_uart_resume_async(pi_device_t *device, int32_t channel, pi_evt_t *event)

Resume the current uart transfer, without any timeout.

RESUME FUNCTIONS

Note

Asynchronous. Use ‘event’ as the callback: need to call pi_evt_sig_init or similar before.

Note

Once event is pushed, use pi_evt_status_get() to know if the timeout has been reached (status == PI_ERR_TIMEOUT).

Parameters:

device – Uart device structure.
channel – Channel (RX_CHANNEL or TX_CHANNEL).
event – Event that will be filled with necessary info to resume the transfer, and for callback.

int32_t pi_uart_resume(pi_device_t *device, int32_t channel, pi_evt_t *event)

Resume the current uart transfer, without any timeout.

Parameters:

device – Uart device structure.
channel – Channel (RX_CHANNEL or TX_CHANNEL).
event – Event that will be filled with necessary info to resume the transfer.

Return values:

0 – If operation is successfull.
PI_ERR_TIMEOUT – Error code if timeout has been reached.
ERRNO – An error code otherwise.

Returns:

Operation status.

void pi_uart_resume_timeout_async(pi_device_t *device, int32_t channel, pi_evt_t *event, uint32_t timeout_us, pi_uart_timeout_flags flags)

Resume the current uart transfer and add a timeout again.

Note

Asynchronous. Use ‘event’ as the callback: need to call pi_evt_sig_init or similar before.

Note

Once event is pushed, use pi_evt_status_get() to know if the timeout has been reached (status == PI_ERR_TIMEOUT).

Parameters:

device – Uart device structure.
channel – Channel (RX_CHANNEL or TX_CHANNEL).
event – Event that will be filled with necessary info to resume the transfer, and for callback.
timeout_us – Number of micro seconds before next timeout.
flags – Flags for the timeout.

int32_t pi_uart_resume_timeout(pi_device_t *device, int32_t channel, pi_evt_t *event, uint32_t timeout_us, pi_uart_timeout_flags flags)

Resume the current uart transfer and add a timeout again.

Parameters:

device – Uart device structure.
channel – Channel (RX_CHANNEL or TX_CHANNEL).
event – Event that will be filled with necessary info to resume the transfer.
timeout_us – Number of micro seconds before next timeout.
flags – Flags for the timeout.

Return values:

0 – If operation is successfull.
PI_ERR_TIMEOUT – Error code if timeout has been reached.
ERRNO – An error code otherwise.

Returns:

Operation status.

int32_t pi_uart_abort(pi_device_t *device, int32_t channel, pi_evt_t *event)

Abort the current uart transfer.

ABORT FUNCTIONS

Aborts the current transfer, executes the next one if it exists.

Parameters:

device – Uart device structure.
channel – Channel (RX_CHANNEL or TX_CHANNEL).
event – Event that will be filled with necessary info to resume the transfer.

Return values:

0 – If operation is successfull.

Returns:

Operation status

uint32_t pi_uart_get_bytes_left(pi_evt_t *timeout_evt)

Returns number of bytes left, at the moment of timeout irq.

OTHER FUNCTIONS

Parameters:

timeout_evt – pi_evt used for timeout access

Return values:

uint32_t – number of bytes left in transfer

uint32_t pi_uart_timeout_get_bytes_left(pi_evt_t *timeout_evt)

Returns number of bytes left, at the moment of timeout irq.

Deprecated:: Use ‘pi_uart_get_bytes_left’ instead

Parameters:

timeout_evt – pi_evt used for timeout access

Return values:

uint32_t – number of bytes left in transfer

uint32_t pi_uart_get_curr_addr(pi_evt_t *timeout_evt)

Returns current pointer in l2 buffer, at the moment of timeout irq.

Parameters:

timeout_evt – pi_evt used for timeout access

Return values:

uint32_t – Pointer to current l2 address in the buffer

uint32_t pi_uart_timeout_get_curr_addr(pi_evt_t *timeout_evt)

Returns current pointer in l2 buffer, at the moment of timeout irq.

Deprecated:: Use ‘pi_uart_get_curr_addr’ instead

Parameters:

timeout_evt – pi_evt used for timeout access

Return values:

uint32_t – Pointer to current l2 address in the buffer

Variables

pi_device_api_t uart_api

struct pi_uart_conf

#include <uart.h>

UART device configuration structure.

This structure is used to pass the desired UART configuration to the runtime when opening the device.

Public Members

uint32_t baudrate_bps: Required baudrate, in baud per second.

uint8_t stop_bit_count: Number of stop bits, 1 stop bit (default) or 2 stop bits

uint8_t parity_mode: 1 to activate it, 0 to deactivate it. Even.

uint8_t word_size: Word size, in bits.

uint8_t enable_rx: 1 to activate reception, 0 to deactivate it.

uint8_t enable_tx: 1 to activate transmission, 0 to deactivate it.

uint8_t uart_id: Uart interface ID.

uint8_t use_ctrl_flow: 1 to activate control flow.

uint8_t is_usart: 1 to activate usart

uint8_t usart_polarity: If 1, the clock polarity is reversed.

uint8_t usart_phase: If 0, the data are sampled on the first clock edge, otherwise on the second clock edge.

uint8_t use_fast_clk: If 0, use fll periph as source otherwise use external fast clock.

uint32_t rts_pad: RTS pad number

struct pi_cl_uart_req_s

#include <uart.h>

UART cluster request structure.

CLUSTER SIDE FUNCTIONS

This structure is used by the runtime to manage a cluster remote copy with the UART. It must be instantiated once for each copy and must be kept alive until the copy is finished. It can be instantiated as a normal variable, for example as a global variable, a local one on the stack, or through a memory allocator.

Public Members

pi_evt_t req_cb: Event task used to send the delegate transfer.

pi_evt_t task_done: Event task used to check EOT.