From 21f1745857b51534fdc1e734427190dc63dd2c28 Mon Sep 17 00:00:00 2001 From: Manish Pandey Date: Thu, 20 Mar 2025 17:39:13 +0000 Subject: [PATCH 1/5] Add security considerations for Relocating a TL Signed-off-by: Manish Pandey --- source/transfer_list.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/transfer_list.rst b/source/transfer_list.rst index 55be5f9..b9a142a 100644 --- a/source/transfer_list.rst +++ b/source/transfer_list.rst @@ -507,6 +507,9 @@ Inputs: #. If `has_checksum`, add the sum of the 4 bytes from `new_tl_base + 0xc` to `new_tl_base + 0x10` to `tl.checksum` (`new_tl_base + 0x4`). +.. note:: + After relocating a TL, implementations should consider scrubbing the old TL memory if it contains + any secrets that might be accessible to later untrusted software. .. _sec_std_entries: From be2d04533e65cd2311ff7c2d359e1f3306239de4 Mon Sep 17 00:00:00 2001 From: Manish Pandey Date: Tue, 25 Mar 2025 14:29:07 +0000 Subject: [PATCH 2/5] Describe helper utility for adding a Void TE Steps for adding a void TE was already described in creating a new TE but this operation can be used at multiple places so introduce it as stand alone operation so that it can be referenced elsewhere. Signed-off-by: Manish Pandey --- source/transfer_list.rst | 46 +++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 15 deletions(-) diff --git a/source/transfer_list.rst b/source/transfer_list.rst index b9a142a..52bb3af 100644 --- a/source/transfer_list.rst +++ b/source/transfer_list.rst @@ -392,23 +392,13 @@ Inputs: starting at `te_base_addr` to `tl.checksum`. #. If an existing XFERLIST_VOID TE was chosen to be overwritten in step 1, and - `old_void_data_size - new_data_size` is greater or equal to `0x8`: + `old_void_data_size - new_data_size` is greater than or equal to `0x8`, then + create a new void TE to fill the remaining space by calling `Adding a void TE`_ + with the following arguments: - #. Use `te_base_addr + align8(new_data_size + 0x8)` as the new `te_base_addr` - for a new XFERLIST_VOID tag. + #. `void_te.base_addr` = `te_base_addr + align8(new_data_size + 0x8)` - #. If `has_checksum`, subtract the sum of the 8 bytes from `te_base_addr` to - `te_base_addr + 0x8` from `tl.checksum`. - - #. Set `te.tag_id` (`te_base_addr + 0x0`) to `0x0` (XFERLIST_VOID). - - #. Set `te.hdr_size` (`te_base_addr + 0x3`) to `0x8`. - - #. Set `te.data_size` (`te_base_addr + 0x4`) to - `old_void_data_size - align8(new_data_size) - 0x8`. - - #. If `has_checksum`, add the sum of the 8 bytes from `te_base_addr` to - `te_base_addr + 0x8` to `tl.checksum`. + #. `void_te.data_size` = `old_void_data_size - align8(new_data_size + 0x8)` Adding a new TE with special data alignment requirement ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -511,6 +501,32 @@ Inputs: After relocating a TL, implementations should consider scrubbing the old TL memory if it contains any secrets that might be accessible to later untrusted software. +Helper Routines +^^^^^^^^^^^^^^^ + +Adding a void TE +~~~~~~~~~~~~~~~~ + +Inputs: + +- `te_base_addr`: Base address where void TE to be added +- `data_size`: Size in bytes of the data to be encapsulated in void TE + +#. If `has_checksum`, subtract the sum of `te.hdr_size + data_size` bytes starting at + `te_base_addr` from `tl.checksum`. + +#. Set `te.tag_id` (`te_base_addr + 0x0`) to `0x0` (XFERLIST_VOID) + +#. Set `te.hdr_size` (`te_base_addr + 0x3`) to `0x8` + +#. Set `te.data_size` (`te_base_addr + 0x4`) to `align8(data_size)` + +#. *(optional)* Set the `data_size` bytes starting at `te_base_addr + te.hdr_size` to 0x0 + +#. If `has_checksum`, add the sum of `te.hdr_size + data_size` bytes starting at + `te_base_addr` with `tl.checksum` + + .. _sec_std_entries: Standard transfer entries From b94bcf067902351ab995246270c0fff9cfe91fa2 Mon Sep 17 00:00:00 2001 From: Manish Pandey Date: Mon, 24 Mar 2025 17:25:47 +0000 Subject: [PATCH 3/5] Describe "Removing a TE" operation Signed-off-by: Manish Pandey --- source/transfer_list.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/source/transfer_list.rst b/source/transfer_list.rst index 52bb3af..81e500e 100644 --- a/source/transfer_list.rst +++ b/source/transfer_list.rst @@ -400,6 +400,23 @@ Inputs: #. `void_te.data_size` = `old_void_data_size - align8(new_data_size + 0x8)` +Removing a TE +^^^^^^^^^^^^^ + +Inputs: + +- `te_base_addr`: Base address of the TE to be removed + +#. Invoke `Adding a void TE`_ with following arguments + + #. `void_te.base_addr` = `te_base_addr` + + #. `void_te.size` = `te.data_size + te.hdr_size - 0x8` + +#. *(Optional)* Implementations may perform memory management by inspecting adjacent entries + and coalescing consecutive `XFERLIST_VOID` entries into a single larger one. This can help + reduce fragmentation and improve reuse of space in the Transfer List. + Adding a new TE with special data alignment requirement ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 6a66fbac99c5fa3be5974ae28e91c5937bed91fc Mon Sep 17 00:00:00 2001 From: Manish Pandey Date: Tue, 25 Mar 2025 13:27:31 +0000 Subject: [PATCH 4/5] Describe "Overwriting a TE" operation Overwrite operation is used to replace content of a given TE Signed-off-by: Manish Pandey --- source/transfer_list.rst | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/source/transfer_list.rst b/source/transfer_list.rst index 81e500e..330f6ba 100644 --- a/source/transfer_list.rst +++ b/source/transfer_list.rst @@ -417,6 +417,39 @@ Inputs: and coalescing consecutive `XFERLIST_VOID` entries into a single larger one. This can help reduce fragmentation and improve reuse of space in the Transfer List. +Overwriting a TE +^^^^^^^^^^^^^^^^ + +Inputs: + +- `te_base_addr`: Base address of the Transfer Entry (TE) to be overwritten +- `new_data_size`: Size in bytes of the new data to be encapsulated in the TE +- [data]: Data to be copied into the TE + +#. If `te.data_size` is smaller than `new_data_size`, the overwrite operation must return an error. + The caller is then responsible for: + + #. Reclaiming the existing space by calling `Adding a void TE`_ with `te_base_addr` and `te.data_size`. + + #. Adding a new TE by invoking `Adding a new TE`_ with appropriate arguments. + +#. If `has_checksum`, subtract the sum of `te.data_size` bytes starting at + `te_base_addr + te.hdr_size` from `tl.checksum`. + +#. Set `te.data_size` (`te_base_addr + 0x4`) to `align8(new_data_size)`. + +#. Copy or generate the new TE data into `te_base_addr + te.hdr_size`. + +#. If `has_checksum`, add the sum of `align8(new_data_size)` bytes starting at + `te_base_addr + te.hdr_size` to `tl.checksum`. + +#. If `te.data_size - align8(new_data_size)` is greater than or equal to `0x8`, create a new + void TE to fill the remaining space by calling `Adding a void TE`_ with the following arguments: + + #. `te_base_addr` = `te_base_addr + align8(new_data_size + te.hdr_size)` + + #. `data_size` = `te.data_size - align8(new_data_size - 0x8)` + Adding a new TE with special data alignment requirement ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 740dfd07e0fb44acb66a8cfac54043e71785032c Mon Sep 17 00:00:00 2001 From: Manish Pandey Date: Thu, 18 Dec 2025 11:48:44 +0000 Subject: [PATCH 5/5] Replace hardcoded 0x8 with te.hdr_size in standard operations Updated the "Standard Operations" section to consistently use `te.hdr_size` instead of the hardcoded `0x8`. Also add a note explaining the assumption of `te.hdr_size = 0x8` and its potential future configurability. This improves consistency, avoids magic numbers, and prepares the format for variable-sized TE headers. Signed-off-by: Manish Pandey --- source/transfer_list.rst | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/source/transfer_list.rst b/source/transfer_list.rst index 330f6ba..63a1ad8 100644 --- a/source/transfer_list.rst +++ b/source/transfer_list.rst @@ -292,6 +292,11 @@ 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. +.. note:: +This section assumes te.hdr_size is 0x8 for all TE entries. This is used consistently throughout the examples. +In the future, if entries with different header sizes are introduced, some operations may need to explicitly +take te.hdr_size as an argument. + Validating a TL header ^^^^^^^^^^^^^^^^^^^^^^ @@ -338,8 +343,7 @@ Inputs: is smaller or equal to `tl.used_size`, otherwise abort (the TL is corrupted). #. If `te.tag_id` (`te_base_addr + 0x0`) is a known tag, interpret the data - at `te_base_addr + te.hdr_size` accordingly. (Do not hardcode the value - for `te.hdr_size`, even for known tags!) Otherwise, ignore the tag and + at `te_base_addr + te.hdr_size` accordingly. Otherwise, ignore the tag and proceed with the next step. #. Add `align8(te.hdr_size + te.data_size)` to `te_base_addr`. @@ -362,14 +366,14 @@ Inputs: #. Use the `te_base_addr` of this tag for the rest of the operation. - #. If `has_checksum`, Subtract the sum of `align8(new_data_size + 0x8)` bytes + #. If `has_checksum`, Subtract the sum of `align8(new_data_size + te.hdr_size)` bytes starting at `te_base_addr` from `tl.checksum`. #. Skip the next step (step 2) with all its substeps. #. Calculate `te_base_addr` as `tl_base_addr + tl.used_size`. - #. If `tl.total_size - tl.used_size` is smaller than `align8(new_data_size + 0x8)`, + #. If `tl.total_size - tl.used_size` is smaller than `align8(new_data_size + te.hdr_size)`, abort (not enough room to add TE). #. If `has_checksum`, subtract the sum of the 4 bytes from @@ -386,19 +390,19 @@ Inputs: #. Set `te.data_size` (`te_base_addr + 0x4`) to `new_data_size`. -#. Copy or generate the TE data into `te_base_addr + 0x8`. +#. Copy or generate the TE data into `te_base_addr + te.hdr_size`. -#. If `has_checksum`, add the sum of `align8(new_data_size + 0x8)` bytes +#. If `has_checksum`, add the sum of `align8(new_data_size + te.hdr_size)` bytes starting at `te_base_addr` to `tl.checksum`. #. If an existing XFERLIST_VOID TE was chosen to be overwritten in step 1, and - `old_void_data_size - new_data_size` is greater than or equal to `0x8`, then + `old_void_data_size - new_data_size` is greater than or equal to `te.hdr_size`, then create a new void TE to fill the remaining space by calling `Adding a void TE`_ with the following arguments: - #. `void_te.base_addr` = `te_base_addr + align8(new_data_size + 0x8)` + #. `void_te.base_addr` = `te_base_addr + align8(new_data_size + te.hdr_size)` - #. `void_te.data_size` = `old_void_data_size - align8(new_data_size + 0x8)` + #. `void_te.data_size` = `old_void_data_size - align8(new_data_size + te.hdr_size)` Removing a TE ^^^^^^^^^^^^^ @@ -411,7 +415,7 @@ Inputs: #. `void_te.base_addr` = `te_base_addr` - #. `void_te.size` = `te.data_size + te.hdr_size - 0x8` + #. `void_te.size` = `te.data_size` #. *(Optional)* Implementations may perform memory management by inspecting adjacent entries and coalescing consecutive `XFERLIST_VOID` entries into a single larger one. This can help @@ -443,12 +447,12 @@ Inputs: #. If `has_checksum`, add the sum of `align8(new_data_size)` bytes starting at `te_base_addr + te.hdr_size` to `tl.checksum`. -#. If `te.data_size - align8(new_data_size)` is greater than or equal to `0x8`, create a new +#. If `te.data_size - align8(new_data_size)` is greater than or equal to `te.hdr_size`, create a new void TE to fill the remaining space by calling `Adding a void TE`_ with the following arguments: #. `te_base_addr` = `te_base_addr + align8(new_data_size + te.hdr_size)` - #. `data_size` = `te.data_size - align8(new_data_size - 0x8)` + #. `data_size` = `te.data_size - align8(new_data_size - te.hdr_size)` Adding a new TE with special data alignment requirement ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^