XBURN#

Synopsis#

xburn xe-file
xburn [options]

Description#

XBURN creates OTP images, and programs images into the OTP memory of xCORE devices.

Usage of the form xburn a.xe burns the application in a.xe directly into OTP. This is typically undesirable as it’s an irreversible process, meaning that the application cannot be removed or upgraded, and OTP memory space is limited and cannot accommodate large applications.

Instead, XBURN is most commonly used to provision a device for secure boot and set the overall security configuration of the system. Secure boot typically works in conjunction with XFLASH - a small bootloader is installed to OTP memory which enforces signature verification of upgradable software loaded from flash memory. This bootloader is installed into OTP using the XBURN option --lock, which burns an executable generated by XBURN rather than one specified from an external file.

For more advanced use cases, XBURN exposes low-level programming of individual OTP rows with supplementary data as required by the application, such as device-unique IDs. This can be read back at runtime using the OTP library.

Options#

Overall Options#

The following options are used to specify the OTP image and security register contents.

<xe-file>#

Specifies bootable images to be constructed from the loadable segments from xe-file and a default set of security bits.

<otp-file>#

Specifies the OTP segments from otp-file which includes the security register value.

<csv-file>#

Specifies OTP tile,address,value tuples from csv-file. This may be anything from a handful of special values to program for device provisioning or identification, to a complete OTP specification generated using --dump-otp-spec.

See CSV Format.

--version#

Displays the version number and copyrights.

--help, -h#

Prints a description of the supported command-line options.

Note

It’s advised to consistently use a single version of XBURN on a given device. Bootloader images and redundancy mechanisms may subtly change between releases of the XTC Tools. By consistently using only a single version, any (perhaps accidental) double-programming attempt will generally behave as a no-op, whereas a difference in content to be programmed may cause irreversible damage to the device.

Target Options#

The following options are used to specify the target hardware platform.

--list-devices, -l#

Prints an enumerated list of all JTAG adapters connected to the host and the devices on each JTAG chain, in the form:

ID        Name        Adapter ID        Devices
--        ----        ----------        -------

The adapters are ordered by their serial numbers.

--id <id>#

Specifies the adapter connected to the target hardware.

--adapter-id <serial-number>#

Specifies the serial number of the adapter connected to the target hardware.

--jtag-speed <n>#

Sets the divider for the JTAG clock to n. The corresponding JTAG clock speed is \(25/(n+2)\) MHz. The default value is 0 (12.5 MHz).

--spi-div <n>#

Sets the divider used in the AES Module for the SPI clock to n. The corresponding SPI clock speed is set to \(100/(2*n)\) MHz. The default value is 20 (2.5MHz).

This option is only valid with --lock.

Security Options#

--genkey <keyfile>#

Outputs to <keyfile> two 128-bit keys used for authentication and decryption. The keys are generated using the open-source library crypto++.

This option does not perform any programming or target interactions.

--lock <keyfile>#

Specifies the XCORE AES boot module and a default set of security bits.

Security Register Options#

The following options are used to specify the contents of the OTP security register, overriding the default options for burning XE images, OTP images and the AES module, as given in Default security bits written by XBURN.

Table 13 Default security bits written by XBURN#

Security Bit

XE Image

OTP Image

AES Module (--lock)

OTP Boot

Enabled

As per OTP image file

Enabled

JTAG Access

Enabled

Disabled

Plink Access

Enabled

Enabled

Global Debug

Enabled

Disabled

Master Lock

Disabled

Enabled

Secure Config Access

Enabled

Enabled

The following options support both the prefixes --enable-... and --disable-... to either enable or disable the feature.

--enable-otp-boot / --disable-otp-boot#

Enables/disables boot from OTP.

--enable-jtag / --disable-jtag#

Enables/disables JTAG access. Once disabled, it is not possible to gain debug access to the device or to read the OTP.

This option does not disable boundary scan.

--enable-global-debug / --disable-global-debug#

Enables/disables the device from participating in global debug. Disabling global debug prevents the tiles from entering debug using the global debug pin.

--enable-master-lock / --disable-master-lock#

Enables/disables the OTP master lock. No further modification of the OTP is permitted. Programming is disabled.

--enable-secure-config-access / --disable-secure-config-access#

Enables/disables access to the security register.

Note

xcore.ai devices do not support the usage style of progressively setting more security bits to upgrade the device’s security in phases by rewriting the security register. The security register can only be burned once on xcore.ai, so must be programmed with the intended final configuration from the start. This diverges from the behaviour of XCORE-200 and previous devices which do allow progressively setting more bits.

Programming Options#

By default, XBURN writes the specified OTP images to the target platform.

--force, -f#

Do not prompt for interactive confirmation before writing the OTP. This is not default.

--outfile <otp-file>, -o <otp-file>#

Place output in <otp-file>, disabling programming.

--dump-otp-images#

Dump the OTP images in separate binary files, disabling programming.

--dump-otp-spec#

Dump the OTP images to CSV specification, disabling programming.

The CSV file can be edited by hand and/or provided to XBURN for programming later in a second pass. If the CSV file has been unmodified, programming in a second pass is identical to single pass behaviour.

See CSV Format.

--make-exec <xe-file>#

Place an executable in <xe-file> that when run on an xCORE device performs the specified OTP burning operation; disables programming.

The XE file can be run later using XRUN.

--target-file <xn-file>#

Specifies <xn-file> as the target platform.

--target <platform>#

Specifies a target platform. The platform configuration must be specified in the file platform .xn, which is searched for in the paths specified by the XCC_DEVICE_PATH environment variable.

--read#

Prints the entire contents of the OTP.

--size-limit <n>#

Limits the amounts of OTP memory written to the first n bytes of the OTP. If the image doesn’t fit within the specified limit an error will be given.

CSV Format#

XBURN supports OTP programming from a CSV format specification. This is an advanced option that can be used for programming additional supplementary data out-of-band, with respect to the majority of OTP memory which is typically occupied by the AES Module generated by XBURN. This option can be used for provisioning of device serial numbers or similar information. Providing a CSV file to XBURN during programming will result in the tool incorporating the OTP data records in the CSV file into the overall image that will be programmed.

XBURN can also generate a complete CSV specification of all OTP data instead of directly programming it. This is done using the --dump-otp-spec option, and the resulting file can be provided later to XBURN to perform the actual programming of the device.

The CSV format is provided in the form tile,address,value where each row programs a 32-bit word of OTP memory. The tile field is typically 0 or 1 indicating tile[0] or tile[1], but may also be the character * to apply to all tiles in the system. The address provided is a word address, so programming two adjacent 32-bit words requires incrementing the address by 1.

0,0x1FE,0xFFFF0000
1,0x1FE,0xFFFF0001
*,0x1FF,0xDEADBEEF

xcore.ai example: sets OTP virtual address 0x1FE to 0xFFFF0000 on tile[0], 0xFFFF0001 on tile[1] and address 0x1FF to 0xDEADBEEF on both tiles. This programs two words at the end of each tile’s OTP, using eight physical rows when accounting for hardware redundancy.

Due to physical implementation details of each device, the format between the XCORE-200 family and xcore.ai family have a few differences. XCORE-200 considers addresses to be physical addresses, with redundant records expressed explicitly within the CSV file. On xcore.ai the addresses are considered to be ‘virtual’ addresses where hardware redundancy is always enabled, and therefore the redundant records are not specified explicitly in the CSV file.

0,0x7FE,0xFFFF0000
1,0x7FE,0xFFFF0001
*,0x7FF,0xDEADBEEF

XCORE-200 example: sets OTP physical address 0x7FE to 0xFFFF0000 on tile[0], 0xFFFF0001 on tile[1] and address 0x7FF to 0xDEADBEEF on both tiles. This programs two words at the end of each tile’s OTP, using four physical rows, with two rows used in each physical OTP.

If exporting a CSV specification on the XCORE-200 family using --dump-otp-spec, an optional fourth CSV column will be present on some rows indicating that the executable (typically the AES Module) participates in the software redundancy mechanism used to improve yield. This column is currently unused by the xcore.ai family.

An example use case for the XCORE-200 family is provided in the tools release under the examples/ExampleBurning/XCORE-200 directory. The script provided serves as a replacement for the retired XBURN --serial-number, --board-id and --mac-address options, and will generate a CSV file that can be provided to XBURN to provision the device with those values.

For a visual confirmation of the effect of the provided CSV entries, the option --dump-otp-images can be provided to XBURN and the resulting images viewed in a hex editor.

Caution

The CSV format allows programming any OTP region with no restrictions. It requires reasonable knowledge of the OTP memory map of the target device family to manipulate it correctly. See your device’s datasheet for more information.

Be careful when using this option, particularly to ensure that the provided CSV doesn’t instruct XBURN to corrupt or overwrite existing data structures, such as the AES Module. It’s advisable to program custom application data towards the end of the OTP array as this area is unused by XBURN internally. The contiguous block at the start of the OTP array is reserved for boot functions.