diff --git a/contributing.rst b/contributing.rst index 67bc8fa..6ac53b9 100644 --- a/contributing.rst +++ b/contributing.rst @@ -29,6 +29,8 @@ Criteria for patch merge Any contribution must be assessed by the maintainers (see Maintainers_). A contribution must be acknowledged by every maintainer before being merged. +This specification adopts a lower-case variation of RFC2119. +The Language used to specify requirements and recommendations must comply with [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119). .. _DCO: DCO .. _LICENSE: LICENSE diff --git a/source/introduction.rst b/source/introduction.rst index 19ee4f1..fedce18 100644 --- a/source/introduction.rst +++ b/source/introduction.rst @@ -4,6 +4,12 @@ Introduction ============ +The key words "must", "must not", "required", "shall", "shall +not", "should", "should not", "recommended", "may", and +"optional" in this document are to be interpreted as described in +[RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). + + A platform initialization procedure may involve the execution of a sequence of firmware stages. It is assumed that only the primary boot core is active during the transition point between firmware stages, the remaining cores must be held @@ -33,10 +39,10 @@ stage concept. Platforms are free to adopt any other boot architecture. Example boot architecture -Depending on the platform, the cold-boot initialization can start from a Board +Depending on the platform, the cold-boot initialization may start from a Board Controller which then releases the Application Processor (AP) into execution. -The boot process on the AP can conceptually be broken apart into the following +The boot process on the AP may conceptually be broken apart into the following stages: * Immutable @@ -45,17 +51,17 @@ stages: * Secure Platform Firmware - * Firmware stage that is executed in a privileged level. It is responsible for loading additional firmware images and optionally performing platform configurations. The stage can be subdivided into other sub-stages. The stage terminates with the transition to the OS Bootloader. + * Firmware stage that is executed in a privileged level. It may be responsible for loading additional firmware images and may perform platform configurations. The stage may be subdivided into other sub-stages. The stage should terminate with the transition to the OS Bootloader. * OS Bootloader - * The firmware stage that executes before the OS. It is responsible for configuring the platform, loading and transferring the execution to the OS. This stage can be composed of several sub-stages. + * The firmware stage that executes before the OS. It should configure the platform, load and transfer the execution to the OS. This stage may be composed of several sub-stages. -Any stage in the AP boot procedure can produce information which is consumed by +Any stage in the AP boot procedure may produce information which is consumed by a later stage. This specification defines the concept of *Transfer List* (TL -- -:numref:`sec_tl`). A firmware stage can append information to the TL. +:numref:`sec_tl`). A firmware stage may append information to the TL. Any information produced by a firmware stage, meant to be consumed by a later firmware stage, must be contained in an entry (:numref:`sec_tl`) in the TL or be directly accessible via the information @@ -64,7 +70,7 @@ A firmware stage transfers the execution flow to a next firmware stage at a poin *handoff boundary*. The TL is transferred between stages at the *handoff boundary*. For a particular *handoff boundary*, the firmware stage that hands off the list to a next stage is termed the *Sender*. The firmware stage -receiving the list is termed the *Receiver*. The *Receiver* can update fields in +receiving the list is termed the *Receiver*. The *Receiver* may update fields in any entry in the list and is allowed to remove entries. diff --git a/source/transfer_list.rst b/source/transfer_list.rst index d3cbf06..29b86de 100644 --- a/source/transfer_list.rst +++ b/source/transfer_list.rst @@ -8,13 +8,13 @@ Transfer list ============= -The TL is composed of a TL header which is followed by sequence of Transfer -Entries (TE). The whole TL is contiguous in physical address space. The TL +The TL must have a TL header which must be followed by one or more Transfer +Entries (TE). The whole TL must be contiguous in physical address space. The TL header and all the TEs are 8-byte aligned (we use `align8()` to denote this). The TL header specifies the number of bytes occupied by the TL. The TEs are defined in :numref:`sec_tl_entry_hdr` and :numref:`sec_std_entries`. Each TE carries a header which contains an -identifier, `tag_id`, that is used to determine the content of the associated +identifier, `tag_id`, that must be used to determine the content of the associated TE. The TL header is located at `tl_base_pa`. The `tl_base_pa` is passed in the register allocated for that handoff boundary (as specified in :numref:`handoff_arch_bindings`). A @@ -47,12 +47,12 @@ Transfer list header -------------------- A TL must begin with a TL header. The layout of the TL header is shown in -:numref:`tab_tl_header`. The presence of a TL header can be verified by +:numref:`tab_tl_header`. The presence of a TL header may be verified by inspecting the signature field which must contain the 4a0f_b10b value. The version field determines the contents of the handoff start header. The version -will only be changed by an update to this specification when new TL header or +must only be changed by an update to this specification, when new TL header or TE header fields are defined (i.e. not when allocating new tag IDs), and all -changes will be backwards-compatible to older readers. +changes must be backwards-compatible to older readers. .. _tab_tl_header: .. list-table:: TL header @@ -71,12 +71,12 @@ changes will be backwards-compatible to older readers. * - checksum - 0x1 - 0x4 - - If enabled by the flags, the checksum is used to provide basic protection against something overwriting the TL in memory. The checksum is set to a value such that the xor over every byte in the {`tl_base_pa`, …, `tl_base_pa + used_size - 1`} address range, is equal to 0. For the purposes of this calculation, the value of this checksum field in the TL header must be assumed as 0. Note that the checksum includes the TL header, all TEs and the inter-TE padding, but not the range reserved for future TE additions up to total_size. The values of inter-TE padding bytes are not defined by this specification and may be uninitialized memory. (This means that multiple TLs with exactly the same size and contents may still have different checksum values.). If checksums are not used, this must be 0. + - If enabled by the flags, the checksum may be used to provide basic protection against something overwriting the TL in memory. The checksum must be set to a value such that the xor over every byte in the {`tl_base_pa`, …, `tl_base_pa + used_size - 1`} address range, is equal to 0. For the purposes of this calculation, the value of this checksum field in the TL header must be assumed as 0. Note that the checksum must include the TL header, all TEs and the inter-TE padding, but must not include the range reserved for future TE additions up to total_size. The values of inter-TE padding bytes are not defined by this specification and may be uninitialized memory. (This means that multiple TLs with exactly the same size and contents may still have different checksum values.). If checksums are not used, this must be 0. * - version - 0x1 - 0x5 - - The version of the TL header. This field is set to |current_version| for the TL header layout described in this version of the table. Code that encounters a TL with a version higher than it knows to support may still read the TL and all its TEs, and assume that it is backwards-compatible to previous versions (ignoring any extra bytes in a potentially larger TL or TE header). However, code may not append new entries to a TL unless it knows how to append entries for the specified version. + - The version of the TL header. This field must be set to |current_version| for the TL header layout described in this version of the table. Code that encounters a TL with a version higher than it knows to support may still read the TL and all its TEs, and assume that it is backwards-compatible to previous versions (ignoring any extra bytes in a potentially larger TL or TE header). However, code must not append new entries to a TL unless it knows how to append entries for the specified version. * - hdr_size - 0x1 @@ -86,7 +86,7 @@ changes will be backwards-compatible to older readers. * - alignment - 0x1 - 0x7 - - The maximum alignment required by any TE in the TL, specified as a power of two. For a newly created TL, the alignment requirement is 8 so this value should be set to 3. It should be updated whenever a new TE is added with a larger requirement than the current value. + - The maximum alignment required by any TE in the TL, specified as a power of two. For a newly created TL, the alignment requirement is 8 so this value must be set to 3. It must be updated whenever a new TE is added with a larger requirement than the current value. * - used_size - 0x4 @@ -138,7 +138,7 @@ field. TL entry header --------------- -All TEs start with an entry header followed by a data section. +All TEs must start with an entry header followed by a data section. Note: the size of an entry (hdr_size + data_size) is not mandatorily an 8-byte multiple. When traversing the TL firmware must compute the next TE address following @@ -172,7 +172,7 @@ The TE header is defined in :numref:`tab_te_header`. * - hdr_size - 0x1 - 0x3 - - The size of this entry header in bytes. This field is set to 8 for the TE header layout described in this version of the table. + - The size of this entry header in bytes. This field must be set to 8 for the TE header layout described in this version of the table. * - data_size - 0x4 @@ -183,7 +183,7 @@ The TE header is defined in :numref:`tab_te_header`. TL Contents ----------- -Tags are expected to have a simple layout (representable by a C structure) and +The tags should have a simple layout (representable by a C structure) and each tag should only represent data for a single logical concept. Data for multiple distinct concepts should be split across different tags, even if they're always expected to appear together on the first platform adding the tag @@ -192,7 +192,7 @@ may be represented in a different kind of well-established handoff data structure (e.g. FDT [DT]_, HOB [PI]_) that is inserted into the TL as a single TE. The same tag ID may occur multiple times in the TL to represent multiple instances of the same kind of object. Tag layouts (including the meaning of all -fields) are considered stable after being added to this specification and may +fields) are considered stable after being added to this specification and must never be changed in a backwards-incompatible way. If a backwards-incompatible change is desired, a new tag ID should be allocated for the new version of the layout instead. @@ -234,20 +234,20 @@ Entry-type allocation Tag IDs must be allocated in this specification before use. A new tag ID can be allocated by submitting a pull request to this repository that adds a description of the respective TE data layout to this specification. Tag IDs do -not have to be allocated in order. Submitters are encouraged to try to group +not have to be allocated in order. Submitters should try to group tag IDs together in logical clusters at 16 or 256-aligned boundaries (e.g. all -tags related to a particular chipset or to a particular firmware project could +tags related to a particular chipset or to a particular firmware project may use adjacent tag numbers), but there are no predefined ranges and no reservations of tag ranges for specific use. The {0xff_f000, ..., 0xff_ffff} range is reserved for non-standardized use. -Anyone is free to use tags from that range for any custom TE layout without -adding their definitions to this specification first. The use of this range is -*strongly discouraged* for anything other than local experiments or code that +Anyone may use tags from that range for any custom TE layout without +adding their definitions to this specification first. The use of this range +should not be used for anything other than local experiments or code that will only ever be used in closed-source components owned by the entity -controlling the entire final firmware image. In particular, a TE just -containing platform-specific data or internal structures specific to a single -firmware implementation is no reason not to allocate a standardized tag for it +controlling the entire final firmware image. In particular, a creator of a TE +that just contains platform-specific data or internal structures specific to +a single firmware implementation, should allocate a standardized tag for it in this specification. Since standards often emerge organically, the goal is to create unique tag IDs for everything just in case it turns out to be useful in more applications than initially anticipated. Basically, whenever you're @@ -270,7 +270,7 @@ specification. - Reserved. (Can later be used to extend standardized range if necessary.) * - 0xff_f000 -- 0xff_ffff - - Non-standardized range. Tag IDs in this range can be used without allocation in this specification. Using this range for anything other than local experimentation or closed-source components that are entirely under the control of a single platform firmware integrator is strongly discouraged. Tags in this range are not tracked in this repository and PRs to add tag defintions for this range will not be accepted. + - Non-standardized range. Tag IDs in this range may be used without allocation in this specification. This range should not be used for anything other than local experimentation or closed-source components that are entirely under the control of a single platform firmware integrator. Tags in this range are not tracked in this repository and PRs to add tag defintions for this range will not be accepted. .. _sec_operations: @@ -278,7 +278,7 @@ specification. Standard operations ------------------- -This section describes the valid operations that can be performed on a TL in +This section describes the valid operations that may be performed on a TL in more detail, in order to clarify how to use the various fields and to serve as a guideline for implementation.