Home ·
  • SAM-BA Command Line Documentation
  • SAM-BA Command Line Documentation

    Introduction

    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

    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:

    Command1st argument2nd argument3rd argumentDescription
    read8addressnonenoneRead a byte from address
    read16addressnonenoneRead a half-word (16-bit) from address address
    read32addressnonenoneRead a word (32-bit) from address address
    readfilenameaddresslengthRead length bytes from address address and write them to file filename
    write8addressvaluenoneWrite byte value to address
    write16addressvaluenoneWrite half-word value to address address
    write32addressvaluenoneWrite word value to address address
    writefilenameaddressnoneRead contents of file filename and write it at address address
    executeaddressnonenoneExecute 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:

    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: 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.

    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.

    Command1st argument2nd argument3rd argumentDescription
    eraseaddress*length*noneErase length bytes starting at address
    readfilenameaddress*length*Read length bytes starting at address into file filename
    writefilenameaddress*noneWrite content of file filename to memory starting at address
    writebootfilenamenonenonePrepare content of file filename for booting and write it to memory starting at address
    verifyfilenameaddress*noneCompare content of file filename with memory starting at address
    verifybootfilenamenonenonePrepare 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.

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