# 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. 
/* Qwantum ASIC configuration info */
/*
Cfg# TrkA TrkB TrkC QT  QT Mode Obfuscation IRQ      Cfg reg	    QT Rev
1	    On	On	    On	  On	 Std	    Off	    Off	    0x4500	    0x04
2	    On	On	    On	  On	 Std	    On	    Off	    0x4400	    0x06
3	    On	On	    On	  On	 Ext	    Off	    Off	    0x0500	    0x05
4	    On	On	    On	  On	 Ext	    On	    Off	    0x0400	    0x07
5	    On	On	    On	  Off  Std	    Off	    Off	    0xC500	    0x00
6	    On	On	    On	  Off	 Std	    On	    Off	    0xC400	    0x00
7	    On	On	    On	  Off	 Ext	    Off	    Off	    0x8500	    0x00
8     On  On      On    Off   Ext     On      Off     0x8400      0x00
*/

/* Configuration register Address (0x00) and Bit definitions for cfg_qwantum_asic */
    #define QTM_CFG_REG	0x0000
    #define QTM_CFG_QT_DIS_MASK  0x8000 // QT Disable (0=en, 1=dis)

#define QTM_CFG_QTEM_DIS_MASK 0x4000 // QT Ext Mode Disable (0=en, 1=dis)
#define QTM_CFG_TKA_DIS_MASK 0x2000 // Track A Disable (0=en, 1=dis) #define QTM_CFG_TKC_DIS_MASK 0x0800 // Track C Disable (0=en, 1=dis) #define QTM_CFG_CPIRQ_DIS_MASK 0x0400 // Card Present IRQ Disable
(0=en, 1=dis)
#define QTM_CFG_OBFALG_DIS_MASK 0x0100 // Obfuscation Algorithm Disable (0=en, 1=dis)

/* Variable used for Qwantum ASIC configuration */

static unsigned short cfg_qwantum_asic = (QTM_CFG_QTEM_DIS_MASK | 
QTM_CFG_CPIRQ_DIS_MASK | QTM_CFG_OBFALG_DIS_MASK);

/* Bit Definitions for QASIC_testFeat */

// QASIC operation mode: 0=Datastrobe mode; 1=SPI mode 
#define QASIC_TESTFEAT_OP_MODE_MASK	(1 << 0) 
#define QASIC_TESTFEAT_OP_MODE_SPI	0x01

// Data read command type: 0=RTKA/RTKBQT/RTKC; 1=RTKABCQT 
#define QASIC_TESTFEAT_RDCMD_ABCQT_MASK (1 << 1)
// Card Data Available Interrupt: 0=CDA Int disabled; 1=CDA Int enabled
#define QASIC_TESTFEAT_MISO_IRQ_TEST_MASK	(1 << 2)
#define QASIC_TESTFEAT_MISO_IRQ_TEST_SHIFT	2 
#define QASIC_TESTFEAT_MISO_IRQ_TEST_ENABLE 0x04
/* This option is to test if QA's MISO signal can generate an interrupt
    * correctly. The MISO pin is connected to PTA17 pin on uC. PTA17 is
    * configured as GPIO with falling edge interrupt when uC doesn't need
    * to access QA. The ISR sets a flag to indicate there is a set of card
    * data to read. The main loop polls this flag and reads the card data
    * of the flag is set.
    */
    
// Card Present Interrupt: 0=CP Int enabled; 1=CP Int disabled
#define QASIC_TESTFEAT_CP_IRQ_TEST_MASK    (1 << 3)
#define QASIC_TESTFEAT_CP_IRQ_TEST_SHIFT     3
#define QASIC_TESTFEAT_CP_IRQ_TEST_ENABLE    0x08

// Obfuscation: 0=enabled; 1=disabled 
#define QASIC_TESTFEAT_OBFUS_MASK    (1 << 5)
#define QASIC_TESTFEAT_OBFUS_SHIFT    5
#define QASIC_TESTFEAT_OBFUS_ENABLE    0x20

// 0=disabled; 1=enabled
#define QASIC_TESTFEAT_RESERVED_06    (1 << 6)  
#define QASIC_TESTFEAT_DEBUG_MASK     (1 <<7)

/* Global variable for Qwantum ASIC feature on/off */ 
uword QASIC_testFeat = QASIC_TESTFEAT_OP_MODE_SPI;
## 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.magtek.com/qwantum-services/qwantum-asic/documentation/msr-chip-spi-firmware-implementation-guide/qwantum-asic-spi-communication-interface/qwantum-asic-application-layer-functions.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.