Home ·

- Getting started with SAM-BA on SAMA5D3 devices

# Getting started with SAM-BA on SAMA5D3 devices

## Connecting to the SAM-BA monitor

For USB connection, the host running sam-ba should be connected to the USB device port of the SAMA5D3 board design. On SAMA5D3-Xplained boards, this port is labeled USB-A (J6).

## Predefined boards and customer board designs

The sam-ba program comes with predefined sama5d3-xplained and sama5d3-ek boards that set default values for different settings such as the applet console or memory controller instances.

Those predefined boards can be selected with the -b sama5d3-xplained or -b sama5d3-ek options on the sam-ba command line.

However the -d sama5d3 option should be used instead on customer board designs not to load any default settings. Instead, additionnal parameters may be passed to the -d sama5d3:<console_instance>:<console_ioset> option to select the applet console. The applet console, when enabled, is used by any applet to print its traces.

Also, default memory controller settings, if any, can be overridden too, passing additional arguments to the -a <applet> option for the applet managing the memory controller.

## Supported applets

The list of supported applets can be displayed with the following command:

    $ sam-ba -p serial -d sama5d3 -a help
    Known applets: lowlevel, extram, sdmmc, serialflash, nandflash, reset

Applet | Short description | Examples
--- | --- | ---
extram | Initialize the external RAM (not needed by any other applets) |
lowlevel | Setup the clock tree (only needed by the extram applet) |
nandflash | Manage raw NAND flash memories connected to the EBI and driven by the NFC | Programming a raw NAND flash
reset | Reset the target device |
sdmmc | Manage e.MMC and SD Cards connected to some HSMCI instance | Programming a SD Card or e.MMC
serialflash | Manage (Q)SPI NOR flash memories connected to some SPI instance | Programming a SPI NOR flash

## Linux4SAM demos

Examples to follow are all based on material provided by Linux4SAM demos for SAMA5D3 Xplained boards or custom builds from Linux4SAM sources.

File name(s) | Description
--- | ---
at91bootstrap-sama5d3_xplained.bin or BOOT.bin | at91bootstrap loaded in SRAM0 then executed by the ROM Code
u-boot.bin or u-boot-sama5d3-xplained.bin | u-boot loaded in external RAM then executed by at91bootstrap
u-boot-env.bin or uboot.env | u-boot environment variables loaded by u-boot
sama5d3_xplained.itb | a FIT image containing the Linux kernel image and its device-tree binary
microchip-headless-image-sama5d3-xplained.ubi | the Linux root file-system (NAND flash only)

## Programming a SPI NOR flash

    $ sam-ba -p serial -b sama5d3-xplained -t 5 -a serialflash -c erase
    $ sam-ba -p serial -b sama5d3-xplained -t 5 -a serialflash -c writeboot:at91bootstrap-sama5d3_xplained.bin -c verifyboot:at91bootstrap-sama5d3_xplained.bin.bin
    $ sam-ba -p serial -b sama5d3-xplained -t 5 -a serialflash -c write:u-boot-env.bin:0x00006000 -c verify:u-boot-env.bin:0x00006000
    $ sam-ba -p serial -b sama5d3-xplained -t 5 -a serialflash -c write:u-boot-sama5d3-xplained.bin:0x00008000 -c verify:u-boot-sama5d3-xplained.bin:0x00008000
    $ sam-ba -p serial -b sama5d3-xplained -t 5 -a serialflash -c write:sama5d3_xplained.itb:0x000A8000 -c verify:sama5d3_xplained.itb:0x000A8000

SPI NOR flashes are likely to be too small to store the Linux root file-system; this should be programmed into another NVM.

If the SPI NOR flash memory is connected to a custom board design, then additional parameters should be passed to the -a serialflash option in above examples.

The list of thos parameters is given by the command:

    $ sam-ba -p serial -d sama5d3 -a serialflash:help
    Syntax: serialflash:[<instance>]:[<ioset>]:[<npcs>]:[<frequency>]
    Parameters:
        instance   SPI controller instance
        ioset      I/O set
        npcs       SPI chip select number
        frequency  SPI clock frequency in MHz
    Examples:
        serialflash           use default board settings
        serialflash:0:1:0:66  use fully custom settings (SPI0, IOSET1, NPCS0, 66Mhz)
        serialflash::::20     use default board settings but force frequency to 20Mhz

Supported <instance>, <ioset> and <npcs> for SPI on SAMA5D3 device are listed here.

## Programming a SDCard or e.MMC user partition

In the following example, the sdcard.img file is a raw image of a SD Card, hence starting with a Master Boot Record (MBR) containing a valid partition table. The first partition is formatted with a FAT32 file-system, which gathers at least four files in its root directory:

- BOOT.bin
- u-boot.bin
- uboot.env
- sama5d3_xplained.itb

The second partition is formatted in EXT4 and contains the root file-system used by the Linux kernel.

    $ sam-ba -p serial -b sama5d3-xplained -t 5 -a sdmmc -c write:sdcard.img

If the SD Card or e.MMC memory is connected to a customer board design, then additional parameters should be passed to the -a sdmmc option in above examples.

The list of those parameters is given by the command:

    $ sam-ba -p serial -d sama5d3 -a sdmmc:help
    Syntax: sdmmc:[<instance>]:[<ioset>]:[<partition>]:[<bus_width>]:[<voltages>]
    Parameters:
        instance   SDMMC controller number
        ioset      SDMMC I/O set
        partition  Partition number (0=user partition, x>0=boot partition x)
        bus_width  Data bus width (0=controller max, 1=1-bit, 4=4-bit, 8=8-bit)
        voltages   Supported voltages (bitfield: 1=1.8V, 2=3.0V, 4=3.3V)
    Examples:
        sdmmc           use default board settings
        sdmmc:0:1:1:8:5 use fully custom settings (SDMMC0, IOSET1, first boot partition, 8-bit, 1.8V/3.3V)
        sdmmc:0::1      use default board settings but force use of SDMMC0, first boot partition

Supported <instance> and <ioset> for SDMMC on SAMA5D3 device are listed here.

## Programming a raw NAND flash

    $ sam-ba -p serial -b sama5d3-xplained -t 5 -a nandflash -c erase
    $ sam-ba -p serial -b sama5d3-xplained -t 5 -a nandflash -c writeboot:at91bootstrap-sama5d3_xplained.bin -c verifyboot:at91bootstrap-sama5d3_xplained.bin
    $ sam-ba -p serial -b sama5d3-xplained -t 5 -a nandflash -c write:u-boot-sama5d3-xplained.bin:0x00040000 -c verify:u-boot-sama5d3-xplained.bin:0x00040000
    $ sam-ba -p serial -b sama5d3-xplained -t 5 -a nandflash -c write:u-boot-env.bin:0x00140000 -c verify:u-boot-env.bin:0x00140000
    $ sam-ba -p serial -b sama5d3-xplained -t 5 -a nandflash -c write:sama5d3_xplained.itb:0x00180000 -c verify:sama5d3_xplained.itb:0x00180000
    $ sam-ba -p serial -b sama5d3-xplained -t 5 -a nandflash -c write:microchip-headless-image-sama5d3-xplained.ubi:0x00800000 -c verify:microchip-headless-image-sama5d3-xplained.ubi:0x00800000

If the raw NAND flash is connected to a custom board design, then additional parameters should be passed to the -a nandflash option in above examples.

The list of those parameters is given by the command:

    $ sam-ba -p serial -d sama5d3 -a nandflash:help
    Syntax: nandflash:[<ioset>]:[<bus_width>]:[<header>]
    Parameters:
        ioset      I/O set
        bus_width  NAND bus width (8/16)
        header     NAND header value
    Examples:
        nandflash                 use default board settings
        nandflash:2:8:0xc0098da5  use fully custom settings (IOSET2, 8-bit bus, header is 0xc0098da5)
        nandflash:::0xc0098da5    use default board settings but force header to 0xc0098da5
    For information on NAND header values, please refer to SAMA5D3 datasheet section "11.4.4 Detailed Memory Boot Procedures".

Supported <ioset> for the NAND flash on SAMA5D3 devices are listed here.

## Secure Boot Mode

In secure boot mode, the ROM code no longer executes its non-secure SAM-BA monitor but instead runs its secure SAM-BA monitor. Hence, the serial or j-link ports cannot be used; the secure port must be used instead.

First, the secure boot mode must be enabled:

    $ sam-ba -p secure -d sama5d3 -m enable_secure:set-secure-mode.cip

Once the secure boot mode has been enabled, the customer-key must be programmed into fuses.}

Then the sam-ba command to program the customer key is:

    $ sam-ba -p secure -d sama5d3 -m write_customer_key:customer-key.cip