# Zephyr Lab MCXN947 Debug
## Objectives
In this lab, you will learn:
- How to build and debug a Zephyr application in VS Code
- How to use various debugging tools and controls
- How to enable Zephyr thread awareness using Kconfig symbols
- How to view thread details in the debugger
- How to enable and use the **Peripherals** view
## Debug Lab
In this lab, we will go through detailed steps to run the Zephyr *Synchronization* sample application. The Debug lab includes steps to build/debug the application and details on debug tools/controls in VS Code. It also includes steps to enable thread awareness by setting up Kconfig symbols for the application example. We will take a closer look at key features like Thread status, Stack usage, Call Stack, Thread structure, and more.
### 1. Import *Synchronization* application example
Follow the steps to import the example, similar to the steps in the [Zephyr Lab MCXN947 Hello World](./Zephyr-Lab-MCXN947-Hello-World.md).
1. To import the *synchronization* application from the Zephyr Repository, click **Import Example from Repository** in the **Quickstart Panel**.
2. Select the following board settings to import the example:
- For the board, you can type **n947** to filter the board target **frdm_mcxn947/mcxn947/cpu0**. Be sure this board target ends with `cpu0`.
- For the example template, type **sync** to filter the app **zephyr/samples/synchronization**
- For Application type, select **Repository Application**
- Click **Import**
### 2. Enable thread awareness and build the example
To enable thread awareness for debugging, we need to add specific Kconfig symbols to the application example. These steps will modify the `prj.conf` file and verify the generated `.config` file, similar to the [Zephyr Lab MCXN947 Kconfig](./Zephyr-Lab-MCXN947-Kconfig.md) guide.
3. Add the following Kconfig symbols to the `prj.conf` file and save the file (Ctrl+S):
```python
CONFIG_DEBUG_THREAD_INFO=y
CONFIG_INIT_STACKS=y
CONFIG_THREAD_STACK_INFO=y
```
4. Build the project by clicking the **Build Selected** icon.
After the build, the Terminal window displays the memory usage (or compiler errors if any).
### 3. Exploring Debug Tools and Controls
After building the application and enabling thread awareness, let’s explore the debug tools and controls in the **Run and Debug** view.
5. If not already connected to the board, connect the USB Type-C cable to J17, to power and debug the board. Connect the Serial monitor to the board’s COM port and click **Start Monitoring**.
6. Click the play icon to **Debug** the Synchronization application.
7. **Download the SVD file**. A pop-up appears in the lower right corner. This lab uses this file to view the hardware peripheral registers while debugging. The SVD file contains the list of peripheral registers and their bitfields for the debugger. **Click the Download button** to save the SVD file in your project.
8. The following debug tools/controls are enabled in the **Run and Debug** view:
1. **Debug controls**: Resume/Pause, Step over, Step into, Restart, Stop
2. **Variables**: Locals and Registers
3. **Watch**: Add expressions to monitor
4. **Call Stack**: List of active subroutines in the program
5. **Breakpoints**: Add, toggle, and view breakpoints in the code
9. To continue with the debug execution click **Resume**. The application prints hello world (both threads) in the **Serial Monitor** view.
### 4. Debugging with Thread awareness – RTOS Details
The synchronization application has two threads (threadA and threadB) taking turns printing a message to the console. The example uses semaphores to synchronize the two tasks.
10. While the debug session is active, go to the **Run and Debug** view, and open the source file with the `main()` subroutine in the editor.
**Add a breakpoint** by double-clicking on the left side of line 48. A red dot next to the line and an entry in the Breakpoints window confirms the addition of the breakpoint.
11. The debug session will halt at the helloLoop(), and the debug controls can be used to resume or step through the code. The synchronization application will print to the terminal after **clicking** **Resume** a couple of times.
When the debugger halts at the breakpoint, the application threads and details are displayed in the **RTOS Details** view. Click the **RTOS Details** tab to see the thread details. These details include the status of each thread along with its priorities, stack pointer, and stack usage.
**Pause** the debug session to notice the changes in the status of each thread.
12. Along with the **RTOS Details** view, the **Call Stack** window provides more information about the threads in the application:
- Running thread:
- Pending thread:
- Idle Thread:
13. The **Watch** window and the **Variables** window can be used to add local variables and CPU registers that need to be monitored.
14. The **Peripherals** View will be added to the **Run And Debug** view when the SVD file is downloaded.
Registers and bitfields can be viewed for the different peripherals (eg. LPUART4).
### 5. Clean up after lab
This lab is completed. But the following steps will clean up the VS Code workspace:
15. Click **Stop** to end the debug session.
16. Close all Editor tabs. Right-Click on a tab, and select **Close All**.
17. If this is the last lab and you are done using the board, you should disconnect the Serial Monitor. Find the **Serial Monitor** view, and click **Stop Monitoring**.
## Additional Resources
[VS Code Debugging](https://code.visualstudio.com/docs/editor/debugging)
[Peripherals View](./Peripherals.md)
[RTOS Details View](./RTOS-Details.md)
---
> Lab completed. Return to the MCXN947 Zephyr Labs Overview [Training Zephyr Getting Started MCXN947](./Training-Zephyr-Getting-Started-MCXN947.md)