USB_PCDC Communication Device (rm_comms_usb_pcdc)

Functions
fsp_err_t	RM_COMMS_USB_PCDC_Open (rm_comms_ctrl_t *const p_api_ctrl, rm_comms_cfg_t const *const p_cfg)
	Opens and configures the USB PCDC Comms module. Implements rm_comms_api_t::open. More...
fsp_err_t	RM_COMMS_USB_PCDC_Close (rm_comms_ctrl_t *const p_api_ctrl)
	Disables specified USB PCDC Comms module. Implements rm_comms_api_t::close. More...
fsp_err_t	RM_COMMS_USB_PCDC_CallbackSet (rm_comms_ctrl_t *const p_api_ctrl, void(*p_callback)(rm_comms_callback_args_t *), void const *const p_context)
	Updates the USB PCDC Comms callback. Implements rm_comms_api_t::callbackSet. More...
fsp_err_t	RM_COMMS_USB_PCDC_Read (rm_comms_ctrl_t *const p_api_ctrl, uint8_t *const p_dest, uint32_t const bytes)
	Performs a read from the USB PCDC device. Implements rm_comms_api_t::read. More...
fsp_err_t	RM_COMMS_USB_PCDC_Write (rm_comms_ctrl_t *const p_api_ctrl, uint8_t *const p_src, uint32_t const bytes)
	Performs a write to the USB PCDC device. Implements rm_comms_api_t::write. More...
fsp_err_t	RM_COMMS_USB_PCDC_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 USB device. Implements rm_comms_api_t::writeRead. More...
void	rm_comms_usb_pcdc_notify_application (rm_comms_usb_pcdc_instance_ctrl_t const *p_ctrl, rm_comms_event_t event)
void	rm_comms_usb_pcdc_callback_handler (usb_instance_ctrl_t *p_args, usb_hdl_t usb_handle, usb_onoff_t usb_onoff_status)
	Common callback function called in the USB PCDC driver callback function.

Detailed Description

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

Overview

The RM_COMMS_USB_PCDC module implements COMMS API for USB_PCDC interface.

Features

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

• Non-blocking API for bare metal
• Non-blocking and blocking API for RTOS
• USB connection detection mode

Configuration

Build Time Configurations for rm_comms_usb_pcdc

The following build time configurations are defined in fsp_cfg/r_usb_pcdc_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.
Bulk In Pipe	USB PIPE1 USB PIPE2 USB PIPE3 USB PIPE4 USB PIPE5	USB PIPE4	Select the USB pipe to use for bulk input transfers.
Bulk Out Pipe	USB PIPE1 USB PIPE2 USB PIPE3 USB PIPE4 USB PIPE5	USB PIPE5	Select the USB pipe to use for bulk output transfers.
Interrupt In Pipe	USB PIPE6 USB PIPE7 USB PIPE8 USB PIPE9	USB PIPE6	Select the USB pipe to use for interrupts.

Configurations for Connectivity > USB PCDC Communication Device (rm_comms_usb_pcdc)

This module can be added to the Stacks tab via New Stack > Connectivity > USB PCDC Communication Device (rm_comms_usb_pcdc).

Configuration	Options	Default	Description
RTOS
Recursive Write Mutex	Do Not Use Use	Use	Lock device for writing in using RTOS.
Recursive 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_usb_pcdc0	Module name.
USB Connection Detection	Disabled Baudrate Configuration Control Line State	Disabled	Enable it only when application wants to process the error of USB host tool not opened.
Callback	Name must be a valid C symbol	NULL	A user callback function can be provided.

Usage Notes

USB connection detection has two modes: Baudrate Configuration mode and Control Line State mode. The former depends on line coding request, and the latter relies on control line state request. When it is enabled, rm_comms_usb_pcdc_write API will return FSP_ERR_NOT_ENABLED when USB host tool is not opened. By default it is disabled.

Limitations

• RM_COMMS_API are not reentrant in non blocking mode
• When in blocking mode, RM_COMMS_USB_PCDC_Write() and RM_COMMS_USB_PCDC_Read() cannot be called in callback.
• RM_COMMS_USB_PCDC_WriteRead API is not implemented
• USB connection detection could be platform specific when it is enabled. For Windows USB host, Baudrate configuration mode should be used.

Examples

Basic Example

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

void rm_comms_usb_pcdc_basic_example (void)
{
    fsp_err_t err = FSP_SUCCESS;


    err = RM_COMMS_USB_PCDC_Open(&g_comms_usb_pcdc_ctrl, &g_comms_usb_pcdc_cfg);
    if (FSP_SUCCESS != err)
    {
        /* Handle any errors. */
    }


    while (true)
    {
        /* Send data. */
        g_err_flag = 0;
        g_tx_flag  = 0;
        err        = RM_COMMS_USB_PCDC_Write(&g_comms_usb_pcdc_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_USB_PCDC_Read(&g_comms_usb_pcdc_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_usb_pcdc_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;
    }
}

Descriptor

A template for PCDC descriptors can be found in ra/fsp/src/r_usb_pcdc/r_usb_pcdc_descriptor.c.template. Also, please be sure to use your vendor ID.

Data Structures
struct	rm_comms_usb_pcdc_instance_ctrl_t

---

Data Structure Documentation

rm_comms_usb_pcdc_instance_ctrl_t

struct rm_comms_usb_pcdc_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_usb_pcdc_extended_cfg_t const *	p_extend
	Pointer to extended configuration structure.
usb_callback_args_t *	p_usb_args
	Pointer to usb callback args.
usb_pcdc_ctrllinestate_t	ctrl_line_state
	Line State Control.
usb_pcdc_linecoding_t	line_coding
	Line Coding to store COM port settings.
void(*	p_callback )(rm_comms_callback_args_t *p_args)
	Pointer to callback that is called when a usb_status_t occurs.
void const *	p_context
	Pointer to context passed into callback function.

Function Documentation

RM_COMMS_USB_PCDC_Open()

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

Opens and configures the USB PCDC Comms module. Implements rm_comms_api_t::open.

Return values

FSP_SUCCESS	USB PCDC 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_USB_PCDC_Close()

fsp_err_t RM_COMMS_USB_PCDC_Close

(

rm_comms_ctrl_t *const

p_api_ctrl

)

Disables specified USB PCDC 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_USB_PCDC_CallbackSet()

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

Updates the USB PCDC 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_USB_PCDC_Read()

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

Performs a read from the USB PCDC 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.
FSP_ERR_NOT_ENABLED	USB device needs connecting from USB host to operate.

Returns

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

RM_COMMS_USB_PCDC_Write()

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

Performs a write to the USB PCDC 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.
FSP_ERR_NOT_ENABLED	USB device needs connecting from USB host to operate.

Returns

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

RM_COMMS_USB_PCDC_WriteRead()

fsp_err_t RM_COMMS_USB_PCDC_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 USB device. Implements rm_comms_api_t::writeRead.

Return values

FSP_ERR_UNSUPPORTED

Not supported.

rm_comms_usb_pcdc_notify_application()

void rm_comms_usb_pcdc_notify_application	(	rm_comms_usb_pcdc_instance_ctrl_t const *	p_ctrl,
		rm_comms_event_t	event
	)

(end addtogroup RM_COMMS_USB_PCDC)