Configure and Build at91bootstrap to Boot MPLAB® Harmony Bare-Metal Application From NAND
Purpose
The purpose of this lab is to:
- Understand the role of at91bootstrap in the system boot sequence
- Configure at91bootstrap for standalone boot, enabling application loading from NAND flash
- 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 lab focuses on configuring and building the at91bootstrap bootloader for an Arm®-based platform. at91bootstrap acts as the first-stage bootloader responsible for initializing essential hardware components and preparing the system to load and execute the main application.
In this lab, you will modify the at91bootstrap configuration to support both debugging and execution of bare metal or MPLAB® Harmony v3 applications. Additionally, the lab demonstrates how to enable loading of the application from Non-Volatile Memory (NVM) such as QSPI, NAND, or SD/MMC, thereby simulating a real production boot flow.
Procedure
Part 1: Configure at91bootstrap to Boot Bare-Metal MPLAB Harmony Application From NAND
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" (the official Microchip 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)
Note: If the following pop-up appears in VS Code while using Kconfig (or throughout the at91bootsrap build and debug), press Esc to dismiss it. This will be fixed in the next version of the UI plugin.
Clone or download at91bootstrap from GitHub®.
Launch VS Code (File > Open Folder…) and select the at91bootstrap directory. Wait about two minutes until a notification pops up at the bottom of VS Code asking you to import the project to MPLAB for VS Code Extensions. Click Yes to proceed.
Wait for the import to be completed. Verify that the MPLAB for VS Code Extensions project loads in the VS Code Explorer and the at91boostrap.mplab.json file is created. Then proceed to the next step.
- There are several default settings files for different hardware configurations that are intended to give you 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 behavior: 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:
- Initializes the board (especially DDR, clocks)
- Loads/starts your application image in the right place or jumps to your application DDR start address:
- We recommend sam9x75_curiositynf_uboot_defconfig (found under the configs folder in the at91bootstrap directory) for the SAM9X75 Curiosity to boot from NAND
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 window. In the file selection dialog, navigate to the at91bootstrap/configs directory, select sam9x75_curiositynf_uboot_defconfig, and click Open.
The various boot configurations are depicted in the accompanying image:
Change the following settings:
- Next Software Type: Load 4MB into start of SDRAM
- Flash Offset: 0x40000
- NAND flash offset where the harmony.bin file should be updated
- Used in SAM-BA ISP while flashing harmony.bin
- The external Ram Address to Load Demo-App Image: 0x23f0000
- This should match that application entry address defined in ddram.ld file
Then click Apply.
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.
To build at91bootstrap follow these steps:
From View > Command Palette (Ctrl + Shift + P) and select Tasks: Run Task.
Choose the required task (e.g., clean and build - at91bootstrap (xc32)) from the list.
Then select Continue without scanning task output.
The task executes and shows build output in the terminal.
If the build fails because python3.exe does not exist in PATH, while only python.exe is available, then do the following:
- Using the 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.
If your build fails with an error, such as:
'rm' is not recognized as an internal or external command, operable program or batch file.
Change default terminal in VS Code. Press Ctrl + Shift + P then select Terminal: Select Default Profile, and choose Git Bash.
Now when VS Code runs make, it will use Bash instead of PowerShell.
The generated at91bootstrap.bin file under build/binaries/ can be used to boot MPLAB Harmony application from NAND flash.
Results
You have successfully:
- Configured at91bootstrap to load an MPLAB Harmony bare-metal application from NAND flash and execute from DRAM
- Generated the at91bootstrap binary image with required configuration
- Verified proper initialization of system components during boot
Collaterals
