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