AT91Bootstrap 3.x series

Introduction

This page is dedicated to AT91Bootstrap 3.x series. For newer versions of AT91Bootstrap, check this page AT91Bootstrap4.

AT91Bootstrap is the 2nd level bootloader for Atmel AT91 SoC 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 of DataFlash), serial EEPROM, SD Card, etc.) to main memory and to start it.

Boot strategies

AT91 chips embed a boot ROM code. It is enabled depending on BMS (Boot Mode Select) pin state on reset. The ROM code scans the contents of different media like serial FLASH, NAND FLASH, SD/MMC Card 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.

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

For more information on this topic, please check the corresponding SAM product datasheet section Boot Strategies.

ROM Code boot Sequence example

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

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

Note need a reset to make BSC_CR effective. And BSC_CR will be restored to factory value if power is removed.

Build AT91Bootstrap from sources

Setup ARM Cross Compiler

If using an old toolchain, there have been reported issues. Please see the document KNOWN ISSUES for your release which is inside the source code. We always recommend using up-to-date toolchains.

• Ubuntu:
  In Ubuntu, you can install the ARM Cross Compiler by doing:

  sudo apt-get install gcc-arm-linux-gnueabi
  export CROSS_COMPILE=arm-linux-gnueabi-
     

• Others:
  For others, you can download the Linaro cross compiler and setup the environment by doing:

  wget -c https://releases.linaro.org/components/toolchain/binaries/7.3-2018.05/arm-linux-gnueabi/gcc-linaro-7.3.1-2018.05-x86_64_arm-linux-gnueabi.tar.xz
  tar xf gcc-linaro-7.3.1-2018.05-x86_64_arm-linux-gnueabi.tar.xz
  export CROSS_COMPILE=`pwd`/gcc-linaro-7.3.1-2018.05-x86_64_arm-linux-gnueabi/bin/arm-linux-gnueabi-
     

Other dependencies

Starting with version 3.9.3, AT91bootstrap changed the python requirements for the pmecc header generating scripts to Python3.
Version 3.9.2 is equivalent with version 3.9.3 but continues to use Python2.
Yocto Project version 3.1 (Dunfell) and later , have obsoleted Python2, thus must use Python3. That is why Yocto Dunfell and later use 3.9.3 or later versions with Python3.
Future versions of AT91Bootstrap will most likely be Python3 only.

Build AT91Bootstrap

This section describes how to get source code from the git repository, how to configure with the default configuration, how to customize AT91Bootstrap based on the default configuration and finally to build AT91Bootstrap to produce the binary. take the default configuration to download U-Boot from NandFlash for example.

Get AT91Bootstrap Source Code

You can easily download AT91Bootstrap source code on the at91bootstrap git repository.

To get the source code, you should clone the repository by doing:

$ git clone https://github.com/linux4sam/at91bootstrap.git
Cloning into 'at91bootstrap'...
remote: Enumerating objects: 17621, done.
remote: Counting objects: 100% (3324/3324), done.
remote: Compressing objects: 100% (1029/1029), done.
remote: Total 17621 (delta 2465), reused 3102 (delta 2285), pack-reused 14297
Receiving objects: 100% (17621/17621), 5.65 MiB | 4.65 MiB/s, done.
Resolving deltas: 100% (13459/13459), done.
$ cd at91bootstrap/

Configure AT91Bootstrap

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

sam9x60ekqspi_uboot_defconfig
sam9x60eksd_uboot_defconfig
sam9x60eknf_uboot_defconfig

Tips: qspi means to read quad-SPI serial flash, sd means to read mmc card, nf means to read nand flash

You can configure AT91Bootstrap to load U-Boot binary from SD Card by doing:

$ make mrproper
$ make sam9x60eksd_uboot_defconfig

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

Customize AT91Bootstrap

If the default configuration doesn't meet your need, after configuring with the default configuration, you can customize it by doing:

$ make menuconfig

Now, in the menuconfig dialog, you can easily add or remove some features to/from AT91Bootstrap as the same way as kernel configuration.
Move to <Exit> with arrows and press this button hitting the Enter key to exit from this screen.

Build AT91Bootstrap

Then you can build the AT91Bootstrap binary by doing:

$ make

If the building process is successful, the final .bin image is build/binaries/at91bootstrap.bin.

Program AT91Bootstrap binary into nandflash

Using SAM-BA to flash AT91Bootstrap to board

Launch SAM-BA tools

• According to this section (take sama5d3xek as example) make sure that the chip can execute the SAM-BA Monitor.

Configure NAND ECC config

Programming AT91Bootstrap

• Choose Send Boot File action, then press Execute button to select the at91bootstrap binary file and to program the binary to the NandFlash

Using U-Boot to flash AT91Bootstrap

Setup PMECC header for different type of board

When ROM code load AT91Bootstrap in nandflash, at first ROM code will check the header to know what kind of ecc that binary is stored in nand.

So the header is made of 52 times the same 32-bit word, total in 0xd0 bytes, each 32-bit word in made in following format:

For different EK boards, the pmecc header is listed in following:

# at91sam9x5ek & at91sam9n12ek
# 2 bit pmecc in 512 byte sector, one page has 4 sectors, spare size: 64, ecc offset: 48
setenv pmecc_header 0xc0c00405

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

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

Load AT91Bootstrap binary and setup the 6th vector (offset is 0x14) as the file size

• Following is U-Boot commands that can flash at91bootstrap to 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 following commands to programming at91bootstrap to nandflash in U-Boot:
  run flash_bootstrap_from_tftp or run flash_bootstrap_from_mmc

Contributing to AT91Bootstrap

If the system board that you have is not listed, then you will need to port AT91Bootstrap to your hardware platform. To do this, follow these steps:

1. Create a new directory to hold your board specific code under contrib/board/ directory. Add any files you need. In your board directory, you will need at least the "board.mk", a ".c", ".h", "Config.in.board", and "Config.in.boardname".
2. Create the necessary default configuration files such as "df_uboot_defconfig" in your new board directory.
3. Add(source) your board's "Config.in.board" in "contrib/board/Config.in.board" file.
4. Add(source) your board's "Config.in.boardname" in the "contrib/board/Config.in.boardname" file.
5. Add your board's ".h" in the "contrib/include/contrib_board.h" file.
6. Run "make df_uboot_defconfig" with your new name.
7. Type "make", and you should get the final .bin image can be found under the binaries/ directory.

To contribute to AT91Bootstrap you should submit the patches for review to the github pull-request facility directly.

Maintainers:

Eugen Hristev eugen.hristev at microchip dot com

Nicolas Ferre nicolas.ferre at microchip dot com

Known Issues

About the latest version, some issues are found not fixed, please see the document KNOWN ISSUES with the project.

Recent FAQ

AT91Bootstrap

• Sama 7 d 65 Curiosity Buildroot BSR: SAMA7D65 ready-made Buildroot images & BSR. (Sama7d65Curiosity)
• SDCard Boot Notice: How to boot up the board from SD card. (Sama5d29Curiosity, Sam9x75Curiosity, Sam9x60Curiosity, Sama5d2-icp, Sam9x60EK, Sama5d27WLSom1EK, Sama5d27Som1EK, Sama5d2PtcEK, Sama5d2Xplained, Sama5d4Xplained, Sama5d4ek, Sama5d3Xplained, Sama5d3xek, AT91sam9x5-ek)
• SOM 1 EKe MMCSupport: . (Sama5d27Som1EK)
• Audio Clocks On SAM 9 X 60: How to configure PLLA in AT91bootstrap to generate clocks for SAM9X60. (Sam9x60EK)
• AT 91 Bootstrap Debug Eclipse: Debug AT91Bootstrap. (Sama5d4Xplained, Sama5d4ek, Sama5d3Xplained, Sama5d3xek)