Description

Driver for the UART peripheral for serial communication.

File(s):

The driver must be configured by supplying a project specific "px_uart_cfg.h". "px_uart_cfg_template.h" can be copied, renamed and modified to supply compile time options.

#include "px_board.h"
#include "px_compiler.h"
#include "px_uart.h"
 
// Create UART handle object
static px_uart_handle_t px_uart_handle;
 
int main(void)
{
    uint8_t data;
 
    // Initialise board
    px_board_init();
    // Initialise module
    px_uart_init();
    // Enable interrupts
    px_interrupts_enable();
    // Open UART1 @ 115200 BAUD, 8 data bits, no parity, 1 stop bit
    px_uart_open2(&px_uart_handle,
                  PX_UART_NR_1, 
                  115200, 
                  PX_UART_DATA_BITS_8, 
                  PX_UART_PARITY_NONE, 
                  PX_UART_STOP_BITS_1);
 
    // Loop forever
    while(true)
    {
        // Wait until a byte is received
        if(px_uart_rd_u8(&px_uart_handle, &data))
        {
            // Send back received byte (loopback/echo mode)
            px_uart_wr_u8(&px_uart_handle, data);
        }
    }
}

Data Structures
struct	px_uart_handle_t
	Define UART handle. More...

Macros
#define	PX_UART_CFG_PER_COUNT
	Number of enabled peripherals. More...

#define	PX_UART_CFG_UART1_EN 1
	Enable/disable support for UART1 peripheral. More...

#define	PX_UART_CFG_UART2_EN 1
	Enable/disable support for UART2 peripheral. More...

#define	PX_UART_CFG_UART4_EN 1
	Enable/disable support for UART4 peripheral. More...

#define	PX_UART_CFG_UART5_EN 0
	Enable/disable support for UART5 peripheral. More...

#define	PX_UART_CFG_DEFAULT_BAUD 115200ul
	Default BAUD rate. More...

#define	PX_UART_CFG_UART_TX_BUF_SIZE 64
	General size of UART transmit buffer. More...

#define	PX_UART_CFG_UART_RX_BUF_SIZE 64
	General size of UART receive buffer. More...

#define	PX_UART_CFG_UART1_TX_BUF_SIZE PX_UART_CFG_UART_TX_BUF_SIZE
	Size of UART1 transmit buffer. More...

#define	PX_UART_CFG_UART1_RX_BUF_SIZE PX_UART_CFG_UART_RX_BUF_SIZE
	Size of UART1 receive buffer. More...

#define	PX_UART_CFG_UART2_TX_BUF_SIZE PX_UART_CFG_UART_TX_BUF_SIZE
	Size of UART2 transmit buffer. More...

#define	PX_UART_CFG_UART2_RX_BUF_SIZE PX_UART_CFG_UART_RX_BUF_SIZE
	Size of UART2 receive buffer. More...

#define	PX_UART_CFG_UART4_TX_BUF_SIZE PX_UART_CFG_UART_TX_BUF_SIZE
	Size of UART4 transmit buffer. More...

#define	PX_UART_CFG_UART4_RX_BUF_SIZE PX_UART_CFG_UART_RX_BUF_SIZE
	Size of UART4 receive buffer. More...

#define	PX_UART_CFG_UART5_TX_BUF_SIZE PX_UART_CFG_UART_TX_BUF_SIZE
	Size of UART5 transmit buffer. More...

#define	PX_UART_CFG_UART5_RX_BUF_SIZE PX_UART_CFG_UART_RX_BUF_SIZE
	Size of UART5 receive buffer. More...

#define	PX_UART_CFG_UART1_CLK_HZ PX_BOARD_PER_CLK_HZ
	UART1 peripheral clock in Hz. More...

#define	PX_UART_CFG_UART2_CLK_HZ PX_BOARD_PER_CLK_HZ
	UART2 peripheral clock in Hz. More...

#define	PX_UART_CFG_UART3_CLK_HZ PX_BOARD_PER_CLK_HZ
	UART3 peripheral clock in Hz. More...

#define	PX_UART_CFG_UART4_CLK_HZ PX_BOARD_PER_CLK_HZ
	UART4 peripheral clock in Hz. More...

#define	PX_UART_CFG_UART5_CLK_HZ PX_BOARD_PER_CLK_HZ
	UART5 peripheral clock in Hz. More...

Enumerations
enum	px_uart_nr_t
	Specify UART peripheral. More...

enum	px_uart_parity_t
	Specify UART parity (none, odd or even) More...

enum	px_uart_data_bits_t
	Specify number of data bits used (7..9) More...

enum	px_uart_stop_bits_t
	Specify number of stop bits (1/2) More...

Functions
void	px_uart_init (void)
	Initialise UART driver. More...

bool	px_uart_open (px_uart_handle_t *handle, px_uart_nr_t uart_nr)
	Open UART peripheral using predefined (default) parameters. More...

bool	px_uart_open2 (px_uart_handle_t *handle, px_uart_nr_t uart_nr, uint32_t baud, px_uart_data_bits_t data_bits, px_uart_parity_t parity, px_uart_stop_bits_t stop_bits)
	Open UART peripheral using specified parameters. More...

bool	px_uart_close (px_uart_handle_t *handle)
	Close specified peripheral. More...

void	px_uart_putchar (px_uart_handle_t *handle, char data)
	Write one byte. More...

bool	px_uart_wr_u8 (px_uart_handle_t *handle, uint8_t data)
	Buffer one byte for transmission. More...

size_t	px_uart_wr (px_uart_handle_t handle, const void data, size_t nr_of_bytes)
	Buffer byte(s) for transmission. More...

char	px_uart_getchar (px_uart_handle_t *handle)
	Read one byte. More...

bool	px_uart_rd_u8 (px_uart_handle_t handle, uint8_t data)
	See if a received byte is available and store it in the specified location. More...

size_t	px_uart_rd (px_uart_handle_t handle, void buf, size_t nr_of_bytes)
	Copy received data from receive buffer into specified buffer. More...

bool	px_uart_wr_buf_is_full (px_uart_handle_t *handle)
	See if transmit buffer can accept more data. More...

bool	px_uart_wr_buf_is_empty (px_uart_handle_t *handle)
	See if transmit buffer is empty. More...

bool	px_uart_wr_is_done (px_uart_handle_t *handle)
	See if all transmission has finished, including last byte. More...

bool	px_uart_rd_buf_is_empty (px_uart_handle_t *handle)
	See if there is received data in the receive buffer. More...

bool	px_uart_change_baud (px_uart_handle_t *handle, uint32_t baud)
	Change UART peripheral baud rate. More...

bool	px_uart_change_data_format (px_uart_handle_t *handle, px_uart_data_bits_t data_bits, px_uart_parity_t parity, px_uart_stop_bits_t stop_bits)
	Change UART peripheral data format. More...

Data Structure Documentation

◆ px_uart_handle_t

struct px_uart_handle_t

Define UART handle.

Definition at line 140 of file px_uart.h.

Data Fields
struct px_uart_per_s *	uart_per	USART peripheral data.

Macro Definition Documentation

◆ PX_UART_CFG_PER_COUNT

#define PX_UART_CFG_PER_COUNT

Value:

                                  (   PX_UART_CFG_UART1_EN \
                                  + PX_UART_CFG_UART2_EN \
                                  + PX_UART_CFG_UART4_EN \
                                  + PX_UART_CFG_UART5_EN )

Number of enabled peripherals.

Definition at line 65 of file px_uart.h.

◆ PX_UART_CFG_UART1_EN

#define PX_UART_CFG_UART1_EN 1

Enable/disable support for UART1 peripheral.

Definition at line 35 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART2_EN

#define PX_UART_CFG_UART2_EN 1

Enable/disable support for UART2 peripheral.

Definition at line 38 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART4_EN

#define PX_UART_CFG_UART4_EN 1

Enable/disable support for UART4 peripheral.

Definition at line 41 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART5_EN

#define PX_UART_CFG_UART5_EN 0

Enable/disable support for UART5 peripheral.

Definition at line 44 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_DEFAULT_BAUD

#define PX_UART_CFG_DEFAULT_BAUD 115200ul

Default BAUD rate.

Definition at line 47 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART_TX_BUF_SIZE

#define PX_UART_CFG_UART_TX_BUF_SIZE 64

General size of UART transmit buffer.

Definition at line 50 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART_RX_BUF_SIZE

#define PX_UART_CFG_UART_RX_BUF_SIZE 64

General size of UART receive buffer.

Definition at line 52 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART1_TX_BUF_SIZE

#define PX_UART_CFG_UART1_TX_BUF_SIZE PX_UART_CFG_UART_TX_BUF_SIZE

Size of UART1 transmit buffer.

Definition at line 55 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART1_RX_BUF_SIZE

#define PX_UART_CFG_UART1_RX_BUF_SIZE PX_UART_CFG_UART_RX_BUF_SIZE

Size of UART1 receive buffer.

Definition at line 57 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART2_TX_BUF_SIZE

#define PX_UART_CFG_UART2_TX_BUF_SIZE PX_UART_CFG_UART_TX_BUF_SIZE

Size of UART2 transmit buffer.

Definition at line 60 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART2_RX_BUF_SIZE

#define PX_UART_CFG_UART2_RX_BUF_SIZE PX_UART_CFG_UART_RX_BUF_SIZE

Size of UART2 receive buffer.

Definition at line 62 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART4_TX_BUF_SIZE

#define PX_UART_CFG_UART4_TX_BUF_SIZE PX_UART_CFG_UART_TX_BUF_SIZE

Size of UART4 transmit buffer.

Definition at line 65 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART4_RX_BUF_SIZE

#define PX_UART_CFG_UART4_RX_BUF_SIZE PX_UART_CFG_UART_RX_BUF_SIZE

Size of UART4 receive buffer.

Definition at line 67 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART5_TX_BUF_SIZE

#define PX_UART_CFG_UART5_TX_BUF_SIZE PX_UART_CFG_UART_TX_BUF_SIZE

Size of UART5 transmit buffer.

Definition at line 70 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART5_RX_BUF_SIZE

#define PX_UART_CFG_UART5_RX_BUF_SIZE PX_UART_CFG_UART_RX_BUF_SIZE

Size of UART5 receive buffer.

Definition at line 72 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART1_CLK_HZ

#define PX_UART_CFG_UART1_CLK_HZ PX_BOARD_PER_CLK_HZ

UART1 peripheral clock in Hz.

Definition at line 75 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART2_CLK_HZ

#define PX_UART_CFG_UART2_CLK_HZ PX_BOARD_PER_CLK_HZ

UART2 peripheral clock in Hz.

Definition at line 77 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART3_CLK_HZ

#define PX_UART_CFG_UART3_CLK_HZ PX_BOARD_PER_CLK_HZ

UART3 peripheral clock in Hz.

Definition at line 79 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART4_CLK_HZ

#define PX_UART_CFG_UART4_CLK_HZ PX_BOARD_PER_CLK_HZ

UART4 peripheral clock in Hz.

Definition at line 81 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART5_CLK_HZ

#define PX_UART_CFG_UART5_CLK_HZ PX_BOARD_PER_CLK_HZ

UART5 peripheral clock in Hz.

Definition at line 83 of file px_uart_cfg_template.h.

Enumeration Type Documentation

◆ px_uart_nr_t

enum px_uart_nr_t

Specify UART peripheral.

Definition at line 107 of file px_uart.h.

◆ px_uart_parity_t

enum px_uart_parity_t

Specify UART parity (none, odd or even)

Definition at line 117 of file px_uart.h.

◆ px_uart_data_bits_t

enum px_uart_data_bits_t

Specify number of data bits used (7..9)

Definition at line 125 of file px_uart.h.

◆ px_uart_stop_bits_t

enum px_uart_stop_bits_t

Specify number of stop bits (1/2)

Definition at line 133 of file px_uart.h.

Function Documentation

◆ px_uart_init()

void px_uart_init ( void )

Initialise UART driver.

Definition at line 452 of file px_uart.c.

◆ px_uart_open()

bool px_uart_open	(	px_uart_handle_t *	handle,
		px_uart_nr_t	uart_nr
	)

Open UART peripheral using predefined (default) parameters.

Parameters

handle	Pointer to handle data structure
uart_nr	UART peripheral number.

See also: px_uart_nr_t

Return values

false	Error: peripheral was not opened
true	Success: peripheral was opened

Definition at line 472 of file px_uart.c.

◆ px_uart_open2()

bool px_uart_open2	(	px_uart_handle_t *	handle,
		px_uart_nr_t	uart_nr,
		uint32_t	baud,
		px_uart_data_bits_t	data_bits,
		px_uart_parity_t	parity,
		px_uart_stop_bits_t	stop_bits
	)

Open UART peripheral using specified parameters.

Parameters

handle	Pointer to handle data structure
uart_nr	UART peripheral number.

See also: px_uart_nr_t

Parameters

baud	Baud rate in bits/s
data_bits	Data bits.

See also: px_uart_data_bits_t

Parameters

parity Parity.

See also: px_uart_parity_t

Parameters

stop_bits Stop bits.

See also: px_uart_stop_bits_t

Return values

false	Error: peripheral was not opened
true	Success: peripheral was opened

Definition at line 483 of file px_uart.c.

◆ px_uart_close()

bool px_uart_close ( px_uart_handle_t * handle )

Close specified peripheral.

Parameters

handle Pointer to handle data structure

Return values

true	Success
false	Specified peripheral was already closed (or not opened)

Definition at line 544 of file px_uart.c.

◆ px_uart_putchar()

void px_uart_putchar	(	px_uart_handle_t *	handle,
		char	data
	)

Write one byte.

This function blocks until space is available in the write buffer.

Parameters

	handle	Pointer to handle data structure
[in]	data	Byte to be written

Definition at line 632 of file px_uart.c.

◆ px_uart_wr_u8()

bool px_uart_wr_u8	(	px_uart_handle_t *	handle,
		uint8_t	data
	)

Buffer one byte for transmission.

Parameters

	handle	Pointer to handle data structure
[in]	data	Byte to be written

Return values

true	Byte has been buffered
false	Byte has not been buffered, because write buffer is full

Definition at line 651 of file px_uart.c.

◆ px_uart_wr()

size_t px_uart_wr	(	px_uart_handle_t *	handle,
		const void *	data,
		size_t	nr_of_bytes
	)

Buffer byte(s) for transmission.

Note: The write buffer may not be able to hold all of the specified data.

Parameters

	handle	Pointer to handle data structure
[in]	data	Buffer containing data for transmission
[in]	nr_of_bytes	Number of bytes in buffer to be written

Returns: size_t The actual number of bytes buffered for transmission.

Definition at line 677 of file px_uart.c.

◆ px_uart_getchar()

char px_uart_getchar ( px_uart_handle_t * handle )

Read one byte.

This function blocks until a byte is received.

Parameters

handle Pointer to handle data structure

Returns: Received byte

Definition at line 706 of file px_uart.c.

◆ px_uart_rd_u8()

bool px_uart_rd_u8	(	px_uart_handle_t *	handle,
		uint8_t *	data
	)

See if a received byte is available and store it in the specified location.

Parameters

	handle	Pointer to handle data structure
[out]	data	Pointer to location where data byte must be stored

Return values

true	Received byte is stored in specified location
false	No received data available (receive buffer empty)

Definition at line 726 of file px_uart.c.

◆ px_uart_rd()

size_t px_uart_rd	(	px_uart_handle_t *	handle,
		void *	buf,
		size_t	nr_of_bytes
	)

Copy received data from receive buffer into specified buffer.

Parameters

	handle	Pointer to handle data structure
[out]	buf	Buffer to copy received data into
[in]	nr_of_bytes	Maximum number of received bytes to copy into buffer

Returns: size_t Number of received bytes copied into buffer

Definition at line 743 of file px_uart.c.

◆ px_uart_wr_buf_is_full()

bool px_uart_wr_buf_is_full ( px_uart_handle_t * handle )

See if transmit buffer can accept more data.

Parameters

handle Pointer to handle data structure

Return values

true	Transmit buffer is full
false	Transmit buffer has space for at least one byte

Definition at line 762 of file px_uart.c.

◆ px_uart_wr_buf_is_empty()

bool px_uart_wr_buf_is_empty ( px_uart_handle_t * handle )

See if transmit buffer is empty.

Note: Buffer may be empty, but UART peripheral may still be busy with the transmission of the last byte in the buffer.

See also: px_uart_tx_finished.

Parameters

handle Pointer to handle data structure

Return values

true	Transmit buffer is empty
false	Transmit buffer has space for at least one byte

Definition at line 778 of file px_uart.c.

◆ px_uart_wr_is_done()

bool px_uart_wr_is_done ( px_uart_handle_t * handle )

See if all transmission has finished, including last byte.

This functions is usefull for communication standards like RS-485 where the mode must be changed manually from TX to RX after transmission.

Parameters

handle Pointer to handle data structure

Return values

true	Transmision completely finished
false	Busy with transmission

Definition at line 794 of file px_uart.c.

◆ px_uart_rd_buf_is_empty()

bool px_uart_rd_buf_is_empty ( px_uart_handle_t * handle )

See if there is received data in the receive buffer.

Parameters

handle Pointer to handle data structure

Return values

true	There is received data in the receive buffer
false	The receive buffer is empty

Definition at line 817 of file px_uart.c.

◆ px_uart_change_baud()

bool px_uart_change_baud	(	px_uart_handle_t *	handle,
		uint32_t	baud
	)

Change UART peripheral baud rate.

Parameters

handle	Pointer to handle data structure
baud	Baud rate in bits/s

Return values

true	Success. Baud was changed
false	Error. Requested baud invalid

Definition at line 833 of file px_uart.c.

◆ px_uart_change_data_format()

bool px_uart_change_data_format	(	px_uart_handle_t *	handle,
		px_uart_data_bits_t	data_bits,
		px_uart_parity_t	parity,
		px_uart_stop_bits_t	stop_bits
	)

Change UART peripheral data format.

Parameters

handle	Pointer to handle data structure
data_bits	Data bits (7,8 or 9)
parity	Parity(NONE, ODD or EVEN)
stop_bits	Stop bits (1 or 2)

Return values

true	Success. data format was changed
false	Error. Requested data format invalid

Definition at line 872 of file px_uart.c.

Description

Data Structures

Macros

Enumerations

Functions

Data Structure Documentation

◆ px_uart_handle_t

Macro Definition Documentation

◆ PX_UART_CFG_PER_COUNT

◆ PX_UART_CFG_UART1_EN

◆ PX_UART_CFG_UART2_EN

◆ PX_UART_CFG_UART4_EN

◆ PX_UART_CFG_UART5_EN

◆ PX_UART_CFG_DEFAULT_BAUD

◆ PX_UART_CFG_UART_TX_BUF_SIZE

◆ PX_UART_CFG_UART_RX_BUF_SIZE

◆ PX_UART_CFG_UART1_TX_BUF_SIZE

◆ PX_UART_CFG_UART1_RX_BUF_SIZE

◆ PX_UART_CFG_UART2_TX_BUF_SIZE

◆ PX_UART_CFG_UART2_RX_BUF_SIZE

◆ PX_UART_CFG_UART4_TX_BUF_SIZE

◆ PX_UART_CFG_UART4_RX_BUF_SIZE

◆ PX_UART_CFG_UART5_TX_BUF_SIZE

◆ PX_UART_CFG_UART5_RX_BUF_SIZE

◆ PX_UART_CFG_UART1_CLK_HZ

◆ PX_UART_CFG_UART2_CLK_HZ

◆ PX_UART_CFG_UART3_CLK_HZ

◆ PX_UART_CFG_UART4_CLK_HZ

◆ PX_UART_CFG_UART5_CLK_HZ

Enumeration Type Documentation

◆ px_uart_nr_t

◆ px_uart_parity_t

◆ px_uart_data_bits_t

◆ px_uart_stop_bits_t

Function Documentation

◆ px_uart_init()

◆ px_uart_open()

◆ px_uart_open2()

◆ px_uart_close()

◆ px_uart_putchar()

◆ px_uart_wr_u8()

◆ px_uart_wr()

◆ px_uart_getchar()

◆ px_uart_rd_u8()

◆ px_uart_rd()

◆ px_uart_wr_buf_is_full()

◆ px_uart_wr_buf_is_empty()

◆ px_uart_wr_is_done()

◆ px_uart_rd_buf_is_empty()

◆ px_uart_change_baud()

◆ px_uart_change_data_format()