Configure and Build at91bootstrap for Application Debugging With the MPLAB® for VS Code® Extension

Last modified by Microchip on 2026/11/20 18:44

Purpose

The purpose of this tutorial is to:

  • Understand the role of at91bootstrap in the system boot sequence
  • Configure at91bootstrap for debug support, enabling application loading via a debugger
  • Gain experience in customizing bootloader settings such as memory initialization, clock setup and boot source selection
  • Build and generate a bootable binary image compatible with the target hardware

Overview

This tutorial covers configuring and building at91bootstrap for a Microchip microprocessor platform that implements the Arm® architecture. Developed and maintained by Microchip, at91bootstrap serves as the second-stage bootloader, initializing essential hardware and preparing the system to load and run the main application.

In this tutorial, we will modify the at91bootstrap configuration to support both debugging and execution of bare-metal or MPLAB® Harmony v3 application flow.

Configure at91bootstrap to Debug an MPLAB Harmony Application

The first step is to launch VS Code®.

Ensure Kconfig for MPLAB extension v1.5.0 or higher is installed by following these steps.

Open VS Code and navigate to the Extensions view (Ctrl + Shift + X)

Search for “Kconfig for MPLAB” (Microchip official extension) 

Check the installed version. Ensure it is v1.5.0 or later.

If not installed:

  • Click Install to add the extension
  • Restart VS Code after install/update (recommended)

kconfig for MPLAB extension in VS Code

If the following pop-up appears in VS Code while using Kconfig (or throughout at91bootsrap build and debug), press Esc to dismiss it. This will be fixed in the next version of the UI plug-in for the MPLAB for VS Code tool.

Project Config- Missing compiler pop up


Clone at91bootstrap or download at91bootstrap from GitHub®.

Launch VS Code (File > Open Folder…) and select the at91bootstrap directory.

Open at91bootstrap


Wait for the import to be completed. Verify that the project created with the MPLAB for VS Code tool loads in the VS Code Explorer and that the at91bootstrap.mplab.json file is created. Then proceed to the next step.

at91bootstrap project creation in the MPLAB for VS Code tool


There are several default settings files for different hardware configurations that provide a starting point when configuring at91bootstrap. 

Examples of differences in the configurations are:

  • Boot media
    • SD/MMC vs QSPI vs NAND (driver + where it looks for the next image)
  • Early hardware init
    • DDR timing/init, clocks, pinmux
  • Console/UART selection
    • where you see logs
  • Debug behaviour
    • whether it stops/waits so a debugger can attach vs immediately loading the next stage

The MPLAB Harmony app debugging flow expects a bootstrap that:

  1. Initializes the board (especially DDR, clocks), and
  2. Loads/starts your application image in the right place or jumps to your application DDR start address

We recommend sama7d65_curiosity_pro_bkptnone_defconfig (found under the configs folder in the at91bootstrap directory) or the SAMA7D65 Curiosity debug flow used in these tutorials.


To load an existing at91bootstrap configuration in VS Code, first open the Command Palette by selecting View > Command Palette or pressing Ctrl + Shift + P, then type and select "MPLAB Kconfig Configure" to launch the Kconfig View for the project.

Once the Kconfig interface opens, verify that the at91bootstrap project is selected, and then click the Load button at the top of the Kconfig View window. In the Load Configuration window, navigate to the at91bootstrap/configs directory, select sama7d65_curiosity_pro_bkptone_defconfig and click Open.

Load defconfig


The various boot configurations are as shown in the accompanying image. Now click Apply.

Boot Configuration options


Click Yes on the pop-up so the selected configuration is correctly saved to the .config file in the at91bootstrap directory.

This completes the configuration of at91bootstrap for debugging an MPLAB Harmony application.

Save Configuration


To build at91bootstrap follow the below steps:

  • Open Command Palette (Ctrl + Shift + P) from View → Command Palette and select Tasks: Run Task.
  • Choose the required task (e.g., clean - at91bootstrap (default)) from the list.
  • Then select Continue without scanning task output 
  • The task executes and shows clean output in the terminalBuild Output
  • Open Command Palette (Ctrl + Shift + P) from View → Command Palette and select Tasks: Run Task.
  • Choose the required task (e.g., build - at91bootstrap (default)) from the list.
  • Then select Continue without scanning task output 
  • The task executes and shows build output in the terminal

Command Palette and select Tasks: Run Task


If the build fails because python3.exe does not exist in PATH, while only python.exe is available, then do the following:

  • Using Windows® Command Prompt, navigate to the Python® installation folder and create a hard link using ​​​​mklink /H python3.exe python.exe.
  • This creates python3.exe as an alias of python.exe.Python 3 Error

If your build fails with an error like:

'rm' is not recognized as an internal or external command, operable program or batch file.

Change the default terminal in VS Code. Press Ctrl + Shift + P, then select Terminal: Select Default Profile > Git Bash.

Now, when VS Code runs make, it will use Bash instead of PowerShell.

git bash


The generated at91bootstrap.elf file under build/binaries/ can be used to debug an MPLAB Harmony application.

at91bootstrap

 

Back to Top

Results

We successfully:

  • Configured at91bootstrap for:
    • Debug-based application loading
  • Generated the at91bootstrap binary image with required configuration
  • Verified proper initialization of system components during boot

Back to Top