feat(Examples): Add RTOS Debug Features to MAX78000 FreeRTOSDemo

[Brandon-Hurst]

Description

Added Debug features to the FreeRTOSDemo for MAX78000. These features are added in such a way as to be easily copyable to most other MCUs in the MSDK.

Summary:

• A default configuration of TMR0 is provided in FreeRTOS_Debug.c and conditionally used based on the DEBUG flag. Numerous FreeRTOS configs related to debugging are also connected to this flag.
• README.md details the inclusion of the TMR0 config based on DEBUG==1
• A HardFaultHandler is defined with a helper function to grab the CPU registers from the failing code context in the event of a HardFault. This is recommended by the FreeRTOS documentation to assist with debugging Hard Faults.

Ideally this would be available at some point for all FreeRTOSDemo Examples or placed inside the MSDK FreeRTOS library. Exposing it inside an example may be preferable as an instructive inclusion for developers. This PR is meant to initiate a dialogue and add some more RTOS Debug features to MSDK. I am also happy to modify anything needed for this PR.

Regarding the HardFault Handler...

Credit to @BrentK-ADI for this portion of the example.
The code included is recommended in the FreeRTOS Documentation to improve debugging Hard Faults by grabbing the stack context from which the code failed. Debugging Hard Faults can be notoriously tricky without this information.
Link: https://www.freertos.org/Debugging-Hard-Faults-On-Cortex-M-Microcontrollers.html

• Within the handler itself, the first instruction checks bit 2 of the LR.
  • Per documentation "Upon exception entry, the active stack pointer is encoded in bit 2 of the EXC_RETURN value pushed to the link register. If the bit is set, the psp was active prior to exception entry, else the msp was active". This check determines which stack pointer the function causing the fault was using.
• The next instruction, ite, is an assembly If/Else code, where the following mrs instructions are the if and else respectively, getting the appropriate stack address into R0. We then place getRegistersFromStack into R2. getRegistersFromStack is then called with bx.
• The getRegistersFromStack function pulls all the relevant registers from the culprits stack. This includes the program counter (instruction) that caused the fault, as well as the LR (link register) determining which function called that block of code. R0-3 can also give context into the state of the calling function.

Testing

RTOS Stats Test

The build was completed and ran successfully on MAX78000FTHR, and RTOS Stats were gathered via the "RTOS Views" extension in VSCode, image below.

Worth noting is that FreeRTOS's kernel does not smartly handle Timer Overflow on the RTOS Stats Timer, so overflowing the provided counter will give inaccurate results. This is documented within FreeRTOS_Debug.c provided. The default 32-bit, 32 kHz configuration provides nearly 100 days before overflow.

HardFault Handler Test

Hard Fault Analysis was tested via a privileged memory read of address 0xFFFFFFFF inserted into the example.

The values shown are from the context which caused the HardFault, not from within the HardFault itself. This streamlines the process of finding the code which caused the fault (in this case located at address 0x1000_083e)

[Jake-Carter]

Thanks @Brandon-Hurst @BrentK-ADI, looks like a great start. A few comments below.

Is there also some mechanism for determining which task/context is active from inside the hard fault handler? This would also be useful to narrow down which task is at fault