Docs: Fix some document build warnings
Fix some duplicated labels warnings and code block language warnings.
Change-Id: Ic25be83273fb8eac3a3ff4c2b98182ff268cb3dd
Signed-off-by: David Hu <david.hu@arm.com>
diff --git a/docs/technical_references/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst b/docs/technical_references/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst
index 2bb3762..1ab1413 100644
--- a/docs/technical_references/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst
+++ b/docs/technical_references/dual-cpu/communication_prototype_between_nspe_and_spe_in_dual_core_systems.rst
@@ -424,8 +424,7 @@
void tfm_rpc_client_call_handler(void);
-Usage
-~~~~~
+**Usage**
``tfm_rpc_client_call_handler()`` invokes callback function ``handle_req()`` to
execute specific mailbox handling.
@@ -442,8 +441,7 @@
void tfm_rpc_client_call_reply(const void *owner, int32_t ret);
-Parameters
-~~~~~~~~~~
+**Parameters**
+-----------+--------------------------------------------------------------+
| ``owner`` | A handle to identify the owner of the PSA client call return |
@@ -452,8 +450,7 @@
| ``ret`` | PSA client call return result value. |
+-----------+--------------------------------------------------------------+
-Usage
-~~~~~
+**Usage**
``tfm_rpc_client_call_reply()`` invokes callback function ``reply()`` to execute
specific mailbox reply.
@@ -470,8 +467,7 @@
void tfm_rpc_set_caller_data(struct tfm_msg_body_t *msg, int32_t client_id);
-Parameters
-~~~~~~~~~~
+**Parameters**
+---------------+-----------------------------------------------------+
| ``msg`` | TF-M message to be set with NS caller private data. |
@@ -479,8 +475,7 @@
| ``client_id`` | The client ID of the NS caller. |
+---------------+-----------------------------------------------------+
-Usage
-~~~~~
+**Usage**
``tfm_rpc_set_caller_data()`` invokes callback function ``get_caller_data()`` to
fetch the private data of caller of PSA client call and set it into TF-M message
@@ -530,15 +525,13 @@
int32_t tfm_rpc_register_ops(const struct tfm_rpc_ops_t *ops_ptr);
-Parameters
-~~~~~~~~~~
+**Parameters**
+-------------+----------------------------------------------+
| ``ops_ptr`` | Pointer to the specific operation structure. |
+-------------+----------------------------------------------+
-Return
-~~~~~~
+**Return**
+----------------------+-----------------------------------------+
| ``TFM_RPC_SUCCESS`` | Operations are successfully registered. |
@@ -546,8 +539,7 @@
| ``Other error code`` | Fail to register operations. |
+----------------------+-----------------------------------------+
-Usage
-~~~~~
+**Usage**
Mailbox should register TF-M RPC callbacks during mailbox initialization, before
enabling secure services for NSPE.
@@ -564,8 +556,7 @@
void tfm_rpc_unregister_ops(void);
-Usage
-~~~~~
+**Usage**
Currently one and only one underlying mailbox communication implementation is
allowed in runtime.
@@ -579,16 +570,14 @@
uint32_t tfm_rpc_psa_framework_version(void);
-Return
-~~~~~~
+**Return**
+-------------+---------------------------------------------------------+
| ``version`` | The version of the PSA Framework implementation that is |
| | providing the runtime services. |
+-------------+---------------------------------------------------------+
-Usage
-~~~~~
+**Usage**
``tfm_rpc_psa_framework_version()`` invokes common ``psa_framework_version()``
handler in TF-M.
@@ -603,8 +592,7 @@
uint32_t tfm_rpc_psa_version(const struct client_call_params_t *params,
bool ns_caller);
-Parameters
-~~~~~~~~~~
+**Parameters**
+---------------+-----------------------------------+
| ``params`` | Base address of parameters. |
@@ -612,8 +600,7 @@
| ``ns_caller`` | Whether the caller is non-secure. |
+---------------+-----------------------------------+
-Return
-~~~~~~
+**Return**
+----------------------+------------------------------------------------------+
| ``PSA_VERSION_NONE`` | The RoT Service is not implemented, or the caller is |
@@ -622,8 +609,7 @@
| ``> 0`` | The minor version of the implemented RoT Service. |
+----------------------+------------------------------------------------------+
-Usage
-~~~~~
+**Usage**
``tfm_rpc_psa_version()`` invokes common ``psa_version()`` handler in TF-M.
The parameters in params should be prepared before calling
@@ -639,8 +625,7 @@
psa_status_t tfm_rpc_psa_connect(const struct client_call_params_t *params,
bool ns_caller);
-Parameters
-~~~~~~~~~~
+**Parameters**
+---------------+-----------------------------------+
| ``params`` | Base address of parameters. |
@@ -648,8 +633,7 @@
| ``ns_caller`` | Whether the caller is non-secure. |
+---------------+-----------------------------------+
-Return
-~~~~~~
+**Return**
+-------------------------+---------------------------------------------------+
| ``PSA_SUCCESS`` | Success. |
@@ -661,8 +645,7 @@
| | service. |
+-------------------------+---------------------------------------------------+
-Usage
-~~~~~
+**Usage**
``tfm_rpc_psa_connect()`` invokes common ``psa_connect()`` handler in TF-M.
The parameters in params should be prepared before calling
@@ -678,8 +661,7 @@
psa_status_t tfm_rpc_psa_call(const struct client_call_params_t *params,
bool ns_caller);
-Parameters
-~~~~~~~~~~
+**Parameters**
+---------------+-----------------------------------+
| ``params`` | Base address of parameters. |
@@ -687,8 +669,7 @@
| ``ns_caller`` | Whether the caller is non-secure. |
+---------------+-----------------------------------+
-Return
-~~~~~~
+**Return**
+---------------------+---------------------------------------------+
| ``PSA_SUCCESS`` | Success. |
@@ -696,8 +677,7 @@
| ``Does not return`` | The call is invalid, or invalid parameters. |
+---------------------+---------------------------------------------+
-Usage
-~~~~~
+**Usage**
``tfm_rpc_psa_call()`` invokes common ``psa_call()`` handler in TF-M.
The parameters in params should be prepared before calling
@@ -713,8 +693,7 @@
void tfm_rpc_psa_close(const struct client_call_params_t *params,
bool ns_caller);
-Parameters
-~~~~~~~~~~
+**Parameters**
+---------------+-----------------------------------+
| ``params`` | Base address of parameters. |
@@ -722,8 +701,7 @@
| ``ns_caller`` | Whether the caller is non-secure. |
+---------------+-----------------------------------+
-Return
-~~~~~~
+**Return**
+---------------------+---------------------------------------------+
| ``void`` | Success. |
@@ -731,8 +709,7 @@
| ``Does not return`` | The call is invalid, or invalid parameters. |
+---------------------+---------------------------------------------+
-Usage
-~~~~~
+**Usage**
``tfm_rpc_psa_close()`` invokes common ``psa_close()`` handler in TF-M.
The parameters in params should be prepared before calling
diff --git a/docs/technical_references/tfm_code_generation_with_jinja2.rst b/docs/technical_references/tfm_code_generation_with_jinja2.rst
index 2e73023..f16fc29 100644
--- a/docs/technical_references/tfm_code_generation_with_jinja2.rst
+++ b/docs/technical_references/tfm_code_generation_with_jinja2.rst
@@ -64,7 +64,7 @@
Below code snippet enumerates services in Secure Partitions:
-.. code-block::
+.. code-block:: jinja
{% for partition in partitions %}
{% if partition.manifest.services %}
@@ -74,4 +74,6 @@
{% endif %}
{% endfor %}
+--------------
+
*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_fwu_service.rst b/docs/technical_references/tfm_fwu_service.rst
index 6d90de4..8577841 100644
--- a/docs/technical_references/tfm_fwu_service.rst
+++ b/docs/technical_references/tfm_fwu_service.rst
@@ -66,7 +66,7 @@
***********************
Service API description
***********************
-This service follows the `Firmware Update API <https://developer.arm.com/documentation/ihi0093/0000/>`_ spec of version 0.7.
+This service follows the PSA Firmware Update API spec of version 0.7 [1]_.
It implements the mandatory interface functions listed in section 5.1 and the
optional interface ``psa_fwu_accept()``. Please refer to Firmware Update spec
for the detailed description.
@@ -108,26 +108,25 @@
fwu_bootloader_staging_area_init(function)
------------------------------------------
-Prototype
-^^^^^^^^^
+**Prototype**
+
.. code-block:: c
psa_status_t fwu_bootloader_staging_area_init(bl_image_id_t bootloader_image_id);
-Description
-^^^^^^^^^^^
+**Description**
+
Prepare the staging area of the image with the given ID for image download.
For example, initialize the staging area, open the flash area, and so on.
The image will be written into the staging area later.
-Parameters
-^^^^^^^^^^
+**Parameters**
+
- ``bootloader_image_id``: The identifier of the target image in bootloader.
fwu_bootloader_load_image(function)
-----------------------------------
-Prototype
-^^^^^^^^^
+**Prototype**
.. code-block:: c
@@ -136,12 +135,12 @@
const void *block,
size_t block_size);
-Description
-^^^^^^^^^^^
+**Description**
+
Load the image to its staging area.
-Parameters
-^^^^^^^^^^
+**Parameters**
+
- ``bootloader_image_id``: The identifier of the target image in bootloader.
- ``image_offset``: The offset of the image being passed into block, in bytes.
- ``block``: A buffer containing a block of image data. This might be a complete image or a subset.
@@ -149,78 +148,78 @@
fwu_bootloader_install_image(function)
---------------------------------------------
-Prototype
-^^^^^^^^^
+**Prototype**
+
.. code-block:: c
psa_status_t fwu_bootloader_install_image(bl_image_id_t bootloader_image_id,
bl_image_id_t *dependency,
psa_image_version_t *dependency_version);
-Description
-^^^^^^^^^^^
+**Description**
+
Check the authenticity and integrity of the image. If a reboot is required to
complete the check, then mark this image as a candidate so that the next time
bootloader runs it will take this image as a candidate one to bootup. Return
the error code PSA_SUCCESS_REBOOT.
-Parameters
-^^^^^^^^^^
+**Parameters**
+
- ``bootloader_image_id``: The identifier of the target image in bootloader.
- ``dependency``: Bootloader image ID of dependency if needed.
- ``dependency_version``: Bootloader image version of dependency if needed.
fwu_bootloader_mark_image_accepted(function)
--------------------------------------------
-Prototype
-^^^^^^^^^
+**Prototype**
+
.. code-block:: c
psa_status_t fwu_bootloader_mark_image_accepted(void);
-Description
-^^^^^^^^^^^
+**Description**
+
Call this API to mark the running images as permanent/accepted to avoid
revert when next time bootup. Usually, this API is called after the running
images have been verified as valid.
-Parameters
-^^^^^^^^^^
+**Parameters**
+
N/A
fwu_bootloader_abort(function)
------------------------------
-Prototype
-^^^^^^^^^
+**Prototype**
+
.. code-block:: c
psa_status_t fwu_bootloader_abort(void);
-Description
-^^^^^^^^^^^
+**Description**
+
Abort the current image download process.
-Parameters
-^^^^^^^^^^
+**Parameters**
+
N/A
fwu_bootloader_get_image_info(function)
---------------------------------------
-Prototype
-^^^^^^^^^
+**Prototype**
+
.. code-block:: c
psa_status_t fwu_bootloader_get_image_info(bl_image_id_t bootloader_image_id,
bool staging_area,
tfm_image_info_t *info);
-Description
-^^^^^^^^^^^
+**Description**
+
Get the image information of the given bootloader_image_id in the staging area
or the running area.
-Parameters
-^^^^^^^^^^
+**Parameters**
+
- ``bootloader_image_id``: The identifier of the target image in bootloader.
- ``active_image``: Indicates image location.
@@ -271,9 +270,9 @@
Implement the FWU functionality in the non-secure side
======================================================
-The Firmware Update APIs listed in `User interfaces`_ can also be implemented
-in the non-secure side. The library model implementation can be referred to for
-the non-secure side implementation.
+The APIs listed in PSA Firmware Update API spec [1]_ can also be implemented in
+the non-secure side. The library model implementation can be referred to for the
+non-secure side implementation.
Pros and Cons for Implementing FWU APIs in Secure Side
======================================================
@@ -310,4 +309,12 @@
the Firmware Update APIs in the non-secure side based on the pros and cons
analysis above.
+*********
+Reference
+*********
+
+.. [1] `PSA Firwmare Update API <https://developer.arm.com/documentation/ihi0093/0000/>`_
+
+--------------
+
*Copyright (c) 2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_its_512_flash.rst b/docs/technical_references/tfm_its_512_flash.rst
index aa58c2b..00f60f8 100644
--- a/docs/technical_references/tfm_its_512_flash.rst
+++ b/docs/technical_references/tfm_its_512_flash.rst
@@ -72,7 +72,7 @@
The logic of the proposal is described in the following diagram
-.. code-block::
+.. code-block:: rst
|----------------------|
| data write() |
diff --git a/docs/technical_references/tfm_non_secure_client_management.rst b/docs/technical_references/tfm_non_secure_client_management.rst
index 970550a..133ae92 100644
--- a/docs/technical_references/tfm_non_secure_client_management.rst
+++ b/docs/technical_references/tfm_non_secure_client_management.rst
@@ -83,15 +83,13 @@
TZ Memory ID identifies an allocated memory slot.
-TF-M usage
-""""""""""
+**TF-M usage**
``TZ_MemoryId_t`` is used for an index into an array containing active NS client
IDs. The memory ID is required by CMSIS to be a positive integer, so it is
mapped to the array index by being decremented by 1.
-Signature
-"""""""""
+**Signature**
.. code-block:: c
@@ -102,20 +100,17 @@
Initialize secure context memory system.
-Return value
-""""""""""""
+**Return value**
This function returns execution status: 1 for success, 0 for error.
-TF-M usage
-""""""""""
+**TF-M usage**
This function call is used to identify a non-secure RTOS that has TZ context
management capabilities, as this function is expected to be called before any
other TZ API function is used.
-Signature
-""""""""""
+**Signature**
.. code-block:: c
@@ -126,27 +121,23 @@
Allocate context memory for calling secure software modules in TrustZone.
-Parameters
-""""""""""
+**Parameters**
``module`` [input]: identifies software modules called from non-secure mode
-Return value
-""""""""""""
+**Return value**
``value != 0`` TrustZone memory slot identifier
``value == 0`` no memory available or internal error
-TF-M usage
-""""""""""
+**TF-M usage**
This function is used to identify a new non-secure thread that may be identified
as a client in the non-secure domain. The ``module`` parameter is unused. The
returned ``TZ_MemoryId_t`` value is the index in the ``NsClientIdList`` array
where the client ID for the newly allocated context is stored.
-Signature
-"""""""""
+**Signature**
.. code-block:: c
@@ -157,26 +148,22 @@
Free context memory that was previously allocated with TZ_AllocModuleContext_S
-Parameters
-""""""""""
+**Parameters**
``id`` [input]: TrustZone memory slot identifier
-Return value
-""""""""""""
+**Return value**
Execution status (1: success, 0: error)
-TF-M usage
-""""""""""
+**TF-M usage**
This function indicates that a non-secure client is inactive, meaning that any
subsequent references to the client ID are considered erroneous. In effect, the
client ID indexed by ``(id – 1)`` is cleared and the memory slot flagged as
free.
-Signature
-"""""""""
+**Signature**
.. code-block:: c
@@ -187,25 +174,21 @@
Load secure context (called on RTOS thread context switch)
-Parameters
-""""""""""
+**Parameters**
``id`` [input]: TrustZone memory slot identifier
-Return value
-""""""""""""
+**Return value**
Execution status (1: success, 0: error)
-TF-M usage
-""""""""""
+**TF-M usage**
The client ID indexed by ``(id – 1)`` becomes the active NS client. Any
subsequent secure service requests coming from non-secure domain will be
associated with this client ID.
-Signature
-"""""""""
+**Signature**
.. code-block:: c
@@ -216,25 +199,21 @@
Store secure context (called on RTOS thread context switch)
-Parameters
-""""""""""
+**Parameters**
``id`` [input]: TrustZone memory slot identifier
-Return value
-""""""""""""
+**Return value**
Execution status (1: success, 0: error)
-TF-M usage
-""""""""""
+**TF-M usage**
The client ID indexed by ``(id – 1)`` becomes inactive. Any subsequent secure
service requests coming from non-secure domain will be invalid until a new NS
context is loaded.
-Signature
-"""""""""
+**Signature**
.. code-block:: c
@@ -302,19 +281,16 @@
IDs for non-secure clients, positive for secure clients). The function call is
rejected if called with a secure ID.
-Parameters
-""""""""""
+**Parameters**
``ns_client_id`` [input]: The client ID to be assigned to the current context
-Return value
-""""""""""""
+**Return value**
``TFM_SUCCESS`` (0) if the client ID assigned successfully, a non-zero error
code in case of error.
-Signature
-"""""""""
+**Signature**
.. code-block:: c
@@ -385,4 +361,6 @@
Description of the TZ API:
https://www.keil.com/pack/doc/CMSIS/Core/html/group__context__trustzone__functions.html
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
\ No newline at end of file
+--------------
+
+*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_secure_irq_handling.rst b/docs/technical_references/tfm_secure_irq_handling.rst
index 8cd664e..469d044 100644
--- a/docs/technical_references/tfm_secure_irq_handling.rst
+++ b/docs/technical_references/tfm_secure_irq_handling.rst
@@ -153,7 +153,7 @@
interrupt of 'A' is triggered, and then this last handler is interrupted. At
this point the context stack looks like this:
-.. code-block::
+.. code-block:: rst
+------------+
| [intr_ctx] |
@@ -172,11 +172,10 @@
So the max stack size can be calculated as a function of the IRQ count of 'A':
-.. code-block::
-
+.. code-block:: c
max_stack_size = intr_ctx_size + (IRQ_CNT * (intr_ctx_size + hndl_ctx_size))
--------------
-*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2018-2021, Arm Limited. All rights reserved.*
diff --git a/docs/technical_references/tfm_secure_partition_interrupt_handling.rst b/docs/technical_references/tfm_secure_partition_interrupt_handling.rst
index 6d9a5e1..79dea0c 100644
--- a/docs/technical_references/tfm_secure_partition_interrupt_handling.rst
+++ b/docs/technical_references/tfm_secure_partition_interrupt_handling.rst
@@ -124,15 +124,13 @@
The only signals implemented in the current TF-M implementation are
interrupt signals.
-Signature
----------
+**Signature**
.. code-block:: c
psa_signal_t psa_wait(psa_signal_t signal_mask, uint32_t timeout);
-Parameters
-----------
+**Parameters**
``psa_signal_t signal_mask`` defines the set of interrupt signals that can
resume execution of the secure service.
@@ -140,8 +138,7 @@
``uint32_t timeout`` defines timeout for the function, as defined in PSA
Firmware Framework 1.0-beta-0 (Chapter 4.3.3).
-Return
-------
+**Return**
The return value indicates the signal(s) that triggered the resumption of the
service; i.e. If multiple interrupt events have been handled, it will be
@@ -152,20 +149,17 @@
A call to ``tfm_enable_irq()`` from a secure service enables an irq.
-Signature
----------
+**Signature**
.. code-block:: c
void tfm_enable_irq(psa_signal_t irq_signal);
-Parameters
-----------
+**Parameters**
``psa_signal_t irq_signal`` defines the interrupt signal to be enabled.
-Return
-------
+**Return**
``void`` Success.
@@ -179,19 +173,17 @@
A call to ``tfm_disable_irq()`` from a secure service disables an irq.
-Signature
----------
+**Signature**
.. code-block:: c
void tfm_disable_irq(psa_signal_t irq_signal);
-Parameters
-----------
+**Parameters**
+
``psa_signal_t irq_signal`` defines the interrupt signal to be disabled.
-Return
-------
+**Return**
``void``: Success.
@@ -207,21 +199,18 @@
informs SPM that an interrupt has been processed. This clears the IRQ signal in
the asserted signal mask associated with the partition.
-Signature
----------
+**Signature**
.. code-block:: c
void psa_eoi(psa_signal_t irq_signal);
-Parameters
-----------
+**Parameters**
``psa_signal_t irq_signal`` defines the interrupt signal that has been
processed.
-Return
-------
+**Return**
``void``: Success.
@@ -231,4 +220,6 @@
- ``irq_signal`` indicates more than one signal.
- ``irq_signal`` is not currently asserted.
+--------------
+
*Copyright (c) 2019-2021, Arm Limited. All rights reserved.*