M480 BSP V3.05.006
The Board Support Package for M480 Series
Functions | Variables

Functions

int32_t SCLIB_Activate (uint32_t num, uint32_t u32EMVCheck)
 Activate a smartcard. More...
 
int32_t SCLIB_ActivateDelay (uint32_t num, uint32_t u32EMVCheck, uint32_t u32Delay)
 Activate a smartcard with large delay between set VCC high and start CLK output. More...
 
int32_t SCLIB_ColdReset (uint32_t num)
 Cold reset a smartcard. More...
 
int32_t SCLIB_WarmReset (uint32_t num)
 Warm reset a smartcard. More...
 
void SCLIB_Deactivate (uint32_t num)
 Deactivate a smartcard. More...
 
int32_t SCLIB_GetCardInfo (uint32_t num, SCLIB_CARD_INFO_T *s_info)
 Get the card information (e.g., protocol selected, ATR...) after activation success. More...
 
int32_t SCLIB_StartTransmission (uint32_t num, uint8_t *cmdBuf, uint32_t cmdLen, uint8_t *rspBuf, uint32_t *rspLen)
 Start a smartcard transmission. More...
 
int32_t SCLIB_SetIFSD (uint32_t num, uint8_t size)
 Set interface device max information field size (IFSD) More...
 
__weak void SCLIB_RequestTimeExtension (uint32_t u32Protocol)
 A callback called by library while smartcard request for a time extension. More...
 
uint32_t SCLIB_CheckCDEvent (uint32_t num)
 Process card detect event in IRQ handler. More...
 
uint32_t SCLIB_CheckTimeOutEvent (uint32_t num)
 Process time out event in IRQ handler. More...
 
uint32_t SCLIB_CheckTxRxEvent (uint32_t num)
 Process card transmission event in IRQ handler. More...
 
uint32_t SCLIB_CheckErrorEvent (uint32_t num)
 Process error event in IRQ handler. More...
 
int32_t SCLIB_ResetAnyway (uint32_t num)
 Activate a smartcard without historical bytes check, this function can be called if SCLIB_Activate or SCLIB_ActivateDelay return an error. More...
 
int32_t SCLIB_SetSpecificAtrBR (uint32_t num, uint32_t br)
 Set a specific baud rate to catch ATR for a card which is not compatible with ISO-7816, this function should be called before SCLIB_Activate or SCLIB_ActivateDelay. More...
 

Variables

uint32_t SCLIB_CARD_INFO_T::T
 
uint32_t SCLIB_CARD_INFO_T::ATR_Len
 
uint8_t SCLIB_CARD_INFO_T::ATR_Buf [SCLIB_MAX_ATR_LEN]
 

Detailed Description

Function Documentation

◆ SCLIB_Activate()

int32_t SCLIB_Activate ( uint32_t  num,
uint32_t  u32EMVCheck 
)

Activate a smartcard.

Parameters
[in]numSmartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
[in]u32EMVCheckEnable EMV error check or not. Valid setting are TRUE and FALSE. By enable EMV error checking, this library will perform ATR checking according to EMV book 1 specification. Otherwise, the error checking follows ISO 7816-3
Returns
Smartcard successfully activated or not
Return values
SCLIB_SUCCESSSmartcard activated successfully
OthersSmartcard activation failed
Note
It is required to set smartcard interface clock between 1 MHz and 5 MHz before calling this API, otherwise this API return with SCLIB_ERR_CLOCK error code.
EMV book 1 is stricter than ISO-7816 on ATR checking. Enable EMV check iff the application supports EMV cards only.
If EMVCheck is set TRUE, this API will call SCLIB_SetIFSD to set IFSD if necessary.

◆ SCLIB_ActivateDelay()

int32_t SCLIB_ActivateDelay ( uint32_t  num,
uint32_t  u32EMVCheck,
uint32_t  u32Delay 
)

Activate a smartcard with large delay between set VCC high and start CLK output.

Parameters
[in]numSmartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
[in]u32EMVCheckEnable EMV error check or not. Valid setting are TRUE and FALSE. By enable EMV error checking, this library will perform ATR checking according to EMV book 1 specification. Otherwise, the error checking follows ISO 7816-3
[in]u32DelayExtra delay time between set VCC high and start CLK output, using ETU as time unit.
Returns
Smartcard successfully activated or not
Return values
SCLIB_SUCCESSSmartcard activated successfully
OthersSmartcard activation failed
Note
It is required to set smartcard interface clock between 1 MHz and 5 MHz before calling this API, otherwise this API return with SCLIB_ERR_CLOCK error code.
EMV book 1 is stricter than ISO-7816 on ATR checking. Enable EMV check iff the application supports EMV cards only.
If EMVCheck is set TRUE, this API will call SCLIB_SetIFSD to set IFSD if necessary.
Only use this function instead of SCLIB_Activate if there's large capacitor on VCC pin and VCC raise slowly.

◆ SCLIB_CheckCDEvent()

uint32_t SCLIB_CheckCDEvent ( uint32_t  num)

Process card detect event in IRQ handler.

Parameters
[in]numSmartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
Returns
Card detect event occur or not
Return values
1Card detect event occurred
0Card detect event did not occur
Note
Smartcard IRQ handler shall call this function with correct interface number as parameter

◆ SCLIB_CheckErrorEvent()

uint32_t SCLIB_CheckErrorEvent ( uint32_t  num)

Process error event in IRQ handler.

Parameters
[in]numSmartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
Returns
Error event occur or not
Return values
1Error event occurred
0Error event did not occur
Note
Smartcard IRQ handler shall call this function with correct interface number as parameter

◆ SCLIB_CheckTimeOutEvent()

uint32_t SCLIB_CheckTimeOutEvent ( uint32_t  num)

Process time out event in IRQ handler.

Parameters
[in]numSmartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
Returns
Time out event occur or not
Return values
1Time out event occurred
0Time out event did not occur
Note
Smartcard IRQ handler shall call this function with correct interface number as parameter

◆ SCLIB_CheckTxRxEvent()

uint32_t SCLIB_CheckTxRxEvent ( uint32_t  num)

Process card transmission event in IRQ handler.

Parameters
[in]numSmartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
Returns
Transmission event occur or not
Return values
1Transmission event occurred
0Transmission event did not occur
Note
Smartcard IRQ handler shall call this function with correct interface number as parameter

◆ SCLIB_ColdReset()

int32_t SCLIB_ColdReset ( uint32_t  num)

Cold reset a smartcard.

Parameters
[in]numSmartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
Returns
Smartcard cold reset success or not
Return values
SCLIB_SUCCESSSmartcard cold reset success
OthersSmartcard cold reset failed

◆ SCLIB_Deactivate()

void SCLIB_Deactivate ( uint32_t  num)

Deactivate a smartcard.

Parameters
[in]numSmartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
Returns
None

◆ SCLIB_GetCardInfo()

int32_t SCLIB_GetCardInfo ( uint32_t  num,
SCLIB_CARD_INFO_T s_info 
)

Get the card information (e.g., protocol selected, ATR...) after activation success.

Parameters
[in]numSmartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
[out]s_infoA pointer to SCLIB_CARD_INFO_T holds the card information
Returns
Success or not
Return values
SCLIB_SUCCESSSuccess, s_info contains card information
SCLIB_ERR_CARD_REMOVEDCard removed, s_info does not contains card information
SCLIB_ERR_DEACTIVECard is deactivated, s_info does not contains card information

◆ SCLIB_RequestTimeExtension()

__weak void SCLIB_RequestTimeExtension ( uint32_t  u32Protocol)

A callback called by library while smartcard request for a time extension.

Parameters
[in]u32ProtocolWhat protocol the card is using while it requested for a time extension. Could be ether SCLIB_PROTOCOL_T0 or SCLIB_PROTOCOL_T1
Returns
None
Note
This function is defined with __weak attribute and does nothing in library. Application can provide its own time extension function. For example, and CCID reader can use this function to report this status to PC. See CCID rev 1.1 Table 6.2-3

◆ SCLIB_ResetAnyway()

int32_t SCLIB_ResetAnyway ( uint32_t  num)

Activate a smartcard without historical bytes check, this function can be called if SCLIB_Activate or SCLIB_ActivateDelay return an error.

Parameters
[in]numSmartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
Returns
Smartcard reset success or not
Return values
SCLIB_SUCCESSSmartcard reset success
OthersSmartcard reset failed

◆ SCLIB_SetIFSD()

int32_t SCLIB_SetIFSD ( uint32_t  num,
uint8_t  size 
)

Set interface device max information field size (IFSD)

This function sends S block to notify card about the max size of information filed blocks that can be received by the interface device. According to EMV 9.2.4.3, this should be the first block transmitted by terminal to ICC after ATR.

Parameters
[in]numSmartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
[in]sizeIFSD size. According to EMV spec 9.2.4.3 Error Free Operation, this field must be 0xFE.
Returns
Smartcard transmission success or failed
Return values
SCLIB_SUCCESSSmartcard warm reset success
OthersSmartcard warm reset failed

◆ SCLIB_SetSpecificAtrBR()

int32_t SCLIB_SetSpecificAtrBR ( uint32_t  num,
uint32_t  br 
)

Set a specific baud rate to catch ATR for a card which is not compatible with ISO-7816, this function should be called before SCLIB_Activate or SCLIB_ActivateDelay.

Parameters
[in]numSmartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
[in]brATR default baud rate should be 9600 according to ISO-7816
Returns
Baud rate set success or not
Return values
SCLIB_SUCCESSset ATR baud rate success
Othersset ATR baud rate failed

◆ SCLIB_StartTransmission()

int32_t SCLIB_StartTransmission ( uint32_t  num,
uint8_t *  cmdBuf,
uint32_t  cmdLen,
uint8_t *  rspBuf,
uint32_t *  rspLen 
)

Start a smartcard transmission.

SCLIB will start a transmission according to the protocol selected

Parameters
[in]numSmartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
[in]cmdBufCommand buffer pointer
[in]cmdLenCommand length
[out]rspBufBuffer to holds card response
[out]rspLenResponse length received
Returns
Smartcard transmission success or failed
Return values
SCLIB_SUCCESSTransmission success. rspBuf and rspLen holds response data and length
OthersTransmission failed
Note
This API supports case 1, 2S, 3S, and 4S defined in ISO-7816, but does NOT support case 2E, 3E, and 4E.

◆ SCLIB_WarmReset()

int32_t SCLIB_WarmReset ( uint32_t  num)

Warm reset a smartcard.

Parameters
[in]numSmartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
Returns
Smartcard warm reset success or not
Return values
SCLIB_SUCCESSSmartcard warm reset success
OthersSmartcard warm reset failed

Variable Documentation

◆ ATR_Buf

uint8_t SCLIB_CARD_INFO_T::ATR_Buf[SCLIB_MAX_ATR_LEN]

Buffer holds ATR answered by smartcard.

Definition at line 94 of file sclib.h.

◆ ATR_Len

uint32_t SCLIB_CARD_INFO_T::ATR_Len

ATR length, between SCLIB_MAX_ATR_LEN and SCLIB_MIN_ATR_LEN.

Definition at line 93 of file sclib.h.

◆ T

uint32_t SCLIB_CARD_INFO_T::T

Protocol, ether SCLIB_PROTOCOL_T0 or SCLIB_PROTOCOL_T1.

Definition at line 92 of file sclib.h.