Docs: Add configuration section to the doc
+ Rebase and include ARoT-less profile
Signed-off-by: Anton Komlev <anton.komlev@arm.com>
Change-Id: If802fa15297fe25585c7523ad0827395d982c554
diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst
new file mode 100644
index 0000000..7c2cc2d
--- /dev/null
+++ b/docs/configuration/index.rst
@@ -0,0 +1,80 @@
+#############
+Configuration
+#############
+
+.. Warning::
+
+ This is a temporay design document for review.
+ Once the design is settled down.
+ It will be converted to user/integration guides.
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ profiles/index
+
+TF-M is a complex project having many configuration options to adjust project
+for a user needs. A user can select the desired set of services and fine-tune
+them to user's requirements. There are 2 types of configuration options:
+
+1. Building : to select which file or component to include into compilation.
+ These are options, usually used by a build system to enable/disable
+ modules, specify location of external dependency or other selection,
+ global to a project. These options shall be considered while adopting TF-M
+ to other build systems.
+ In the Base configuration table theses options have *Build* type.
+
+2. Component tuning : to adjust a particular parameter to a desired value.
+ Those options are local to a component or externally referenced when
+ components are coupled. Usually, such options are located in C header
+ file. The Header File Config System has more details about it.
+ In the Base configuration table theses options have *Component* type.
+
+.. Note::
+ Originally, TF-M used CMake variables for both building and component tuning
+ purposes. It was convenient to have a single system for both building and
+ component's configurations. To simplify and improve configurability and
+ better support build systems other than a CMake, TF-M introduced a header
+ file configuration and moved component options into a dedicated config headers.
+
+****************
+How to configure
+****************
+
+The default TF-M build includes the minimum set of components required in any
+project: SPM and a selected platform. This is not very useful for any product
+and desired services shall be enabled by a user. There are several independent
+ways to configure TF-M.
+
+1. Use profiles. There are 4 sets of predefined configurations for a elected
+ use cases, called profiles. A user can select a profile by providing
+ -DTFM_PROFILE=<profile file name>.
+ Each profiles represented by a pair of configuration files for
+ Building (CMake) options and Component options (.h file)
+
+2. A custom profile. Another method is to take a profile as a base and manually
+ modify desired options.
+
+3. Use KConfig system. This is recommended method especially for beginners.
+ KConfig ensurers that all selected options are consistent and valid. This
+ is new in v1.7.0 and it covers only SPM and PSA ervices. As an output
+ KConfig produces a pair of configuration files, similar to a profile.
+
+.. Note::
+ In contrast, before TF-M v1.7.0, the default build includes all possible
+ features. With growing functionality, such rich default build became
+ unpractical by not fitting into every platform and confusing of big
+ memory requirements.
+
+**********
+Priorities
+**********
+Note::
+
+ TODO: Need a secion on configuration Priorities
+
+
+--------------
+
+*Copyright (c) 2022, Arm Limited. All rights reserved.*
\ No newline at end of file
diff --git a/docs/configuration/profiles/index.rst b/docs/configuration/profiles/index.rst
new file mode 100644
index 0000000..1b3e69b
--- /dev/null
+++ b/docs/configuration/profiles/index.rst
@@ -0,0 +1,86 @@
+TF-M Profiles
+=============
+
+The capabilities and resources may dramatically vary on different IoT devices.
+Some IoT devices may have very limited memory resource. The program on those devices should keep
+small memory footprint and basic functionalities.
+On the other hand, some devices may consist of more memory and extended storage, to support stronger
+software capabilities.
+
+Diverse IoT use cases also require different levels of security and requirements on device resource.
+For example, use cases require different cipher capabilities. Selecting cipher suites can be
+sensitive to memory footprint on devices with constrained resource.
+
+Trusted Firmware-M (TF-M) defines several general profiles, such as Profile Small, Profile Medium,
+Profile Medium ARoT-less and Profile Large, to provide different levels of security to fit diverse
+device capabilities and use cases applied on the top of the base configuration.
+
+Each profile specifies a predefined list of features, targeting typical use cases with specific
+hardware constraints. Profiles can serve as reference designs, based on which developers can
+continue further development and configurations, according to use case.
+
+TF-M Profiles align with Platform Security Architecture specifications and certification
+guidelines. It can help vendors to simplify security configuring for PSA certification.
+
+Please check the table below to compare differences while details are discussed
+in the links below.
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ Small <tfm_profile_small>
+ ARoT-less <tfm_profile_medium_arot-less>
+ Medium <tfm_profile_medium>
+ Large <tfm_profile_large>
+
++----------------------------------------+--------+--------+---------+--------+--------+
+| Option | Base | Small |ARoT-less| Medium | Large |
++========================================+========+========+=========+========+========+
+| TFM_ISOLATION_LEVEL | 1 | 1 | 1 | 2 | 3 |
++----------------------------------------+--------+--------+---------+--------+--------+
+| CONFIG_TFM_SPM_BACKEND | SFN | SFN | SFN | IPC | IPC |
++----------------------------------------+--------+--------+---------+--------+--------+
+| TFM_PARTITION_CRYPTO | OFF | ON | ON | ON | ON |
++----------------------------------------+--------+--------+---------+--------+--------+
+| TFM_PARTITION_INTERNAL_TRUSTED_STORAGE | OFF | ON | ON | ON | ON |
++----------------------------------------+--------+--------+---------+--------+--------+
+| TFM_PARTITION_PLATFORM | OFF | OFF | ON | ON | ON |
++----------------------------------------+--------+--------+---------+--------+--------+
+| TFM_PARTITION_PROTECTED_STORAGE | OFF | OFF | OFF | ON | ON |
++----------------------------------------+--------+--------+---------+--------+--------+
+| TFM_PARTITION_INITIAL_ATTESTATION | OFF | ON | ON | ON | ON |
++----------------------------------------+--------+--------+---------+--------+--------+
+| SYMMETRIC_INITIAL_ATTESTATION | OFF | ON | OFF | ON | ON |
++----------------------------------------+--------+--------+---------+--------+--------+
+| TFM_PARTITION_FIRMWARE_UPDATE | OFF | OFF | ON | OFF | OFF |
++----------------------------------------+--------+--------+---------+--------+--------+
+| *Advanced options, defined in the corresponded header (.h) file* |
++----------------------------------------+--------+--------+---------+--------+--------+
+| CRYPTO_ENGINE_BUF_SIZE | 0x2080 | 0x400 | 0x2080 | 0x2080 | 0x2080 |
++----------------------------------------+--------+--------+---------+--------+--------+
+| CRYPTO_ASYM_SIGN_MODULE_DISABLED | OFF | ON | OFF | OFF | OFF |
++----------------------------------------+--------+--------+---------+--------+--------+
+| PS_CRYPTO_AEAD_ALG | GCM | GCM | CCM | CCM | GCM |
++----------------------------------------+--------+--------+---------+--------+--------+
+| CRYPTO_ASYM_ENCRYPT_MODULE_DISABLED | OFF | ON | ON | ON | OFF |
++----------------------------------------+--------+--------+---------+--------+--------+
+| CRYPTO_SINGLE_PART_FUNCS_DISABLED | OFF | ON | OFF | OFF | OFF |
++----------------------------------------+--------+--------+---------+--------+--------+
+| CRYPTO_CONC_OPER_NUM | 8 | 4 | 8 | 8 | 8 |
++----------------------------------------+--------+--------+---------+--------+--------+
+| PSA_FRAMEWORK_HAS_MM_IOVEC | OFF | ON | OFF | OFF | OFF |
++----------------------------------------+--------+--------+---------+--------+--------+
+| CONFIG_TFM_CONN_HANDLE_MAX_NUM | 8 | 3 | 8 | 8 | 8 |
++----------------------------------------+--------+--------+---------+--------+--------+
+| ITS_BUF_SIZE | | 32 | 32 | | |
++----------------------------------------+--------+--------+---------+--------+--------+
+| MCUBOOT_IMAGE_NUMBER | | 1 | | | |
++----------------------------------------+--------+--------+---------+--------+--------+
+
+Each profile has predefined configuration for cryptographic library, located in
+``/lib/ext/mbedcrypto/mbedcrypto_config/``
+
+--------------
+
+Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/design_docs/profiles/tfm_profile_large.rst b/docs/configuration/profiles/tfm_profile_large.rst
similarity index 98%
rename from docs/technical_references/design_docs/profiles/tfm_profile_large.rst
rename to docs/configuration/profiles/tfm_profile_large.rst
index b5a1ba2..841a2b1 100644
--- a/docs/technical_references/design_docs/profiles/tfm_profile_large.rst
+++ b/docs/configuration/profiles/tfm_profile_large.rst
@@ -2,10 +2,6 @@
Trusted Firmware-M Profile Large Design
#######################################
-:Author: David Hu
-:Organization: Arm Limited
-:Contact: david.hu@arm.com
-
************
Introduction
************
@@ -62,7 +58,6 @@
- Asymmetric key algorithm based Initial Attestation
- Secure boot
-
- Anti-rollback protection
- Multiple image boot
@@ -427,9 +422,9 @@
Reference
*********
-.. [1] :doc:`Trusted Firmware-M Profile Small Design </technical_references/design_docs/profiles/tfm_profile_small>`
+.. [1] :doc:`Trusted Firmware-M Profile Small Design </configuration/profiles/tfm_profile_small>`
-.. [2] :doc:`Trusted Firmware-M Profile Medium Design </technical_references/design_docs/profiles/tfm_profile_medium>`
+.. [2] :doc:`Trusted Firmware-M Profile Medium Design </configuration/profiles/tfm_profile_medium>`
.. [3] `PSA Certified Level 3 Lightweight Protection Profile <https://www.psacertified.org/app/uploads/2020/12/JSADEN009-PSA_Certified_Level_3_LW_PP-1.0-BET02.pdf>`_
diff --git a/docs/technical_references/design_docs/profiles/tfm_profile_medium.rst b/docs/configuration/profiles/tfm_profile_medium.rst
similarity index 98%
rename from docs/technical_references/design_docs/profiles/tfm_profile_medium.rst
rename to docs/configuration/profiles/tfm_profile_medium.rst
index f43e631..9f98542 100644
--- a/docs/technical_references/design_docs/profiles/tfm_profile_medium.rst
+++ b/docs/configuration/profiles/tfm_profile_medium.rst
@@ -2,10 +2,6 @@
Trusted Firmware-M Profile Medium Design
########################################
-:Author: David Hu
-:Organization: Arm Limited
-:Contact: david.hu@arm.com
-
************
Introduction
************
@@ -463,7 +459,7 @@
.. [RFC7925] `Transport Layer Security (TLS) / Datagram Transport Layer Security (DTLS) Profiles for the Internet of Things <https://tools.ietf.org/html/rfc7925>`_
-.. [PROFILE-S] :doc:`Trusted Firmware-M Profile Small Design </technical_references/design_docs/profiles/tfm_profile_small>`
+.. [PROFILE-S] :doc:`Trusted Firmware-M Profile Small Design </configuration/profiles/tfm_profile_small>`
.. [RFC7252] `The Constrained Application Protocol (CoAP) <https://tools.ietf.org/html/rfc7252>`_
diff --git a/docs/technical_references/design_docs/profiles/tfm_profile_medium_arot-less.rst b/docs/configuration/profiles/tfm_profile_medium_arot-less.rst
similarity index 98%
rename from docs/technical_references/design_docs/profiles/tfm_profile_medium_arot-less.rst
rename to docs/configuration/profiles/tfm_profile_medium_arot-less.rst
index 833dc07..cfb5744 100755
--- a/docs/technical_references/design_docs/profiles/tfm_profile_medium_arot-less.rst
+++ b/docs/configuration/profiles/tfm_profile_medium_arot-less.rst
@@ -227,7 +227,7 @@
.. [1] `SESIP Profile for PSA Certified ARoT-less Level 2 <https://www.psacertified.org/app/uploads/2022/10/JSADEN019-PSA_Certified_Level_2_PP_SESIP_ARoT-less_REL-01.pdf>`_
-.. [2] :doc:`Trusted Firmware-M Profile Medium Design </technical_references/design_docs/profiles/tfm_profile_medium>`
+.. [2] :doc:`Trusted Firmware-M Profile Medium Design </configuration/profiles/tfm_profile_medium>`
.. [3] `SESIP Profile for PSA Certified Level 2 <https://www.psacertified.org/app/uploads/2021/03/JSADEN012-PSA_Certified_Level_2_PP_SESIP-BETA02.pdf>`_
diff --git a/docs/technical_references/design_docs/profiles/tfm_profile_small.rst b/docs/configuration/profiles/tfm_profile_small.rst
similarity index 99%
rename from docs/technical_references/design_docs/profiles/tfm_profile_small.rst
rename to docs/configuration/profiles/tfm_profile_small.rst
index 045f7d1..41dab92 100644
--- a/docs/technical_references/design_docs/profiles/tfm_profile_small.rst
+++ b/docs/configuration/profiles/tfm_profile_small.rst
@@ -2,10 +2,6 @@
Trusted Firmware-M Profile Small Design
#######################################
-:Author: David Hu
-:Organization: Arm Limited
-:Contact: david.hu@arm.com
-
************
Introduction
************
diff --git a/docs/index.rst b/docs/index.rst
index a4ee9c9..f03abac 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -87,6 +87,7 @@
Platform Selection<platform/index>
building/tfm_build_instruction
+ configuration/index
integration_guide/index
technical_references/design_docs/index
Tools <tools/index>
diff --git a/docs/releases/1.3.0.rst b/docs/releases/1.3.0.rst
index b01bba0..06f8185 100644
--- a/docs/releases/1.3.0.rst
+++ b/docs/releases/1.3.0.rst
@@ -164,7 +164,7 @@
.. [4] :doc:`TF-M physical attack mitigation </technical_references/design_docs/tfm_physical_attack_mitigation>`
- .. [5] :doc:`TF-M Profile Large design </technical_references/design_docs/profiles/tfm_profile_large>`
+ .. [5] :doc:`TF-M Profile Large design </configuration/profiles/tfm_profile_large>`
.. [6] :doc:`Code sharing between independently linked XIP binaries </technical_references/design_docs/code_sharing>`
diff --git a/docs/technical_references/design_docs/profiles/index.rst b/docs/technical_references/design_docs/profiles/index.rst
deleted file mode 100644
index 928fc8b..0000000
--- a/docs/technical_references/design_docs/profiles/index.rst
+++ /dev/null
@@ -1,34 +0,0 @@
-TF-M Profiles
-=============
-
-The capabilities and resources may dramatically vary on different IoT devices.
-Some IoT devices may have very limited memory resource. The program on those devices should keep
-small memory footprint and basic functionalities.
-On the other hand, some devices may consist of more memory and extended storage, to support stronger
-software capabilities.
-
-Diverse IoT use cases also require different levels of security and requirements on device resource.
-For example, use cases require different cipher capabilities. Selecting cipher suites can be
-sensitive to memory footprint on devices with constrained resource.
-
-Trusted Firmware-M (TF-M) defines several general profiles, such as Profile Small, Profile Medium,
-Profile Medium ARoT-less and Profile Large, to provide different levels of security to fit diverse
-device capabilities and use cases.
-Each profile specifies a predefined list of features, targeting typical use cases with specific
-hardware constraints. Profiles can serve as reference designs, based on which developers can
-continue further development and configurations, according to use case.
-
-TF-M Profiles align with Platform Security Architecture specifications and certification
-guidelines. It can help vendors to simplify security configuring for PSA certification.
-
-TF-M Profiles details are discussed in the links below.
-
-.. toctree::
- :maxdepth: 1
- :glob:
-
- *
-
---------------
-
-*Copyright (c) 2020, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/design_docs/symmetric_initial_attest.rst b/docs/technical_references/design_docs/symmetric_initial_attest.rst
index 193bad9..02b23cd 100644
--- a/docs/technical_references/design_docs/symmetric_initial_attest.rst
+++ b/docs/technical_references/design_docs/symmetric_initial_attest.rst
@@ -551,7 +551,7 @@
.. [1] `PSA Attestation API 1.0 (ARM IHI 0085) <https://developer.arm.com/-/media/Files/pdf/PlatformSecurityArchitecture/Implement/IHI0085-PSA_Attestation_API-1.0.2.pdf?revision=eef78753-c77e-4b24-bcf0-65596213b4c1&la=en&hash=E5E0353D612077AFDCE3F2F3708A50C77A74B2A3>`_
-.. [2] :doc:`Trusted Firmware-M Profile Small Design </technical_references/design_docs/profiles/tfm_profile_small>`
+.. [2] :doc:`Trusted Firmware-M Profile Small Design </configuration/profiles/tfm_profile_small>`
.. [3] :doc:`Initial Attestation Service Integration Guide </integration_guide/services/tfm_attestation_integration_guide>`