1 MPLAB® Harmony Class B Library for PIC32CM MC00 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
Following table shows the 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.
![](GUID-2CFCDCD8-83A3-453B-BB00-B398598611C3-low.png)
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 MHC, the selected SSTs are inserted into the _on_reset()
function which is called from the Reset_Handler()
. 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.h
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 inside the CPU.
![](GUID-2E1A324F-CC7E-42BF-B865-A5F9A2D6333A-low.png)
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, 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
Internal Flash program memory
Generic Flow of Critical Tests
![](GUID-950CED79-D1C0-483F-B9E9-852BB00D3AAE-low.png)
Non-critical Components
CPU clock
IO pins
Internal SRAM
Interrupts
Generic Flow of Non-Critical Tests
![](GUID-402961DC-5098-45C4-9FE0-F87D48B6374E-low.png)
Self-tests for Components in the Library
CPU Registers
The ARM® Cortex®-M0+ is the CPU on the PIC32CM MC00 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.
This self-test follows the register save/restore convention specified by AAPCS. 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.
Flow chart of the self-test for CPU registers
![](GUID-166631A1-EEBB-4060-A9E1-C4247F6CE440-low.png)
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.
Flow chart of the self-test for Program Counter (PC)
![](GUID-58C32B9E-2455-4D5D-AA05-DE04E2AAEECF-low.png)
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. 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.
Flow chart of the self-test for internal flash program memory
![](GUID-BDD32550-044E-4B84-BA33-620536CDFF77-low.png)
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. 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
Fault Coverage for March Algorithms
Name | Fault Coverage |
---|---|
March C | Addressing faults, Stuck-at faults, Transition faults, all coupling faults |
March C- | 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 |
Flow chart of the self-test for SRAM
![](GUID-8E6604F8-FA39-4CFC-847E-D439881E59F2-low.png)
Flow chart of the internal routine for SRAM self-test
![](GUID-3EFECA4B-00A4-4514-AB80-6F570021F3A4-low.png)
Clock
The self-test for CPU clock checks whether the CPU clock frequency is within the permissible range. It uses RTC and SysTick to measure the CPU clock frequency. The RTC 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.
Note
This self-test uses the RTC peripheral. Thus, if it is used during run-time, the RTC shall not be used by the application for continuous modes such as real time clock or calendar. If the RTC 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.
Flow chart of the self-test for CPU clock frequency
![](GUID-1DABC9F1-CFC1-4406-A636-DD84F87563DA-low.png)
Interrupt
The self-test for this element checks the interrupts functionality of the microcontroller. It configures the Nested Vectored Interrupt Controller (NVIC), the Real-Time Counter (RTC) and the Timer Counter 0 (TC0) 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. It reports a PASS if the RTC has generated at least one interrupt and the total number of interrupts generated by the TC0 is greater than one and less than the specified upper limit. The clock used for RTC is 1kHz from the internal OSCULP32K and for TC0 the clock is same as the default CPU clock (48MHz from the DFLL48M). The interrupt self-test can be used only at startup.
Note
This startup self-test utilizes the interrupts generated by RTC and TC0. For run-time testing of interrupts, a separate self-test need to be developed.
Flow chart of the self-test for interrupts
![](GUID-B9D8A546-D3CD-4EC4-B704-BD0030842C01-low.png)
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. Before testing an output pin, call CLASSB_IO_InputSamplingEnable() function to enable input sampling for the IO pin. 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.
Flow chart of the self-test for IO pins
![](GUID-651007EF-CA66-4239-950D-76A2ACFCFCE8-low.png)
Class B Peripheral Library - Timing of self-tests
Peripherals other than Flash and SRAM
Name | Time (in miroseconds) |
---|---|
CLASSB_CPU_RegistersTest | 14 |
CLASSB_CPU_PCTest | 8 |
CLASSB_RST_IOTest | 5 |
CLASSB_ClockTest | 5100 |
CLASSB_SST_InterruptTest | 9200 |
Flash and SRAM
Name | Time (in miroseconds) | Tested size |
---|---|---|
CLASSB_FlashCRCTest | 12 | 32 KB |
CLASSB_SRAM_MarchTestInit | 282 | 8 KB |
Note
Timing is measured using onchip peripherals (SysTick and TC) at optimization level -O1 with CPU running at 48MHz from the internal 48MHz 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
MPLAB X v5.50
XC32 Compiler v3.00
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 | -O0 |
All other files (.h, .c, .S) | -O1 or -O2 or -O3 |
Applying File Level Optimization MPLAB X
![](GUID-F59EF12D-14B0-4A19-B57C-F66D1D3F9335-low.png)
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 MHC, the linker setting is modified by MHC as shown below. In this example, the PIC32CM1216MC00048 device with 16kB of SRAM is used.
-DRAM_ORIGIN=0x20000400,-DRAM_LENGTH=0x3C00
![](GUID-E4577708-C82B-4F16-8E78-599548007E5E-low.png)
Modified Startup Sequence
When generating project with help of MPLAB Harmony 3, the startup code is present in a file named startup_xc32
.
This file contains the Reset_Handler
which has all startup code that runs before the main()
function.
Initialization of the Class B library is done from the _on_reset
function which is the first function
to be executed from the Reset_Handler
. The function named CLASSB_Startup_Tests
executes all startup self-tests
inserted into classb.c
file by the MHC. 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_reset
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.
In CLASSB_Startup_Tests
(in file classb.c
), before performing startup self-tests, the WDT timeout period is configured.
It can be modified after generating the project.
During startup, the device runs from 4 MHz internal clock. Before running any self-test which takes longer time
(SRAM or Flash test), configuring the CPU clock at 48 MHz will help to recude the exection time.
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.
![](GUID-BCB7FF3B-CFD5-4CA3-80A8-CBDF25BA22E0-low.png)
![](GUID-94C97E0C-BC14-42EB-AE69-3042034CE9B5-low.png)
Configuring Startup Tests via MHC
Clone the classb_pic32cm_mc
repo. When an MPLAB Harmony 3 project is created, the MHC lists all available
components that can be added to the project. The self-tests which need to run during startup can be configured via MHC.
The Configuration Options
menu appears with a mouse click on the Class B Library
component inside
the Project Graph
. The configurations done via MHC 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
Name | Description |
---|---|
Constants Summary | |
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_RTC_CLK_FREQ | RTC clock frequency. |
CLASSB_CLOCK_TEST_RTC_RATIO_NS | Duration of RTC 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_DEVICE_VECT_OFFSET | Defines the offset for first device specific interrupt. |
CLASSB_INTR_MAX_INT_COUNT | Defines the upper limit for interrupt count. |
CLASSB_INTR_TEST_RTC_COUNT | Defines the counter value for RTC peripheral. |
CLASSB_INTR_TEST_TC_COUNT | Defines the counter value for TC0 peripheral. |
CLASSB_INTR_VECTOR_TABLE_SIZE | Defines the size of the vector table. |
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. |
Data types Summary | |
*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 0x20000000. 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 0x20000004. 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_PORT_PIN | PIN definitions for Class B library I/O pin test. |
CLASSB_PORT_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. |
Interface Routines Summary | |
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_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_GlobalsInit | This function initializes the global variables for the classb library. |
CLASSB_IO_InputSamplingEnable | Enable input sampling for an IO pin. |
CLASSB_Init | This function is executed on every device reset. This shall be called right after the reset, before any other initialization is performed. |
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_SST_WDT_Recovery | This function is called if a WDT reset has happened during the execution of an SST. |
CLASSB_Startup_Tests | This function executes all startup self-tests inserted into classb.c file. |
CLASSB_RST_IOTest | This self-test can be used to perform plausibility checks on IO pins. |
CLASSB_TestWDT | This function tests the WatchDog Timer (WDT). |