ADAC: Docs: Update RSE implementation doc
* Update RSE specific implementation for ADAC
* Moved ADAC integration guide to tf-m repo since it reflects generic
use case and mapping of various ADAC components to repositories.
Signed-off-by: Maulik Patel <maulik.patel@arm.com>
Change-Id: Ie7573c5772553bdc5f1f980376eaab8e063ade5e
diff --git a/docs/partitions/adac/adac_integration_guide.rst b/docs/partitions/adac/adac_integration_guide.rst
deleted file mode 100644
index c1cb3e7..0000000
--- a/docs/partitions/adac/adac_integration_guide.rst
+++ /dev/null
@@ -1,163 +0,0 @@
-#########################################
-ADAC (Authenticated Debug Access Control)
-#########################################
-
-.. toctree::
- :maxdepth: 1
-
- ADAC Implementation for RSE <adac_impl_for_rse>
-
-************
-Introduction
-************
-
-Background
-==========
-In order to make sure debug capabilities of any system do not become attack
-vectors, PSA provides reference ADAC system architecture. It specifies
-functional layers that reside above actual physical link.
-
-Authenticated Debug Access Control (ADAC), also referred to as Secure Debug, is
-a protocol that provides a way to use strong authentication to restrict device
-debug access to only authorized entities. Across various life cycle states of
-target device, it permits appropriate access to finely configured domains.
-
-Requirements
-============
-Debug capabilities must achieve several safety goals to be fully resilient.
-It requires
-
-1. Strong authentication
-2. Finely grained hardware and firmware domains
-3. Enforcing debug limitations
-
-ADAC protocol is fully flexible to meet the above goals. But depending on the
-system design and topology, it must be implemented so to meet varying attack
-surface.
-
-ADAC runtime services fulfills requirement #1 mentioned above and authenticates
-incoming debug request by calling ADAC core protocol Secure debug manager API.
-
-Secure debug policy
-===================
-
-Depending on hardware and system topology and security requirements, each
-platform may have its own custom policy. It includes (but is not limited to)
-
-1. Classification of various debug zones
-2. Determination of appropriate debug permissions for each zone
-3. Appropriate life cycle states where debug request should be acknowledged
-4. Whether a new power cycle session is required to initiate and close a specific
- session
-
-Implementation of policies (#1 and #2) is outside of scope of runtime ADAC
-service and must be implemented and integrated into suitable layer of firmware.
-However, depending on platform specific implementation, ADAC runtime service may
-check for appropriate current device life cycle state. It may also request a
-system reset to initiate and close a debug session.
-
-************************************
-Code structure & Service Integration
-************************************
-
-The ADAC Service source and header files are located in the current directory.
-The interface for the ADAC runtime Service is located in ``interface/include``.
-The only header to be included by applications that want to use functions from
-the PSA API is ``tfm_adac_api.h``.
-
-Service interface
-=================
-The ADAC Service exposes the following interface:
-
-.. code-block:: c
-
- /*!
- * \brief Authenticates the requested debug service.
- *
- * \param[in] debug_request Request identifier for the debug zone
- * (valid values vary based on the platform
- * Each bit of the \p debug_request represents
- * debug request for corresponding zone.
- * e.g.
- * If no bits are set => no debug request
- * If bit0 is set => start debug for zone1
- * If bit0 is cleared => end debug for zone1
- * If bit1 is set => start debug for zone2
- * If bit1 is cleared => end debug for zone2
- * ...
- *
- * Enumeration of zones (zone1, zone2, etc.) is
- * done by ``tfm_debug_zones`` (platform specific)
- *
- * \return Returns PSA_SUCCESS on success,
- * otherwise error as specified in \ref psa_status_t
- */
- psa_status_t tfm_adac_service(uint32_t debug_request)
-
-Service source files
-====================
-- ``tfm_adac_api.c``: Implements the secure API layer to allow
- other services in the secure domain to request functionalities
- from the adac service using the PSA API interface.
-
-- ``adac_req_mngr.c``: Includes the initialization entry of
- adac service and handles adac service requests in IPC model.
-
-- ``adac.c``: Implements core functionalities such as implementation
- of APIs, handling and processing of debug request.
-
-Hardware abstraction layer
-==========================
-As mentioned above, classification of various debug zones is output of
-platform/system specific debug policy formulation.
-
-Below additional HAL interface MAY be required depending on platform policy.
-
-- ``tfm_debug_zones``: enumerates various debug zones.
-
-- ``tfm_platform_system_reset()``: Request system reset to initiate or terminate
- a debug session.
-
-- ``tfm_plat_otp_read()``: Reads the life cycle state as well as secure debug
- key required for authentication.
-
-Bootloader Interface
-====================
-The ADAC runtime service requires to convey debug state information between
-runtime service and bootloader. Implementation of this functionality is
-dependant on platform hardware.
-
-ADAC Protocol (SDA) integration
-===============================
-ADAC protocol which implements the Secure Debug Authenticator (SDA) component
-is source in external github repository.
-
- ``git@github.com:ARMmbed/psa-adac.git``.
-
-The API to initiate the connection with host debugger and to perform
-authentication process is platform specific. It requires secure debug keys as
-input for authentication.
-
-For example for RSE platform, the API to integrate is:
-
-- ``tfm_to_psa_adac_rse_secure_debug()``
-
-Please follow the below link for further information on SDA implementation.
-
-| `psa-adac read me`_
-
-.. _psa-adac read me:
- https://developer.arm.com/documentation/den0101/latest
-
-*********
-Reference
-*********
-
-| `ADAC specification`_
-
-.. _ADAC specification:
- https://developer.arm.com/documentation/den0101/latest
-
---------------
-
-*Copyright (c) 2022-2023, Arm Limited. All rights reserved.*
diff --git a/docs/partitions/adac/index.rst b/docs/partitions/adac/index.rst
deleted file mode 100644
index 0597756..0000000
--- a/docs/partitions/adac/index.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-#########################################
-Authenticated Debug Access Control (ADAC)
-#########################################
-
-.. toctree::
- :maxdepth: 1
-
- ADAC Integration guide <adac_integration_guide>
- ADAC Implementation for RSE <adac_impl_for_rse>
-
-*Copyright (c) 2024, Arm Limited. All rights reserved.*
diff --git a/docs/partitions/adac/adac_impl_for_rse.rst b/docs/partitions/adac_impl_for_rse.rst
similarity index 70%
rename from docs/partitions/adac/adac_impl_for_rse.rst
rename to docs/partitions/adac_impl_for_rse.rst
index fdb1e44..4bd6e8d 100644
--- a/docs/partitions/adac/adac_impl_for_rse.rst
+++ b/docs/partitions/adac_impl_for_rse.rst
@@ -73,6 +73,56 @@
reset, ADAC service does not initiate any reset and enables the debug
immediately.
+************************************
+Code structure & Service Integration
+************************************
+
+The ADAC Service source and header files are located in the current directory.
+The interface for the ADAC runtime Service is located in ``interface/include``.
+The only header to be included by applications that want to use functions from
+the PSA API is ``tfm_adac_api.h``.
+
+Service interface
+=================
+The ADAC Service exposes the following interface:
+
+.. code-block:: c
+
+ /*!
+ * \brief Authenticates the requested debug service.
+ *
+ * \param[in] debug_request Request identifier for the debug zone
+ * (valid values vary based on the platform
+ * Each bit of the \p debug_request represents
+ * debug request for corresponding zone.
+ * e.g.
+ * If no bits are set => no debug request
+ * If bit0 is set => start debug for zone1
+ * If bit0 is cleared => end debug for zone1
+ * If bit1 is set => start debug for zone2
+ * If bit1 is cleared => end debug for zone2
+ * ...
+ *
+ * Enumeration of zones (zone1, zone2, etc.) is
+ * done by ``tfm_debug_zones`` (platform specific)
+ *
+ * \return Returns PSA_SUCCESS on success,
+ * otherwise error as specified in \ref psa_status_t
+ */
+ psa_status_t tfm_adac_service(uint32_t debug_request)
+
+Service source files
+====================
+- ``tfm_adac_api.c``: Implements the secure API layer to allow
+ other services in the secure domain to request functionalities
+ from the adac service using the PSA API interface.
+
+- ``adac_req_mngr.c``: Includes the initialization entry of
+ adac service and handles adac service requests in IPC model.
+
+- ``adac.c``: Implements core functionalities such as implementation
+ of APIs, handling and processing of debug request.
+
Hardware abstraction layer Interface
====================================
@@ -122,4 +172,4 @@
--------------
-*Copyright (c) 2023, Arm Limited. All rights reserved.*
+*Copyright (c) 2023-2024, Arm Limited. All rights reserved.*
diff --git a/docs/partitions/index.rst b/docs/partitions/index.rst
index 6eab7e9..87e658e 100644
--- a/docs/partitions/index.rst
+++ b/docs/partitions/index.rst
@@ -5,7 +5,7 @@
:maxdepth: 2
:titlesonly:
- Authenticated Debug Access Control (ADAC) <adac/index>
+ Authenticated Debug Access Control (ADAC) <adac_impl_for_rse>
Delegated Attestation <delegated_attestation/delegated_attest_integration_guide>
DICE Protection Environmnet <dice_protection_environment/dice_protection_environment>
DMA-350 ARoT <dma350_unpriv_partition/dma350_unpriv_partition>