Skip to Content

AT91Bootstrap Version 4.x

Last modified by Microchip on 2025/11/21 14:55

Introduction

AT91Bootstrap is the second level bootloader for Microchip MPUs, providing a set of algorithms to manage the hardware initialization such as clock speed configuration, PIO settings, DRAM initialization, to download your main application from specified boot media (NAND FLASH, serial FLASH (both AT25-compatible or DataFlash), serial EEPROM, SD Card, eMMC, etc.) to main memory and to start it.

This page is dedicated to AT91Bootstrap 4.0.0 and newer. For older versions of AT91Bootstrap, check this page AT91Bootstrap v3.x.

AT91Bootstrap v4 only supports these devices:

  • SAMA5D3
  • SAMA5D4
  • SAMA5D2
  • SAM9X60
  • SAM9x7
  • SAMA7G5
  • SAMA7D65

Boot Strategies

Microchip MPUs embed a boot ROM code. It is enabled depending on Boot Mode Select (BMS) pin state on reset, fuse content or OTP boot packed. The ROM code scans the contents of different media like serial NAND FLASH, SD/MMC Card, QSPI flash and serial EEPROM. If a valid application is available, then it downloads this application into the chip internal SRAM and runs it. To determine if a valid application is present, the ROM code checks the eight Arm® exception vectors or file name.

If no valid application is available, then the SAM-BA® monitor is executed. It waits for transactions either on the USB device or on the DBGU serial port, then the SAM-BA software can be used to program FLASH or EEPROM present on your board.

For more information on this topic, please check the corresponding product data sheet section "Boot Strategies".

ROM Code Boot Sequence Example

This is an example of boot sequence when BMS=1 taken from the sama5 product family:

NVM boot sequence

By programming the BSC_CR register, we can bypass some steps in the above sequence.

Information

 Note: A reset is needed to make BSC_CR effective. BSC_CR will be restored to factory value if power is removed.

Back to Top

Build AT91Bootstrap From Sources

Set Up Arm® Cross Compiler

Warning

 We always recommend using up-to-date toolchains. Check the README file inside the source code for known issues.

Failed to execute the [display] macro. Cause: [Current user [null] doesn't have view rights on document [xwiki:Development.applications.linux4sam.subsections.cross-compiler.13-2-rel1.WebHome]]. Click on this message for details.

  • The first step is to download the Arm GNU toolchain:
    wget -c https://developer.arm.com/-/media/Files/downloads/gnu/13.2.rel1/binrel/arm-gnu-toolchain-13.2.rel1-x86_64-arm-none-linux-gnueabihf.tar.xz
  • The next step is to add the Arm GNU toolchain to your system:
    tar -xf arm-gnu-toolchain-13.2.rel1-x86_64-arm-none-linux-gnueabihf.tar.xz export CROSS_COMPILE=`pwd`/arm-gnu-toolchain-13.2.rel1-x86_64-arm-none-linux-gnueabihf/bin/arm-none-linux-gnueabihf- 

    or

    tar -xf arm-gnu-toolchain-13.2.rel1-x86_64-arm-none-linux-gnueabihf.tar.xz
    export CROSS_COMPILE=arm-none-linux-gnueabihf-
    export PATH=$PATH:/YOUR/PATH/TO/arm-gnu-toolchain-13.2.Rel1-x86_64-arm-none-linux-gnueabihf/bin/   

Note: If you already have an old Arm GNU toolchain, clean up the PATH with:

export PATH=${PATH/':/YOUR/PATH/TO/arm-gnu-toolchain-VERSION-x86_64-arm-none-linux-gnueabihf/bin/'/

Other Dependencies

Warning

 Python 3 is required for the scripts that generate PMECC headers.

Warning

 On the latest Ubuntu versions, make sure that /bin/sh points to bash.

ls -l `which sh`
/bin/sh -> dash
sudo dpkg-reconfigure dash #Select "no" when you're asked
[...]
ls -l `which sh`
/bin/sh -> bash

Build AT91Bootstrap

Failed to execute the [display] macro. Cause: [Current user [null] doesn't have view rights on document [xwiki:Development.applications.linux4sam.subsections.at91bootstrap.build-at91bootstrap-all-top.WebHome]]. Click on this message for details.

Assuming you are at the AT91Bootstrap root directory, you will find a configs folder that contains several default configuration files:

sam9x60ekqspi_uboot_defconfig
sam9x60eksd_uboot_defconfig
sam9x60eknf_uboot_defconfig

Tip: QSPI means to read Quad-SPI (QSPI) serial flash, SD means to read MMC card, and nf means to read NAND flash.

You can configure AT91Bootstrap to load the U-Boot binary from the SD card by:

$ make mrproper
$ make sam9x60eksd_uboot_defconfig

If the configuration process is successful, the .config file can be found at the AT91Bootstrap root directory.

Failed to execute the [display] macro. Cause: [Current user [null] doesn't have view rights on document [xwiki:Development.applications.linux4sam.subsections.at91bootstrap.build-at91bootstrap-all-bottom.WebHome]]. Click on this message for details.

Back to Top

Customizing and Tailoring AT91Bootstrap to Your Specific Board Step-by-Step

Unlike the 3.x series of AT91Bootstrap, the 4.x series allows the user to completely configure a new board from existing code, without the need to add a new board under the contrib directory.

Information

AT91Bootstrap 4.x no longer has the concept of 'board.' Board was a file that had plenty of duplicate code from one board to another, which was completely redundant. The idea is to have the concept of 'device,' and then to tailor the device for the needs of each board. The support for a device includes all peripherals, all iosets, and each board can select which configuration is used. The concept of board now switched to a defconfig concept: the board will be just a simple defconfig that picks parts of the code that are applicable to the specific board.

Information

It is possible that the existing code does not fully cover all possible cases that are needed for a specific board. In this case, we add what is called a 'board quirk' and we have specific code that can be selected in the defconfig.

Starting the menuconfig

To start the menuconfig operation, you have to execute:

make menuconfig

You will see a screen similar to the following:

AT91Bootstrap configuration window

Back to Top

Selecting the Goal of the Bootloader

Choose the goal of the bootloader, which can be:

Load and launch the next software.

This is the most used purpose of a bootloader. The bootloader should initialize the device (the MPU), and the required peripherals to copy the next software stage from Non-Volatile Media (NVM) to the external RAM (DRAM) and then launch the next piece of software.

In other words, load a software image from external media to RAM then, depending on the type of software, prepare the required boot parameters, and finally jump to the entry point of this software in RAM. Alternatively, if XIP is enabled, execute the software in place.

Launch externally loaded software.

This is a mode that asks the bootloader to only initialize the MPU and have other external tools load the software into memory, and then launch them. It is equivalent to the previous step, with the mention of skipping the copy of the next software image from NVM to DRAM.

This is available because, in some cases, we cannot copy the software from external media to RAM. Then, we can skip copying any software image from external media to RAM. In this mode, we expect the required images and boot parameters to be present in RAM already. For instance, they will have been loaded by a debugger via JTAG, or by the SAM-BA monitor boot assistant. Jump directly to the entry point of the software in RAM.

Configure and stop.

This mode is similar to the previous, with the difference that the bootloader will no longer copy the next software image, and also does not jump to any address after configuration is done. This mode can be used for debugging, for the user to connect with a hardware probe (JTAG) to take control of the MPU once the bootloader configures the MPU correctly.

The bootloader will configure essential peripherals. Do not load any image. Once the system is configured, trigger a breakpoint and enter an infinite loop. Wait there until a debugger takes control. Resort to the debugger (attached via JTAG) for taking control and possibly loading/running a software application. To load code into DRAM from a debugger, a bootloader is required to configure the clocks, PIOs, and memory correctly. Selecting this option builds a bootstrap image that can be used for this purpose.

Primary Operation window

Back to Top

Selecting the Device

Select the supported MPU device for the configuration.

bs43.jpg

Back to Top

Selecting the Clock Configuration

You can select the clock signals that feed the MPU, both the main clock and the slow clock. One has to choose the CPU operating frequency and the bus clock frequency of the product. The bootloader will configure the desired frequencies in the initialization sequence.

Clock Signals window

Back to Top

Console and Debug

In the next menu, select the desired console output of the bootloader, the debug verbosity level, as well as the bootstrap banner.

Console and Debug window

The console is selected with a number, and it's worth mentioning that there is a table in the help menu that explains exactly which console index corresponds to which UART or Flexcom interface of the product, and to which ioset/pinout of the specific interface. For each product, the numbers differ. To see the exact values, press h on the menuconfig interface. The following screenshot shows an example.

Console Port window

Back to Top

DRAM Configuration

Configure the DRAM controller and the DRAM timings for the DRAM initialization.

DRAM window

There are three different ways to select the possible DRAM configuration that one can choose:

  1. DRAM part number: This allows you to use the configuration tailored for a specific DRAM chip, selectable by part number (manufacturer and model).
  2. JEDEC profile: With this method, you can choose the JEDEC recommended configuration and timings for a specific DRAM family, like DDR2, DDR3, etc. These are the failsafe timings recommended by JEDEC and should work with all DRAM parts that are compliant with the JEDEC specification.
  3. Customized timings: This method allows complete custom configuration of all the parameters and timings of the DRAM interface.

Configuration method window

Back to Top

NVM Configuration

Select the NVM media that stores the next stage software. The next stage binary will be loaded from this NVM and copied into the DRAM.

AT91Bootstrap supports various NVMs like SD-Card, NAND flash, SPI flash, etc.

Non-volatile memory to load from

Back to Top

Next Stage Configuration

Configure the next stage software. This section includes the offset inside the NVM or the file name inside the NVM file system, and the DRAM address where to copy the data. It also includes other types of software-specific configuration (registers before jump, etc).

Next Software Type window

Back to Top

Board Workaround Options

Configure different board-specific quirks and other options that have not been previously determined. For example, configuring the PMIC driver can be done in this menu (voltage setting for different PMIC rails), or which LEDs are present on the board and the pinout to these LEDs. I2C buses can also be selected here, and the specific bus on which different I2C devices are connected (like the PMIC, HDMI device, i2c EEPROMs, etc.).

Board's Workaround Options window

Back to Top

Saving Configuration

Once the configuration is completed, save the configuration and exit the menuconfig. Save the configuration in a minimal text file named defconfig with the following command:

make savedefconfig

Once this is done, a file named defconfig will be created, and you can add this to the configs/ directory and send it as a patch for inclusion in AT91Bootstrap mainline.

Back to Top

Program AT91Bootstrap Binary into NVMs

Using SAM-BA In-System Programmer to Flash AT91Bootstrap to Board NVMs

SAM-BA software tool can be used to flash the boot.bin binary file on the board, using your Linux® or Windows® computer and a USB cable.

SAM-BA (SAM Boot Assistant) application is a tool you can find on the Microchip website, and can be used from the command line to flash all NVMs on the boards (SPI flashes, eMMCs, NAND flashes, QSPI flashes, etc.). SAM-BA application can be used to write to SD cards as well, but it's easier to remove the card, mount the first partition as it has a simple FAT file system and copy the boot.bin file directly to the filesystem using your Linux or Windows computer.

Set Up PMECC Header for Different Type of Board

When ROM code loads AT91Bootstrap from NAND flash, it will first check the header to know what kind of Error Correction Code (ECC) the NAND flash uses. This is also useful for other NAND flash manufacturer parameters. The header consists of 52 repetitions of the same 32-bit word, totaling 0xd0 bytes. Each 32-bit word is formatted as follows:

pmecc header

For different EK boards, the pmecc header is listed as follows:

# sama5d3_xplained
# 4 bit pmecc in 512 byte sector, one page has 4 sectors, spare size: 64, ecc offset: 36
setenv pmecc_header 0xc0902405

# sama5d4 xplained
# 8 bit pmecc in 512 byte sector, one page has 8 sectors, spare size: 224, ecc offset: 120
setenv pmecc_header 0xc1e04e07

The ROM code expects this header to be written in NAND flash, before the actual boot.bin file.

AT91Bootstrap has a PMECC header generator that can prepend the boot.bin file with the expected PMECC header. Thus, you can write the boot.bin directly with any tool to the NAND flash, once you have used this script to prepend the PMECC header.

If you do not have the PMECC header prepended to the binary, it will be automatically prepended to the binary by SAM-BA software when you write the boot.bin using the writeboot command from the nandflash applet.

Using U-Boot to Flash AT91Bootstrap

One can use U-boot tools to flash the AT91Bootstrap binary to an NVM.

Load AT91Bootstrap Binary and Set Up the Sixth Vector (Offset is 0x14) as the File Size

  • The following are the U-Boot commands that can flash at91bootstrap to NAND flash, by copying it from mmc into DRAM and then into NAND flash
setenv load_addr 22000000                            # load_addr started by pmecc header
setenv load_addr_bootstrap 220000d0                  # load_addr + 0xd0
setenv load_addr_bootstrap_vector 220000e4           # load_addr + 0xd0 + 0x14

setenv erase_bootstrap 'nand erase 0 10000'          # erase first 64k nand.

setenv mmc_bootstrap_file 'boot.bin'                 # at91bootstrap file name in mmc card
setenv load_mmc_bootstrap 'mw.b ${load_addr} 0xff 0x10000; mw.l ${load_addr} ${pmecc_header} 0x34; fatload mmc 0 ${load_addr_bootstrap} ${mmc_bootstrap_file};'

setenv flash_bootstrap_from_mmc 'run erase_bootstrap; run load_mmc_bootstrap; mw.l ${load_addr_bootstrap_vector} ${filesize}; nand write ${load_addr} 0 0x10000;'

setenv tftp_bootstrap_file 'u-boot/boot.bin'         # at91bootstrap file name in tftp server folder
setenv load_tftp_bootstrap 'mw.b ${load_addr} 0xff 0x10000; mw.l ${load_addr} ${pmecc_header} 0x34;tftp ${load_addr_bootstrap} ${tftp_bootstrap_file};'

setenv flash_bootstrap_from_tftp 'run erase_bootstrap; run load_tftp_bootstrap; mw.l ${load_addr_bootstrap_vector} ${filesize}; nand write ${load_addr} 0 0x10000;'
  • Now we can run the following commands to program at91bootstrap to nandflash in U-Boot:
    run flash_bootstrap_from_tftp or run flash_bootstrap_from_mmc

Back to Top

Contributing to AT91Bootstrap

If your system board is not listed, then you will need to port AT91Bootstrap v3.x to your hardware platform. To do this, you need to customize your bootstrap as in "Customizing and Tailoring AT91Bootstrap to Your Specific Board Step-by-Step".

Once you are done customizing, you can execute:

$ make savedefconfig

Then you will have a saved defconfig file that can be placed into configs/ directory, after you rename it according to the rule described in "Configure AT91Bootstrap".

The configuration file can be sent as a patch for review to the GitHub pull-request facility directly.

You should be able to perform the previous steps without writing any actual C code. However, your board may require specific board quirks, as some boards do. In that case, you will have to implement your quirk into AT91Bootstrap v3.x and send this board quirk as a separate patch. Board quirks include resetting certain devices on the board, reconfiguring specific I/O pins, or blocking the TWI access on some buses, for example.

Back to Top

Related Topics