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

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.
Read Mutex	Do Not Use Use	Use	Lock device for reading in using RTOS.
Mutex Timeout	Value must be a non-negative integer	0xFFFFFFFF	Timeout for recursive mutex operation in using RTOS.
Write Semaphore	Do Not Use Use	Use	Block writing in using RTOS.
Read Semaphore	Do Not Use Use	Use	Block reading in using 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_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.

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.