1*33f40117STimur Tabi.. SPDX-License-Identifier: (GPL-2.0+ OR MIT) 2*33f40117STimur Tabi 3*33f40117STimur Tabi================================== 4*33f40117STimur TabiTLV Tags in Nova Firmware Images 5*33f40117STimur Tabi================================== 6*33f40117STimur Tabi 7*33f40117STimur TabiNova firmware images use a Type-Length-Value (TLV) format to encapsulate 8*33f40117STimur Tabifirmware components and metadata. The TLV file begins with a 4-byte "magic" 9*33f40117STimur Tabiheader that contains the string "NVFW". Following the header is a sequence of 10*33f40117STimur TabiTLV blocks. 11*33f40117STimur Tabi 12*33f40117STimur TabiEach block consists of a 4-byte tag of ASCII characters, a 4-byte length 13*33f40117STimur Tabiencoded as a little-endian unsigned integer, and a sequence of bytes, the size 14*33f40117STimur Tabiof which is equal to the length rounded up to the next multiple of 4. 15*33f40117STimur Tabi 16*33f40117STimur TabiThe driver code that reads the TLV and uses its contents is called the parser. 17*33f40117STimur TabiIt is the responsibility of the parser to handle missing or malformed tags, 18*33f40117STimur Tabilengths, and values in the TLV. 19*33f40117STimur Tabi 20*33f40117STimur Tabi:: 21*33f40117STimur Tabi 22*33f40117STimur Tabi +------+------+------+------+ 23*33f40117STimur Tabi | 'N' | 'V' | 'F' | 'W' | Magic header 24*33f40117STimur Tabi +------+------+------+------+ 25*33f40117STimur Tabi | Tag (4 bytes, ASCII) | TLV block 0 26*33f40117STimur Tabi +---------------------------+ 27*33f40117STimur Tabi | Length (4 bytes, LE) | 28*33f40117STimur Tabi +---------------------------+ 29*33f40117STimur Tabi | | 30*33f40117STimur Tabi | Value (length bytes, | 31*33f40117STimur Tabi | padded to 4-byte align) | 32*33f40117STimur Tabi | | 33*33f40117STimur Tabi +---------------------------+ 34*33f40117STimur Tabi | Tag (4 bytes, ASCII) | TLV block 1 35*33f40117STimur Tabi +---------------------------+ 36*33f40117STimur Tabi | Length (4 bytes, LE) | 37*33f40117STimur Tabi +---------------------------+ 38*33f40117STimur Tabi | | 39*33f40117STimur Tabi | Value (length bytes, | 40*33f40117STimur Tabi | padded to 4-byte align) | 41*33f40117STimur Tabi | | 42*33f40117STimur Tabi +---------------------------+ 43*33f40117STimur Tabi | ... | More TLV blocks 44*33f40117STimur Tabi +---------------------------+ 45*33f40117STimur Tabi 46*33f40117STimur TabiTags and Length 47*33f40117STimur Tabi=============== 48*33f40117STimur TabiTLV tags are always four-character words, with all letters being upper case. 49*33f40117STimur TabiDuplicate tags are not allowed. 50*33f40117STimur Tabi 51*33f40117STimur TabiA TLV file may contain additional tags not described in this document. 52*33f40117STimur Tabi 53*33f40117STimur TabiValues 54*33f40117STimur Tabi====== 55*33f40117STimur TabiValues are one of four types. The type is not encoded in the format; rather, 56*33f40117STimur Tabithe parser expects a given tag to have a value of a given type. 57*33f40117STimur Tabi 58*33f40117STimur Tabi1) Integers, encoded in 32-bit or 64-bit little-endian format. 59*33f40117STimur Tabi2) Strings, encoded as-is and required to be only printable ASCII characters 60*33f40117STimur Tabi and without a null terminator. 61*33f40117STimur Tabi3) An array of bytes, for binary data. 62*33f40117STimur Tabi4) Boolean, encoded as single byte, with a value of 0 for False or 1 for True. 63*33f40117STimur Tabi 64*33f40117STimur TabiCommon Tags 65*33f40117STimur Tabi=========== 66*33f40117STimur TabiThese tags are shared across firmware types and carry the same meaning 67*33f40117STimur Tabiwherever they appear. Unlike the firmware-specific tags below, a common tag 68*33f40117STimur Tabiis reserved: its meaning is fixed and may never be redefined for a particular 69*33f40117STimur Tabifirmware type. 70*33f40117STimur Tabi 71*33f40117STimur Tabi``VERS`` (string) 72*33f40117STimur Tabi Human-readable firmware version string. Present in all TLV files. 73*33f40117STimur Tabi 74*33f40117STimur TabiA TLV image must contain either a single ``BLOB`` tag (firmware embedded 75*33f40117STimur Tabiinline) or a ``SIZE``/``FILE`` pair (firmware stored in a separate file). 76*33f40117STimur Tabi 77*33f40117STimur Tabi``BLOB`` (bytes) 78*33f40117STimur Tabi If the firmware microcode binary is stored in the TLV, this tag contains 79*33f40117STimur Tabi the actual firmware image bytes. 80*33f40117STimur Tabi 81*33f40117STimur Tabi``FILE`` (string) 82*33f40117STimur Tabi If the firmware binary is stored as a separate file, this tag contains the 83*33f40117STimur Tabi name of that file, which is required to be in the same directory as the TLV, 84*33f40117STimur Tabi so no paths are allowed in the filename. This tag is always paired with 85*33f40117STimur Tabi ``SIZE``, so as to allow the driver to pre-allocate the buffer before 86*33f40117STimur Tabi loading the file. 87*33f40117STimur Tabi 88*33f40117STimur Tabi``SIZE`` (u32) 89*33f40117STimur Tabi Total size in bytes of the firmware image to be loaded from the companion 90*33f40117STimur Tabi file named by ``FILE``. This tag is mandatory if ``FILE`` exists, so the 91*33f40117STimur Tabi size of the firmware image must be known when the TLV is created. If the 92*33f40117STimur Tabi firmware image is updated and its size changes, then the TLV must be 93*33f40117STimur Tabi updated with it. 94*33f40117STimur Tabi 95*33f40117STimur TabiGSP Firmware Tags 96*33f40117STimur Tabi================= 97*33f40117STimur Tabi``SIGN`` (bytes) 98*33f40117STimur Tabi Cryptographic signature for the GSP firmware. 99*33f40117STimur Tabi 100*33f40117STimur Tabi``BLID`` (string) 101*33f40117STimur Tabi The build ID, extracted from the ".note.gnu.build-id" section. 102*33f40117STimur Tabi 103*33f40117STimur TabiBooter Firmware Tags 104*33f40117STimur Tabi==================== 105*33f40117STimur Tabi``DAOF`` (u32) - ``os_data_offset`` 106*33f40117STimur Tabi OS data section offset within the firmware image (absolute byte offset). 107*33f40117STimur Tabi Maps to the DMEM load source. 108*33f40117STimur Tabi 109*33f40117STimur Tabi``DASZ`` (u32) - ``os_data_size`` 110*33f40117STimur Tabi OS data section size in bytes. 111*33f40117STimur Tabi 112*33f40117STimur Tabi``CDOF`` (u32) - ``os_code_offset`` 113*33f40117STimur Tabi OS code section offset within the firmware image (absolute byte offset). 114*33f40117STimur Tabi Maps to the non-secure IMEM load source. 115*33f40117STimur Tabi 116*33f40117STimur Tabi``CDSZ`` (u32) - ``os_code_size`` 117*33f40117STimur Tabi OS code section size in bytes. 118*33f40117STimur Tabi 119*33f40117STimur Tabi``PLOC`` (u32) - ``patch_loc`` 120*33f40117STimur Tabi Signature patch location -- byte offset within the firmware image where the 121*33f40117STimur Tabi selected signature should be written. 122*33f40117STimur Tabi 123*33f40117STimur Tabi``FUSE`` (u32) - ``fuse_version`` 124*33f40117STimur Tabi Fuse version of the firmware, used with the hardware fuse register to 125*33f40117STimur Tabi select the correct signature index. 126*33f40117STimur Tabi 127*33f40117STimur Tabi``ENID`` (u32) - ``engine_id`` 128*33f40117STimur Tabi Engine ID mask identifying the falcon engine this firmware targets. 129*33f40117STimur Tabi 130*33f40117STimur Tabi``UCID`` (u32) - ``ucode_id`` 131*33f40117STimur Tabi Microcode ID used together with the engine ID to query hardware signature 132*33f40117STimur Tabi fuse registers. 133*33f40117STimur Tabi 134*33f40117STimur Tabi``A0CO`` (u32) - ``app0_code_offset`` 135*33f40117STimur Tabi App0 code offset -- start of the secure code region within the firmware 136*33f40117STimur Tabi image. Used as the IMEM secure section source. 137*33f40117STimur Tabi 138*33f40117STimur Tabi``A0CS`` (u32) - ``app0_code_size`` 139*33f40117STimur Tabi App0 code size in bytes. 140*33f40117STimur Tabi 141*33f40117STimur Tabi``NSIG`` (u32) - ``num_sigs`` 142*33f40117STimur Tabi Number of signatures included in the ``SIGN`` tag. 143*33f40117STimur Tabi 144*33f40117STimur Tabi``SIGN`` (bytes) 145*33f40117STimur Tabi Concatenated array of firmware signatures. The size of each signature is 146*33f40117STimur Tabi the total length of the ``SIGN`` value divided by ``NSIG``. The correct 147*33f40117STimur Tabi signature is selected using the fuse-version-derived index. 148*33f40117STimur Tabi 149*33f40117STimur TabiGeneric Bootloader Tags 150*33f40117STimur Tabi======================= 151*33f40117STimur Tabi``CDSZ`` (u32) - ``code_size`` 152*33f40117STimur Tabi Size in bytes of the bootloader code to copy from the ``BLOB`` tag and 153*33f40117STimur Tabi PIO-load into falcon IMEM. 154*33f40117STimur Tabi 155*33f40117STimur Tabi``STRT`` (u32) - ``start_tag`` 156*33f40117STimur Tabi Start tag identifying the IMEM block where execution begins. The falcon 157*33f40117STimur Tabi boot address is derived as ``start_tag << 8``. 158*33f40117STimur Tabi 159*33f40117STimur TabiGSP Bootloader Tags 160*33f40117STimur Tabi=================== 161*33f40117STimur Tabi``CDOF`` (u32) - ``code_offset`` 162*33f40117STimur Tabi Offset within the firmware image at which the code section starts. 163*33f40117STimur Tabi 164*33f40117STimur Tabi``DAOF`` (u32) - ``data_offset`` 165*33f40117STimur Tabi Offset within the firmware image at which the data section starts. 166*33f40117STimur Tabi 167*33f40117STimur Tabi``MFOF`` (u32) - ``manifest_offset`` 168*33f40117STimur Tabi Offset within the firmware image at which the manifest starts. 169*33f40117STimur Tabi 170*33f40117STimur Tabi``APPV`` (u32) - ``app_version`` 171*33f40117STimur Tabi Application version of the firmware. 172*33f40117STimur Tabi 173*33f40117STimur TabiFMC Firmware Tags 174*33f40117STimur Tabi================= 175*33f40117STimur Tabi``HASH`` (bytes) 176*33f40117STimur Tabi SHA-384 hash of the FMC firmware, exactly 48 bytes long. 177*33f40117STimur Tabi 178*33f40117STimur Tabi``PKEY`` (bytes) 179*33f40117STimur Tabi Public key used to verify the FMC firmware. At most 384 bytes (RSA-3072), 180*33f40117STimur Tabi but may be shorter. 181*33f40117STimur Tabi 182*33f40117STimur Tabi``SIGN`` (bytes) 183*33f40117STimur Tabi Signature of the FMC firmware. At most 384 bytes (RSA-3072), but may 184*33f40117STimur Tabi be shorter. 185