The Smart Card Detective (SCD)
Defines | Functions
scd_hal.h File Reference

scd_hal.h - SCD hardware abstraction layer header file for AT90USB1287 More...

Go to the source code of this file.

Defines

#define ICC_CLK_MODE   0
#define ETU_TERMINAL   372
#define ETU_HALF(X)   ((unsigned int) ((X)/2))
#define ETU_LESS_THAN_HALF(X)   ((unsigned int) ((X)*0.46))
#define ETU_EXTENDED(X)   ((unsigned int) ((X)*1.075))
#define ICC_VCC_DELAY_US   50
#define PULL_UP_HIZ_ICC   1
#define F_CPU   16000000UL
#define MAX_WAIT_TERMINAL   (1 * F_CPU)
#define ICC_CLK_OCR0A   1
#define ICC_CLK_TCCR1B   0x09
#define ETU_ICC   1488
#define ICC_RST_WAIT   50000

Functions

uint32_t GetCounter ()
 Retrieves the value of the sync counter.
void SetCounter ()
 Sets the value of the sync counter to the given value.
void ResetCounter ()
 Resets to 0 the value of the sync counter.
void EnableWDT (uint16_t ms)
 Enables the Watch Dog Timer.
void DisableWDT ()
 Disables the Watch Dog Timer.
void ResetWDT ()
 Resets the Watch Dog Timer.
void EnableTerminalResetInterrupt ()
 Enable the terminal reset interrupt.
void DisableTerminalResetInterrupt ()
 Disable the terminal reset interrupt.
uint16_t GetTerminalFreq ()
 Returns the frequency of the terminal clock in khz, zero if there is no clock.
uint16_t IsTerminalClock ()
 Checks if we have terminal clock or not.
uint8_t GetTerminalIOLine ()
 Returns the status of the terminal I/O line.
uint8_t GetTerminalResetLine ()
 Retrieves the state of the reset line from the terminal.
uint8_t WaitTerminalResetIOLow (uint32_t max_wait)
 Loops until the IO or reset line from the terminal become low.
uint8_t ReadTimerT2 ()
 Reads the value of the timer T2.
void StartTimerT2 ()
 Starts the T2 timer.
void StopTimerT2 ()
 Stops the T2 timer.
void IncrementCounter ()
 Increments the sync counter.
uint16_t ReadCounterTerminal ()
 Reads the value of the terminal counter.
void StartCounterTerminal ()
 Starts the counter for the external clock given by the terminal.
void StopCounterTerminal ()
 Stops the terminal clock counter.
void PauseCounterTerminal ()
 Pauses the terminal clock counter.
uint8_t SendByteTerminalParity (uint8_t byte, uint8_t inverse_convention)
 Sends a byte to the terminal with parity check.
void SendByteTerminalNoParity (uint8_t byte, uint8_t inverse_convention)
 Sends a byte to the terminal without parity check.
uint8_t GetByteTerminalParity (uint8_t inverse_convention, uint8_t *r_byte, uint32_t max_wait)
 Receives a byte from the terminal with parity check.
uint8_t GetByteTerminalNoParity (uint8_t inverse_convention, uint8_t *r_byte, uint32_t max_wait)
 Receives a byte from the terminal without parity check.
void LoopTerminalETU (uint8_t nEtus)
 Waits (loops) for a number of nEtus based on the Terminal clock.
uint8_t IsICCInserted ()
 Returns non-zero if ICC is inserted, zero otherwise.
uint8_t IsICCPowered ()
 Returns non-zero if ICC is powered up.
uint8_t PowerUpIcc ()
 Powers up the card, if possible.
void PowerDownICC ()
 Powers down the ICC.
void LoopICCETU (uint8_t nEtus)
 Waits (loops) for a number of nEtus based on the ICC clock.
uint8_t WaitForICCData (uint32_t max_cycles)
 Loops for max_cycles or until the I/O line from ICC becomes low.
uint8_t GetByteICCNoParity (uint8_t inverse_convention, uint8_t *r_byte)
 Receives a byte from the ICC without parity checking.
uint8_t GetByteICCParity (uint8_t inverse_convention, uint8_t *r_byte)
 Receives a byte from the ICC with parity checking.
void SendByteICCNoParity (uint8_t byte, uint8_t inverse_convention)
 Sends a byte to the ICC without parity check.
uint8_t SendByteICCParity (uint8_t byte, uint8_t inverse_convention)
 Sends a byte to the ICC with parity check.
void SetICCResetLine (uint8_t high)
 Sets the reset line of the ICC to the desired value.
uint8_t ActivateICC (uint8_t warm)
 Starts the activation sequence for the ICC.
void DeactivateICC ()
 Starts the deactivation sequence for the ICC.
void EnableICCInsertInterrupt ()
 Enable the ICC insert interrupt.
void DisableICCInsertInterrupt ()
 Disable the ICC insert interrupt.

Detailed Description

scd_hal.h - SCD hardware abstraction layer header file for AT90USB1287

This file provides an abstract definition for all micro-controller dependent functions that are used in the Smartcard Defender

For each microcontroller a different scd_hal.c source file should be used.

Copyright (C) 2012 Omar Choudary (omar.choudary@cl.cam.ac.uk)

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Definition in file scd_hal.h.


Define Documentation

#define ETU_EXTENDED (   X)    ((unsigned int) ((X)*1.075))

Definition at line 51 of file scd_hal.h.

#define ETU_HALF (   X)    ((unsigned int) ((X)/2))

Definition at line 49 of file scd_hal.h.

#define ETU_ICC   1488

Definition at line 62 of file scd_hal.h.

#define ETU_LESS_THAN_HALF (   X)    ((unsigned int) ((X)*0.46))

Definition at line 50 of file scd_hal.h.

#define ETU_TERMINAL   372

Definition at line 48 of file scd_hal.h.

#define F_CPU   16000000UL

Definition at line 55 of file scd_hal.h.

#define ICC_CLK_MODE   0

Definition at line 41 of file scd_hal.h.

#define ICC_CLK_OCR0A   1

Definition at line 60 of file scd_hal.h.

#define ICC_CLK_TCCR1B   0x09

Definition at line 61 of file scd_hal.h.

#define ICC_RST_WAIT   50000

Definition at line 63 of file scd_hal.h.

#define ICC_VCC_DELAY_US   50

Definition at line 52 of file scd_hal.h.

#define MAX_WAIT_TERMINAL   (1 * F_CPU)

Definition at line 56 of file scd_hal.h.

#define PULL_UP_HIZ_ICC   1

Definition at line 53 of file scd_hal.h.


Function Documentation

uint8_t ActivateICC ( uint8_t  warm)

Starts the activation sequence for the ICC.

Starts the activation sequence for the ICC

Parameters:
warmif warm=1 it specifies a warm reset activation, cold reset otherwise *
Returns:
0 if successful, non-zero otherwise

Definition at line 1200 of file scd_hal.c.

void DeactivateICC ( )

Starts the deactivation sequence for the ICC.

Starts the deactivation sequence for the ICC

Definition at line 1267 of file scd_hal.c.

Disable the ICC insert interrupt.

Disable the ICC insert interrupt

Definition at line 1307 of file scd_hal.c.

Disable the terminal reset interrupt.

Disable the terminal reset interrupt. This interrupt should fire when the terminal reset line goes low (0).

Definition at line 76 of file scd_hal.c.

void DisableWDT ( )

Disables the Watch Dog Timer.

Disable the Watch Dog Timer and the WDT interrupt

Definition at line 144 of file scd_hal.c.

Enable the ICC insert interrupt.

Enable the ICC insert interrupt on any edge trigger

Definition at line 1297 of file scd_hal.c.

Enable the terminal reset interrupt.

Enable the terminal reset interrupt. This interrupt should fire when the terminal reset line goes low (0).

Enable INT0 on falling edge. This is the recommended procedure, as in the data sheet. First disable the interrupt, then change the mode, then clear the interrupt flag and finally enable the interrupt

Definition at line 63 of file scd_hal.c.

void EnableWDT ( uint16_t  ms)

Enables the Watch Dog Timer.

Enable the Watch Dog Timer. This function will also enable the WDT interrupt.

Parameters:
msthe number of miliseconds to wait. This is an estimate since each hardware platform might provide just a limited set of possible values. For the AT90USB1287 (this uC) the possible values are 15ms, 30ms, 60ms, 120ms, 250 ms, 500 ms, 1s, 2s, 4s and 8s. Therefore this function simply approximates the closest larger value. For example sending a value of 14 will actually use 15ms, sending 25 will use 30ms, sending 100 will use 120ms and sending 1000 will use 1s.

Definition at line 115 of file scd_hal.c.

uint8_t GetByteICCNoParity ( uint8_t  inverse_convention,
uint8_t *  r_byte 
)

Receives a byte from the ICC without parity checking.

Receives a byte from the ICC without parity checking

Parameters:
inverse_conventiondifferent than 0 if inverse convention is to be used *
r_bytecontains the byte read on return
Returns:
zero if read was successful, non-zero otherwise

ICC clock counter must be already enabled

Definition at line 911 of file scd_hal.c.

uint8_t GetByteICCParity ( uint8_t  inverse_convention,
uint8_t *  r_byte 
)

Receives a byte from the ICC with parity checking.

Receives a byte from the ICC with parity checking

Parameters:
inverse_conventiondifferent than 0 if inverse convention is to be used *
r_bytecontains the byte read on return
Returns:
zero if read was successful, non-zero otherwise

ICC clock counter must be already enabled

Definition at line 999 of file scd_hal.c.

uint8_t GetByteTerminalNoParity ( uint8_t  inverse_convention,
uint8_t *  r_byte,
uint32_t  max_wait 
)

Receives a byte from the terminal without parity check.

Receives a byte from the terminal without parity checking. This function also checks if the terminal reset line is low.

Parameters:
inverse_conventiondifferent than 0 if inverse convention is to be used
r_bytecontains the byte read on return
max_waitthe maximum number of cycles to wait for the reset or the IO line to become low. Give 0 to wait indefinitely.
Returns:
zero if read was successful, RET_TERMINAL_RESET_LOW if the terminal reset line was low while waiting, RET_TERMINAL_TIME_OUT if we did not get any signal within the specified max_wait period, or RET_ERROR otherwise

Terminal clock counter must be already enabled

Definition at line 640 of file scd_hal.c.

uint8_t GetByteTerminalParity ( uint8_t  inverse_convention,
uint8_t *  r_byte,
uint32_t  max_wait 
)

Receives a byte from the terminal with parity check.

Receives a byte from the terminal with parity checking

Parameters:
inverse_conventiondifferent than 0 if inverse convention is to be used
r_bytecontains the byte read on return
max_waitthe maximum number of cycles to wait for the reset or the IO line to become low. Give 0 to wait indefinitely.
Returns:
zero if read was successful, RET_TERMINAL_RESET_LOW if the terminal reset line was low while waiting, RET_TERMINAL_TIME_OUT if we did not get any signal within the specified max_wait period, or RET_ERROR otherwise

Terminal clock counter must be enabled before calling this function

Definition at line 755 of file scd_hal.c.

uint32_t GetCounter ( )

Retrieves the value of the sync counter.

uint16_t GetTerminalFreq ( )

Returns the frequency of the terminal clock in khz, zero if there is no clock.

Returns:
the frequency of the terminal clock in khz, zero if there is no clock

Assumes the terminal counter is already started (Timer 3)

Definition at line 232 of file scd_hal.c.

uint8_t GetTerminalIOLine ( )

Returns the status of the terminal I/O line.

Get the status of the terminal I/O line

Returns:
1 if the line is high or 0 if low.

Assumes the terminal counter is already started (Timer 3)

Definition at line 88 of file scd_hal.c.

uint8_t GetTerminalResetLine ( )

Retrieves the state of the reset line from the terminal.

Retrieves the state of the reset line from the terminal

Returns:
0 if reset is low, non-zero otherwise

Definition at line 98 of file scd_hal.c.

void IncrementCounter ( )

Increments the sync counter.

uint8_t IsICCInserted ( )

Returns non-zero if ICC is inserted, zero otherwise.

SCD to ICC functions

Returns non-zero if ICC is inserted, zero otherwise

Definition at line 808 of file scd_hal.c.

uint8_t IsICCPowered ( )

Returns non-zero if ICC is powered up.

Returns non-zero if ICC is powered up

Definition at line 821 of file scd_hal.c.

uint16_t IsTerminalClock ( )

Checks if we have terminal clock or not.

Returns:
non-zero if we have some terminal clock, zero otherwise.

Assumes the terminal counter is already started (Timer 3)

Definition at line 191 of file scd_hal.c.

void LoopICCETU ( uint8_t  nEtus)

Waits (loops) for a number of nEtus based on the ICC clock.

Waits (loops) for a number of nEtus based on the ICC clock

Parameters:
nEtusthe number of ETUs to loop

Assumes the ICC clock counter is already started

Definition at line 859 of file scd_hal.c.

void LoopTerminalETU ( uint8_t  nEtus)

Waits (loops) for a number of nEtus based on the Terminal clock.

Waits (loops) for a number of nEtus based on the Terminal clock

Parameters:
nEtusthe number of ETUs to loop

Assumes the terminal clock counter is already started

Definition at line 440 of file scd_hal.c.

Pauses the terminal clock counter.

Pauses the terminal clock counter

Definition at line 428 of file scd_hal.c.

void PowerDownICC ( )

Powers down the ICC.

Powers down the ICC

Definition at line 845 of file scd_hal.c.

uint8_t PowerUpIcc ( )

Powers up the card, if possible.

uint16_t ReadCounterTerminal ( )

Reads the value of the terminal counter.

This method increments the synchronization counter. The sync counter can be used as a synchronization mechanism. It is a 32-bit value, which should be updated regularly, e.g. by the timer T2.

See also:
ReadTimerT2 This method returns the value of the sync counter.
Returns:
the value of the sync counter
See also:
IncrementCounter This method resets to 0 the value of the sync counter.
IncrementCounter
Returns:
the value of the terminal counter

Definition at line 380 of file scd_hal.c.

uint8_t ReadTimerT2 ( )

Reads the value of the timer T2.

The timer T2 can be used for event management. It is an 8-bit counter.

Returns:
the value of the timer T2
See also:
StartTimerT2

Definition at line 309 of file scd_hal.c.

void ResetCounter ( )

Resets to 0 the value of the sync counter.

void ResetWDT ( )

Resets the Watch Dog Timer.

Reset the Watch Dog Timer

Definition at line 153 of file scd_hal.c.

void SendByteICCNoParity ( uint8_t  byte,
uint8_t  inverse_convention 
)

Sends a byte to the ICC without parity check.

Sends a byte to the ICC without parity error retransmission

Parameters:
bytebyte to be sent
inverse_conventiondifferent than 0 if inverse convention is to be used

The ICC clock counter must be started before calling this function

Definition at line 1048 of file scd_hal.c.

uint8_t SendByteICCParity ( uint8_t  byte,
uint8_t  inverse_convention 
)

Sends a byte to the ICC with parity check.

Sends a byte to the ICC with parity error retransmission

Parameters:
bytebyte to be sent
inverse_conventiondifferent than 0 if inverse convention is to be used
Returns:
0 if successful, non-zero otherwise

As in the No Parity version, this function relies on counter started

Definition at line 1139 of file scd_hal.c.

void SendByteTerminalNoParity ( uint8_t  byte,
uint8_t  inverse_convention 
)

Sends a byte to the terminal without parity check.

Sends a byte to the terminal without parity error retransmission

Parameters:
bytebyte to be sent
inverse_conventiondifferent than 0 if inverse convention is to be used

The terminal clock counter must be started before calling this function

Definition at line 466 of file scd_hal.c.

uint8_t SendByteTerminalParity ( uint8_t  byte,
uint8_t  inverse_convention 
)

Sends a byte to the terminal with parity check.

Sends a byte to the terminal with parity error retransmission

Parameters:
bytebyte to be sent
inverse_conventiondifferent than 0 if inverse convention is to be used
Returns:
0 if successful, non-zero otherwise

As in the NoParity version, this function relies on counter started

Definition at line 560 of file scd_hal.c.

void SetCounter ( )

Sets the value of the sync counter to the given value.

void SetICCResetLine ( uint8_t  high)

Sets the reset line of the ICC to the desired value.

Sets the reset line of the ICC to the desired value

Parameters:
highsend 0 to put the reset line to low (0), or non-zero to put the reset line to high (1)

Definition at line 1185 of file scd_hal.c.

Starts the counter for the external clock given by the terminal.

Starts the counter for the external clock given by the terminal

From hardware tests it seems that it is better to just leave the counter running all the time and just modify the register values as needed

Definition at line 404 of file scd_hal.c.

void StartTimerT2 ( )

Starts the T2 timer.

Starts the timer T2 using the internal clock CLK_IO. The current setup is for an interrupt frequency f_t2_int = 976.5625 Hz. That means that each value of the udpated counter represents 1.024 ms.

See also:
ReadTimerT2

Definition at line 322 of file scd_hal.c.

Stops the terminal clock counter.

Stops the terminal clock counter

Definition at line 419 of file scd_hal.c.

void StopTimerT2 ( )

Stops the T2 timer.

Stops the timer T2

Definition at line 336 of file scd_hal.c.

uint8_t WaitForICCData ( uint32_t  max_cycles)

Loops for max_cycles or until the I/O line from ICC becomes low.

Loops until the I/O line from ICC becomes low

Parameters:
max_cyclesthe maximum number of clocks to wait for the I/O line to become low. Loops forever if this is 0
Returns:
0 if the I/O line is 0, non-zero otherwise

Definition at line 882 of file scd_hal.c.

uint8_t WaitTerminalResetIOLow ( uint32_t  max_wait)

Loops until the IO or reset line from the terminal become low.

Loops until the IO or reset line from the terminal become low.

Parameters:
max_waitthe maximum number of cycles to wait for the reset or the IO line to become low. Give 0 to wait indefinitely.
Returns:
1 if reset is low, 2 if the I/O is low, or 3 if both lines are low. In case the maximum number of wait cycles has elapsed then this function returns 0.

Definition at line 167 of file scd_hal.c.

 All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines