Doc: Minor documentation fixes
This patch introduces a set of minor bug-fixes,
aimed at increasing the quality of the rendered
documentation
It also adds a new feature of exposing cmake
variables to the documentation.
* Exposed @SPHINXCFG_TFM_VERSION@ to .rst documents
as |TFM_VERSION|
* Upgraded tfm_its_512_flash document to comply with
the documentation guidelines
* Fixed a typo in tfm_build_instruction document
* Reworded the cryptocell-312-runtime readme file with
valid links to the user-manual
* Added psoc64/security/keys/readme.rst to excluded
document-list
* Fixed an external link referencing on readme.rst
Change-Id: Ic6406fb9b59ff25f964506675a24334beeaaa738
Signed-off-by: Galanakis, Minos <minos.galanakis@arm.com>
diff --git a/docs/conf.py.in b/docs/conf.py.in
index 4c5a740..39b2e1c 100644
--- a/docs/conf.py.in
+++ b/docs/conf.py.in
@@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
#-------------------------------------------------------------------------------
-# Copyright (c) 2019, Arm Limited. All rights reserved.
+# Copyright (c) 2019-2020, Arm Limited. All rights reserved.
#
# SPDX-License-Identifier: BSD-3-Clause
#
@@ -81,7 +81,8 @@
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'readme.rst']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'readme.rst',
+ 'platform/ext/target/cypress/psoc64/security/keys/readme.rst']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
@@ -130,6 +131,9 @@
# Output file base name for HTML help builder.
htmlhelp_basename = 'TF-M doc'
+rst_prolog = """
+.. |TFM_VERSION| replace:: @SPHINXCFG_TFM_VERSION@
+"""
# -- Options for LaTeX output ------------------------------------------------
diff --git a/docs/design_documents/tfm_its_512_flash.rst b/docs/design_documents/tfm_its_512_flash.rst
index 768ec59..6ce144d 100644
--- a/docs/design_documents/tfm_its_512_flash.rst
+++ b/docs/design_documents/tfm_its_512_flash.rst
@@ -1,6 +1,6 @@
-===============================================================
+###############################################################
Add support for block-aligned flash in Internal Trusted Storage
-===============================================================
+###############################################################
:Author: Minos Galanakis
:Organization: Arm Limited
@@ -38,31 +38,31 @@
================================
1. A new block-sized static buffer should be added to its_flash.c when
-``ITS_FLASH_PROGRAM_UNIT`` is larger than currently supported.
+ ``ITS_FLASH_PROGRAM_UNIT`` is larger than currently supported.
2. Methods calling the flash API such as ``its_flash_write()`` or
-``its_flash_block_to_block_move()`` will populate the buffer instead of
-directly programming the flash.
+ ``its_flash_block_to_block_move()`` will populate the buffer instead of
+ directly programming the flash.
3. A new method ``its_flash_flush()``, should be provided in order to flush
-the block buffer to the device.
-4. ``its_flash_flush()`` should be called twice: Once after a data block update
-and once more after the metadata block update is completed.
-4. The proposed design should require that the data block update is
-always completed before the metadata block update starts
-5. Writes to the block buffer should be atomic, and guarded against corruption
-by data from different blocks.
+ the block buffer to the device.
+4. ``its_flash_flush()`` should be called twice: Once after a data block
+ update and once more after the metadata block update is completed.
+5. The proposed design should require that the data block update is always
+ completed before the metadata block update starts
+6. Writes to the block buffer should be atomic, and guarded against corruption
+ by data from different blocks.
Considerations
==============
- The proposed implementation will increase the RAM usage of ITS by the size
-of a block, only for platforms which require block-aligned writes.
+ of a block, only for platforms which require block-aligned writes.
- Currently power-failure is detected by software by incrementing an 8-bit
-metadata header field (``swap_count``), as the last written byte. When the
-proposed block-buffer is used, the block is programmed in one-shot and the
-order the bytes are written on the physical device, is hardware dependent.
+ metadata header field (``swap_count``), as the last written byte. When the
+ proposed block-buffer is used, the block is programmed in one-shot and the
+ order the bytes are written on the physical device, is hardware dependent.
- A set of guarantees are required by the supported flash ECC devices.
-The device's flash APIs should provide a mechanism to capture and raise
-incomplete program operations, as well as write bytes in a sequential order.
+ The device's flash APIs should provide a mechanism to capture and raise
+ incomplete program operations, as well as write bytes in a sequential order.
For example, if a board powers down through a 512 page program operation, the
next read operation should return an error rather than read invalid data.
@@ -72,6 +72,8 @@
The logic of the proposal is described in the following diagram
+.. code-block::
+
|----------------------|
| data write() |
|----------------------|
@@ -97,7 +99,6 @@
| Operation Complete |
|--------------------------|
-
--------------
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
diff --git a/docs/user_guides/tfm_build_instruction.rst b/docs/user_guides/tfm_build_instruction.rst
index b7ab2c0..7257ec7 100644
--- a/docs/user_guides/tfm_build_instruction.rst
+++ b/docs/user_guides/tfm_build_instruction.rst
@@ -214,7 +214,7 @@
``-DTARGET_PLATFORM=AN524``
- Cypress CYS0644ABZI-S2D44 board (PSoC64 platform)
``-DTARGET_PLATFORM=psoc64``
- See :doc:`Cypress PSoC 64 platform specifics </platform/ext/target/cypress/psoc64/cypress_psoc_64_spec>`
+ See :doc:`Cypress PSoC 64 platform specifics </platform/ext/target/cypress/psoc64/cypress_psoc64_spec>`
- DesignStart FPGA on Cloud: Cortex-M33 based platform (SSE-200_AWS platform)
``-DTARGET_PLATFORM=SSE-200_AWS``
@@ -250,4 +250,4 @@
--------------
-*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*
+*Copyright (c) 2017-2020, Arm Limited. All rights reserved.*