| M480 BSP V3.05.001 The Board Support Package for M480 Series

Functions
Smartcard Library Exported Functions
Library » Smartcard Library

## 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...

## Detailed Description

## Function Documentation

## ◆ SCLIB_Activate()

int32_t SCLIB_Activate | ( | uint32_t | num,
|  | uint32_t | u32EMVCheck
| ) |  |

Activate a smartcard.

Parameters

  [in] | num | Smartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
  [in] | u32EMVCheck | Enable 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_SUCCESS | Smartcard activated successfully
  Others | Smartcard 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] | num | Smartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
  [in] | u32EMVCheck | Enable 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] | u32Delay | Extra delay time between set VCC high and start CLK output, using ETU as time unit.

Returns
  Smartcard successfully activated or not

Return values

  SCLIB_SUCCESS | Smartcard activated successfully
  Others | Smartcard 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] | num | Smartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)

Returns
  Card detect event occur or not

Return values

  1 | Card detect event occurred
  0 | Card 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] | num | Smartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)

Returns
  Error event occur or not

Return values

  1 | Error event occurred
  0 | Error 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] | num | Smartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)

Returns
  Time out event occur or not

Return values

  1 | Time out event occurred
  0 | Time 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] | num | Smartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)

Returns
  Transmission event occur or not

Return values

  1 | Transmission event occurred
  0 | Transmission 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] | num | Smartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)

Returns
  Smartcard cold reset success or not

Return values

  SCLIB_SUCCESS | Smartcard cold reset success
  Others | Smartcard cold reset failed

## ◆ SCLIB_Deactivate()

void SCLIB_Deactivate | ( | uint32_t | num | ) |

Deactivate a smartcard.

Parameters

  [in] | num | Smartcard 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] | num | Smartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
  [out] | s_info | A pointer to SCLIB_CARD_INFO_T holds the card information

Returns
  Success or not

Return values

  SCLIB_SUCCESS | Success, s_info contains card information
  SCLIB_ERR_CARD_REMOVED | Card removed, s_info does not contains card information
  SCLIB_ERR_DEACTIVE | Card 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] | u32Protocol | What 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_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] | num | Smartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
  [in] | size | IFSD 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_SUCCESS | Smartcard warm reset success
  Others | Smartcard warm reset 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] | num | Smartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
  [in] | cmdBuf | Command buffer pointer
  [in] | cmdLen | Command length
  [out] | rspBuf | Buffer to holds card response
  [out] | rspLen | Response length received

Returns
  Smartcard transmission success or failed

Return values

  SCLIB_SUCCESS | Transmission success. rspBuf and rspLen holds response data and length
  Others | Transmission 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] | num | Smartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)

Returns
  Smartcard warm reset success or not

Return values

  SCLIB_SUCCESS | Smartcard warm reset success
  Others | Smartcard warm reset failed