at91bootstrap: A Second Stage Bootloader for Microchip Microprocessors

Introduction

This training topic describes at91bootstrap, a second-stage bootloader for Microchip Technology Arm®-based Microprocessor Units (MPU), where to get the source code, how to configure and compile it, and how to write it to mass storage (external Non-Volatile Memory (NVM)) for booting.

The following is based on at91bootstrap version 3.9.x.

The at91bootstrap bootloader is stored in external NVM (SD Memory Card, MultiMedia Card (MMC), Embedded MultiMedia Card (eMMC), NAND Flash, Serial Flash, QSPI Flash, DataFlash™ memory). The first-stage bootloader (contained in the ROM Boot Code) will load at91bootstrap from external NVM depending on the device. Refer to the device datasheet for specific details on their boot strategies. Additional information is available at:

at91bootstrap if configured to do so, will initialize the following peripherals and memory controllers:

  • Advanced Interrupt Controller (AIC)
  • Peripheral I/O Controller (PIO)
  • Power Management Controller (PMC)
  • Clock Generator (CKGR)
  • Static Memory Controller (HSMC)
  • NAND Flash Controller (NFC)
  • Multiport DDR-SDRAM Controller (MPDDRC)
  • Secure Digital MultiMedia Card Controller (SDMMC)

at91bootstrap can be configured to:

  • Download and jump to the third-stage bootloader (for example, Das U-Boot or BusyBox)
  • Download and jump to the Linux® kernel directly, thus it does not require a third-stage bootloader
  • Download and jump to a Real Time Operating System (RTOS)
  • Download and jump to the debugger (JTAG)
  • Configure peripherals and wait for a debugger to take over the JTAG
  • Configure peripherals and jump to your main program

at91bootstrap is written and maintained by Microchip Technology and hosted on GitHub.

Subjects covered in this topic:


Prerequisites

Cross Toolchain

A working cross-toolchain for ARM-based MPU targets is required to complete this topic.

Boot Process

Knowledge of the Boot Process is required as this topic discusses the second-stage bootloader.

Also, see:

Git

If you are new to git there are many online resources. One such resource is the online book Pro Git by Scott Chacon and Ben Straub. It is available in several languages and you can also download the book in eBook formats (EPUB and MOBI) and PDF.

Another excellent resource is the Learn Git tutorial by Atlassian.

Git documentation is also available.


Download - Getting at91bootstrap Source Code

1

Create a Project Directory

It is a good practice to create a project directory to place the source code for a given project. In this way, you can archive the contents so that you may give them to other developers and/or for archival purposes.

For the purposes of this tutorial topic, we’ll name our project directory project_1:

$ mkdir project_1

Using this method, you can archive your project directory with the following commands:

$ cd ~/project_1
$ make tarball

The result will be a *.tar.gz package.

2

Get at91bootstrap

You will get at91bootstrap by copying (git clone) the source code from a remote repository to your project directory:

Change directory to the project directory:

$ cd ~/project_1

Copy (git clone) the at91bootstrap source code to your project directory:

When you git clone from a remote repository, you are creating a copy on your host computer’s project directory (also known to git as the working directory or local directory).

The result of this command will be a copy of at91bootstrap on your host computer with the following directory structure:

/project_1/
  |-- at91bootstrap/
       |-- board/
       |-- config/
       |-- contrib/
       |-- driver/
       |-- fs/
       |-- host-utilities/
       |-- include/
       |-- lib/
       |-- scripts/
       |-- README.txt

Checkout Branch

Once you have cloned at91bootstrap to your project directory, it will contain several branches (versions). You can view all the available branches by issuing a git tag command.

$ git tag
5series_1.0
5series_1.1
5series_1.2
5series_1.3
.
.
v3.9.1
v3.9.1
v3.9.2
v3.9.2-mplabx
v3.9.2-rc1
v3.9.2-rc2
v3.9.3

Since you just cloned the remote repository, the HEAD pointer is pointing to the “master” branch. Think of “master” as the “default” branch after cloning and informs you that it has not diverged from the same branch that is on the GitHub repository. You can see this by issuing a git status command:

$ git status
On branch master
Your branch is up-to-date with "origin/master".
nothing to commit, working tree clean

$ git checkout v3.9.3 -b <temp_branch>

The results of this command is to check out the latest branch (version) that was observed when you issued the git tag command above. The -b switch causes a new branch of the name <temp_branch> to be created. Now, when you issue a git status command:

$ git status
On branch <temp_branch>
Nothing to commit, working tree clean

If you wish to contribute to at91bootstrap, please submit patches for review using pull-request command or to the forum. See the “Contributing” section in the README.txt file.


Updating at91bootstrap Source Code

If during development you require an updated copy of at91bootstrap, you can issue the git pull command:

$ git pull

The results of this command will be to copy updated files from the at91bootstrap GitHub repository and merge them into your project directory.


Dependancies

Starting with version 3.9.3, at91bootstrap requires Python 3.x.y (python3). This is required for the scripts generating the PMECC headers for NAND Flash memories.


Configure using a Default Configuration

Once you have cloned at91bootstrap to your project directory, the next step is to configure the files for building. In this section, you will use a default configuration file supplied by Microchip Technology.

Default configuration (defconfig) files are provided for the many evaluation kits sold by Microchip. They are located in the /project_1/at91bootstrap/board/ directory. At this level you will see directories arranged by processor model/type:

/project_1/
  |-- at91bootstrap/
       |-- board/
            |-- at91sam9260ek/
            |-- at91sam9261ek/
            |-- at91sam9263ek/
            |-- at91sam9g10ek/
            |-- at91sam9g20ek/
            |-- at91sam9m10g45ek/
            |-- at91sam9n12ek/
            |-- at91sam9rlek/
            |-- at91sam9x5ek/
            |-- at91sam9xeek/
            |-- sam9x60_ddr2_sip_eb/
            |-- sam9x60ek/
            |-- sam9x60_sdr_sip_eb/
            |-- sama5d27_som1_ek/
            |-- sama5d27_wlsom1_ek/
            |-- sama5d2_icp/
            |-- sama5d2_lpddr2sip_vb/
            |-- sama5d2_ptc_ek/
            |-- sama5d2_xplained/
            |-- sama5d3x_cmp/
            |-- sama5d3xek/
            |-- sama5d3_xplained/
            |-- sama5d4ek/
            |-- sama5d4_xplained/
       |-- config/
       |-- contrib/
       |-- driver/
       |-- fs/
       |-- host-utilities/
       |-- include/
       |-- lib/
       |-- scripts/
       |-- README.txt

As you enter the processor model/type directory, you will see default configuration files for each of the evaluation kits. Below we are showing the ATSAMA5D27-SOM1-EK1 evaluation kit as an example:

/project_1/
  |-- at91bootstrap/
       |-- board/
            |-- sama5d27_som1_ek/
                 |-- sama5d27_som1_ekqspi_linux_image_dt_defconfig
                 |-- sama5d27_som1_ekqspi_uboot_defconfig
                 |-- sama5d27_som1_eksd1_uboot_defconfig
                 |-- sama5d27_som1_eksd_linux_image_dt_defconfig
                 |-- sama5d27_som1_eksd_uboot_defconfig

The files are annotated with the choice of location of external boot memory. In the case of the ATSAMA5D27-SOM1-EK1 evaluation kit, you can boot at91bootstrap from either QSPI Flash memory (qspi) or SD Memory Card (sd).

Legend:

  • qspi – QSPI Flash Memory
  • sd – SD Memory Card
    • If no number is given, boot from port 0
    • If number is given, boot from indicated port (for example, 1 = port 1)
  • nf – NAND Flash Memory
  • df – Serial/DataFlash™ Memory

The default configure files are also annotated with the choice of what at91bootstrap will load next: either a third-stage bootloader (uboot) and/or application (linux_image_dt).

Legend:

  • uboot – Third-Stage Bootloader
  • linux_image_dt – Linux kernel and Device Tree

For example, this will be the default configuration file you will use in the next section:

sama5d27_som1_eksd_uboot_defconfig

Processor: SAMA5D27-SOM1
Evaluation Kit: SAMA5D27-SOM1-EK
Second Stage: (where is boot.bin located) SD Memory Card, SDMMC_0
Third Stage: (what should at91bootstrap load next) U-Boot
Fourth Stage: (what should U-Boot load next): Linux kernel, mount Root File System (Note: this information is contained in uboot.env)

Default Configure at91bootstrap

Below are the steps to configuring at91bootstrap using a default configuration file.

1

Change directory into the at91bootstrap directory:

$ cd ~/project_1/at91bootstrap

2

Configure at91bootstrap for the desired evaluation board and boot/application settings.

For this example, we will boot at91bootstrap from the SD Memory Card on port 0 and load the third-stage bootloader, U-Boot:

$ make mrproper
$ make sama5d27_som1_eksd_uboot_defconfig

What is the difference between make clean and make mrproper?

make clean - Remove most generated files but keep the config and enough build support to build external modules
make mrproper - Remove all generated files + config + various backup files

Anytime the configuration is changed, you should execute make mrproper.

3

You may customize the default configuration setting using menuconfig:

Menuconfig allows you to view the settings of the default configuration and it also allows you to make any customization. We go into more detail in the next section.

$ make menuconfig

When you execute make menuconfig followed by save, you are creating a .config file that the make command in the next step will use to build at91bootstrap.

For examples of custom changes that can be made to at91bootstrap, see the training topic: Customize a Default Configuration

at91bootstrap_menuconfig.png

You may exit menuconfig by repeatedly typing ESC-ESC.

4

Build at91bootstrap:

$ make

A working cross-toolchain for ARM-based MPU target is required to build at91bootstrap.

Ensure you set the CROSS_COMPILE=<path_to>/<cross_compiler> and ARCH=arm environment variables.

For example, if your cross-compiler executable is arm-linux-gcc then CROSS_COMPILE=<path_to>/arm-linux-

A second method is you may include these as command variables. For example:

$ make ARCH=arm CROSS_COMPILE=<path_to>/<cross_compiler>

The results of the build will be a binary (*.bin) image that can be written to the external memory device selected during configuration. The *.elf image is used by a debugger.

$ cd ~/project_1/at91bootstrap/binaries
$ ls -l
at91bootstrap.bin -> sama5d27_som1_ek-sdcardboot-uboot-3.9.3.bin
boot.bin -> sama5d27_som1_ek-sdcardboot-uboot-3.9.3.bin
sama5d27_som1_ek-sdcardboot-uboot-3.9.3.bin
sama5d27_som1_ek-sdcardboot-uboot-3.9.3.elf
sama5d27_som1_ek-sdcardboot-uboot-3.9.3.map

Note the resulting binary image is named sama5d27_som1_ek-sdcardboot-uboot-3.9.3.bin. There are two symbolic links at91bootstrap.bin and boot.bin pointing to it.

In the next section, you will be shown the steps required to write boot.bin to an external NVM memory.


Writing boot.bin to External NVM Memory

Once boot.bin and has been configured and built, it can be written to external Mass Storage memory (NVM memory). Below are links for how to write to various external NVM memories on evaluation kits and using the SAM-BA® In-System Programmer utility program.

SAM-BA In-System Programmer

ATSAMA5D27-SOM1-EK1 Evaluation Kit

SAM9X60-EK Evaluation Kit


Additional Resources

Linux4SAM


Summary

In this topic, you learned about at91bootstrap program, what it is, where to get it, how to configure and build, and how to write it to external NVM.


What's Next?

© 2020 Microchip Technology, Inc.
Notice: ARM and Cortex are the registered trademarks of ARM Limited in the EU and other countries.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.