| Kinetis SDK v.2.0 API Reference Manual Rev. 0 Freescale Semiconductor, Inc.

- Main Page
- Related Pages
- API Reference

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Files | Data Structures | Macros | Typedefs | Enumerations
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:

- Smart Card voltage class
- Smart Card Interface options such as the RST, IRQ, CLK pins, and so on.

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

enum smartcard_status_t

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.

enum smartcard_control_t

enum smartcard_direction_t