SMCI (r_sci_smci)

Functions
fsp_err_t	R_SCI_SMCI_Open (smci_ctrl_t *const p_api_ctrl, smci_cfg_t const *const p_cfg)
fsp_err_t	R_SCI_SMCI_Write (smci_ctrl_t *const p_api_ctrl, uint8_t const *const p_src, uint32_t const bytes)
fsp_err_t	R_SCI_SMCI_Read (smci_ctrl_t *const p_api_ctrl, uint8_t *const p_dest, uint32_t const bytes)
fsp_err_t	R_SCI_SMCI_TransferModeSet (smci_ctrl_t *const p_api_ctrl, smci_transfer_mode_t const *const p_transfer_mode_params)
fsp_err_t	R_SCI_SMCI_BaudSet (smci_ctrl_t *const p_api_ctrl, void const *const p_baud_setting)
fsp_err_t	R_SCI_SMCI_StatusGet (smci_ctrl_t *const p_api_ctrl, smci_status_t *const p_status)
fsp_err_t	R_SCI_SMCI_ClockControl (smci_ctrl_t *const p_api_ctrl, bool clock_enable)
fsp_err_t	R_SCI_SMCI_CallbackSet (smci_ctrl_t *const p_api_ctrl, void(*p_callback)(smci_callback_args_t *), void const *const p_context, smci_callback_args_t *const p_callback_memory)
fsp_err_t	R_SCI_SMCI_Close (smci_ctrl_t *const p_api_ctrl)
fsp_err_t	R_SCI_SMCI_BaudCalculate (smci_speed_params_t const *const p_speed_params, uint32_t baud_rate_error_x_1000, void *const p_baud_setting)

Detailed Description

Driver for the SCI peripheral on RA MCUs. This module implements the SMCI Interface.

Overview

Features

The SCI SMCI module supports the following features:

• Abort in-progress read/write operations
• Interrupt-driven data transmission and reception
• Invoking the user-callback function with an event code (RX/TX complete, RX char, error, etc)
• Transfer mode (normal and block) and data convention type change at run time.
• All channels with SMCI support shall be configurable by the driver
• Baud-rate (and ETU) calculation and change based on ISO7816 asynchronous parameters at run-time. ETU is 1/baud.
• Error notifications of parity error, error signal reception (guard time) and overrun.
• Clock output control

Configuration

Build Time Configurations for r_sci_smci

The following build time configurations are defined in fsp_cfg/r_sci_smci_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.

Clock Configuration

The clock for this module is derived from the following peripheral clock for each MCU group:

MCU Group	Peripheral Clock
RA2A1	PCLKB
RA2A2	PCLKB
RA2E1	PCLKB
RA2E2	PCLKB
RA2E3	PCLKB
RA2L1	PCLKB
RA4E1	PCLKA
RA4E2	PCLKA
RA4M1	PCLKA
RA4M2	PCLKA
RA4M3	PCLKA
RA4T1	PCLKA
RA4W1	PCLKA
RA6E1	PCLKA
RA6E2	PCLKA
RA6M1	PCLKA
RA6M2	PCLKA
RA6M3	PCLKA
RA6M4	PCLKA
RA6M5	PCLKA
RA6T1	PCLKA
RA6T3	PCLKA

The clock source for the baud-rate clock generator is the PCLK. It is scaled by the SMR_SMCI.CKS bits to acheive the requested baud rate. This is done in R_SCI_SMCI_BaudSet routine.

Pin Configuration

This module uses TXDx and RXDx to communicate to external devices. TXDx and RXDx need to be tied together and pulled up to VCC externally via a pullup resistor and connected to the DATA line of a connected card.

The SmartCard clock signal is generated by the SMCI module on the SCKx pin. The clock frequency produced by the module is (baudrate * F) / D. The ISO specification defines the valid maximum frequency range as 4Mhz to 20MHz; only certain combinations of Fi, Di and f(max) are allowed.

When writing the application for the driver, the application developer must also allocate a software controlled Reset line via a GPIO. This will allow the reliable receipt of the ATR message. Optionally, VCC and VPP can also be controlled by a GPIO output, so that cold starts can be forced.

Usage Notes

The SMCI module is compliant to ISO7816-3. SMCI is a half duplex interface. Direct convention in T0 mode is the default. The driver supports both direct and indirect (inverted) modes of transmission. It also supports GSM mode in which the output clock can be enabled and disabled while the interface is still active. If it is known that the device connected is a device in inverse convention, the convention can be changed with smci_api_t::transferModeSet() after calling open.

The MCU creates the clock for the attached SMCI device based on the initial baudrate setting. Upon reset the SmartCard device advertises the Di and Fi parameters as well as the max clock speed it can handle. The Di and Fi parameters dictate at what rate the SmartCard device can sample the data line as a function of the supplied clock generated by the RA MCU. Only certain combinations of D and F are supported by the SMCI on SCI module. Only combinations where the the ratio of S=F/D corresponds to a value of S of 32, 64, 93, 128, 186, 256, 372, or 512 (for example see Table 27-9 RA4M2 Group User's Manual R01UH0892EJ0110 or the relevant section for the MCU being used).

The baud rate (1/ETU) can be changed while the device is open to allow for speed negotiation based on the attached device's capabilities.

The SMCI module does not contain a FIFO, and as such the receipt of multi-byte data has to be handled by interrupt initiated callback. The application developer must develop their callback so that the receipt of data is handled sufficiently without receiver overrun. If the read routine is called with a length=0, every receive interrupt will initiate a call to the user's callback. If the read is called with a non-zero length... the interrupt will fill the user's read buffer and initiate the callback after the last byte is complete. In many cases, the user can send an event from their callback so that the reading routine can wait for the event with a timeout. If a timeout occurs, the user can return the read state machine to an idle state by calling the read routine with a length of 0.

Limitations

Examples

SCI SMCI Example

uint8_t  g_dest[TRANSFER_LENGTH];
uint8_t  g_src[TRANSFER_LENGTH];
uint8_t  g_out_of_band_received[TRANSFER_LENGTH];
uint32_t g_transfer_complete = 0;
uint32_t g_receive_complete  = 0;
uint32_t g_out_of_band_index = 0;
void r_sci_smci_basic_example (void)
{
    /* Initialize g_src to known data */
    for (uint32_t i = 0; i < TRANSFER_LENGTH; i++)
    {
        g_src[i] = (uint8_t) ('A' + (i % 26));
    }


    /* Open the smci instance with initial configuration. */
    fsp_err_t err = R_SCI_SMCI_Open(&g_smci0_ctrl, &g_smci0_cfg);

    assert(FSP_SUCCESS == err);

    /* Need to have clock on inorder to receive or transmit*/
    R_SCI_SMCI_ClockControl(&g_smci0_ctrl, true);


    err = R_SCI_SMCI_Read(&g_smci0_ctrl, g_dest, TRANSFER_LENGTH);

    assert(FSP_SUCCESS == err);


    err = R_SCI_SMCI_Write(&g_smci0_ctrl, g_src, TRANSFER_LENGTH);

    assert(FSP_SUCCESS == err);

    while (!g_transfer_complete)
    {
    }

    while (!g_receive_complete)
    {
    }
}

void user_smci_callback (smci_callback_args_t * p_args)
{
    /* Handle the SMCI event */
    switch (p_args->event)
    {
        /* Received a character */
        case SMCI_EVENT_RX_CHAR:
        {
            /* Only put the next character in the receive buffer if there is space for it */
            if (sizeof(g_out_of_band_received) > g_out_of_band_index)
            {
                /* Write either the next one or two bytes depending on the receive data size */
                g_out_of_band_received[g_out_of_band_index++] = p_args->data;
            }

            break;
        }

        /* Receive complete */
        case SMCI_EVENT_RX_COMPLETE:
        {
            g_receive_complete = 1;
            break;
        }

        /* Transmit complete */
        case SMCI_EVENT_TX_COMPLETE:
        {
            g_transfer_complete = 1;
            break;
        }

        default:
        {
        }
    }
}

SCI SMCI Baud Set Example

#define SCI_SMCI_BAUDRATE_28800              (28800)
#define SCI_SMCI_BAUDRATE_ERROR_PERCENT_5    (5000)
void r_sci_smci_baud_example (void)
{
    smci_speed_params_t speed_settings;
    smci_baud_setting_t baud_setting;


    speed_settings.baudrate = SCI_SMCI_BAUDRATE_28800;
    speed_settings.fi       = SMCI_CLOCK_CONVERSION_INTEGER_512_5;
    speed_settings.di       = SMCI_BAUDRATE_ADJUSTMENT_INTEGER_4;

    fsp_err_t err = R_SCI_SMCI_BaudCalculate(&speed_settings, SCI_SMCI_BAUDRATE_ERROR_PERCENT_5, &baud_setting);
    assert(FSP_SUCCESS == err);


    err = R_SCI_SMCI_BaudSet(&g_smci0_ctrl, (void *) &baud_setting);
    assert(FSP_SUCCESS == err);
}

Data Structures
struct	sci_smci_instance_ctrl_t
struct	smci_baud_setting_t
struct	sci_smci_extended_cfg_t

---

Data Structure Documentation

sci_smci_instance_ctrl_t

struct sci_smci_instance_ctrl_t

SMCI instance control block.

smci_baud_setting_t

struct smci_baud_setting_t

Register settings to achieve a desired baud rate in Smart Card mode

Data Fields
uint32_t	computed_baud_rate
union smci_baud_setting_t	__unnamed__
uint8_t	scmr_bcp2: 1	BCP2 setting in Smart Card Mode Register.
uint8_t	brr	Bit Rate Register setting.

sci_smci_extended_cfg_t

struct sci_smci_extended_cfg_t

SMCI on SCI device Configuration

Data Fields
smci_baud_setting_t *	p_smci_baud_setting	Register settings for a desired baud rate.

Function Documentation

R_SCI_SMCI_Open()

fsp_err_t R_SCI_SMCI_Open	(	smci_ctrl_t *const	p_api_ctrl,
		smci_cfg_t const *const	p_cfg
	)

Configures the Smart Card Interface driver based on the input configurations. The interface stays in the clock-off state without enabling reception at the end of this function. ISO7816-3 default communication parameters are used to initial ize SMCI port speed and parameters, as the ATR message is always sent in that format. Only if Inverse convention is expected should the transfer mode be changed after reset. Implements smci_api_t::open

Parameters

[in,out]	p_api_ctrl	Pointer to SMCI control block that is to be opened
[in]	p_cfg	Pointer to the config structure that shall be used to set paramters of the SMCI baud calculations needed to be have done and set into p_cfg->p_extend->p_smci_baud_setting

Return values

FSP_SUCCESS	Channel opened successfully.
FSP_ERR_ASSERTION	Pointer to SMCI control block or configuration structure is NULL.
FSP_ERR_IP_CHANNEL_NOT_PRESENT	The requested channel does not exist on this MCU.
FSP_ERR_ALREADY_OPEN	Control block has already been opened or channel is being used by another instance. Call close() then open() to reconfigure.

Returns

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

R_SCI_SMCI_Write()

fsp_err_t R_SCI_SMCI_Write	(	smci_ctrl_t *const	p_api_ctrl,
		uint8_t const *const	p_src,
		uint32_t const	bytes
	)

Transmits user specified number of bytes from the source buffer pointer. Implements smci_api_t::write

Parameters

[in,out]	p_api_ctrl	Pointer to SMCI control block that is to be opened
[in]	p_src	Pointer to buffer that will be written out
[in]	bytes	Number of bytes to be transferred

Return values

FSP_SUCCESS	Data transmission started successfully.
FSP_ERR_ASSERTION	Pointer to SMCI control block is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened
FSP_ERR_IN_USE	A SMCI transmission is in progress

Returns

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

R_SCI_SMCI_Read()

fsp_err_t R_SCI_SMCI_Read	(	smci_ctrl_t *const	p_api_ctrl,
		uint8_t *const	p_dest,
		uint32_t const	bytes
	)

Receives user specified number of bytes into destination buffer pointer. Receiving is done at the isr level as there is no FIFO. If 0 is passed in as the length, reception will always invoke the user callback. Implements smci_api_t::read

Parameters

[in,out]	p_api_ctrl	Pointer to SMCI control block that is to be opened
[in,out]	p_dest	Pointer to the buffer top be read into
[in]	bytes	Number of bytes to copy from the SMCI receive register

Return values

FSP_SUCCESS	Data reception successfully ends.
FSP_ERR_ASSERTION	Pointer to SMCI control block or read buffer is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened
FSP_ERR_IN_USE	A previous read operation is still in progress.

Returns

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

R_SCI_SMCI_TransferModeSet()

fsp_err_t R_SCI_SMCI_TransferModeSet	(	smci_ctrl_t *const	p_api_ctrl,
		smci_transfer_mode_t const *const	p_transfer_mode_params
	)

Updates the settings of block transfer mode and data transfer convention. The SCMR and SMR_SMCI registers will be set according to the input arguments of protocol type, data convention type, and mode. Implements smci_api_t::transferModeSet

Parameters

[in,out]	p_api_ctrl	Pointer to SMCI control block that is to be modified
[in]	p_transfer_mode_params	Pointer to SMCI settings like protocol, convention, and gsm_mode

Warning

This terminates any in-progress transmission and reception.

Return values

FSP_SUCCESS	Transfer mode and data transfer direction was successfully changed.
FSP_ERR_IN_USE	Unable to change transfer mode as device has clock off or is actively RX or TX
FSP_ERR_ASSERTION	Null pointer was passed as a parameter
FSP_ERR_NOT_OPEN	The control block has not been opened

Returns

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

R_SCI_SMCI_BaudSet()

fsp_err_t R_SCI_SMCI_BaudSet	(	smci_ctrl_t *const	p_api_ctrl,
		void const *const	p_baud_setting
	)

Updates the baud rate and clock output. p_baud_setting is a pointer to a smci_baud_setting_t structure that needs to have already been filled by R_SCI_SMCI_BaudCalculate Implements smci_api_t::baudSet

Warning

This terminates any in-progress transmission.

Parameters

[in,out]	p_api_ctrl	Pointer to SMCI control block that is to be modified
[in]	p_baud_setting	Pointer to baud setting information to be written to the SMCI hardware registers

Return values

FSP_SUCCESS	Baud rate was successfully changed.
FSP_ERR_ASSERTION	Pointer to SMCI control block or p_baud_setting is NUL
FSP_ERR_NOT_OPEN	The control block has not been opened
FSP_ERR_INVALID_ARGUMENT	The p_baud_setting does not seem to be set correctly

R_SCI_SMCI_StatusGet()

fsp_err_t R_SCI_SMCI_StatusGet	(	smci_ctrl_t *const	p_api_ctrl,
		smci_status_t *const	p_status
	)

Provides the state of the driver and the # of bytes received since read was called Implements smci_api_t::statusGet

Parameters

[in]	p_api_ctrl	Pointer to SMCI control block of this SMCI instance
[out]	p_status	Pointer structure that will be filled in with status info

Return values

FSP_SUCCESS	Information stored in provided p_info.
FSP_ERR_ASSERTION	Pointer to SMCI control block, or info structure is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened

R_SCI_SMCI_ClockControl()

fsp_err_t R_SCI_SMCI_ClockControl	(	smci_ctrl_t *const	p_api_ctrl,
		bool	clock_enable
	)

Enable or disable the clock signal that is provided by interface the baud rate. When the clock is enabled, reception is enabled at the end of this function. "Clock output control as defined in section 34.6.8 "Clock Output Control in Smart Card Interface Mode" in the RA6M3 manual R01UH0886EJ0100 or the relevant section for the MCU being used. Implements smci_api_t::clockControl

Warning

This terminates any in-progress transmission and reception.

Parameters

[in,out]	p_api_ctrl	Pointer to SMCI control block
[in]	clock_enable	true=Enable or false=disable the Smart Card Interface clock

Return values

FSP_SUCCESS	Clock output setting was successfully changed.
FSP_ERR_ASSERTION	Pointer to SMCI control block is NULL
FSP_ERR_NOT_OPEN	The control block has not been opened
FSP_ERR_INVALID_MODE	Clock cannot be disabled if GSM mode isnt active

R_SCI_SMCI_CallbackSet()

fsp_err_t R_SCI_SMCI_CallbackSet	(	smci_ctrl_t *const	p_api_ctrl,
		void(*)(smci_callback_args_t *)	p_callback,
		void const *const	p_context,
		smci_callback_args_t *const	p_callback_memory
	)

Updates the user callback and has option of providing memory for callback structure. Implements smci_api_t::callbackSet

Return values

FSP_SUCCESS	Callback updated successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.
FSP_ERR_NO_CALLBACK_MEMORY	p_callback is non-secure and p_callback_memory is either secure or NULL.

R_SCI_SMCI_Close()

fsp_err_t R_SCI_SMCI_Close

(

smci_ctrl_t *const

p_api_ctrl

)

Aborts any in progress transfers. Disables interrupts, receiver, and transmitter. Implements smci_api_t::close

Parameters

[in]

p_api_ctrl

Pointer to SMCI control block that is reqested to close

Return values

FSP_SUCCESS	Channel successfully closed.
FSP_ERR_ASSERTION	Pointer to SMCI control block is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened

R_SCI_SMCI_BaudCalculate()

fsp_err_t R_SCI_SMCI_BaudCalculate	(	smci_speed_params_t const *const	p_speed_params,
		uint32_t	baud_rate_error_x_1000,
		void *const	p_baud_setting
	)

Calculates baud rate register settings. Evaluates and determines the best possible settings set to the baud rate related registers. And then updates the SCI registers.

Parameters

[in]	p_speed_params	structure including speed defining paramets, baud, F, D, and max frequency
[in]	baud_rate_error_x_1000	<baud_rate_percent_error> x 1000 required for module to function. Absolute max baud_rate_error is 20000 (20%) according to the ISO spec.
[out]	p_baud_setting	Baud setting information stored here if successful

Return values

FSP_SUCCESS	Baud rate setting calculation successful
FSP_ERR_ASSERTION	p_speed params or p_baud is a null pointer
FSP_ERR_INVALID_ARGUMENT	Baud rate is '0', freq is '0', or error in calculated baud rate is larger than 20%.