UART Communication Device (rm_comms_uart)

Functions
fsp_err_t	RM_COMMS_UART_Open (rm_comms_ctrl_t *const p_api_ctrl, rm_comms_cfg_t const *const p_cfg)
	Opens and configures the UART Comms module. Implements rm_comms_api_t::open. More...
fsp_err_t	RM_COMMS_UART_Close (rm_comms_ctrl_t *const p_api_ctrl)
	Disables specified UART Comms module. Implements rm_comms_api_t::close. More...
fsp_err_t	RM_COMMS_UART_Read (rm_comms_ctrl_t *const p_api_ctrl, uint8_t *const p_dest, uint32_t const bytes)
	Performs a read from the UART device. Implements rm_comms_api_t::read. More...
fsp_err_t	RM_COMMS_UART_Write (rm_comms_ctrl_t *const p_api_ctrl, uint8_t *const p_src, uint32_t const bytes)
	Performs a write to the UART device. Implements rm_comms_api_t::write. More...
fsp_err_t	RM_COMMS_UART_WriteRead (rm_comms_ctrl_t *const p_api_ctrl, rm_comms_write_read_params_t const write_read_params)
	Performs a write to, then a read from the UART device. Implements rm_comms_api_t::writeRead. More...
fsp_err_t	RM_COMMS_UART_CallbackSet (rm_comms_ctrl_t *const p_api_ctrl, void( *p_callback)(rm_comms_callback_args_t *), void const *const p_context)
	Updates the UART Comms callback. Implements rm_comms_api_t::callbackSet. More...

Detailed Description

Middleware to implement a generic communications interface over UART. This module implements the Communicatons Middleware Interface.

Overview

The RM_COMMS_UART module implements COMMS API for UART interface.

Features

The implementation of the UART communications interfacehas the following key features:

• Non-blocking API for bare metal
• Non-blocking and blocking API for RTOS

Configuration

Build Time Configurations for rm_comms_uart

The following build time configurations are defined in fsp_cfg/rm_comms_uart_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.

Configurations for Connectivity > UART Communication Device (rm_comms_uart)

This module can be added to the Stacks tab via New Stack > Connectivity > UART Communication Device (rm_comms_uart).

Configuration	Options	Default	Description
RTOS > Write Mutex	Do Not Use Use	Use	Lock device for writing in using RTOS.
RTOS > Read Mutex	Do Not Use Use	Use	Lock device for reading in using RTOS.
RTOS > Mutex Timeout	Value must be a non-negative integer	0xFFFFFFFF	Timeout for recursive mutex operation in using RTOS.
RTOS > Write Semaphore	Do Not Use Use	Use	Block writing in using RTOS.
RTOS > Read Semaphore	Do Not Use Use	Use	Block reading in using RTOS.
RTOS > Semaphore Timeout	Value must be a non-negative integer	0xFFFFFFFF	Timeout for semaphore operation in using RTOS.
Name	Name must be a valid C symbol	g_comms_uart0	Module name.
Callback	Name must be a valid C symbol	NULL	A user callback function can be provided.

Usage Notes

Limitations

• RM_COMMS_API are not reentrant in non blocking mode
• When in blocking mode, RM_COMMS_UART_Write() and RM_COMMS_UART_Read() cannot be called in callback.
• RM_COMMS_UART_WriteRead API is not implemented

Examples

Basic Example

This is a basic example of minimal use of UART communications implementation in an application.

void rm_comms_uart_basic_example (void)
{
    fsp_err_t err = FSP_SUCCESS;


    err = RM_COMMS_UART_Open(&g_comms_uart_ctrl, &g_comms_uart_cfg);
    if (FSP_SUCCESS != err)
    {
        /* Handle any errors. */
    }


    while (true)
    {
        /* Send data. */
        g_err_flag = 0;
        g_tx_flag  = 0;
        err        = RM_COMMS_UART_Write(&g_comms_uart_ctrl, g_tx_buf, TX_BUF_LEN);
        if (FSP_SUCCESS != err)
        {
            /* Handle any errors. */
        }

        while ((0 == g_tx_flag) && (0 == g_err_flag))
        {
            /* Wait callback */
        }

        /* Receive data. */
        g_err_flag = 0;
        g_rx_flag  = 0;
        err        = RM_COMMS_UART_Read(&g_comms_uart_ctrl, g_rx_buf, RX_BUF_LEN);
        if (FSP_SUCCESS != err)
        {
            /* Handle any errors.*/
        }

        while ((0 == g_rx_flag) && (0 == g_err_flag))
        {
            /* Wait callback */
        }
    }
}

static void rm_comms_uart_callback (rm_comms_callback_args_t * p_args)
{
    if (p_args->event == RM_COMMS_EVENT_TX_OPERATION_COMPLETE)
    {
        g_tx_flag = 1;
    }
    else if (p_args->event == RM_COMMS_EVENT_RX_OPERATION_COMPLETE)
    {
        g_rx_flag = 1;
    }
    else
    {
        g_err_flag = 1;
    }
}

Data Structures
struct	rm_comms_uart_instance_ctrl_t

---

Data Structure Documentation

rm_comms_uart_instance_ctrl_t

struct rm_comms_uart_instance_ctrl_t

Communications middleware control structure.

Data Fields
uint32_t	open
	Open flag.
rm_comms_cfg_t const *	p_cfg
	Middleware configuration.
rm_comms_uart_extended_cfg_t const *	p_extend
	Pointer to extended configuration structure.
void(*	p_callback )(rm_comms_callback_args_t *p_args)
	Pointer to callback that is called when a uart_event_t occurs.
void const *	p_context
	Pointer to context passed into callback function.

Function Documentation

RM_COMMS_UART_Open()

fsp_err_t RM_COMMS_UART_Open	(	rm_comms_ctrl_t *const	p_api_ctrl,
		rm_comms_cfg_t const *const	p_cfg
	)

Opens and configures the UART Comms module. Implements rm_comms_api_t::open.

Return values

FSP_SUCCESS	UART Comms module successfully configured.
FSP_ERR_ASSERTION	Null pointer, or one or more configuration options is invalid.
FSP_ERR_ALREADY_OPEN	Module is already open. This module can only be opened once.

Returns

See Common Error Codes or functions called by this function for other possible return codes.

RM_COMMS_UART_Close()

fsp_err_t RM_COMMS_UART_Close

(

rm_comms_ctrl_t *const

p_api_ctrl

)

Disables specified UART Comms module. Implements rm_comms_api_t::close.

Return values

FSP_SUCCESS	Successfully closed.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not open.

Returns

See Common Error Codes or functions called by this function for other possible return codes.

RM_COMMS_UART_Read()

fsp_err_t RM_COMMS_UART_Read	(	rm_comms_ctrl_t *const	p_api_ctrl,
		uint8_t *const	p_dest,
		uint32_t const	bytes
	)

Performs a read from the UART device. Implements rm_comms_api_t::read.

Return values

FSP_SUCCESS	Successfully data decoded.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not open.

Returns

See Common Error Codes or functions called by this function for other possible return codes.

RM_COMMS_UART_Write()

fsp_err_t RM_COMMS_UART_Write	(	rm_comms_ctrl_t *const	p_api_ctrl,
		uint8_t *const	p_src,
		uint32_t const	bytes
	)

Performs a write to the UART device. Implements rm_comms_api_t::write.

Return values

FSP_SUCCESS	Successfully writing data .
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not open.

Returns

See Common Error Codes or functions called by this function for other possible return codes.

RM_COMMS_UART_WriteRead()

fsp_err_t RM_COMMS_UART_WriteRead	(	rm_comms_ctrl_t *const	p_api_ctrl,
		rm_comms_write_read_params_t const	write_read_params
	)

Performs a write to, then a read from the UART device. Implements rm_comms_api_t::writeRead.

Return values

FSP_ERR_UNSUPPORTED

Not supported.

RM_COMMS_UART_CallbackSet()

fsp_err_t RM_COMMS_UART_CallbackSet	(	rm_comms_ctrl_t *const	p_api_ctrl,
		void(*)(rm_comms_callback_args_t *)	p_callback,
		void const *const	p_context
	)

Updates the UART Comms callback. Implements rm_comms_api_t::callbackSet.

Return values

FSP_SUCCESS	Successfully set.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not open.