SAM-BA Command Line Documentation

Introduction

SAM-BA includes command line interface that provides support for the most common actions:

reading / writing to arbitrary memory addresses and/or peripherals
uploading applets and using them to erase/read/write external memories

The command line interface is designed to be self-documenting.

The main commands can be listed using the "sam-ba --help" command:

Usage: ./sam-ba [options]
SAM-BA Command Line Tool

Options:
  -v, --version                          Displays version information.
  -h, --help                             Displays this help.
  -x, --execute <script.qml>             Execute script <script-file>.
  -p, --port <port[:options:...]>        Communicate with device using <port>.
  -d, --device <device>                  Connected device is <device>.
  -b, --board <board>                    Connected board is <board>.
  -m, --monitor <command[:options:...]>  Run monitor command <command>.
  -a, --applet <applet[:options:...]>    Load and initialize applet <applet>.
  -c, --command <command[:args:...]>     Run command <command>.

Additional help can be obtained for most commands by supplying a "help" parameter that will display their usage.

For example "sam-ba --port help" will display:

Known ports: j-link, serial

Command that take an argument with options (port, monitor, applet) will display even more documentation when called with "help" as option valu

For example "sam-ba --port serial:help" will display:

Syntax: serial:[<port>]:[<baudrate>]
Examples: serial -> serial port (will use first AT91 USB if found otherwise first serial port)
          serial:COM80 -> serial port on COM80
          serial:ttyUSB0:57600 -> serial port on /dev/ttyUSB0, baudrate 57600

Running User Scripts

To run user scripts, a single "-x" must be provided on the command line.

For example: "sam-ba -x myscript.qml".

If the script executes without error, the SAM-BA program will return an error code of 0. Otherwise, if a javascript/QML exception occurs, the tool will return 255.

User script that execute successfully can also override the return code by setting the requested code in "Script.returnCode". For example, this simple user script will just return with code 42:

import QtQuick 2.3
Item {
        Component.onCompleted: {
                Script.returnCode = 42
        }
}

Monitor Commands

We call monitor commands the commands that allow reading and writing from the device address space.

In this mode, a valid port option ("-p" or "--port") must be present on the command line. Several monitor commands can be run sequentially in the same command line invokation.

For example, the following command line will display the CHIPID_CIDR register on a SAMA5D2 device and then read and write into SRAM at address 0x200000:

sam-ba -p serial -m read32:0xfc069000 -m write32:0x200000:0x12345678 -m read16:0x200000 -m read16:0x200002

Running this command line with a SAMA5D2 connected will display:

read32(0xfc069000)=0x8a5c08c0
write32(0x00200000,0x12345678)
read16(0x200000)=0x5678
read16(0x200002)=0x1234

The monitor commands supported may depend on the connection type selected, but usually include:

Command	1st argument	2nd argument	3rd argument	Description
read8	address	none	none	Read a byte from address
read16	address	none	none	Read a half-word (16-bit) from address address
read32	address	none	none	Read a word (32-bit) from address address
read	filename	address	length	Read length bytes from address address and write them to file filename
write8	address	value	none	Write byte value to address
write16	address	value	none	Write half-word value to address address
write32	address	value	none	Write word value to address address
write	filename	address	none	Read contents of file filename and write it at address address
execute	address	none	none	Execute code at address address

Address, length and value arguments can be provided in hexadecimal (prefixed with "0x") or in decimal.

Applet Commands

External memories can be programmed by uploading small programs to the device that are called applets and communicating with them using a shared memory region.

Running applet commands requires several parameters on the command line:

a port to connect to the device (option "-p" or "--port")
either a device option (option "-d" or "--device") or a board option (option "-b" or "--board")
an applet to use (option "-a" or "--applet")
zero or more applet commands to run (option "-c" or "--command")

Devices and Boards

The list of supported devices can be displayed by using "sam-ba -d help". Running this command with SAM-BA 3.2 will display:

Known devices: sam9xx5, sama5d2, sama5d3, sama5d4, samv71

For ease of use, several aliases are accepted by the tool: for example using "sama5d2" is equivalent to "sama5d27".

Boards also select a device, but also a set of settings that are available to the applets. For example, selecting board "sama5d2-xplained" will pre-configure the system for:

SPI0 IOSET1 NPCS0 66Mhz
QSPI0 IOSET3 66Mhz

It is always possible to override/provide applet initialization settings regardless of the configuration set or not by the device/board options.

Applets

The list of applets available depends on the device selected. It is possible to get a list of the supported applets for the device by running "sam-ba -d <device> -a help":

sam-ba -d sama5d2 -a help

Known applets: bootconfig, lowlevel, serialflash, qspiflash, nandflash

Each applet may provide different commands, but most external memory applets will support the commands in section Common Memory Applet Commands.

Documentation on the supported commands can be obtained by running "sam-ba -d <device> -a <applet> -c help".

For example the QSPI Flash applet for the SAMA5D2 supports commands: erase, read, write, writeboot, verify, verifyboot.

The Boot Config applet for the SAMA5D2 is not an external memory applet and only supports these commands: readcfg, writecfg.

Applets can have some parameters that may be provided either by the board preset or explicitely. Help on the parameters can be obtained by using an "help" argument. For example:

sam-ba -d sama5d2 -a qspiflash:help

Syntax: qspiflash:[<instance>]:[<ioset>]:[<frequency>]
Examples: qspiflash -> QSPI flash applet using default board settings
          qspiflash:0:3:66 -> QSPI flash applet using fully custom settings (QSPI0, IOSET3, 66Mhz)
          qspiflash:::20 -> QSPI flash applet using default board settings but frequency set to 20Mhz

Common Memory Applet Commands

The following common commands are often provided by external memory applets.

Command	1st argument	2nd argument	3rd argument	Description
erase	address*	length*	none	Erase length bytes starting at address
read	filename	address*	length*	Read length bytes starting at address into file filename
write	filename	address*	none	Write content of file filename to memory starting at address
writeboot	filename	none	none	Prepare content of file filename for booting and write it to memory starting at address
verify	filename	address*	none	Compare content of file filename with memory starting at address
verifyboot	filename	none	none	Prepare content of file filename for booting and compare it to memory starting at address

Argument noted with a star (*) in the previous table are not required and may be ommited. A suitable default will be used in this case: 0 for the address and the remaining size between address and the end of the memory for the length. For example, for a 4MB memory, the following commands are equivalent:

erase:0:4194304
erase::4194304
erase:0
erase

Depending on the applet, some commands may not be supported, or there may be some additional ones. The syntax of the commands may also change between applets. Please use "-c help" to get the list of supported commands and their usage.

SAMA5D2 Applet Commands and Examples

The SAMA5D2 external memory applets are: serialflash, qspiflash and nandflash.

Except for initialization parameters, usage of these applets is the same. For example, to erase the first 64KB, write and verify a 30448 bytes boot program on the serialflash of a SAMA5D2-Xplained:

sam-ba -p serial -b sama5d2-xplained -a serialflash -c erase -c writeboot:program.bin -c verifyboot:program.bin

Opening serial port 'ttyACM0'
Connection opened.
Detected memory size is 4194304 bytes.
Executing command 'erase:0:65536'
Erased 65536 bytes at address 0x00000000 (100.00%)
Executing command 'writeboot:program.bin'
Patched file length (30448) at offset 20
Added 16 bytes of padding to align to page size
Wrote 30464 bytes at address 0x00000000 (100.00%)
Executing command 'verifyboot:program.bin'
Patched file length (30448) at offset 20
Added 16 bytes of padding to align to page size
Verified 30464 bytes at address 0x00000000 (100.00%)
Connection closed.

The SAMA5D2 boot configuration can also be set using the command line via the boot config applet. The readcfg and writecfg commands can be used to get/set the Boot Sequence Register (BSCR) and the Boot Config Word either in BUREG registers or in FUSE. Please refer to SAMA5D2 Datasheet section "15.4 Boot configuration" for more details on the SAMA5D2 boot sequence.

To configure the boot to use BSCR/BUREG1 and boot on SPI0 IOSET2 or SDMMC0 and keep the default UART and JTAG settings, the following command can be used (line broken for easier reading):

sam-ba -p serial -d sama5d2 -a bootconfig -c writecfg:bscr:valid,bureg1
        -c writecfg:bureg1:QSPI0_DISABLED,QSPI1_DISABLED,SPI0_IOSET2,SPI1_DISABLED,NFC_DISABLED,SDMMC0,SDMMC1_DISABLED,EXT_MEM_BOOT

Opening serial port 'ttyACM0'
Connection opened.
Executing command 'writecfg:bscr:valid,bureg0'
Setting BSCR to 0x00000005
Executing command 'writecfg:bureg1:QSPI0_DISABLED,QSPI1_DISABLED,SPI0_IOSET2,SPI1_DISABLED,NFC_DISABLED,SDMMC0,SDMMC1_DISABLED,EXT_MEM_BOOT'
Setting BUREG1 to 0x00040bdf
Connection closed.

The current boot configuration can be displayed using this command:

sam-ba -p serial -d sama5d2 -a bootconfig -c readcfg:bscr -c readcfg:bureg0
        -c readcfg:bureg1 -c readcfg:bureg2 -c readcfg:bureg3 -c readcfg:fuse

Opening serial port 'ttyACM0'
Connection opened.
Executing command 'readcfg:bscr'
BSCR=0x00000005 / BUREG1,VALID
Executing command 'readcfg:bureg0'
BUREG0=0x00040bdf / QSPI0_DISABLED,QSPI1_DISABLED,SPI0_IOSET2,SPI1_DISABLED,NFC_DISABLED,SDMMC0,SDMMC1_DISABLED,UART1_IOSET1,JTAG_IOSET1,EXT_MEM_BOOT
Executing command 'readcfg:bureg1'
BUREG1=0x00040bdf / QSPI0_DISABLED,QSPI1_DISABLED,SPI0_IOSET2,SPI1_DISABLED,NFC_DISABLED,SDMMC0,SDMMC1_DISABLED,UART1_IOSET1,JTAG_IOSET1,EXT_MEM_BOOT
Executing command 'readcfg:bureg2'
BUREG2=0x00000000 / QSPI0_IOSET1,QSPI1_IOSET1,SPI0_IOSET1,SPI1_IOSET1,NFC_IOSET1,SDMMC0,SDMMC1,UART1_IOSET1,JTAG_IOSET1
Executing command 'readcfg:bureg3'
BUREG3=0x00000000 / QSPI0_IOSET1,QSPI1_IOSET1,SPI0_IOSET1,SPI1_IOSET1,NFC_IOSET1,SDMMC0,SDMMC1,UART1_IOSET1,JTAG_IOSET1
Executing command 'readcfg:fuse'
FUSE=0x00040000 / QSPI0_IOSET1,QSPI1_IOSET1,SPI0_IOSET1,SPI1_IOSET1,NFC_IOSET1,SDMMC0,SDMMC1,UART1_IOSET1,JTAG_IOSET1,EXT_MEM_BOOT
Connection closed.

Contents