#Format Firmware files

#Overview

The SpringCore devices do not contain only a MCU that runs a single firmware image; they also rely on peripheral chipsets (NFC/RFID HF, BLE, network…) that have their own firmware image. Therefore, a firmware file does not contain a single firmware image targetting the MCU, but a collection of many firmware images, targetting all the peripheral chipsets a device may have.

Basically, we say that the firmware file contains one or more parts, one for every chipset. Flashing the SpringCore device generally means copying all the parts to the relevant storage area in the device’s NVM (see NVM mapping Appendix for details). On the next reset, the device’s bootloader will copy the new firmware images from the NVM to the MCU and to the peripheral chipsets.

One part of the firmware file may be a meta-data block.

#File mapping

A firmware file is a set of firmware parts. Every part is introduced by a fixed-length part header (10 bytes).

Offset in file	Length	Content
0	10	Header of first part
10	L0	Firmware image (raw binary)
10+L0	10	Header of second part
20+L0	L1	Firmware image (raw binary)
20+L0+L1	10	Header of third part
…	…	…

#Format of part header

Every firmware part is introduced by a 10-B part header defined as follow:

Bytes	Content
0-1	ID of the part (see table below)
2-5	CRC32 of the following binary content The raw content is padded to be on a 4-byte boundary to calculate the CRC efficiently
6-9	Length of the following binary content

Note that this header is coherent with the first packet of a [PUSH_TO_STORAGE or PUSH_TO_STORAGE_FAST]([PUSH_TO_STORAGE _and_PUSH_TO_STORAGE_FAST]) sequence.

#Part IDs

Part ID	Description	Remark
0000	Firmware for the MCU	This is the only part that could be loaded directly into the MCU’s ROM using PUSH_TO_ROM
0001	Firmware for the NFC/RFID HF chipset (PN5180)	For devices with a NFC/RFID HF interface
0002	Firmware for the BLE chipset (BGM111)	For devices with a BLE interface
0003	Audio packs	For devices with an audio output capability
0004	Firmware for the ‘Vegas’ antenna	For devices with the UI interface delegated to a PIC or RL78/G12
0005	Firmware for the network chipset
0xFFFE	Hardware Dependant Pack	May contains multiple variant of firmware from the same group (for example a BGM111, a BGM13P32 and a BGM220)
FFFF	Meta-data	Not actually stored in the device, but used to describe the firmware upgrade file

#Meta-data block

If part ID = FFFF , the following firmware image is not a raw binary but a meta-data block. The meta-data block shall not be transmitted to the device.

The meta-data block contains either a JSON or plain-text self-documentation of the firmware file.

#Detail of firmware contents

#MCU

#Renesas RX651 and RX65N

RX firmware image is generated by SCPacker to match RX’s internal ROM upgrade requirements (alignment, size and empty sectors).

The image contains its own header that is used by the bootloader to check that the ROM is OK. The image also contains a digital signature to that is checked by the bootloader.

Byte	Content
0-3	EndCRC pointer (ROM address of EndCRC)
4-7	StartCRC
8-11	Firmware ID
12-15	RFU
16-…	Actual firmware entry point
…	Signature block
…	EndCRC

The Firmware ID is used in 2 situations:

• Before flashing a device, the device’s bootloader checks that the ID of the new firmware matches the ID of the current firmware and fails with STAtus = 07 (WRONG_ID) if this is not the case. This protects the device from being flashed with a firmware that targets another hardware and would ‘brick’ the device,
• When the firware starts, it checks that its own ID matches the ID of the previous firmware. If this is not the case, the new firmware erases all the existing configuration registers before running. This prevents ‘bricking’ the device due to old configuration settings that are not valid under the new firmware.

For reference, the ID of the last firmware to have run is found in register 01E0. Erasing this register disable the protection. Also a Firmware ID set to DEADBEEF is accepted over any earlier value. This is used by the “Panic” firmware.

#BLE chipset

A BLE chipset firmware image contains the firmware for the Silicon Labs BGM111 module.

This part of the firmware file contains the whole xxxxx_full.gbl file generated by Simplicity Studio ‘as is’.

#NFC/RFID HF chipset

A NFC/RFID HF chipset firmware image contains the firmware for the NXP PN5180 frontend.

This part of the firmware file contains the whole xxxxx.sfwu file provided by NXP ‘as is’.

#Hardware Dependant Pack format

An Hardware Dependant Pack contains multiple variant of firmware from the same group (for example a BGM111, a BGM13P32 and a BGM220). It’s up to the Flasher application to select the compliant variant for the product being upgraded.

To ease the selection process, the Hardware Dependant Packed file contains:

• the query to send to the product (for example: send me your BGM’s model string)
• multiple options (comparison with the result of the above query)
• multiple firmware

Item	Length	Description / remark
Group	2 bytes	0xFFFE
Checksum	4 bytes	dynamic bloc’s crc32 (including padding)
Length	4 bytes	dynamic bloc’s length
Dynamic bloc	multiple bytes	TLV records

#Dynamic bloc TLVs

Length fields (L) are coded on 1 to 5 bytes. This Dynamic bloc acts as a switch/case.

SpringCoreFlash will, on a group 0xFFFE firmware:

• look for a type 0x01 record to obtain the query, execute it and store the result. If there is no result, the first firmware in this dynamic bloc will be used.

• look for a type 0x02 record to obtain the default part index value to be used.

• look for all type 0x10 records and compare it with the query result. If there is no matching record, the first firmware in this dynamic bloc will be used (index 0). If a record matches, the firmware with the same index will be used.

• look for all type 0x20 records and stop on the previously choosen index, the Value field contains the complete Single “packed” firmware to use for upgrade.

Type	Length	Value
0x00	1	00: Version
0x01	n	Query to send to the product (58 20 34 for example, to retrieve the BGM’s model)
0x02	1	03: part 3 is the default one
0x10	n	First possible option (for example “BGM111”), index 0
0x10	n	Second possible option (for example “BGM13P32”), index 1
..	..	..
0x10	n	Last possible option (for example “BGM220”), index z
0x20	n	Firmware for the first option (This field contains a complete Single “packed” firmware), index 0
0x20	n	Firmware for the second option (This field contains a complete Single “packed” firmware), index 1
..	..	..
0x20	n	Firmware for the last option (This field contains a complete Single “packed” firmware), index z

#Example

00 01 00	Record version 0x00
01 03 58 20 34	Send 58 20 34 to the product and save result.
02 01 02	Default part index is 2
10 06 42 47 4d 31 31 31	First option, at index 0 is “BGM111”
10 08 42 47 4d 31 33 50 58 32	Second option, at index 1 is “BGM13P32”
10 06 42 47 4d 32 32 30	Third option, at index 2 is “BGM220”
20 83 nn nn nn [Single “packed” firmware]	First firmware for the BGM111
20 83 nn nn nn [Single “packed” firmware]	Second firmware for the BGM13P32
20 83 nn nn nn [Single “packed” firmware]	Third firmware for the BGM220