Kinetis SDK v.2.0 API Reference Manual  Rev. 0
Freescale Semiconductor, Inc.
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Smart Card

Overview

The Kinetis SDK provides Peripheral drivers for the UART-ISO7816 and EMVSIM modules of Kinetis devices.

Smart Card driver provides the necessary functions to access and control integrated circuit cards. The driver controls communication modules (UART/EMVSIM) and handles special ICC sequences, such as the activation/deactivation (using EMVSIM IP or external interface chip). The Smart Card driver consists of two IPs (SmartCard_Uart and SmartCard_EmvSim drivers) and three PHY drivers (smartcard_phy_emvsim, smartcard_phy_ncn8025 and smartcard_phy_gpio drivers). These drivers can be combined, which means that the Smart Card driver wraps one IP (transmission) and one PHY (interface) driver.

The driver provides asynchronous functions to communicate with the Integrated Circuit Card (ICC). The driver contains RTOS adaptation layers which use semaphores as synchronization objects of synchronous transfers. The RTOS driver support also provides protection for multithreading.

SmartCard Driver Initialization

The Smart Card Driver is initialized by calling the SMARTCARD_Init() and SMARTCARD_PHY_Init() functions. The Smart Card Driver initialization configuration structure requires these settings:

The driver also supports user callbacks for assertion/de-assertion Smart Card events and transfer finish event. This feature is useful to detect the card presence or for handling transfer events i.e., in RTOS. The user should initialize the Smart Card driver, which consist of IP and PHY drivers.

SmartCard Call diagram

Because the call diagram is complex, the detailed use of the Smart Card driver is not described in this section. For details about using the Smart Card driver, see the Smart Card driver example which describes a simple use case.

PHY driver

The Smart Card interface driver is initialized by calling the function SMARTCARD_PHY_Init(). During the initialization phase, Smart Card clock is configured and all hardware pins for IC handling are configured.

Modules

 Smart Card EMVSIM Driver
 
 Smart Card FreeRTOS Driver
 
 Smart Card PHY EMVSIM Driver
 
 Smart Card PHY GPIO Driver
 
 Smart Card PHY NCN8025 Driver
 
 Smart Card UART Driver
 
 Smart Card µCOS/II Driver
 
 Smart Card µCOS/III Driver
 

Files

file  fsl_smartcard.h
 

Data Structures

struct  smartcard_card_params_t
 Defines card-specific parameters for Smart card driver. More...
 
struct  smartcard_timers_state_t
 Smart card Defines the state of the EMV timers in the Smart card driver. More...
 
struct  smartcard_interface_config_t
 Defines user specified configuration of Smart card interface. More...
 
struct  smartcard_xfer_t
 Defines user transfer structure used to initialize transfer. More...
 
struct  smartcard_context_t
 Runtime state of the Smart card driver. More...
 

Macros

#define SMARTCARD_INIT_DELAY_CLOCK_CYCLES   (42000u)
 Smart card global define which specify number of clock cycles until initial 'TS' character has to be received.
 
#define SMARTCARD_EMV_ATR_DURATION_ETU   (20150u)
 Smart card global define which specify number of clock cycles during which ATR string has to be received.
 
#define SMARTCARD_TS_DIRECT_CONVENTION   (0x3Bu)
 Smart card specification initial TS character definition of direct convention.
 
#define SMARTCARD_TS_INVERSE_CONVENTION   (0x3Fu)
 Smart card specification initial TS character definition of inverse convention.
 

Typedefs

typedef void(* smartcard_interface_callback_t )(void *smartcardContext, void *param)
 Smart card interface interrupt callback function type.
 
typedef void(* smartcard_transfer_callback_t )(void *smartcardContext, void *param)
 Smart card transfer interrupt callback function type.
 
typedef void(* smartcard_time_delay_t )(uint32_t miliseconds)
 Time Delay function used to passive waiting using RTOS [ms].
 

Enumerations

enum  smartcard_status_t {
  kStatus_SMARTCARD_Success = MAKE_STATUS(kStatusGroup_SMARTCARD, 0),
  kStatus_SMARTCARD_TxBusy = MAKE_STATUS(kStatusGroup_SMARTCARD, 1),
  kStatus_SMARTCARD_RxBusy = MAKE_STATUS(kStatusGroup_SMARTCARD, 2),
  kStatus_SMARTCARD_NoTransferInProgress = MAKE_STATUS(kStatusGroup_SMARTCARD, 3),
  kStatus_SMARTCARD_Timeout = MAKE_STATUS(kStatusGroup_SMARTCARD, 4),
  kStatus_SMARTCARD_Initialized = MAKE_STATUS(kStatusGroup_SMARTCARD, 5),
  kStatus_SMARTCARD_PhyInitialized = MAKE_STATUS(kStatusGroup_SMARTCARD, 6),
  kStatus_SMARTCARD_CardNotActivated = MAKE_STATUS(kStatusGroup_SMARTCARD, 7),
  kStatus_SMARTCARD_InvalidInput = MAKE_STATUS(kStatusGroup_SMARTCARD, 8),
  kStatus_SMARTCARD_OtherError = MAKE_STATUS(kStatusGroup_SMARTCARD, 9)
}
 Smart card Error codes. More...
 
enum  smartcard_control_t
 Control codes for the Smart card protocol timers and misc. More...
 
enum  smartcard_card_voltage_class_t
 Defines Smart card interface voltage class values.
 
enum  smartcard_transfer_state_t
 Defines Smart card I/O transfer states.
 
enum  smartcard_reset_type_t
 Defines Smart card reset types.
 
enum  smartcard_transport_type_t
 Defines Smart card transport protocol types.
 
enum  smartcard_parity_type_t
 Defines Smart card data parity types.
 
enum  smartcard_card_convention_t
 Defines data Convention format.
 
enum  smartcard_interface_control_t
 Defines Smart card interface IC control types.
 
enum  smartcard_direction_t
 Defines transfer direction. More...
 

Driver version

#define FSL_SMARTCARD_DRIVER_VERSION   (MAKE_VERSION(2, 1, 0))
 Smart card driver version 2.1.0. More...
 

Data Structure Documentation

struct smartcard_card_params_t

Data Fields

uint16_t Fi
 4 bits Fi - clock rate conversion integer
 
uint8_t fMax
 Maximum Smart card frequency in MHz.
 
uint8_t WI
 8 bits WI - work wait time integer
 
uint8_t Di
 4 bits DI - baud rate divisor
 
uint8_t BWI
 4 bits BWI - block wait time integer
 
uint8_t CWI
 4 bits CWI - character wait time integer
 
uint8_t BGI
 4 bits BGI - block guard time integer
 
uint8_t GTN
 8 bits GTN - extended guard time integer
 
uint8_t IFSC
 Indicates IFSC value of the card.
 
uint8_t modeNegotiable
 Indicates if the card acts in negotiable or a specific mode. More...
 
uint8_t currentD
 4 bits DI - current baud rate divisor
 
uint8_t status
 Indicates smart card status.
 
bool t0Indicated
 Indicates ff T=0 indicated in TD1 byte.
 
bool t1Indicated
 Indicates if T=1 indicated in TD2 byte.
 
bool atrComplete
 Indicates whether the ATR received from the card was complete or not.
 
bool atrValid
 Indicates whether the ATR received from the card was valid or not.
 
bool present
 Indicates if a smart card is present.
 
bool active
 Indicates if the smart card is activated.
 
bool faulty
 Indicates whether smart card/interface is faulty.
 
smartcard_card_convention_t convention
 Card convention, kSMARTCARD_DirectConvention for direct convention, kSMARTCARD_InverseConvention for inverse convention.
 

Field Documentation

uint8_t smartcard_card_params_t::modeNegotiable
struct smartcard_timers_state_t

Data Fields

volatile bool adtExpired
 Indicates whether ADT timer expired.
 
volatile bool wwtExpired
 Indicates whether WWT timer expired.
 
volatile bool cwtExpired
 Indicates whether CWT timer expired.
 
volatile bool bwtExpired
 Indicates whether BWT timer expired.
 
volatile bool initCharTimerExpired
 Indicates whether reception timer for initialization character (TS) after the RST has expired.
 
struct smartcard_interface_config_t

Data Fields

uint32_t smartCardClock
 Smart card interface clock [Hz].
 
uint32_t clockToResetDelay
 Indicates clock to RST apply delay [smart card clock cycles].
 
uint8_t clockModule
 Smart card clock module number.
 
uint8_t clockModuleChannel
 Smart card clock module channel number.
 
uint8_t clockModuleSourceClock
 Smart card clock module source clock [e.g., BusClk].
 
smartcard_card_voltage_class_t vcc
 Smart card voltage class.
 
uint8_t controlPort
 Smart card PHY control port instance.
 
uint8_t controlPin
 Smart card PHY control pin instance.
 
uint8_t irqPort
 Smart card PHY Interrupt port instance.
 
uint8_t irqPin
 Smart card PHY Interrupt pin instance.
 
uint8_t resetPort
 Smart card reset port instance.
 
uint8_t resetPin
 Smart card reset pin instance.
 
uint8_t vsel0Port
 Smart card PHY Vsel0 control port instance.
 
uint8_t vsel0Pin
 Smart card PHY Vsel0 control pin instance.
 
uint8_t vsel1Port
 Smart card PHY Vsel1 control port instance.
 
uint8_t vsel1Pin
 Smart card PHY Vsel1 control pin instance.
 
uint8_t dataPort
 Smart card PHY data port instance.
 
uint8_t dataPin
 Smart card PHY data pin instance.
 
uint8_t dataPinMux
 Smart card PHY data pin mux option.
 
uint8_t tsTimerId
 Numerical identifier of the External HW timer for Initial character detection.
 
struct smartcard_xfer_t

Data Fields

smartcard_direction_t direction
 Direction of communication. More...
 
uint8_t * buff
 The buffer of data. More...
 
size_t size
 The number of transferred units. More...
 

Field Documentation

smartcard_direction_t smartcard_xfer_t::direction

(RX/TX)

uint8_t* smartcard_xfer_t::buff
size_t smartcard_xfer_t::size
struct smartcard_context_t

Data Fields

void * base
 Smart card module base address.
 
smartcard_direction_t direction
 Direction of communication. More...
 
uint8_t * xBuff
 The buffer of data being transferred. More...
 
volatile size_t xSize
 The number of bytes to be transferred. More...
 
volatile bool xIsBusy
 True if there is an active transfer. More...
 
uint8_t txFifoEntryCount
 Number of data word entries in transmit FIFO. More...
 
smartcard_interface_callback_t interfaceCallback
 Callback to invoke after interface IC raised interrupt. More...
 
smartcard_transfer_callback_t transferCallback
 Callback to invoke after transfer event occur. More...
 
void * interfaceCallbackParam
 Interface callback parameter pointer. More...
 
void * transferCallbackParam
 Transfer callback parameter pointer. More...
 
smartcard_time_delay_t timeDelay
 Function which handles time delay defined by user or RTOS. More...
 
smartcard_reset_type_t resetType
 Indicates whether a Cold reset or Warm reset was requested. More...
 
smartcard_transport_type_t tType
 Indicates current transfer protocol (T0 or T1)
 
volatile smartcard_transfer_state_t transferState
 Indicates the current transfer state.
 
smartcard_timers_state_t timersState
 Indicates the state of different protocol timers used in driver.
 
smartcard_card_params_t cardParams
 Smart card parameters(ATR and current) and interface slots states(ATR and current)
 
uint8_t IFSD
 Indicates the terminal IFSD.
 
smartcard_parity_type_t parity
 Indicates current parity even/odd.
 
volatile bool rxtCrossed
 Indicates whether RXT thresholds has been crossed.
 
volatile bool txtCrossed
 Indicates whether TXT thresholds has been crossed.
 
volatile bool wtxRequested
 Indicates whether WTX has been requested or not.
 
volatile bool parityError
 Indicates whether a parity error has been detected.
 
uint8_t statusBytes [2]
 Used to store Status bytes SW1, SW2 of the last executed card command response.
 
smartcard_interface_config_t interfaceConfig
 Smart card interface configuration structure.
 

Field Documentation

smartcard_direction_t smartcard_context_t::direction

(RX/TX)

uint8_t* smartcard_context_t::xBuff
volatile size_t smartcard_context_t::xSize
volatile bool smartcard_context_t::xIsBusy
uint8_t smartcard_context_t::txFifoEntryCount
smartcard_interface_callback_t smartcard_context_t::interfaceCallback
smartcard_transfer_callback_t smartcard_context_t::transferCallback
void* smartcard_context_t::interfaceCallbackParam
void* smartcard_context_t::transferCallbackParam
smartcard_time_delay_t smartcard_context_t::timeDelay
smartcard_reset_type_t smartcard_context_t::resetType

Macro Definition Documentation

#define FSL_SMARTCARD_DRIVER_VERSION   (MAKE_VERSION(2, 1, 0))

Enumeration Type Documentation

Enumerator
kStatus_SMARTCARD_Success 

Transfer ends successfully.

kStatus_SMARTCARD_TxBusy 

Transmit in progress.

kStatus_SMARTCARD_RxBusy 

Receiving in progress.

kStatus_SMARTCARD_NoTransferInProgress 

No transfer in progress.

kStatus_SMARTCARD_Timeout 

Transfer ends with time-out.

kStatus_SMARTCARD_Initialized 

Smart card driver is already initialized.

kStatus_SMARTCARD_PhyInitialized 

Smart card PHY drive is already initialized.

kStatus_SMARTCARD_CardNotActivated 

Smart card is not activated.

kStatus_SMARTCARD_InvalidInput 

Function called with invalid input arguments.

kStatus_SMARTCARD_OtherError 

Some other error occur.