Skip to Content

SAM-BA® In-System Programmer - Applets

Last modified by Microchip on 2024/06/20 12:33

Introduction

SAM-BA® In-System Programmer Applets are binary programs that the SAM-BA Host and Monitor can load and execute in the target device RAM to provide additional features and capabilities.

Applet programs are loaded and executed in the target device RAM by the SAM-BA Host program by including the -a, --applet option on the command line:

sam-ba -p <port> -d <device> -a <applet>[:arg1>:<arg2>:<arg3>:…]

or

sam-ba -p <port> -b <board> -a <applet>[:arg1>:<arg2>:<arg3>:…]

Alert: DO NOT use the Monitor -m, --monitor or Scripting -e, --execute options on the same command line with the Applet -a, --applet option.

Applet programs support commands and arguments to customize their behavior. The command has the following structure:

sam-ba -p <port> -d <device> -a <applet> [-c <command1[:<arg1_1>:<arg1_2>:…]

More than one Applet command can be added to the command line:

sam-ba -p <port> -d <device> -a <applet> [-c <command1>[:<arg1_1>:<arg1_2>:…] -c <command2>[:<arg2_1>:<arg2_2>:…]

-c <command3>[:<arg3_1>:<arg3_2>:…] …]

Applet Console

Applet programs provide tracing information to the Target Console (also referred to as the Applet Console). The Target Console is typically configured by the boot configuration in the target device. However, the console can be explicitly configured by the console_instance and console_ioset arguments of the-d, --device option.

sam-ba -p <port> -d <device>:<console_instance>:<console_ioset>

Example:

$ sam-ba -p serial -d sama5d2:help
Syntax: sama5d2:[<instance>]:[<ioset>]
Parameters:
    instance   Serial console peripheral number
    ioset      Serial console I/O set
Examples:
    sama5d2       use default device/board settings
    sama5d2:1:2   use fully custom settings (peripheral number 1, I/O set 2)
    sama5d2::2    use default device/board settings but force use of I/O set 2
Note:
    Peripheral numbers and I/O sets are device specific. Please see device documentation in 'doc' directory.

Tracelevel Verbosity

The level of Applet Console verbosity can be controlled with the -t, --tracelevel option:

sam-ba -p <port> -d <device> -t n -a <applet> [-c <command1[:<arg1_1>:<arg1_2>:…]

where n specifies the level:

0: no trace
1: fatal error
2: error
3: warning
4: info
5: debug

Applets

A listing of supported Applets for a given target device can be found with the help argument:

sam-ba -p <port> -d <device> -a help


Back to Top

Read and Write Boot Configuration bootconfig

The bootconfig applet reads and writes the Boot Configuration Word (SAMA5D2 Series)/Boot Configuration Packet (SAM9X60).

The bootconfig applet applies to the following devices. Documentation is available in the ../sam-ba/doc/ directory.

Alert: The boot configuration is specific to each device. For detailed information, refer to the device datasheet.

bootconfig Command Structure

The bootconfig applet has the following command structure (SAMA5D27 shown in the example below):

$ sam-ba -p serial -d sama5d27 -a bootconfig -c help
* readcfg - read boot configuration
Syntax:
    readcfg:(fuse|bureg0|bureg1|bureg2|bureg3|bscr)
Examples:
    readcfg:fuse    read boot configuration word in fuses
    readcfg:bureg0  read boot configuration word in BUREG0
    readcfg:bscr    read boot sequence register (BSCR)
* writecfg - write boot configuration
Syntax:
    writecfg:(fuse|bureg0|bureg1|bureg2|bureg3|bscr):<configuration>
Examples:
    writecfg:fuse:0x440000       write boot configuration word 0x440000 in fuses
    writecfg:bureg0:0x40fcf      write boot configuration word 0x40fcf in BUREG0
    writecfg:bureg2:QSPI0_IOSET2,EXT_MEM_BOOT  write boot configuration word 0x40001 in BUREG2
    writecfg:bscr:4              write boot sequence register (BUREG0, VALID)
    writecfg:bscr:bureg0,valid   write boot sequence register (BUREG0, VALID)
Configuration value can be either a number or a sequence of tokens separated by commas.
    BSCR tokens:
        BUREG0*, BUREG1, BUREG2, BUREG3 -> to select which BUREG to use
        VALID -> to validate the BSCR and use the selected BUREG
    BUREG/Fuse tokens:
        UART1_IOSET1*, UART0_IOSET1, UART1_IOSET2, UART2_IOSET1,
UART2_IOSET2, UART2_IOSET3, UART3_IOSET1, UART3_IOSET2,
UART3_IOSET3, UART4_IOSET1, UART_DISABLED,
        JTAG_IOSET1*, JTAG_IOSET2, JTAG_IOSET3, JTAG_IOSET4,
        QSPI0_IOSET1*, QSPI0_IOSET2, QSPI0_IOSET3, QSPI0_DISABLED,
        QSPI1_IOSET1*, QSPI1_IOSET2, QSPI1_IOSET, QSPI1_DISABLED,
        SPI0_IOSET1*, SPI0_IOSET2, SPI0_DISABLED,
        SPI1_IOSET1*, SPI1_IOSET2, SPI1_IOSET3, SPI1_DISABLED,
        NFC_IOSET1*, NFC_IOSET2, NFC_DISABLED,
        SDMMC0*, SDMMC0_DISABLED,
        SDMMC1*, SDMMC1_DISABLED,
        EXT_MEM_BOOT,
        QSPI_XIP_MODE,
        DISABLE_BSCR,
        DISABLE_MONITOR,
        SECURE_MODE,
    Tokens with a star (*) are selected by default if no token from the same line is provided (field value is 0).
    Please refer to SAMA5D2 Datasheet section "16.5 Boot configuration" for information on boot settings.


Back to Top

Initialize External RAM extram

The extram applet initializes external RAM.

The extram applet applies to the following devices. Documentation is available in the ../sam-ba/doc/ directory.

Additional documentation is located in the document directory ../doc/extram.html.

Alert: The Initialize Device Clock Tree lowlevel applet should be executed prior to executing the Initialize External RAM extram applet. The lowlevel applet initializes the external RAM bus clock frequency.

extram Command Structure

The extram applet has the following command structure:

$ sam-ba -p serial -d <device> -a lowlevel
$ sam-ba -p serial -d <device> -a extram:help
Syntax: extram:[<preset>]
Parameters:
    preset  External RAM chip
Examples:
    extram    use default board settings
    extram:1  use preset 1 for type of external RAM

The extram applet accepts a single <preset> parameter which tells the applet which SDRAM chip is connected to the device. A list of preset parameter values by device is located in the ../doc/extram.html directory.


Back to Top

Enable Internal RC internalrc

The internalrc applet forces the selection of the internal 12 MHz RC oscillator as the source of the MAIN Clock (MAINCK).

Alert: Before executing the bootconfig writecfg:fuse command, you must execute the internalrc command once per RESET.

internalrc Command Structure

The internalrc applet must be called once after each RESET before executing the bootconfig writecfg:fuse command

The internalrc applet has the following command structure:

$ sam-ba -p serial -d <device> -a internalrc

There are no parameters.

Back to Top

Initialize Device Clock Tree lowlevel

The lowlevel applet initializes the device clock tree: PLLA, CPU Clock, and Master Clock (MCK).

The lowlevel applet applies to the following devices. Documentation is available in the ../sam-ba/doc/ directory.

Additional documentation is located in the ../doc/lowlevel.html document directory.

Alert: The Initialize Device Clock Tree lowlevel applet should be executed prior to executing the Initialize External RAM extram applet. The lowlevel applet initializes the external RAM bus clock frequency.

lowlevel Command Structure

The lowlevel applet has the following command structure:

​ $ sam-ba -p serial -d <device> -a lowlevel

The lowlevel applet does not require a parameter; with the exception of the SAM9X60 device. In this case, the help parameter shows the available parameters. SAM9X60 presets are listed in the ../doc/lowlevel.html document directory.

​$ sam-ba -p serial -d sam9x60 -a lowlevel:help
Syntax: lowlevel:[<preset>]
Parameters:
    preset  System clock configuration
Examples:
    lowlevel    use default board settings if defined, preset 0 otherwise
    lowlevel:0  use preset 0 for system clock configuration

Back to Top

Program External NAND Flash Memory nandflash

The nandflash applet initializes the Static Memory Controller (SMC) or the NAND Flash Controller (NFC) and can perform read, write, erase, and verify functions.

The nandflash applet applies to the following devices. Documentation is available in the ../sam-ba/doc/ directory.

Additional documentation is located in the document directory ../doc/nandflash.html.

nandflash Command Structure

The nandflash applet has the following command structure:

​$ sam-ba -p <port> -d <device> -a nandflash -c <command>

Initialize Controller

Initialization of the nandflash applet has the following command structure:

$ sam-ba -p <port> -d <device> -a nandflash ​

A list of parameters to initialize the nandflash applet can be displayed with the following command (using the SAMA5D2 series device as an example):

​$ sam-ba -p serial -d sama5d2 -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

A list of parameters is located in the document directory: ../doc/nandflash.html.

Supported Commands

A list of commands supported by the nandflash controller can be displayed with the following command:

​$ sam-ba -p <port> -d <device> -a nandflash -c help

read Command

The read command reads data from NAND Flash into a binary file.

​$ sam-ba -p serial -b sam9x60-ek -a nandflash -c read:help
* read - read from memory to a file
Syntax:
    read:<filename>:[<addr>]:[<length>]
Examples:
    read:firmware.bin              read all to firmware.bin
    read:firmware.bin:0x1000       read from 0x1000 to end into firmware.bin
    read:firmware.bin:0x1000:1024  read 1024 bytes from 0x1000 into firmware.bin
    read:firmware.bin::1024        read 1024 bytes from start of memory into firmware.bin

write and writeboot Command

Thewrite and writeboot commands writes data from a binary file into the NAND Flash.

Alert: The blocks containing the pages to be written should be erased first with the erase command.

Padding bytes are added to align programmed data to the page boundary. The page size is computed from the PMECC header.

$ sam-ba -p serial -b sam9x60-ek -a nandflash -c write:help
* write - write to memory from a file
Syntax:
    write:<filename>:[<addr>]
Examples:
    write:bootstrap.bin         write bootstrap.bin to start of memory
    write:u-boot.bin:0x10000    write u-boot.bin at offset 0x10000

The writeboot command should only be used when programming a bootstrap file into an external NAND Flash memory boot partition.

The writeboot command modifies the relevant unused Arm® exception vector to store the size of the bootstrap binary, as required by the ROM code during the boot process.

$ sam-ba -p serial -b sam9x60-ek -a nandflash -c writeboot:help
Syntax:
    writeboot:<filename>
Example:
    writeboot:bootstrap.bin     write bootstrap.bin as boot program at start of memory

verify and verifyboot Command

The verify and verifyboot commands compare the data written into the NAND Flash with the contents of a binary file.

$ sam-ba -p serial -b sam9x60-ek -a nandflash -c verify:help
* verify - verify memory from a file
Syntax:
    verify:<filename>:[<addr>]
Examples:
    verify:firmware.bin verify that start of memory matches firmware.bin
    verify:firmware.bin:0x1000 verify that memory at offset 0x1000 matches firmware.bin

The verifyboot command ignores the relevant unused Arm exception vector in the binary file.

$ sam-ba -p serial -b sam9x60-ek -a nandflash -c verifyboot:help
* verifyboot - verify boot program from a file
Syntax:
    verifyboot:<filename>
Example:
    verifyboot:bootstrap.bin verify that start of memory matches boot program bootstrap.bin

Back to Top

Translate Bootstrap Master Image to Paired Target Device pairingmode

The pairingmode applet enhances the Secure Boot mode with anti-cloning protection for the target device.

Note:The SAMA5Dx family and SAM9X60 have the ability to load signed and encrypted programs during the boot process. This allows only authorized code to load and execute on the processor.

Alert: Enabling the ROM boot code for Secure Boot mode requires a Non-Disclosure Agreement (NDA) from Microchip Technology. Contact your nearest Microchip Sales office for instructions on how to attain confidential application note AN2435, SAMA5D2 Series Secure Boot Strategy (Lit. No. DS00002435).

The pairingmode applet applies to the following devices. Documentation is available in the ../sam-ba/doc/ directory.

Additional documentation is located in the ../doc/pairingmode-sam9x60.html and ../doc/pairingmode-sama5d2.html document directories.

pairingmode Command Structure

Applet Initialization

Initialization of the pairingmode applet has the following command structure:

$ sam-ba -p secure -d sama5d2 -a pairingmode:help
Syntax: pairingmode:[<algo>]:[<force_settings>]:[<keys_in_fuse>]
Parameters:
    algo - Signature algorithm for authentication (cmac or rsa)
    force_settings - By-pass ROM code settings and force settings from applet parameters
    keys_in_fuse - If <force_settings> is set, load customer keys from fuses
Examples:
    pairingmode:cmac - Signature algorithm is set to AES-256-CMAC
    pairingmode:rsa - Signature algorithm is set to RSA

Supported Commands

A list of commands supported by the pairingmode controller can be displayed with the following command:

​$ sam-ba -p secure -d sama5d2 -a pairingmode -c help

Translate Command

The translate command transforms the input stream of binary data, loaded from the bootstrap master image file <master_input>, into the output stream of binary data, saved into the bootstrap paired image file <paired_output>.

​$ sam-ba -p secure -d sama5d2 -a pairingmode -c translate:help
* translate - convert a bootstrap master image into a bootstrap paired image
Syntax:
    translate:<master_input>:<paired_output>
Examples:
    translate:at91bootstrap.cip:at91bootstrap_paired.cip

Back to Top

Program External QSPI NOR Flash Memory qspiflash

The qspiflash applet initializes the Quad Serial Peripheral Interface (QSPI) controller and can perform read, write, erase, and verify functions.

The qspiflash applet applies to the following devices. Documentation is available in the ../sam-ba/doc/ directory.

Additional documentation is located in the ../doc/qspiflash.html document directory.

qspiflash Command Structure

Initialize Controller

Initialization of the qspiflash applet has the following command structure:

$ sam-ba -p <port> -d <device> -a qspiflash -c <command>

A list of parameters to initialize the qspiflash applet can be displayed with the following command:

$ sam-ba -p serial -d sama5d2 -a qspiflash:help
Syntax: qspiflash:[<instance>]:[<ioset>]:[<frequency>]
Parameters:
    instance   QSPI controller instance
    ioset      QSPI I/O set
    frequency  QSPI clock frequency in MHz
Examples:
    qspiflash         use default board settings
    qspiflash:0:3:66  use fully custom settings (QSPI0, IOSET3, 66MHz)
    qspiflash:::20    use default board settings but force frequency to 20MHz

A list of parameters per support target device is located in the ../doc/qspiflash.html document directory.

Supported Commands

A list of commands supported by the qspiflash controller can be displayed with the following command:

$ sam-ba -p <port> -d <device> -a qspiflash -c help

read Command

Theread command reads data from QSPI Flash into a binary file.

$ sam-ba -p serial -b sam9x60-ek -a qspiflash -c read:help
* read - read from memory to a file
Syntax:
    read:<filename>:[<addr>]:[<length>]
Examples:
    read:firmware.bin              read all to firmware.bin
    read:firmware.bin:0x1000       read from 0x1000 to end into firmware.bin
    read:firmware.bin:0x1000:1024  read 1024 bytes from 0x1000 into firmware.bin
    read:firmware.bin::1024        read 1024 bytes from start of memory into firmware.bin

erase Command

The erase command erases (resets to 0xFF) a range of data blocks in the QSPI Flash. The size of the data block depends on the target device (manufacturer and part number).

$ sam-ba -p serial -b sam9x60-ek -a qspiflash -c erase:help
* erase - erase all or part of the memory
Syntax:
    erase:[<addr>]:[<length>]
Examples:
    erase                 erase all
    erase:4096            erase from 4096 to end
    erase:0x1000:0x10000  erase from 0x1000 to 0x11000
    erase::0x1000         erase from 0 to 0x1000

write and writeboot Command

The write and writeboot commands write data from a binary file into the QSPI flash.

Alert: ​The blocks containing the pages to be written should be erased first with the erase command.

Padding bytes are added to align programmed data to the page boundary.

$ sam-ba -p serial -b sam9x60-ek -a qspiflash -c write:help
* write - write to memory from a file
Syntax:
    write:<filename>:[<addr>]
Examples:
    write:bootstrap.bin         write bootstrap.bin to start of memory
    write:u-boot.bin:0x10000    write u-boot.bin at offset 0x10000

The writeboot command modifies the relevant unused Arm exception vector to store the size of the bootstrap binary, as required by the ROM boot code during the boot process.

$ sam-ba -p serial -b sam9x60-ek -a qspiflash -c writeboot:help
Syntax:
    writeboot:<filename>
Example:
    writeboot:bootstrap.bin     write bootstrap.bin as boot program at start of memory

verify and verifyboot Command

The verify and verifyboot commands compare the data written into the QSPI Flash with the contents of a binary file.

$ sam-ba -p serial -b sam9x60-ek -a qspiflash -c verify:help
* verify - verify memory from a file
Syntax:
    verify:<filename>:[<addr>]
Examples:
    verify:firmware.bin         verify that start of memory matches firmware.bin
    verify:firmware.bin:0x1000  verify that memory at offset 0x1000 matches firmware.bin
​$ sam-ba -p serial -b sam9x60-ek -a qspiflash -c verifyboot:help
* verifyboot - verify boot program from a file
Syntax:
    verifyboot:<filename>
Example:
    verifyboot:bootstrap.bin verify that start of memory matches boot program bootstrap.bin

Back to Top

Read Target Device Unique ID readuniqueid

The readuniqueid applet reads and displays the target device's unique ID. It can also save it to a binary file.

The readuniqueid applet applies to the following devices. Documentation is available in the ../sam-ba/doc/ directory.

Additional documentation is located in the document directory: ../doc/readuniqueid.html.

readuniqueid Command Structure

The readuniqueid applet has the following command structure:

​$ sam-ba -p <port> -d <device> -a readuniqueid[:<filename>]

Examples (using the SAMA5D2 series):

$ sam-ba -p serial -d sama5d2 -a readuniqueid
 $ sam-ba -p serial -d sama5d2 -a readuniqueid:uid.bin


Back to Top

Write to RESET Controller (RSTC) Control Register (CR) reset

The reset applet resets the target device by writing to the Reset Controller (RSTC) Control Register (CR).

The reset applet applies to the following devices. Documentation is available in the ../sam-ba/doc/ directory.

Additional documentation is located in the ../doc/reset.html document directory.

reset Command Structure

The reset applet has the following command structure:

​$ sam-ba -p <port> -d <device> -a reset

Example (using the SAMA5D2 series):

​$ sam-ba -p serial -d sama5d2 -a reset


Back to Top

Program High-Speed Multimedia Card Interface (HSMCIx) or Secure Digital Multi-Media Card (SDMMCx)

The sdmcc applet initializes the High-Speed Multimedia Card (HSMCIx) or the Secure Digital Multi-Media Card (SDMMCx) Interfaces and can perform read, write, and verify functions of an external Secure Digital (SD) memory card or Embedded Multi-Media Card (e.MMC) memory embedded on the target board.

The sdmcc applet applies to the following devices.

  • SAM9X60
  • SAMA5D2 series
  • SAMA5D3
  • SAMA5D4

Documentation is available in the ../sam-ba/doc/ directory.

Additional documentation is located in the document directory ../doc/sdmmc.html.

sdmmc Command Structure

The sdmcc applet has the following command structure:

$ sam-ba -p <port> -d <device> -a sdmmc -c <command>

Initialize Controller

Initialization of the sdmcc applet has the following command:

$ sam-ba -p <port> -d <device> -a sdmmc

A list of parameters to initialize the sdmcc applet can be displayed with the help option (using the SAMA5D2 series device as an example):

​$ sam-ba -p serial -d sama5d2 -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

A list of parameters is located in the document directory: ../doc/sdmmc.html.

Supported Commands

A list of commands supported by the sdmcc controller can be displayed with the following command:

$ sam-ba -p <port> -d <device> -a sdmcc -c help/span>

read Command

The read command reads data from SD memory card or e.MMC memory into a binary file.

$ sam-ba -p serial -b sam9x60-ek -a sdmmc -c read:help
* read - read from memory to a file
Syntax:
    read:
    read:firmware.bin              read all to firmware.bin
    read:firmware.bin:0x1000       read from 0x1000 to end into firmware.bin
    read:firmware.bin:0x1000:1024  read 1024 bytes from 0x1000 into firmware.bin
    read:firmware.bin::1024        read 1024 bytes from start of memory into firmware.bin

write and writeboot Command

Thewrite and writeboot commands write data from a binary file into the SD memory card or e.MMC memory.

Alert: The blocks containing the pages to be written should be erased first with the erase command.

Note: The sdcard.img file contains the raw data of the SD memory card. It must begin with a Master Boot Record (MBR), a valid partition table, and contain two partitions:

The first partition (BOOT) must be formatted in FAT12, FAT16, or FAT32 and it must include a boot.bin file in the root folder. The boot.bin file is the second stage bootloader (at91bootstrap) that is loaded and executed by the ROM Boot code.

The second partition (ROOTFS) must be formatted in EXT2 or EXT4 and include the Root File System.

The write command should only be used to write a binary image (sdcard.img) into either an SD memory card or an e.MMC memory user partition.

$ sam-ba -p serial -b sam9x60-ek -a sdmmc -c write:help
* write - write to memory from a file
Syntax:
    write:<filename>:[<addr>]
Examples:
    write:sdcard.img            write sdcard.img to start of memory

The writeboot command should only be used when programming a bootstrap file into an e.MMC memory boot partition.

The writeboot command modifies the relevant unused Arm exception vector to store the size of the bootstrap binary, as required by the ROM Boot code during the boot process.

​$ sam-ba -p serial -b sam9x60-ek -a sdmmc -c writeboot:help
Syntax:
    writeboot:<filename>
Example:
    writeboot:bootstrap.bin     write bootstrap.bin as boot program at start of memory

verify and verifyboot Command

Theverify and verifyboot commands compare the data written into the SD memory card or e.MMC memory with the contents of a binary file.

$ sam-ba -p serial -b sam9x60-ek -a sdmmc -c verify:help
* verify - verify memory from a file
Syntax:
    verify:<filename>:[<addr>]
Examples:
    verify:sdcard.img           verify that start of memory matches sdcard.img
    verify:firmware.bin:0x1000  verify that memory at offset 0x1000 matches firmware.bin

Theverifyboot command ignores the relevant unused Arm exception vector in the binary file.

$ sam-ba -p serial -b sam9x60-ek -a sdmmc -c verifyboot:help
* verifyboot - verify boot program from a file
Syntax:
    verifyboot:<filename>
Example:
    verifyboot:bootstrap.bin     verify that start of memory matches boot program bootstrap.bin


Back to Top

Program External Serial Peripheral Interface (SPI) NOR Flash Memory serialflash

The serialflash applet initializes the SPIx or Flexible Serial Communications Controller (FLEXCOMx_SPI) controller and can perform read, write, erase, and verify functions on external SPI NOR Flash memory.

The serialflash applet applies to the following devices.

  • SAM9X60
  • SAM9XX5
  • SAMA5D2 series
  • SAMA5D3
  • SAMA5D4

Documentation is available in the ../sam-ba/doc/ directory.

Additional documentation is located in the ../doc/serialflash.html document directory.

serialflash Command Structure

The serialflash applet has the following command structure:

$ sam-ba -p <port> -d <device> -a serialflash -c <command>

Initialize Controller

Initialization of the serialflash applet has the following command structure:

$ sam-ba -p <port> -d <device> -a serialflash

A list of parameters to initialize the serialflash applet can be displayed with the following command (using the SAMA5D2 series device as an example):

$ sam-ba -p serial -d sama5d2 -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

A list of parameters is located in the ../doc/serialflash.html document directory.

Supported Commands

A list of commands supported by serialflash can be displayed with the following command:​

$ sam-ba -p <port> -d <device> -a serialflash -c help

read Command

The read command reads data from external SPI NOR Flash memory into a binary file.​

$ sam-ba -p serial -b sam9x60-ek -a serialflash -c read:help
* read - read from memory to a file
Syntax:
    read:<filename>:[<addr>]:[<length>]
Examples:
    read:firmware.bin              read all to firmware.bin
    read:firmware.bin:0x1000       read from 0x1000 to end into firmware.bin
    read:firmware.bin:0x1000:1024  read 1024 bytes from 0x1000 into firmware.bin
    read:firmware.bin::1024        read 1024 bytes from start of memory into firmware.bin

erase Command

The erasecommand erases (resets to 0xFF) a range of erase blocks in the external SPI NOR Flash memory. The size of the erase block depends on the target device (manufacturer and part number).

$ sam-ba -p serial -b sam9x60-ek -a serialflash -c erase:help
* erase - erase all or part of the memory
Syntax:
    erase:[<addr>]:[<length>]
Examples:
    erase                 erase all
    erase:4096            erase from 4096 to end
    erase:0x1000:0x10000  erase from 0x1000 to 0x11000
    erase::0x1000         erase from 0 to 0x1000

write and writeboot Command

The write and writeboot commands write data from a binary file into external SPI NOR Flash memory pages.

Alert: The blocks containing the pages to be written should be erased first with the erase command.

Padding bytes are added to align programmed data to the page boundary.

$ sam-ba -p serial -b sam9x60-ek -a serialflash -c write:help
* write - write to memory from a file
Syntax:
    write:<filename>:[<addr>]
Examples:
    write:bootstrap.bin write bootstrap.bin to start of memory
    write:u-boot.bin:0x10000 write u-boot.bin at offset 0x10000

The writeboot command should only be used when programming a bootstrap file into an external SPI NOR Flash memory boot partition.

The writeboot command modifies the relevant unused Arm exception vector to store the size of the bootstrap binary, as required by the ROM boot code during the boot process.​

$ sam-ba -p serial -b sam9x60-ek -a serialflash -c writeboot:help
Syntax:
    writeboot:<filename>
Example:
    writeboot:bootstrap.bin write bootstrap.bin as boot program at start of memory

verify and verifyboot Command

The verify and verifyboot commands compare the data written into external SPI NOR Flash memory with the contents of a binary file.

$ sam-ba -p serial -b sam9x60-ek -a serialflash -c verify:help
* verify - verify memory from a file
Syntax:
    verify:<filename>:[<addr>]
Examples:
    verify:firmware.bin         verify that start of memory matches firmware.bin
    verify:firmware.bin:0x1000  verify that memory at offset 0x1000 matches firmware.bin

The verifyboot command ignores the relevant unused Arm exception vector in the binary file.

$ sam-ba -p serial -b sam9x60-ek -a serialflash -c verifyboot:help
* verifyboot - verify boot program from a file
Syntax:
    verifyboot:<filename>
Example:
    verifyboot:bootstrap.bin    verify that start of memory matches boot program bootstrap.bin

Back to Top