UART Universal Asynchronous Receiver Transmitter. More...

Data Structures
struct	pi_uart_conf
	UART device configuration structure. More...

Typedefs
typedef struct pi_cl_uart_req_s	pi_cl_uart_req_t
	UART cluster request structure. More...

Enumerations
enum	pi_uart_stop_bits
	Stop bits enum. More...

enum	pi_uart_parity_mode
	Parity mode enum. More...

enum	pi_uart_word_size
	Bit length of each word. More...

enum	pi_uart_ioctl_cmd
	UART ioctl commands. More...

Functions
void	pi_uart_conf_init (struct pi_uart_conf *conf)
	Initialize a UART configuration with default values. More...

int	pi_uart_open (struct pi_device *device)
	Open a UART device. More...

void	pi_uart_close (struct pi_device *device)
	Close an opened UART device. More...

int	pi_uart_ioctl (struct pi_device device, uint32_t cmd, void arg)
	Dynamically change device configuration. More...

int	pi_uart_write (struct pi_device device, void buffer, uint32_t size)
	Write data to an UART. More...

int	pi_uart_read (struct pi_device device, void buffer, uint32_t size)
	Read data from an UART. More...

int	pi_uart_write_byte (struct pi_device device, uint8_t byte)
	Write a byte to an UART. More...

int	pi_uart_read_byte (struct pi_device device, uint8_t byte)
	Read a byte from an UART. More...

int	pi_uart_write_async (struct pi_device device, void buffer, uint32_t size, pi_task_t *callback)
	Write data to an UART asynchronously. More...

int	pi_uart_read_async (struct pi_device device, void buffer, uint32_t size, pi_task_t *callback)
	Read data from an UART asynchronously. More...

int	pi_uart_write_timeout (struct pi_device device, void buffer, uint32_t size, uint32_t timeout_us)
	Write data to an UART synchronously, with timeout. More...

int	pi_uart_read_timeout (struct pi_device device, void buffer, uint32_t size, uint32_t timeout_us)
	Read data from an UART synchronously, with timeout. More...

int	pi_uart_write_byte_async (struct pi_device device, uint8_t byte, pi_task_t *callback)
	Write a byte to an UART asynchronously. More...

int	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. More...

int	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. More...

static void	pi_cl_uart_write_wait (pi_cl_uart_req_t *req)
	Wait until the specified UART cluster write request has finished. More...

int	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. More...

int	pi_cl_uart_read_byte (pi_device_t device, uint8_t byte, pi_cl_uart_req_t *req)
	Read a byte from an UART. More...

static void	pi_cl_uart_read_wait (pi_cl_uart_req_t *req)
	Wait until the specified UART cluster read request has finished. More...

Description

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

Typedef Documentation

typedef struct pi_cl_uart_req_s pi_cl_uart_req_t

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.

Enumeration Type Documentation

enum pi_uart_ioctl_cmd

UART ioctl commands to configure, enable device.

Enumerator

PI_UART_IOCTL_CONF_SETUP

Setup UART device.

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

Parameters

conf	Pointer to struct pi_uart_conf.

PI_UART_IOCTL_ABORT_RX

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.

PI_UART_IOCTL_ABORT_TX

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.

PI_UART_IOCTL_ENABLE_RX

Enable reception.

This command enables reception on UART device.

PI_UART_IOCTL_ENABLE_TX

Enable transmission.

This command enables transmission on UART device.

PI_UART_IOCTL_ENABLE_FLOW_CONTROL

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).

PI_UART_IOCTL_DISABLE_FLOW_CONTROL

Disable flow control.

This command disables flow control on UART device.

PI_UART_IOCTL_FLUSH

Flush UART TX.

This command will wait until all pending buffers are flushed outside

PI_UART_IOCTL_ATTACH_TIMEOUT_RX

Attach UDMA timer.

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

Parameters

timeout_id UDMA timeout channel ID.

PI_UART_IOCTL_DETACH_TIMEOUT_RX

Detach UDMA timer.

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

Parameters

timeout_id UDMA timeout channel ID.

PI_UART_IOCTL_ATTACH_TIMEOUT_TX

Attach UDMA timer.

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

Parameters

timeout_id UDMA timeout channel ID.

PI_UART_IOCTL_DETACH_TIMEOUT_TX

Detach UDMA timer.

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

Parameters

timeout_id UDMA timeout channel ID.

enum pi_uart_parity_mode

Enumerator
PI_UART_PARITY_DISABLE	Disable parity mode.
PI_UART_PARITY_ENABLE	Enable parity mode.

enum pi_uart_stop_bits

Enumerator
PI_UART_STOP_BITS_ONE	One stop bit.
PI_UART_STOP_BITS_TWO	Two stop bits.

enum pi_uart_word_size

Enumerator
PI_UART_WORD_SIZE_5_BITS	5 bits length.
PI_UART_WORD_SIZE_6_BITS	6 bits length.
PI_UART_WORD_SIZE_7_BITS	7 bits length.
PI_UART_WORD_SIZE_8_BITS	8 bits length.

Function Documentation

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

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.

int pi_cl_uart_read_byte	(	pi_device_t *	device,
		uint8_t *	byte,
		pi_cl_uart_req_t *	req
	)

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.

static void pi_cl_uart_read_wait ( pi_cl_uart_req_t * req )

inlinestatic

This blocks the calling core until the specified cluster remote copy is finished.

Parameters

req	Request structure used for termination.

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

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.

int pi_cl_uart_write_byte	(	pi_device_t *	device,
		uint8_t *	byte,
		pi_cl_uart_req_t *	req
	)

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.

static void pi_cl_uart_write_wait ( pi_cl_uart_req_t * req )

inlinestatic

This blocks the calling core until the specified cluster remote copy is finished.

Parameters

req	Request structure used for termination.

void pi_uart_close ( struct pi_device * 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.

void pi_uart_conf_init ( struct pi_uart_conf * conf )

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.

int pi_uart_ioctl	(	struct pi_device *	device,
		uint32_t	cmd,
		void *	arg
	)

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.

int pi_uart_open ( struct pi_device * 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.

Parameters

device Pointer to device structure of the device to open.

Return values

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

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

int pi_uart_read	(	struct pi_device *	device,
		void *	buffer,
		uint32_t	size
	)

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.

int pi_uart_read_async	(	struct pi_device *	device,
		void *	buffer,
		uint32_t	size,
		pi_task_t *	callback
	)

This reads data from the specified UART asynchronously. A task 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 task used to notify the end of transfer. See the documentation of pi_task_t for more details.

Return values

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

int pi_uart_read_byte	(	struct pi_device *	device,
		uint8_t *	byte
	)

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.

int pi_uart_read_timeout	(	struct pi_device *	device,
		void *	buffer,
		uint32_t	size,
		uint32_t	timeout_us
	)

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.

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.

Return values

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

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_RX
pi_uart_read_timeout()

To use this feature asynchronously, proceed as follows :

pi_udma_timeout_alloc()
pi_uart_ioctl() //PI_UART_IOCTL_ATTACH_TIMEOUT_RX
pi_task_timeout_set()
pi_uart_read_async()

int pi_uart_write	(	struct pi_device *	device,
		void *	buffer,
		uint32_t	size
	)

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.

int pi_uart_write_async	(	struct pi_device *	device,
		void *	buffer,
		uint32_t	size,
		pi_task_t *	callback
	)

This writes data to the specified UART asynchronously. A task 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 task used to notify the end of transfer. See the documentation of pi_task_t for more details.

Return values

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

int pi_uart_write_byte	(	struct pi_device *	device,
		uint8_t *	byte
	)

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.

int pi_uart_write_byte_async	(	struct pi_device *	device,
		uint8_t *	byte,
		pi_task_t *	callback
	)

This writes a byte to the specified UART asynchronously. A task 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 task used to notify the end of transfer. See the documentation of pi_task_t for more details.

Return values

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

int pi_uart_write_timeout	(	struct pi_device *	device,
		void *	buffer,
		uint32_t	size,
		uint32_t	timeout_us
	)

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.

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.

Return values

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

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()

To use this feature asynchronously, proceed as follows :

pi_udma_timeout_alloc()
pi_uart_ioctl() //PI_UART_IOCTL_ATTACH_TIMEOUT_TX
pi_task_timeout_set()
pi_uart_write_async()

Data Structures

Typedefs

Enumerations

Functions

Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation