 |
TT-System-Firmware APIs 19.15.99
Tenstorrent Firmware
|
|
TT-System-Firmware APIs 19.15.99
Tenstorrent Firmware
|
#include <tt_bundle_loader.h>
Data Fields | |
| uint32_t | manifest_identifier |
| The manifest identifier The manifest_identifier is used to identify which boot stage payload this manifest describes. These values should be 4 character ASCII strings so that hex dumps of a manifest can be identified visually. Defined values are below. All other values are reserved. Tenstorrent may introduce new values to this field in the future. Hex values are in little-endian format. MANIFEST_ID_BL1 MANIFEST_ID_MIS. | |
| uint16_t | manifest_version_major |
| The major version of the manifest Major version of the manifest format that the manifest conforms to. Current major version is 1. Changes to the major version indicate a change that is not backwards compatible. If the major version number in a manifest is greater than the major version for which the software was designed to use the software will reject the manifest. Old software can correctly use a format that only differs by having a larger minor version than it was designed to work with. | |
| uint16_t | manifest_version_minor |
| The minor version of the manifest Minor version of the manifest format. Current minor version is 0. | |
| uint32_t | manifest_length |
| The Length of the manifest in bytes Manifest version 1.0 is 1184 bytes. The manifest will always be a multiple of 8 bytes in length. This ensures proper alignment of fields when manifests are packed together in flash or RAM. The SEP BL0 ROM supports a v1.x manifest ⇐ 2048 bytes in size. | |
| uint32_t | reserved |
| Reserved. Must be 0x0. | |
| uint64_t | selector_bits |
| selector bits | |
| uint8_t | chiplet_id [32] |
| Chiplet identifier Chiplet identifier value which is compared against the CHIPLET_ID value stored in the SEP OTP. Mapped to bits [7:0] of selector_bits. Unselected words must be set to FW_BUNDLE_MANIFEST_UNUSED_WORD. See detailed description below. | |
| uint8_t | package_id [32] |
| Package identifier Package identifier value which is compared against the PACKAGE_ID value stored in the SEP OTP. Mapped to bits [15:8] of selector_bits. Unselected words must be set to FW_BUNDLE_MANIFEST_UNUSED_WORD. See detailed description below. | |
| union fw_bundle_lc_state | lifecycle_states |
| lifecycle state control | |
| union fw_bundle_auth_flags | authenticated_flags |
| Authenticated flags. | |
| uint8_t | encryption_iv [32] |
| Encryption initial vector Only valid when encrypted_payload = 1. | |
| uint8_t | encryption_kdf_input [32] |
| Key Derivation Function's input to derive the key used for encryption Only valid when encrypted_payload =1. | |
| uint16_t | reserved_0 |
| Reserved - must be 0. | |
| uint16_t | security_version |
| Security version of the manifest Used for anti-rollback protection. Must be a monotonically increasing integer. Only valid when boot is secure. When flags.security_version_update == 1, the hardware security version is updated to match the version in this field by SEP BL1 firmware. Maximum security version is device dependent. | |
| uint8_t | encryption_type |
| Encryption algorithm Used when authenticated_flags.encrypted_payload == 1. Allowed values: FW_BUNDLE_ENCRYPTION_TYPE_AES 0xE0-0xEF: chiplet implementation defined 0xF0-0xFF: Package implementation defined All other values reserved. | |
| uint8_t | signature_type |
| Signature algorithm, including padding/hash used for signature of the manifest. Ignored when boot is not secure. Allowed values: FW_BUNDLE_SIGNATURE_TYPE_RSA FW_BUNDLE_SIGNATURE_TYPE_ECC_P256 0xE0-0xEF: chiplet implementation defined 0xF0-0xFF: Package implementation defined All other values: reserved. | |
| union fw_bundle_public_key_sel | public_key_sel |
| Public key selector requested by software. This field contains the index of the public key to be used for authentication. The valid range is determined by the number of keys in the hardware. The selected key needs to be an unrevoked key in the hardware. Boot fails with an error if this value is out of range or selects a revoked key. | |
| uint8_t | public_key [384] |
| Public key used for authentication. This field is sized to support the maximum size key which is RSA 3072. Key types that do not use all of the space occupy the beginning of this field. They unused bits in this field are 0x0. | |
| uint8_t | payload_hash [32] |
| SHA-256 hash digest of the portion of the payload covered by this hash. See payload_hashed_length for more information. | |
| uint64_t | payload_hashed_length |
| Number of bytes of the payload that are covered by payload_hash. For encrypted payloads this length must be equal to the payload length, as the entire encrypted payload must be authenticated before it is decrypted. For cleartext payloads this is the length of the TOC (Table of Contents) portion of the payload. The TOC contains hashes for all images in the payload. This transitive authentication allows for more flexible processing of images in cleartext payloads. | |
| int64_t | timestamp |
| Unix timestamp (64 bit) of the creation time of the manifest. When secure_boot == 1 this is the timestamp of when the signature was generated. This timestamp is not used for security checks. | |
| uint64_t | payload_length |
| Length of payload in bytes. The payload consists of all data between payload_offset and payload_offset + payload_length. When the payload is encrypted this includes any padding added when encryption is performed. For cleartext payloads this length must match the payload_length in the payload TOC. | |
| union fw_bundle_sem_ver | manifest_content_version |
| Version for the payload described by this manifest. | |
| uint8_t | manifest_description [128] |
| ASCII NULL terminated string describing the manifest and payload. This is provided to make identification binary manifests more precise and human readable. This is expected to contain version control details, release status and other useful information. This field is not used by firmware. The final byte of this field (ie manifest_description[127]) must be 0 and this will be set to 0 by software that uses this field to ensure NULL termination. | |
| uint8_t | signature [384] |
| The signature over all preceding fields in the manifest. The type of signature contained in this field is indicated by the signature_type field. This field is sized to support the maximum size used by any of the supported signature types which is RSA-3072. When secure_boot == 0, this field is unused and ignored. | |
| uint8_t | manifest_hash [32] |
| SHA-256 hash over the signed region of the manifest. This hash is required for both secure and non-secure manifests. | |
| int64_t | payload_offset |
| Offset in bytes from the start of the manifest to the start of the payload. This field may be updated when the manifest and payload are written to flash, so this cannot be part of the signed region of the manifest. A negative value indicates that the payload is located before the manifest. | |
| union fw_bundle_unauthed_flags | flags |
| Unauthenticated flags field. | |
| uint8_t | reserved_1 [12] |
| Reserved, must be 0. | |
| union fw_bundle_auth_flags fw_bundle_manifest::authenticated_flags |
Authenticated flags.
| uint8_t fw_bundle_manifest::chiplet_id[32] |
Chiplet identifier Chiplet identifier value which is compared against the CHIPLET_ID value stored in the SEP OTP. Mapped to bits [7:0] of selector_bits. Unselected words must be set to FW_BUNDLE_MANIFEST_UNUSED_WORD. See detailed description below.
| uint8_t fw_bundle_manifest::encryption_iv[32] |
Encryption initial vector Only valid when encrypted_payload = 1.
| uint8_t fw_bundle_manifest::encryption_kdf_input[32] |
Key Derivation Function's input to derive the key used for encryption Only valid when encrypted_payload =1.
| uint8_t fw_bundle_manifest::encryption_type |
Encryption algorithm Used when authenticated_flags.encrypted_payload == 1. Allowed values: FW_BUNDLE_ENCRYPTION_TYPE_AES 0xE0-0xEF: chiplet implementation defined 0xF0-0xFF: Package implementation defined All other values reserved.
| union fw_bundle_unauthed_flags fw_bundle_manifest::flags |
Unauthenticated flags field.
| union fw_bundle_lc_state fw_bundle_manifest::lifecycle_states |
lifecycle state control
| union fw_bundle_sem_ver fw_bundle_manifest::manifest_content_version |
Version for the payload described by this manifest.
| uint8_t fw_bundle_manifest::manifest_description[128] |
ASCII NULL terminated string describing the manifest and payload. This is provided to make identification binary manifests more precise and human readable. This is expected to contain version control details, release status and other useful information. This field is not used by firmware. The final byte of this field (ie manifest_description[127]) must be 0 and this will be set to 0 by software that uses this field to ensure NULL termination.
| uint8_t fw_bundle_manifest::manifest_hash[32] |
SHA-256 hash over the signed region of the manifest. This hash is required for both secure and non-secure manifests.
| uint32_t fw_bundle_manifest::manifest_identifier |
The manifest identifier The manifest_identifier is used to identify which boot stage payload this manifest describes. These values should be 4 character ASCII strings so that hex dumps of a manifest can be identified visually. Defined values are below. All other values are reserved. Tenstorrent may introduce new values to this field in the future. Hex values are in little-endian format. MANIFEST_ID_BL1 MANIFEST_ID_MIS.
| uint32_t fw_bundle_manifest::manifest_length |
The Length of the manifest in bytes Manifest version 1.0 is 1184 bytes. The manifest will always be a multiple of 8 bytes in length. This ensures proper alignment of fields when manifests are packed together in flash or RAM. The SEP BL0 ROM supports a v1.x manifest ⇐ 2048 bytes in size.
| uint16_t fw_bundle_manifest::manifest_version_major |
The major version of the manifest Major version of the manifest format that the manifest conforms to. Current major version is 1. Changes to the major version indicate a change that is not backwards compatible. If the major version number in a manifest is greater than the major version for which the software was designed to use the software will reject the manifest. Old software can correctly use a format that only differs by having a larger minor version than it was designed to work with.
| uint16_t fw_bundle_manifest::manifest_version_minor |
The minor version of the manifest Minor version of the manifest format. Current minor version is 0.
| uint8_t fw_bundle_manifest::package_id[32] |
Package identifier Package identifier value which is compared against the PACKAGE_ID value stored in the SEP OTP. Mapped to bits [15:8] of selector_bits. Unselected words must be set to FW_BUNDLE_MANIFEST_UNUSED_WORD. See detailed description below.
| uint8_t fw_bundle_manifest::payload_hash[32] |
SHA-256 hash digest of the portion of the payload covered by this hash. See payload_hashed_length for more information.
| uint64_t fw_bundle_manifest::payload_hashed_length |
Number of bytes of the payload that are covered by payload_hash. For encrypted payloads this length must be equal to the payload length, as the entire encrypted payload must be authenticated before it is decrypted. For cleartext payloads this is the length of the TOC (Table of Contents) portion of the payload. The TOC contains hashes for all images in the payload. This transitive authentication allows for more flexible processing of images in cleartext payloads.
| uint64_t fw_bundle_manifest::payload_length |
Length of payload in bytes. The payload consists of all data between payload_offset and payload_offset + payload_length. When the payload is encrypted this includes any padding added when encryption is performed. For cleartext payloads this length must match the payload_length in the payload TOC.
| int64_t fw_bundle_manifest::payload_offset |
Offset in bytes from the start of the manifest to the start of the payload. This field may be updated when the manifest and payload are written to flash, so this cannot be part of the signed region of the manifest. A negative value indicates that the payload is located before the manifest.
| uint8_t fw_bundle_manifest::public_key[384] |
Public key used for authentication. This field is sized to support the maximum size key which is RSA 3072. Key types that do not use all of the space occupy the beginning of this field. They unused bits in this field are 0x0.
| union fw_bundle_public_key_sel fw_bundle_manifest::public_key_sel |
Public key selector requested by software. This field contains the index of the public key to be used for authentication. The valid range is determined by the number of keys in the hardware. The selected key needs to be an unrevoked key in the hardware. Boot fails with an error if this value is out of range or selects a revoked key.
| uint32_t fw_bundle_manifest::reserved |
Reserved. Must be 0x0.
| uint16_t fw_bundle_manifest::reserved_0 |
Reserved - must be 0.
| uint8_t fw_bundle_manifest::reserved_1[12] |
Reserved, must be 0.
| uint16_t fw_bundle_manifest::security_version |
Security version of the manifest Used for anti-rollback protection. Must be a monotonically increasing integer. Only valid when boot is secure. When flags.security_version_update == 1, the hardware security version is updated to match the version in this field by SEP BL1 firmware. Maximum security version is device dependent.
| uint64_t fw_bundle_manifest::selector_bits |
selector bits
| uint8_t fw_bundle_manifest::signature[384] |
The signature over all preceding fields in the manifest. The type of signature contained in this field is indicated by the signature_type field. This field is sized to support the maximum size used by any of the supported signature types which is RSA-3072. When secure_boot == 0, this field is unused and ignored.
| uint8_t fw_bundle_manifest::signature_type |
Signature algorithm, including padding/hash used for signature of the manifest. Ignored when boot is not secure. Allowed values: FW_BUNDLE_SIGNATURE_TYPE_RSA FW_BUNDLE_SIGNATURE_TYPE_ECC_P256 0xE0-0xEF: chiplet implementation defined 0xF0-0xFF: Package implementation defined All other values: reserved.
| int64_t fw_bundle_manifest::timestamp |
Unix timestamp (64 bit) of the creation time of the manifest. When secure_boot == 1 this is the timestamp of when the signature was generated. This timestamp is not used for security checks.
1.14.0