| NANO100_BSP V3.05.000 The Board Support Package for Nano100BN Series

Functions | Variables
Smartcard Library Exported Functions
NANO100 Library » Smartcard Library » Smartcard Library Exported Constants » Smartcard Library Exported Structs
Collaboration diagram for Smartcard Library Exported Functions:

## 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_GetCardAttrib (uint32_t num, SCLIB_CARD_ATTRIB_T *s_attrib)
| Get the card attribute (e.g., Fi, Di, convention, guard time... etc. ) 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...
| __attribute__ ((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...

## Variables
uint32_t | SCLIB_CARD_INFO_T::T
| Protocol, ether SCLIB_PROTOCOL_T0 or SCLIB_PROTOCOL_T1. More...
uint32_t | SCLIB_CARD_INFO_T::ATR_Len
| ATR length, between SCLIB_MAX_ATR_LEN and SCLIB_MIN_ATR_LEN. More...
uint8_t | SCLIB_CARD_INFO_T::ATR_Buf [SCLIB_MAX_ATR_LEN]
| Buffer holds ATR answered by smartcard. More...
uint8_t | SCLIB_CARD_ATTRIB_T::Fi
| F index. More...
uint8_t | SCLIB_CARD_ATTRIB_T::Di
| D index. More...
uint8_t | SCLIB_CARD_ATTRIB_T::conv
| Convention, direct or inverse. 0 direct, 1 inverse. More...
uint8_t | SCLIB_CARD_ATTRIB_T::chksum
| Checksum type. More...
uint8_t | SCLIB_CARD_ATTRIB_T::GT
| Guard Time. More...
uint8_t | SCLIB_CARD_ATTRIB_T::WI
| Wait integer for T0. More...
uint8_t | SCLIB_CARD_ATTRIB_T::BWI
| Block waiting integer for T1;. More...
uint8_t | SCLIB_CARD_ATTRIB_T::CWI
| Character waiting integer for T1;. More...
uint8_t | SCLIB_CARD_ATTRIB_T::clkStop
| Card clock stop status. 00 Not allowed, 01 low, 02, high, 03 ether high or low. More...
uint8_t | SCLIB_CARD_ATTRIB_T::IFSC
| size of negotiated IFCS More...
uint8_t | SCLIB_CARD_ATTRIB_T::NAD
| NAD value. More...

## Detailed Description

## Function Documentation

## ◆ __attribute__()

__attribute__ | ( | (weak) |  | ) |

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

Definition at line 35 of file _syscalls.c.

Here is the call graph for this function:

## ◆ 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.
  Application should call this API after SC_Open() and SC interrupt enabled

## ◆ 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.
  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 if and only if the smartcard slot has a card detect signal

## ◆ 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_GetCardAttrib()

int32_t SCLIB_GetCardAttrib | ( | uint32_t | num,
|  | SCLIB_CARD_ATTRIB_T * | s_attrib
| ) |  |

Get the card attribute (e.g., Fi, Di, convention, guard time... etc. ) after activation success.

Parameters

  [in] | num | Smartcard interface number. From 0 ~ ( SC_INTERFACE_NUM - 1)
  [out] | s_attrib | A pointer to SCLIB_CARD_ATTRIB_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_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_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

## 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 97 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 96 of file sclib.h.

## ◆ BWI

uint8_t SCLIB_CARD_ATTRIB_T::BWI

Block waiting integer for T1;.

Definition at line 111 of file sclib.h.

## ◆ chksum

uint8_t SCLIB_CARD_ATTRIB_T::chksum

Checksum type.

Definition at line 108 of file sclib.h.

## ◆ clkStop

uint8_t SCLIB_CARD_ATTRIB_T::clkStop

Card clock stop status. 00 Not allowed, 01 low, 02, high, 03 ether high or low.

Definition at line 113 of file sclib.h.

## ◆ conv

uint8_t SCLIB_CARD_ATTRIB_T::conv

Convention, direct or inverse. 0 direct, 1 inverse.

Definition at line 107 of file sclib.h.

## ◆ CWI

uint8_t SCLIB_CARD_ATTRIB_T::CWI

Character waiting integer for T1;.

Definition at line 112 of file sclib.h.

## ◆ Di

uint8_t SCLIB_CARD_ATTRIB_T::Di

D index.

Definition at line 106 of file sclib.h.

## ◆ Fi

uint8_t SCLIB_CARD_ATTRIB_T::Fi

F index.

Definition at line 105 of file sclib.h.

## ◆ GT

uint8_t SCLIB_CARD_ATTRIB_T::GT

Guard Time.

Definition at line 109 of file sclib.h.

## ◆ IFSC

uint8_t SCLIB_CARD_ATTRIB_T::IFSC

size of negotiated IFCS

Definition at line 114 of file sclib.h.

## ◆ NAD

uint8_t SCLIB_CARD_ATTRIB_T::NAD

NAD value.

Definition at line 115 of file sclib.h.

## ◆ T

uint32_t SCLIB_CARD_INFO_T::T

Protocol, ether SCLIB_PROTOCOL_T0 or SCLIB_PROTOCOL_T1.

Definition at line 95 of file sclib.h.

## ◆ WI

uint8_t SCLIB_CARD_ATTRIB_T::WI

Wait integer for T0.

Definition at line 110 of file sclib.h.