Simplifying System Integration
TM
73S12xxF
Software User Guide
September 14, 2009
Rev. 1.50
UG_12xxF_016
73S12xxF Software User Guide UG_12xxF_016
2 R ev. 1.50
© 2009 Teridian Semiconductor C or poration. All r i ghts reserved.
Teridian Semico nductor Corp or ation is a r egistered trademark of Ter i dian Sem i conductor Corporation .
S im pli fying Syst em Integrati on is a trademark of Teridian Semicon duct or Corp or ation.
Windows, Visual Basic, Visual Stud io and Visual C/C++ are registered tr ademarks of Micr osoft
Corporation.
Pentium is a reg i ster ed t r ademark of Intel Cor poration.
µVision is a registered tr ademark of Keil ( an ARM® Company).
Lin ux is a r egistered t r ademark of Linus Torvalds.
MasterCar d is a reg ist er ed trademark of MasterCard Wor ldwide.
V isa is a reg i ster ed t r ademark of Visa Inc.
A ll other tradem ar ks are th e propert y of their r especti ve owner s.
Teridian Semiconductor Corporation makes no warranty for the use of i ts pr oducts, other than exp r essly
cont ained in the Company’s warranty detai led i n t he Teridi an Semico nductor Corporation standar d Terms
and Conditions. The company assumes no r esponsibil ity for an y error s wh i ch m ay appear in this
document, r eserves the ri ght to change devices or specificati ons det ailed herein at any ti me wit hout
notice and does not make any commitment to update the information contained herein. Accordingly, the
reader i s cauti oned to verify t hat this document i s cur r ent by compari ng i t to the latest version on
http:// www.t er idi an.co m or by checking wit h your sal es represe ntative.
Teridian Semiconductor Corp., 6440 Oak Canyon, Suite 100, Irvine, CA 92618
TEL (714) 508-8800, FAX (714) 508-8877, http://www.teridian.com
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 3
Table of Contents
1 Introduction ................................................................................................................................... 5
1.1 Acronyms ................................................................................................................................ 5
1.2 U se of t his D ocument............................................................................................................... 6
1.3 Statement of Compliance ......................................................................................................... 6
2 Design Guide ................................................................................................................................. 7
2.1 D evelopment E nvironment ...................................................................................................... 7
2.1.1 Hardware Requi r ements .............................................................................................. 7
2.1.2 Software Requir ements ............................................................................................... 7
2.2 Software B uil d Environment ..................................................................................................... 8
2.2.1 Software Architecture .................................................................................................. 8
2.2.2 AP I/ Libr ar y and Header Files ..................................................................................... 10
2.2.3 External Appl i cati on ................................................................................................... 11
2.2.4 Em bedded Application .............................................................................................. 11
2.2.5 Build Environment with the Seri al Boot Loader .......................................................... 11
2.2.6 Build Environm ent with the USB DF U Boot Loader .................................................... 14
3 Te sting E nvironme nt ................................................................................................................... 17
3.1 EM V Level I Compl iant Testing .............................................................................................. 17
3.2 CCI D Testin g ......................................................................................................................... 17
3.2.1 USB Testing: Microsoft HCT/DTM, and USB Command Verifier ................................ 17
3.2.2 Serial Testing ............................................................................................................ 18
4 Design Reference ........................................................................................................................ 19
4.1 Memory Map .......................................................................................................................... 19
4.1.1 Progr am Memory ....................................................................................................... 19
4.1.2 External D ata M emory ............................................................................................... 20
4.1.3 Internal Data Memory ................................................................................................ 20
4.2 Low-level A PI ......................................................................................................................... 20
4.2.1 Keyboar d Driver API – A vailable with all 73S12 xxF Devices ....................................... 21
4.2.2 LCD Driver API – Availabl e with all 73S12xxF Devices .............................................. 23
4.2.3 LED Driver AP I – A vailable with all 73S12 xxF Devices............................................... 24
4.2.4 Real Time Clock AP I - Available with the 68-pin 73S12xxF ....................................... 26
4.2.5 Smar t Card Interface Dri ver API – Available with all 73S1 2xxF Devices ..................... 30
4.2.6 SERIAL (RS232) Dri ver API – Available with all 73S12 xxF Devices ........................... 39
4.2.7 USB API – Available with 64K Flash version of the 73S12xxF ................................... 42
4.2.8 Clock Gener ator Cir cuit API – Available with all 73S12 xxF Devices ........................... 51
4.2.9 Power Man agement API – Available wit h all 7 3S12 xxF Devices ................................ 52
4.2.10 Analog Threshold M anagement D r i ver API – Available with all 73S12 xxF Devices ..... 53
4.2.11 Event Management API – Available with all 73 S12xxF Devices ................................. 55
4.2.12 Timers API – A vailable with all 73S12 xxF Devices ..................................................... 57
4.2.13 User IO API – Available with all 73S12 xxF Devices ................................................... 58
4.2.14 External Interrupts API – Available with all 73S12 xxF Devices ................................... 60
4.2.15 Special Function R egister API – A vailable with all 73S12 xxF Devices ........................ 61
4.2.16 Flash/M emory API – Available with all 73 S12xxF Devices.......................................... 63
4.2.17 Boot Loader and Passcode M anagement – Available with the LAPI-*BL. lib Only ....... 67
4.2.18 Secur ity Mode Management - Available with the LAPI -*BL.lib Only ........................... 69
4.2.19 Other Mi scell aneous API Calls – Available with all 7 3S12xxF Devices ....................... 71
4.3 High-L evel AP I ....................................................................................................................... 72
4.3.1 Smar t Card Contr ol ................................................................................................... 72
4.4 F lash Pr ogrammi ng ............................................................................................................... 85
73S12xxF Software User Guide UG_12xxF_016
4 R ev. 1.50
4.5 Test Tools and Cer tification/co mpliance 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.3 VISA-1 Loopback Test ............................................................................ 90
4.5.2 VISA-2 Loopback Test .............................................................................................. 91
5 Related Documentation .............................................................................................................. 92
6 Contac t Informa ti on .................................................................................................................... 92
Revision History .................................................................................................................................. 93
Figures
Fi gure 1: Software Architecture Diagram .................................................................................................. 9
Figure 2: Device Options for Building with the Boot Loader .................................................................... 12
Figure 3: Target Options for Building with the Boot Loader .................................................................... 13
Figure 4: C51 Options for Building with the Boot Loader ........................................................................ 13
Figure 5: Target Options for Building with the DFU Boot Loader ............................................................ 15
Figure 6: C51 Options for Building with the Boot Loader ........................................................................ 16
Fi gure 7: M emory Layout ....................................................................................................................... 19
Fig ure 8: Smart Card Rx/Tx Tim ing ........................................................................................................ 31
Fi gure 9: Boot Loader Scenari o ............................................................................................................. 67
Figure 10: FLASH Download and Pr ogramming P r ocess ....................................................................... 68
Figu re 11: EMV PSE Test Flow Chart .................................................................................................... 87
Figure 1 2: MCI Test Flow Chart with PTS/P PS ...................................................................................... 88
Figure 1 3: MCI Test Flow Chart without PTS /PP S ................................................................................. 89
Figure 14: VISA-1 Loopback Test F low Ch ar t ........................................................................................ 90
Figure 15: VISA-2 Loopback Test F low Ch ar t ........................................................................................ 91
Tables
Tabl e 1: Upper 1 KB Exter nal D ata M emory layout ................................................................................ 20
Tabl e 2: IRAM Special Function Regi ster M ap ....................................................................................... 20
Tabl e 3: Interr upt Source s and Pri or ity L evel .......................................................................................... 21
Table 4: Clock Speeds and Baud Rates Suppor ted ............................................................................... 51
Tabl e 5: Securi ty Mode Actions Al l owed ................................................................................................ 70
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 5
1 Introduction
The Teridian Semi conductor Corpor ation 73S12xxF single-chip Smart Card Terminal Control l ers consist
of the 73S1209F, 73S1210F, 73S1215F and 73S1217F. These System-on-Chip devices provide the
fun ct ions necessary to bui ld a l ow-cost smart card terminal.
The 73S12xxF Evaluation Board all ows development of an embedded application in conjunction with an
In-Circuit E mu lator (ICE). An applica tion can be programmed in either ANSI C or 80515 assem bly
language using this evaluation board.
Teridian provides a development Toolkit that i ncludes a set of libr ar i es ( Appl i cati on Programming
I nt er face or API ) . The API i s written in ANSI C to co nt r ol all the features prese nt on the evaluation
boards. These l ibrar ies include functions to manage the low-level 80515 core functions such as memory,
cl ock, p ower modes, int er r upts; and high-level functions such as the Liquid Crystal Display (LCD),
keyboard, Real-Time C lock ( RTC), smar t car d interfaces, U niversa l Serial Bus ( U SB)/Ser ial i nterface s and
I/Os. These APIs r educe development ti me dr amati cally, since they allow the developer to focus on
developing the application without dealing with the low-level layer such as hardware contr ol , timing, etc.
Thi s docum ent describes the Toolkit’s hier ar chica l layers and how t o use them.
Certain function blocks (such as USB and RTC) are not available on all 73S12xxF devices. As a r esult,
t he related APIs can not be used wi th some ICs. Refer to the data sheets for further details.
This document appli es to the following components:
• LAPI Version 4.00 (DFU), LAPI Version 3.30 (BL), LAPI Version 2.30 (non-BL)
• HAPI Version 4. 00 (DFU), HAPI Version 3.30 (BL), HAPI Version 2.40 (non-BL)
• S er ial Pseudo-CCID App lication Version 3. 1
• USB CCI D Application Version 2.1 (DFU), USB CCID A pplicat ion Version 1.5 (non-DFU)
• Devices: 1215A05, 1217A06 and 1210/1209A02
1.1 Acronyms
APDU Appl i cati on Protocol D ata Uni t
API Application Programm ing Interface
ATR Answer To Reset
BL Boot Loader
CCID Int egrated Cir cuit Car d Inter face Device
COM Communica tion Port
DFU Device Fi r mware Upgr ade
DTK Development ToolKit
DTM Device Test Manager
EMV Eur o, M asterCard®, V isa®
HAPI High-level API
HCT Hardware Compat i bil ity Test
ICC Int egrated Cir cuit Car d
ISO Inter national Standards Or ganizati on
ISP In-System Programming
JICSAP Japan IC Card System Application council
LAPI Low-level API
LAPIE Low-level API exerciser
LCD L iquid Crystal Display
Non-BL Non Boot Loader
PC Personal Computer
PIN Per sonal Indenti fi cati on
RAM Random Access Memory
ROM Read O nly Memory
73S12xxF Software User Guide UG_12xxF_016
6 R ev. 1.50
RTC Real Time Clock
TSC Teridian Semiconductor Cor porati on
USB Universal Serial Bus
WHQL Windows H ar dware Quality Lab
1.2 Use of this Document
The reader should be fami l iar with microprocessors, particularly the 80C51/80C52/80515 architecture,
firmware, embedded software d evelopment and smart car d appl ication. Knowled ge of the USB 2.0
Specification, ISO 7816 Parts 1/2/3/4 and EMV2000 standards may also be hel pfu l.
This docum ent presents the software features as designed in the 73S12xxF Evaluati on Board. Users
should also have available other 73S12xxF publications such as the data sheet for the particular
73S12xxF device being used, the 72S12xxF Evaluation Board User’s Guide, and the applica tion not es
for addi tional detail s and recent development i nformation.
1.3 Statement of Compliance
The soft ware and hardware for the 73S12xxF mee ts or exce eds USB 2.0 Full Speed, EMV2000 (both
T=0 and T=1 protocols) and ISO 7816 protocol standards. The W indows® XP USB CCID Driver is
designed to meet Mi crosoft Windows Logo co mpliance . Refer to the respective documentati on for further
information about these standards.
The embedded appl ica tions (and their associated librari es) have p assed the USB.org USB Command
V er ifier version 1.3 Bet a, Microsoft HCT version 12.01.1 for U SB , Microsoft DTM for both XP and Vi sta,
and EMV Level 1 compliant testing.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 7
2 Design Guide
This section provides designers with basic guidance in developing smart card reader applications utilizing
the TSC 73S12xxF device s. Th er e ar e three types of appli cati ons that can be developed:
• A Host appli cati on (for example: an application residing on a PC, e.g. Windows 2000, Windows XP,
Windows CE or in a host mi croprocessor ) .
• An Embedded application using both High-level APIs an d Low-level API s (in Flash).
• An Embedded application using the Low-level A PI s on ly (in Flash).
Ther e ar e two options to connect t he 73S12xxF Evaluati on Board or demo boar ds to a PC or host
controller:
• UART/RS232 serial interface.
• USB V2.0 full speed/12 Mbps interface.
2.1 Development Environment
2.1.1 Hard ware Requ irem en ts
The recommended hardware requir ements include:
• Teridian 73S12xxF Evaluation Board.
• AC Adaptor (AC/DC output) or Variable Bench Power Supply.
• PC Pen tiu m® with 512 MB RAM and 10 GB hard drive, 2 COM ports, and 2 USB port (if the USB
interface is utilized) running Windows XP.
O pt ional Hardware in cludes:
• Signum System s ADM-51 In-Circuit Emulator (for debugging the embedded application) with or
withou t tr ace capabil i ty. Si gnum references this device as the ADM-51 Emulator. This device is
configured to use one of the PC’s USB Ports. Cont act Signum System s at www.signumsystems.com
for the latest version of the ICE software.
• The Teridi an Fl ash Programming Tool (for programmi ng F lash when a Signum ADM-51 ICE is not
available).
2.1.2 S oftw ar e Requ irem en ts
The foll owing are the recommended so ftware requirements:
• For embedded application programming:
Keil™ Compiler. Ver sion 7.0 or later is recommended.
• Keil μVision®2 or μVision3 IDE.
• If an ICE is u sed, Sign um Systems software (comes with S ig nu m S ystems A DM-51 ICE hardware).
The IC E can also be used to program Flash.
• A Teridian Fl ash Programmer ( TFP) module for progr amming F l ash.
• For Windows PC application programming:
Visual Basic®, Visual S tu dio® or Visual C/C++® for Windows 2000 or W indows XP.
• Optionally, Keil’s extended linker (LX51 instead of BL51) for code size optimization purposes.
The foll owing s oftware tools/programs are included in the 73S12xxF Development Kit and should be
instal led on t he development PC:
USB View – a shar eware PC tool which can be downloaded from www.usb.org.
usbccid.sys/usbccid.inf – a Microsoft gen eric Wind ows X P CCI D USB d river.
73S12xxF Software User Guide UG_12xxF_016
8 R ev. 1.50
CCIDTSC-*.sys/CCIDTSC-*.inf – Teridian Wind ows Drivers.
ccidusb-*.hex – an embedded application used for USB CCID com m unications with Windows or
Linux OS. This embedded program can be used with either Microsoft’s generic U SB dri ver 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.sys
USB dr iver with t he evaluation board programmed with the CCIDUSB-*.hex firmware.
Low-level A PI Library – an em bedded flash module that provides low-level APIs ( physi cal l ayer) to
control the 73S12xxF.
High-level API Library – an em bedded flash module at the pr otocol l evel that provides API s to contr ol
different features of the Smar t Card. EMV Level I protocol l ayer i s i mpl emented wit hin this module.
Include/ header fi l es for both the Low-level API and the High-level A PI lib raries.
Sample co de for S erial’s Pseudo CC ID pr otocol . For the US B int erface, t he USB CCID firmware
source code is also included.
Linux driver for USB CCID and Linux Application for USB DFU i nterface .
2.2 Software Build Environment
I nstall the Kei l compi ler and se l ect al l defaul t options ( r ecommended) . When prompted for a t ar get
device , sel ect TSC-73S12xxF. This opt ion may n ot be available on ol der versions of the compiler. In t his
case, select TSC 73M6513. For development, an upgrade to a newer version of the Keil com piler is
highly recomm ended. This option can be changed at any tim e by:
Under ‘Project’ – ‘ Select Device for target ‘Target1’ ‘ – CPU tab’ – scroll down to TDK Semiconductor
(wit h older version of K ei l) or Teridian Semico nductor ( avail able with newer ver sion of Keil) – select
either 71M6513 or 73S12xx.
Under ‘Project’ – ‘ Options for target ‘ target1’’ – Target tab – Xdata memor y field, the R AM start
address should be set to 0x0000, and RAM size should be set to 0x0800.
2.2.1 S oftw ar e Architecture
The 73S12xxF soft ware archi tecture is par titi oned int o three separ ate layers:
• The Low-level API (LAPI) device or physi cal l ayer, wh i ch contai ns a set of functi on calls to directl y
manage the peripherals and CPU management ( such as clock, timing, power saving, etc.).
• The seco nd l ayer is the High-level API (HAPI), which is essentiall y the protoco l layer. It provides
functions for communication with the smart card (ICC).
• The third layer is the appl i cati on layer. Th i s l ayer i s left for the applicati on software developer to
design any suitable smart card reader applica tions.
Figure 1 shows the parti tions for each soft ware co mponent and its approximate memory size . As
illustrated, ther e ar e many di fferent ways an appli cati on can be designed and implemented. Section 4
Design Reference describes the API functions within each com ponent in more det ail. The e mbedded
appl ica tion sample source code for most of t he main featur es of the chip i s provided in the release.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 9
Application
Low Level API - Core
Hardware
73S12xxF
PC
Embedded
Application
TSC Serial Pseudo -
CCID Application
(32K)
USB CCID Driver or
COM port Driver
size: 12K
USB
COM / SLIP Message
Protocol Layer
Device Layer Application Layer
ICC
14K
TSC USB CCID
Application
(36K)
COM
SC LAPI (Internal
slot only)
SC LAPI (Internal
or I2C interface)
size: < 1K Size: 2K
Figure 1: Software Architecture Diagram
(Sizes indicated are approximate)
73S12xxF Software User Guide UG_12xxF_016
10 R ev. 1.50
2.2.2 API/ Libr ary an d Header F iles
The lib rary files incl uded in t he software development kit ar e listed below (see Figure 1: Software
A r chitecture Diagr am for the library partitions). The following nomenclature appli es to the file names:
• ‘?’ is eit her ‘S’ (for Single-8 010) or ‘M’ (for Mul tiple-8010)
• ‘xx’ is ‘BL’ (for Serial Boot Loader) , ‘DFU’ for USB DFU Boot Loader or empty.
• There ar e other versions such as LA PI -MS1.LIB, LAPI-S L ED.LIB, that are specific builds for specific
hardware setups and are typically NOT included in the sample applicat i on project files. F or all
evalu ation purposes, these fi l es will NOT be used.
The High-level A PI l i br a r y doe s no t i nc l ude a USB API. For the U SB 2.0 Specification (specifically,
chapter 9 of the specification), the LA PI l a yer handles a ll endpo i nt 0 ( or control endpoint) communications
w i th the ho st; thus a High-level API for USB is not necessary. An application can call the LAPI USB
functions directly f o r all o f its bulk and inte r rupt e ndpo i nt c o mmuni ca t i o ns.
LAPI-?xx.lib1
I2C_SC-?xx.lib Low-level API library containing co nt r ol of both i nternal and external smart
card slots. This library should be included in an application that supports
an I2C interface via an 8010 IC.
Low-level API l ibr ar y containing all nece ssary cor e contr ols .
ICC_API-?xx.lib High-level Smart C ard AP I li brary for Smart Card .
I n addition, the foll owing header ( .h) and so urce ( .c) files ar e included:
API_12.h Low-level header file. Include this file in all embedded applications.
Api_struct_12.h Low-level header fi l e with all enumerati on t ypes defined.
Reg12xx.h Low-level header file specific to the 73S12xxF p er i pheral registers.
LangIDs.h Low-level h eader fil e. I nclude t his fil e i n all embedded appl i cati ons for U SB
communication.
Portable.h Low-level header file. Include this file in all embedded appl i cati ons.
Reg_banks_12.h Low-level header file. Include this file in all embedded applications.
ICCMgt.h High-level ICC header file. I nclude this file wh en the ICC_A PI.lib is used.
Allocate.c High-level API common file that indicates the specific number of com m ands
t hat can be used for each High-level API l ibrary.
Allocate.h High-level AP I common header fil e used with all ocate.c.
Commands.h High-level API common header fi l e used with all ocate.h.
CCID S ou rce See the CCIDAP_73S12xx_V...pdf file under the CCI D USB F irmware
folder.
P-CCID Source See the 12xxANPseudo-CCID-SerialProtocol…pd f file in the TSC-
12xxRS232\vx.xx\TSCP-CCID\Firmware\Doc folder.
1 When the low-level LAPI -?xx.LIB library is included in an application, the compiler requires that the
m odu les within the library be excl usi vely selected ; otherwise, it will not b e in cl uded . No error/warnin g will
be displayed during the build but when the hex file is downloaded and run, the intended function will not
operate as exp ected. To avoid thi s probl em, right -cli ck on the low-level LAPI -?xx.LIB library (after adding
it to the proj ect) , sel ect ‘ opt ions for F i le LAPI -?xx.LIB’ – and under ‘Select Modules to Always Include’,
sel ect the modul es that t he applicati on use s, as l i sted. If pr ogram space permits, select al l listed
modules. This setup can be optimized l ater ( once the applicati on code is stabl e) by desel ecti ng unused
modules to r educe code space.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 11
2.2.3 E xter n al App lication
A n exter nal appli cati on ca n run on a PC or any host microproces sor. The 73S12xxF supports two
options to i nterface with a PC exter nal applica tion: RS -232/Serial interface or USB V2.0 full speed
interface.
RS232 / Serial Interface
When using the RS-232 or a generic asynchronous seri al int er face, TSC can provide the s ample so urce
code for a ser ial / RS-232 firm ware application. It implements a SLIP protocol which enabl es the t r ansfer
of d ata bet ween the PC (or a host mi croprocessor ) and the 73S12xxF. The seri al communi cati on speed
can range from 9600 bps to 115200 bps, with consider ation of the sel ected CPU clock speed. Contact a
Teridian Semiconductor sa les r epresentati ve for availability. For more i nformation, r efer to the Pseudo-
CCID Host GUI Users Guide, the Pseudo-CCID Host Ap plication Guide, and the Pseudo-CCID
Serial/RS232 Firmware Application Note.
USB V2.0 Full Speed Interface
When using the USB V2.0 full speed interface, the communication speed is fixed at 12 Mbps. Software
included with t he TSC 73S12xxF Evaluat i on Boards provides sample sour ce code for a USB fir mware
appl ica tion to be run with either a Mi crosoft generic C C ID USB dr i ver (for XP ) or the TSC customized
driver (also included in the rel ease). When the CCID-USB firmware is loaded and ei ther the Microsoft or
TSC driver is used on the host side, any PC /SC co mpliant applicati on for Windows XP would be able to
communica te and contr ol the Reader. F or more information, refer to the USB-CCID Host GUI Users
Guide and the CCID A pplication Note.
2.2.4 Embedded Application
A use r written embedded applicati on ca n link directl y to the TSC low-level API to better handl e hardware
con trol, timing or interrupts. In addition, an embedded application can be significantly simplified by using
the TSC High-level API t o gain access t o the Smart C ar d protocol interfaces, especially when software
certification is desired to meet USB 2.0, EMV 2000, ISO 7816 or Microsoft Windows Logo.
2.2.5 Build Environment w ith the Serial Boot Loa der
Starting with the Teridian P-CCID Release version 2.00 or higher, t he Boot Loader API is incl uded in the
Low-Level li brary (LAP I-?BL.lib). When linking the application with the libraries containing the boot
loader, a few rul es must be adhered t o. Follow the instructions described below.
LAPI-?BL.lib version 3.xx supports the Boot Loader with Serial/RS-232 interface only.
73S12xxF Software User Guide UG_12xxF_016
12 R ev. 1.50
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 t he Boot Loader and the Teridian Pseudo-
CCID ap plicat ion with in 32 K of Flash. As a r esult, appl i cati ons that use these components must be built
with this option enabled in the compiler in order for the project to build.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 13
Figure 3: Ta r get Options for Bui l ding with the Boot Loader
Off-chip code memory should be set to start at 0x0200 since the first page (512 bytes) of Flash is
rese r ved for boot code (se e Figure 3).
Figure 4: C51 Options for Bui l ding with the Boot Loader
73S12xxF Software User Guide UG_12xxF_016
14 R ev. 1.50
The Preprocessor Sym bol “MULTI8010” ( r efer to Figure 4) is used for a hardware co nfigur ation wh er e
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 pr oject files set up for a multiple 8010 configuration have th e letter ‘M’ in
their filename. For example, the Low-Level library that supports the MULTI8010 configuration would be
named LAPI-MBL.lib.
The Pr eproce ssor Sym bol “SINGLE8010” is used instead of “MULTI8010” for a hardware confi gurati on
where a single 8010 and a custom mux are use d to drive u p t o four exter nal smart card slots. Associated
library or pr oject files set up for single 8010 configuration have the lett er ‘S ’ in t heir filename. This
configuration is supported under the Serial /RS232 i nterface only.
The prepr ocessor symbol “ BOOTLOADER” is used t o incorporate the Serial/RS232 boot loader por tion of
the LAPI. This directive is used when linking to a librar y with ‘B L’ in it s name. In terrupt vectors start at
address 0x0200 due to the B OO TLO ADER’s resid ence. All associat ed li brary or pr oject files set up for
t he Boot Loader co nfiguration have t he letter s ‘ BL’ i n thei r filename.
TSCP-CCID Release version 2. 00 or higher (a separate release built specifically for Teridian’s
Pseudo-CCID RS-232 Ser i al int er face) has configured all its build files for the appropriate build
environm ent and specific configuration. It is NOT recomm ended that these values be changed, in other
words, the proj ect files ( *.uv2) shoul d not be altered. Contact a Teridian S ales Representat ive for fur ther
inquiry.
2.2.6 Build Environment w ith the USB DFU Boot Loader
Starting with the Teridian CCID USB Release version 2.00 or higher, the DFU Boot Loader i s i ncl uded in
t he Low-Level li brary (LAPI-MDFU.lib ). The DF U Boot Loader has a d ifferent architecture than the
S er ial/RS232 Boot Loader described in above section. It is a stand-alone fir mware ap pli cati on that r uns
as a D FU class (0xFE) device wh er eas the Serial/RS-2 32 Boot Loader i s part of t he LAPI l ibr ar y. When
linki ng th e applicat ion with the libraries containing the DFU b oot loader a few ru les must be adher ed t o.
Fol l ow t he instr uctions descri bed below.
The DFU boot loader is supported under the USB interface only.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 15
Figure 5: Target Options for Building with the DFU Boot Loade r
Figure 5 shows the application’s starting address. It m ust be set to start at 0x1802. The Flash address
range from 0x0000 through 0x17FF is reserved inclusively for the DFU Boot Loader.
73S12xxF Software User Guide UG_12xxF_016
16 R ev. 1.50
Figure 6: C51 Options for Buil di ng wi th the Boot Loader
In Figure 6, the int er r upt vector s address must be se t t o wh er e the appli cati on star ts, as descri bed above.
The Preproce ssor Symbol “ DFU” i s used to link in the DFU option as implem ented in LAPI-MDFU.LIB
and ICC-A PI _MDFU.lib. Review the 12xxBootLoaderFir mwareA NV…pdf for detailed information about
this option. The associat ed li braries built to support this option has the letter s “DFU” i n thei r filenames.
The Preproce ssor Symbol “ LEDM GT” indi cates status of Smart Card’s even ts as descri bed in t he
CCIDAP_73S12xx_V…pdf. This option is only implemented and applicable at the firmware application
level. Any versi on of t he li brari es would work whether this option is use d or not.
The USB inter face only supports “MULTI8010” hardware configuration; thus, “SINGLE8010” will not be
used.
The Pr eproce ssor Sym bol “HIGH C PU” is to set the CPU clock to r un at 24MHz. This option is set and
used in the CCID application code. Without this option, the default CPU clock is 3.69MHz.
The source code included in the CCID release has all its build files set up for the appropriate build
environm ent and specific configuration. It is NOT recomm ended that these values be changed, in other
words, the proj ect files ( *.uv2) shoul d not be altered. Contact a Teridian Sales Repr esent ative for fur ther
inquiry.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 17
3 Tes ting Environment
Teridian performs c onformance and ce r tification t esti ng to verify both the 73S12xxF IC (hardware and
electrical) and li braries ( protocol, timing and appl i cati on firmware an d drivers) . These tests are dictated
by specific standards. Each st andard has a specific set of hardware an d software configur ation
requirements. This section describes the protocol porti on of the testing that has been per formed.
3.1 EMV Level I Compliant Testing
Th is section d escribes the EMV Level I compliant protocol testing. E M V Level I E lect rical t esting is
beyond the scope of this document.
Depending on the accredited test labs, EMV Level I co mpliant protocol testing can be done using either a
Visa or a MasterCard test suite under the Payment System Environment (PSE). E ach test environment
has its own se tup/configuration and se lected tests for each set up.
For example, in the MasterC ar d t est suite, ther e ar e a few configurable choice s that must be consider ed.
E ach answer to t hese six questions wou l d requir e a different test setup and expected behavior of the
reader . The true/ fal se answer s shown after the questi ons below wer e sel ected for Teridian’s EMV Level I
compliant testing.
Terminal supports param eter s negotiation technique: (true/false) - true
Term inal deactivat es aft er I-Block with LE N = 0xFF: (true/false) - true
Terminal supports resynchronization: (true/false) - false
Terminal deacti vates after BWT excess: (true/false) - true
Terminal deacti vates after CWT excess: (true/false) - true
Terminal sends S( Abort Response): (true/false) – false
The EMV Level I M aster C ar d t est suite was per formed by both an independent/accredit ed t est l ab and
by Teridian’s internal test lab. The testing was done using internal slot (slot #1) and all internal EMV
Level I tests passed.
E M V Level I formal compliant test at an accredited lab (Cetecom) i s i n progress.
3.2 CCID Testing
The 73S12xxF part provides two contr ol int er faces to the host: U SB and Ser ial/RS232. Using either of
these bus types, a command can be se nt from the host t o the chip t o cont r ol the Smart C ar d. Because
of this co nt r ol interface , testi ng under the CCID Specification usually involves two p ar ts: Smart Card and
Bus type (USB or Serial/RS232).
3.2.1 US B T estin g: Microsoft HCT/DT M, an d US B Com man d Verifier
Teridian used three different tests to verify USB CCI D complian ce:
1. Microsoft Hardware Compatibi lity Test (H CT) for Wi ndows Logo or their updated test suite: Device
Test M anager for Vista and Windows X P, which tests CCI D and PC/ SC complian ces.
2. USB 2.0 Chapter 9 Test (USB C ommand V er ifier Test) .
3. L i nux Dri ver test using the available smar t car d t est tool downl oaded from the i nternet.
The H C T/ DTM S mart Card t est was completed in-house using t he I FDTest. exe t hat ca me wit h HC T
version 12.01.1. (Note: This test sti l l requir es the use of older PC/SC test ca r ds that are no longer
availabl e for purchase) At this rel ease, the t wo V i sta drivers have been certified with M icroso ft. The ad-
hoc testing was performed using both the TSC USB driver and the Microsoft g en eric USB CCID d river.
The D TM test was run and certified with Microsoft using only the TSC customized dr iver.
73S12xxF Software User Guide UG_12xxF_016
18 R ev. 1.50
The USB Command Ver ifier version 1.3 Bet a ( latest versi on) was also r un wit h t his rel ease usi ng the TSC
customized driver. The USB.ORG com pliant testing was com pleted both in house and by an accredited,
independent lab (NTS). Both tests passed.
The Linux driver was d one in-house, but previously version 1.20 of the TSC CCI DUSB firm ware was
certified by the Linux CCIDUSB driver developer.
3.2.2 S er ial T esting
PCCID is built in a separate release that includes a host applica tion to contr ol the 73S12xxF device
programmed with the P CCID firmware. The testin g was done using this proprietary interface ranging
from EM V Level I pr otocol testi ng to slot-switching Smart Card Tests.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 19
4 Design Reference
As depicted in Figure 1: S oftware Archi tecture Diagr am, the 73S12xxF provides many design options for
an appli cati on developer. Details of the software modules are described in t his section .
4.1 Memory Map
The 73S12xxF contains a high performance, em bedded 80515 core, referred to as the ‘core’. It execut es
all ASM51 instructions and has the same instruction set as the 80C51.
The core supports separ ate Progr am and Data memory as shown in Figure 7. The 73S12xxF family of
devices has two p r ogram sizes (32 KB and 64 KB). This program space is segmented into 512-byte
pages. Th er e ar e 2048 byt es of external dat a RAM ( XData or XRAM) and 256 bytes of internal data
RA M (IDat a or IRAM).
0000 00
80
FFFF
0000
FFFF FFFF
07FF
0800
SFR
IRAM
upper
IRAM
lower
XRAM
2 K Bytes
FLASH
PROGRAM
MEMORY
64 K Bytes
EXTERNAL
DATA
MEMORY
INTERNAL
DATA
MEMORY
Reserved for
Smart Card,
USB,
Peripheral
Control
Registers
7F
80
FC00
Direct
Addressing
Indirect
Addressing
Direct/Indirect
Adressing
Figure 7: Memory Layout
4.1.1 Program Memory
The 73S12xxF is available with either 64 KB or 32 KB of pr ogram memory. The 73S1209F/73S1210F
have 32 KB and the 73S1215F/73S1217F have 64 KB. Con tact a Teridian Sales Repr esent ative for
order i ng i nformati on.
73S12xxF Software User Guide UG_12xxF_016
20 R ev. 1.50
4.1.2 E xter n al Data Memory
The 2 KB of XRAM are avail able at address locations 0x0000 through 0x07FF. The upper 1K bytes of
t he external data memory space (from 0xFC00 t o 0 xFFFF) is reserved for additional special function
registers for the 73S12xxF chip and is se gment ed as shown in Table 1.
Table 1: Upper 1 KB External Data Memory layout
Function Spa ce # Bytes Sta r ti ng Address Endi ng Address
P er ipheral Contr ol
128
0xFF80
0xFFFF
S mart Card Control 384 0xFE00 0xFF7F
USB Contr ol 512 0xFC00 0xFDFF
4.1.3 Intern al Data Memory
The 256 bytes of IR AM are avail able for use as scratch-pad RAM.
The IRAM Special F unction Registers are mapped as shown in Table 2. Al l r egisters appearing in the
first column (000b) are bi t-addressable:
Table 2: I RAM Spe cial Function Re gister Map
HEX/BIN
000b
001b
010b
011b
100b
101b
110b
111b
0xF8 - 0xFF
0xF0 - 0xF7 b
0xE8 - 0xEF
0xE0 - 0xE7 acc
0xD8 - 0xDF wdcon
0xD0 - 0xD7 psw kcol krow kscan kstat ksize korderl korderh
0xC8 - 0xCF t2con
0xC0 - 0xC7 ircon
0xB8 - 0xBF ien1 ip1 s0relh s1relh
0xB0 - 0xB7 p3 flshctl pgadr
0xA8 - 0xAF ien0 ip0 s0rell
0xA0 - 0xA7 usr15
8 udir15
8
0x98 - 0x9F s0con sobuf ien2 s1con s1buf s1rell
0x90 - 0x97 usr70 udir70 dps erase
0x88 - 0x8F tcon tmod tl0 tl1 th0 th1 ckcon mclkctl
0x80 - 0x87 sp dp1 dph dpl1 dph1 wdtrel pcon
4.2 Low-level API
A low-level Applicati on Programmi ng Interface ( AP I) is pr ovided to co ntrol all hardware peripherals. An
application can link to the low-level API library to utilize t he fun ction s described in subsequent sections.
B efore using the l ow-level API , an embedded appli cati on should call the API_Init() routine in the
beginning of the program as part of its initialization. As a general guideline, any feature to be included or
use d in an applicati on must first ca ll its associated initializati on routine. For example, to l ink the USB
module into an application, U SB_Init( ) must fir st be cal led to i niti alize i ts associated r egisters for the USB
functions.
E ach feature avail able with the 73S12xxF device has a sampl e applica tion to demonstrate the library
function’s usage.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 21
The core provides four i nterrupt prior i ty levels among six group sources. The 73S12xxF sources are
grouped as shown in Table 3. All source s belonging to a group shar e the same i nt er r upt prior i ty level.
The LAPI sets up the fou r prior ity levels for these groups as shown in Table 3.
Table 3: I nterrupt S our ces and Priority Level
Group 6 G r oup 5 Gr oup 4 G r oup 3 Gr oup 2 G r oup 1
I2C USB Smart Car d Ext In t 1 Timer 0 Ext In t0
VDD RTC Timer 1 Ext Int 3 Ext Int 2 Ser ial 1
Analog Keypad
S er ial 0
Priorities as se t in LAPI.LIB:
Highest Low High Lowest Lowest Low
The l ow-level API s ar e l isted below. Additional detail s ar e i n the subsequent subse cti ons.
• K eyboar d Dri ver API – Available with all 73 S12xxF Devices (page 21).
• LCD Driver API – Available with all 73 S12xxF Devices (page 23).
• LED Driver API – Available with all 73 S12xxF Devices (page 24).
• Real Tim e Clock AP I - Available wit h the 68-pin 73S12xxF (page 26).
• S mart Card I nterface D r iver API – A vailable with all 73S12 xxF Devices (page 30).
• SERIAL (RS232) Driver API – Available wit h all 7 3S12xxF Devices (page 39).
• USB API – Available with 64K Flash version of the 73S12xxF (page 42).
• Clock Gener ator Ci r cuit API – A vailable with all 73S12 xxF Devices (page 51).
• P ower Management API – Available with all 73 S12xxF Devices (page 52).
• A nalog Thr eshol d Management Dr iver A PI – Available with all 73S1 2xxF Devices (page 53).
• E vent M anagement API – Available wit h all 7 3S12xxF Devices (page 55).
• Timers API – Available with all 73S12xxF Devices (page 57).
• User IO API – A vailable with all 73S12xxF Devices (page 58).
• Extern al Interrupts API – A vailable with all 73S12 xxF Devices (page 60).
• Special F unction Reg ister API – A vailable with all 73S12 xxF Devices (page 61).
• Fl ash/Memory API – Available with all 73 S12xxF Devices (page 63).
• B oot Loader and Passcode Management – Av ailable with the LAPI-*BL.lib Only (page 67).
• S ecurit y Mode Management - Avail able with the LAPI-*BL.lib Only (page 69).
• O ther Miscellaneous API Calls – A vailable with all 73S12 xxF Devices (page 71).
4.2.1 Keyb oard Driver API – Available with all 73S12xxF Devices
The Keyboard Driver manages the ke ystroke acquisition using a scr ambled al gori thm. It is the High-level
A PI ’s r ole to manage the scrambli ng algorithm. Up to 30 keys can be managed in a 6 row by 5 column
configuration. The APIs below are written to use Har dware Scan enabling. An application can be written
t o bypass Har dware Scanning to per form i ts own manual key scan functional ity. Refer to the 73S12xxF
Data Sheet for information on the ke ypad bypass mode.
The Keyboard Dr i ver API i ncludes:
• KEY_Init () (page 22)
• KEY_Wait () (page 22)
73S12xxF Software User Guide UG_12xxF_016
22 R ev. 1.50
KE Y_I n it ()
Purpose C onfigure the keyboard. This AP I will call the Set _Even t( ) r outine t o enabl e an
Interrupt Service Routine (ISR) to handle keyboard scanning.
Synopsis Voi d KE Y_I nit ( IN unsigned char rows_cols, IN unsigned char debounce_scan );
Parameters RowsCols: Input paramet er
Number of rows on keypad ( max valu e is 6) ti mes eight plus num ber of columns on
keypad ( max valu e is 5), i.e. r ows*8 + col s.
Debounce_scan: Input paramet er
Number of milliseconds to debounce key (granularity is 4ms) plus number of
milliseconds between key scans (1 to 4 ms) 1 = 1 ms; 2 = 2 ms; 3 = 3 m s and 0=4 ms.
Retur n Codes None.
KE Y_Wait ()
Purpose Wait for a keypad input during a maximum time specified by the TimeO ut value.
Ot her even ts ( e.g. Smar t Card insertion and removal) can be specified as exit
conditions for this function.
Synopsis KEY_RC KEY_Wa it (
IN Unsigned Int ScanOrder,
IN Unsigned char TimeOut,
IN Un signed Int ExitOnICCInsert,
IN Unsigned In t ExitOnICCRemoval,
IN Unsigned Word ExitOnEvent,
OUT Unsigned Word *ExitOn,
OUT Unsigned char *KeyCode );
Parameters ScanOrder: Input paramet er
Column scan order , in five se ts of thr ee bits each, wit h the l east signi ficant 3-bits (0-
2) indexing the first column scanned and bits (12-14) indexing the fifth column
scanned.
TimeOut: Input parameter
Timeout value in seconds. If no key is entered within t hi s pe r i od, the functi o n i s aborted.
ExitOnICCInsert: I nput parameter
S pecifies which, i f any, Smar tCard in sertion events are exit conditi ons. Bit[n]
cor r esponds to IC C [n], bit[1] being mapped to the least significant bit. This option
should NOT be used simultaneously with the ExitOnICCRemoval option.
ExitOnICCRemoval: Input parameter
S pecifies which, i f any, Smar tCard removal events are exit conditi ons. Bit[n]
cor r esponds to IC C [n]. This option should NOT be used simultaneously with the
ExitOnICCInsert option.
ExitOnEvent : Input par ameter
On input, specifies which, if any, other events are exit conditions. Possible values are any
combination of the following:
EVENT_EXT0 0x00000001
EVENT_EXT1 0x00000002
EVEN T_EXT2 0x00000004
EVENT_EXT3 0x00000008
EVENT_TIMER0 0x00000010
EVENT_TIMER1 0x00000020
EVENT_ICC 0x00000040
EVENT_RTC 0x00000080 / /not available wit h 73S1205F
EVENT_KEY_DETECT 0x00000100
EVENT_USB 0x00000200 / /not available wit h 73S1205F
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 23
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_S MARTCARD_xxx return code, it specifies wh ich SmartCard event
occurred. Bit[n] corresponds to ICC[n]. If KEY_ERR_E VE NT, it specifies wh ich
EVENT occurred.
KeyCode: Outp u t p arameter
S pecifies the KeyCode that was pressed. The KeyCode is equal to
((row-1 ) * KeypadCols) + ( col -1), where column r anges from 1 to KeypadCols and
row ranges from 1 to K eypadRows.
Retur n Codes
KEY_OK Successful operation: a vali d ke y was pressed.
KEY_ERR_TIMEOUT TimeOut error.
KEY_ERR_SMARTCARD_INSERTED SmartCard inser ti on detected.
KEY_ERR_SMARTCARD_REMOVED SmartCard removal detected.
KEY_ERR_EVENT
S canO r der ca n be any per mutation of the values 0,1,2,3 and 4. If an unscrambled order is
desired, se t ScanOrder = 0x4688. The scrambling algorithm is handled by the caller. If the
event was a Smart Card event exit, use ICC_Status() to di scover which car d caused the exit.
4.2.2 L CD Dr iver API – Available w ith all 73S12xxF Devices
The LCD inter face supports a generic external LC D co ntrol l er and uses USR I/O that is accessed by the
LCD driver API . The LCD ca lls manage a gener i c 7-bit (4-bit data bus) interface to the external LCD
controller. For the 73S1215F Evaluation Board, where the MDL-16265 LCD is used, USR pins 0-3 are
use d for t he 4-bit data bus, USR pins 4, 5 and 6 are used for E, RW and RS, respectively).
The USR IO pins can be used for several different featur es such as LC D, I2C addressing for external
sl ots and a Serial RS232 in ter face to a Windows X P host depending on the TSC evalu ation board and
the application firmware being used. Care must be taken by the application to make sur e there is no
conflicting usage. The LCD API includes:
• LCD_Init () (page 23)
• LCD_Command () (page 24)
• LCD_Data_Write () (page 24)
• LCD_D ata_Read () (page 24)
LCD_Init ()
Purpose Initialize the L CD interface. After initialization the Disp lay will be O N an d cl eared. A
block cursor will be at the home position.
Synopsis Voi d LCD_ Init ( void );
Parameters None.
Retur n Codes None.
73S12xxF Software User Guide UG_12xxF_016
24 R ev. 1.50
LCD_Command ()
Purpose Send comm and to LCD.
Synopsis Voi d LCD_ Command ( IN char LcdCmd );
Parameters LcdCmd: Input parameter
8-bit command to cont r ol the LCD . A vail able commands are:
LCD_CLEAR Cl ear displ ay and r eturn curso r to home.
LCD_HOME Return display and cursor to hom e
position.
LCD_MO DE | LCD_ INC Increment cursor on read/write of display.
LCD_MO DE | LCD_ INC|LCD_SHIF T Increment cursor and shift display on
read/wri te of display.
LCD_CTRL | LCD_DON | LCD_CO N Disp lay ON and cursor ON (visible).
LCD_CTRL | LCD_DON Display ON an d cursor OFF (invisible).
LCD_CTRL | LCD_BO N Display O N and blinki ng O N.
LCD_CURSOR Shi ft cursor left.
LCD_CURSO R | LCD_ RL Shift cursor right.
LCD_CURSO R | LCD_SC Shift display left.
Retur n Codes None.
LCD_Data_Write ()
Purpose Write data to LC D.
Synopsis Void LCD_Data_Write ( IN char LcdData );
Parameters LcdData : Input parameter
8-bit data written to the LCD at the current cursor position.
Return Codes None.
LCD_Data_Read ()
Purpose R ead data from the LCD.
Synopsis Void LCD_Data_Read ( OU T char * LcdData );
Parameters LcdData : Output parameter
8-bit data read from the LCD at the current cursor position.
Retur n Codes None.
4.2.3 LED D r iv e r API – Available with all 73S12xxF Devices
The 73S12xxF provides four LEDs that can be programmed with four levels of output current: 0 mA
(LED_OFF), 2 mA (LED_DIM), 4 mA (LED_NORMAL) and 10 mA (LED_BRIGHT). On the 73S1205F,
only LED 0 and LED 1 (lower two bi ts) ar e available.
The L ED Driver API incl udes:
• LED_Config () (page 25)
• L ED_Write () (page 25)
• LED_Read () (page 25)
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 25
LED_ Config ()
Purpose Configure the LED interface (all pins).
Synopsis Voi d LED_Config ( I N Bbool PU_E nab le, IN enum LED_CURRENT LC );
Parameters PU_Enable: Input paramet er
B oolean value specifies enable ( TRUE) or disabl e ( FALS E) pull -up.
LC: Input par ameter
Enum type indicating the output current level for the LEDs (when turned on). The
following values ar e avail able:
LED_OFF: turn off LED (0 mA).
LED_DIM: turn LED on at dim level (2 mA).
LED_NORMAL: tur n LED on at normal l evel ( 4 mA) .
LED_BRIGHT: turn LED on at brightest level (10 mA).
Retur n Codes None.
LE D _Write ()
Purpose Turn LED on/off. If turned on, the br i ghtness contr ol is possibl e at one of three
levels: Dim, Norm al, Bright as specified in LED_Config().
Synopsis Voi d LCD_ Wr i te ( IN unsigned char LED_Pin, IN unsigned char Value );
Parameters LED_Pin : Input parameter
S elected LED(s) t o be t urned on, wh er e bit[n] = 1 indicates LED[n] to b e written.
Value: Input parameter
V alue to be writ ten to se l ected LED . Bit[n] is the value to be written to LED[n] if
LED [n] is sel ected t o be writ ten t o.
Retur n Codes None.
LED_Read ()
Purpose R ead curr ent state of the LED data.
Synopsis Voi d LCD_ Rea d ( OUT unsigned char LEDValue );
Parameters LEDvalue: Output p arameter
Bit[0] indicates the current state of LED 0.
Bit[1] indicates the current state of LED 1.
Bit[2] indicates the current state of LED 2 – Not available in 73S1205F.
Bit[3] indicates the current state of LED 3 – N o t availa ble in 73S1205F.
Bit[4] indicates the stat e of the pull-up (1=enable).
Bit[5,6] indicate the output curr ent level wher e:
00 = OFF
01 = DIM
1 0 = NORMAL
11 = BRI GHT
Retur n Codes None.
73S12xxF Software User Guide UG_12xxF_016
26 R ev. 1.50
4.2.4 Real Tim e Clock API - Available with the 68-pin 73S12xxF
The 73S12xx F 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
f unc ti o n, alo ng with a 24-bit accumulator , is pr o vide d t o corr e c t the c l o c k dr i ft i nduced by t he qua r t z c r ystal.
The device al so supports a watchdog capability. Thi s feat ure will give t he processor 0.5 seconds to
respond to an RTC interrupt. If the RTC interrupt is not serviced within 0.5 seconds, a full R ESET to the
72S12xxF is performed. To use the watchdog timer function, the RTC interrupt must be enabled.
Consequently, the watchdog will always be enabled when the RTC interrupt is enabled. It is not possible
to turn off the watchdog while the RTC interrupt is enabled.
Care should be take n as i t is possibl e for the device to be put into an infini te r eset l oop when an
RTC interrupt is not serviced on time (within 0.5 second). W hen this problem occurs,
reprogram the F l ash wi th a known good application/program using the TFP.
The RTC block uses the 32768 Hz osci llator signal or divider logic (from t he 1 2 MHz osci llator circuit ) to
produce 0. 5 se cond t ime mar ks. The 32768 Hz oscil l ator can be di sabled ( see the PowerOFF API), but
is intended to operate at al l times in all power consumption modes. If a 32 kHz crystal is not provided,
this oscillator m ust be disabled and the RTC will operate from an i nt er nal 96 MHz clock divided by 2930.
In t his case, the RTC trim value shoul d be set as described in the following paragraph.
The 3-byte accumulator c a n hold 2 24 = 16,777,216, which yie l ds a 0.0596 PPM r e s o l uti o n. U si ng the 12 MHz
oscillator gives 96 MHz/2930 whic h wil l gene r a t e 32,764 H z. The c o r e R TC use s a 32,768 Hz Oscillato r cr y stal .
This yie l ds a 106 PPM error. Therefore, the tr i m v alue = ( 106 PPM) / (.0596 PPM) ~ = 1778 (0x06F2).
When the accumulator r eaches overflow, i t will advance the counter one addi tional count if the trim value
is p ositive, or preven t t he counter from advancing one count i f the tr im valu e is negati ve.
The trim value can be set in the API_12.h file. RTClk_Init () m ust be called prior to using any of the RTC
APIs. Once the RTC is init ialized , the 3 2 kH z OSC clock will always be running. To turn it off, use the
PowerOFF (DISABLE_RTC) API.
The R eal Time Cl ock API is described in detail below and includes:
• RTClk_Init () (page 26)
• RTCClk_Cont rol () (page 27)
• RTClk_Writ e () (page 27)
• RTClk_Read () (page28)
• RTCClk_GetTIME () (page 28)
• RTCClk_Set TIME () (page 29)
RTClk_Init ()
Purpose Initialize the Real Time Clock values by setting the accumulator to 0 and setting the
trim values as defined in api_12.h. The default base day is defined as 12:00:00,
01/01/2005 calculated using the Gregorian/Julian conversion defined in:
http://webexhibits.org/calendars/calendar-christian.html.
When this function is called, the RTC is stopped and restarted. The RTC counter,
t r i m and accum ulator will be l oaded at the next 32 kHz clock positi ve edge. The RTC
inter r upt i s N OT set here. U se R TClk_Con tr ol() to set the inter r upt. The RTC
counter continues to count whether the RTC interrupt is enabled or not.
The Interru pt se r vice rout ine for the RTC interrupt can be masked using the Set_Event (eRTC,
pRTCVector) API. If customization o f the RTC IS R is desirabl e, cal l Set_Event after th is API is
cal led. See Set_Event() for its usage description.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 27
Synopsis V oid RTClk_Init ( void );
Parameters None.
Retur n Codes None.
RTCCl k_Contr o l ()
Purpose Enabl e or disabl e th e RTC interrupt. If enabled, the interrupt interval must be
specified.
Synopsis RTCClk_Control ( I N Bbool RTCI nt_ Enb, IN enum RTC_I NTERV AL int v );
Parameters RTCInt_Enb: Input parameter
Enable (TRUE) or disable (FALSE) the RTC interrupt. If set to Enable when the intv
parameter i s set to N O_I NT, the RTC int er r upt will NOT be enabl ed.
Intv: Input paramet er
The RTC interrupt interval as defined in API_STRUCT_12.h as follows:
HALF_SEC Inter r upt to occur every ½ seco nd.
ONE_SEC Int er r upt to occur every 1 seco nd (defau lt).
TWO_SEC I nt er r upt to occur every 2 seco nds.
FOUR_SEC Interrupt to occur ever y 4 seco nds.
EIGHT_SEC Inter r upt to occur every 8 seco nds.
NO_INT No interrupt.
Retur n Codes None.
The wat chdog ti mer will give t he processor ½ second t o r espond to an RTC int er r upt. If the R TC
inter r upt i s not ser viced withi n thi s ti meframe, a full reset will be performed.
RTClk_Write ()
Purpose Initi alize the Real Time Cl ock co ntrol , counter, accumulator and tr i m registers. When
this function is called , the RTC is stopped and restarted.
Synopsis V oid RTClk_Write ( IN struct RTC_t * pRTC );
Where R TC_t is defined as:
struct RTC_t
{
Unsigned char RTCCtl;
Unsigned long RTCCnt;
Unsigned char RTCAcc[3];
Signed char RTCTrim[3];
}
Parameters RTCCtl: Input paramet er
BIT[7-6]: not used
BIT[5]: RTCLoad – when set, RTCCnt , RTCAcc and RTCTrim ar e l oaded at the next
32 kHz clock positive edge.
BIT[4-3]: Set tic i nterval as fol l ows:
0x – 1 second
10 – ½ seco nd
11 – 2 seconds
BIT[2-0]: Set i nterrupt i nterval as fol l ows:
100 – ½ seco nd
0xx – 1 seco nd
101 – 2 seconds
110 – 4 seconds
111 – 8 seconds
73S12xxF Software User Guide UG_12xxF_016
28 R ev. 1.50
RTCCnt: Input par ameter
32-bit RTC coun ter value.
RTCAcc[3]: Input parameter
24-bit accumulator value. Normall y these values are to be initi al ize d only once
during the manufacturing phase.
RTCTrim[3]: I nput parameter
24-bit s i gned t r i mmer value. This i s the offset value use d to co r r ect the quar tz crystal
dri ft. It is the number of ti cks between each co r r ecti on of t he Real Time Cl ock. Use
a negati ve numbers to decrease the tic-count by one and a positive num ber to
increase the t ick-count by 1.
Retur n Codes None.
The RTC can be enabled and disabled via the PowerON() and PowerOFF() or RTCClk_Con trol ()
functions. The new values will not be loaded until the RTCLoad bit (bit 5) of the RTCCtl register
is set (HI).
RTClk_Read ()
Purpose Extract the current Real Time Clock control, counter, accumulator, and trimmer values.
Synopsis Void RT Clk_Read ( IN struct RTC_t * pRTC );
struct RTC_t
{
Unsigned char RTCCtl;
Unsigned long RTCCnt;
Unsigned char RTCAcc[3];
Signed char RTCTrim[3];
}
Parameters RTCCtl: Output paramet er
Cur r ent Real Time Cl ock Control r egister value ( setting).
RTCCnt: Output par ameter
Cur r ent Real Time Cl ock Counter value.
RTCAcc[3]: Output par ameter
Cur r ent Real Time Cl ock accumul ator value.
RTCTrim[3]: Out put par ameter
Current Real Time Clock Trimmer value.
Retur n Codes None.
RTCClk_GetTIME ()
Purpose Extract current ca lendar Time. Time conversi on is done by the Gr egorian/Julian conversion
method as defined on websit e: http://webexhibits.org/calendars/calendar-christian.html.
Synopsis Void RTCCl k_G etTIME ( stru ct C_RTC_t xdata *pRTC_Time )
struct C_RTC_t
{
Unsigned char Sec;
Unsigned char Min;
Unsigned char Hour;
Unsigned char Date;
enum MO NTH Month;
Unsigned integer Year;
enum RTC_INTERV AL TicInterval; //Tic interval - 1, 1/2 or 2 sec
enum RTC_INTERV AL IntInterval; // int in terval. NO_I NT=disab le in t.
};
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 29
Where MONTH is defined as: enum { JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG,
SEP, OCT, NOV, DEC }; and RTC_INTE RVAL is defined as:
en um {HALF_SEC, ONE_SEC, TWO_SEC, F OUR_ SEC, EI GHT_SEC, NO_I NT};
Parameters Sec: Out put paramet er
Current second unit.
Min : Outp u t parameter
Current minute unit.
Hour: Output par ameter
Current hour unit.
Date: Output parameter
Current date unit.
Month: Output paramet er
Current month unit as specified in the enum MONTH type.
Year: O utput paramet er
Current year unit, e.g. 2005.
TicInterval: O utput paramet er
Tic interval as HA LF_SE C, O NE_S EC or TWO_ SEC, defined in RTC_INTERVAL.
IntInterval: Output paramet er
Interrupt interval as defined in RTC_INTERVAL.
Retur n Codes None.
RTCClk_SetTIME ()
Purpose Set time and start clocking immediately. Time conversion is done by the Gregorian/Julian
conversion method as defined on website: http://webexhibits.org/calendars/calendar-
christian.html.
Synopsis Bbool RTCClk_Se tTIME ( stru ct C_RTC_t xdata *RTC_Time )
struct C_RTC_t
{
Unsigned char Sec;
Unsigned char Min;
Unsigned char Hour;
Unsigned char Date;
enum MO NTH Month;
Unsigned integer Year;
enum RTC_INTERV AL TicInterval; //Tic interval - 1, 1/2 or 2 sec
enum RTC_INTERV AL IntInterval; // int in terval. NO_I NT=disab le in t.
};
Where MONTH is defined as: enum { JAN=1, FEB, MAR, APR, MA Y, JUN, JUL,
AUG, SEP, OCT, NOV, DEC }; and RTC_INTERVAL is defined as: enum
{HAL F_SEC, ONE_SEC, TWO_SEC, FOUR_SEC, EIGHT_SEC, NO_INT };
Parameters Sec: Input parameter
Current second unit.
Min: Input parameter
Current minute unit.
Hour: Input parameter
Current hour unit.
Date: Input parameter
Current Date unit.
Month: Input parameter
Current month unit as specified in the enum MONTH type .
73S12xxF Software User Guide UG_12xxF_016
30 R ev. 1.50
Year: Input parameter
Current year unit, e.g. 2005.
TicInterval: Input parameter
Tic interval as HA LF_SE C, O NE_S EC or TWO_ SEC, defined in RTC_I NTERV AL.
IntInterval: Input parameter
Interrupt interval as defined in RTC_INTERVAL.
Retu rn Codes TRUE if su ccess. FA LSE if TicInt erval or Interrupt In terval value is invalid.
4.2.5 S mar t Card Inter face Driver API – Available with all 73S12xxF Devices
The Smart Card I nt er face Dr iver A PI manages al l the Smart C ar d interfaces. Each of the smart car d sl ots
can be indi viduall y activat ed, deactivat ed, etc. since m ost of the functions take the I C C identi fier as an
input. This API handles the physica l layer, i .e., t he inter-character and inter-b lock timeouts. O pt ionally, it
can handle the LRC/CRC com putation.
To switch bet ween multipl e acti vated cards, re-ini tiali ze the selected card ( using the eIccId parameter).
ICC_1ST refers to the internal Smart Card #1. ICC_2ND or higher refers to external slot #2 with I2C
interface (8010 interface) and uses USRIO as its associated address.
When developing an application with an inter nal i nterface only (1 sl ot on ly), in cl ude libraries LAPI.LIB and
Internal-SC.LIB. When developing an application with interface to an internal interface and/or external
slot(s), incl ude l i brari es LAPI.LIB and I2C-SC.LIB ( r eplace Internal -S C.lib with I 2C-SC.LIB).
For an external I2C int er face, it is nece ssary t o assign the I2C address, an d I 2C C ar d Even t signal as
specified by the board design (se e ICC_InitUART() for more det ails).
The Smart Card I nt er face API includes:
• ICC_InitUART() (page 31)
• ICC_Activate() (page 34)
• ICC_Status() (page 35)
• ICC_Tx() (page 36)
• ICC_Rx() (page 37)
• ICC_RxLen() (page 38)
• ICC_RxDone() (page 38)
• ICC_Deactivate() (page 38)
• ICC_Mode() (page 38)
• ICC_Clk_Restart() (page 39)
• ICC_Clk_Stop() (page 39)
Fol l ow t he general procedure described bel ow t o communi cate wit h any asynchronous ICCs present:
1. Initialize the Smart C ar d UAR T parameters for each sel ected card.
2. Activate the card(s) t hat were initialized in Step 1.
3. Re-initialize the Smar t Card UAR T parameters for each card, base d on ATR anal ysis.
4. Negotiate the protocol and/or Fi /D i values for the sel ected cards. (Optional )
5. Update the S mart Card parameters based on the protocol negoti ati on if per formed.
6. Re-initialize the sel ected car d.
7. Transmit r equests to a sel ected car d via I C C_Tx call ( s).
8. Rece i ve responses from a sel ected card via I CC_Rx cal l(s).
9. Repeat Steps 6, 7 and 8 as needed for any activated card.
10. Deactivat e acti ve car d(s).
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 31
Figure 8: Smart Card Rx/Tx Tim ing
ICC_InitUART()
Purpose Initializes t he S mart Card UA RT for the specified ICC.
Synopsis Void I CC_Ini tUART ( IN struct ICC_ In it_t *pICC_Init );
Struct {
enum ICC_ID IccId,
B oolean IccDetect,
enum I CC_HZ IccH z,
unsigned char FiDi,
B oolean IccProtoco l ,
B oolean IccEDCEnabl ed,
Boolean IccEDCTypeCRC,
B oolean IccParityCheck,
B oolean IccBreakGeneration,
unsigned char IccBreakStartPosition,
unsigned char IccBreakDur ation,
unsigned char IccRxRetry,
B oolean IccBreakDetect,
unsigned char IccTxRetry,
TX
EGT < t
TX/RX
BGT < t < B WT (T=1) or WWT (T=0)
RX/TX
t < CWT (T=1) or WWT (T=0)
RX
73S12xxF Software User Guide UG_12xxF_016
32 R ev. 1.50
int IccExtraGu ardTime,
int IccBlockGuardTime,
int I ccCharWaitin gTime,
long in t I ccBlockWaitingTime,
long in t I ccWorkWaitingTime
B oolean IccPU Enabl ed; Boolean IccPD Enabled;
B oolean IccVDDFaultOff;.
enum I CC_ADDR I ccAd dr; // Use ful for exter nal I2C.
enum I CC_RES ET IccExtRst; / / Use ful for exter nal I2C.
enum I CC_CARDE VENT IccCE ; / / U seful for external I2C.
} ICC_Init_t;
Parameters IccId: I nput parameter
Specifies wh ich SmartCard UA RT int erface is to b e in itialized. Possible values are:
ICC_1ST 0 (Internal)
ICC_2ND 1 (External)
…
ICC_9TH 8 (External)
IccDetect: Input parameter
S pecifies the detect polar ity of the car d present. S pecify TRUE t o det ect a card
present when the DET_CARDx pin is HI GH. Specify FALS E t o detect a car d with
the DET_CA RDx pin is LOW. Th i s paramet er is only valid for the inter nal IC C
interface.
IccHz: I nput paramet er
Specifies the smart card frequency. Possibl e values are:
ICC_3600KHZ (0)
ICC_1800KHZ (1)
ICC_7200KHZ (2)
The LAPI supports these three rates to fol l ow t he same desi gn as the older device
family (73S11xx). The 73S12xxF hardware supports a wider range of smart card
cl ock generati ons, which can be derived using a dividing factor (F) such that:
SC clock = 96 MHz / (F + 1) / 2 where F can be any value used to generate the
desired clock. In the thr ee case s above, the F values were defined as: 12, 24 and 6
respectively. See the data sheet for more informati on.
FiDi: Input paramet er
Specifies the current F i/Di values, equivalent in format to the P PS1 byte of a PPS
request.
IccProtocolT1: Input paramet er
Specifies the current prot ocol, T=1 (TRUE) or T=0 (FALS E). U sed t o set appropriate
guard and wait tim es.
IccEDCEnabled: Input parameter
S pecifies if the E DC byte( s) ar e to be updated on t he fly.
IccEDCTypeCRC: Input paramet er
Specifies if the EDC value is t o be calculated with the C RC alg orithm (TRUE) or wit h
the LRC algorithm (FALSE).
IccParityCheck: Input par ameter
S pecifies if the pari ty bi t is to be checked (TRUE) or not (F ALSE).
IccBreakGeneration: Input paramet er
S pecifies whether the UAR T must generate a break on a parity error (TRUE) or not
(FALSE).
IccBreakStartPosition: Input paramet er
Specifies where the break signal should start. Possible va l ue s a r e 0x00 thr o ugh 0x07 (i n
0.125 ETU increments), which are a s sociate d with bi t po si ti ons 10 thr ough 10.875 ETUs.
For e xampl e , 1 c o r r e s po nds to 10. 125 ETUs. The defaul t va lue is 0x04 (10.5 ETUs).
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 33
IccBreakDuration: Input paramet er
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 ret r i es to al low on r eception of a bad byte. Ret r ies = total tri es – 1.
IccBreakDetect: Input paramet er
S pecifies whether to acknowledge (TRUE) or i gnore ( FALSE) a break co ming from
t he Smart Car d.
IccTxRetry: I nput paramet er
The number of retri es to al low on tr ansmi ssion of a bad byte. Retries = total tri es – 1.
IccExtraGuardTime: Input paramet er
S pecifies the mi nimum del ay in ETUs between the leadi ng edges of two consecuti ve
characters se nt to t he Smart Car d.
IccBlockGuardTime: Input parameter
Specifies th e minimum delay in ETUs between the leading edges of two consecuti ve
characters se nt in opposite directi ons.
IccCharWaitingTime: I nput parameter
S pecifies the maximum delay in ETUs between the leading edges of two consecuti ve
characters from t he smart car d (T=1 protocol ).
IccBlockWaitingTime: Input paramet er
S pecifies the maximum delay in ETUs bet ween the leadi ng edges of two consecutive
characters se nt in opposite directi ons. Possible values are in the range 0x01
through 0x078000.
IccWorkWaitingTime: I nput parameter
S pecifies the maximum delay in ETUs bet ween the leadi ng edges of two consecutive
characters from t he Smart Car d or of one sent to the Smart C ar d and the next one
received from it ( T=0 pr otocol ) .
IccPUEnabled: Input par ameter
Enables (TRUE) or d i sables (FALSE) the Smart Card pull-up current source on the
Card Detect pin.
IccPDEnabled: Input paramet er
Enables (TRUE) or d isa bles (F ALSE) the Smar t Card pul l-down current sour ce on
t he Card Detect pin.
IccVDDFaultOff: I nput parameter
When enabled (1), allows the 73S12xxF to aut omati cally p er form a deacti vation
sequence when there i s a VD D Fault. W hen disabled (0), allows the 73S12xxF to
si gnal the co mpanion circui t to set i ts VCC= 0 when there i s a VD D F ault.
IccAddr: Input par ameter
The following settings are defined in API_STRUCT_12.h
ICC_INTERNAL – U se this value for slot #1 (Inter nal slot)
ICC_I2C_0 = 0x40, – Any of these values can be used for I2C, slot # > ICC_1ST
ICC_I2C_1 = 0x42,
ICC_I2C_2 = 0x44,
ICC_I2C_3 = 0x46,
ICC_I2C_4 = 0x48,
ICC_I2C_5 = 0x4A,
ICC_I2C_6 = 0x4C,
ICC_I2C_7 = 0x4E
IccExtRst: Input parameter
E xternal R eset signal. The following settings are defined in API_STRUCT_12.h:
ICC_NRS T = 0x00 , – U se this value for slot #1 (Internal slot)
ICC_RST0 = 0x80,
ICC_RST1 = 0x90,
ICC_RST2 = 0xA0,
73S12xxF Software User Guide UG_12xxF_016
34 R ev. 1.50
ICC_RST3 = 0xB0,
ICC_RS T4 = 0xC0,
ICC_RS T5 = 0xD0,
ICC_RST6 = 0xE0,
ICC_RS T7 = 0xF0
IccCE: Input parameter
Card Even t parameter. Th e fol l owing sett i ngs are avail able as defined in
API_STRUCT_12.h. Set this variabl e according to the hardware design where ei ther
interrupt 2 or interrupt 3 is used for an exter nal card event det ect.
ICC_INT2_NONE = 0x00,
ICC_INT2_I2C = 0x0 1, // U se IN T2 for card event det ecti on
ICC_INT3_I2C = 0x02, //Use INT3 for card event detection
Retur n Codes None.
The T=0 and T=1 protocols affect which guard and wait times to use. For protocols other than t hese , use
whichever protocol ( either T=0 or T=1) best matches the timing requirements. I f nei ther protoco l
matches, then the appl i cati on will need to bypass t he Smart C ar d UAR T.
ICC_Activate()
Purpose Activate the co nt acts of t he se l ected S mart Card, as specified by eIccId. The VCC,
RST, I/O and CLK signals are configured according to the ISO 7816-3 standard.
Synopsis ICC_RC ICC_Activate ( IN struct ICC_Activate_ t *p Activate, IN stru ct ICC_t *pATR
);
Struct {
enum ICC_VOLTAGE IccVCC;
Unsi gned char IccVCCO ffDelay; / / # of etus delay b efore VCC should go off.
Unsigned char IccVCCTmr; / / # of et us to wait for VC C stable.
unsigned char IccRese tDelay,
int I ccInitialWaitingTime,
B oolean IccATR_ TimeoutEnabled,
int I ccATR_Timeout,
int IccTS_Timeout
} ICC_Activate_ t;
Where ICC_VOLTAGE is defined as:
VCC_0V = 0,
VCC_1V8 = 1 ,
VCC_3V = 2,
VCC_5V = 3
Parameters IccVcc: Input parameter
Voltage to apply when powering up this card.
IccVCCOffDelay: Input paramet er
Number of ETUs to delay b efore shutting off t he VCC . The default should be set to
3 ETUs. The maximum value is 15.
IccVCCTmr: Input parameter
Number of ETUs to wait for VCC to become stable. This time is ca l culated as:
timer * 30.5 µs using a 32768 Hz clock. A value of 0 will result in no ti meout ( as
opposed to zer o ti me). The maximum value is 15.
IccResetDelay: Input parameter
Specifies the number of ETUs to ke ep RESET asse r ted after power h as stabi lized.
IccInitialWaitingTime: I nput parameter
S pecifies the maximum delay in ETUs bet ween the leadi ng edges of two
consecutive characters of the ATR response.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 35
IccATR_TimeoutEnabled: Input parameter
Specifies if the ATR timeout is enabl ed (TRUE) or disabled (FALSE).
IccATR_Timeout: Input paramet er
S pecifies the maximum delay in ETUs bet ween the leadi ng edge of the first char acter
and l ast char acter of the ATR response , if enabled.
IccTS_Timeout: Input paramet er
S pecifies the maximum delay in ETUs bet ween the de-asse r tion of the RST signal
and the leading edge of the TS byt e of the A TR.
pIccATR: Input paramet er .
P ointer to th e ICC_Rx_ t structure.
Retur n Codes
ICC_OK
The SmartCard is present and active.
ICC_ACTIVATION_INCOMPLETE
The SmartCard is present, but i ts reset i s sti l l asser ted.
ICC_ERR_OVERCURRENT or ICC_ERR_V CC_UNSTABLE
An attempt to acti vate the Smar tC ar d ca used an over current condition and it
has been deacti vated.
ICC_ERR_REMOVED
The SmartCard is not pr esent.
ICC_ERR_TIMEOUT
O ne of the maximum delays was exceeded forcing a t imeout. Take appropr iate
action.
ICC_ERR_BREAK
Data was always rece ived with parity error, necessitati ng br eak signal i ng of the
Smart Card (T=0 prot ocol).
ICC_ERR_PARITY
A byt e was r eceived with an invali d pari ty.
ICC_RX_PENDING
Rece ption has started, but i s not yet compl eted. This code is returned on ei ther
a successful co mpl etion or a ter mi nat i on due t o er r or .
ICC_RX_OVERRUN
An Rx overrun condition has occurred, resulting in the loss of at l east one byte.
I f the Smar t Card was powered-down on entry, this function will perform a cold-reset.
I f the Smar t Card was powered-up on entry, this function will perform a warm-reset.
This function will return after r eception of the TS byte or an error conditi on.
The ICC_t structure should be set up to expect the l ar gest possibl e ATR response. Call ICC_RxLen() to
determine the cur r ent tot al number of bytes r ecei ved. Call ICC_RxDone() to complete A TR recept ion.
(Refer t o ICC_Tx() or ICC_Rx() for the ICC_t structure definition)
ICC_Status()
Purpose R etr i eve the prese nce and active status of all the Smar t Cards.
Synopsis void I CC_S ta tus ( OUT int *pnIccPresent, OUT int *pnIccActive );
Parameters pnIccPresent: Output parameter
S pecifies which SmartC ar ds ar e prese nt , Bit[n] corresponding to ICC[n], Bit[1] being
mapped to the least significant bit.
PnIccActive: Output p arameter
S pecifies which SmartC ar ds ar e acti ve, Bit[n] corr esponding t o ICC[n].
Retur n Codes None.
73S12xxF Software User Guide UG_12xxF_016
36 R ev. 1.50
ICC_Tx()
Purpose Send dat a to the se l ected Smart Car d. Before call ing t his function, the Smart Card
UAR T must have b een initialized and the selected Smart C ar d activat ed.
Synopsis ICC_RC I CC_Tx ( INOUT struct ICC_t *pICC );
struct {
I N char *IccData,
INOUT unsigned int IccLen,
I N Boolean I ccLastByte,
INO UT int IccEDC,
OUT ICC_RC ICC_S tatus,
O U T Boolean I ccDone
} ICC_t;
Parameters IccData: Input paramet er
Contains the data to be tr ansmi tted.
IccLen: Input / output param eter
On input, specifies the num ber of bytes to send. On output, specifies the num ber of
bytes successful l y se nt without er r or s, vali d after IccDone is true.
IccLastByte: I nput parameter
Specifies if the last transmitted byte is included in this buffer.
IccEDC: Input / output parameter
Cont ain s the cu rrent LRC or CRC valu e (T=1).
ICC_Status: Output
Contains the current status of this transmission.
IccDone: Output
S et on co mpletion of t r ansmission, possibly with er r or s. C heck ICC_Status for
status.
Retur n Codes
ICC_ERR_PRESENT_INACTIVE
The SmartCard is present but i nactive.
ICC_ERR_NO_CARD
The Smart Card is not pr esent.
ICC_TX_PENDING
Transmission has started, but is not yet co mpleted. O n either a successful
completion or a termi nat ion due t o er r or , the I CC_Status will change t o one of
t he following:
ICC_OK
S uccessful operati on: All of the dat a was successfull y t r ansmi tted to the
S martCard without par ity error.
ICC_BREAK
S uccessful operati on. All of the dat a was successfull y sent to t he SmartCar d
with at most a few retries. I niti ally, br eak signaling was det ected, which
necessitated at least one retransmission. (O nly in T=0 protocol)
ICC_ERR_BREAK
All attempts at sending the next byte resulted in break signaling, indicating a
perceived parity error at the SmartC ard end. (Only in T=0 protocol) The
S martCard has been aut omati cally d eacti vat ed. Check ICCTxLen t o determine
how m any bytes were successful l y transmitted.
IccLastByte should be set when it is time to switch to reception mode and star t the BGT an d BWT timers
and possibly send the EDC.
The ICC_OK status wil l not occ ur until after the CRC/LRC has been sent to the SmartC ar d.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 37
ICC_Rx()
Purpose R ecei ve data from the Smar tC ar d int er face. Before calling this function, the
S martCard UART m ust have b een initi al ize d and the se l ected SmartCar d activated.
Synopsis ICC_RC I CC_Rx ( INOUT struct ICC_t *pICC );
struct {
O U T char *IccData,
INOUT unsigned int IccLen,
I N Boolean I ccLastByte,
INOUT Int IccEDC,
OUT ICC_RC ICC_S tatus,
O U T Boolean I ccDone
} ICC_t;
Parameters IccData: Outp ut p arameter
Contains the data curr ent ly recei ved from the Smar tC ar d.
IccLen: Input / output parameter
On input this is the number of requested bytes. On output this is the number of
successfull y received bytes, valid after bIccDone i s tr ue.
IccLastByte: Input parameter
S pecifies if the last byt e has been recei ved after get ting t hese IccLen bytes.
IccEDC: Input / output parameter
Contains th e current LRC or CRC valu e (T=1).
Icc_Status: Output
Contains the current status of t his reception.
IccDone: Output
S et on co mpletion of rece pt i on, possibly with er r or s. Check Icc_Status for status.
Retur n Codes
ICC_ERR_PRESENT_INACTIVE
The SmartCard is present, but i nactive.
ICC_ERR_NO_CARD
The SmartCard is not pr esent.
ICC_RX_PENDING
Rece ption has started, but i s not yet compl eted. On ei ther a successful
completion or a termi nat ion due to err or , the ICC _Status will change t o one of
t he following:
ICC_OK
S uccessful operati on, IccLen bytes have been received from the SmartCard.
ICC_BREAK
S uccessful operati on, IccLen bytes have been r ecei ved from the SmartCard, but
some bytes were initi al ly recei ved with parity error , nece ssitating some br eak
signaling of the SmartCard, forcing it to retransmit at l east once ( T=0) .
ICC_ERR_BREAK
Data was always rece ived with parity error, necessitati ng br eak signaling of the
SmartCard (T=0). Th e SmartCard has been automati cal ly d eacti vat ed. Check
ICC_RxLen() to det er mine how many bytes were successfully recei ved.
ICC_ERR_TIMEOUT
A byte was not r ecei ved before the maximum d elay specified by
nIccWorkWaitingTime (T=0) or nIccCharWaitingTim e (T=1) expired .
ICC_ERR_PARITY
A byte was recei ved wit h an i nvalid parity.
ICC_ERR_OVERRUN
A n RX overrun conditi on has occurred, resulting in the loss of at l east one byte.
73S12xxF Software User Guide UG_12xxF_016
38 R ev. 1.50
IccLastByte should be set when it is time to switch to transmi ssion mode and start th e BGT timer. If it is not
immediatel y k nown when it is tim e t o switch , call ICC_RxDone() aft er al l the bytes have been r eceived.
To deter mine if all the expected bytes have b een rece i ved, cal l ICC_RxLen(). Si nce the ICC _OK or
I C C_BREAK status occurs after r ecept i on of ICCLen bytes, this value should include any CRC/LRC
byte( s) r ecei ved.
ICC_RxLen()
Purpose Return the number of byt es recei ved thus far.
Synopsis unsigned I nt ICC_ RxLe n ( void );
Parameters None.
Retur n Codes None.
ICC_RxDone()
Purpose Notify the SmartCar d UART that all the expected bytes have been rece ived . This
forces the switch t o activati on of block guard and wait ti mes.
Synopsis Void I CC_RxDon e ( void );
Parameters None.
Retur n Codes None.
ICC_Deactivate()
Purpose D eacti vate the contacts of the sel ected Smar tCard inter face as specified by IccId.
The Vcc, RST, I/O and Clk signals ar e confi gured according to the ISO 7816-3
standard. This function uses the IccVCCOffDelay, as described in ICC_Activate()
before turning VCC off.
Synopsis void ICC_Deactivate ( void );
Parameters None.
Return Codes None.
ICC_Mode()
Purpose Enabl e or Disable PC ( via D IREC T mode) or Applicati on (via Byp ass mode) to
direct ly cont rol ICC I/ O line.
Synopsis ICC_RC I CC_Mode (
IN en um ICC_I D Iccid,
I N Boolean bEnable,
IN Boolean bP C_DI RECT )
Parameters IccId : Input paramet er
S pecifies which SmartC ar d to all ow dir ect access to I/O . Possible values ar e:
ICC_1ST 0 , (Internal)
ICC_2ND 1, (External)
…
ICC_9TH 8 (External).
bEnable: Input par ameter
I f TRUE, it enables the sel ected mode.
bPC_DIRECT: Input parameter
Enables or disables PC_DIRECT mode (if TRUE) or BYPASS m ode (if FAL SE).
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 39
Retur n Codes
ICC_OK The Smar tCard is present and active.
ICC_ERR_PRESENT_INACTIVE The SmartCard is pr esent but i nactive.
ICC_ERR_NO_CARD The SmartC ar d is not present.
This API is par t of the support for Synchronous cards.
ICC_Clk_Restart()
Purpose Restart s an I CC’s clock.
Synopsis ICC_Clk_Restart ( IN int nIccDelayIO );
Parameters nIccDelayIO: I nput parameter
Delay in clock cy cles after r estar t of the cl ock before allowing I /O.
Retur n Codes
ICC_OK Successful operation. IccLen bytes have been received from the SmartCard.
ICC_ERR_PRESENT_INACTIVE The SmartCard is pr esent but i nactive.
ICC_ERR_REMOVED The SmartCard is r emoved.
The har dware TIMER1 is used by this routine, making it unavailable to the application. This
approach helps support lower power consumption.
ICC_Clk_Stop()
Purpose S t ops an ICC’s clock.
Synopsis ICC_RC I CC_Cl k_Stop ( IN Boolean bIccClkStop, IN int nI ccDelaySt op );
Parameters bIccClkStop: Input par ameter
Specifies whether to stop the IccClk when HIGH (TRUE) or when LOW (FALSE).
nIccDelayStop: Input parameter
Delay in clock cycles b efore stoppin g clock.
Retur n Codes ICC_OK Successful oper ati on.
ICC_ERR_PRESENT The SmartCard is present but i nactive.
ICC_ERR_REMOVED The SmartCard is r emoved
The hardware TIMER1 is used by this routine, making it unavailable to the application. This
approach helps support lower power consumption.
4.2.6 S ERIAL (RS232) Driver API – Available with all 73S12xxF Devices
The Seri al D river API manages the RS232 inter face (Ser ial C hannel 0) . It may be used to communi cate
through the UART with any host that supports an RS232 interface. The API includes:
• Serial_Init() (page 40)
• Serial_Tx() (page 40)
• Serial_CTx() (page 41)
• Serial_TxLen() (page 41)
• S er ial_TxByte () (page 41 )
• Serial_Rx() (page 41)
• Serial_CRx() (page 42)
• Serial_RxLen() (page 42)
• S er ial_RxByte ( ) (page 42)
73S12xxF Software User Guide UG_12xxF_016
40 R ev. 1.50
After calling Serial_Init() and prior to r eceiving data from the RS232 interface, Serial_Rx() and Serial_Tx()
must be ca l led to pass on t he rece ive/tr ansmi t buffer poi nt er , which is u sed to stor e R x and Tx char acters,
respectively. For a sa mpl e of the Serial AP I usa ge, see the Pseudo-CCID applica tion sour ce code.
Serial_Init()
Purpose C onfigure the communi cati on speed, flow cont r ol, character parity and number of
stop b its. The seri al int er r upt service rout ine i s N OT maskabl e, the i nt er r upt vector is
set inter nall y, so using Set_Event ( eSerial, ...) will not have an y effect. The baud
rates listed below are available for specific CPU clock speeds only. Review the
API_Struct_12.h for more information.
Synopsis Bbool Serial_Init (
IN enum SERIAL_SPD speed,
I N Boolean pari ty_en,
I N Boolean parity,
I N Boolean t wo_ stop_bi ts,
I N Boolean xon_xoff )
Parameters Speed: Input par ameter
Thi s selects the communi cati on speed. Possible values ar e:
_RATE_600, 0
_RATE_1200, 1
_RATE_2400, 2
_RATE_4800, 3
_RATE_9600, 4
_RATE_14400, 5
_RATE_19200, 6
_RATE_28800, 7
_RATE_38400, 8
_RATE_57600, 9
_RATE_115200, 10
_RATE_125000, 11
_RATE_250000, 12
_RATE_375000 13
Parity_enb: Input parameter
S pecifies if the exchanged char acters contai n a parity b it (TRUE) or not ( FALSE).
parity: Input parameter
S pecifies if the characters par i ty bi ts must be odd (TRU E) or even (F ALSE) .
Two_stop_bits: Input paramet er
S pecifies if the exchanged char acters contai n two stop bits (TRUE) or one (FALSE) .
xon_xoff: Input par ameter
S pecifies if Xon_Xoff contr ol is on (TRUE) or off (FALSE).
Retur n Codes None.
The lower speeds help support Plug & Play.
Serial_Tx()
Purpose Setup the Tx buffer before sending data to the PC UART. An application should call
this API immediat ely after calling Serial_Init().
Synopsis enum SERIAL_RC data *Serial_Tx ( U08x xdata *buffer, U16 len )
Parameters buffer: I nput parameter
Specifies a pointer to the data buffer co ntaining data to send to the PC UART.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 41
Len: I nput parameter.
Specifies the current number of bytes to be sent.
Retur n Codes S_EMPTY Successful transmission.
S_PE NDING , 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 ca ll to setup the Tx buffer.
Synopsis Unsigned Integer Serial_CTx ( U08x xdata *buffer, U16 len )
Parameters buffer: I nput parameter
Specifies a pointer to the data buffer containing the data to se nd to the P C UART.
len: Input parameter.
Specifies the current number of bytes to be sent.
Return Value Unsigned integer specifying the number of bytes sent thus far.
A fter calling this API, an appl i cati on ca n make sure all bytes were transmitted by checking that
Serial_TxLen() returns a 0.
Serial_TxLen()
Purpose Number of bytes transmitted thus far.
Synopsis Unsigne d i nte ger S er i al _ TxLen ( void )
Parameters none.
Return Value Unsigned integer specifying the num ber of bytes left in the Tx buffer, i.e. the
remaining bytes to be sent .
Serial_TxByte ()
Purpose Send a quick byte out.
Synopsis void Serial_TxByte ( U08 cbyte )
Parameters cbyte: Input paramet er
Byte to put at t he end of the Tx buffer to be sent out quickly.
Retur n Codes none.
This function performs si milarly t o Serial_CTx() ( U08 &cbyte, 1) but it has much less overhead. Use this
A PI when performance optimizati on is requir ed yet only one byt e can be se nt at a time.
Serial_Rx()
Purpose Set up recei ve buffer and start receiving. Al ways call this functi on aft er Serial_Init() to
make sure the receive b uffer is avail able.
Synopsis enum SERIAL_RC data *Serial_Rx ( U08x xdata *buffer, U16 len )
Parameters buffer: I nput parameter
Specifies a poi nt er to the dat a buffer to store the data recei ved from the PC UART.
73S12xxF Software User Guide UG_12xxF_016
42 R ev. 1.50
len: Input parameter.
Specifies the maximum number of bytes to r ecei ve at any on e ti me.
Retur n Codes On a successful completion or ter mi nat ion, the ser ial St atus will r eturn one of t he following:
S_EMPTY Reception has star ted but the receive buffer is still em pty.
S_PENDING Recepti on has started, but i s not yet co mpleted.
S_FULL R eception has star ted and the buffer is now full.
S_PARITY_ERR Parity error occurred on the received byte(s).
S_OVERRUN Buffer overrun, which may result in a loss of at l east 1 byte.
Serial_CRx()
Purpose Get addi tional bytes from t he receiving buffer.
Synopsis Unsigned Integer Serial_CRx ( U08x xdata *buffer, U16 len )
Parameters buffer: I nput parameter
Specifies a poi nt er to the dat a buffer to store the data recei ved from the PC UART.
len: Input paramet er .
Specifies the maximum number of bytes to r ecei ve at any on e ti me.
Return Value U pon co mpletion, returns t he number of bytes r ecei ved thus far.
Serial_RxLen()
Purpose N umber of byt es recei ved thus far.
Synopsis Unsigned Inte ger S er i al _ RxLen ( void )
Parameters None.
Return Value Unsigned integer specifying the number of bytes recei ved thus far.
Serial_RxByte ()
Purpose Get a quick byte out of the input buffer.
Synopsis Unsigned Char Seri al_RxByte ( void )
Parameters None.
Return Value Byte received from t he ser ial inter face .
This function performs similarly as Serial_CRx ( U08 &cbyte, 1 ) but has much less overhead. Use this
A PI when performance optimizati on is requir ed yet only one byt e can be read at a t i me.
4.2.7 USB AP I – Available with 64K Flash ver sion of the 73S12xxF
Thi s API manages the USB inter face which is compatibl e with the USB Specifi cations 2.0 – Full
Speed/12Mbps. The U SB pr otocol Suspend, Resume and Rese t operati ons ar e m anaged by this API.
The API includes:
• USB_Init() (page 43)
• USB_Status() (page 48)
• USB_Stall() (page 49)
• USB_UnStall() (page 49)
• USB_IN_1() (page 49)
• USB_IN_2() (page 50)
• USB_OUT_1() (page 50)
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 43
The U SB inter face cont ai ns four endpoints, which are defined as follows:
1. Endpoint 0 for the control transfer
2. Endpoint 1 IN for the Bulk transfer
3. Endpoint 1 OUT for the Bulk transfer
4. Endpoint 2 IN for the interrupt transfer
The Low-level API handles all Endpoint 0 (control endpoint) com m unications; thus PC driver enumeration
takes place during the device reset time and is transparent to an applicati on. An appli cati on can be
written to m onitor this reset signal to determine when it can start sending Endpoint 1 IN and/or Endpoint
2 IN packets to the host or to expect Endpoint 1 OUT packets from the host. ( References to
t r ansmi ssion dir ecti on (IN/OUT) are relative to the host.)
USB_Init()
Purpose Configure the USB interface during the reset procedure. The descriptors (device,
configuration, endpoint, interface and string) used in future enum eration requests are
configured. When leaving thi s functi on, the U SB interface i s r eady to answer any
enumerati on request.
Synopsis Voi d US B_Ini t (
IN struct USB_Init_t *pUSB,
IN struct USB_LangID_t *pLangID,
IN void (*p RESET) (),
IN void (*p SUSP END) (),
IN void (*pRESUME) () );
struct USB_Init_t
{
struct USB _Device_t Device;
struct USB_Config_t Config;
struct USB _CCID_ t CCID;
struct USB_Strings_t Strings;
};
The Device, Con fig , CCI D, S trin gs and Lan gID structures are described at the end of
this function description.
Parameters pUSB: Input paramet er
Specifies the Device, Configuration, Endpoints, Interfaces and String Descriptors
defining the USB interface.
pLangID: Input parameter
Specifies the Language ID codes Str ing Descript or .
pRESET: I nput parameter
Specifies a poi nt er to the function to call when RESET signaling has occurred on the
USB bus.
pSUSPEND: Input parameter
Specifies a poi nt er to the function to call when SUSPEND signaling has occurred on
the USB bus.
pRESUME: Input paramet er
Specifies a poi nt er to the function to call when RESUME signaling has occurred on
the USB bus.
Retur n Codes None.
This function will activate the USB interface and ALL Endpoints will be ACTIVE. Endpoint 0 gets device
descriptor requests and will return the device descriptor. Endpoint 0 gets configuration descriptor
73S12xxF Software User Guide UG_12xxF_016
44 R ev. 1.50
requests and will return the configuration, endpoint, interface and string descriptors including the CCID
class descriptor, depending on the maximum length requested.
There ar e two possibl e configur ations for the US B: self-powered and bus-powered. Each confi guration
requires some power consum pt ion management to effectively reduce the power according t o the USB 2.0
Specification. As a result, the foll owing must be implemented for each configur ation:
• For Self-P ower: Cable attach/detach must be det ectable to tur n D+ on/off resp ect ively. The CCID
USB sampl e code included as part of the release has impl ement ed t he use of USR 7 with external
interrupt 0 (al l inter nal to IC ) so that a cable attach/detach event will be detected and se r viced via the
INT0 interrupt service routine.
• For Bus-P ower: D+ must be kept high at all times via the PowerON(ENABLE_USB) API. When the
host puts the device in Suspend mode, the CC ID USB sa mple co de puts the device ’ s C PU to sleep
t o conser ve power. After Suspend mode, the host wakes up the device via a R eset or a Resume
signal.
This s ignal ( D+ being pul l e d l ow for a pe r i o d of ti me as de s c r ibed in the USB 2.0 Specification) will cause
int e r r upt 0 t o o c cur whic h w ill w a ke up the device ’s CPU. T he i nte r r upt i s r e qui r e d because the U SB clo ck is
tur ne d o ff dur ing s l e e p mo de, so t he D + ( R e set/R e s ume ) si gnal wo ul d no t wa ke up the C PU . U po n wa ki ng
up, the INT0 interrupt service routine will turn the U SB clock back o n to re sume its f unction.
I n order to configur e the self-powered or bus-powered mode, modify the ATTR IBUTE S vari able, defi ned
in API_12.h, to its respective value before building the application. See the CCID USB s ource code
proj ect for an example.
The U SB ini tializa tion descriptor s and relevant structures are described bel ow. All the descriptors are
modifiable, but some values should not change. These ar e flagged as “ Always”.
//
// USB API.
//
/*** the total size of the confi guration descriptor ***/
#define CONFIG_DESC_TOTAL_SIZE 93
/*** define the number of core endpoints (including EP0) ***/
#define NUMBER_OF_EPS 4
/ *** defi ne t he total possibl e number of interface s for al l confi gurations *** /
#define NUMBER_OF_INTERFACES 1
/*******************************************************
Descript or types
*******************************************************/
#define DEVI CE_DE SCRI PTOR 1
#define CONFIG URATION_DE SCRI PTOR 2
#define STRING_DES CRIP TOR 3
#define INTERFA CE_DE SCRI PTOR 4
#define EP_DE SCRI PTOR 5
#define CCID_DE SCRIP TOR 0x21
struct USB _Device_t
{
unsigned char Length; // Always 18.
unsigned char DescriptorType; // A lways DEVI CE_DE SCRI PTOR = 1.
unsigned int USB_spec_rev; // 0x0002 (rev 2.0).
unsigned char DeviceClass; // A lways 0.
unsigned char DeviceSubclass; // Always 0.
unsigned char DeviceProtocol; // A lways 0.
unsigned char MaxPacketSize0; // Always 16.
unsigned int idVendor; //Always 0xc309
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 45
unsigned int idProduct; // Always 0x0500
unsigned int Device; // 0x4600;
unsigned char iManufacturer; // 0, TBD;
unsigned char iProduct; // 0, TBD;
unsigned char iSerialNum; // 0, TBD;
unsigned char NumConfigs; // 1, TBD;
};
struct USB_Interface_t
{
unsigned char Length; // Always 9.
unsigned char DescriptorType; // Always INTERFACE_DESCRIPTOR = 4.
unsigned char InterfaceNumber; // 0.
unsigned char AlternateSetting; // 0 .
unsigned char NumEndPoints; // Always NUMBER_OF_EPS - 1 = 3;
unsigned char InterfaceClass; // 0x0 B.
unsigned char InterfaceSubClass; // 0.
unsigned char InterfaceProtocol; // 0 .
unsigned char iInterface; // 0.
};
#define CLASS 0x0B / /Always 0B for Smart C ar d Reader
#define SUBCLASS 0
struct USB_EP_t
{
unsigned char Length; // Always 7.
unsigned char DescriptorType; // Always EP_DESCRIPTOR = 5.
unsigned char EndpointAddress; // (IN or OUT) plus (1 or 2).
unsigned char Attributes; // BULK or INTERRUP T.
unsigned int MaxPacketSize; // 16, 32 or 64.
unsigned char Interval; // 0 for BUL K. 10 for INTERRUP T.
};
#define IN 0x80
#define OUT 0x00
#define BULK 0x02
#define INTERRUPT 0x03
#define INTERVAL 10 // Interrupt EndPoint interval in fram es (about 10 msec).
struct USB_Config_t
{
unsigned char Length; // Alway s 9.
unsigned char DescriptorType; // A lways CONFIGURATION_DES CRIP TOR = 2.
unsigned char TotalLengthL; // CONFIG_DESC_TOTAL_SIZE = 93
// (One Interface, three Endpoints).
unsigned char TotalLengthH; // Always 0.
unsigned char NumInterfaces; // NUMBE R_OF_I NTERFA CES = 1 .
unsigned char ConfigurationValue; // Always 1.
unsigned char iConfiguration; // Application specific.
unsigned char Attributes; // App lication specific.
unsigned char MaxPower; // App lication specific.
struct USB_Interface_t I;
};
#define ATTRIBUTES BIT7 | SELF_POWERED // ap plication specific, self-powered
73S12xxF Software User Guide UG_12xxF_016
46 R ev. 1.50
#define SELF_POWERED BIT6
#define REMOTE_WAKEUP BIT5
#define MAXPOWER 50 // 100 mA, if bus-powered.
#define NUMBER_ LANG IDS 1 / / Change as needed.
#ifdef DFU
#define NUMBER_ STRINGS 4 // Change as needed.
#else
#define NUMBER_ STRINGS 3
struct USB_LangID_t
{
Uc Length; // (NUMBE R_LANG IDS * 2) + 2.
Uc DescriptorType; // Always STRING_DES CRIP TOR = 3.
Ui Lang ID [ NUMBE R_LANG IDS ]; // Array of L angID codes.
};
#define MAX_STRING_LEN 80 // Change and duplicate as needed.
struct USB_String_t
{
Uc Length; // Real STRING_LEN + 2 .
Uc DescriptorType; // Always STRING_DES CRIP TOR = 3.
Uc String[ MAX_STRING_LEN ]; // UNICO DE encoded string.
};
//Pointers to strings of a language are grouped together.
struct USB_Strings_t
{
U08 Number_Of_Strings; // Number of String descriptors per language.
/ / Array of p oi nters to U N ICODE enco ded STRIN G descriptor s.
struct USB_String_t code *Strings[ NUMBER_STRINGS * NUMBE R_LA NGI DS ] ;
};
/ / Define for any selecti on parameter below.
#define NONE 0x00000000L
/ / Defines for Voltage Support.
#define VOLTS5_0 0x01
#define VOLTS3_0 0x02
#define VOLTS1_8 0x04
/ / Defines for Pr otocol s supported.
#define PROTOCOL_T_0 0x00000001L
#define PROTOCOL_T_1 0x00000002L
/ / Defines for C l ock rates.
#define KHZ3600 3600L
#define KHZ4000 4000L
#define KHZ5050 5050L
#define KHZ6000 6000L
#define KHZ8000 8000L
#define KHZ9600 9600L
#define KHZ12000 12000L
/ / Defines for I CC bps.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 47
#define BPS9600 9600L // 0x00002580 (9600 +- 1%)
#define BPS14400 14400L
#define BPS19200 19200L
#define BPS28800 28800L
#define BPS38400 38400L
#define BPS57600 57600L
#define BPS57688 57688L
#define BPS115200 115200L // 0x0001C200 (115200 +- 1%)
#define BPS116129 116129L // 0x0001C200
#define BPS225000 225000L
#define BPS230400 230400L
/ / Defines for Mechani cal .
#define ACCEP T 0x00000001L
#define EJECT 0x00000002L
#define CAPTURE 0x00000004L
#define LOCK 0x00000008L
/ / Defines for F eatures.
#define ATR_CO NFIG URATION 0x00000002L
#define INSERT_ACTIVATION 0x00000004L
#define VOLTAGE_SELECTION 0x00000008L
#define CLOCK _FREQ_ CHANG E 0x00000010L
#define BIT_RATE_ CHANG E 0x00000020L
#define A UTO_NEGOTIATION 0x00000040L
#define AUTO_PPS 0x00000080L
#define CLOCK_STOP 0x00000100L
#define NAD_NO T_NULL 0x00000200L
#define AUTO_IFSD 0x00000400L
#define TPDU 0x00010000L
#define SHORT_APDU 0x00020000L
#define EXTENDED_APDU 0x00040000L
/ / Defines for LcdLayout
#define NO_LCD 0x0000
#define LCD_ROWS 0xFF00
#define LCD_COLS 0x00FF
// Defines for PinSupport.
#define NO_PIN 0x00
#define VERIFY 0x01
#define MODIFY 0x02
struct USB _CCID_ t
{
unsigned char Length; // Always 54 (0x36).
unsigned char DescriptorType; / / A lways CCID_DE SCRI PTOR = 0x21
unsigned int CCID; // 0x0100 CCID version number.
unsigned char MaxSlotIndex; / / A pplicat ion specific.
unsigned char VoltageSupport; / / A pplicat ion specific.
unsigned long Protocols; // Application specific.
unsigned long DefaultClock; // 3600kHz (0x00000E10).
unsigned long MaximumClock; // 7200kHz (0x00001C20)
unsigned char NumClockSupported; // 3. (1800, 3600 and 7200 kHz).
unsigned long DataRate; // 9600 bps (0x00002580).
unsigned long MaxDataRate; // 115200 bps (0x0001C200).
73S12xxF Software User Guide UG_12xxF_016
48 R ev. 1.50
unsigned char NumDataRates; // 7.
unsigned long MaxIFSD; // Ap plicat ion specific.
unsigned long SynchProtocols; // 0x00000000.
unsigned long Mechanical; // App lication specific.
unsigned long Features; / / A pplicat ion specific.
unsigned long MaxCCIDMsgLen; // A pplicat ion specific.
unsigned char ClassGetResponse; / / A pplicat ion specific.
unsigned char ClassEnvelope; // Ap plicat ion specific.
unsigned int LcdLayout; // Application specific.
unsigned char PinSupport; // App lication specific.
unsigned char MaxCCIDBusySlots; // Ap plicat ion specific.
struct USB_EP_t EP[ NUMBER_OF_EPS-1 ];
#ifdef D FU
struct USB_Interface_t DFU_I; //One for DFU.
struct USB _DFUF unctional_ t DFUFunction al;
#endif
};
struct USB_t
{
U08x *UsbData;
U16 UsbLen;
enum USB_RC UsbStatus;
};
USB_Status()
Purpose Gets the status of the USB interface and its endpoints.
Synopsis Voi d US B_Sta tus (
OUT char *cUSB_ CONTROL_St atus,
OUT char *cUSB_ INTERRUPT_S tatus,
OUT char *cUSB_BULK_IN_Status
OUT char *cUSB_BULK_OUT_Status );
Parameters cUSB_CONTROL_Status: Outp ut parameter
Cur r ent state of the Contr ol EndPoint. Possible values are:
USB_ACTIVE 0
USB_SUSPENDED 1
USB_RESUMED 2
USB_STALLED 3
USB_RESET 4
USB_TX_PENDING 5
USB_RX_PENDING 6
cUSB_INTERRUPT_Status: Ou tp u t p arameter
Cur r ent state of the I N TERRUPT EndPoint.
cUSB_BULK_IN_Status: Ou tp u t p arameter
Current state of the BULK_IN EndPoint.
cUSB_BULK_OUT_Status: Output parameter
Current state of the BULK_OUT EndPoint.
Retur n Codes None.
US B_AC TIVE i ndi cates that e i ther the Int e r r upt a nd B ulk _IN EndPoints are ready for another USB transmission
( the pr e vio us o ne ha s fini shed ) o r tha t the Bul k _OU T EndPo int is r e ady for ano the r USB reception.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 49
USB_Stall()
Purpose St al ls porti ons of the USB inter face : The Endpoints to be stal led ar e confi gurable.
Synopsis Void USB_Stall ( IN char cUSBEndpointStall );
Parameters cUSBEndpointStall: Input paramet er
Specifies which endpoints are to be stalled by this function. The other endpoints
remain in their previous state. Th i s paramet er can be the result of an O R operati on
between the following values if several endpoints are to be di sabled:
ENDPOINT_0 0x01
ENDPOINT_1_IN 0x02
ENDPOINT_2_IN 0x04
ENDPOINT_1_OUT 0x08
Retur n Codes None.
Deactivat ed endpoint s will have a STALLE D stat us. If all endp oints are stalled, it will disconnect
t he USB inter face from t he Host.
USB_UnStall()
Purpose Unst al ls porti ons of the USB inter face : The Endpoints to be unstalled ar e confi gurable.
Synopsis Voi d US B_UnStall ( IN char cUSBEndpointUnStall );
Parameters cUSBEndpointUnStall: Input parameter
Specifies which endpoints are to be unstalled by this function. The other endpoints
remain in their previous state. Th i s paramet er can be the result of an O R operati on
between the following values if several endpoints are to be di sabled:
ENDPOINT_0 0x01
ENDPOINT_1_IN 0x02
ENDPOINT_2_IN 0x04
ENDPOINT_1_OUT 0x08
Retur n Codes None.
All unstalled endpoints will have status = IDLE.
USB_IN_1()
Purpose Send data to the Host through Endpoint 1 (BULK IN). When the buffer size is b igger
than the Maximum Packet Size (specified by the Descriptor string initialized in the
USB_Init() function), then the AP I will split the buffer int o smaller blocks and transmit
it in pieces.
Synopsis Void USB_IN_1 ( IN struct USB_t *pUSB );
struct
{
unsigned char *USBData,
unsigned int USBLen
USB_RC USBStatus
} USB_t;
Parameters USBData: Input par ameter
S pecifies the point er to the data to be t r ansmi tted to the Host.
USBLen: Input/Output paramet er
On input, specifi es the number of byt es to send to the H ost. On output, specifies the
current number of bytes sent to the Host.
73S12xxF Software User Guide UG_12xxF_016
50 R ev. 1.50
USBStatus: Output parameter
Contains the current status of t his transmi ssion, one of t he following:
USB_TX_PENDING: Tran smission has started, but i s not yet co mplete. On
either a successful compl etion or a ter mi nat ion due to err or , the USBStatus will
change to one of t he following:
USB_ACTIVE: Successful data t ransm ission.
USB_SUSPENDED: The HOST has suspended the U SB bus, r etr y later .
USB_STALLED: This Endpoint has been STALLED.
USB_RESET: The H OST has reset the USB bus, retr y later .
Retur n Codes None.
USB_IN_2()
Purpose Send data to the Host through Endpoin t 2 (INTERRUPT IN).
Synopsis Void USB_IN_2 ( IN struct USB_t *pUSB );
Parameters USBData: Input par ameter
S pecifies the point er to the data to be t r ansmi tted to the Host.
USBLen: Input/Outp ut p arameter
On input, specifi es the number of byt es to send to the H ost. On output, specifies the
curren t number of byt es se nt to the Host.
USBStatus: Out put par ameter
Contains the current status of t his transmi ssion, one of t he following:
USB_TX_PENDING: Tran smission has started, but i s not yet co mpleted. On
either a successful compl etion or a ter mi nat ion due to err or , the USBStatus will
change to one of t he following:
USB_ACTIVE: Successful data t ransm ission.
USB_SUSPENDED: The HOST has suspended the USB bus, retry later.
USB_STALLED: This Endpoint has been STALLED.
USB_RESET: The H OST has reset the USB bus, retr y later .
Retur n Codes None.
USB_OUT_1()
Purpose R ecei ve a buffer from the H ost through Endpoint 1 (BULK OUT). The data may be
rece i ved withi n several packets i f the buffer size is greater or equal to the Maximum
P acket Si ze, specified by the D escrip tor St ring init ialized in USB_Init().
Synopsis Void USB_OUT_2 ( IN stru ct USB_t *pUSB );
Parameters USBData: Outpu t p arameter
Contains the bytes recei ved from t he Host.
USBLen: Input/Outp ut p arameter
On input, specifies the maximum number of bytes to r ecei ve from the Host. On
output, specifies the current number of byt es recei ved from t he Host.
USBStatus: Output parameter
Contains the current status of t his reception, one of the following:
USB_RX_PENDING: Recepti on has started, but i s not yet co mpleted. On either
a successful compl eti on or a termi nat ion due to err or , the USBStatus will chan ge
t o one of the following:
USB_ACTIVE: Successf ul dat a r ecept i on.
USB_SUSPENDED: The HOST has suspended the USB bus, retr y later .
USB_STALLED: This Endpoint has been STALLED.
USB_RESET: The H OST has reset the USB bus, retr y later .
USB_ERR_OVERFLOW: Th e HOST h as sent too much data.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 51
Retur n Codes None.
4.2.8 Clock Generator Circuit API – Available w ith all 73S12xxF Devices
The Clock Gener ator API configu res the system clock speed.
CPU_Select()
Purpose Select the CPU speed. Thi s API should be ca lled after API_Init() is called if a
change in CPU speed is desired. The default speed is 3.69 MHz. C ar e should be
t aken when selecting speeds other than 3.69 MHz, as the speed will affect t he
number of supported Serial baud rates and timers API. The timer and Serial baud
rates will be adjusted inter nall y by the LAPI. A wait state will be inser ted to allow
USB I/O access time, i.e. CKCON will be set to the appropriate valu e to adjust wait
states.
Synopsis void CPU_Select ( en um CPU_ SPEED speed )
Parameters speed: I nput parameter
S pecifies which CPU speed t o r un. Possible values are
CPU_3Mhz69 0,
CPU_6Mhz 1,
CPU_12Mhz 2,
CPU_24Mhz 3
Retur n Codes None.
Some C PU speeds will li mi t the number of S er ial baud r ates supported. Table 4 lists the baud rates
supported by specific CPU clock rates.
Table 4: Clock Spe eds and Baud Rates Suppor ted
Baud Rate (bps)
CPU Cloc k Rate
3.69
MHz 6 MHz 12
MHz 24 MHz
600
X
1200 X X
2400 X X X
4800 X X X
9600 X X X
14400
X
X
X
X
19200 X X
28800 X X X
38400 X
57600 X X
115200
X
115385 X
187500 X
375000 X
750000 X
//Can only support these rates when the CPU is running at 3.69 MHz
//CPU_3Mhz69
{BPS_600_3MHz69, BPS_1200_3MHz69, BPS_2400_3MHz69, BPS_4800_3MHz69,
BPS_9600_3MHz69, BPS_14400_3MHz69, BPS_19200_3MHz69, BPS_28800_3MHz69,
73S12xxF Software User Guide UG_12xxF_016
52 R ev. 1.50
BPS_38400_3MHz69,BPS_57600_3MHz69, BPS_115200_3MHz69, 0, 0, 0 },
/ /Can only suppor t these r ates wh en the CPU is running at 6 MHz
//CPU_6MHz
{0, BPS_1200_6MHz, BPS_2400_6MHz, BPS_4800_6MHz,
0, BPS_14400_6MHz, 0, 0,
0, 0, 0, 0 , 0, 0},
/ /Can only suppor t these r ates wh en the CPU is running at 12 MHz
//CPU_12MHz
{0, 0, BPS_2400_12MHz, 0, BPS_9600_12MHz,
BPS_14400_12MHz, 0, BPS_28800_12MHz, 0,
0, 0, BPS_125000_12MHz, 0, BPS_375000_12MHz },
/ /Can only suppor t these r ates wh en the CPU is running at 24 MHz
//CPU_24MHz
{0, 0, 0, BPS_4800_24MHz, BPS_9600_24MHz,
BPS_14400_24MHz, BPS_19200_24MHz, BPS_28800_24MHz, 0,
BPS_57600_24MHz, 0, BPS_125000_24MHz, BPS_250000_24MHz,
BPS_375000_24MHz}
4.2.9 Power Managem en t API – Available with all 73S12xxF Devices
The Power Management API configur es the active d evices, thereby managing the power co nsumption of
the 73S12xxF. The API includes:
• PowerON() (page 52)
• PowerOFF() (page 53)
PowerON()
Purpose M anage power co nsumption.
Synopsis Voi d PowerON ( IN unsigned int PowerSelect );
Parameters PowerSelect: Input parameter
S pecifies which internal devices to enabl e. The following possibl e values (defined in
API_12.h) or any combinat i on (by OR’ing them) ar e allowed:
ENABLE_EICC BIT14 // External Smart car d.
ENABLE_VDDF BIT13 // VDD fault detection
ENABLE_UART BIT12 // Serial
ENABLE_PLL BIT11
ENABLE_ANALOG BIT10
ENABLE_USBXCVR BIT9 //USB Transceiver, Unavailable with 73S1205F
ENABLE_USB BIT8 //D+, Unavailable with 73S1205F
ENABLE_RTC BIT7 // Unavailable with 73S1205F
ENABLE_KEYPAD BIT6
ENABLE_ICC BIT5 // Smart card.
ENABLE_USBCLK BIT4 // USB Clock, Unavailable with 73S1205F
ENABLE_LS_OSC BIT3 //Low speed OSC-32kHz, Unavailable with
73S1205F
B its 2, 1 and 0 ar e r eserved for MCount value. D evices whi ch are already enabled
will remai n enabl ed.
Retur n Codes None.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 53
PowerOFF()
Purpose M anage power co nsumption.
Synopsis void PowerOFF ( IN unsigned int PowerSelect );
Parameters PowerSelect: Input parameter
S pecifies which internal devices to disable. Th e followin g possible values or any
combinati on (by O R’i ng them) ar e al lowed:
DISABLE_EICC BIT14 // External Smart car d.
DISABLE_VDDF BIT13
DISABLE_UART BIT12
DISABLE_PLL BIT11
DISABLE_ANALOG BIT10
DISABLE_USBXCVR BIT9
DISABLE_USB BIT8
DISABLE_RTC BIT7
DISABLE_KEYPAD BIT6
DISABLE_ICC BIT5
DISABLE_ USBCLK BIT4
DISABLE_LS_OSC BIT3
/ / Bit 2 r eser ved.
CPU_HALT BIT1
CPU_I DLE BIT0
Retur n Codes None.
Devices whi ch ar e already di sabled will remain disa bled. Any en abled inter r upt will cause an exit from
this function.
CPU_HALT has precedence over CPU_IDLE. CPU_I DLE mod e stops the clock going t o the CPU, al l
other clocks keep running.
CPU_HALT mode can be stopped by the USB an d RTC interrupts (i f available), by a key p r ess, by ICC
insertion or r emoval or by Rese t of the 73S12xxF. In order to use these external even ts to wake up the
CPU, they m u st first be individually initialized. For example, ICC_InitUART() or KEY_Init () should be
called pr ior to calling PowerOFF (DISABLE_ICC) or PowerOFF (DISABLE_KEYPAD). Internally, the API
will configure INT0 to b e active upon any of the events (key press, Smart Card event, etc..); thus an
application m ay setup its own INT0 interrupt service routine via Set_Event (eEXT0, ...) to custom ize its
specific needs upon waking up.
4.2.10 Analog T h resh old Man ag emen t Driver API – Available with all 73S12xxF Devices
This API co nt r ol s the analog volt age co mpar i son against t he volt age on the ANA_I N pin. The API
includes:
• ANALOG_Detect_Enable() (page 53)
• ANALOG_Detect_Disable() (page 54)
• A NALOG _Compare( ) (page 54)
ANALOG_Detect_Enable()
Purpose Select the analog threshold level and enable the i nte r r upt a c co r di ng to the polarity setting.
Synopsis void ANALOG_Detect_Enable (
IN Unsigned char threshold_select,
IN Unsigned char acomp_pol)
73S12xxF Software User Guide UG_12xxF_016
54 R ev. 1.50
Parameters threshold_select: Input parameter
Specifies which input voltage channel m ust be compared against Vco mpar e.
A llowable values ar e i n the r ange [0, 7].
acomp_pol: Input paramet er
Specifies the polarity f o r which an int e r r upt occur s; when v oltage level is Above (acomp_pol
= 1) or Below (acomp_pol = 0). Voltage levels are val ues i n the r a nge [0, 7].
7 corresponds to 2.50 volts //Only available with the 73S1205F
6 corresponds to 2.30 volts //Only available with the 73S1205F
5 corresponds to 2.00 volts //Only available with the 73S1205F
4 corresponds to 1.75 volts //Only available with the 73S1205F
3 corresponds to 1.50 volts
2 corresponds to 1.40 volts
1 corresponds to 1.24 volts
0 corresponds to 1.00 volts.
Retur n Codes None.
ANALOG_Detect_Disable()
Purpose D isa ble the Anal og level detect i nterrupt.
Synopsis Void ANALOG_Detect_Disable ( void );
Parameters None.
Retur n Codes None.
ANALOG _ Compa r e()
Purpose C ompare the selected input voltage against specified threshold.
Synopsis enum ANALOG_RC ANALOG_Compar e (
IN unsigned char threshold_select,
IN unsigned char acomp_pol );
Parameters threshold_select: Input parameter
Specifies which input voltage to compar e against ANA_I N . V alues are i n the range
[0, 7] as specified below.
acomp_pol: Input paramet er
Specifies which level to compare against (above or below). Values are in the range [0, 7].
7 corresponds to 2.50 volts
6 corresponds to 2.30 volts
5 corresponds to 2.00 volts
4 corresponds to 1.50 volts
3 corresponds to 1.40 volts
2 corresponds to 1.28 volts
1 corresponds to 1.24 volts
0 corresponds to 1.00 volts.
Retur n Codes ANALOG_OK
ANALOG_BELOW
ANALOG_ABOVE
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 55
4.2.11 E ven t Managemen t API – Available w ith all 73S12xxF Devices
The Even t M anagement API allows the application to handl e all system even ts. An application should
always call Events_Init() to initi al ize all event vector s at the beginning of the m ain program. The API
includes:
• Events_Init() (page 55)
• Events_Clear() (page 55)
• Get_Event () (page 56)
• S et_Event () (page 56)
Events_Init()
Purpose Initialize the system defau l t event vectors. Upon exiting this function, all vectors will
point to a null_isr. F or this reason, every feature (Smart car d, U SB, RTC, Keypad,
LCD, etc.) must call its initialization rou tine so th at its int erru pt service routin e will be
set proper ly.
Synopsis void Events_Ini t ( void );
Parameters None.
Retur n Codes None.
Events_Clear()
Purpose C lear selected events.
Synopsis Void Events_Clear ( unsigned long Events );
Parameters Events: Input paramet er
S pecifies which even ts to clear. Multi ple events ar e specified by OR’ing toget her
individual events. Possible values ar e:
EVENT_EXT0 BIT0
EVENT_EXT1 BIT1
EVENT_EXT2 BIT2
EVENT_EXT3 BIT3
EVENT_TIMER0 BIT4
EVENT_TIMER1 BIT5
RFU BIT6
EVENT_RTC BIT7 //not ava i la bl e with the 73S1205F
EVENT_KEY_DETECT BIT8
EVENT_USB BIT9 //not ava i la bl e with the 73S1205F
EVENT_VDDF BIT10
EVENT_I2C BIT11
EVENT_ANALOG BIT12
EVENT_USR0 BIT13
EVENT_USR1 BIT14
EVENT_USR2 BIT15
EVENT_USR3 BIT16
RFU BIT17
Return Codes None.
73S12xxF Software User Guide UG_12xxF_016
56 R ev. 1.50
Get_Event ()
Purpose Get sel ected event vector.
Synopsis (* void () ) Get_Eve n t_Vecto r ( IN en u m EVENT_ID eEventID );
Parameters eEventID: Input par ameter
S pecifies for which even t t o r eturn the curr ent vector. P ossible values ar e:
eEXT0, // 0
eEXT1, // 1
eEXT2, // 2
eEXT3, // 3
eTIMER0, // 4
eTIMER1, // 5
eICC, // 6 – will return poin ter to a Null_ isr
eRTC, // 7
eKEY_DETECT, // 8
eUSB, // 9
eVDDF, // 10
eI2C, // 11
eANALOG, // 12
eUSR0, // 1 3
eUSR1, // 1 4
eUSR2, // 1 5
eUSR3, // 1 6
eSERIAL // 17– will retu rn pointer to a Null_ isr
Return Value Selected Even t vector.
Set_ Event ()
Purpose Set sel ected event vector . Use this function to r edirect an inter r upt service rout i ne to
a customized function/routine. Care m ust be taken when using this function as other
functions within the LA PI may no longer work.
Synopsis Void Set_Event_Vector (
IN enu m EVENT_ID eE ventID,
I N void (*pEventVector ) ( void) );
Parameters eEventID: Input parameter
S pecifies for which even t t o add the handler. Possible values are:
eEXT0, // 0
eEXT1, // 1
eEXT2, // 2
eEXT3, // 3
eTIMER0, // 4
eTIMER1, // 5
RFU, // 6
eRTC, // 7
eKEY_DETECT, // 8
eUSB, // 9
eVDDF, // 10
eI2C, // 11
eANALOG, // 12
eUSR0, // 13
eUSR1, // 14
eUSR2, // 15
eUSR3, // 16
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 57
RFU // 17
pEventVector: Input par ameter
P ointer ( vector) to the function to call when the event occurs.
Retur n Codes None.
The eUSB handler should check the x.USBStatus value and/or cal l the
USB_Status() routine t o determine whi ch USB event occurred. All other even ts have unique ca uses.
4.2.12 Time rs API – Available w ith all 73S12xxF Devices
The Timers API allows up to four 16-bit 10 ms t imers to be run concurrently. Hardware timer T0 i s
dedi cated for t he Timers API. The API includes:
• Timers_Init () (page 57)
• Wait() (page 57)
• Wait_1ms() (page 57)
• Add_Timer() (page 57)
• Add_Timer_Func() (page 58)
• Remove_Timer() (page 58)
• Process_Timers() (page 58)
Timers_Init ()
Purpose Initialize all r egisters and functi ons associated with Timer 0 and Time r 1.
Synopsis V oid Timers_Init ( void );
Parameters None.
Retur n Codes None.
Wait()
Purpose Wait (10 x nTimeWait) milliseconds and then return.
Synopsis Voi d Wait ( IN unsigned int nTimeWait );
Parameters nTimeWait: I nput parameter
S pecifies how many 10 msec uni ts to wait before r eturni ng to the caller.
Retur n Codes None.
Wait_1ms()
Purpose Wait (nTimeWait) milliseconds and then return.
Synopsis Voi d Wait ( IN unsigned int nTimeWait );
Parameters nTimeWait: Input parameter
S pecifies how many 1 mse c units to wait before r eturni ng to the caller.
Retur n Codes None.
Add_Timer()
Purpose Add a 10 m s so ftware t imer.
73S12xxF Software User Guide UG_12xxF_016
58 R ev. 1.50
Synopsis Unsigned Inte ger * Add_Time r ( IN Unsigned integer nDuration)
Parameters nDuration: Input par ameter
S pecifies durati on of ti me i n 10 ms units.
Return Value Pointer to added timer. If the value is zer o (NULL), ther e ar e no t imers avail able.
This function can be called inside an ISR. When th e ti mer expi r es (*pTimer == 0), it will be autom at ically
removed. I f al l timers ar e in use, a NULL pointer will be returned. The Process_Timers() routine must be
cal led to keep the timer updated.
Add_Timer_Func()
Purpose Add a 10 m s so ftware t imer and the function to execute on timer expiration.
Synopsis Unsigned Inte ger * Add_Time r _Func (
IN unsigned int nDuration,
IN void (*pfExpi re (void)) );
Parameters nDuration: Input parameter
S pecifies durati on of time in 10 ms units.
pfExpire: Input paramet er
Specifies a poi nt er to the function to execute when the timer exp ires.
Return Value Pointer to the added ti mer. If value i s zero, there are no timers available.
Remove_Timer()
Purpose St op and r emove the se lected ti mer.
Synopsis Void Remove_T imer ( IN unsigned integer *pTimerId );
Parameters ptimerID: Input paramet er
S pecifies which ti mer to stop and remove. This is the value returned by the
Add_Timer() or Add_Timer_Func() functions.
Retur n Codes None.
Process_Timers()
Purpose Proce ss and updat e the active timers. Th is function must be called from a
foreground routine whenever ther e is acti ve timer.
Synopsis Void Process_Timers ( void );
Parameters None.
Retur n Codes None.
4.2.13 U s e r IO API – Available with all 73S12xxF Devices
The USER IO Pins can be configured, individually, as an interrupt source to Timer 0, Timer 1, I N T0 or
INT1. For INT0 or INT1, the interrupt can be configured to occur on the rising edge/high level or falling
edge/l ow level. Only IN T0 ca n be used t o wake up the CPU from sleep/ halt mode. This API includes:
• USR_I NT_Con fig () (page 59)
• USR_INT_Read() (page 59)
• USER_IO_Config() (page 60)
• USER_IO_Read() (page 60)
• USER_IO_Write() (page 60)
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 59
USR_I NT_Confi g ()
Purpose Con fig ure USER I O as an interrupt source for T0, T1, INT0 or INT1.
Synopsis void USR_INT_Config (
IN en um USRI NTSRC usr_src,
IN en um USRI NTSE L int_select,
I N Boolean Enable,
I N Boolean EdgeTrigger )
Parameters usr_src: I nput paramet er
S pecifies which USER IO is to be used as the interrupt source. The available
choices (defined in USRINTSRC in api_struct_12.h) are:
USR0SRC 0,
USR1SRC 1,
USR2SRC 2,
USR3SRC 3,
USR4SRC 4,
USR5SRC 5,
USR6SRC 6,
USR7SRC 7
Int_select: Input par ameter
Selects the interrupt source (defined in USRINTSEL in api_struct_12.h) as:
NOT_USE1 0,
NOT_USE2 1,
SEL_TIMER0 2,
SEL_TIMER1 3,
SEL_INT0_HI_RISE 4,
SEL_INT1_HI_RISE 5,
SEL_INT0_LOW_FALL 6,
SEL_INT1_LOW_FALL 7;
Enable: Input par ameter
If TRUE, enables t he selected i nt er r upt sour ce; other wise, di sables it.
EdgeTrigger: Inupt parameter
For INT0 and INT1 only, sets th e interrupt to be l evel ( FALSE) or edge (TRUE).
Retur n Codes None.
USR_INT_Read()
Purpose Read the current interrupt settings of the specified USER IO pin.
Synopsis en um USRI NTS EL USR_ INT_ Read ( en um USRI NTSRC u sr _src );
Parameters usr_src: I nput paramet er
Corresponding USR pin to read the interrupt setting from.
Retur n Codes One of the following as defined in USRINTSEL:
NULL,
SEL_TIMER0 2,
SEL_TIMER1 3,
SEL_INT0_HI_RISE 4,
SEL_INT1_HI_RISE 5,
SEL_INT0_LOW_FALL 6,
SEL_INT1_LOW_FALL 7;
73S12xxF Software User Guide UG_12xxF_016
60 R ev. 1.50
USER_IO_Config()
Purpose Configure the directi on for t he US ER I O pin s .
Synopsis void US ER_ IO_ Config ( Unsigned char usrsrc, Unsigned char dir )
Parameters usrsrc: I nput parameter
Corresponding USR pins to be co nfigur ed as Input or Output. USRIO 0 through 7
will be configured according to the Dir parameter below.
Dir: Input paramet er
Direction value (1=input, 0=output) for the selected pins.
Retur n Codes None.
USER_IO_Read()
Purpose Read the value of the USE R IO pins.
Synopsis void USER_IO_Read ( OUT char *user_dir, OUT char *user_data );
Parameters User_dir: Output par ameter
Direction value (1=input, 0=output) for the selected pins.
User_data: Output paramet er
V alue of the corresponding USER IO pins. All outpu ts will reflect the last value
written.
Retur n Codes None.
USER_IO_Write()
Purpose Write values to sel ected USER IO pins.
Synopsis V oid USER_IO_ Write ( IN char cUserIO, I N ch ar cUserIOselect );
Parameters cUserIO: Input paramet er
V alues to write to selected USE R IO pins.
cUserIOselect: Input par ameter
A ‘1’ in the corresponding bit will enable writing to that USR pin provided it is
configured as an output.
Retur n Codes None.
4.2.14 E xter n al Interrup ts API – Available w ith all 73S12xxF Devices
This API allows direct access to the two external i nterrupt pins (EXT3 and EXT2). These two interrupts
are onl y available as edge (falling/negative or rising/positive) sensiti ve. The API includes:
• INT2_Config() (page 60)
• INT2_Read() (page 61)
• INT3_Config() (page 61)
• INT3_Read() (page 61)
INT2_Config()
Purpose Configure External Interrupt 2.
Synopsis void I NT2_Config ( Unsigned char Enable, Unsigned char Polarity );
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 61
Parameters Enable: Input par ameter
Enable (1) or disable (0) interrupt 2.
Polarity : Input paramet er
Configure interrupt on rising edge (1) or falling edge (0).
Retur n Codes None.
INT2_Read()
Purpose R ead value of External Interrupt 2.
Synopsis void INT2_Read ( Unsigned char *polarity, Unsigned char *status)
Parameters polarity: Output parameter
Specifies t he pol ar i ty of the external interrupt 2 pin, rising edge = 1, falling edge = 0.
status: Output p arameter
External interrupt 2 edge flag.
Retur n Codes None.
INT3_Config()
Purpose Configure External Interrupt 2.
Synopsis void I NT3_Config ( Unsigned char Enable, Unsigned char Polarity );
Parameters Enable: Input parameter
Enable (1) or d isable (0) interrupt 3.
Polarity: Input par ameter
Configure interrupt on rising edge (1) or falling edge (0).
Retu rn Codes None
INT3_Read()
Purpose R ead value of External Interrupt 3.
Synopsis void INT3_Read ( Unsigned char *polarity, Unsigned char *status )
Parameters polarity: Output parameter
S pecifies the polar i ty of t he external i nt er r upt 3 pin, rising edge = 1, falling edge = 0.
status: Output p arameter
External interrupt 3 edge flag.
Retur n Codes None.
4.2.15 S p ecial Fun ction Register API – Available with all 73S12xxF Devices
The API allows read/write access to al l the 73S12xxF special functi on registers. The API includes:
• SFR_Read() (page 61)
• SFR_Write() (page 62)
SFR_Read()
Purpose R ead from the specified Special Function R egister.
73S12xxF Software User Guide UG_12xxF_016
62 R ev. 1.50
Synopsis SFR_RC SFR_Read ( IN char cSFRAddr, O UT char *pcSFRValu e );
Parameters cSFRAddr: Input parameter
Specifies the address of t he Special F unction Register to be r ead.
pcSFRValue: Ou tp u t p arameter
S pecifies the value read from the specified Special F unction Register.
Retur n Codes SFR_OK Successful r ead from the SF R.
SFR_INVALID Invalid SFR r eference d.
SFR_Write()
Purpose Write to the specified Special Function R egister.
Synopsis SFR_RC SFR_Wr ite ( IN char cSFRAddr, IN char cSFR, IN char cSF ROper ation );
Parameters cSFRAddr: Input parameter
Specifies the address of t he Special F unction Register to be written.
cSFR: Input parameter
S pecifies the value t o use to either set, clear or assign bi ts of the Special Function
Register specified.
cSFROperation: Input paramet er
S pecifies the operati on t o perform on the S pecial Function Regi ster with the value
supplied. Possible values ar e:
ASSIGN_SFR 0
AND_SFR 1
OR_SFR 2
Retur n Codes SFR_OK Successful write to the SF R.
SFR_INVALID Invalid or forbidden SFR r eference d.
T o set speci f ic bits of the SFR, OR them with ‘1’s. To clear specif i c bits of the SFR AND them w ith ‘0’s.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 63
4.2.16 F lash/ Memory API – Available with all 73S12xxF Devices
Fl ash management assumes that the CPU is running at the defau l t cl ock rate of 3.69 MHz. A Flash write
is processed on a page basis. If a writ e to a Fl ash address overlays two p ages, a t wo-page writ e
operati on will be performed.
The F lash write pr ocess involves 4 steps: Read, Erase , Verify, Write. Should any of these steps fail, the
writ e operation will fail. The user must use caution when using these APIs as there will be no check in
the LAPI for accidental writes. The API includes:
• Flash_Init() (page 63)
• memcpy_rx () (page 63)
• memcpy_xx () (page 64)
• memcpy_xi () (page 64)
• memcpy_ix () (page 64)
• memcmp_rx () (page 65)
• memcmp_xx () (page 65)
• memse t_x () (page 65)
• st rl en_x () (page 66)
• st rl en_r () (page 66)
• Log2 () (page 66)
Flash_Init()
Purpose Initialize the Flash management regi ster s to values appropr iate for the CPU running
at the default speed.
Synopsis void Fl ash_I nit ( void );
Parameters None.
Retur n Codes None.
m emcpy_rx ()
Purpose Flash m anagement – use to write to a Fl ash page t hat the destinat i on ROM address
belongs to using the contents from t he RAM sour ce l ocati on. If the length of the
source and the starting R OM l ocati on ca use the writ e operati on t o span more than
one 512-byte Flash page, the Read/Erase /Verify/ Write will take place on all the
pages involved. A n erase oper ati on will r esult in t he Flash co ntents being set to
0xFF.
Synopsis Bbool memcpy_ r x (
Unsigned char code *dst,
Unsigned char xdata *src,
Unsigned integer len );
Parameters dst: Input paramet er
Specifies starti ng R OM address of Fl ash to be written (destination).
src: Input parameter
Use contents at this RAM address locati on as the source data.
len: I nput parameter
Length (in bytes) of data to write to Fl ash.
Retur n Codes TRUE if t he Write was successful.
FALSE if the Write was not completed.
73S12xxF Software User Guide UG_12xxF_016
64 R ev. 1.50
m emcpy_xx ()
Purpose M emory management – use to copy the content s of external RAM (XRAM)
location(s) to other XR AM locati on(s).
Synopsis memcpy_xx (
Unsigned char xdata *dst,
Unsigned char xdata *src,
Unsigned integer len );
Parameters dst: Input paramet er
Destination: specifies starti ng address of XR AM to be written.
src: Input parameter
Use data at this XRA M address locati on as the source data.
len: I nput parameter
Length (in bytes) of data to co py from source to destination.
Retur n Codes None.
m emcpy_xi ()
Purpose M emory management – use to copy the content s of internal RA M (IRAM) l ocati on(s)
to XRAM location(s).
Synopsis memcpy_xi (
Unsigned char xdata *dst,
Unsigned char idata *src,
Unsigned char len );
Parameters dst: Input par ameter
Destinat ion: specifies starting addr ess of XRAM to be written.
src: In p u t parameter
Use data starti ng at this IRAM loca tion as the source dat a.
len: Input paramet er
S pecifies the lengt h (in byt es) to write to XRAM .
Retur n Codes None.
m emcpy_ix ()
Purpose M emory management – use to copy the content s of XRAM locations to IRAM
locations.
Synopsis memcpy_ix (
Unsigned char idata *dst,
Unsigned char xdata *src,
Unsigned char len );
Parameters dst: Input parameter
Destinat ion: specifies starting addr ess of I RAM to be writ ten
src: Input parameter
Use data starti ng at this XR AM locati on as the source data.
len: I nput parameter
S pecifies the length (in b ytes) to write to IRAM.
Retur n Codes None.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 65
m emcmp_rx ()
Purpose M emory management – use to compare the co nt ents of an XRAM l ocati on and a
ROM loca tion.
Synopsis Signed char mem cmp_rx (
Unsigned char code *dst,
Unsigned char xdata *src,
Unsigned integer len );
Parameters dst: Input parameter
S pecifies the star ti ng address of the ROM dat a to be co mpar ed.
src: Input parameter
S pecifies the star ti ng address of the XR AM data to co mpar e to.
len: Input parameter
S pecifies the lengt h (in bytes) of data to compare.
Retur n Codes 0 if the compare is successful (data matched).
Non zero if the sour ce and destination data do not mat ch.
m emcmp_xx ()
Purpose M emory management – use to compare the co nt ent s of an XR AM loca tion and
another XRAM l ocati on.
Synopsis Signed char mem cmp_xx (
Unsigned char xdata *dst,
Unsigned char xdata *src,
Unsigned integer len );
Parameters dst: Input paramet er
S pecifies the star ti ng address of the the fir st XRAM location to be compared.
src: Input parameter
S pecifies the star ti ng address of the the XRAM loca tion to compare to.
len: I nput parameter
S pecifies the length (in bytes) of data to compare.
Retur n Codes 0 if the compare is successful (dat a matched).
Non zero if t he source and destinat ion dat a do not match.
m emset_x ()
Purpose M emory management – use to fill the co nt ent s of X RAM with a specified value.
Synopsis void memset_x (
Unsigned char xdata *dst,
Unsigned char s,
Unsigned integer len );
Parameters dst: Input paramet er
S pecifies the star ti ng address of the XRA M location s to fill.
src: Input parameter
S pecifies the value to fill the XRAM with.
len: I nput parameter
S pecifies the num ber of bytes to fill with t he specified data.
Retur n Codes None.
73S12xxF Software User Guide UG_12xxF_016
66 R ev. 1.50
strlen_x ()
Purpose Compute the string length of ASCII data in XDATA (XRAM).
Synopsis unsigned i nt strlen_x ( IN unsigned char xdata *psource );
Parameters psource: Input paramet er
Specifies a p oi nter to the source data i n XRAM.
Return Value Length of the ASCII data string (in bytes) in the sp ecified X RAM location.
strl en _r ()
Purpose Compute the string length of ASCII data in ROM (Flash).
Synopsis unsigned i nt strlen_x ( IN unsigned char code *psource );
Parameters psource: Input paramet er
Specifies a poi nt er to the source data in Flash.
Return Value Length of the ASCII data (in bytes) in the specified Flash ROM location.
Log2 ()
Purpose Compute the l ogari thm ( base 2) of the input.
Synopsis unsigned i nt log2 ( IN unsigned int unumber );
Parameters unumber: Input par ameter
The input value to determine t he log2 of.
Return Value log2 of the input.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 67
4.2.17 Boot Loader and Passcode Management – Av a ila b le wit h the LAPI-*BL.lib Only
The Boot Loader code occupies the fir st (lower) 512 bytes of the Flash program space (0x0000 - 0x01FF)
including the passcode storag e space. The Boot Loader assumes that the CPU is running at the default
cl ock rate which is 3.69 MHz. As a r esult, the serial baud rate and al l soft-t i mers (timer 0) ar e cal culated
base d on the default CPU clock rate. The Boot Loader al so only accepts In tel Hex files via the Serial
RS-232 interface. The Boot Loader and Passcode M anagement API include:
• Boot() (page 68)
• CheckPassCode () (page 68)
• S etP assCode ( ) (page 69)
For secur ity an d author iza tion enforcement, t he passcode is implemented, embedded and validated
within the Boot Loader code. The Boot Loader will r eturn a hardware error if S ecurit y Mode 0 or Securit y
Mode 1 has already been enabl ed. Figure 9 depicts a successful Boot Loader scenario.
Application
Layer LAPI
Invoke the Boot
Loader Code
Boot (U16 PassCode)
Send Intel Hex record (one record at a time) in the format of:
:NNAAAARRDD..DD.CRC<crlf>
NN=#of bytes in record, AAAA = address of first byte,
RR=record type - see Note2
'P' = pass (record is valid) OR 'F' = fail
Validate PassCode
and wait for
Intel hex record
Start
Flash
Prog.
Start
Flash
Down
Load
If response = 'F'
resend the record,
ifresponse = 'P'
send next record
Figure 9: Boot Loader Sc enari o
The Passcode is a 2-byte integer data type wh er e the se cond byte is the co mpl ement of the fi r st byte.
A fter vali dat ing t he Passcode, the LAPI will configure the device’s serial inter face to be runni ng at 115200
baud wi th 8 data bi ts, No stop bit and Xon/ Xoff control ena ble d. It then waits for a valid Intel hex
record from t he Seri al RS-232 interface. The record’s checksum is checked along with its Flash address
loca tion. The Boot Loader code ar ea ( the first page of Fl ash – 512 bytes at address 0x0000 – 0x01FF)
will be protected. Any hex record with addresses on the first page will be ignored. Once a vali d hex
reco r d is accepted by the device, all Flash space ( exce pt for the Boot Loader area) will be permanently
erase d. For each successful hex record rece ived by the device, t he device will r espond with a ‘P’ . For
each failed hex recor d received by the device (bad C R C), the device will respond wit h an ‘F’. W hen the
device r eceives the last successful hex recor d and i f there is no er r or , the device will immediatel y jump to
t he start of t he new ap plicati on. F or a sample of t he usage of the Boot Loader API, r eview the
Pseudo-CCID application code (built and shipped in a separate TSC 73S12xxF PCCI D Serial release).
Figure 10 illustrates the Flash Download and F l ash Progr amming pr ocess.
73S12xxF Software User Guide UG_12xxF_016
68 R ev. 1.50
Application/Host
Received hex
record from
App/Host
Good record
(good CRC)?
Send 'F' to App/
Host Address >
0x01FF
Send 'P' to App/
Host
Program Flash
with Hex record End of File?
Yes
Jump to new app.
Start
Flash
Prog.
Yes
Start
Flash
Down
Load
Configure COM port
@ 115,200 baud,
8N1, Xon/Xoff
Open Hex File Yes
No
No
End of file?
Read Hex Record
Send Record to
LAPI
No
Prompt User to
terminate App.
LAPI Responds
= ? Retry
exhausted
'P' 'F'
No
Yes
Yes
LAPI-*.lib
Ignore Record
No
Configure COM port
@ 115,200 baud,
8N1, Xon/Xoff
Figure 10: FLASH Download and Progra mming Process
Boot()
Purpose Invoke the Boot Loader function to star t r eprogr amming of Fl ash.
Synopsis void Boot ( U16 PassCode );
Parameters PassCode: Input par ameter
S pecifies the 2-b yt e passcode.
Retur n Codes FALSE if the PassCode fail s validat ion.
O nce an applicati on ca l ls the Boot fu nction, and the PassCode is validat ed, cont r ol will not be returned.
CheckPassCode ()
Purpose Validate the PassCode for Secur i ty Mode management, PassCode management and
t he Boot function.
Synopsis Bbool Chec kPassCode ( U16 PassCode );
Parameters PassCode: Input par ameter
S pecifies the 2-b yt e passcode.
Retur n Codes TRUE if the PassCode is vali dated.
FALSE if the P assCode doesn’ t match with the passcode stored i n the Boot Loader
code space .
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 69
SetPassCode ( )
Purpose Change the PassCode t o a new val ue. The first (and default) passcode is 0x5AA5
and is stored at location 0x01E0 and 0x01E1. W hen SetPassCode() is executed the
first time, it writes 0x00 00 to these two ad dresses. The new P assCode will be written
at 0x01E2 and 0x01E3. Each time th is functi on is ca l led, the new PassCode will be
written at the next two consecutive addr ess locati ons and t he location of t he
OldPassCode will be over-written with a value of 0x0000. Once the new PassCode
reaches the last l ocati on (address loca tion 0x01F1), this function will no longer be
allowed to change the PassCode.
Synopsis SetPassCode ( U16 OldPassCode, U16 NewPassCode );
Parameters OldPassCode: Input paramet er
O l d PassCode as stored in the Boot Loader code space.
NewPassCode: Input parameter
NewPassCode t o be stored i n the new passcode location.
Retur n Codes TRUE if both the OldPassCode is validated and the number of passcode changes
has not exce eded 8. (The tot al number of passcode changes all owed is 8)
4.2.18 Security Mode Management - Av a ila b le wit h the LAPI-*BL.lib Only
There ar e three possible secur i ty modes , defined as MODE0, MODE1 and MODE2. MODE0 and
MODE1 are directl y co nt r olled by the hardware by a cal l to the LAPI. MODE2 is controlled by the
appl ica tion l ayer using the PassCode mechanism as desi gned by L API . A cor r ect PassCode is requir ed
before the se curit y mode can be set. The Secur ity Mode Management API includes:
• SETSecurity () (page 70)
• SECStatus () (page 70)
The pr ocesses wh ich occur when i niti ating each of t he t hree modes are descri bed below. Table 5 shows
t he actions al l owed during each mode.
Mode 0
1. Flctl SFR (0xB2 bi t 6) i s alr eady set in the cur r ent fl ash progr am.
2. S etup the Fuse C ont r ol Register.
3. S etup the Securi ty Ctl Regi ster.
4. Enable t he Trim Pulse Ct l Reg ister
A fter M ode 0 is execut ed, a ful l circui t r eset must be done for mode 0 to be in effect.
Mode 1
1. SEC (JP15 on EVB) bit set to HI.
2. S etup the Fuse C ont r ol Register.
3. Setu p th e Security Ctl Register.
4. Enable t he Trim Pulse Ct l Reg ister
Mode 2
This mode is strictly firmware and is implemented at the application level by calling the SetPassCode ( ) API.
1. If the Passcode is valid and has been m odified less than 8 times, the application should loop through
t o exhaust the number of ti mes the passcode change i s allowed.
2. S crambl e the last passcode wit h an i nvalid value t hen write it to t he last designated location of t he
passcode. The TSC Pseudo-CCID for Serial RS-232 release contai ns applica tion sour ce code that
demonstrates this mode. Please co nt act a Teridian Sales Represe ntative for a co py.
73S12xxF Software User Guide UG_12xxF_016
70 R ev. 1.50
I f the passcode has changed 8 times pri or to ent er ing Mode 2, it will be di sabled since no mor e passcode
changes are allowed . S ince this mode is controll ed by firmware, i t can be reset/re-initialized by using the
I C E t o r eprogr am the Flash.
Table 5: S ecuri ty Mode Actions Al lowed
Action Mode 0 Mode 1 Mode 2
P assCode Change No Yes2 No
P r ogram Space Visible via the ICE Flctl SFR bit 6:
Set - No
Not Set - Yes
No Yes
Fl ash Progr ammabl e via IC E Yes
1
No Yes
Fl ash Progr am via Boot Loader Yes Yes2 No
1 To reprogram the Flash using the ICE, hit the Erase button via the ICE, hit Reset on the EVB, then
reload t he Flash. If the new program has the FlCtl SFR security mode bit (bi t 6) set, t he ICE will continu e
t o be disabled (this is the case for all firmware wit h ' BL' i n the fil ename).
2 The Passcode and Boot Loader r eside on the first page of Flash, which is protected by Mode 1. In
order to compl etel y pr otect the Flash, enable M ode 2 which will disabl e Passcode and Boot Loader
changes.
SETSecuri ty ()
Purpose Set the hardware security to Mode 0 or Mode 1. C ar e must be t aken as once this
API is finished, the action is not reversible.
Synopsis void SE TSec ur ity ( U08 Mode )
Parameters Mode: I nput parameter
MODE0 – This mode only works wh en the Flash Control SFR (0xB2 bit 6) is set.
LAPI-MBL.lib was built with this SFR already setup for thi s mode.
MODE1 – The security bit (JP15 on the 1215 EVB) must be set high in order to set
t his mode.
Retur n Codes None.
SECStatus ()
Purpose The current hardware security status of the part. This function only returns the
hardware securi ty stat us ( M OD E 0 or M ODE 1) . Since M ode 2 is a
firmware/appli cati on level contr ol , it will not be repor ted.
Synopsis U08 SECStatus ( void )
Parameters None.
Retur n Codes MODE0 = BIT0 (0x01) – returned if the part is al r eady in MOD E 0.
MODE1 = BIT1 (0x02) – returned if the part i s alr eady in MODE 1.
0x00 – returned if no se cur ity mode setup has been performed on the part.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 71
4.2.19 Other Miscellaneous API Calls – Available w ith all 73S12xxF Devices
Several A PI calls are provided to help with initializing or re-initializin g all the registers, int erru pt s and
events. As a general gui deline, API_Init() should always be called at the beginning of the application
main routine. Th e mi scell aneous APIs i nclude:
• API_Init() (page 71)
• S oft_Reset () (page 71)
API_Init()
Purpose Enable TIMER0 and TIMER1 interrupts, clear all pending USB interrupts, set the
CPU to run at 3.69 MHz. Always call this routine at the beginning of an embedded
application.
Synopsis void API_ Init ( void );
Parameters None.
Retur n Codes None.
So ft_Re set ()
Purpose Initialize all 73S12xxF specific i nt er nal and exter nal SFRs to their hardware p ower-on
defaults.
I niti alize Smart Card SFR s to hard r eset defau l t values.
I niti alize U SB SFRs to hard r eset defau lt values.
Initialize most 80515 SFRs.
Synopsis void Soft_Re set ( void );
Parameters None.
Retur n Codes None.
73S12xxF Software User Guide UG_12xxF_016
72 R ev. 1.50
4.3 High-Level API
The 73S12xxF comes with a high-level API library to co nt r ol the Smart Card. This library is linked t o the
low-level API as described in Section 4.2 Low-level A PI for al l smar t card co mmunica tion contr ols.
4.3.1 S m art Card Control
This API provides support for the asynchronous (T=0) and (T=1) Smart Card protocol managem ent.
E ach Smart Card interface is individually addressed by specifying the correct eIccId val ue. Up to 9 smart
card slots can be configured, with the first (ICC_1ST) being the internal slot and the next 8 being external
slots. The API provides specific support for several test sui te constr aints (M i crosoft WHQL ( aka HCT),
EMVC o (MCI an d VCI)) by adding se veral opt ions to most of the API functions.
The Sm art Card API includes:
• ICC_Enable() or ICC_Enable_Ext () (page 73)
• ICC_WarmReset() (page 75)
• ICC_PTSNegotiate() (page 76)
• ICC_Send() (page 77)
• ICC_Send_Ext() (page 78)
• ICC_Configure_Ext () (page 79)
• ICC_Configure() (page 82)
• ICC_Disable() (page 83)
• ICC_CheckPresence() (page 84)
In order to use this API, the following minim um set of files i s required:
IccMgt .h: header fi l e which contai ns the prototypes for the API se r vices .
Icc_api-*. lib: this i s the ICC library itself.
Allocate.c: allows configuring the number of ICC interfaces use d (ther efore, only t he memory for the
use d int er face s i s reser ved).
Api_12.h and API_Struct_12.h: header files for low-level A PI .
Por table.h: co nt ains defi niti ons for C co de portabil i ty.
Several applicati ons are included in the release which deal with multi ple smart card slots. In or der for the
multiple smart card slot feature to function properly, it m ust first be configured using the ICC_Configure()
API. For a sample utilization of the ICC library, se e the sample appli cati ons: CCID firmware or Pseudo-
CCID firmware.
Configuring the ICC Interfaces
The ICC_USE D_INTERFACE_NUMBER an d INTERFACE_US ED[ 9] definition s in t he A llocate.c file
must be modified as shown below before using the API services. In this example, Smart card slots 1 and
2 are to be uti l ize d.
#define I CC_USE D_INTERFACE_NUMB ER 2 //two smartcard slots
unsigned char code INTERFACE_USED[9] =
{
ICC_1ST,
ICC_2ND,
ICC_NONE,
ICC_NONE,
ICC_NONE,
ICC_NONE,
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 73
ICC_NONE,
ICC_NONE,
ICC_NONE
};
ICC_Enable() or ICC_Enable_Ext ()
Purpose Activate the Smart C ar d inter face slot specified by eIccId, and return the ATR to the
appl ica tion. ICC_Enable_Ext() is the extended function. The extended version has
one additi onal par ameter as input. This l ast par ameter i s a pointer to a cal lback
fu nction to be called whenever the car d se nds a r equest for wait ti me ext ension
(S(WTX) in T=1 or 0x60 (NULL) in T=0 per the CCID Specification).
Synopsis AR_I CC_RC ICC_ Enable (
IN enum ICC_I D eIccId,
IN BOOLEAN bIccATRAutoCh eck,
IN BOOLEAN bIccEMVCompliant,
IN BOOLEAN bIccHighSpeed,
IN BO OL EAN bIccClockSt op Enable,
I N enum ICC_POWER ucIccPowerSelect,
OUT unsigned char *pucIccATR
OUT unsigned char *pucIccATRLength );
or
AR_ICC_ RC ICC_E n able _Ext (
IN enu m ICC_ID eIccId,
IN BOOLEAN bIccATRAutoCh eck,
IN BOOLEAN bIccEMVCompliant,
IN BOOLEAN bIccHighSpeed,
IN BO OL EAN bIccClockSt op Enable,
I N enum ICC_POWER ucIccPowerSelect,
OUT unsigned char *pucIccATR
OUT unsigned char *pucIccATRLength,
IN (Send_WTE) ( void ) );
Parameters eIccId: In p u t p arameter.
The l ower (least signi fi cant) 4-bits sp ecify which Smart Card inter face is to be
activated. Possible values are:
ICC_1ST 0, (Internal)
ICC_2ND 1, (External)
…
ICC_9TH 8 (E xternal).
The higher (m ost significant) 4-bits specify whether the card detect polarity is high
(CARD_DET_H) or low (CA RD_DET_L). See additional detai ls at the end of the
description for this function.
bIccATRAutoCheck: Input parameter
S pecifies whether the S mart Card interface must be immediatel y de-activated in t he
case of an unsupported ATR (TRUE) or i f the A TR must be tr ansmi tted back to the
application, which will decide what needs to be done (e.g. performing a Warm
Reset). [The defau l t valu e shoul d be TRUE, but for the various test suites, it may b e
nece ssary for t he applicati on to decide whether or not the i nterface i s to be
deactivated.]
bIccEMVCompliant: Input paramet er
S pecifies whether the S mart Card interface i s to be managed according to the EMV
Specification (TRUE) or to the ISO 7816-3 standard (FALSE). Th is is especially
important on TimeOut er r or s and on IFSD negoti ati on. On TimeO ut error s i n the T=1
protocol , EMV specifi es that t he I FD must de-activate the Smar t C ar d int er face,
73S12xxF Software User Guide UG_12xxF_016
74 R ev. 1.50
whereas the ISO 7816-3 standard all ows an error r ecovery p r ocedure. EM V
specifies that the IFD must initi ate an I FSD negoti ation before t he first command
t r ansmi ssion in ( T=1) protoco l. Wh en EMV mode is specified, bIccIFSDRequestT1
is set t o TRUE and bIccDeactivatedOnTimeOutErrorT1 is set to TRUE.
bIccHighSpeed: Input parameter
S pecifies if the reader has to swi tch to the high speed clock (7.384 MHz) if the smart
car d all ows i t ( according to parameter Fi in th e A TR). I f this parameter is FAL SE, the
reader will always use the defaul t clock, namel y 3.692 M H z. If the value is TRUE,
t he reader will switch to 7.384 MHz after the ATR, i f the smart card all ows this speed.
bIccClockStopEnable: Input parameter
If this flag is set to TRUE an d the smart card allows clock st op/ st art, the clock will be
stopped when there is no t r ansacti on. That is to say t hat the clock is stopped after a
command is done and restarted before the next command will be executed.
ucIccPowerSelect: Input par ameter
Specifies the voltage t hat is to be applied t o the ca r d. P ossible values ar e:
ICC_POWER_AUTOMATIC 00, (automati c voltage sel ecti on accor ding to ISO
7816-3 standard)
ICC_POWER_SET_5 01,
ICC_POWER_SET_3 02, Other values are R FU.
pucIccATR: Output parameter
The ATR valu e r eturned by t he Smart Car d.
pucIccATRLength: Outp ut p arameter
Length of the ATR returned by the Sm art Card. This value should not exceed 32, as
the ATR cannot contain more than 32 bytes.
Send_WTE: Input paramet er
Call th is function whenever the card se nds a Wait Time Extension r equest (i n T=1,
whenever the card sends an S (WTX) block; fo r T=0, whenever the card sends NULL
(0x60) when it is waiting for data from the reader). This functionality is required by
the CCID Specification. This callback function will NOT be ca l led i f the smart card is
cal led for EMV mode because of the strict timing requirements of the EMV
S pecificati on.
Retur n Codes AR_ICC_OK
S uccessful operati on. The Smart C ar d was activated and the ATR is supported
by the chip.
AR_ICC_ERR_BAD_PARAM
A n invalid paramet er ( eIccId for example) was specified.
AR_ICC_ERR_CARD_MUTE
The Smart Card is mut e.
AR_ICC_ERR_CARD_ABSENT
No Smart C ar d is i nser ted.
AR_ICC_ERR_CARD_DISCONNECTED
The Smart C ar d was deactivat ed.
AR_ICC_ERR_CARD_OVERLOAD
The Smart C ar d has generated an over curr ent.
AR_ICC_ERR_CARD_UNSUPPORTED_ATR
The Sm art Card ATR is not supported by the chip and is stored in pucIccAtr.
The Smart Card inter face has not been de-activated (bIccATRAutoCheck option
is not selected).
AR_ICC_ERR_BAD_TCK
The ATR has a bad TCK byte.
AR_ICC_ERR_BAD_TS
The ATR has a bad TS byte.
AR_ICC_ERR_CARD_COMM_PB
The ATR has either a parity error, an Rx over-ru n or a VCC unst able error.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 75
The eIccId parameter is split into two fields: C ar d Detect Polari ty and Card S lot number, by using the
most significant nibble and least significant nibble, respectively. Therefore, the most significant nibble of
the eIccId parameter is used t o det er mi ne if the Card Detect Pol ar ity is to be configured High or Low.
The constants CARD_DET_H and CARD_DET_L are defined in ICCMgt.h. Examples:
1. If Card Detect Polar ity is to be se t to High when a ca r d is inserted, it can be done so by call ing:
ICC_En able( eIccI d | CARD_DET_H, bIcc ATRAutoCheck,etc.).
2. If Car d Detect Polari ty is to be set to Low when a car d is i nser ted, it can be done so by call ing:
ICC_En able( eIccI d | CARD_DET_L, bIccATRAutoCheck,etc.).
3. Calling ICC_ Enab le (eIccId , bIccA TRAu t oCheck, etc.) withou t OR’ing eIccId with CA RD_DET_L or
CARD_DET_H (in ot her word s, eIccID <= 0x09 ) will default to CARD_DET_H.
ICC_WarmReset()
Purpose Perform a War m R eset on t he Smart Car d and r eturn t he ATR t o the applicati on.
Synopsis AR_I CC_RC ICC_ WarmRe se t (
IN enu m ICC_ID eIccId,
OUT unsigned char *pucIccATR,
OUT unsigned int *punIccATRLength );
Parameters eIccId: Input paramet er
S pecifies which Smart C ar d int er face is to be acti vated. Possible values ar e:
ICC_1ST 0, (Internal)
ICC_2ND 1, ( External)
…
ICC_9TH 8 (E xternal).
pucIccATR: Output parameter
A TR value r eturned by t he Smart Car d.
punIccATRLength: Outpu t p arameter
Length of the ATR returned by the Sm art Card. This value should not exceed 32, as
the ATR cannot contain more than 32 bytes.
Retur n Codes AR_ICC_OK
Successful operati on. The rece ived ATR is stor ed in pucIccATR.
AR_ICC_ERR_BAD_PARAM
An invalid paramet er ( eIccId for example) was specified.
AR_ICC_ERR_CARD_MUTE
The Smart C ar d is mute.
AR_ICC_ERR_CARD_ABSENT
N o Smar t Card is inserted.
AR_ICC_ERR_CARD_DISCONNECTED
The Smart Card was d eacti vated.
AR_ICC_ERR_CARD_OVERLOAD
The Smart C ar d has generated an over curr ent.
AR_ICC_ERR_CARD_UNSUPPORTED_ATR
The Sm art Card ATR is not supported by the chip and is stored in pucIccAtr. The
S mart Card interface has not been de-activated (the bIccATRAutoCheck op tion not
selected).
AR_ICC_ERR_BAD_TCK
The ATR has a bad TCK byte.
AR_ICC_ERR_BAD_TS
The ATR has a bad TS byte.
AR_ICC_ERR_CARD_COMM_PB
The ATR h as ei ther a parity error, an Rx over run or a V CC unstable error.
73S12xxF Software User Guide UG_12xxF_016
76 R ev. 1.50
ICC_PTSNegotiate()
Purpose Transmit the PTS negoti ation r equest to the Smart Card and veri fy its answer. When
the PTS negotiation succeeds, the 73S12xxF configures its internal protocol
parameters wit h t he negot i ated values.
Synopsis AR_I CC_RC ICC_ PTSNegotiate (
IN enu m ICC_ID eIccId,
I N BO OLEAN bIccChangeProtocol ,
IN BOOLEAN bIccChangeSpeed,
IN BOOLEAN bIccSelectT1 Protocol,
IN unsigned char ucIccFiDi,
OUT unsigned char *pucIccPTS,
OUT unsigned int *punIccPTSLength );
Parameters eIccId: Input paramet er
S pecifies which Smart C ar d int er face is to be acti vated. Possible values ar e:
ICC_1ST 0, (Internal)
ICC_2ND 1, ( External)
…
ICC_9TH 8 (External)
bIccChangeProtocol: Input parameter
Specifies wh ether the protocol i s to be changed (TRUE) or not.
bIccChangeSpeed: I nput paramet er
Specifies whether the speed is to be changed (TRUE) or not .
bIccSelectT1Protocol: Input par ameter
Specifies whether T=1 protocol i s selected (TRUE) or T=0 ( FALSE). This par ameter
is ig nored if bIccChangeProtocol is set to FALSE.
ucIccFiDi: Input parameter
Specifies the new bit rate and clock adj ustment factors to be used (i n case
bIccChangeSpeed is set to TRUE)
pucIccPTS: Output parameter
Contains t he PTS answer received from the Smar t C ar d.
punIccPTSLength: Output parameter
Contains t he length of the PTS answer received from the Smart C ar d. Thi s value
should be in the range 03 to 06.
Retur n Codes AR_ICC_OK
S uccessful operati on. The PTS negoti ation succeeded. The PTS answer from
t he Smart Car d is stored in pucIccPTS.
AR_ICC_ERR_CARD_MUTE
The Smart Card does not r espond t o the PTS negotiation.
AR_ICC_ERR_CARD_ABSENT
No Smart C ar d is i nser ted.
AR_ICC_ERR_CARD_DISCONNECTED
The Smart Card was removed duri ng the PTS negotiation operation.
AR_ICC_ERR_CARD_OVERLOAD
The Smart Card has generated an overload.
AR_ICC_ERR_BAD_PARAM
Incorrect bytes were sent by the card.
ICC_ERR_PTS_NEGOTIATION
Fi D i to negot iate is unacceptabl e.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 77
ICC_Send()
Purpose Transmit a data co mmand t o the Smart Car d int er face and wais for the answer from
t he Smart Car d. This fu nction is r esponsibl e for the Smart C ar d command format
analysis which computes the correct comm and case (1, 2 Short, 3 Short or 4 Short).
The AP I assumes that the data record size is 255 bytes or less which is why it
supports short ca ses onl y.
Synopsis AR_I CC_RC I CC_Send (
IN enu m ICC_ID eIccId,
IN unsigned int unIccCommandLength,
IN unsigned char *pucIccCommand,
OUT unsigned int *punIccResponseLength,
OUT unsigned char *pucIccResponse,
OUT unsigned char *pucSW1,
OUT unsigned char *pucSW2,
OUT BOOL EA N *pbitStatusJustAfterHeader );
Parameters eIccId: Input paramet er
S pecifies which Smart C ar d int er face is to be acti vated. Possible values ar e:
ICC_1ST 0, (Internal)
ICC_2ND 1, ( External)
…
ICC_9TH 8 (External)
unIccCommandLength: Input paramet er
S pecifies the number of bytes of data point ed to by puclccCommand.
pucIccCommand: Input paramet er
S pecifies the command to be t r ansmi tted to the Smar t Card inter face.
punIccResponseLength: O ut put par ameter
S pecifies the number of bytes of response data point ed to by puclccResponse. (The
lengt h value does not include the status bytes SW1/SW2).
pucIccResponse: Ou tp u t p arameter
Contains the response of the Smart Card (SW 1/SW2 not included).
pucSW1: Output paramet er
Contains the r ecei ved SW1value.
pucSW2: Output parameter
Contains the r ecei ved SW2 value.
pbStatusJustAfterHeader: Output par ameter
Thi s boolean parameter specifies i f the status bytes have b een rece ived j ust after the
header ( TRUE) or after the data (FALSE) [Use ful for the EMV Tests suite]. This
parameter must be t aken into account only if t he ICC_Configure() command sets the
pbIccWarningStatusBytesManagementT0 bit.
Retur n Codes AR_ICC_OK
S uccessful operati on: the co mmand was successfully t r ansmi tt ed t o the Smart
Card and a vali d response was recei ved.
AR_ICC_ERR_BAD_PARAM
An inconsistent com m and was specified. The API was unable to compute t he
command case value.
AR_ICC_ERR_CARD_MUTE
The Smart Card is mut e.
AR_ICC_ERR_CARD_ABSENT
No Smart C ar d is i nser ted.
AR_ICC_ERR_CARD_DISCONNECTED
The Smart Card was removed duri ng the acti vation operation.
73S12xxF Software User Guide UG_12xxF_016
78 R ev. 1.50
AR_ICC_ERR_WRONG_LEN
Either the co mmand case (T=0) i s not corr ectl y formatted, or the buffe r size
specified is too small; especially in a Case 2 wh er e the ca r d sometimes responds
with a 61xx with xx > specifi ed buffer size.
AR_ICC_ERR_CARD_COMM_PB
Too many errors occurred, so the inter face has been close d.
AR_ICC_ERR_CARD_COMM_PB
There is a communica tion er r or bet ween the reader and smart card such as a
p arity error, a bad r esponse block from the card, a bad EDC, a transmission err or
or a bad pr ocedure byt e.
ICC_Send_Ext()
Purpose Transmit a data command to the S mart Card interface and wait for the answer. This
API is very similar to the ICC_Send() AP I except i t r equi r es a MaxBuffSize. Th e
appl ica tion i s responsible for the Smart Car d co mmand format analysi s to compute
the corr ect command case (1, 2 Short and Extended, 3 Short and Extended or 4
Short and Extended). Calling ICC_Send_Ext() with a MaxBuffSize of 260 bytes (255
data byt es + 5 header bytes) i s equivalent to calling ICC_Send. The ISO 7816-4
standard specifies that setting the fi r st byte (of 3 bytes; or the 5th byt e of the
command header bytes) of the data length field equal to 0x00 indicates the extended
cases; wher eas JICSAP (version 1.1) specifies the valu e of this byte to be 0xFF .
This AP I is written to accept the I SO format so any co mmand with the fift h byte of the
command header having a value of 0x00 will be tr eated as an extended case .
Synopsis AR_I CC_RC I CC_Send_Ext (
IN enu m ICC_ID eIccId,
IN unsigned int unIccCommandLength,
IN unsigned char *pucIccCommand,
IN unsigned int MaxBuffSize,
OUT unsigned int *punIccResponseLength,
OUT unsigned char *pucIccResponse,
OUT unsigned char *pucSW1,
OUT unsigned char *pucSW2,
OUT BOOL EA N *pbStatusJustAfterHeader );
Parameters eIccId: Input paramet er
S pecifies which Smart C ar d int er face is to be acti vated. Possible values ar e:
ICC_1ST 0, (Internal)
ICC_2ND 1, ( External)
…
ICC_9TH 8 (External)
unIccCommandLength: Input paramet er
S pecifies the number of bytes of data point ed to by puclccCommand.
pucIccCommand: Input paramet er
S pecifies the command to be t r ansmi tted to the Smar t Card inter face.
MaxBuffSize: I nput parameter
S pecifies the maximum buffer size the r eader should r eserve to hol d the data byt es
sent from the card.
punIccResponseLength: Output p arameter
S pecifies the number of bytes of response data point ed to by puclccResponse. (This
lengt h value does not include the status bytes SW1/SW2)
pucIccResponse: Ou tp u t p arameter
Contains the r esponse of t he Smart Card (SW1/SW2 not included).
pucSW1: Output parameter
Contains the r ecei ved SW1value.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 79
pucSW2: Output parameter
Contains the r ecei ved SW2 value.
pbStatusJustAfterHeader: Output p arameter
Thi s boolean parameter specifies i f the status bytes have b een rece i ved j ust after the
header ( TRUE) or after the data (FALSE) [Use ful for the EMV Tests suite]. This
parameter must be t aken into account only if t he ICC_Configure() command set t he
pbIccWarningStatusBytesManagementT0 bit.
Retur n Codes AR_ICC_OK
S uccessful operati on: the co mmand was successfully t r ansmi tt ed t o the Smart
Card and a vali d response was recei ved.
AR_ICC_ERR_BAD_PARAM
An inconsistent com m and was specified. The API was unable to compute t he
command case value.
AR_ICC_ERR_CARD_MUTE
The Smart Card is mut e.
AR_ICC_ERR_CARD_ABSENT
No Smart C ar d is i nser ted.
AR_ICC_ERR_CARD_DISCONNECTED
The Smart Card was removed duri ng the acti vation operation.
AR_ICC_ERR_WRONG_LEN
Either the co mmand case (T=0) i s not corr ectl y formatted, or the buffe r size
specified is too small; especially in a Case 2 wh er e the ca r d sometimes responds
with a 61xx where xx > specified buffer size.
AR_ICC_ERR_CARD_COMM_PB
Too many errors wit h the Smart Card occurred, so the int er face has been close d.
AR_ICC_ERR_CARD_COMM_PB
There is some co mmunica tion err or between the reader and smart card such as
a parity error, a bad response block from the card, a bad EDC, a transmission
error or a bad proce dure byte.
ICC_Configur e_E xt ()
Purpose Get and Set the configurabl e protocol parameters of t he specified Smart Car d
inter face. Th i s function was developed to support different conformance tests and
different hardware co nfiguration. This AP I should be called as the fi r st H API cal l to
make sure the har dware configurati on is setup properly accor ding to the hardware
design.
This API is recently added to the CCID USB release version 1. 50 (or PCCID release
later than version 3.10). Th e API is an extensi on of ICC_Configure() t o provide
backw ar d compatibi lity. Either ICC_Configure_Ext () or ICC_Configure() should be
called, not both. ICC_Confi gure i s exactly the sa me as ICC_Configure_Ext with
default values for ICC_HW Configure_t such that: IccHz = ICC_3600KHZ),
DebouncePUE nab le = SC_DEBOUNCEON | TRUE and Deb oun cePDE nab le =
SC_DEBOUNCEOFF | FALSE.
Synopsis AR_I CC_RC I CC_Co nfigur e_Ex t (
IN enu m ICC_ID eIccId,
I N enu m ICC_ADDR IccAd dr,
IN en um ICC_CA RDEVE NT IccCE,
IN enu m I2C_USRIO eIccUsrIO, // only use this option i n t he ca se of
single-8010
// controlling mult iple external slots.
IN BOOLEAN bIccSetOperation,
INOUT ICC_Configure_t *ptrConfigure,
73S12xxF Software User Guide UG_12xxF_016
80 R ev. 1.50
//This is newly added from version 1.50 release
IN I CC_HWConfigu re_ t p trHWCon fig ure );
Struct ICC_Configure_t
{
INOUT unsigned char ucIccIFSD;
INOUT unsigned char ucIccNAD;
//this variable when initialize to 0xFF the GetResponse command will carry the C LA
//byte of the last C-APDU. UcIccCLA = 0x00 for EMV, = 0xFF for non-EMV
INOUT unsigned char ucIccCLA;
INOUT unsigned char ucIccTSTimeOut;
INOUT unsigned char ucIccRxErrorCounterT0;
INOUT unsigned char ucIccTxErrorCounterT0;
INO UT unsigned char ucIccTxErrorCounterT1;
INOUT unsigned char ucIccConfigurationByte;
};
Struct ICC_HWConfigure_t
{
IN en um ICC_HZ I cc_Hz; //Smart Card Clock Frequency desired by application.
IN unsigned char DebouncePUEnable;
IN unsigned char DebouncePDEnable;
}
Parameters eIccId: Input paramet er
S pecifies which Smart C ar d int er face is to be acti vated. Possible values ar e:
ICC_1ST 0, (Internal)
ICC_2ND 1, ( External)
…
ICC_9TH 8 (External)
IccAddr: Input par ameter
Specifies the address fo r the exter nal I2C slot.
ICC_I2C0 0x40, (1st external slot)
ICC_I2C1 0x42,
ICC_I2C2 0x44,
…
ICC_I2C7 0x4 E; ( Last external slot)
IccCE: Input par ameter
S pecifies assignment of the INT2/INT3 pins for card events. Possible values ar e:
ICC_INT2_NONE 0x00,
ICC_INT2_I2C 0x01,
ICC_INT3_I2C 0x02;
bIccSetOperation: Input paramet er
S pecifies if the fu nction i s called to perform a Set oper ation ( TRUE) or a Get
operati on (F ALSE) .
pucIccIFSD: Input/output parameter
S pecifies the IFSD value t o be used ( or being used). [Defaul t value is 32, as
specified by ISO/IEC 7816-3]
pucIccNAD: Input/output parameter
S pecifies the NAD value to be used ( or being used) . [Default value is 00]
pucIccCLA: Input/output parameter
S pecifies the CLA value t o be used (or being used) when performing a GetResponse
in case 2 / 4 in t he T= 0 protocol. Setting pucIccCLA equal to 0xFF indicates that the
G etResponse comm and shall echo the cl ass byte of t he APD U command. [Default
value is 00]
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 81
punIccTSTimeOut: Input/output parameter
S pecifies the maximum delay in clock cy cles bet ween the de-asse r tion of the RST
si gnal and the leadi ng edge of t he TS character of the ATR. [Default valu e is 40 000]
pucIccRxErrorCounterT0: Input/output parameter
S pecifies the maximum number of err or s allowed wh en t he Inter face Device is in
rece pt ion mode in T=0 protocol.
pucIccTxErrorCounterT0: Input/output parameter
S pecifies the maximum number of err or s wh en t he Inter face Device i s i n
t r ansmi ssion mode in T=0 protocol.
pucIccTxErrorCounterT1: Input/output parameter
S pecifies the maximum number of err or s when T=1. The most si gnificant nibble
gives the maximum number of R(NA) block transmissions, wh ile the least significant
nibble gives the m aximum number of I or S-block retransmissions.
ucIccConfigurationByte: Input/output parameter
This byte contains the following configuration bits:
[b0] bIccIFSDRequestT1: Input/output. Speci fi es i f the next I-B lock will be
p receded by an S (IFS request) (TRUE) or not (F ALSE).
[b1] bIccDeactivatedOnTimeOutErrorT1: Input/output. Specifies if the Smart Card
inter face is to be de-activated (TRUE) on a TimeOut er r or . Ot herwise, an error
reco very p r ocedure i s engaged.
[b2] bIccNADErrorCheckingT1: Input/output. S peci fi es wh ether the NAD er r or s
are to be checked (TRUE) or not (F ALSE).
[b3] bIccABORTManagementT1: Input/output. Specifi es wh ether the AB ORT
Request is to be managed (TRUE) or i f the cont acts are to be de-activated on
S(ABORT Request) reception (FALSE).
[b4] bIccRESYNCHManagementT1: Input/output. Specifies whether an
S ( RESYN CH R equest) command i s to be sent when too many error s occur
(TRUE ) or if a de-activation sequence is to be initi ated (F ALSE) .
[b5] bIccRetransmitLastBlockAfterRESYNCHT1: Input/output. Specifies whether
t he last bl ock in T=1 protocol is to be retransmi tted aft er a r esynchronization
occur s or the whol e command. [Useful for Mi crosoft IF DTESTs suite]
[b6] bIccWarningStatusBytesManagementT0: Input/output. Specifies if th e IF D
must inform the appl i cati on level of whether the status bytes have been
rece i ved j ust after the co mmand header tr ansmi ssion or aft er the co mmand
data transmi ssion (in T=0 protocol). [Useful for EM V Test suites]
[b7] bIccDeactivateOnIFSDNegotiationError: Input/output. Specifies if t he Smart
Card interface i s to be de-activated on an IFSD negoti ation er r or .
Icc_Hz: Input paramet er
S pecifies the desired Smart Car d clock frequency. Avail able values ar e defined in
the API_Struct_12.h file (LAPI). The default value for bot h the inter nal and exter nal
slots is 3.69 MHz.
Care must be t aken to make sure the Smart C ar d Cl ock is slower than the CPU clock. Since the
CPU has much more overhead to process, a fast er Smar t Card cl ock may out r un the CPU
resulting in unexpected or undesirable delays.
Since t he Smart C ar d Clock for the external slots (slot ICC_ 2ND or higher) is driven by the 73S12xxF
si ngl e sour ce, al l exter nal slots will share the same SC clock configuration. For example, i f an appl ica tion
sets the first ext er nal slot t o one rate, subsequent calls to this function with a different rate will be ignored.
DebouncePUEnable: Input parameter
The higher order (m ost significant) nibble of this byte enables (SC_DEBOUNCEON)
or di sables (SC_DEBOUNCEOFF) card debounce. Th e low ord er ( l east signi fi cant)
nibble of this byte enables (TRUE ) or d isables (FALSE) the Pull-Up.
73S12xxF Software User Guide UG_12xxF_016
82 R ev. 1.50
DebouncePDEnable: Input parameter
The higher order (m ost significant) nibble of this byte enables (SC_DEBOUNCEON)
or di sables ( SC_D EBOUNCEO FF ) card debounce. The low ord er ( least significant)
nibble of this byte enables (TRUE) or disables (FALSE) the Pull-Down.
Retur n Codes AR_ICC_OK Successful oper ation.
ICC_Configure()
Purpose Get / S et t he configurabl e protocol parameters of t he specified S mart Card interface.
This function was developed to support different conformance tests. This API should
be called prior to calling I CC_Enable. It is the sa me as ICC_C onfigure_Ext, above,
with default values for IccHz (ICC_3600KHZ), DebouncePUEnable =
SC_DEBOUNCEON | T RUE, and DebouncePDEnable = SC _DEBOU N CEOF F | FALSE.
Synopsis AR_I CC_RC ICC_ Co nfigur e (
IN enu m ICC_ID eIccId,
IN en um ICC_A DDR IccAddr,
IN en um ICC_CA RDEVE NT IccCE,
IN BOOLEAN bIccSetOperation,
INOUT ICC_Configure_t *ptrConfigure );
Struct ICC_Configure_t
{
INOUT unsigned char ucIccIFSD;
INOUT unsigned char ucIccNAD;
// this variable when initi al ize to 0xFF the GetResponse co mmand will ca r r y the
CLA //byte of the last C-APDU. UcIccCLA = 0x00 for EMV, = 0xFF for non-EMV
INOUT unsigned char ucIccCLA;
INOUT unsigned char ucIccTSTimeOut;
INOUT unsigned char ucIccRxErrorCounterT0;
INOUT unsigned char ucIccTxErrorCounterT0;
INOUT unsigned char ucIccTxErrorCounterT1;
INOUT unsigned char ucIccConfigurationByte;
};
Parameters eIccId: Input paramet er
S pecifies which Smart C ar d int er face is to be activated. P ossible values ar e:
ICC_1ST 0, (Internal)
ICC_2ND 1, ( External)
…
ICC_9TH 8 (External)
IccAddr: I nput parameter
Specifies the address for the external I2C slot. Possible values ar e:
ICC_I2C0 0x40, (1st external slot)
ICC_I2C1 0x42,
ICC_I2C2 0x44,
…
ICC_I2C7 0x4 E; ( Last external slot)
IccCE: Input par ameter
Specifies the assignment of the INT2/INT3 pins for card events. Possibl e values ar e:
ICC_INT2_NONE 0x00,
ICC_INT2_I2C 0x01,
ICC_INT3_I2C 0x02;
bIccSetOperation: Inp ut par ameter
S pecifies if the fu nction i s called to perform a Set oper ation ( TRUE) or a Get
operati on (F ALSE) .
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 83
pucIccIFSD: Input/output parameter
S pecifies the IFSD value t o be used ( or being used) . [Default value is 32 as
specified by ISO/IEC 7816-3]
pucIccNAD: Input/output parameter
S pecifies the NAD value to be used ( or being used) . [Default valu e is 00]
pucIccCLA: Input/output parameter
Spe c ifie s the C LA val ue to be us e d ( or be i ng used) whe n pe r for mi ng a GetR e s po nse in
case 2 / 4 (in T=0 protocol). Setti ng pucIccCLA to 0xFF indicates that the GetResponse
command w ill echo the class byte of the APDU command. [Default value is 00]
punIccTSTimeOut: Input/output parameter
S pecifies the maximum delay in clock cy cles bet ween the de-asse r tion of the RST
signal and the leading edge of the TS character of the ATR. [Default value is 40 000]
pucIccRxErrorCounterT0: Input/output parameter
S pecifies the maximum number of err or s allowed when t he Inter face Device i s i n
rece pt ion mode (in T=0 protocol).
pucIccTxErrorCounterT0: Input/output parameter
S pecifies the maximum number of err or s allowed when t he Inter face Device i s i n
t r ansmi ssion mode (in T=0 protocol).
pucIccTxErrorCounterT1: Input/output parameter
S pecifies the maximum number of err or s in the T=1 protocol. The most si gnificant
nibble gives the m aximum number of R(NA) block transmissions, whil e the least
significant nibble gives the m aximum number of I or S-block ret ransm issions.
ucIccConfigurationByte: Input/output parameter
Thi s byte contains the following configuration bits:
[b0] bIccIFSDRequestT1: Input/output. Specifies if t he next I-B lock will be
p receded by an S (IFS request) (TRUE) or not (F ALSE).
[b1] bIccDeactivatedOnTimeOutErrorT1: Input/output. Specifies i f the Smar t Card
inter face is to be de-acti vated ( TRUE) on a TimeO ut error . O therwise, an error
reco very p r ocedure i s engaged.
[b2] bIccNADErrorCheckingT1: Input/output. Specifies wh ether the NAD er r or s
are to be checked ( TRUE) or not ( FALS E).
[b3] bIccABORTManagementT1: Input/output. Specifies whether the ABOR T
Request is to be managed (TRUE) or i f the cont acts are to be de-activated on
S(ABORT Request) reception (FALSE).
[b4] bIccRESYNCHManagementT1: Input/output. Specifies whether an
S(RES YNCH Request ) command is to be sent when too many error s occur
(TRUE ) or if a de-activation sequence is to be initi ated (F ALSE) .
[b5] bIccRetransmitLastBlockAfterRESYNCHT1: Input/output. Specifies whether
t he last bl ock in T=1 protocol i s to be retransmi tted aft er a r esync hronization
occur s or the whol e command. [U seful for M i crosoft IF DTESTs suite]
[b6] bIccWarningStatusBytesManagementT0: Input/output. Specifies if the IFD
must inform the appl i cati on level of whether the status bytes have been
rece i ved j ust after the command header tr ansmi ssion or aft er the co mmand
data transmi ssion (in T=0 protocol) . [Use ful for EMV Test suites]
[b7] bIccDeactivateOnIFSDNegotiationError: Input/output. Speci fi es i f the Smar t
Card interface i s to be de-activated on an IFSD negoti ation error.
Retur n Codes AR_ICC_OK Successful oper ation.
ICC_Disable()
Purpose D eacti vate the Smar t Card inter face, slot number i s specified by eIccId.
Synopsis AR_I CC_RC ICC_ Disab le ( IN enum ICC_ID eIccId );
73S12xxF Software User Guide UG_12xxF_016
84 R ev. 1.50
Parameters eIccId: Input paramet er
Specifies wh ich Smart C ar d int er face is to be acti vated. Possible values ar e:
ICC_1ST 0, (Internal)
ICC_2ND 1, ( External)
…
ICC_9TH 8 (External)
Retur n Codes AR_ICC_OK S uccessful operati on.
AR_ICC_ERR_BAD_PARAM I nvalid ICC Slot.
ICC_CheckPresence()
Purpose Retur n t he stat us of the specified ICC inter face .
Synopsis AR_ICC_RC ICC_CheckPresence ( IN en u m ICC_ID eIccId );
Parameters eIccId: In p u t p arameter.
The l ower (least signi fi cant) 4-b its specify which Smar t C ar d int er face to activate.
P ossible values are:
ICC_1ST 0, (Internal)
ICC_2ND 1, ( External)
…
ICC_9TH 8 (E xternal).
The higher (m ost significant) 4-bits specify whether the card detect polarity is high
(CARD_DET_H) or low (CA RD_DET_L). S ee add itional details at t he end of the
description of this function.
Retur n Codes AR_ICC_OK
S uccessful operati on. The Smar t car d is prese nt and activated.
AR_ICC_ERR_CARD_ABSENTNo
A Smart C ar d is pr esent in this int er face.
AR_ICC_ERR_CARD_DISCONNECTED
The Smart Card is present but not activated.
The eIccId parameter is split into two fields: C ar d Detect Polari ty and Card Slot number, by u sing the
most significant nibble and least significant nibble, respectively. Therefore, the m ost significant nibble of
the eIccId parameter i s used t o det er mi ne if the C ar d Detect Polari ty is to be configur ed Hi gh or Low.
The constants CARD_DET_H and CARD_DET_L are defined in ICCMgt.h.
Examples:
1. If C ar d Detect Pol ar i ty is to be set to High wh en a car d is inse r ted, it ca n be done so by call ing:
ICC_En able( eIccI d | CARD_DET_ H, bIccATRAutoCheck,etc.).
2. If C ar d Detect Pol ar i ty is to be set to Low when a ca r d is inser ted, it can be done so by calling:
ICC_Enable( eIccId | CARD_DET_L, bIccATRAutoCheck,etc.).
3. Calling ICC_ Enab le (eIccId, bI ccATRAut oCheck, etc.) withou t O R’ing eIccId with CA RD_DET_L or
CARD_DET_H (in other words, eIccID <= 0x09) will default t o CA RD_DET_H.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 85
4.4 Flash Programming
There ar e two ways to down load a hex file t o the 73S12xxF Flash:
1. Using a Teridian Flash Pr ogrammer Tool. Th is tool is packaged separatel y; contact a Teridian Sales
Rep r esentative for more information.
2. Using a Signum System s ADM51 ICE.
4.5 Test Tools and Certification/compliance Tests
A set of tool s is provided with the 73S 12xxF development kit t o assist the appli cati on development.
Teridian uses t hese tool s to perform various ce r tification and compl iance tests such as WHQ L (aka H CT),
USB 2.0 certifica tion, EMV Level 1 and ISO extended ca ses testing. These tools include the Smart ATR
and CCID-U SB Modules descri bed bel ow.
Smart ATR Test Tool
The Smar t ATR tool runs on a PC under Windows 98/2000/XP. This tool is helpful when used in
conjunction wit h t he EMV Tool. It reads an ATR input by the use r and tr ansl ates each byte of the ATR
per the ISO 7816 Specification.
CCID-USB Te st Tool
Thi s tool i nclud es ccidtsc-*.sys,ccidtsc-*.inf and CCID-USB.exe. Th ese modules use the USB
communication interface to interface with a PC running Windows XP.
CCID-USB. exe is a Windows XP appl i cati on used to test the PC/SC API s as specified by t he PCSC
Wor kgrou p and M icroso ft. After the ccidusb.hex file is downloaded to Flash and ccid t sc-*.sys and
ccidtsc-*.inf are loaded into a Windows XP Device Manager, any PC/SC application can be run on
Windows X P t o send co mmands to the 73S12xxFdevice. Th ese tool s are also used for H C T/ DTM an d
USB command verifi er testi ng. Th e fol l owing procedure descri bes the setup for this tool:
1. Program the Flash with ccidusb-*.hex.
2. Connect a USB cable between a PC running Windows XP and the 73S12xxF evaluation board. The
Wind ows’ ‘Hardware found wizard’ should pop up.
3. Follow the wiza r d procedure to i nstall the . sy s and . inf fil e on t o Windows. A reboot is NOT
nece ssary.
4. Inser t a smart card int o slot #1 of the evaluation board.
5. Run CCI D-USB.exe to test a command going t o the Smart Card.
A nother good test applicati on is the M icroso ft i fdtest.exe whi ch is par t of the HC T t est sui te. Run t his
program in manual mode ( i fdtest –m) to obse r ve t he 73S12xxF communica tion to the smar t card.
The sour ce co de for both appl ica tions is included in the release.
The fol l owing embedded applicati on so urce code is available, depending on the CD ROM included with
your product:
• Ccidusb-*.hex: This applicat ion uses the USB communi cati on int er face and runs any PC/SC or
CCID aware ap pli cati on to int er face wit h t he reader . Review the accompanying documentation and
source code for usa ge and implementation det ails.
• tscPccid-*.hex: This application uses the Serial/RS232 interface and runs on any PC with a generic
S er ial COM driver. R eview the accompanying documentation and source code for usage and
impl ementation det ai ls.
73S12xxF Software User Guide UG_12xxF_016
86 R ev. 1.50
4.5.1 E MV L E VE L I Certification Tests
The EMV compl iant test sui te follows the Payment System Environment specification. There ar e several
t est l abs, listed on the www.emvco.com website, qual ified to perform these tests.
Currently, there are two availabl e Protoco l test suites that can be used to qual i fy for E M V Level I
compliance. Passing ei ther of these sui tes will qualify as EMV Level I compl i ance. The Pseudo-CCID
code li nks to the two TS C libraries LAP I an d HAP I which comply with bot h tests. However, since each
lab h as its own test scripts and the test scripts differ accor ding t o the lab’s se tup, the applicati on layer
must be written and adapted specifica lly for each test lab’s requir ements. The following subsections
describe the loopback tests that are to be writ ten either on the host side or added to the TSC Pseudo-
CCID firmware.
4.5.1.1 EMV Test Mode
A n EMV t est ( or session) i s defined as a Command/R esponse pair that r uns from the Activation of t he
car d t o the D eacti vat ion of the card. A Bl ock Transfer may or may not occur during the session
depending on the car d’s ATR response.
The host may set up the EMV PSE t est environment via the USB CCID Car d Cont r ol command ( Escape
command) . The fir st par ameter byte ( B1) of the Escape command must specifically indicate whether a
t est mode i s i nvoked and if so , it should be invoked using the MCI, VISA I or VIS A II test environ ment.
Review the Escape co mmand section for detai ls about this test mode.
Following a su ccessful Escape command , t he host should start the test by sending the PowerOn
command (ScardConnect). Depending on the status of the A TR (good or bad), the host should send an
empt y Block Transfer command without the APDU command (comm and length = 0). For example: 6F
00 00 00 00… CRC.
The test loopback will be handled by the firmware and upon completion of each test, the firmware will
respond to the host with the status, indicating whether the t est session compl eted with a successful
retur n code or not. A n unsuccessful return code m ay or may not indicate that the test failed. The test
result (test passed or test failed) i s determ ined only by the card side.
Figure 11 depicts the minimal coding required on the host side to invoke the EMV PSE test environment.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 87
Initialization
Get Delay Time
(in Secs)
Power-Up Ok
(Good ATR)?
Start Test by sending a
Block Transfer (0x6F)
with 0 Lenth data
EMV Power
Down
Single Shot
Select Single-Shot or
Loopback test?
Delay Time Wait
EMV Power Up
Yes
SingleShot?Yes
No
No
No
No
Escape command is sent
with B1 = MCI(10) or
VISA I (20) or VISA II
(40) in EMVmode
Setup EMV Test
Mode
LoopBack
Figure 11: EMV PSE Test Flow Chart
4.5.1.2 MasterCar d Loopbac k Test
Teridian used the CETECOM test lab in Ger many and the FIME test lab i n Fr ance (both listed on the
www.emvco.com website) for Master C ar d Loopback verifi cati on. These labs used the MCI test suite for
t heir EMV Level I qualification test services.
Figure 12 and Figure 13 show the flow of the entir e M CI test suite with the coding to be done on both the
host side (invokes t he test) and the device side (manages al l aspect of the smart card’s EMV test).
These test flows are specific to both the FIM E and the Cetecom’s Level I Pr otocol test scri pts. Source
code is also incl uded in the release.
73S12xxF Software User Guide UG_12xxF_016
88 R ev. 1.50
Initialization
EMV Power Up
Power-Up Ok
(Good ATR)?
Select File
1PAY.SYS.DDF01
EMV Power
Down
Yes
Warm Res et OK?
No
Yes
No
APDU Exchange
R-APDU < 6
bytes?
Yes
Yes
Wait 5 seconds
Exchange OK?
Yes
No
INS='70'?No
No
Extrac Next C-A PDU
from R-APDU
No
Negotiable
Mode? PPS OK?Yes
No
No
Yes
Figure 12: MCI Te st Flow Char t wit h PTS/ PPS
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 89
Initialization
EMV Power Up
Power-Up Ok
(Good ATR)?
Select File
1PAY.SYS.DDF01
EMV Power
Down
Yes
Warm Reset OK?
No
Yes
No
APDU Exchange
R-APDU < 6
bytes?
Yes Yes
Wait 5 s econds
Exchange OK?
Yes
No
INS='70'?
No
No
Extrac Next C-A P DU
from R-APDU
No
Figure 13: MCI Te st Flow Char t wit hou t PTS/PPS
73S12xxF Software User Guide UG_12xxF_016
90 R ev. 1.50
4.5.1.3 VISA-1 Loopback Test
Teridian used the RF I G l obal test l ab in the UK (listed on the www.emvco.com website) for VISA-1
testing. This lab used the VIS A test suite for t heir EMV Level I qualification test services. Figure 14
shows t he VISA-1 t est flow which is specific to RFI’s test scripts. Source code for this test is also
included in the release.
Initialization
Enter Delay Time
(in Secs)
Power-Up Ok
(Good ATR)?
SELECT FILE
1PAY.SYS.DDF01
EMV Power
Down
M/m
Any other Key
Warm Reset O K ?
Yes
No
APDU Exchange
No
Exchange OK?
End of Record?
or No Record?
Enter (M/m) Multi-
or (anykey) Single
Shot?
Delay Time Wai t
EMV Power Up
Negotiable Mode?
No
PPS OK?Yes
SingleShot?Yes
No
No
Yes
No
Yes
READ RECORD
(00 B2 'P1' 0C 00)
Yes
P1 = 01
Increm ent RECORD
Index (P1)
Yes
No Exchange OK?
Yes
No
Figure 14: VISA-1 Loopba ck Te st Flow Char t
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 91
4.5.2 VISA-2 Loopb ack Test
Teridian used th e ICT-K test l ab in Korea (li sted on the www.emvco.com website) for VISA-2 loopback
testing. This lab used the V ISA test suite version 4 .1 for their EMV Level I qualification test service s
(details shown in Figure 15). The USB CCID firmware includes the so urce co de t hat impl ement s this
test.
Initialization
Enter Delay Time
(in Secs)
Power-Up Ok
(Good ATR)?
SELECT FILE
1PAY.SYS.DDF01
EMV Power
Down
M/m
Any other Key
W arm Reset OK?
Yes
No
No
Exchange OK?
End of Record?
or No Record?
Enter (M/m) Multi-
or (anykey) Single
Shot?
Delay Time Wai t
EMV Power Up
Negotiable Mode?
No
PPS OK?
Yes
SingleShot?
Yes
No
No
Yes
No
Yes
READ RECORD
(00 B2 'P1' 0C 00)
Yes
P1 = 01
Increm ent RECORD
Index (P1)
Yes
No Exchange OK?
No
T-AID Present T-Select AID Command
Yes
Yes
Exchange OK?
No
Yes
No
T-Book1 - 12.4 S t ep 1
T - 00A404000CA00000000310100000000001
Figure 15: VISA-2 Loopba ck Te st Flow Char t
73S12xxF Software User Guide UG_12xxF_016
92 R ev. 1.50
5 Related Documentation
The following 73S12xxF documents are avail able from Teridi an Semico nductor Corporation:
73S1209F Data Sheet
73S1210F Data Sheet
73S1215F Data Sheet
73S1217F Data Sheet
73S12xxF FPGA Evaluation Board User’s Manual
Pseudo-CCID Host GUI Use rs Guid e
Pseudo-CCID Host Applicat ion Gu ide
Pseudo-CCID Serial/ RS232 F irmware Applicat ion Note
USB-CCID-Host GUI Users Guide
CCID Application No te
6 Contact Information
For more informati on about Teridian Semico nductor products or to check the availabi lity of t he 73S12xxF,
cont act us at:
6440 Oak Canyon Road
Suite 100
Irvine, CA 92618-5201
Telephone: (714) 508-8800
FAX: (714) 508-8878
Email: scr.support@teridian.com
For a compl ete list of worldwide sales office s, go t o http://www.teridian.com.
UG_12xxF_016 73S12xxF Software User Guide
R ev. 1.50 93
Revision His tory
Date Revision Description
12/12/2005 0.01 Prel iminar y versi on
11/20/2006 0.80 Updated with the latest change since the last build. This version is still
consider ed a Beta rel ease.
3/1/2007 1.00 First production build. Includes modules that passed HCT/Microsoft
WHQL, EMV Level I, USB.ORG’s comm and verifier and gol dtree testi ng.
3/19/2009 1.30 1. Updat ed t o r efl ect the latest HAPI err or r eturn codes.
2. Added a new API (ICC_Configure_Ext) to the HAPI library to support:
a. Setting D i fferent S mart Card clock frequencies for both i nternal and
external slots. R eview this docum ent carefully before i mpl ement i ng
t his feat ure.
b. Enable/disable Pull-up with options to turn card debounce On/Off.
c. Enable/disable Pull-down with options to turn card debounce
On/Off.
4/27/2009 1.40 Added Linux driver for USB_CCID information and Linux Application for
USB DF U Interface i nformat i on.
A dded E M V Level 1 protoco l layer informat i on.
Added Section 2.2.6, Build Environm ent with the USB Boot Loader.
9/14/2009 1.50 Modified the code sam ple on pages 44 to 48.
Modi fi ed t he code sample on pages 51 and 52.
