Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Qwantum ASIC Application Layer Functions

This section describes the Qwantum ASIC application layer functions, structures and variables used in the reference code.

Card Data Related Structures and Variables

A structure variable called CDM_Common1 defined at the application layer gets track data, Qwantum Token and Qwantum ASIC Status from the command layer functions. The track data and Qwantum Token come from the tracks of the swiped card and the Qwantum ASIC status bits are collected individually from the Status 1 register (address = 0x02), Configuration register (address = 0x00) and ASIC Revision Code register (address = 0x10). The Qwantum ASIC status is constructed from the hardware register bits while it comes from the ASIC in the data strobe mode. Thus, the format of the Qwantum ASIC status follows the definition of the Qwantum ASIC status bits for the data strobe mode.

ryubFmtBfr[MSR_TK_CNT][MSR_FMT_BFR_LEN]

  • Track data from the command layer function is stored in this variable.

rycubFmtLen[MSR_TK_CNT]

  • This variable can be initialized with MSR_FMT_BFR_LEN. It is not determined by the command layer function.

ryubQwantumTokenBfr[MSR_EXT_MAGNEPRINT_DATA_LEN]

  • Qwantum Token from the command layer function is stored in this variable.

ryubQwantumAsicStatusBfr[MSR_MAGNEPRINT_STATUS_LEN]

  • Qwantum ASIC Status from the command layer function is stored in this variable.

/* Length of a track in bits */ 
#define MSR_ASIC_TK_LEN_IN_BITS	704

/* Length of a track in bytes including leading/trailing bits */
/* The leading & trailing bits are ignored in SPI mode */ 
#define MSR_FMT_BFR_LEN ((MSR_ASIC_TK_LEN_IN_BITS / 8) + 4)

/* Track count and Track ID */ #define MSR_TK_CNT	3
#define MSR_TK1	0
#define MSR_TK2	1
#define MSR_TK3	2

/* Standard QwantumToken Mode support */ 
#define MSR_QWANTUM_TOKEN_LEN_IN_BITS 432
#define MSR_QWANTUM_TOKEN_DATA_LEN	(MSR_ QWANTUM_TOKEN_LEN_IN_BITS
/ 8)
#define MSR_QWANTUM_TOKEN_LEN_MAX	128
#define MSR_QT_BLOCKS	((MSR_ QWANTUM_TOKEN_LEN + 7) 
/ 8)

/* Extended Qwantum Token Mode support */ 
#define MSR_EXT_QWANTUM_TOKEN_LEN_IN_BITS 1584
#define MSR_EXT_QWANTUM_TOKEN_LEN	(MSR_EXT_ QWANTUM_TOKEN_LEN_IN_BITS 
/ 8)
##define MSR_EXT_QWANTUM_TOKEN_LEN_MAX	255
#define MSR_EXT_QT_BLOCKS	((MSR_EXT_QWANTUM_TOKEN_LEN + 7) 
/ 8)

/* Qwantum ASIC Status */
#define MSR_QWANTUM_ASIC_STATUS_LEN_IN_BITS 32 
#define MSR_QWANTUM_ASIC_STATUS_LEN
(MSR_QWANTUM_ASIC_STATUS_LEN_IN_BITS / 8 )

/* Card data buffer structure */ 
typedef struct
{
ubyte ryubFmtBfr[MSR_TK_CNT][MSR_FMT_BFR_LEN]; ubyte rycubFmtLen[MSR_TK_CNT];
ubyte ryubQwantumTokenBfr[MSR_EXT_QWANTUM_TOKEN_LEN];
ubyte ryubQwantumAsicStatusBfr[MSR_QWANTUM_ASIC_STATUS_LEN];
} MSR_COMMON;

/* Structure definition that contains MSR data */ typedef struct
{
    MSR_COMMON MSR_Common1;
} CDM_COMMON1;

/* Global variable that contains track data, Qwantum Token and Qwantum Status */
CDM_COMMIN1 CDM_Common1;

ASIC Feature and Configuration related Equates and Variables

The reference code uses two variables to configure the ASIC: cfg_qwantum_asic and QASIC_testFeat. The configuration variable, cfg_qwantum_asic is updated based on the QASIC_testFeat settings and its content is written to the Configuration register after the ASIC is paired with the microcontroller.

QASIC_Init

This function configures the ASIC based on two variables and is invoked by SPI_APP_init after the host SPI interface is initialized and configured.

  • cfg_qwantum_asic – a static variable used to configure the ASIC. This is the value written in the Configuration register. This variable gets the value from QASIC_config first and then updated based on bit settings in QASIC_testFeat and QASIC_qtFlags.

  • QASIC_config – a variable that contains the default ASIC configuration settings from a non-volatile storage.

  • QASIC_testFeat – a variable that contains the use of the application-level feature such as Operation Mode, Type of Track Read Command, IRQ, Qwantum Obfuscation.

  • QASIC_qtFlags – a variable that contains the Qwantum Token Enable/Disable and Qwantum Token Mode information.

  • mtqasic.h, mtqasic.c

QASIC_reset

This function invokes another routine that sends the Reset command to the ASIC.

QASIC_check_card_data_available

The ASIC is in the ATR state while waiting for a card swipe. It enters the EXTRACT state when a card is swiped, and the card data is ready to be transferred to the host microcontroller.

This function checks if the card data is available in the buffer only when the interrupt feature is disabled and returns TRUE if the data is available. This function is supposed to be used in the non-interrupt case and meant to be called from the main loop.

The interrupt version of this function is QASIC_check_card_data_available_irq.

QASIC_get_ready_for_swipe

This function changes the state of the ASIC to the ATR state for the next card swipe. It is called from QASIC_get_card_data and QASIC_get_card_data_alt after finishing reading the card data from the ASIC. A 400us delay is added after the command to change the state to ATR is issued to the ASIC to make sure the state transition is complete. Another way to confirm the state transition can be done by checking FSM_STATE_STATUS[3:0] in the Status 1 register.

The IRQN_ACK bit in the Acknowledge register doesn’t need to be cleared since it is automatically cleared by the read track commands.

QASIC_finish_read

This is the top-level function that is invoked when the card data becomes available in the ASIC. This function calls either QASIC_get_card_data or QASIC_get_card_data_alt based on the type of the track read command to be used.

The function, QASIC_get_card_data uses the RTKABCQT command while QASIC_get_card_data_alt uses the three separate commands, RTKA, RTKBQT, RTKC to read the card data.

QASIC_get_card_data

This function outputs the card data listed below in the buffer from the caller.

  • 32-bit ASIC Status Bits

  • Track A/B/C data

  • Qwantum Token (Q.T. Status | Q.T. Data | CRC)

The RTKABCQT command is used to read the current card data (Track A, B, C and Qwantum Token) from the ASIC and stores all in tkabcmp_data first and then splits them in the buffer from the caller. It also calls qasic_read_status, to get the 32-bit ASIC Status Bits and constructs the 4-byte Qwantum Token Status.

QASIC_get_card_data_alt

This function performs the same task as QASIC_get_card_data, but it uses the other three commands: RTKA, RTKBQT and RTKC instead. The track A and C are read only if they are enabled in the ASIC while the track B and Qwantum Token are read all the time.

It may take less time to collect all data from the ASIC using this function than QASIC_get_card_data if any one of Track A and C is disabled. Otherwise, there is no difference between the two.

QASIC_isr

This function is the interrupt service routine for the Qwantum ASIC SPI. The reference code uses a feature configuration variable, QASIC_testFeat, to check if the Qwantum ASIC SPI interrupt is enabled before performing the required tasks. Checking the interrupt enable configuration bit is not required in the product application and can be removed.

If other IP blocks within the microcontroller need to be resumed from a power-down state or any special tasks need to be performed before the card data becomes available in the ASIC, the CP interrupt can be utilized for this purpose. In this case a CP interrupt is generated followed by a Card Data Available (Ready) interrupt for each card swipe.

The ISR in the reference code sets flags (cpIntFlag and/or cdaIntFlag) based on the feature settings and the current ASIC state to determine which interrupt occurred between the two. The card swipe service function, MAI_serviceCardSwipe, performs the card data read based on cdaFlag or cdaIntFlag.

QASIC_check_card_data_available_irq

The role of this function is like QASIC_check_card_data_available. Instead of checking the ASIC state, it returns the Card Data Available interrupt flag, cdaIntFlag, which is set in the ISR, to the caller to indicate the card data is available in the ASIC.

QASIC_clear_card_data_available_irq

This function clears the Card Data Available interrupt flag, cdaIntFlag.

QASIC_check_card_present_irq

The function returns the Card Present interrupt flag, cpIntFlag, which is set in the ISR, to the caller to indicate the Card Present interrupt occurred.

The ISR in the reference code doesn’t do anything special besides incrementing the CP interrupt counter when this interrupt occurs. If the product application needs to perform special tasks before the card data becomes available in the ASIC it can be done inside the ISR or in another routine by calling this function.

QASIC_clear_card_present_irq

This function clears the Card Present interrupt flag, cpIntFlag.

Last updated