Getting started with SAM-BA on SAM9X7 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 SAM9X75-DDR3-EB board.

Predefined boards and customer board designs

The sam-ba program comes with a predefined sam9X75-ddr3-eb board that sets default values for different settings such as the applet console or memory controller instances and iosets.

This predefined board can be selected with the -b sam9x75-ddr3-eb option on the sam-ba command line.

However the -d sam9x7 or one of the aliases sam9x70, sam9x72, sam9x75 option should be used instead on customer board designs, not to load any default settings.

Additional parameters may be passed to the -d sam9x7:<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 by passing additional arguments to the -a <applet> option for the applet mananing the memory controller.

Supported applets

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

$ sam-ba -p serial -d sam9x7 -a help
Known applets: reset, readuniqueid, bootconfig, sdmmc, qspiflash, nandflash, serialflash

OTPC Emulation mode

During developments and tests, we recommend the user to enable the OTPC emulation mode. Doing so, the OTP controller or OTPC, replaces its OTP matrix by internal SRAM1 (4k) to store all User Area packets, including the Boot Configuration packeta and Secure Boot Configuration packet.

The bootconfig applet provides the user with helper commands to manage the OTPC emulation mode.

As internal SRAM1 is not powered by VDDBU, data are kept as long as board is powered, including User Area packets of the OTPC in emulation mode. However, those packets remain ignored by the ROM code unless the proper value is written into the BSCR register, for instance by executing the writecfg:bscr:EMULATION_ENABLED command:

$ sam-ba -p serial -b sam9x75-ddr3-eb -t 5 -a bootconfig -c writecfg:bscr:EMULATION_ENABLED

or:

$ sam-ba -p serial -d sam9x7 -t 5 -a bootconfig -c writecfg:bscr:EMULATION_ENABLED

Note: Setting bit 0 (EMULATION_ENABLED) in the BSCR does not enable the OTPC emulation mode immediately, it only tells the ROM code to enable the OTPC emulation mode on the next reset before fetching the Boot Configuration packet and any other User Area packet.

Warning: Once any User Area packet has been programmed into the OTP matrix, the emulation mode can never be enabled again. Be careful before writing a packet in the OTPC matrix!

To prevent the user from writing a packet into the OTP matrix by mistake, SAM-BA requires the user to append an explicit emul or otp suffix to the packet type telling whether this packet is to be stored into the OTP matrix or into internal SRAM1.

Before writing a first packet in emulation mode, internal SRAM1 must be cleared to zero. This is the purpose of the resetemul command:

$ sam-ba -p serial -b sam9x75-ddr3-eb -t 5 -a bootconfig -c resetemul

or:

$ sam-ba -p serial -d sam9x7 -t 5 -a bootconfig -c resetemul

Once internal SRAM1 has been reset to zero, the user should request the OTPC to scan again, hence refresh, packets from the User Area by running a refreshcfg:emul command.

$ sam-ba -p serial -b sam9x75-ddr3-eb -a bootconfig -t 5 -c refreshcfg:emul

or:

$ sam-ba -p serial -d sam9x7 -a bootconfig -t 5 -c refreshcfg:emul

Unlike the writecfg:bscr:EMULATION_ENABLED, the refreshcfg:emul command enables the OTPC emulation mode immediately, till the next power-on/reset or till disabled again by the refreshcfg:otp command.

If the refreshcfg:emul command returns

-E- Cannot enable EMULATION mode

message in console, it means that a User Area packet was previously written into OTP matrix. In this case OTPC emulation mode can't be used anymore.

Boot Configuration

The ROM code of SAM9X7 devices is the 1st stage boot loader responsible for the system boot. Hence, the ROM code fetches the active Boot Configuration packet from the OTPC User Area in order to get boot settings such as the ROM code console and the NVM boot sequence.

Active Boot Configuration packet

ROM code boot settings are stored in an OTPC User Area packet of Boot Configuration type. Like any other OTPC packet, Boot Configuration packets can be read, programmed, locked or invalidated.

The latest valid Boot Configuration packet is the active Boot Configuration packet. That is to say that ROM code fetches its boot settings from this packet.

If no valid Boot Configuration packet is programmed in the OTPC User Area, then the ROM code uses its default console and default boot sequence.

ROM Code console

The Boot Configuration packet tells the ROM code which RS-232 UART instance is to be used for the console. For instance, the "RomBOOT" string is always printed on power-on or reset on this console. Also, the ROM code console is used by SAM-BA monitors to communicate with the sam-ba program when USB is not available.

On SAM9X7 devices, the default ROM code console is DBGU but it can be set to any of the FLEXCOM<0-12> USART. Please note that the ROM code console may be different from the applet console

NVM boot sequence

The Non-Volatile Memory (NVM) boot sequence is the list of controllers managing external NVM where the ROM code tries to load bootstrap application from.

On SAM9X7 devices, the default boot sequence is:

1. SDMMC0 (e.MMC / SD Card)
2. SDMMC1 (e.MMC / SD Card)
3. QSPI (QSPI NOR flash)
4. SMC (raw NAND flash)
5. FLEXCOM5 SPI (SPI NOR flash)

All the possible values for the memory interfaces and IOsets for SAM9X7 devices can be obtained by

$ sam-ba -p serial -d sam9x7 -t 5 -a bootconfig -c help

Programming a Boot Configuration packet

The user can program his first Boot Configuration packet with the writecfg:bcp-emul / writecfg:bcp-otp command:

$ sam-ba -p serial -b sam9x75-ddr3-eb -a bootconfig -t 5 -c writecfg:bcp-emul:QSPI0_IOSET1

or

$ sam-ba -p serial -d sam9x7 -a bootconfig -t 5 -c writecfg:bcp-emul:QSPI0_IOSET1

In this example, DBGU is implicitly chosen as the ROM code console and QSPI is the only boot media in the boot sequence.

If the user wants to try to boot from a NAND flash first, then from SDMMC1 then the sam-ba command will be:

$ sam-ba -p serial -b sam9x75-ddr3-eb -a bootconfig -t 5 -c writecfg:bcp-emul:NFC_IOSET1,SDMMC1_IOSET1

or:

$ sam-ba -p serial -d sam9x7 -a bootconfig -t 5 -c writecfg:bcp-emul:NFC_IOSET1,SDMMC1_IOSET1

The writecfg command fails on purpose to create a new packet if an active packet of the same type already exists but cannot be updated. This packet must be invalidated first by the invalidatecfg command before creating a new valid packet.

Reading back the Boot Configuration packet

If an active Boot Configuration packet is available from the OTPC User Area, this packet can be read-back with the readcfg:bcp-emul / readcfg:bcp-otp command:

$ sam-ba -p serial -b sam9x75-ddr3-eb -a bootconfig -t 5 -c readcfg:bcp-emul

or:

$ sam-ba -p serial -d sam9x7 -a bootconfig -t 5 -c readcfg:bcp-emul

If no active Boot Configuration packet is available from the OTPC User Area, then this command reports an error. Especially, the default boot configuration used by the ROM code is not returned. Only the active Boot Configuration packet programmed in the OTPC User Area can be returned.

Updating the Boot Configuration packet

Only 32-bit zeroed words can be updated in OTPC packet payloads. For instance, if the boot sequence is not full, the user can append another entry to the boot sequence. However, already set entries must be left unchanged. As an example, assuming the current boot sequence is "NFC_IOSET1,SDMMC1_IOSET1", then user can still append a "SDMMC0_IOSET1" entry with the writecfg:bcp-emul / writecfg:bcp-otp command:

$ sam-ba -p serial -b sam9x75-eb -a bootconfig -t 5 -c writecfg:bcp-emul:NFC_IOSET1,SDMMC1_IOSET1,SDMMC0_IOSET1

or:

$ sam-ba -p serial -d sam9x7 -t 5 -c writecfg:bcp-emul:NFC_IOSET1,SDMMC1_IOSET1,SDMMC0_IOSET1

The update or the creation of new Boot Configuration packet can be persistently disabled by setting the BCPGDIS bit of the User Hardware Configuration packet.

Locking the Boot Configuration packet

Locking a packet discards any further modification of this packet, except its invalidation. Hence, once locked, a packet can no longer be updated. Locking the Boot Configuration packet is done by the lockcfg:bcp-emul / lockcfg:bcp-otp command:

$ sam-ba -p serial -b sam9x75-ddr3-eb -a bootconfig -t 5 -c lockcfg:bcp-emul
$ sam-ba -p serial -b sam9x75-ddr3-eb -a bootconfig -t 5 -c writecfg:bcp-emul:NFC_IOSET1,SDMMC1_IOSET1,SDMMC0_IOSET1,FLEXCOM0_SPI_IOSET1

The second command fails since the Boot Configuration packet has been locked by the first command.

Locking of Boot Configuration packets can be persistently disabled by setting the BCLKDIS bit of the User Hardware Configuration packet.

Invalidating the Boot Configuration packet

The Boot Configuration packet can be tagged as invalid so it is ignored by the OTPC when it scans the OTPC User Area, hence ignored by the ROM code on futher power-on/reset. This is achieved with the invalidatecfg:bcp-emul / invalidatecfg:bcp-otp command

$ sam-ba -p serial -b sam9x75-ddr3-eb -a bootconfig -t 5 -c invalidatecfg:bcp-emul

or:

$ sam-ba -p serial -d sam9x7 -a bootconfig -t 5 -c invalidatecfg:bcp-emul

Packet invalidation cannot be reverted, however a new packet of the same type can be programmed with a new writecfg:bcp-emul/ writecfg:otp-emul command. In case of many Boot Configuration packets exists, the latest packet that has been programmed but not invalidated yet is the active Boot Configuration packet.

$ sam-ba -p serial -d sam9x7 -a bootconfig -t 5 -c writecfg:bcp-emul:NFC_IOSET1

The invalidation of Boot Configuration packets can be persistently disabled by setting the BCINVDIS bit of the User Hardware Configuration packet.

User Hardware Configuration

The User Hardware Configuration packet is designed to persistently disable the JTAG port or some OTPC features and commands.

Like with the Boot Configuration packet, sam-ba provides commands to create, read-back, update, lock and invalidate the User Hardware Configuration packet.

When a User Hardware Configuration packet has been created or updated, the packet is not taken into account by the OTPC controller until the next power-on/reset or until a refresh operation has been triggered by the refreshcfg command.

After each refresh, the payload of the active User Hardware Configuration packet is visible from OTPC_UHC0R and OTPC_UHC1R registers. Please refer to the OTPC section of the SAM9X7x series datasheet for the exact description of those registers.

The User Hardware Configuration packet should be programmed at the end of the production to persistenly disable OTPC features such as programming, locking or invalidating given types of packet that may be used as breaches into the security of a device from SAM9X7 devices.

This is done with the writecfg:uhcp-emul / writecfg:uhcp-otp command:

$ sam-ba -p serial -b sam9x75-ddr3-eb -a bootconfig -t 5 -c writecfg:uhcp-emul:JTAGDIS,BCPGDIS,BCINVDIS,UHCPGDIS,UHCINVDIS

or:

$ sam-ba -p serial -d sam9x7 -a bootconfig -t 5 -c writecfg:uhcp-emul:JTAGDIS,BCPGDIS,BCINVDIS,UHCPGDIS,UHCINVDIS

Secure Boot Configuration

To enable the secure boot mode on a device from SAM9x7 series, an initial Secure Boot Configuration packet must be created with the writecfg:sbcp-emul / writecfg:sbcp-otp command:

$ sam-ba -p serial -b sam9x75-ddr3-eb -a bootconfig -t 5 -c writecfg:sbcp-emul:SECURE_BOOT_ENABLED

or shortly:

$ sam-ba -p serial -b sam9x75-ddr3-eb -a bootconfig -t 5 -c writecfg:sbcp-emul:

or:

$ sam-ba -p serial -d sam9x7 -a bootconfig -t 5 -c writecfg:sbcp-emul:

Don't forget the final colon (:) after sbcp-emul as the writecfg command expects 2 arguments; the 2nd argument being left to its default SECURE_BOOT_ENABLED value.

For further details on how to configure the secure boot mode, refer to Secure Boot Mode.

Programming a raw NAND flash

In the following example, we show how to program a bootstrap.bin file into a NAND flash that SAM9X75-DDR3-EB board may be equipped with. Please refer to SAM9X75-DDR3-EB User Guide for details on how to install a NAND flash memory device on SAM9X75-DDR3-EB board.

$ sam-ba -p serial -b sam9x75-ddr3-eb:::<header> -t 5 -a nandflash -c erase
$ sam-ba -p serial -b sam9x75-ddr3-eb:::<header> -t 5 -a nandflash -c writeboot:bootstrap.bin -c verifyboot:bootstrap.bin

or: $ sam-ba -p serial -d sam9x7:1:8:<header> -t 5 -a nandflash -c erase $ sam-ba -p serial -b sam9x7:1:8:<header> -t 5 -a nandflash -c writeboot:bootstrap.bin -c verifyboot:bootstrap.bin

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 sam9x7 -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:1:8:0xc0098da5  use fully custom settings (IOSET1, 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 Boot Strategy chapter from SAM9X7x series datasheet.

Supported <ioset> for the NAND flash on SAM9X7 device are listed here.

Programming a QSPI NOR flash

In the following example, we program the bootstrap.bin and user_app.bin files into a QSPI NOR flash that SAM9X75-DDR3-EB board may be equipped with:

$ sam-ba -p serial -b sam9x75-ddr3-eb -t 5 -a qspiflash -c erase
$ sam-ba -p serial -b sam9x75-ddr3-eb -t 5 -a qspiflash -c writeboot:bootstrap.bin -c verifyboot:bootstrap.bin
$ sam-ba -p serial -b sam9x75-ddr3-eb -t 5 -a qspiflash -c write:user_app.bin:0x00040000 -c verify:user_app.bin:0x00040000

or:

$ sam-ba -p serial -d sam9x7:0:1:50 -t 5 -a qspiflash -c erase
$ sam-ba -p serial -d sam9x7:0:1:50 -t 5 -a qspiflash -c writeboot:bootstrap.bin -c verifyboot:bootstrap.bin
$ sam-ba -p serial -d sam9x7:0:1:50 -t 5 -a qspiflash -c write:user_app.bin:0x00040000 -c verify:user_app.bin:0x00040000

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

The list of those parameters is given by the command:

$ sam-ba -p serial -d sam9x7 -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:60
    qspiflash         use default board settings
    qspiflash:0:1:50  use fully custom settings (QSPI0, IOSET1, 50Mhz)
    qspiflash:::50    use default board settings but force frequency to 50Mhz

Supported <instance> and <ioset> for QSPI on SAM9X7 devices are listed here.

Programming a SPI NOR flash

In the following example, we program the bootstrap.bin, user_app.bin files into a SPI NOR flash that may be connected to the FLEXCOM5_SPI of a SAM9X75-DDR3-EB board:

$ sam-ba -p serial -b sam9x75-ddr3-eb -t 5 -a serialflash -c erase
$ sam-ba -p serial -b sam9x75-ddr3-eb -t 5 -a serialflash -c writeboot:bootstrap.bin -c verifyboot:bootstrap.bin
$ sam-ba -p serial -b sam9x75-ddr3-eb -t 5 -a serialflash -c write:user_app.bin:0x00008000 -c verify:user_app.bin.bin:0x00008000

or:

$ sam-ba -p serial -d sam9x7 -t 5 -a serialflash:5:1:0:50 -c erase
$ sam-ba -p serial -d sam9x7 -t 5 -a serialflash:5:1:0:50 -c writeboot:bootstrap.bin -c verifyboot:bootstrap.bin
$ sam-ba -p serial -d sam9x7 -t 5 -a serialflash:5:1:0:50 -c write:user_app.bin:0x00008000 -c verify:user_app.bin.bin:0x00008000

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 those parameters is given by the command:

$ sam-ba -p serial -d sam9x7 -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:5:1:0:50  use fully custom settings (SPI5, IOSET1, NPCS0, 50Mhz)
    serialflash::::20     use default board settings but force frequency to 20Mhz

Supported <instance>, <ioset> and <npcs> for SPI on SAM9X7 devices 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 boot files in its root directory:

• a boot.bin file: the bootstrap.bin file renammed into boot.bin
• a user_app.bin file: some binary image, loaded then executed by boot.bin

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

$ sam-ba -p serial -b sam9x75-ddr3-eb -t 5 -a sdmmc -c write:sdcard.img

or:

$ sam-ba -p serial -d sam9x7 -t 5 -a sdmmc:0:1:0:0:4 -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 sam9x7 -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 SAM9X7 devices are listed here.

Secure Boot Mode

First step to benefit from secure boot features of SAM9X7 devices is to enable this secure boot mode as describe in section Secure Boot Configuration.

Once the Secure Boot Configuration packet has been written, the device must be reset so the ROM code executes its secure SAM-BA monitor:

$ sam-ba -p serial -d sam9x7 -a reset

From this point, the ROM code no longer executes its Standard 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.

Then, another mandatory step is to program the customer keys into the device. This customer keys are wrapped into a ciphered and signed customer key message.

This so called customer key message is actually generated from the 640-bit customer key by the secure-sam-ba-cipher.py tool. This tool is distributed under NDA, hence not covered by this documentation.

As stated, the customer key message is ciphered to protect the customer key from eavesdropping during device provisioning in factory and is also signed so the customer key message can be authenticated by the ROM code. Only the secure-sam-ba-cipher.py tool with a license provided by Microchip can generate genuine customer key messages.

Assumming the customer key message is packaged inside a customer-key_aes.cip or customer-key_rsa.cip files, programming the customer key into a device from SAM9X7 devices must be done by sam-ba with one of these commans:

in case the customer key is signed using Microchip secret key:

$ sam-ba -p secure -b sam9x75-ddr3-eb -m write_customer_key:customer-key_aes.cip

or in case the customer key message is signed using Microchip RSA public key:

$ sam-ba -p secure -b sam9x75-ddr3-eb -m write_customer_key_payload:customer-key_rsa.cip

At this point and on further resets, the ROM code expects the bootstrap or user application stored into the external NVM to be both ciphered with AES-256-CBC and signed with AES-256-CMAC.

Optionally, the shared key signature algorithm can be replaced by a public key algorithm. More precisely, the AES-256-CMAC signature is replaced by a RSA signature that will be verified by the ROM code at each boot to authenticate the bootstrap or user application.

Indeed, a chain of X.509 version 3 certificates in DER format is concatenated to the bootstrap and its RSA signature.

The first certicate in this chain is called the root certificate and must be a self-signed certificate.

Besides, except the root certificate, each certificate in the chain is signed, hence authenticated, by the previous certificate in the chain. So the root certificate, more precisely its public key, is the root of trust since it, directly or indirectly, authenticates all certificates in the chain.

The secure-sam-ba-cipher.py tool can compute a SHA-512 digest of the public key of the root certificate. Like the customer key with the customer key message, this digest is wrapped into a ciphered and signed message called the RSA hash message.

The selection of RSA signature should be made in customer key file and the generation of customer key message with this configuration is done by the secure-sam-ba-ciher.py. This step is not covered by this documentation.

After that and for each boot, the ROM code still deciphers the bootstrap or the user application with the AES-256-CBC algorithm using the same shared key as before but no longer authenticates it with an AES-256-CMAC signature.

Instead, it computes the SHA-512 digest of the public key of the root certificate with the same algorithm used by the secure-sam-ba-cipher.py tool. Then, the ROM code authenticates the root certificate by comparing the computed digest with the one that has been programmed into the OTPC.

If both digests match then the root certificate is authenticated by the ROM code. Next, the ROM code authenticates each X.509 certificate of the chain by verifying its signature with the public key of the previous X.509 certificate in the chain.

Finally, when all X.509 certificates in the chain have been authenticated, the ROM code uses the public key stored into the last certificate of the chain to verify the RSA signature of the bootstrap or user application stored in NVM.

To speed-up the boot process, the X.509 certificate chain can be limited to a single X.509 self-signed certificate. In such case, this certificate is both the root certificate and the certificate used to authenticate the bootstrap or user application.

Both 2048 and 4096-bit RSA signatures are supported by the SAM9X7 devices.

Enabling the pairing mode

The pairing mode enhances the secure boot mode with an anti-cloning protection for the target device.

The user can enable this mode from the customer key file and the generation of customer key message with this configuration is done by the secure-sam-ba-ciher.py. This step is not covered by this documentation.

In any configuration the customer key message should be written only once using the above detailed commands.