Skip to Content

at91bootstrap: A Second Stage Bootloader for Microchip MPUs

Last modified by Microchip on 2024/06/20 12:44
Contents

Introduction

This training topic describes at91bootstrap, a second-stage bootloader for Microchip Technology Arm®-based microprocessors (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 an external NVM (SD Memory Card, MultiMedia Card (MMC), Embedded MultiMedia Card (e.MMC), NAND Flash, Serial Flash, NOR Flash). The first-stage bootloader (contained in the ROM Boot Code of the MPU) will load at91bootstrap from external NVM depending on its configuration. Refer to the device datasheet for specific details on their boot strategies. Additional information is available at:

If configured to do so, at91bootstrap 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.

Back to top

Prerequisites

Cross Toolchain

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

Back to top

Boot Process

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

Also, see:

Back to top

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.

Back to top

Download - Getting at91bootstrap Source Code

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.

Get at91bootstrap

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

Change the directory to the project directory:

$ cd ~/project_1

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

$ git clone git:~/~/github.com/linux4sam/at91bootstrap.git

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##

Back to top

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.

Back to top

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.

Back to top

Dependencies

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.

Back to top

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. The following is an example showing the ATSAMA5D27-SOM1-EK1 evaluation kit:

/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 NOR Flash memory (qspi) or SD Memory Card (sd).

Back to top

Legend:

  • qspi– NOR 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).

Back to top

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)

Back to top

Default Configure at91bootstrap

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

Change the directory into the at91bootstrap directory:

$ cd ~/project_1/at91bootstrap

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. 

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: at91bootstrap: Customizing a Default Configuration

at91bootstrap menuconfig

You may exit menuconfig by repeatedly typing ESC-ESC.

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.

Back to top

Writing boot.bin to External NVM Memory

Once boot.bin has been configured and built, it can be written to Mass Storage memory (external 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.

Back to top

SAM-BA In-System Programmer

Back to top

ATSAMA5D27-SOM1-EK1 Evaluation Kit

Back to top

SAM9X60-EK Evaluation Kit

Back to top

SAM9X60-Curiosity Development Board

Back to top

Additional Resources

Back to top

Summary

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

Back to top

What's Next?

 Back to top