diff options
author | Jimmy Brisson <jimmy.brisson@arm.com> | 2020-04-02 15:19:16 -0500 |
---|---|---|
committer | Jimmy Brisson <jimmy.brisson@arm.com> | 2020-04-20 10:04:20 -0500 |
commit | a48f50719a5c957bd67c68d5bdeec582dff6c59c (patch) | |
tree | 577b8152c6288aeffb70d7f0a467d4eec405fd09 | |
parent | 0862f0152af1f4f9a2661ba993ce3f3c021aa387 (diff) | |
download | tf-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.rst | 4 | ||||
-rw-r--r-- | docs/porting/build-flags.rst | 31 | ||||
-rw-r--r-- | docs/porting/index.rst | 30 | ||||
-rw-r--r-- | docs/porting/mandatory-mods.rst (renamed from docs/porting-guide.rst) | 132 | ||||
-rw-r--r-- | docs/porting/optional-mods.rst | 57 | ||||
-rw-r--r-- | docs/porting/requirements.rst | 16 | ||||
-rw-r--r-- | docs/porting/storage.rst | 18 |
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.* |