Home · |
SAM-BA includes command line interface that provides support for the most common actions:
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
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 } }
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.
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:
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: sam9x60, 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:
It is always possible to override/provide applet initialization settings regardless of the configuration set or not by the device/board options.
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
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:
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.
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 "16.5 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.
Copyright © 2018 Microchip Technology | SAM-BA Documentation |