aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJimmy Brisson <jimmy.brisson@arm.com>2020-04-02 15:19:16 -0500
committerJimmy Brisson <jimmy.brisson@arm.com>2020-04-20 10:04:20 -0500
commita48f50719a5c957bd67c68d5bdeec582dff6c59c (patch)
tree577b8152c6288aeffb70d7f0a467d4eec405fd09
parent0862f0152af1f4f9a2661ba993ce3f3c021aa387 (diff)
downloadtf-a-tests-a48f50719a5c957bd67c68d5bdeec582dff6c59c.tar.gz
doc: Move content from Porting Guide
The Porting Guide document is broken down into separate, per-topic documents that all live under the new "Porting" chapter. Change-Id: I269fa06cbf6544ce3c76700d1fcf3a669793c483 Signed-off-by: Paul Beesley <paul.beesley@arm.com> Signed-off-by: Jimmy Brisson <jimmy.brisson@arm.com>
-rw-r--r--docs/index.rst4
-rw-r--r--docs/porting/build-flags.rst31
-rw-r--r--docs/porting/index.rst30
-rw-r--r--docs/porting/mandatory-mods.rst (renamed from docs/porting-guide.rst)132
-rw-r--r--docs/porting/optional-mods.rst57
-rw-r--r--docs/porting/requirements.rst16
-rw-r--r--docs/porting/storage.rst18
7 files changed, 156 insertions, 132 deletions
diff --git a/docs/index.rst b/docs/index.rst
index 14367673d..e8eee2f30 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -9,9 +9,9 @@ Trusted Firmware-A Tests Documentation
about/index
getting_started/index
process/index
- porting-guide
- implementing-tests
design
+ implementing-tests
+ porting/index
change-log
license
diff --git a/docs/porting/build-flags.rst b/docs/porting/build-flags.rst
new file mode 100644
index 000000000..7f9854d0f
--- /dev/null
+++ b/docs/porting/build-flags.rst
@@ -0,0 +1,31 @@
+Build Flags
+===========
+
+The platform may define build flagsto to control inclusion or exclusion of
+certain tests. These flags must be defined in the platform makefile which
+is included by the build system.
+
+- **PLAT_TESTS_SKIP_LIST**
+
+This build flag can be defined by the platform to control exclusion of some
+testcases from the default test plan for a platform. If used this needs to
+point to a text file which follows the following criteria:
+
+ - Contain a list of tests to skip for this platform.
+
+ - Specify 1 test per line, using the following format:
+
+ ::
+
+ testsuite_name/testcase_name
+
+ where ``testsuite_name`` and ``testcase_name`` are the names that appear in
+ the XML tests file.
+
+ - Alternatively, it is possible to disable a test suite entirely, which will
+ disable all test cases part of this test suite. To do so, only specify the
+ test suite name, omitting the ``/testcase_name`` part.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/porting/index.rst b/docs/porting/index.rst
new file mode 100644
index 000000000..2f39ea274
--- /dev/null
+++ b/docs/porting/index.rst
@@ -0,0 +1,30 @@
+Porting
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ requirements
+ storage
+ build-flags
+ mandatory-mods
+ optional-mods
+
+Porting the TF-A Tests to a new platform involves making some mandatory and
+optional modifications for both the cold and warm boot paths. Modifications
+consist of:
+
+* Implementing a platform-specific function or variable,
+* Setting up the execution context in a certain way, or
+* Defining certain constants (for example #defines).
+
+The platform-specific functions and variables are all declared in
+``include/plat/common/platform.h``. The framework provides a default
+implementation of variables and functions to fulfill the optional requirements.
+These implementations are all weakly defined; they are provided to ease the
+porting effort. Each platform port can override them with its own implementation
+if the default implementation is inadequate.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/porting-guide.rst b/docs/porting/mandatory-mods.rst
index ba9b9aaf8..4f1132418 100644
--- a/docs/porting-guide.rst
+++ b/docs/porting/mandatory-mods.rst
@@ -1,39 +1,3 @@
-Porting Guide
-=============
-
-Introduction
-------------
-
-Please note that this document is incomplete.
-
-Porting the TF-A Tests to a new platform involves making some mandatory and
-optional modifications for both the cold and warm boot paths. Modifications
-consist of:
-
-* Implementing a platform-specific function or variable,
-* Setting up the execution context in a certain way, or
-* Defining certain constants (for example #defines).
-
-The platform-specific functions and variables are all declared in
-``include/plat/common/platform.h``. The framework provides a default
-implementation of variables and functions to fulfill the optional requirements.
-These implementations are all weakly defined; they are provided to ease the
-porting effort. Each platform port can override them with its own implementation
-if the default implementation is inadequate.
-
-Platform requirements
----------------------
-
-The TF-A Tests rely on the following features to be present on the platform and
-accessible from Normal World.
-
-- Watchdog
-- Non-Volatile Memory
-- System Timer
-
-This also means that a platform port of the TF-A Tests must include software
-drivers for those features.
-
Mandatory modifications
-----------------------
@@ -332,101 +296,9 @@ Function : plat_crash_console_flush() [mandatory]
This function waits until all the characters of the platform-specific crash
console have been actually printed.
-Optional modifications
-----------------------
-
-The following are helper functions implemented by the test framework that
-perform common platform-specific tasks. A platform may choose to override these
-definitions.
-
-Function : platform_get_stack()
-```````````````````````````````
-
-::
-
- Argument : unsigned long
- Return : unsigned long
-
-This function returns the base address of the memory stack that has been
-allocated for the CPU specified by MPIDR. The size of the stack allocated to
-each CPU is specified by the platform defined constant ``PLATFORM_STACK_SIZE``.
-
-Common implementation of this function is provided in
-``plat/common/aarch64/platform_mp_stack.S``.
-
-Function : tftf_platform_end()
-``````````````````````````````
-
-::
-
- Argument : void
- Return : void
-
-This function performs any operation required by the platform to properly finish
-the test session.
-
-The default implementation sends an EOT (End Of Transmission) character on the
-UART. This can be used to automatically shutdown the FVP models. When running on
-real hardware, the UART output may be parsed by an external tool looking for
-this character and rebooting the platform for example.
-
-Function : tftf_plat_reset()
-````````````````````````````
-
-::
-
- Argument : void
- Return : void
-
-This function resets the platform.
-
-The default implementation uses the ARM watchdog peripheral (`SP805`_) to
-generate a watchdog timeout interrupt. This interrupt remains deliberately
-unserviced, which eventually asserts the reset signal.
-
-Storage abstraction layer
--------------------------
-
-In order to improve platform independence and portability a storage abstraction
-layer is used to store test results to non-volatile platform storage.
-
-Each platform should register devices and their drivers via the Storage layer.
-These drivers then need to be initialized in ``tftf_platform_setup()`` function.
-
-It is mandatory to implement at least one storage driver. For the FVP and Juno
-platforms the NOR Flash driver is provided as the default means to store test
-results to storage. The storage layer is described in the header file
-``include/lib/io_storage.h``. The implementation of the common library is in
-``drivers/io/io_storage.c`` and the driver files are located in ``drivers/io/``.
-
-
-Build Flags
------------
-
-- **PLAT_TESTS_SKIP_LIST**
-
-This build flag can be defined by the platform to control exclusion of some
-testcases from the default test plan for a platform. If used this needs to
-point to a text file which follows the following criteria:
-
- - Contain a list of tests to skip for this platform.
-
- - Specify 1 test per line, using the following format:
-
- ::
-
- testsuite_name/testcase_name
-
- where ``testsuite_name`` and ``testcase_name`` are the names that appear in
- the XML tests file.
-
- - Alternatively, it is possible to disable a test suite entirely, which will
- disable all test cases part of this test suite. To do so, only specify the
- test suite name, omitting the ``/testcase_name`` part.
-
--------------
-*Copyright (c) 2018-2019, Arm Limited. All rights reserved.*
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
-.. _docs/psci-pd-tree.rst: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/psci-pd-tree.rst
.. _SP805: https://static.docs.arm.com/ddi0270/b/DDI0270.pdf
+.. _docs/psci-pd-tree.rst: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/about/docs/psci-pd-tree.rst
diff --git a/docs/porting/optional-mods.rst b/docs/porting/optional-mods.rst
new file mode 100644
index 000000000..8bee341d2
--- /dev/null
+++ b/docs/porting/optional-mods.rst
@@ -0,0 +1,57 @@
+Optional modifications
+======================
+
+The following are helper functions implemented by the test framework that
+perform common platform-specific tasks. A platform may choose to override these
+definitions.
+
+Function : platform_get_stack()
+```````````````````````````````
+
+::
+
+ Argument : unsigned long
+ Return : unsigned long
+
+This function returns the base address of the memory stack that has been
+allocated for the CPU specified by MPIDR. The size of the stack allocated to
+each CPU is specified by the platform defined constant ``PLATFORM_STACK_SIZE``.
+
+Common implementation of this function is provided in
+``plat/common/aarch64/platform_mp_stack.S``.
+
+Function : tftf_platform_end()
+``````````````````````````````
+
+::
+
+ Argument : void
+ Return : void
+
+This function performs any operation required by the platform to properly finish
+the test session.
+
+The default implementation sends an EOT (End Of Transmission) character on the
+UART. This can be used to automatically shutdown the FVP models. When running on
+real hardware, the UART output may be parsed by an external tool looking for
+this character and rebooting the platform for example.
+
+Function : tftf_plat_reset()
+````````````````````````````
+
+::
+
+ Argument : void
+ Return : void
+
+This function resets the platform.
+
+The default implementation uses the ARM watchdog peripheral (`SP805`_) to
+generate a watchdog timeout interrupt. This interrupt remains deliberately
+unserviced, which eventually asserts the reset signal.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
+
+.. _SP805: https://static.docs.arm.com/ddi0270/b/DDI0270.pdf
diff --git a/docs/porting/requirements.rst b/docs/porting/requirements.rst
new file mode 100644
index 000000000..158b4b89f
--- /dev/null
+++ b/docs/porting/requirements.rst
@@ -0,0 +1,16 @@
+Platform requirements
+=====================
+
+The TF-A Tests rely on the following features to be present on the platform and
+accessible from Normal World.
+
+- Watchdog
+- Non-Volatile Memory
+- System Timer
+
+This also means that a platform port of the TF-A Tests must include software
+drivers for those features.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*
diff --git a/docs/porting/storage.rst b/docs/porting/storage.rst
new file mode 100644
index 000000000..6074358b5
--- /dev/null
+++ b/docs/porting/storage.rst
@@ -0,0 +1,18 @@
+Storage abstraction layer
+=========================
+
+In order to improve platform independence and portability a storage abstraction
+layer is used to store test results to non-volatile platform storage.
+
+Each platform should register devices and their drivers via the Storage layer.
+These drivers then need to be initialized in ``tftf_platform_setup()`` function.
+
+It is mandatory to implement at least one storage driver. For the FVP and Juno
+platforms the NOR Flash driver is provided as the default means to store test
+results to storage. The storage layer is described in the header file
+``include/lib/io_storage.h``. The implementation of the common library is in
+``drivers/io/io_storage.c`` and the driver files are located in ``drivers/io/``.
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*