WIP: doc: tfm: Add documentation regarding configurable build #19562

SeppoTakalo · 2024-12-16T14:13:58Z

Add documentation regarding CONFIG_TFM_PROFILE_TYPE_NOT_SET and various TF-M partitions that user need to configure.

NOTE: This is very early phase. This work is still in progress, but I'm just starting the review process very early.

NordicBuilder · 2024-12-16T14:18:25Z

CI Information

^{To view the history of this post, clich the 'edited' button above}
Build number: 8

Inputs:

Sources:

more details

Github labels

Enabled	Name	Description
	ci-disabled	Disable the ci execution
	ci-all-test	Run all of ci, no test spec filtering will be done
	ci-force-downstream	Force execution of downstream even if twister fails
	ci-run-twister	Force run twister
	ci-run-zephyr-twister	Force run zephyr twister

List of changed files detected by CI (0)

Outputs:

Toolchain

Version:
Build docker image:

Test Spec & Results: ✅ Success; ❌ Failure; 🟠 Queued; 🟡 Progress; ◻️ Skipped; ⚠️ Quarantine

❌ Toolchain
❌ Build twister
❌ Integration tests

Note: This message is automatically posted and updated by the CI

NordicBuilder · 2024-12-16T14:32:36Z

You can find the documentation preview for this PR at this link. It will be updated about 10 minutes after the documentation build succeeds.

Note: This comment is automatically posted by the Documentation Publish GitHub Action.

MarkusLassila

Some comments. Moving to right direction.

MarkusLassila · 2024-12-27T07:22:03Z

doc/nrf/releases_and_maturity/migration/migration_guide_spm_to_tf-m.rst

+The Nordic Secure Partition Manager (SPM) was replaced with Trusted Firmware-M (TF-M) as the default trusted execution solution in the nRF Connect SDK 2.1.0.
+This change was made to enhance the security features of the SDK by integrating the more widely adopted TF-M, which aligns with the Arm Platform Security Architecture (PSA).
+
+The migration from SPM to TF-M requires changes in the application code and the partition configuration file.


Suggested change

The migration from SPM to TF-M requires changes in the application code and the partition configuration file.

The migration from SPM to TF-M requires changes in the application code and the possible static partition configuration file.

I'll remove the reference to file because the partition configuration might also be the one that is generated automatically. So it is either static, or generated, but anyway it is not the same as before SPM.

MarkusLassila · 2024-12-27T07:43:48Z

doc/nrf/security/tfm.rst

-* In Isolation level 2 or higher, the number of peripherals configured as secure in Application Root of Trust (ARoT) is limited by the number of available MPU regions.
-* Nordic Semiconductor devices only support the GCC toolchain for building TF-M.
+The minimal version of TF-M is disabled by setting the :kconfig:option:`CONFIG_TFM_PROFILE_TYPE_NOT_SET` option or one of the other build profiles.
+For description of the build profiles, see Trusted Firmware M documentation regarding :ref:`tf-m_profiles`.


I think that we should give a direct recommendation to use CONFIG_TFM_PROFILE_TYPE_NOT_SET in here.

We are not really supporting ARoT-less (no support for TFM_PARTITION_FIRMWARE_UPDATE) or Large (No support for isolation level 3) profiles.

MarkusLassila · 2024-12-27T07:49:02Z

doc/nrf/security/tfm.rst

+     - Disabled
+   * - :kconfig:option:`CONFIG_TFM_PARTITION_FIRMWARE_UPDATE`
+     - Provides firmware update services.
+     - Disabled


We do not really support this partition, so that should be mentioned.

MarkusLassila · 2024-12-27T07:51:30Z

doc/nrf/security/tfm.rst

+     - Provides platform services.
+     - Enabled
+   * - :kconfig:option:`CONFIG_TFM_PARTITION_CRYPTO`
+     - Provides cryptographic services.


I think that it would be beneficial to list which partitions this (and others) require. The functionality is built on top of other partitions and it would be good for the reader to understand this when they start to try to minimize the size.

I know that it is listed in the Kconfig description, but reading that from there is bit clumsy.

MarkusLassila · 2024-12-27T07:53:57Z

doc/nrf/security/tfm.rst

+     - Provides firmware update services.
+     - Disabled
+
+When cryptographic services are enabled, you can configure what crypto modules to include in TF-M by using the ``CONFIG_TFM_CRYPTO_*`` Kconfig options as explained above.


This is missing something.

MarkusLassila · 2024-12-27T08:03:28Z

doc/nrf/security/tfm.rst

+   :align: center
+
+   Partition alignment granularity on different nRF devices.
+
 When the :ref:`partition_manager` is enabled, it will take into consideration the alignment requirements.


Partition manager likely warrants its own chapter in here. I would like to at least give the flow of working with partition manager in here:

Minimize your partitions

Copy the partitions.yaml from build directory as static partitions.yaml.

Modify static partitions.yaml (if necessary) (PS and ITS storage can be set more efficiently, reserve enough space for future updates).

MarkusLassila · 2024-12-27T08:10:40Z

doc/nrf/security/tfm.rst

+   :align: center
+
+   Example of aligning partitions with flash regions.
+
 If you are experiencing any partition alignment issues when using the Partition Manager, check the :ref:`known_issues` page on the main branch.

 The partitions which need to be aligned with the TrustZone flash region size are partitions ``tfm_nonsecure`` and ``nonsecure_storage``.


tfm_storage also needs to be aligned with this, if it is set after non-secure partition.

MarkusLassila · 2024-12-27T08:16:10Z

doc/nrf/security/tfm.rst

@@ -254,38 +267,106 @@ We will decrease the size of the (optional) ``mcuboot_pad`` partition and thus t
      address: 0x8000
      size: 0x4000

+Analyzing TF-M partition size


Some things that are missing:

ITS + PS partition size

tfm_ram_report, tfm_rom_report

Add documentation regarding CONFIG_TFM_PROFILE_TYPE_NOT_SET and various TF-M partitions that user need to configure. Signed-off-by: Seppo Takalo <[email protected]>

Current user guide does not need this information anymore. It should be moved to a separate migration guide. Signed-off-by: Seppo Takalo <[email protected]>

Move building, configuring and limitations to appear before background information on TF-M user guide. Signed-off-by: Seppo Takalo <[email protected]>

Unfortunately TF-M rst file in Zephyr does not have cross-reference labels. Signed-off-by: Seppo Takalo <[email protected]>

Add diagram to show the granularity differences between each HW. Signed-off-by: Seppo Takalo <[email protected]>

SeppoTakalo added the DNM label Dec 16, 2024

SeppoTakalo requested review from juhaylinen and MarkusLassila December 16, 2024 14:13

github-actions bot added doc-required PR must not be merged without tech writer approval. changelog-entry-required Update changelog before merge. Remove label if entry is not needed or already added. labels Dec 16, 2024

SeppoTakalo force-pushed the tfm_partition_docs branch 3 times, most recently from 426dd6c to 536d653 Compare December 23, 2024 14:04

MarkusLassila reviewed Dec 27, 2024

View reviewed changes

SeppoTakalo added 5 commits December 27, 2024 15:06

doc: tfm: Add documentation regarding configurable build

73249fd

Add documentation regarding CONFIG_TFM_PROFILE_TYPE_NOT_SET and various TF-M partitions that user need to configure. Signed-off-by: Seppo Takalo <[email protected]>

doc: tfm: Move SPM migration guide to own page

3e46efa

Current user guide does not need this information anymore. It should be moved to a separate migration guide. Signed-off-by: Seppo Takalo <[email protected]>

doc: tfm: Restructure sections

0b21d18

Move building, configuring and limitations to appear before background information on TF-M user guide. Signed-off-by: Seppo Takalo <[email protected]>

doc: tfm: Add section about analyzing the size

7abc7a9

Unfortunately TF-M rst file in Zephyr does not have cross-reference labels. Signed-off-by: Seppo Takalo <[email protected]>

doc: tfm: Add diagram to describe granularity

e15f633

Add diagram to show the granularity differences between each HW. Signed-off-by: Seppo Takalo <[email protected]>

SeppoTakalo force-pushed the tfm_partition_docs branch from 536d653 to e15f633 Compare December 27, 2024 14:08

SeppoTakalo requested a review from melwee01 December 30, 2024 12:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WIP: doc: tfm: Add documentation regarding configurable build #19562

WIP: doc: tfm: Add documentation regarding configurable build #19562

SeppoTakalo commented Dec 16, 2024

NordicBuilder commented Dec 16, 2024 •

edited

Loading

NordicBuilder commented Dec 16, 2024

MarkusLassila left a comment

MarkusLassila Dec 27, 2024

SeppoTakalo Dec 27, 2024

MarkusLassila Dec 27, 2024

MarkusLassila Dec 27, 2024

MarkusLassila Dec 27, 2024

MarkusLassila Dec 27, 2024

MarkusLassila Dec 27, 2024

MarkusLassila Dec 27, 2024

MarkusLassila Dec 27, 2024

MarkusLassila Dec 27, 2024

	The migration from SPM to TF-M requires changes in the application code and the partition configuration file.
	The migration from SPM to TF-M requires changes in the application code and the possible static partition configuration file.

WIP: doc: tfm: Add documentation regarding configurable build #19562

Are you sure you want to change the base?

WIP: doc: tfm: Add documentation regarding configurable build #19562

Conversation

SeppoTakalo commented Dec 16, 2024

NordicBuilder commented Dec 16, 2024 • edited Loading

CI Information

Inputs:

Sources:

Github labels

Outputs:

Toolchain

Test Spec & Results: ✅ Success; ❌ Failure; 🟠 Queued; 🟡 Progress; ◻️ Skipped; ⚠️ Quarantine

NordicBuilder commented Dec 16, 2024

MarkusLassila left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NordicBuilder commented Dec 16, 2024 •

edited

Loading