Doc: convert markdown files to rst
The official documentation format for TF-M is becoming Restructured
Text. This change converts the existing .md files to the new format.
Due to support for documentation of external code (/lib) md support is
kept.
Change-Id: I3c1aef5d22442e0c7c362a40a8d344a266dc0940
Signed-off-by: Gyorgy Szing <Gyorgy.Szing@arm.com>
diff --git a/platform/ext/readme.md b/platform/ext/readme.md
deleted file mode 100644
index 5558e41..0000000
--- a/platform/ext/readme.md
+++ /dev/null
@@ -1,135 +0,0 @@
-# Details for the platform/ext folder
-
-This folder has code that has been imported from other projects. This means the
-files in this folder and subfolders have Apache 2.0 license which
-is different to BSD 3.0 license applied to the parent TF-M project.
-
-
-`NOTE` This folder is strictly Apache 2.0 with the exception of cmake files.
-Maintainers should be consulted if this needs to be revisited.
-
-## Sub-folders
-
-### cmsis
-
-This folder contains core and compiler specific header files imported from the
-CMSIS_5 project.
-
-### common
-
-This folder contains stdout redirection to UART, a temporary memory mapped
-flash implementation for the bootloader and tfm_mbedtls_config.h for all
-the targets.
-
-### drivers
-
-This folder contains the headers with CMSIS compliant driver definitions that
-that TF-M project expects a target to provide.
-
-#### target_cfg.h
-
-This file is expected to define the following macros respectively.
-
- - `TFM_DRIVER_STDIO`
- This macro should expand to a structure of type `ARM_DRIVER_USART`.
- TFM redirects its standard input and output to this instance of USART.
- - `NS_DRIVER_STDIO`
- This macro should expand to a structure of type `ARM_DRIVER_USART`.
- Non-Secure application redirects its standard input and output to this
- instance of USART.
-
-### target
-
-This folder contains the files for individual target.
-
-#### Flash layout header file
-
-Target must provide a header file, called flash_layout.h, which defines the
-information explained in the follow subsections. The defines must be named
-as they are in the subsections.
-
-##### BL2 bootloader
-
-The BL2 bootloader requires the following definitions:
-
- - `FLASH_BASE_ADDRESS`
- Defines the first valid address in the flash.
- - `FLASH_AREA_BL2_OFFSET`
- Defines the offset from the flash base address
- where the BL2 - MCUBOOT area starts.
- - `FLASH_AREA_BL2_SIZE`
- Defines the size of the BL2 area.
- - `FLASH_AREA_IMAGE_0_OFFSET`
- Defines the offset from the flash base address
- where the image 0 area starts, which hosts the
- active firmware image.
- - `FLASH_AREA_IMAGE_0_SIZE`
- Defines the size of the image 0 area.
- - `FLASH_AREA_IMAGE_1_OFFSET`
- Defines the offset from the flash base address
- where the image 1 area starts, which is a placeholder
- for new firmware images.
- - `FLASH_AREA_IMAGE_1_SIZE`
- Defines the size of the image 1 area.
- - `FLASH_AREA_IMAGE_SCRATCH_OFFSET`
- Defines the offset from the flash base address
- where the scratch area starts, which is used during
- image swapping.
- - `FLASH_AREA_IMAGE_SCRATCH_SIZE`
- Defines the size of the scratch area. The minimal size
- must be as the biggest sector size in the flash.
- - `FLASH_DEV_NAME`
- Specifies the flash device used by BL2.
-
-##### Assemble tool
-
-The assemble.py tools is used to concatenate secure and non-secure
-binary to a single binary blob. It requires the following definitions:
-
- - `SECURE_IMAGE_OFFSET`
- Defines the offset from the single binary blob base address,
- where the secure image starts.
- - `SECURE_IMAGE_MAX_SIZE`
- Defines the maximum size of the secure image area.
- - `NON_SECURE_IMAGE_OFFSET`
- Defines the offset from the single binary blob base address,
- where the non-secure image starts.
- - `NON_SECURE_IMAGE_MAX_SIZE`
- Defines the maximum size of the non-secure image area.
-
-##### Secure Storage (SST) Service definitions
-
-The SST service requires the following definitions:
-
- - `SST_FLASH_AREA_ADDR`
- Defines the flash area address where the secure
- store area starts.
- - `SST_SECTOR_SIZE`
- Defines the size of the flash sectors.
- - `SST_NBR_OF_SECTORS`
- Defines the number of sectors available for
- the secure area.
- - `SST_FLASH_DEV_NAME`
- Specifies the flash device used by SST to store the data.
- - `SST_FLASH_PROGRAM_UNIT`
- Defines the smallest flash programmable unit in bytes.
- - `SST_MAX_ASSET_SIZE`
- Defines the maximum asset size to be stored in the SST area.
- - `SST_NUM_ASSETS`
- Defines the maximum number of assets to be stored in the SST area.
-
-**Note**: The sectors must be consecutive.
-
-## Expose target support for HW components
-
-Services may require HW components to be supported by the target
-to enable some features (e.g. SST service with rollback protection, etc).
-The following definitions need to be set in the <TARGET_NAME>.cmake file if the
-target has the following HW components:
-
- - `TARGET_NV_COUNTERS_ENABLE`
- Specifies that the target has non-volatile (NV) counters.
-
---------------
-
-*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*
diff --git a/platform/ext/readme.rst b/platform/ext/readme.rst
new file mode 100644
index 0000000..2f93940
--- /dev/null
+++ b/platform/ext/readme.rst
@@ -0,0 +1,121 @@
+###################################
+Details for the platform/ext folder
+###################################
+This folder has code that has been imported from other projects. This means the
+files in this folder and subfolders have Apache 2.0 license which is different
+to BSD 3.0 license applied to the parent TF-M project.
+
+.. Note::
+ This folder is strictly Apache 2.0 with the exception of cmake files.
+ Maintainers should be consulted if this needs to be revisited.
+
+***********
+Sub-folders
+***********
+
+cmsis
+=====
+This folder contains core and compiler specific header files imported from the
+``CMSIS_5`` project.
+
+common
+======
+This folder contains stdout redirection to UART, a temporary memory mapped flash
+implementation for the bootloader and tfm\_mbedtls\_config.h for all the
+targets.
+
+drivers
+=======
+This folder contains the headers with CMSIS compliant driver definitions that
+that TF-M project expects a target to provide.
+
+target_cfg.h
+------------
+This file is expected to define the following macros respectively.
+
+- ``TFM_DRIVER_STDIO`` - This macro should expand to a structure of type
+ ``ARM_DRIVER_USART``. TFM redirects its standard input and output to this
+ instance of USART.
+- ``NS_DRIVER_STDIO`` - This macro should expand to a structure of type
+ ``ARM_DRIVER_USART``. Non-Secure application redirects its standard input and
+ output to this instance of USART.
+
+target
+======
+This folder contains the files for individual target.
+
+Flash layout header file
+------------------------
+Target must provide a header file, called ``flash_layout.h``, which defines the
+information explained in the follow subsections. The defines must be named
+as they are in the subsections.
+
+BL2 bootloader
+^^^^^^^^^^^^^^
+The BL2 bootloader requires the following definitions:
+
+- ``FLASH_BASE_ADDRESS`` - Defines the first valid address in the flash.
+- ``FLASH_AREA_BL2_OFFSET`` - Defines the offset from the flash base address
+ where the BL2 - MCUBOOT area starts.
+- ``FLASH_AREA_BL2_SIZE`` - Defines the size of the BL2 area.
+- ``FLASH_AREA_IMAGE_0_OFFSET`` - Defines the offset from the flash base address
+ where the image 0 area starts, which hosts the active firmware image.
+- ``FLASH_AREA_IMAGE_0_SIZE`` - Defines the size of the image 0 area.
+- ``FLASH_AREA_IMAGE_1_OFFSET`` - Defines the offset from the flash base address
+ where the image 1 area starts, which is a placeholder for new firmware images.
+- ``FLASH_AREA_IMAGE_1_SIZE`` - Defines the size of the image 1 area.
+- ``FLASH_AREA_IMAGE_SCRATCH_OFFSET`` - Defines the offset from the flash base
+ address where the scratch area starts, which is used during image swapping.
+- ``FLASH_AREA_IMAGE_SCRATCH_SIZE`` - Defines the size of the scratch area. The
+ minimal size must be as the biggest sector size in the flash.
+- ``FLASH_DEV_NAME`` - Specifies the flash device used by BL2.
+
+Assemble tool
+^^^^^^^^^^^^^
+The ``assemble.py`` tools is used to concatenate secure and non-secure binary
+to a single binary blob. It requires the following definitions:
+
+- ``SECURE_IMAGE_OFFSET`` - Defines the offset from the single binary blob base
+ address, where the secure image starts.
+- ``SECURE_IMAGE_MAX_SIZE`` - Defines the maximum size of the secure image area.
+- ``NON_SECURE_IMAGE_OFFSET`` - Defines the offset from the single binary blob
+ base address, where the non-secure image starts.
+- ``NON_SECURE_IMAGE_MAX_SIZE`` - Defines the maximum size of the non-secure
+ image area.
+
+Secure Storage (SST) Service definitions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The SST service requires the following definitions:
+
+- ``SST_FLASH_AREA_ADDR`` - Defines the flash area address where the secure
+ store area starts.
+- ``SST_SECTOR_SIZE`` - Defines the size of the flash sectors.
+- ``SST_NBR_OF_SECTORS`` - Defines the number of sectors available for the
+ secure area.
+- ``SST_FLASH_DEV_NAME`` - Specifies the flash device used by SST to store the
+ data.
+- ``SST_FLASH_PROGRAM_UNIT`` - Defines the smallest flash programmable unit in
+ bytes.
+- ``SST_MAX_ASSET_SIZE`` - Defines the maximum asset size to be stored in the
+ SST area.
+- ``SST_NUM_ASSETS`` - Defines the maximum number of assets to be stored in the
+ SST area.
+
+.. Note::
+
+ The sectors must be consecutive.
+
+***************************************
+Expose target support for HW components
+***************************************
+Services may require HW components to be supported by the target to enable some
+features (e.g. SST service with rollback protection, etc). The following
+definitions need to be set in the .cmake file if the target has the following
+HW components:
+
+- ``TARGET_NV_COUNTERS_ENABLE`` - Specifies that the target has non-volatile
+ (NV) counters.
+
+--------------
+
+*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*
diff --git a/platform/ext/target/musca_b1/readme.md b/platform/ext/target/musca_b1/readme.md
deleted file mode 100644
index 0894d5f..0000000
--- a/platform/ext/target/musca_b1/readme.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# DAPLink Firmware
-
-The code on Musca-B1 is running from embededed flash.
-Make sure that the DAPLink FW for eFlash is downloaded to the board.
-You can find it from Arm Community page:
-https://community.arm.com/developer/tools-software/oss-platforms/w/docs/425/musca-b1-firmware-update-qspi-boot-recovery
-A short description of how to update the DAPLink FW can be found there as well.
diff --git a/platform/ext/target/musca_b1/readme.rst b/platform/ext/target/musca_b1/readme.rst
new file mode 100644
index 0000000..159af55
--- /dev/null
+++ b/platform/ext/target/musca_b1/readme.rst
@@ -0,0 +1,15 @@
+###########################
+Musca-B1 Platform Specifics
+###########################
+
+****************
+DAPLink Firmware
+****************
+The code on Musca-B1 is running from embededed flash. Make sure that the DAPLink
+FW for eFlash is downloaded to the board. You can find on the
+`Arm Community page <https://community.arm.com/developer/tools-software/oss-platforms/w/docs/425/musca-b1-firmware-update-qspi-boot-recovery>`__
+A short description of how to update the DAPLink FW can be found there as well.
+
+--------------
+
+*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*
diff --git a/platform/readme.md b/platform/readme.md
deleted file mode 100644
index 6cac5a1..0000000
--- a/platform/readme.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# Details for the platform folder
-
-`NOTE` This folder and subfolders, especially the target folder, are likely to
-be refactored and updated to improve the overall structure of dependencies.
-
-## Interfacing with TF-M core
-
-### platform/ext/target/<target_platform>/tfm_peripherals_def.h
-This file should enumerate the hardware peripherals that are available for TF-M
-on the platform. The name of the peripheral used by a service is set in its
-manifest file. The platform have to provide a macro for each of the provided
-peripherals, that is substituted to a pointer to type
-`struct tfm_spm_partition_platform_data_t`. The memory that the pointer points
-to is allocated by the platform code. The pointer gets stored in the partitions
-database in SPM, and it is provided to the SPM HAL functions.
-
-#### Peripherals currently used by the services in TF-M
- - `TFM_PERIPHERAL_FPGA_IO` FPGA system control and I/O
- - `TFM_PERIPHERAL_UART1` UART1
-
-`NOTE` If a platform doesn't support a peripheral, that is used by a service,
-then the service cannot be used on the given platform. Using a peripheral in
-TF-M that is not supported by the platform results in compile error.
-
-### platform/include/tfm_spm_hal.h
-This file contains the declarations of functions that a platform implementation
-has to provide for TF-M. For details see the comments in the file.
-
-### secure_fw/core/tfm_platform_core_api.h
-This file contains declarations of functions that can be or have to be called
-from platform implementations. For details see the comments in the file.
-
-## Sub-folders
-
-### include
-This folder contains the interfaces that TF-M expects every target to provide.
-The code in this folder is created as a part of the TF-M project
-therefore it adheres to the BSD 3.0 license.
-
-### ext
-This folder contains code that has been imported from other projects so it may
-have licenses other than the BSD 3.0 used by the TF-M project.
-
-Please see the [readme file the ext folder](ext/readme.md) for details.
-
---------------
-
-*Copyright (c) 2017-2018, Arm Limited. All rights reserved.*
diff --git a/platform/readme.rst b/platform/readme.rst
new file mode 100644
index 0000000..20e5fbc
--- /dev/null
+++ b/platform/readme.rst
@@ -0,0 +1,64 @@
+###############################
+Details for the platform folder
+###############################
+
+.. Warning::
+
+ This folder and subfolders, especially the target folder, are likely to be
+ refactored and updated to improve the overall structure of dependencies.
+
+**************************
+Interfacing with TF-M core
+**************************
+
+platformext/target/tfm_peripherals_def.h
+========================================
+This file should enumerate the hardware peripherals that are available for TF-M
+on the platform. The name of the peripheral used by a service is set in its
+manifest file. The platform have to provide a macro for each of the provided
+peripherals, that is substituted to a pointer to type
+``struct tfm_spm_partition_platform_data_t``. The memory that the pointer points
+to is allocated by the platform code. The pointer gets stored in the partitions
+database in SPM, and it is provided to the SPM HAL functions.
+
+Peripherals currently used by the services in TF-M
+--------------------------------------------------
+- ``TFM_PERIPHERAL_FPGA_IO`` - FPGA system control and I/O
+- ``TFM_PERIPHERAL_UART1``- UART1
+
+.. Note::
+
+ If a platform doesn't support a peripheral, that is used by a service, then
+ the service cannot be used on the given platform. Using a peripheral in
+ TF-M that is not supported by the platform results in compile error.
+
+platform/include/tfm_spm_hal.h
+==============================
+This file contains the declarations of functions that a platform implementation
+has to provide for TF-M. For details see the comments in the file.
+
+secure_fw/core/tfm_platform_core_api.h
+======================================
+This file contains declarations of functions that can be or have to be called
+from platform implementations. For details see the comments in the file.
+
+***********
+Sub-folders
+***********
+
+include
+=======
+This folder contains the interfaces that TF-M expects every target to provide.
+The code in this folder is created as a part of the TF-M project therefore it
+adheres to the BSD 3.0 license.
+
+ext
+===
+This folder contains code that has been imported from other projects so it may
+have licenses other than the BSD 3.0 used by the TF-M project.
+
+Please see the :doc:`readme file the ext folder <ext/readme>` for details.
+
+--------------
+
+*Copyright (c) 2017-2019, Arm Limited. All rights reserved.*