1 MPLAB® Harmony Class B Library for PIC32MK MC Devices

The Class B Library provides APIs to perform self-tests for the on-board systems of the microcontroller.

Features Tested by the Class B Library

Table 1-1. Components tested by the Class B library
Component	Reference (Table H1 of IEC 60730-1)	Fault/Error	Acceptable Measures
CPU Registers	1.1	Stuck-at	Static memory test
CPU Program Counter	1.3	Stuck-at	Static memory test
Interrupts	2	No interrupt / too frequent interrupt	Functional test
CPU Clock	3	Wrong frequency	Frequency monitoring
Flash	4.1	All single bit faults	Modified checksum
SRAM	4.2	DC fault	Static memory test
SRAM data path	5.1	Stuck-at	Static memory test
SRAM data path	5.2	Wrong address	Static memory test
Digital I/O	7.1	Abnormal operation	Input comparison or output verification

Class B Peripheral Library Usage

This topic describes the basic architecture of the Class B library and provides information and examples on how to use it. APIs defined by the Class B library can be used either by the start-up code or by the application code. The application may use PLIBs, drivers or middleware from the Harmony 3 software framework along with the Class B library code.

Abstraction Model

The following picture shows positioning of Class B library in a Harmony 3 based application.

Start-up vs. Run-time

The Class B library contains many self-test routines those can be executed at startup and run-time. If a self-test is executed at startup, it is called as a Start-up Self-test (SST) and if it is executed at run-time, then it is called a Run-time Self-test (RST). There are a few self-tests which can be used only as SST or as RST, such self-tests have SST or RST in the API name eg: CLASSB_RST_IOTest(), CLASSB_SST_InterruptTest(). If a self-test API does not have SST or RST in its name, then it can be used at startup as well as runtime.

Start-up Self-test (SST)

SSTs are used to test a component inside the microcontroller before it is initialized and used. When the Class B library is added via MPLAB® Code Configurator (MCC), the selected SSTs are inserted into the _on_bootstrap() function which is called during startup. This means that none of the data initialization could have happened before running SSTs. So, the Class B library initializes necessary variables before using them. It is not mandatory to test all the components during startup. The SRAM can be tested partially if a faster startup is needed by the application. In this case, modify the corresponding configuration macro (CLASSB_SRAM_STARTUP_TEST_SIZE) present in classb.c file to change the size of the tested area.

Run-time Self-test (RST)

RSTs can be used by the application during run-time to check safe operation of different components in the microcontroller. These tests are non-destructive. In the case of run-time tests, the application shall decide which test to execute when.

Components in the Library

The Class B library contains self-test routines for different components listed in Table 1-1.

Critical and Non-critical Components

Based on the impact of failure, different components inside this Class B library are categorized as critical or non-critical.

If the self-test for CPU registers, FPU registers, PC or Flash detects a failure, the code execution is stopped, and it remains in an infinite loop. This is to prevent unsafe code execution. In the case of non-critical components, a failsafe function (CLASSB_SelfTest_FailSafe) is called when a failure is detected. This function contains a software break point and an infinite loop. Further code shall be added into this function as per the application need. The failsafe function must not return to the Class B library, since it is called due to a self-test failure. Avoid use of features which depend on the failed component. For example, if self-test for clock is failed, it is not advisable to use UART for error reporting as BAUD rate may not be accurate. In the case of SRAM failure, avoid the use of function calls or use of variables in SRAM. A simple error reporting mechanism in this case of SRAM failure can be toggling of an IO pin.

Critical Components

CPU registers including the Program Counter
FPU registers
Internal Flash program memory

Figure 1-1. Generic Flow of Critical Tests

Non-critical Components

CPU clock
IO pins
Internal SRAM
Interrupts

Figure 1-2. Generic Flow of Non-Critical Tests

Self-tests for Components in the Library

CPU Registers

The MIPS32® microAptiv™ MCU core is the CPU on the PIC32MK MC devices. The Class B library checks the processor core registers for stuck-at faults. The stuck-at condition causes register bit to remain at logic 0 or logic 1. Code execution should be stopped if this error condition is detected in any of the CPU registers.

It can be used at startup as well as run-time. The Program Counter (PC) self-test is designed as a separate test since this register cannot be checked with usual test data patterns.

Figure 1-3. Flow chart of the self-test for CPU registers

Figure 1-4. Flow chart of the internal routine 'sCLASSB_CPURegistersTest()' defined in 'classb_cpu_reg_test_asm.S' for CPU registers self-test

FPU Registers

The self-test for FPU checks whether a stuck-at condition is present in the FPU register. The stuck-at condition causes register bit to remain at logic 0 or logic 1. Code execution should be stopped if this error condition is detected.

It can be used at startup as well as run-time.

Figure 1-5. Flow chart of the self-test for FPU

Figure 1-6. Flow chart of the internal routine 'sCLASSB_FPURegistersTest()' defined in 'classb_cpu_reg_test_asm.S' for FPU registers self-test

Program Counter (PC)

The self-test for PC checks whether a stuck-at condition is present in the PC register. The stuck-at condition causes register bit to remain at logic 0 or logic 1. Code execution should be stopped if this error condition is detected.

The self-test for PC calls multiple functions in predefined order and verifies that each function is executed and returns the expected value. If the return values of all test functions are correct, the Program Counter is assumed to be working fine. This self-test can be used at startup as well as run-time.

Figure 1-7. Flow chart of the self-test for Program Counter (PC)

Flash

The internal flash memory of the device needs to be checked for proper functionality. The self-test for internal flash performs CRC check on the internal flash memory of the device. The address range is configurable for this self-test. The address range is defined by the input argument for this self-test and this range should be within the range defined in kseg1 (non-cacheable memory, refer datasheet) area of the device. It runs CRC-32 algorithm with reversed representation of the polynomial 0x04C11DB7 and compares the generated checksum with the expected checksum. It uses table-based approach where the table is generated during the execution.

This self-test uses a CRC-32 generation function. This function is used inside the Class B library to generate CRC-32 of the internal Flash memory but it can be used on any contiguous memory area. The flash self-test can be used at startup as well as run-time. If this self-test is used during start up, it must be ensured that the CRC of the application area is precalculated and stored at a specific memory address which is passed as an argument for the Flash self-test. If this self-test detects a failure, it remains in an infinite loop.

Figure 1-8. Flow chart of the self-test for flash program memory

SRAM

Self-test for the SRAM element looks for stuck-at faults, DC faults and addressing faults with the help of RAM March algorithms. One of the input arguments to this self-test selects the algorithm. This self-test copies the data from the tested area of the SRAM into the reserved area in the SRAM and restore the data after the test. The tested SRAM should be within the range defined in kseg1 (non-cacheable memory, refer datasheet) area of the device. Refer to section Configuring the Library for the details on reserving the SRAM. The stack pointer is moved to the reserved area in the SRAM before running this self-test. The SRAM self-test can be used at startup as well as run-time.

It provides three standard tests to detect error conditions:

March C
March C minus
March B

Table 1-2. Fault Coverage for March Algorithms
Name	Fault Coverage
March C	Addressing faults, Stuck-at faults, Transition faults, all coupling faults
March C minus	Unlinked addressing faults, Stuck-at faults, Transition faults, all coupling faults
March B	Addressing faults, Stuck-at faults, Transition faults, Linked idempotent coupling faults, Linked inversion coupling faults

Figure 1-9. Flow chart of the self-test for SRAM

Figure 1-10. Flow chart of the internal routine for SRAM self-test

Clock

The self-test for CPU clock checks whether the CPU clock frequency is within the permissible range. It uses TMR1 and SysTick to measure the CPU clock frequency. The TMR1 is clocked at 32768 Hz from the 32 kHz External Crystal Oscillator and CPU clock can be from any other high frequency oscillator. If the CPU clock frequency is within specified error limit, it returns PASS. The test duration is defined by one of the input arguments. The clock self-test can be used at startup as well as run-time.

Notes:

This self-test uses the TMR1 peripheral. Thus, if it is used during run-time, the TMR1 shall not be used by the application for continuous modes. If the TMR1 is used for some other purpose, it must be reconfigured after running the clock self-test.
Keep the clock test duration lesser than the WDT timeout period, to avoid the WDT resetting the device.
If the Application enables clock self-test , user must ensure to configure respective external clock i.e. SOSC via MCC.

Interrupt

The self-test for this element checks the interrupts functionality of the microcontroller. It configures the EVIC, the Timer 1 (TMR1) and the Timer 2 (TMR2) peripherals to test the interrupt handling mechanism. It verifies that at least one interrupt is generated and handled properly. This self-test also checks whether the number of interrupts generated are too many within a given time period.

TMR1 is configured for polling (Without ISR). It reports a PASS if the total number of interrupts generated by the TMR2 is greater than one and less than the specified upper limit. The clock used for TMR1 and TMR2 is from the Internal peripheral clock. The interrupt self-test can be used only at startup.

Note:

The startup self-test utilizes the interrupts generated by TMR2 and TMR1 with polling method. For run-time testing of interrupts, a separate self-test need to be developed.

Figure 1-11. Flow chart of the self-test for interrupts

IO pin

The self-test for IO pins verifies that any output pin is able to keep the configured logic state on the pin and any input pin is able to read the logic state present on the pin.

As the exact use of an IO pin is decide by the application, it is the responsibility of the application to configure the IO pin direction and drive the pin to the expected state before calling this self-test. When testing an input pin, ensure that the IO pin is externally kept at a defined logic state. The IO pin self-test can be used only at run-time.

Figure 1-12. Flow chart of the self-test for IO pins

Class B Peripheral Library - Timing of self-tests

Table 1-3. Peripherals other than Flash and SRAM
Name	Time (in microseconds)
CLASSB_CPU_RegistersTest	50 μs
CLASSB_FPU_RegistersTest	15 μs
CLASSB_CPU_PCTest	10 μs
CLASSB_RST_IOTest	8 μs
CLASSB_ClockTest	10000 μs
CLASSB_SST_InterruptTest	110000 μs

Table 1-4. Flash and SRAM Startup Test
Name	Time (in milliseconds)	Tested size
CLASSB_FlashCRCTest	40	122 KB
CLASSB_SRAM_MarchTestInit	220	16 KB

Notes:

Timing is measured using onchip peripherals (Coretimer) at optimization level -O1 with CPU running at 120 MHz from the primary 8 MHz oscillator. Before using these self-tests in an application it is recommended to check self-test timings with the required configuration (CPU clock, compiler optimization, memory size).
Timing measured for CLASSB_SRAM_MarchTestInit using the ‘March C’ algorithm.
Following IDE and toolchain are used for timing measurements:
1. MPLAB X v6.20
2. XC32 Compiler v4.35

Configuring the Library (MPLAB X)

This section provides details necessary to integrate the Class B library with other software components.

Optimization Requirements

The self-test routines provides by the Class B software has specific optimization requirements which are listed in the following table. If the optimization level for the project is different from what is listed in this table, file level optimization has to be applied as per this table.


File	Optimization Level
classb_cpu_pc_test.c, classb_sram_algorithm.c, classb_sram_test.c	-O0
All other files (.h, .c, .S)	-O1

Applying File Level Optimization MPLAB X

Reserved SRAM area for the Class B library

It is required to reserve 1kB of SRAM for exclusive use by the Class B library. This reserved SRAM must not be accessed from outside the Class B library. To check or update test results, use the corresponding interface APIs. When the Class B library is added into the project with the help of MCC, the linker setting is modified by MCC as shown below.

-mreserve=data@0x00000400:0x000007ff

Modified Startup Sequence

When generating project with help of MPLAB Code Configurator, the startup code is present in a file named crt0.s. This is a compiler provided file and can be found in local folder of pc ..\xc32\v4.35\pic32mx\lib, after installation of xc32 compiler. Initialization of the Class B library is done from the _on_bootstrap function which is to be executed before main(). The function named sCLASSB_Startup_Tests executes all startup self-tests inserted into classb.c file by the MCC. If none of the self-tests are failed, this function returns CLASSB_STARTUP_TEST_PASSED. If any of the startup self-tests are failed, this function does not return becasue of the following reason. In the case of critical failures (CPU registers or internal flash), the corresponding self-test remains in an infinite loop to avoid unsafe execution of code. The self-tests for SRAM, Clock and Interrupt are considered non-critical since it may be possible to execute a fail-safe function after detecting a failure. In such case, the CLASSB_SelfTest_FailSafe() function is called when a failure is detected. Since the default implementation of CLASSB_SelfTest_FailSafe routine contains an infinite loop, it won't return to the caller.

Note:

The library defines the _on_bootstrap function and handles some of the reset causes. The application developer shall insert functions to handle the rest of the reset causes.

WDT Test and Timeout

The Watchdog timer is used as a recovery mechanism in case of software failures. The Class B library enables the WDT and checks whether a WDT reset is issued if the timer is not cleared. User must ensure to configure proper time out period of WDT using MCC as per the application needs to avoid long startup.

If any of these self-tests takes more time than the WDT timeout period, it results in a WDT reset. Thus, properly configuring the WDT period is essential during startup as well as runtime.

Configuring Startup Tests via MCC

Clone the classb_pic32mk_mc repo. When an MPLAB Code Configurator project is created, the MCC lists all available components that can be added to the project. The self-tests which need to run during startup can be configured via MCC. The Configuration Options menu appears with a mouse click on the Class B Library component inside the Project Graph. The configurations done via MCC does not configure the library, instead it helps to modify the input arguments and to decide whether to run a specific test during startup.

Class B Library Interface

Table 1-5. List of Constants
Name	Description
CLASSB_CLOCK_DEFAULT_CLOCK_FREQ	Default CPU clock speed.
CLASSB_CLOCK_ERROR_PERCENT	Clock error percentage selected for startup test.
CLASSB_CLOCK_MAX_CLOCK_FREQ	Maximum CPU clock speed.
CLASSB_CLOCK_MAX_SYSTICK_VAL	Upper limit of SysTick counter.
CLASSB_CLOCK_MAX_TEST_ACCURACY	Maximum detectable accuracy for clock self-test.
CLASSB_CLOCK_MUL_FACTOR	Multiplication factor used in clock test.
CLASSB_CLOCK_TMR1_CLK_FREQ	TMR1 clock frequency.
CLASSB_CLOCK_TEST_TMR1_RATIO_NS	Duration of TMR1 clock in nano seconds.
CLASSB_CLOCK_TEST_RATIO_NS_MS	Ratio of milli second to nano second.
CLASSB_COMPL_RESULT_ADDR	Address of one's complement test results.
CLASSB_FLASH_CRC32_POLYNOMIAL	CRC-32 polynomial.
CLASSB_INTERRUPT_COUNT_VAR_ADDR	Address of the variable which keeps interrupt count.
CLASSB_INTERRUPT_TEST_VAR_ADDR	Address of the variable which keeps interrupt test internal status.
CLASSB_INTR_MAX_INT_COUNT	Defines the upper limit for interrupt count.
CLASSB_INVALID_TEST_ID	Invalid test ID.
CLASSB_ONGOING_TEST_VAR_ADDR	Address at which the ID of ongoing test is stored.
CLASSB_RESULT_ADDR	Address of test results.
CLASSB_SRAM_ALL_32BITS_HIGH	Defines name for max 32-bit unsigned value.
CLASSB_SRAM_APP_AREA_START	Defines the start address of the SRAM for the application.
CLASSB_SRAM_BUFF_START_ADDRESS	SRAM test buffer start address.
CLASSB_SRAM_FINAL_WORD_ADDRESS	Final word address in the SRAM.
CLASSB_SRAM_STARTUP_TEST_SIZE	Size of the SRAM tested during startup.
CLASSB_SRAM_TEST_BUFFER_SIZE	Defines the size of the buffer used for SRAM test.
CLASSB_SRAM_TEMP_STACK_ADDRESS	Address of the temporary stack.
CLASSB_TEST_IN_PROG_VAR_ADDR	Address of the variable which indicates that a Class B test is in progress.
CLASSB_WDT_TEST_IN_PROG_VAR_ADDR	Address of the variable which indicates that a WDT test is in progress.

Table 1-6. List of Data Types
Name	Description
CLASSB_SST_RESULT_BF	Pointer to the structure for the Class B library startup self-test result. This can be used to point to the result address 0xA0000400(KSEG1 of SRAM, Refer datasheet). It will help to see the result in text form via watch window.
CLASSB_RST_RESULT_BF	Pointer to the structure for the Class B library run-time self-test result. This can be used to point to the result address 0xA0000404(KSEG1 of SRAM, Refer datasheet). It will help to see the result in text form via watch window.
CLASSB_CPU_PC_TEST_VALUES	Data type for PC Test input and output values.
CLASSB_INIT_STATUS	Identifies Class B initialization status.
CLASSB_PORT_INDEX	PORT index definitions for Class B library I/O pin test.
CLASSB_GPIO_PIN	PIN definitions for Class B library I/O pin test.
CLASSB_GPIO_PIN_STATE	PORT pin state.
CLASSB_SRAM_MARCH_ALGO	Selects the RAM March algorithm to run.
CLASSB_STARTUP_STATUS	Identifies startup test status.
CLASSB_TEST_ID	Identifies Class B library tests.
CLASSB_TEST_STATUS	Identifies result from Class B library test.
CLASSB_TEST_STATE	Identifies Class B library test state.
CLASSB_TEST_TYPE	Identifies type of the Class B library test.

Table 1-7. List of Interface Routines
Name	Description
CLASSB_App_WDT_Recovery	This function is called if a WDT reset has happened during run-time.
CLASSB_CPU_RegistersTest	This self-test checks the processor core registers.
CLASSB_FPU_RegistersTest	This self-test checks the processor FPU registers.
CLASSB_CPU_PCTest	This self-test checks the Program Counter register (PC).
CLASSB_ClearTestResults	Clears the results of SSTs or RSTs.
CLASSB_ClockTest	This self-test checks whether the CPU clock frequency is within the permissible limit.
CLASSB_GetTestResult	Returns the result of the specified self-test.
CLASSB_FlashCRCGenerate	Generates CRC-32 checksum for a given memory area.
CLASSB_FlashCRCTest	This self-test checks the internal Flash program memory to detect single bit faults.
CLASSB_SelfTest_FailSafe	This function is called if any of the non-critical tests detects a failure.
CLASSB_SRAM_MarchTestInit	This self-test checks the SRAM with the help of RAM March algorithm.
CLASSB_SST_InterruptTest	This self-test checks basic functionality of the interrupt handling mechanism.
CLASSB_RST_IOTest	This self-test can be used to perform plausibility checks on IO pins.