Detailed Description

Interface for SMCI communications.

Summary

The SMCI interface provides common APIs for SMCI HAL drivers. The SMCI interface supports the following features:

Interrupt driven transmit/receive processing
Callback function with returned event code
Runtime baud-rate change (baud = 1/ETU)
Hardware resource locking during a transaction

Data Structures
struct	smci_status_t

struct	smci_transfer_mode_t

struct	smci_speed_params_t

struct	smci_callback_args_t

struct	smci_cfg_t

struct	smci_api_t

struct	smci_instance_t

Typedefs
typedef void	smci_ctrl_t

Enumerations
enum	smci_state_t

enum	smci_event_t

enum	smci_convention_type_t

enum	smci_clock_conversion_integer_t

enum	smci_baudrate_adjustment_integer_t

enum	smci_protocol_type_t

Data Structure Documentation

◆ smci_status_t

struct smci_status_t

SMCI driver specific information

Data Fields
smci_state_t	smci_state	State ot the smci state machine.
uint32_t	bytes_recvd	Bytes read into receive buffer since read was called.

◆ smci_transfer_mode_t

struct smci_transfer_mode_t

SMCI Transfer Mode settings

Data Fields
smci_protocol_type_t	protocol	Protocol (Normal t=0, or Block t=1)
smci_convention_type_t	convention	Convention Direct or Inverse.
bool	gsm_mode	True=GMS Mode, false=Normal.

◆ smci_speed_params_t

struct smci_speed_params_t

SMCI settings that are used as inputs to register setting calculations

Data Fields
uint32_t	baudrate	Bits per second requested, 1/ETU.
smci_baudrate_adjustment_integer_t	di	Referred to as D in ISO spec (from Table 8 in ISO7816-3 3rd Edition)
smci_clock_conversion_integer_t	fi	Index of in ISO spec (from Table 8 in ISO7816-3 3rd Edition)

◆ smci_callback_args_t

struct smci_callback_args_t

SMCI Callback parameter definition

Data Fields
uint32_t	channel	Device channel number.
smci_event_t	event	Event code.
uint8_t	data	Data Byte to process. Contains the next character received for the events SMCI_EVENT_RX_CHAR, SMCI_EVENT_ERR_PARITY, SMCI_EVENT_ERR_LOW_SIGNAL, or SMCI_EVENT_ERR_OVERRUN. Otherwise unused.
void const *	p_context	Context provided to user during callback.

◆ smci_cfg_t

struct smci_cfg_t

Configuration Structure for SMCI

Data Fields
uint8_t	channel
	Channel number of the hardware.

uint8_t	rxi_ipl
	Receive interrupt priority.

uint8_t	txi_ipl
	Transmit interrupt priority.

uint8_t	eri_ipl
	Error interrupt priority.

IRQn_Type	rxi_irq
	Receive interrupt IRQ number.

IRQn_Type	txi_irq
	Transmit interrupt IRQ number.

IRQn_Type	eri_irq
	Error interrupt IRQ number.

void(*	p_callback )(smci_callback_args_t *p_args)
	Pointer to callback function.

void const *	p_context
	User defined context passed into callback function.

void const *	p_extend
	SMCI hardware dependent configuration.

◆ smci_api_t

struct smci_api_t

Shared Interface definition for SMCI

Data Fields
fsp_err_t(*	open )(smci_ctrl_t const p_ctrl, smci_cfg_t const const p_cfg)

fsp_err_t(*	read )(smci_ctrl_t const p_ctrl, uint8_t const p_dest, uint32_t const bytes)

fsp_err_t(*	write )(smci_ctrl_t const p_ctrl, uint8_t const const p_src, uint32_t const bytes)

fsp_err_t(*	transferModeSet )(smci_ctrl_t const p_ctrl, smci_transfer_mode_t const const p_transfer_mode_params)

fsp_err_t(*	baudSet )(smci_ctrl_t const p_ctrl, void const const p_baud_setting)

fsp_err_t(*	statusGet )(smci_ctrl_t const p_ctrl, smci_status_t const p_status)

fsp_err_t(*	clockControl )(smci_ctrl_t *const p_ctrl, bool clock_enable)

fsp_err_t(*	callbackSet )(smci_ctrl_t const p_ctrl, void(p_callback)(smci_callback_args_t ), void const const p_context, smci_callback_args_t *const p_callback_memory)

fsp_err_t(*	close )(smci_ctrl_t *const p_ctrl)

Field Documentation

◆ open

fsp_err_t(* smci_api_t::open) (smci_ctrl_t *const p_ctrl, smci_cfg_t const *const p_cfg)

Open Smart Card Interface Mode (SMCI)

Parameters

[in,out]	p_ctrl	Pointer to the SMCI control block. Must be declared by user. Value set here.
[in]	smci_cfg_t	Pointer to SMCI configuration structure. All elements of this structure must be set by user.

◆ read

fsp_err_t(* smci_api_t::read) (smci_ctrl_t *const p_ctrl, uint8_t *const p_dest, uint32_t const bytes)

Read from Smart Card device. The read buffer is used until the read is complete. When a transfer is complete, the callback is called with event SMCI_EVENT_RX_COMPLETE. Bytes received outside an active transfer are received in the callback function with event SMCI_EVENT_RX_CHAR.

Parameters

[in]	p_ctrl	Pointer to the SMCI control block for the channel.
[in]	p_dest	Destination address to read data from.
[in]	bytes	Read data length.

◆ write

fsp_err_t(* smci_api_t::write) (smci_ctrl_t *const p_ctrl, uint8_t const *const p_src, uint32_t const bytes)

Write to Smart Card device. The write buffer is used until write is complete. Do not overwrite write buffer contents until the write is finished. When the write is complete (all bytes are fully transmitted on the wire), the callback called with event SMCI_EVENT_TX_COMPLETE.

Parameters

[in]	p_ctrl	Pointer to the SMCI control block.
[in]	p_src	Source address to write data to.
[in]	bytes	Write data length.

◆ transferModeSet

fsp_err_t(* smci_api_t::transferModeSet) (smci_ctrl_t *const p_ctrl, smci_transfer_mode_t const *const p_transfer_mode_params)

Change the peripheral settings based on provided transfer mode and data convention type

Parameters

[in]	p_ctrl	Pointer to the SMCI control block.
[in]	p_transfer_mode_params	Pointer to SMCI setting like protocol, convention, and gsm_mode

◆ baudSet

fsp_err_t(* smci_api_t::baudSet) (smci_ctrl_t *const p_ctrl, void const *const p_baud_setting)

Change baud rate.

Warning: Calling this API aborts any in-progress transmission and disables reception until the new baud settings have been applied.

Parameters

[in]	p_ctrl	Pointer to the SMCI control block.
[in]	p_baud_setting	Pointer to module specific setting for configuring baud rate.

◆ statusGet

fsp_err_t(* smci_api_t::statusGet) (smci_ctrl_t *const p_ctrl, smci_status_t *const p_status)

Get the driver specific information.

Parameters

[in]	p_ctrl	Pointer to the SMCI control block.
[out]	p_status	State info for the driver.

◆ clockControl

fsp_err_t(* smci_api_t::clockControl) (smci_ctrl_t *const p_ctrl, bool clock_enable)

Enable or disable the SMCI clock to control the start of the activation or de-activation

Parameters

[in]	p_ctrl	Pointer to the SMCI control block.
[in]	clock_enable	True: enables clock output, False disables it

◆ callbackSet

fsp_err_t(* smci_api_t::callbackSet) (smci_ctrl_t *const p_ctrl, void(*p_callback)(smci_callback_args_t *), void const *const p_context, smci_callback_args_t *const p_callback_memory)

Specify callback function and optional context pointer and callback memory pointer.

Parameters

[in]	p_ctrl	Pointer to the SMCI control block.
[in]	p_callback	Callback function
[in]	p_context	Pointer to send to callback function
[in]	p_callback_memory	Pointer to volatile memory where callback structure can be allocated. Callback arguments allocated here are only valid during the callback.

◆ close

fsp_err_t(* smci_api_t::close) (smci_ctrl_t *const p_ctrl)

Close SMCI device.

Parameters

[in] p_ctrl Pointer to the SMCI control block.

◆ smci_instance_t

struct smci_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
smci_ctrl_t *	p_ctrl	Pointer to the control structure for this instance.
smci_cfg_t const *	p_cfg	Pointer to the configuration structure for this instance.
smci_api_t const *	p_api	Pointer to the API structure for this instance.

Typedef Documentation

◆ smci_ctrl_t

typedef void smci_ctrl_t

Smart Card Interface control block. Allocate an instance specific control block to pass into the SMCI API calls.

Enumeration Type Documentation

◆ smci_state_t

enum smci_state_t

Enumerator
SMCI_STATE_IDLE_CLOCK_OFF	SMCI idle state with no clock output.
SMCI_STATE_TX_RX_IDLE	SMCI is in idle state, clock is active.
SMCI_STATE_TX_PROGRESSING	Transmission is in progress.
SMCI_STATE_RX_PROGRESSING	Reception is in progress.

◆ smci_event_t

enum smci_event_t

SMCI Event codes

Enumerator
SMCI_EVENT_RX_COMPLETE	Receive complete event.
SMCI_EVENT_TX_COMPLETE	Transmit complete event.
SMCI_EVENT_RX_CHAR	Character transfer is completed.
SMCI_EVENT_ERR_PARITY	Parity error event.
SMCI_EVENT_ERR_LOW_SIGNAL	Low error signal response occurred event.
SMCI_EVENT_ERR_OVERRUN	Overrun error event.

◆ smci_convention_type_t

enum smci_convention_type_t

Enumerator
SMCI_CONVENTION_TYPE_DIRECT	Direct convention type (LSB First, High=1)
SMCI_CONVENTION_TYPE_INVERSE	Inverse convention type (MSB First, Low=1)

◆ smci_clock_conversion_integer_t

enum smci_clock_conversion_integer_t

Enumerator
SMCI_CLOCK_CONVERSION_INTEGER_372_4	372 base cycles for 1-bit period, max freq = 4Mhz
SMCI_CLOCK_CONVERSION_INTEGER_372_5	372 base cycles for 1-bit period, max freq = 5Mhz
SMCI_CLOCK_CONVERSION_INTEGER_558_6	558 base cycles for 1-bit period, max freq = 6Mhz
SMCI_CLOCK_CONVERSION_INTEGER_744_8	744 base cycles for 1-bit period, max freq = 8Mhz
SMCI_CLOCK_CONVERSION_INTEGER_1116_12	1116 base cycles for 1-bit period, max freq = 12Mhz
SMCI_CLOCK_CONVERSION_INTEGER_1488_16	1488 base cycles for 1-bit period, max freq = 16Mhz
SMCI_CLOCK_CONVERSION_INTEGER_1860_20	1860 base cycles for 1-bit period, max freq = 20Mhz
SMCI_CLOCK_CONVERSION_INTEGER_UNSUPPORTED7	Unsupported Clock Cycles.
SMCI_CLOCK_CONVERSION_INTEGER_UNSUPPORTED8	Unsupported Clock Cycles.
SMCI_CLOCK_CONVERSION_INTEGER_512_5	512 base cycles for 1-bit period, max freq = 5Mhz
SMCI_CLOCK_CONVERSION_INTEGER_768_75	768 base cycles for 1-bit period, max freq = 7.5Mhz
SMCI_CLOCK_CONVERSION_INTEGER_1024_10	1024 base cycles for 1-bit period, max freq = 10Mhz
SMCI_CLOCK_CONVERSION_INTEGER_1536_15	1536 base cycles for 1-bit period, max freq = 15Mhz
SMCI_CLOCK_CONVERSION_INTEGER_2048_20	2048 base cycles for 1-bit period, max freq = 20Mhz
SMCI_CLOCK_CONVERSION_INTEGER_UNSUPPORTED14	Unsupported Clock Cycles.
SMCI_CLOCK_CONVERSION_INTEGER_UNSUPPORTED15	Unsupported Clock Cycles.

◆ smci_baudrate_adjustment_integer_t

enum smci_baudrate_adjustment_integer_t

Enumerator
SMCI_BAUDRATE_ADJUSTMENT_INTEGER_RFU0	RESERVED.
SMCI_BAUDRATE_ADJUSTMENT_INTEGER_1	Di=1.
SMCI_BAUDRATE_ADJUSTMENT_INTEGER_2	Di=2.
SMCI_BAUDRATE_ADJUSTMENT_INTEGER_4	Di=4.
SMCI_BAUDRATE_ADJUSTMENT_INTEGER_8	Di=8.
SMCI_BAUDRATE_ADJUSTMENT_INTEGER_16	Di=16.
SMCI_BAUDRATE_ADJUSTMENT_INTEGER_32	Di=32.
SMCI_BAUDRATE_ADJUSTMENT_INTEGER_64	Di=64.
SMCI_BAUDRATE_ADJUSTMENT_INTEGER_12	Di=12.
SMCI_BAUDRATE_ADJUSTMENT_INTEGER_20	Di=20.
SMCI_BAUDRATE_ADJUSTMENT_INTEGER_RFU10	RESERVED.
SMCI_BAUDRATE_ADJUSTMENT_INTEGER_RFU11	RESERVED.
SMCI_BAUDRATE_ADJUSTMENT_INTEGER_RFU12	RESERVED.
SMCI_BAUDRATE_ADJUSTMENT_INTEGER_RFU13	RESERVED.
SMCI_BAUDRATE_ADJUSTMENT_INTEGER_RFU14	RESERVED.
SMCI_BAUDRATE_ADJUSTMENT_INTEGER_RFU15	RESERVED.

◆ smci_protocol_type_t

enum smci_protocol_type_t

SMCI Protocol Type according to ISO7816-3

Enumerator
SMCI_PROTOCOL_TYPE_T0	Normal mode operation (Protocol T = 0)
SMCI_PROTOCOL_TYPE_T1	Block transfer mode operation (Protocol T = 1)

Detailed Description

Summary

Data Structures

Typedefs

Enumerations

Data Structure Documentation

◆ smci_status_t

◆ smci_transfer_mode_t

◆ smci_speed_params_t

◆ smci_callback_args_t

◆ smci_cfg_t

Data Fields

◆ smci_api_t

Data Fields

Field Documentation

◆ open

◆ read

◆ write

◆ transferModeSet

◆ baudSet

◆ statusGet

◆ clockControl

◆ callbackSet

◆ close

◆ smci_instance_t

Typedef Documentation

◆ smci_ctrl_t

Enumeration Type Documentation

◆ smci_state_t

◆ smci_event_t

◆ smci_convention_type_t

◆ smci_clock_conversion_integer_t

◆ smci_baudrate_adjustment_integer_t

◆ smci_protocol_type_t