Software

ManualsBrandsMaxim Integrated ManualsHardware73S12xxF

Simplifying System Integration

73S12xxF

Software User Guide

September 14, 2009

Rev. 1.50

UG_12xxF_016

Summary of content (93 pages)

PAGE 1
Simplifying System IntegrationTM 73S12xxF Software User Guide September 14, 2009 Rev. 1.
PAGE 2
73S12xxF Software User Guide UG_12xxF_016 © 2009 Teridian Semiconductor Corporation. All rights reserved. Teridian Semiconductor Corporation is a registered trademark of Teridian Semiconductor Corporation. Simplifying System Integration is a trademark of Teridian Semiconductor Corporation. Windows, Visual Basic, Visual Studio and Visual C/C++ are registered trademarks of Microsoft Corporation. Pentium is a registered trademark of Intel Corporation.
PAGE 3
UG_12xxF_016 73S12xxF Software User Guide Table of Contents 1 Introduction ................................................................................................................................... 5 1.1 Acronyms ................................................................................................................................ 5 1.2 Use of this Document............................................................................................................... 6 1.
PAGE 4
73S12xxF Software User Guide UG_12xxF_016 4.5 Test Tools and Certification/compliance Tests ........................................................................ 85 4.5.1 EMV LEVEL I Certification Tests .............................................................................. 86 4.5.1.1 EMV Test Mode..................................................................................... 86 4.5.1.2 MasterCard Loopback Test .................................................................... 87 4.5.1.
PAGE 5
UG_12xxF_016 73S12xxF Software User Guide 1 Introduction The Teridian Semiconductor Corporation 73S12xxF single-chip Smart Card Terminal Controllers consist of the 73S1209F, 73S1210F, 73S1215F and 73S1217F. These System-on-Chip devices provide the functions necessary to build a low-cost smart card terminal. The 73S12xxF Evaluation Board allows development of an embedded application in conjunction with an In-Circuit Emulator (ICE).
PAGE 6
73S12xxF Software User Guide RTC TSC USB WHQL 1.2 UG_12xxF_016 Real Time Clock Teridian Semiconductor Corporation Universal Serial Bus Windows Hardware Quality Lab Use of this Document The reader should be familiar with microprocessors, particularly the 80C51/80C52/80515 architecture, firmware, embedded software development and smart card application. Knowledge of the USB 2.0 Specification, ISO 7816 Parts 1/2/3/4 and EMV2000 standards may also be helpful.
PAGE 7
UG_12xxF_016 73S12xxF Software User Guide 2 Design Guide This section provides designers with basic guidance in developing smart card reader applications utilizing the TSC 73S12xxF devices. There are three types of applications that can be developed: • • • A Host application (for example: an application residing on a PC, e.g. Windows 2000, Windows XP, Windows CE or in a host microprocessor). An Embedded application using both High-level APIs and Low-level APIs (in Flash).
PAGE 8
73S12xxF Software User Guide UG_12xxF_016  CCIDTSC-*.sys/CCIDTSC-*.inf – Teridian Windows Drivers.  ccidusb-*.hex – an embedded application used for USB CCID communications with Windows or Linux OS. This embedded program can be used with either Microsoft’s generic USB driver or the Teridian driver.  ccidrs232.hex – an embedded application used for RS232/Serial communications with a host running Windows OS.  CCID-USB.exe – a PC application written in C# to be used in conjunction with the CCIDTeridian.
PAGE 9
UG_12xxF_016 73S12xxF Software User Guide USB USB CCID Driver or COM port Driver COM / SLIP Message PC COM Application Layer Application 73S12xxF TSC Serial Pseudo CCID Application (32K) TSC USB CCID Application (36K) ICC Protocol Layer Embedded Application Device Layer 14K SC LAPI (Internal slot only) SC LAPI (Internal or I2C interface) size: < 1K Size: 2K Low Level API - Core size: 12K Hardware Figure 1: Software Architecture Diagram (Sizes indicated are approximate) Rev. 1.
PAGE 10
73S12xxF Software User Guide UG_12xxF_016 2.2.2 API/Library and Header Files The library files included in the software development kit are listed below (see Figure 1: Software Architecture Diagram for the library partitions). The following nomenclature applies to the file names: • • • ‘?’ is either ‘S’ (for Single-8010) or ‘M’ (for Multiple-8010) ‘xx’ is ‘BL’ (for Serial Boot Loader), ‘DFU’ for USB DFU Boot Loader or empty. There are other versions such as LAPI-MS1.LIB, LAPI-SLED.
PAGE 11
UG_12xxF_016 73S12xxF Software User Guide 2.2.3 External Application An external application can run on a PC or any host microprocessor. The 73S12xxF supports two options to interface with a PC external application: RS-232/Serial interface or USB V2.0 full speed interface. RS232 / Serial Interface When using the RS-232 or a generic asynchronous serial interface, TSC can provide the sample source code for a serial / RS-232 firmware application.
PAGE 12
73S12xxF Software User Guide UG_12xxF_016 Figure 2: Device Options for Building with the Boot Loader Figure 2 shows the Device configuration build options. The selected device should be one of the Teridian 80515-based products, either the 6513 or the 73S12xxF family. The Extended Linker (LX51) option is required to pack both the Boot Loader and the Teridian PseudoCCID application within 32 K of Flash.
PAGE 13
UG_12xxF_016 73S12xxF Software User Guide Figure 3: Target Options for Building with the Boot Loader Off-chip code memory should be set to start at 0x0200 since the first page (512 bytes) of Flash is reserved for boot code (see Figure 3). Figure 4: C51 Options for Building with the Boot Loader Rev. 1.
PAGE 14
73S12xxF Software User Guide UG_12xxF_016 The Preprocessor Symbol “MULTI8010” (refer to Figure 4) is used for a hardware configuration where multiple 8010 parts are used to drive up to four external smart card slots (any slot that is higher than ICC_1ST ). Associated library or project files set up for a multiple 8010 configuration have the letter ‘M’ in their filename. For example, the Low-Level library that supports the MULTI8010 configuration would be named LAPI-MBL.lib.
PAGE 15
UG_12xxF_016 73S12xxF Software User Guide Figure 5: Target Options for Building with the DFU Boot Loader Figure 5 shows the application’s starting address. It must be set to start at 0x1802. The Flash address range from 0x0000 through 0x17FF is reserved inclusively for the DFU Boot Loader. Rev. 1.
PAGE 16
73S12xxF Software User Guide UG_12xxF_016 Figure 6: C51 Options for Building with the Boot Loader In Figure 6, the interrupt vectors address must be set to where the application starts, as described above. The Preprocessor Symbol “DFU” is used to link in the DFU option as implemented in LAPI-MDFU.LIB and ICC-API_MDFU.lib. Review the 12xxBootLoaderFirmwareANV…pdf for detailed information about this option. The associated libraries built to support this option has the letters “DFU” in their filenames.
PAGE 17
UG_12xxF_016 73S12xxF Software User Guide 3 Testing Environment Teridian performs conformance and certification testing to verify both the 73S12xxF IC (hardware and electrical) and libraries (protocol, timing and application firmware and drivers). These tests are dictated by specific standards. Each standard has a specific set of hardware and software configuration requirements. This section describes the protocol portion of the testing that has been performed. 3.
PAGE 18
73S12xxF Software User Guide UG_12xxF_016 The USB Command Verifier version 1.3 Beta (latest version) was also run with this release using the TSC customized driver. The USB.ORG compliant testing was completed both in house and by an accredited, independent lab (NTS). Both tests passed. The Linux driver was done in-house, but previously version 1.20 of the TSC CCIDUSB firmware was certified by the Linux CCIDUSB driver developer. 3.2.
PAGE 19
UG_12xxF_016 73S12xxF Software User Guide 4 Design Reference As depicted in Figure 1: Software Architecture Diagram, the 73S12xxF provides many design options for an application developer. Details of the software modules are described in this section. 4.1 Memory Map The 73S12xxF contains a high performance, embedded 80515 core, referred to as the ‘core’. It executes all ASM51 instructions and has the same instruction set as the 80C51.
PAGE 20
73S12xxF Software User Guide UG_12xxF_016 4.1.2 External Data Memory The 2 KB of XRAM are available at address locations 0x0000 through 0x07FF. The upper 1K bytes of the external data memory space (from 0xFC00 to 0xFFFF) is reserved for additional special function registers for the 73S12xxF chip and is segmented as shown in Table 1.
PAGE 21
UG_12xxF_016 73S12xxF Software User Guide The core provides four interrupt priority levels among six group sources. The 73S12xxF sources are grouped as shown in Table 3. All sources belonging to a group share the same interrupt priority level. The LAPI sets up the four priority levels for these groups as shown in Table 3. Table 3: Interrupt Sources and Priority Level Group 6 I2C VDD Analog Group 5 Group 4 USB Smart Card RTC Timer 1 Keypad Serial 0 Priorities as set in LAPI.
PAGE 22
73S12xxF Software User Guide UG_12xxF_016 KEY_Init () Purpose Configure the keyboard. This API will call the Set_Event() routine to enable an Interrupt Service Routine (ISR) to handle keyboard scanning. Synopsis Void KEY_Init ( IN unsigned char rows_cols, IN unsigned char debounce_scan ); Parameters RowsCols: Input parameter Number of rows on keypad (max value is 6) times eight plus number of columns on keypad (max value is 5), i.e. rows*8 + cols.
PAGE 23
UG_12xxF_016 73S12xxF Software User Guide EVENT_VDDF 0x00000400 EVENT_I2C 0x00000800 EVENT_ANALOG 0x00001000 EVENT_USR0 0x00002000 EVENT_USR1 0x00004000 EVENT USR2 0x00008000 EVENT_USR3 0x00010000 EVENT_ES 0x00020000 ExitOn: Output parameter If KEY_ERR_SMARTCARD_xxx return code, it specifies which SmartCard event occurred. Bit[n] corresponds to ICC[n]. If KEY_ERR_EVENT, it specifies which EVENT occurred. KeyCode: Output parameter Specifies the KeyCode that was pressed.
PAGE 24
73S12xxF Software User Guide UG_12xxF_016 LCD_Command () Purpose Send command to LCD. Synopsis Void LCD_Command ( IN char LcdCmd ); Parameters LcdCmd: Input parameter 8-bit command to control the LCD. Available commands are: LCD_CLEAR Clear display and return cursor to home. LCD_HOME Return display and cursor to home position. LCD_MODE | LCD_INC Increment cursor on read/write of display. LCD_MODE | LCD_INC|LCD_SHIFT Increment cursor and shift display on read/write of display.
PAGE 25
UG_12xxF_016 73S12xxF Software User Guide LED_Config () Purpose Configure the LED interface (all pins). Synopsis Void LED_Config ( IN Bbool PU_Enable, IN enum LED_CURRENT LC ); Parameters PU_Enable: Input parameter Boolean value specifies enable (TRUE) or disable (FALSE) pull-up. LC: Input parameter Enum type indicating the output current level for the LEDs (when turned on). The following values are available: LED_OFF: turn off LED (0 mA). LED_DIM: turn LED on at dim level (2 mA).
PAGE 26
73S12xxF Software User Guide UG_12xxF_016 4.2.4 Real Time Clock API - Available with the 68-pin 73S12xxF The 73S12xxF provides a 32-bit counter selectable in 0.5, 1 or 2 second increments to measure time. This time mark can also be used to generate RTC interrupts at 0.5, 1, 2, 4, or 8-second intervals. A 24-bit trimming function, along with a 24-bit accumulator, is provided to correct the clock drift induced by the quartz crystal. The device also supports a watchdog capability.
PAGE 27
UG_12xxF_016 73S12xxF Software User Guide Synopsis Void RTClk_Init ( void ); Parameters None. Return Codes None. RTCClk_Control () Purpose Enable or disable the RTC interrupt. If enabled, the interrupt interval must be specified. Synopsis RTCClk_Control ( IN Bbool RTCInt_Enb, IN enum RTC_INTERVAL intv ); Parameters RTCInt_Enb: Input parameter Enable (TRUE) or disable (FALSE) the RTC interrupt. If set to Enable when the intv parameter is set to NO_INT, the RTC interrupt will NOT be enabled.
PAGE 28
73S12xxF Software User Guide UG_12xxF_016 RTCCnt: Input parameter 32-bit RTC counter value. RTCAcc[3]: Input parameter 24-bit accumulator value. Normally these values are to be initialized only once during the manufacturing phase. RTCTrim[3]: Input parameter 24-bit signed trimmer value. This is the offset value used to correct the quartz crystal drift. It is the number of ticks between each correction of the Real Time Clock.
PAGE 29
UG_12xxF_016 73S12xxF Software User Guide Where MONTH is defined as: enum { JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC }; and RTC_INTERVAL is defined as: enum {HALF_SEC, ONE_SEC, TWO_SEC, FOUR_SEC, EIGHT_SEC, NO_INT}; Parameters Sec: Output parameter Current second unit. Min : Output parameter Current minute unit. Hour: Output parameter Current hour unit. Date: Output parameter Current date unit. Month: Output parameter Current month unit as specified in the enum MONTH type.
PAGE 30
73S12xxF Software User Guide UG_12xxF_016 Year: Input parameter Current year unit, e.g. 2005. TicInterval: Input parameter Tic interval as HALF_SEC, ONE_SEC or TWO_SEC, defined in RTC_INTERVAL. IntInterval: Input parameter Interrupt interval as defined in RTC_INTERVAL. Return Codes TRUE if success. FALSE if TicInterval or Interrupt Interval value is invalid. 4.2.
PAGE 31
UG_12xxF_016 73S12xxF Software User Guide EGT < t TX BGT < t < BWT (T=1) or WWT (T=0) TX/RX RX/TX t < CWT (T=1) or WWT (T=0) RX Figure 8: Smart Card Rx/Tx Timing ICC_InitUART() Purpose Initializes the Smart Card UART for the specified ICC.
PAGE 32
73S12xxF Software User Guide UG_12xxF_016 int IccExtraGuardTime, int IccBlockGuardTime, int IccCharWaitingTime, long int IccBlockWaitingTime, long int IccWorkWaitingTime Boolean IccPUEnabled; Boolean IccPDEnabled; Boolean IccVDDFaultOff;. enum ICC_ADDR IccAddr; // Useful for external I2C. enum ICC_RESET IccExtRst; // Useful for external I2C. enum ICC_CARDEVENT IccCE; // Useful for external I2C. } ICC_Init_t; Parameters IccId: Input parameter Specifies which SmartCard UART interface is to be initialized.
PAGE 33
UG_12xxF_016 Rev. 1.50 73S12xxF Software User Guide IccBreakDuration: Input parameter Specifies the break signal duration. Possible values are 0x00 (1 ETU), 0x01 (1.5 ETU) and 0x02 (2 ETU). The default value is 0x00 (1 ETU). IccRxRetry: Input parameter The number of retries to allow on reception of a bad byte. Retries = total tries – 1. IccBreakDetect: Input parameter Specifies whether to acknowledge (TRUE) or ignore (FALSE) a break coming from the Smart Card.
PAGE 34
73S12xxF Software User Guide UG_12xxF_016 ICC_RST3 = 0xB0, ICC_RST4 = 0xC0, ICC_RST5 = 0xD0, ICC_RST6 = 0xE0, ICC_RST7 = 0xF0 IccCE: Input parameter Card Event parameter. The following settings are available as defined in API_STRUCT_12.h. Set this variable according to the hardware design where either interrupt 2 or interrupt 3 is used for an external card event detect.
PAGE 35
UG_12xxF_016 73S12xxF Software User Guide IccATR_TimeoutEnabled: Input parameter Specifies if the ATR timeout is enabled (TRUE) or disabled (FALSE). IccATR_Timeout: Input parameter Specifies the maximum delay in ETUs between the leading edge of the first character and last character of the ATR response, if enabled. IccTS_Timeout: Input parameter Specifies the maximum delay in ETUs between the de-assertion of the RST signal and the leading edge of the TS byte of the ATR. pIccATR: Input parameter.
PAGE 36
73S12xxF Software User Guide UG_12xxF_016 ICC_Tx() Purpose Send data to the selected Smart Card. Before calling this function, the Smart Card UART must have been initialized and the selected Smart Card activated. Synopsis ICC_RC ICC_Tx ( INOUT struct ICC_t *pICC ); struct { IN char *IccData, INOUT unsigned int IccLen, IN Boolean IccLastByte, INOUT int IccEDC, OUT ICC_RC ICC_Status, OUT Boolean IccDone } ICC_t; Parameters IccData: Input parameter Contains the data to be transmitted.
PAGE 37
UG_12xxF_016 73S12xxF Software User Guide ICC_Rx() Purpose Receive data from the SmartCard interface. Before calling this function, the SmartCard UART must have been initialized and the selected SmartCard activated.
PAGE 38
73S12xxF Software User Guide UG_12xxF_016 IccLastByte should be set when it is time to switch to transmission mode and start the BGT timer. If it is not immediately known when it is time to switch, call ICC_RxDone() after all the bytes have been received. To determine if all the expected bytes have been received, call ICC_RxLen(). Since the ICC_OK or ICC_BREAK status occurs after reception of ICCLen bytes, this value should include any CRC/LRC byte(s) received.
PAGE 39
UG_12xxF_016 73S12xxF Software User Guide Return Codes ICC_OK ICC_ERR_PRESENT_INACTIVE ICC_ERR_NO_CARD The SmartCard is present and active. The SmartCard is present but inactive. The SmartCard is not present. This API is part of the support for Synchronous cards. ICC_Clk_Restart() Purpose Restarts an ICC’s clock. Synopsis ICC_Clk_Restart ( IN int nIccDelayIO ); Parameters nIccDelayIO: Input parameter Delay in clock cycles after restart of the clock before allowing I/O.
PAGE 40
73S12xxF Software User Guide UG_12xxF_016 After calling Serial_Init() and prior to receiving data from the RS232 interface, Serial_Rx() and Serial_Tx() must be called to pass on the receive/transmit buffer pointer, which is used to store Rx and Tx characters, respectively. For a sample of the Serial API usage, see the Pseudo-CCID application source code. Serial_Init() Purpose Configure the communication speed, flow control, character parity and number of stop bits.
PAGE 41
UG_12xxF_016 73S12xxF Software User Guide Len: Input parameter. Specifies the current number of bytes to be sent. Return Codes S_EMPTY Successful transmission. S_PENDING, Successful transmission thus far but not yet finished. Where return code SERIAL_RC is defined as: Enum SERIAL_RC. Serial_CTx() Purpose Put bytes into the transmit buffer and start sending. Prior to calling this function, Serial_Tx() must be call to setup the Tx buffer.
PAGE 42
73S12xxF Software User Guide UG_12xxF_016 len: Input parameter. Specifies the maximum number of bytes to receive at any one time. Return Codes On a successful completion or termination, the serial Status will return one of the following: S_EMPTY Reception has started but the receive buffer is still empty. S_PENDING Reception has started, but is not yet completed. S_FULL Reception has started and the buffer is now full. S_PARITY_ERR Parity error occurred on the received byte(s).
PAGE 43
UG_12xxF_016 73S12xxF Software User Guide The USB interface contains four endpoints, which are defined as follows: 1. 2. 3. 4. Endpoint 0 Endpoint 1 Endpoint 1 Endpoint 2 for the control transfer IN for the Bulk transfer OUT for the Bulk transfer IN for the interrupt transfer The Low-level API handles all Endpoint 0 (control endpoint) communications; thus PC driver enumeration takes place during the device reset time and is transparent to an application.
PAGE 44
73S12xxF Software User Guide UG_12xxF_016 requests and will return the configuration, endpoint, interface and string descriptors including the CCID class descriptor, depending on the maximum length requested. There are two possible configurations for the USB: self-powered and bus-powered. Each configuration requires some power consumption management to effectively reduce the power according to the USB 2.0 Specification.
PAGE 45
UG_12xxF_016 unsigned unsigned unsigned unsigned unsigned unsigned }; int int char char char char 73S12xxF Software User Guide idProduct; Device; iManufacturer; iProduct; iSerialNum; NumConfigs; struct USB_Interface_t { unsigned char Length; unsigned char DescriptorType; unsigned char InterfaceNumber; unsigned char AlternateSetting; unsigned char NumEndPoints; unsigned char InterfaceClass; unsigned char InterfaceSubClass; unsigned char InterfaceProtocol; unsigned char iInterface; }; #define CLASS 0x0B #
PAGE 46
73S12xxF Software User Guide UG_12xxF_016 #define SELF_POWERED BIT6 #define REMOTE_WAKEUP BIT5 #define MAXPOWER 50 #define NUMBER_LANGIDS 1 // 100 mA, if bus-powered. // Change as needed. #ifdef DFU #define NUMBER_STRINGS 4 #else #define NUMBER_STRINGS 3 // Change as needed. struct USB_LangID_t { Uc Length; // (NUMBER_LANGIDS * 2) + 2. Uc DescriptorType; // Always STRING_DESCRIPTOR = 3. Ui LangID [ NUMBER_LANGIDS ]; // Array of LangID codes.
PAGE 47
UG_12xxF_016 #define BPS9600 #define BPS14400 #define BPS19200 #define BPS28800 #define BPS38400 #define BPS57600 #define BPS57688 #define BPS115200 #define BPS116129 #define BPS225000 #define BPS230400 73S12xxF Software User Guide 9600L // 0x00002580 (9600 +- 1%) 14400L 19200L 28800L 38400L 57600L 57688L 115200L // 0x0001C200 (115200 +- 1%) 116129L // 0x0001C200 225000L 230400L // Defines for Mechanical.
PAGE 48
73S12xxF Software User Guide UG_12xxF_016 unsigned char NumDataRates; // 7. unsigned long MaxIFSD; // Application specific. unsigned long SynchProtocols; // 0x00000000. unsigned long Mechanical; // Application specific. unsigned long Features; // Application specific. unsigned long MaxCCIDMsgLen; // Application specific. unsigned char ClassGetResponse; // Application specific. unsigned char ClassEnvelope; // Application specific. unsigned int LcdLayout; // Application specific.
PAGE 49
UG_12xxF_016 73S12xxF Software User Guide USB_Stall() Purpose Stalls portions of the USB interface: The Endpoints to be stalled are configurable. Synopsis Void USB_Stall ( IN char cUSBEndpointStall ); Parameters cUSBEndpointStall: Input parameter Specifies which endpoints are to be stalled by this function. The other endpoints remain in their previous state.
PAGE 50
73S12xxF Software User Guide UG_12xxF_016 USBStatus: Output parameter Contains the current status of this transmission, one of the following: USB_TX_PENDING: Transmission has started, but is not yet complete. On either a successful completion or a termination due to error, the USBStatus will change to one of the following: USB_ACTIVE: Successful data transmission. USB_SUSPENDED: The HOST has suspended the USB bus, retry later. USB_STALLED: This Endpoint has been STALLED.
PAGE 51
UG_12xxF_016 Return Codes 73S12xxF Software User Guide None. 4.2.8 Clock Generator Circuit API – Available with all 73S12xxF Devices The Clock Generator API configures the system clock speed. CPU_Select() Purpose Select the CPU speed. This API should be called after API_Init() is called if a change in CPU speed is desired. The default speed is 3.69 MHz. Care should be taken when selecting speeds other than 3.69 MHz, as the speed will affect the number of supported Serial baud rates and timers API.
PAGE 52
73S12xxF Software User Guide UG_12xxF_016 BPS_38400_3MHz69,BPS_57600_3MHz69, BPS_115200_3MHz69, 0, 0, 0 }, //Can only support these rates when the CPU is running //CPU_6MHz {0, BPS_1200_6MHz, BPS_2400_6MHz, 0, BPS_14400_6MHz, 0, 0, 0, 0, at 6 MHz BPS_4800_6MHz, 0, 0, 0, 0}, //Can only support these rates when the CPU is running at 12 MHz //CPU_12MHz {0, 0, BPS_2400_12MHz, 0, BPS_14400_12MHz, 0, BPS_28800_12MHz, 0, 0, BPS_125000_12MHz, 0, BPS_9600_12MHz, 0, BPS_375000_12MHz }, //Can only support these
PAGE 53
UG_12xxF_016 73S12xxF Software User Guide PowerOFF() Purpose Manage power consumption. Synopsis void PowerOFF ( IN unsigned int PowerSelect ); Parameters PowerSelect: Input parameter Specifies which internal devices to disable. The following possible values or any combination (by OR’ing them) are allowed: DISABLE_EICC BIT14 // External Smart card.
PAGE 54
73S12xxF Software User Guide UG_12xxF_016 Parameters threshold_select: Input parameter Specifies which input voltage channel must be compared against Vcompare. Allowable values are in the range [0, 7]. acomp_pol: Input parameter Specifies the polarity for which an interrupt occurs; when voltage level is Above (acomp_pol = 1) or Below (acomp_pol = 0). Voltage levels are values in the range [0, 7]. 7 corresponds to 2.50 volts //Only available with the 73S1205F 6 corresponds to 2.
PAGE 55
UG_12xxF_016 73S12xxF Software User Guide 4.2.11 Event Management API – Available with all 73S12xxF Devices The Event Management API allows the application to handle all system events. An application should always call Events_Init() to initialize all event vectors at the beginning of the main program. The API includes: • • • • Events_Init() (page 55) Events_Clear() (page 55) Get_Event () (page 56) Set_Event () (page 56) Events_Init() Purpose Initialize the system default event vectors.
PAGE 56
73S12xxF Software User Guide UG_12xxF_016 Get_Event () Purpose Get selected event vector. Synopsis (* void () ) Get_Event_Vector ( IN enum EVENT_ID eEventID ); Parameters eEventID: Input parameter Specifies for which event to return the current vector.
PAGE 57
UG_12xxF_016 73S12xxF Software User Guide RFU // 17 pEventVector: Input parameter Pointer (vector) to the function to call when the event occurs. Return Codes None. The eUSB handler should check the x.USBStatus value and/or call the USB_Status() routine to determine which USB event occurred. All other events have unique causes. 4.2.12 Timers API – Available with all 73S12xxF Devices The Timers API allows up to four 16-bit 10 ms timers to be run concurrently.
PAGE 58
73S12xxF Software User Guide UG_12xxF_016 Synopsis Unsigned Integer *Add_Timer ( IN Unsigned integer nDuration) Parameters nDuration: Input parameter Specifies duration of time in 10 ms units. Return Value Pointer to added timer. If the value is zero (NULL), there are no timers available. This function can be called inside an ISR. When the timer expires (*pTimer == 0), it will be automatically removed. If all timers are in use, a NULL pointer will be returned.
PAGE 59
UG_12xxF_016 73S12xxF Software User Guide USR_INT_Config () Purpose Configure USER IO as an interrupt source for T0, T1, INT0 or INT1. Synopsis void USR_INT_Config ( IN enum USRINTSRC usr_src, IN enum USRINTSEL int_select, IN Boolean Enable, IN Boolean EdgeTrigger ) Parameters usr_src: Input parameter Specifies which USER IO is to be used as the interrupt source. The available choices (defined in USRINTSRC in api_struct_12.
PAGE 60
73S12xxF Software User Guide UG_12xxF_016 USER_IO_Config() Purpose Configure the direction for the USER IO pins. Synopsis void USER_IO_ Config ( Unsigned char usrsrc, Unsigned char dir ) Parameters usrsrc: Input parameter Corresponding USR pins to be configured as Input or Output. USRIO 0 through 7 will be configured according to the Dir parameter below. Dir: Input parameter Direction value (1=input, 0=output) for the selected pins. Return Codes None.
PAGE 61
UG_12xxF_016 73S12xxF Software User Guide Parameters Enable: Input parameter Enable (1) or disable (0) interrupt 2. Polarity : Input parameter Configure interrupt on rising edge (1) or falling edge (0). Return Codes None. INT2_Read() Purpose Read value of External Interrupt 2. Synopsis void INT2_Read ( Unsigned char *polarity, Unsigned char *status) Parameters polarity: Output parameter Specifies the polarity of the external interrupt 2 pin, rising edge = 1, falling edge = 0.
PAGE 62
73S12xxF Software User Guide UG_12xxF_016 Synopsis SFR_RC SFR_Read ( IN char cSFRAddr, OUT char *pcSFRValue ); Parameters cSFRAddr: Input parameter Specifies the address of the Special Function Register to be read. pcSFRValue: Output parameter Specifies the value read from the specified Special Function Register. Return Codes SFR_OK Successful read from the SFR. SFR_INVALID Invalid SFR referenced. SFR_Write() Purpose Write to the specified Special Function Register.
PAGE 63
UG_12xxF_016 73S12xxF Software User Guide 4.2.16 Flash/Memory API – Available with all 73S12xxF Devices Flash management assumes that the CPU is running at the default clock rate of 3.69 MHz. A Flash write is processed on a page basis. If a write to a Flash address overlays two pages, a two-page write operation will be performed. The Flash write process involves 4 steps: Read, Erase, Verify, Write. Should any of these steps fail, the write operation will fail.
PAGE 64
73S12xxF Software User Guide UG_12xxF_016 memcpy_xx () Purpose Memory management – use to copy the contents of external RAM (XRAM) location(s) to other XRAM location(s). Synopsis memcpy_xx ( Unsigned char xdata *dst, Unsigned char xdata *src, Unsigned integer len ); Parameters dst: Input parameter Destination: specifies starting address of XRAM to be written. src: Input parameter Use data at this XRAM address location as the source data.
PAGE 65
UG_12xxF_016 73S12xxF Software User Guide memcmp_rx () Purpose Memory management – use to compare the contents of an XRAM location and a ROM location. Synopsis Signed char memcmp_rx ( Unsigned char code *dst, Unsigned char xdata *src, Unsigned integer len ); Parameters dst: Input parameter Specifies the starting address of the ROM data to be compared. src: Input parameter Specifies the starting address of the XRAM data to compare to.
PAGE 66
73S12xxF Software User Guide UG_12xxF_016 strlen_x () Purpose Compute the string length of ASCII data in XDATA (XRAM). Synopsis unsigned int strlen_x ( IN unsigned char xdata *psource ); Parameters psource: Input parameter Specifies a pointer to the source data in XRAM. Return Value Length of the ASCII data string (in bytes) in the specified XRAM location. strlen_r () Purpose Compute the string length of ASCII data in ROM (Flash).
PAGE 67
UG_12xxF_016 73S12xxF Software User Guide 4.2.17 Boot Loader and Passcode Management – Available with the LAPI-*BL.lib Only The Boot Loader code occupies the first (lower) 512 bytes of the Flash program space (0x0000 - 0x01FF) including the passcode storage space. The Boot Loader assumes that the CPU is running at the default clock rate which is 3.69 MHz. As a result, the serial baud rate and all soft-timers (timer 0) are calculated based on the default CPU clock rate.
PAGE 68
73S12xxF Software User Guide UG_12xxF_016 Application/Host LAPI-*.lib Start Flash Down Load Start Flash Prog. Configure COM port @ 115,200 baud, 8N1, Xon/Xoff Configure COM port @ 115,200 baud, 8N1, Xon/Xoff Received hex record from App/Host Good record (good CRC)? Open Hex File Yes Send 'F' to App/ Host End of file? Read Hex Record Yes No No Prompt User to terminate App.
PAGE 69
UG_12xxF_016 73S12xxF Software User Guide SetPassCode ( ) Purpose Change the PassCode to a new value. The first (and default) passcode is 0x5AA5 and is stored at location 0x01E0 and 0x01E1. When SetPassCode() is executed the first time, it writes 0x0000 to these two addresses. The new PassCode will be written at 0x01E2 and 0x01E3.
PAGE 70
73S12xxF Software User Guide UG_12xxF_016 If the passcode has changed 8 times prior to entering Mode 2, it will be disabled since no more passcode changes are allowed. Since this mode is controlled by firmware, it can be reset/re-initialized by using the ICE to reprogram the Flash.
PAGE 71
UG_12xxF_016 73S12xxF Software User Guide 4.2.19 Other Miscellaneous API Calls – Available with all 73S12xxF Devices Several API calls are provided to help with initializing or re-initializing all the registers, interrupts and events. As a general guideline, API_Init() should always be called at the beginning of the application main routine.
PAGE 72
73S12xxF Software User Guide 4.3 UG_12xxF_016 High-Level API The 73S12xxF comes with a high-level API library to control the Smart Card. This library is linked to the low-level API as described in Section 4.2 Low-level API for all smart card communication controls. 4.3.1 Smart Card Control This API provides support for the asynchronous (T=0) and (T=1) Smart Card protocol management. Each Smart Card interface is individually addressed by specifying the correct eIccId value.
PAGE 73
UG_12xxF_016 73S12xxF Software User Guide ICC_NONE, ICC_NONE, ICC_NONE }; ICC_Enable() or ICC_Enable_Ext () Purpose Activate the Smart Card interface slot specified by eIccId, and return the ATR to the application. ICC_Enable_Ext() is the extended function. The extended version has one additional parameter as input.
PAGE 74
73S12xxF Software User Guide UG_12xxF_016 whereas the ISO 7816-3 standard allows an error recovery procedure. EMV specifies that the IFD must initiate an IFSD negotiation before the first command transmission in (T=1) protocol. When EMV mode is specified, bIccIFSDRequestT1 is set to TRUE and bIccDeactivatedOnTimeOutErrorT1 is set to TRUE. bIccHighSpeed: Input parameter Specifies if the reader has to switch to the high speed clock (7.
PAGE 75
UG_12xxF_016 73S12xxF Software User Guide The eIccId parameter is split into two fields: Card Detect Polarity and Card Slot number, by using the most significant nibble and least significant nibble, respectively. Therefore, the most significant nibble of the eIccId parameter is used to determine if the Card Detect Polarity is to be configured High or Low. The constants CARD_DET_H and CARD_DET_L are defined in ICCMgt.h. Examples: 1.
PAGE 76
73S12xxF Software User Guide UG_12xxF_016 ICC_PTSNegotiate() 76 Purpose Transmit the PTS negotiation request to the Smart Card and verify its answer. When the PTS negotiation succeeds, the 73S12xxF configures its internal protocol parameters with the negotiated values.
PAGE 77
UG_12xxF_016 73S12xxF Software User Guide ICC_Send() Purpose Transmit a data command to the Smart Card interface and wais for the answer from the Smart Card. This function is responsible for the Smart Card command format analysis which computes the correct command case (1, 2 Short, 3 Short or 4 Short). The API assumes that the data record size is 255 bytes or less which is why it supports short cases only.
PAGE 78
73S12xxF Software User Guide UG_12xxF_016 AR_ICC_ERR_WRONG_LEN Either the command case (T=0) is not correctly formatted, or the buffer size specified is too small; especially in a Case 2 where the card sometimes responds with a 61xx with xx > specified buffer size. AR_ICC_ERR_CARD_COMM_PB Too many errors occurred, so the interface has been closed.
PAGE 79
UG_12xxF_016 73S12xxF Software User Guide pucSW2: Output parameter Contains the received SW2 value. pbStatusJustAfterHeader: Output parameter This boolean parameter specifies if the status bytes have been received just after the header (TRUE) or after the data (FALSE) [Useful for the EMV Tests suite]. This parameter must be taken into account only if the ICC_Configure() command set the pbIccWarningStatusBytesManagementT0 bit.
PAGE 80
73S12xxF Software User Guide UG_12xxF_016 //This is newly added from version 1.50 release IN ICC_HWConfigure_t ptrHWConfigure ); Struct ICC_Configure_t { INOUT unsigned char ucIccIFSD; INOUT unsigned char ucIccNAD; //this variable when initialize to 0xFF the GetResponse command will carry the CLA //byte of the last C-APDU.
PAGE 81
UG_12xxF_016 73S12xxF Software User Guide punIccTSTimeOut: Input/output parameter Specifies the maximum delay in clock cycles between the de-assertion of the RST signal and the leading edge of the TS character of the ATR. [Default value is 40 000] pucIccRxErrorCounterT0: Input/output parameter Specifies the maximum number of errors allowed when the Interface Device is in reception mode in T=0 protocol.
PAGE 82
73S12xxF Software User Guide UG_12xxF_016 DebouncePDEnable: Input parameter The higher order (most significant) nibble of this byte enables (SC_DEBOUNCEON) or disables (SC_DEBOUNCEOFF) card debounce. The low order (least significant) nibble of this byte enables (TRUE) or disables (FALSE) the Pull-Down. Return Codes AR_ICC_OK Successful operation. ICC_Configure() 82 Purpose Get / Set the configurable protocol parameters of the specified Smart Card interface.
PAGE 83
UG_12xxF_016 73S12xxF Software User Guide pucIccIFSD: Input/output parameter Specifies the IFSD value to be used (or being used). [Default value is 32 as specified by ISO/IEC 7816-3] pucIccNAD: Input/output parameter Specifies the NAD value to be used (or being used). [Default value is 00] pucIccCLA: Input/output parameter Specifies the CLA value to be used (or being used) when performing a GetResponse in case 2 / 4 (in T=0 protocol).
PAGE 84
73S12xxF Software User Guide UG_12xxF_016 Parameters eIccId: Input parameter Specifies which Smart Card interface is to be activated. Possible values are: ICC_1ST 0, (Internal) ICC_2ND 1, (External) … ICC_9TH 8 (External) Return Codes AR_ICC_OK AR_ICC_ERR_BAD_PARAM Successful operation. Invalid ICC Slot. ICC_CheckPresence() Purpose Return the status of the specified ICC interface. Synopsis AR_ICC_RC ICC_CheckPresence ( IN enum ICC_ID eIccId ); Parameters eIccId: Input parameter.
PAGE 85
UG_12xxF_016 4.4 73S12xxF Software User Guide Flash Programming There are two ways to download a hex file to the 73S12xxF Flash: 1. Using a Teridian Flash Programmer Tool. This tool is packaged separately; contact a Teridian Sales Representative for more information. 2. Using a Signum Systems ADM51 ICE. 4.5 Test Tools and Certification/compliance Tests A set of tools is provided with the 73S12xxF development kit to assist the application development.
PAGE 86
73S12xxF Software User Guide UG_12xxF_016 4.5.1 EMV LEVEL I Certification Tests The EMV compliant test suite follows the Payment System Environment specification. There are several test labs, listed on the www.emvco.com website, qualified to perform these tests. Currently, there are two available Protocol test suites that can be used to qualify for EMV Level I compliance. Passing either of these suites will qualify as EMV Level I compliance.
PAGE 87
UG_12xxF_016 73S12xxF Software User Guide Initialization Yes SingleShot? Select Single-Shot or Loopback test? No Single Shot LoopBack Get Delay Time (in Secs) EMV Power Down Delay Time Wait Setup EMV Test Mode EMV Power Up No No Escape command is sent with B1 = MCI(10) or VISA I (20) or VISA II (40) in EMVmode Power-Up Ok (Good ATR)? Yes Start Test by sending a Block Transfer (0x6F) with 0 Lenth data No Figure 11: EMV PSE Test Flow Chart 4.5.1.
PAGE 88
73S12xxF Software User Guide UG_12xxF_016 Initialization Wait 5 seconds EMV Power Up Power-Up Ok (Good ATR)? No Yes Warm Reset OK? No EMV Power Down Yes Negotiable Mode? Yes PPS OK? No No Yes Select File 1PAY.SYS.DDF01 APDU Exchange Yes No Yes Exchange OK? Yes No R-APDU < 6 bytes? No INS='70'? No Extrac Next C-APDU from R-APDU Figure 12: MCI Test Flow Chart with PTS/PPS 88 Rev. 1.
PAGE 89
UG_12xxF_016 73S12xxF Software User Guide Initialization Wait 5 seconds EMV Power Up Power-Up Ok (Good ATR)? No Warm Reset OK? No EMV Power Down Yes Yes Select File 1PAY.SYS.DDF01 APDU Exchange No Yes Yes Exchange OK? Yes R-APDU < 6 bytes? No INS='70'? No No Extrac Next C-APDU from R-APDU Figure 13: MCI Test Flow Chart without PTS/PPS Rev. 1.
PAGE 90
73S12xxF Software User Guide UG_12xxF_016 4.5.1.3 VISA-1 Loopback Test Teridian used the RFI Global test lab in the UK (listed on the www.emvco.com website) for VISA-1 testing. This lab used the VISA test suite for their EMV Level I qualification test services. Figure 14 shows the VISA-1 test flow which is specific to RFI’s test scripts. Source code for this test is also included in the release.
PAGE 91
UG_12xxF_016 73S12xxF Software User Guide 4.5.2 VISA-2 Loopback Test Teridian used the ICT-K test lab in Korea (listed on the www.emvco.com website) for VISA-2 loopback testing. This lab used the VISA test suite version 4.1 for their EMV Level I qualification test services (details shown in Figure 15). The USB CCID firmware includes the source code that implements this test.
PAGE 92
73S12xxF Software User Guide UG_12xxF_016 5 Related Documentation The following 73S12xxF documents are available from Teridian Semiconductor Corporation: 73S1209F Data Sheet 73S1210F Data Sheet 73S1215F Data Sheet 73S1217F Data Sheet 73S12xxF FPGA Evaluation Board User’s Manual Pseudo-CCID Host GUI Users Guide Pseudo-CCID Host Application Guide Pseudo-CCID Serial/RS232 Firmware Application Note USB-CCID-Host GUI Users Guide CCID Application Note 6 Contact Information For more information about Teridian S
PAGE 93
UG_12xxF_016 73S12xxF Software User Guide Revision History Date 12/12/2005 11/20/2006 Revision 0.01 0.80 3/1/2007 1.00 3/19/2009 1.30 4/27/2009 1.40 9/14/2009 1.50 Rev. 1.50 Description Preliminary version Updated with the latest change since the last build. This version is still considered a Beta release. First production build. Includes modules that passed HCT/Microsoft WHQL, EMV Level I, USB.ORG’s command verifier and goldtree testing. 1.