Platform Documentation

This document describes conventions for platform documentation for easy and smooth integration into TF-M online documentation.

Principles

Minimise TF-M requirements and maximise flexibility to let platform vendors reuse existing documentation.
Platforms are grouped under vendors’ name. There is space to keep general information not specific to any of the vendors’ platforms.
A Table Of Contents (TOC) structures platforms’ documentation. There is no defined template for platform documents.

Rules

Platforms documentation is gathered in /docs/platform folder. This folder is similar to the platforms implementation folder /platform/ext/target but does not need to mirror its structure.
A vendor is represented by a subfolder with index.rst as an entry point. This file may contain general materials about a vendor not specific to a particular platform.
A vendor’s index.rst shall carry a TOCtree structure with a list of all supported platforms at the top level.
An explicit platform name is preferred in a vendor’s TOCtree instead of use of platform’s title by default.

Note

Do not forget to update the summary file after adding a new platform /docs/platform/platform_introduction.rst included into TF-M introduction.

Example

Assuming a vendor ABCD123 wants to add and document a new platform Secure 1024 in TF-M. Here are the basic steps:

Create a folder /docs/platform/ABCD123/
Create a platform documentation under /docs/platform/ABCD123. A natural choice is to put a new platform under /docs/platform/ABCD123/Secure_1024 folder but it’s not required.
Create a file /docs/platform/ABCD123/index.rst with a platform entry, presuming it’s location in /docs/platform/ABCD123/Secure_1024/index.rst:

#################
ABCD123 platforms
#################

.. toctree::
Secure 1024 <Secure_1024/index>

Finally, update /docs/platform/index.rst with a new vendor name:

##############
TF-M Platforms
##############

.. toctree::
    :maxdepth: 2
    :glob:

    Arm <arm/index.rst>
    NXP <nxp/index.rst>
    Cypress <cypress/index.rst>
    ...
    ABCD123 <ABCD123/index.rst>