diff options
author | Sandrine Bailleux <sandrine.bailleux@arm.com> | 2018-10-09 11:12:55 +0200 |
---|---|---|
committer | Sandrine Bailleux <sandrine.bailleux@arm.com> | 2018-10-10 12:34:34 +0200 |
commit | 3cd87d77947ec4fc04440268ed122b4ed81c7781 (patch) | |
tree | 78fdee12b026b931029e434f29b4fe09835fe4c9 /docs | |
download | tf-a-tests-3cd87d77947ec4fc04440268ed122b4ed81c7781.tar.gz |
Trusted Firmware-A Tests, version 2.0v2.0
This is the first public version of the tests for the Trusted
Firmware-A project. Please see the documentation provided in the
source tree for more details.
Change-Id: I6f3452046a1351ac94a71b3525c30a4ca8db7867
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>
Co-authored-by: amobal01 <amol.balasokamble@arm.com>
Co-authored-by: Antonio Nino Diaz <antonio.ninodiaz@arm.com>
Co-authored-by: Asha R <asha.r@arm.com>
Co-authored-by: Chandni Cherukuri <chandni.cherukuri@arm.com>
Co-authored-by: David Cunado <david.cunado@arm.com>
Co-authored-by: Dimitris Papastamos <dimitris.papastamos@arm.com>
Co-authored-by: Douglas Raillard <douglas.raillard@arm.com>
Co-authored-by: dp-arm <dimitris.papastamos@arm.com>
Co-authored-by: Jeenu Viswambharan <jeenu.viswambharan@arm.com>
Co-authored-by: Jonathan Wright <jonathan.wright@arm.com>
Co-authored-by: Kévin Petit <kevin.petit@arm.com>
Co-authored-by: Roberto Vargas <roberto.vargas@arm.com>
Co-authored-by: Sathees Balya <sathees.balya@arm.com>
Co-authored-by: Shawon Roy <Shawon.Roy@arm.com>
Co-authored-by: Soby Mathew <soby.mathew@arm.com>
Co-authored-by: Thomas Abraham <thomas.abraham@arm.com>
Co-authored-by: Vikram Kanigiri <vikram.kanigiri@arm.com>
Co-authored-by: Yatharth Kochar <yatharth.kochar@arm.com>
Diffstat (limited to 'docs')
-rw-r--r-- | docs/change-log.rst | 241 | ||||
-rw-r--r-- | docs/design.rst | 266 | ||||
-rw-r--r-- | docs/implementing-tests.rst | 128 | ||||
-rw-r--r-- | docs/porting-guide.rst | 409 | ||||
-rw-r--r-- | docs/user-guide.rst | 550 |
5 files changed, 1594 insertions, 0 deletions
diff --git a/docs/change-log.rst b/docs/change-log.rst new file mode 100644 index 000000000..912a35a4d --- /dev/null +++ b/docs/change-log.rst @@ -0,0 +1,241 @@ + +.. section-numbering:: + :suffix: . + +.. contents:: + +Please note that the Trusted Firmware-A Tests version follows the Trusted +Firmware-A version for simplicity. At any point in time, TF-A Tests version +`x.y` aims at testing TF-A version `x.y`. Different versions of TF-A and TF-A +Tests are not guaranteed to be compatible. This also means that a version +upgrade on the TF-A-Tests side might not necessarily introduce any new feature. + +Trusted Firmware-A Tests - version 2.0 +====================================== + +New features +------------ + +This is the first public release of the Trusted Firmware-A Tests source code. + +TFTF +```` + +- Provides a baremetal test framework to exercise TF-A features through its + ``SMC`` interface. + +- Integrates easily with TF-A: the TFTF binary is packaged in the FIP image + as a ``BL33`` component. + +- Standalone binary that runs on the target without human intervention (except + for some specific tests that require a manual target reset). + +- Designed for multi-core testing. The various sub-frameworks allow maximum + parallelism in order to stress the firmware. + +- Displays test results on the UART output. This may then be parsed by an + external tool and integrated in a continuous integration system. + +- Supports running in AArch64 (NS-EL2 or NS-EL1) and AArch32 states. + +- Supports parsing a tests manifest (XML file) listing the tests to include in + the binary. + +- Detects most platform features at run time (e.g. topology, GIC version, ...). + +- Provides a topology enumeration framework. Allows tests to easily go through + affinity levels and power domain nodes. + +- Provides an event framework to synchronize CPU operations in a multi-core + context. + +- Provides a timer framework. Relies on a single global timer to generate + interrupts for all CPUs in the system. This allows tests to easily program + interrupts on demand to use as a wake-up event source to come out of CPU + suspend state for example. + +- Provides a power-state enumeration framework. Abstracts the valid power + states supported on the platform. + +- Provides helper functions for power management operations (CPU hotplug, + CPU suspend, system suspend, ...) with proper saving of the hardware state. + +- Supports rebooting the platform at the end of each test for greater + independence between tests. + +- Supports interrupting and resuming a test session. This relies on storing + test results in non-volatile memory (e.g. flash). + +FWU images +`````````` + +- Provides example code to exercise the Firmware Update feature of TF-A. + +- Tests the robustness of the FWU state machine implemented in the TF-A by + sending valid and invalid authentication, copy and image execution requests + to the TF-A BL1 image. + +EL3 test payload +```````````````` + +- Tests the ability of TF-A to load an EL3 payload. + +Cactus test secure partition +```````````````````````````` + +- Tests that TF-A has correctly setup the secure partition environment: it + should be allowed to perform cache maintenance operations, access floating + point registers, etc. + +- Tests the ability of a secure partition to request changing data access + permissions and instruction permissions of memory regions it owns. + +- Tests the ability of a secure partition to handle StandaloneMM requests. + +Known issues and limitations +---------------------------- + +The sections below lists the known issues and limitations of each test image +provided in this repository. + +TFTF +```` + +The TFTF test image might be conceptually sub-divided further in 2 parts: the +tests themselves, and the test framework they are based upon. + +Test framework +'''''''''''''' + +- Some stability issues. + +- No mechanism to abort tests when they time out (e.g. this could be + implemented using a watchdog). + +- No convenient way to include or exclude tests on a per-platform basis. + +- Power domains and affinity levels are considered equivalent but they may + not necessarily be. + +- Need to provide better support to alleviate duplication of test code. There + are some recurrent test patterns for which helper functions should be + provided. For example, bringing up all CPUs on the platform and executing the + same function on all of them, or programming an interrupt and waiting for it + to trigger. + +- Every CPU that participates in a test must return from the test function. If + it does not - e.g. because it powered itself off for testing purposes - then + the test framework will wait forever for this CPU. This limitation is too + restrictive for some tests. + +- No protection against interrupted flash operations. If the target is reset + while some data is written to flash, the test framework might behave + incorrectly on reset. + +- When compiling the code, if the generation of the tests_list.c and/or + tests_list.h files fails, the build process is not aborted immediately and + will only fail later on. + +- The directory layout is confusing. Most of the test framework code has been + moved under the ``tftf/`` directory to better isolate it but this effort is + not complete. As a result, there are still some TFTF files scattered around. + +Tests +''''' + +- Some tests are implemented for AArch64 only and are skipped on AArch32. + +- Some tests are not robust enough: + + - Some tests might hang in some circumstances. For example, they might wait + forever for a condition to become true. + + - Some tests rely on arbitrary time delays instead of proper synchronization + when executing order-sensitive steps. + + - Some tests have been implemented in a practical manner: they seem to work + on actual hardware but they make assumptions that are not guaranteed by + the Arm architecture. Therefore, they might fail on some other platforms. + +- PSCI stress tests are very unreliable and will often hang. The root cause is + not known for sure but this might be due to bad synchronization between CPUs. + +- The GICv2 spurious IRQ test is Juno-specific. In reality, it should only be + GICv2-specific. It should be reworked to remove any platform-specific + assumption. + +- The GICv2 spurious IRQ test sometimes fails with the following error message: + + ``SMC @ lead CPU returned 0xFFFFFFFF 0x8 0xC`` + + The root cause is unknown. + +- The manual tests in AArch32 mode do not work properly. They save some state + information into non-volatile memory in order to detect the reset reason but + this state does not appear to be retained. As a result, these tests keep + resetting infinitely. + +- The FWU tests take a long time to complete. This is because they wait for the + watchdog to reset the system. On FVP, TF-A configures the watchdog period to + about 4 min. This is way too long in an automated testing context. Besides, + the user gets not feedback, which may let them think that the tests are not + working properly. + +- The test "Target timer to a power down cpu" sometimes fails with the + following error message: + + ``Expected timer switch: 4 Actual: 3`` + + The root cause is unknown. + +FWU images +`````````` + +- NS-BL1U and NS-BL2U images reuse TFTF-specific code for legacy reasons. This + is not a clean design and may cause confusion. + +Cactus test secure partition +```````````````````````````` + +- Cactus is experimental code. It's likely to change a lot as the secure + partition software architecture evolves. + +- Fails to link with GNU toolchain 7.3.1. + +- Cactus is supported on AArch64 FVP platform only. + +All test images +``````````````` + +- TF-A Tests are derived from a fork of TF-A so: + + - they've got some code in common but lag behind on some features. + + - there might still be some irrelevant references to TF-A. + +- Some design issues. + E.g. TF-A Tests inherited from the I/O layer of TF-A, which still needs a + major rework. + +- Cannot build TF-A Tests with Clang. Only GCC is supported. + +- The build system does not cope well with parallel building. The user should + not attempt to run multiple jobs in parallel with the ``-j`` option of `GNU + make`. + +- The build system does not properly track build options. A clean build must be + performed every time a build option changes. + +- SMCCC v2 is not properly supported. + +- UUIDs are not compliant to RFC 4122. + +- No floating point support. The code is compiled with GCC flag + ``-mgeneral-regs-only``, which prevents the compiler from generating code + that accesses floating point registers. This might limit some test scenarios. + +- The documentation is too lightweight. + +-------------- + +*Copyright (c) 2018, Arm Limited. All rights reserved.* diff --git a/docs/design.rst b/docs/design.rst new file mode 100644 index 000000000..a59c1d7b4 --- /dev/null +++ b/docs/design.rst @@ -0,0 +1,266 @@ +Trusted Firmware-A Tests - Design +================================= + +.. section-numbering:: + :suffix: . + +.. contents:: + +This document provides some details about the internals of the TF-A Tests +design. It is incomplete at the moment. + +Global overview of the TF-A tests behaviour +------------------------------------------- + +The EL3 firmware is expected to hand over to the TF-A tests with all secondary +cores powered down, i.e. only the primary core should enter the TF-A tests. + +The primary CPU initialises the platform and the TF-A tests internal data +structures. + +Then the test session begins. The TF-A tests are executed one after the +other. Tests results are saved in non-volatile memory as we go along. + +Once all tests have completed, a report is generated. The TF-A tests currently +supports 2 report formats: + +- Raw output, i.e. text messages over serial console. + +- Junit output, i.e. XML file generated over semihosting. This is useful when a + post-processing tool needs to parse the test report, as it is more + machine-friendly than the raw output. + +The report format to use is chosen at build time. For more information, +refer to the section `Summary of build options`_ in the User Guide. + +Global Code Structure +--------------------- + +The code is organised into the following categories (present as directories at +the top level or under the ``tftf/`` directory): + +- **Drivers.** + + Some examples follow, this list might not be exhaustive. + + - Generic GIC driver. + + ``arm_gic.h`` contains the public APIs that tests might use. Both GIC + architecture versions 2 and 3 are supported. + + - PL011 UART driver. + + - VExpress NOR flash driver. + + Note that tests are not expected to use this driver in most + cases. Instead, they should use the ``tftf_nvm_read()`` and + ``tftf_nvm_write()`` wrapper APIs. See definitions in + ``tftf/framework/include/nvm.h``. See also the NVM validation test cases + (``tftf/tests/framework_validation_tests/test_validation_nvm.c``) for an + example of usage of these functions. + + - SP805 watchdog. + + Used solely to generate an interrupt that will reset the system on purpose + (used in ``tftf_plat_reset()``). + + - SP804 timer. + + This is used as the system timer on Juno. It is configured such that an + interrupt is generated when it reaches 0. It is programmed in one-shot + mode, i.e. it must be rearmed every time it reaches 0. + +- **Framework.** + + Core features of the test framework. + +- **Library code.** + + Some examples of APIs provided in ``include/lib/`` follow, this list might + not be exhaustive. + + - ``aarch64/`` + + Architecture helper functions for e.g. system registers access, cache + maintenance operations, MMU configuration, ... + + - ``events.h`` + + Events API. Used to create synchronisation points between CPUs in tests. + + - ``irq.h`` + + IRQ handling support. Used to configure IRQs and register/unregister + handlers called upon reception of a specific IRQ. + + - ``power_management.h`` + + Power management operations (CPU ON/OFF, CPU suspend, etc.). + + - ``sgi.h`` + + Software Generated Interrupt support. Used as an inter-CPU communication + mechanism. + + - ``spinlock.h`` + + Lightweight implementation of synchronisation locks. Used to prevent + concurrent accesses to shared data structures. + + - ``timer.h`` + + Support for programming the timer. Any timer which is in the `always-on` + power domain can be used to exit CPUs from suspend state. + + - ``tftf_lib.h`` + + Miscellaneous helper functions/macros: MP-safe ``printf()``, low-level + PSCI wrappers, insertion of delays, raw SMC interface, support for writing + a string in the test report, macros to skip tests on platforms that do not + meet topology requirements, etc. + + - ``semihosting.h`` + + Semihosting support. + + - ``io_storage.h`` + + Low-level IO operations. Tests are not expected to use these APIs + directly. They should use higher-level APIs like ``tftf_nvm_read()`` + and ``tftf_nvm_write()``. + + ``include/stdlib/`` provides standard C library functions (``memcpy()``, + ``printf()``, and so on). + +- **Platform specific.** + + Note that ``include/plat/common/plat_topology.h`` provides the interfaces + that a platform must implement to support topology discovery (i.e. how many + CPUs and clusters there are). + +- **Tests.** + +The tests are divided into the following categories (present as directories in +the ``tftf/tests/`` directory): + +- **Framework validation tests.** + + Tests that exercise the core features of the framework. Verify that the test + framework itself works properly. + +- **Runtime services tests.** + + Tests that exercise the runtime services offered by the EL3 Firmware to the + Normal World software. For example, this includes tests for the Standard + Service (to which PSCI belongs to), the Trusted OS service or the SiP + service. + +- **CPU extensions tests.** + + Tests some CPU extensions features. For example, the AMU tests ensure that + the counters provided by the Activity Monitor Unit are behaving correctly. + +- **Firmware Update tests.** + + Tests that exercise the `Firmware Update`_ feature of TF-A. + +- **Template tests.** + + Sample test code showing how to write tests in practice. Serves as + documentation. + +- **Performance tests.** + + Simple tests measuring the latency of an SMC call. + +- **Miscellaneous tests.** + + Tests for RAS support, correct system setup, ... + +All assembler files have the ``.S`` extension. The linker source file has the +extension ``.ld.S``. This is processed by GCC to create the linker script which +has the extension ``.ld``. + +Detailed Code Structure +----------------------- + +The cold boot entry point is ``tftf_entrypoint`` (see +``tftf/framework/aarch64/entrypoint.S``). As explained in section `Global +overview of the TF-A tests behaviour`_, only the primary CPU is expected to +execute this code. + +Tests can power on other CPUs using the function ``tftf_cpu_on()``. This uses +the PSCI ``CPU_ON`` API of the EL3 Firmware. When entering the Normal World, +execution starts at the warm boot entry point, which is ``tftf_hotplug_entry()`` +(see ``tftf/framework/aarch64/entrypoint.S``). + +Information about the progression of the test session and tests results are +written into Non-Volatile Memory as we go along. This consists of the following +data (see struct ``tftf_state_t`` typedef in ``tftf/framework/include/nvm.h``): + +- ``test_to_run`` + + Reference to the test to run. + +- ``test_progress`` + + Progress in the execution of ``test_to_run``. This is used to implement the + following state machine: + +:: + + +-> TEST_READY (initial state of the test) <--------------+ + | | | + | | Test framework prepares the test environment. | + | | | + | v | + | TEST_IN_PROGRESS | + | | | + | | Hand over to the test function. | + | | If the test wants to reboot the platform ---> TEST_REBOOTING | + | | | | + | | Test function returns into framework. | Reboot | + | | | | + | | +---------+ + | v + | TEST_COMPLETE + | | + | | Do some framework management. + | | Move to next test. + +--------+ + +- ``testcase_buffer`` + + A buffer that the test can use as a scratch area for whatever it is doing. + +- ``testcase_results`` + +- ``result_buffer_size`` + +- ``result_buffer`` + + Buffer holding the tests output. Tests output are concatenated. + +Interrupts management +--------------------- + +The TF-A tests expect SGIs #0 to #7 to be available for their own usage. In +particular, this means that Trusted World software must configure them as +non-secure interrupts. + +SGI #7 has a special status. It is the SGI that the timer management framework +sends to all CPUs when the system timer fires off (see the definition of the +constant ``IRQ_WAKE_SGI`` in the header file ``include/lib/irq.h``). Although +test cases can use this specific SGI - e.g. they can register an IRQ handler for +it and use it as an inter-CPU communication mechanism - they have to be aware of +the underlying consequences. Some tests, like the PSCI ``CPU_SUSPEND`` tests, +rely on this SGI to be enabled in order to wake up CPUs from their suspend +state. If it is disabled, these tests will leave the system in an unresponsive +state. + +-------------- + +*Copyright (c) 2018, Arm Limited. All rights reserved.* + +.. _Summary of build options: user-guide.html#summary-of-build-options +.. _Firmware Update: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/firmware-update.rst diff --git a/docs/implementing-tests.rst b/docs/implementing-tests.rst new file mode 100644 index 000000000..f7be28433 --- /dev/null +++ b/docs/implementing-tests.rst @@ -0,0 +1,128 @@ +How to implement tests +====================== + +.. section-numbering:: + :suffix: . + +.. contents:: + +This document aims at providing some pointers to help implementing new tests in +the TFTF image. + +Structure of a test +------------------- + +A test might be divided into 3 logical parts, detailed in the following +sections. + +Prologue +'''''''' + +A test has a main entry point function, whose type is: + +:: + + typedef test_result_t (*test_function_t)(void); + +See `tftf/framework/include/tftf.h`_. + +Only the primary CPU enters this function, while other CPUs are powered down. + +First of all, the test function should check whether this test is applicable to +this platform and environment. Some tests rely on specific hardware features or +firmware capabilities to be present. If these are not available, the test should +be skipped. For example, a multi-core test requires at least 2 CPUs to +run. Macros and functions are provided in `include/common/test_helpers.h`_ to +help test code verify that their requirements are met. + +Core +'''' + +This is completely dependent on the purpose of the test. The paragraphs below +just provide some useful, general information. + +The primary CPU may power on other CPUs by calling the function +``tftf_cpu_on()``. It provides an address to which secondary CPUs should jump +to once they have been initialized by the test framework. This address should be +different from the primary CPU test function. + +Synchronization primitives are provided in `include/lib/events.h`_ in case CPUs' +execution threads need to be synchronized. Most multi-processing tests will need +some synchronisation points that all/some CPUs need to reach before test +execution may continue. + +Any CPU that is involved in a test must return from its test function. Failure +to do so will put the framework in an unrecoverable state, see the `TFTF known +limitations`_. The return code indicates the test result from the point of view +of this CPU. At the end of the test, individual CPU results are aggregated and +the overall test result is derived from that. A test is considered as passed if +all involved CPUs reported a success status code. + +Epilogue +'''''''' + +Each test is responsible for releasing any allocated resources and putting the +system back in a clean state when it finishes. Any change to the system +configuration (e.g. MMU setup, GIC configuration, system registers, ...) must be +undone and the original configuration must be restored. This guarantees that the +next test is not affected by the actions of the previous one. + +One exception to this rule is that CPUs powered on as part of a test must not be +powered down. As already stated above, as soon as a CPU enters the test, the +framework expects it to return from the test. + +Template test code +------------------ + +Some template test code is provided in `tftf/tests/template_tests`_. It can be +used as a starting point for developing new tests. Template code for both +single-core and multi-core tests is provided. + +Plugging the test into the build system +--------------------------------------- + +All test code is located under the `tftf/tests`_ directory. Tests are usually +divided into categories represented as sub-directories under ``tftf/tests/``. + +The source file implementing the new test code should be added to the +appropriate tests makefile, see `.*mk` files under `tftf/tests`_. + +The new test code should also appear in a tests manifest, see ``*.xml`` files +under `tftf/tests`_. A unique name and test function must be provided. An +optional description may be provided as well. + +For example, to create a test case named "``Foo test case``", whose test +function is ``foo()``, add the following line in the tests manifest: + +:: + + <testcase name="Foo test case" function="foo" /> + +A testcase must be part of a testsuite. The ``testcase`` XML node above must be +inside a ``testsuite`` XML node. A unique name and a description must be +provided for the testsuite. + +For example, to create a test suite named "``Bar test suite``", whose +description is: "``An example test suite``", add the following 2 lines: + +:: + + <testsuite name="Bar test suite" description="An example test suite"> + </testsuite> + +See the template test manifest for reference: `tftf/tests/tests-template.xml`_. + +-------------- + +*Copyright (c) 2018, Arm Limited. All rights reserved.* + +.. _SMC Calling Convention: SMCCC_ +.. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf + +.. _TFTF known limitations: change-log.rst#test-framework +.. _tftf/framework/include/tftf.h: ../tftf/framework/include/tftf.h +.. _tftf/tests: ../tftf/tests +.. _tftf/tests/template_tests: ../tftf/tests/template_tests +.. _tftf/tests/tests-template.xml: ../tftf/tests/tests-template.xml +.. _include/common/test_helpers.h: ../include/common/test_helpers.h +.. _include/lib/events.h: ../include/lib/events.h diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst new file mode 100644 index 000000000..59d9dbad5 --- /dev/null +++ b/docs/porting-guide.rst @@ -0,0 +1,409 @@ +Trusted Firmware-A Tests - Porting Guide +======================================== + +.. section-numbering:: + :suffix: . + +.. contents:: + +-------------- + +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 +----------------------- + +File : platform_def.h [mandatory] +````````````````````````````````` + +Each platform must ensure that a header file of this name is in the system +include path with the following constants defined. This may require updating the +list of ``PLAT_INCLUDES`` in the ``platform.mk`` file. In the ARM FVP port, this +file is found in ``plat/arm/board/fvp/include/platform_def.h``. + +- **#define : PLATFORM_LINKER_FORMAT** + + Defines the linker format used by the platform, for example + `elf64-littleaarch64` used by the FVP. + +- **#define : PLATFORM_LINKER_ARCH** + + Defines the processor architecture for the linker by the platform, for + example `aarch64` used by the FVP. + +- **#define : PLATFORM_STACK_SIZE** + + Defines the stack memory available to each CPU. This constant is used by + ``plat/common/aarch64/platform_mp_stack.S``. + +- **#define : PLATFORM_CLUSTER_COUNT** + + Defines the total number of clusters implemented by the platform in the + system. + +- **#define : PLATFORM_CORE_COUNT** + + Defines the total number of CPUs implemented by the platform across all + clusters in the system. + +- **#define : PLATFORM_NUM_AFFS** + + Defines the total number of nodes in the affinity hierarchy at all affinity + levels used by the platform. + +- **#define : PLATFORM_MAX_AFFLVL** + + Defines the maximum number of affinity levels in the system that the platform + implements. ARMv8-A has support for 4 affinity levels. It is likely that + hardware will implement fewer affinity levels. For example, the Base AEM FVP + implements two clusters with a configurable number of CPUs. It reports the + maximum affinity level as 1. + +- **#define : PLAT_MAX_SPI_OFFSET_ID** + + Defines the offset of the last Shared Peripheral Interrupt supported by the + TF-A Tests on this platform. SPI numbers are mapped onto GIC interrupt IDs, + starting from interrupt ID 32. In other words, this offset ID corresponds to + the last SPI number, to which 32 must be added to get the corresponding last + GIC IRQ ID. + + E.g. If ``PLAT_MAX_SPI_OFFSET_ID`` is 10, this means that IRQ #42 is the last + SPI. + +- **#define : PLAT_LOCAL_PSTATE_WIDTH** + + Defines the bit-field width of the local state in State-ID field of the + power-state parameter. This macro will be used to compose the State-ID field + given the local power state at different affinity levels. + +- **#define : PLAT_MAX_PWR_STATES_PER_LVL** + + Defines the maximum number of power states at a power domain level for the + platform. This macro will be used by the ``PSCI_STAT_COUNT/RESIDENCY`` tests + to determine the size of the array to allocate for storing the statistics. + +- **#define : TFTF_BASE** + + Defines the base address of the TFTF binary in DRAM. Used by the linker + script to link the image at the right address. Must be aligned on a page-size + boundary. + +- **#define : IRQ_PCPU_NS_TIMER** + + Defines the IRQ ID of the per-CPU Non-Secure timer of the platform. + +- **#define : IRQ_CNTPSIRQ1** + + Defines the IRQ ID of the System timer of the platform. + +- **#define : TFTF_NVM_OFFSET** + + The TFTF needs some Non-Volatile Memory to store persistent data. This + defines the offset from the beginning of this memory that the TFTF can use. + +- **#define : TFTF_NVM_SIZE** + + Defines the size of the Non-Volatile Memory allocated for TFTF usage. + +If the platform port uses the ARM Watchdog Module (`SP805`_) peripheral, the +following constant needs to be defined: + +- **#define : SP805_WDOG_BASE** + + Defines the base address of the `SP805`_ watchdog peripheral. + +If the platform port uses the IO storage framework, the following constants +must also be defined: + +- **#define : MAX_IO_DEVICES** + + Defines the maximum number of registered IO devices. Attempting to register + more devices than this value using ``io_register_device()`` will fail with + ``IO_RESOURCES_EXHAUSTED``. + +- **#define : MAX_IO_HANDLES** + + Defines the maximum number of open IO handles. Attempting to open more IO + entities than this value using ``io_open()`` will fail with + ``IO_RESOURCES_EXHAUSTED``. + +If the platform port uses the VExpress NOR flash driver (see +``drivers/io/vexpress_nor/``), the following constants must also be defined: + +- **#define : NOR_FLASH_BLOCK_SIZE** + + Defines the largest block size as seen by the software while writing to NOR + flash. + +Function : tftf_plat_arch_setup() [mandatory] +````````````````````````````````````````````` +:: + + Argument : void + Return : void + +This function performs any platform-specific and architectural setup that the +platform requires. + +In both the ARM FVP and Juno ports, this function configures and enables the +MMU. + +Function : tftf_early_platform_setup() [mandatory] +`````````````````````````````````````````````````` + +:: + + Argument : void + Return : void + +This function executes with the MMU and data caches disabled. It is only called +by the primary CPU. It is used to perform platform-specific actions very early +in the boot. + +In both the ARM FVP and Juno ports, this function configures the console. + +Function : tftf_platform_setup() [mandatory] +```````````````````````````````````````````` + +:: + + Argument : void + Return : void + +This function executes with the MMU and data caches enabled. It is responsible +for performing any remaining platform-specific setup that can occur after the +MMU and data cache have been enabled. + +This function is also responsible for initializing the storage abstraction layer +used to access non-volatile memory for permanent storage of test results. It +also initialises the GIC and detects the platform topology using +platform-specific means. + +Function : plat_get_nvm_handle() [mandatory] +```````````````````````````````````````````` + +:: + + Argument : uintptr_t * + Return : void + +It is needed if the platform port uses IO storage framework. This function is +responsible for getting the pointer to the initialised non-volatile memory +entity. + +Function : tftf_plat_get_pwr_domain_tree_desc() [mandatory] +``````````````````````````````````````````````````````````` + +:: + + Argument : void + Return : const unsigned char * + +This function returns the platform topology description array in a suitable +format as expected by TFTF. The size of the array is expected to be +``PLATFORM_NUM_AFFS - PLATFORM_CORE_COUNT + 1``. The format used to describe +this array is : + +1. The first entry in the array specifies the number of power domains at the + highest power level implemented in the platform. This caters for platforms + where the power domain tree does not have a single root node e.g. the FVP + which has two cluster power domains at the highest level (that is, 1). + +2. Each subsequent entry corresponds to a power domain and contains the number + of power domains that are its direct children. + +The array format is the same as the one used by Trusted Firmware-A and more +details of its description can be found in the Trusted Firmware-A documentation: +`docs/psci-pd-tree.rst`_. + +Function : tftf_plat_get_mpidr() [mandatory] +```````````````````````````````````````````` + +:: + + Argument : unsigned int + Return : uint64_t + +This function converts a given `core_pos` into a valid MPIDR if the CPU is +present in the platform. The `core_pos` is a unique number less than the +``PLATFORM_CORE_COUNT`` returned by ``platform_get_core_pos()`` for a given +CPU. This API is used by the topology framework in TFTF to query the presence of +a CPU and, if present, returns the corresponding MPIDR for it. If the CPU +referred to by the `core_pos` is absent, then this function returns +``INVALID_MPID``. + +Function : plat_get_state_prop() [mandatory] +```````````````````````````````````````````` + +:: + + Argument : unsigned int + Return : const plat_state_prop_t * + +This functions returns the ``plat_state_prop_t`` array for all the valid low +power states from platform for a specified affinity level and returns ``NULL`` +for an invalid affinity level. The array is expected to be NULL-terminated. +This function is expected to be used by tests that need to compose the power +state parameter for use in ``PSCI_CPU_SUSPEND`` API or ``PSCI_STAT/RESIDENCY`` +API. + +Function : plat_fwu_io_setup() [mandatory] +`````````````````````````````````````````` + +:: + + Argument : void + Return : void + +This function initializes the IO system used by the firmware update. + +Function : plat_arm_gic_init() [mandatory] +`````````````````````````````````````````` + +:: + + Argument : void + Return : void + +This function initializes the ARM Generic Interrupt Controller (GIC). + +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. + +Function : tftf_platform_setup() +```````````````````````````````` + +:: + + Argument : void + Return : void + +Setup code for platform hardware. The default implementation initializes the IO +and GIC. + +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, Arm Limited. All rights reserved.* + +.. _docs/psci-pd-tree.rst: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/psci-pd-tree.rst +.. _SP805: https://static.docs.arm.com/ddi0270/b/DDI0270.pdf diff --git a/docs/user-guide.rst b/docs/user-guide.rst new file mode 100644 index 000000000..b638c6872 --- /dev/null +++ b/docs/user-guide.rst @@ -0,0 +1,550 @@ +Trusted Firmware-A Tests - User Guide +===================================== + +.. section-numbering:: + :suffix: . + +.. contents:: + +This document describes how to build the Trusted Firmware-A Tests (TF-A Tests) +and run them on a set of platforms. It assumes that the reader has previous +experience building and running the `Trusted Firmware-A (TF-A)`_. + +Host machine requirements +------------------------- + +The minimum recommended machine specification for building the software and +running the `FVP models`_ is a dual-core processor running at 2GHz with 12GB of +RAM. For best performance, use a machine with a quad-core processor running at +2.6GHz with 16GB of RAM. + +The software has been tested on Ubuntu 16.04 LTS (64-bit). Packages used for +building the software were installed from that distribution unless otherwise +specified. + +Tools +----- + +Install the required packages to build TF-A Tests with the following command: + +:: + + sudo apt-get install build-essential make git perl libxml-libxml-perl + +Download and install the GNU cross-toolchain from Linaro. The TF-A Tests have +been tested with version 6.2-2016.11 (gcc 6.2): + +- `AArch32 GNU cross-toolchain`_ +- `AArch64 GNU cross-toolchain`_ + +In addition, the following optional packages and tools may be needed: + +- For debugging, Arm `Development Studio 5 (DS-5)`_. + +Getting the TF-A Tests source code +---------------------------------- + +Download the TF-A Tests source code using the following command: + +:: + + git clone https://git.trustedfirmware.org/tf-a-tests.git + +Building TF-A Tests +------------------- + +- Before building TF-A Tests, the environment variable ``CROSS_COMPILE`` must + point to the Linaro cross compiler. + + For AArch64: + + :: + + export CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-linux-gnu- + + For AArch32: + + :: + + export CROSS_COMPILE=<path-to-aarch32-gcc>/bin/arm-linux-gnueabihf- + +- Change to the root directory of the TF-A Tests source tree and build. + + For AArch64: + + :: + + make PLAT=<platform> + + For AArch32: + + :: + + make PLAT=<platform> ARCH=aarch32 + + Notes: + + - If ``PLAT`` is not specified, ``fvp`` is assumed by default. See the + `Summary of build options`_ for more information on available build + options. + + - By default this produces a release version of the build. To produce a + debug version instead, build the code with ``DEBUG=1``. + + - The build process creates products in a ``build/`` directory tree, + building the objects and binaries for each test image in separate + sub-directories. The following binary files are created from the + corresponding ELF files: + + - ``build/<platform>/<build-type>/tftf.bin`` + - ``build/<platform>/<build-type>/ns_bl1u.bin`` + - ``build/<platform>/<build-type>/ns_bl2u.bin`` + - ``build/<platform>/<build-type>/el3_payload.bin`` + - ``build/<platform>/<build-type>/cactus.bin`` + + where ``<platform>`` is the name of the chosen platform and ``<build-type>`` + is either ``debug`` or ``release``. The actual number of images might differ + depending on the platform. + + Refer to the sections below for more information about each image. + +- Build products for a specific build variant can be removed using: + + :: + + make DEBUG=<D> PLAT=<platform> clean + + ... where ``<D>`` is ``0`` or ``1``, as specified when building. + + The build tree can be removed completely using: + + :: + + make realclean + +- Use the following command to list all supported build commands: + + :: + + make help + +TFTF test image +``````````````` + +``tftf.bin`` is the main test image to exercise the TF-A features. The other +test images provided in this repository are optional dependencies that TFTF +needs to test some specific features. + +``tftf.bin`` may be built independently of the other test images using the +following command: + +:: + + make PLAT=<platform> tftf + +In TF-A boot flow, ``tftf.bin`` replaces the ``BL33`` image and should be +injected in the FIP image. This might be achieved by running the following +command from the TF-A root directory: + +:: + + BL33=tftf.bin make PLAT=<platform> fip + +Please refer to the `TF-A User guide`_ for further details. + +NS_BL1U and NS_BL2U test images +``````````````````````````````` + +``ns_bl1u.bin`` and ``ns_bl2u.bin`` are test images that exercise the `Firmware +Update`_ (FWU) feature of TF-A [#]_. Throughout this document, they will be +referred as the `FWU test images`. + +In addition to updating the firmware, the FWU test images also embed some tests +that exercise the `FWU state machine`_ implemented in the TF-A. They send valid +and invalid SMC requests to the TF-A BL1 image in order to test its robustness. + +NS_BL1U test image +'''''''''''''''''' + +The ``NS_BL1U`` image acts as the `Application Processor (AP) Firmware Update +Boot ROM`. This typically is the first software agent executing on the AP in the +Normal World during a firmware update operation. Its primary purpose is to load +subsequent firmware update images from an external interface, such as NOR Flash, +and communicate with ``BL1`` to authenticate those images. + +The ``NS_BL1U`` test image provided in this repository performs the following +tasks: + +- Load FWU images from external non-volatile storage (typically flash memory) + to Non-Secure RAM. + +- Request TF-A BL1 to copy these images in Secure RAM and authenticate them. + +- Jump to ``NS_BL2U`` which carries out the next steps in the firmware update + process. + +This image may be built independently of the other test images using the +following command: + +:: + + make PLAT=<platform> ns_bl1u + +NS_BL2U test image +'''''''''''''''''' + +The ``NS_BL2U`` image acts as the `AP Firmware Updater`. Its primary +responsibility is to load a new set of firmware images from an external +interface and write them into non-volatile storage. + +The ``NS_BL2U`` test image provided in this repository overrides the original +FIP image stored in flash with the backup FIP image (see below). + +This image may be built independently of the other test images using the +following command: + +:: + + make PLAT=<platform> ns_bl2u + +Putting it all together +''''''''''''''''''''''' + +The FWU test images should be used in conjunction with the TFTF image, as the +latter initiates the FWU process by corrupting the FIP image and resetting the +target. Once the FWU process is complete, TFTF takes over again and checks that +the firmware was successfully updated. + +To sum up, 3 images must be built out of the TF-A Tests repository in order to +test the TF-A Firmware Update feature: + + - ``ns_bl1u.bin`` + - ``ns_bl2u.bin`` + - ``tftf.bin`` + +Once that's done, they must be combined in the right way. + + - ``ns_bl1u.bin`` is a standalone image and does not require any further + processing. + + - ``ns_bl2u.bin`` must be injected into the ``FWU_FIP`` image. This might be + achieved by setting ``NS_BL2U=ns_bl2u.bin`` when building the ``FWU_FIP`` + image out of the TF-A repository. Please refer to the section `Building FIP + images with support for Trusted Board Boot`_ in the TF-A User Guide. + + - ``tftf.bin`` must be injected in the standard FIP image, as explained + in section `TFTF test image`_. + +Additionally, on Juno platform, the FWU FIP must contain a ``SCP_BL2U`` image. +This image can simply be a copy of the standard ``SCP_BL2`` image if no specific +firmware update operations need to be carried on the SCP side. + +Finally, the backup FIP image must be created. This can simply be a copy of the +standard FIP image, which means that the Firmware Update process will restore +the original, uncorrupted FIP image. + +EL3 test payload +```````````````` + +``el3_payload.bin`` is a test image exercising the alternative `EL3 payload boot +flow`_ in TF-A. Refer to the `EL3 test payload README file`_ for more details +about its behaviour and how to build and run it. + +Cactus test image +````````````````` + +``cactus.bin`` is a test secure partition that exercises the `Secure Partition +Manager`_ (SPM) in TF-A [#]_. It runs in Secure-EL0. It performs the following +tasks: + +- Test that TF-A has correctly setup the secure partition environment: Cactus + should be allowed to perform cache maintenance operations, access floating + point registers, etc. + +- Test that TF-A accepts to change data access permissions and instruction + permissions on behalf of Cactus for memory regions the latter owns. + +- Test communication with SPM through the `ARM Management Mode Interface`_. + +At the moment, Cactus is supported on AArch64 FVP only. It may be built +independently of the other test images using the following command: + +:: + + make PLAT=fvp cactus + +In TF-A boot flow, Cactus replaces the ``BL32`` image and should be injected in +the FIP image. This might be achieved by running the following command from +the TF-A root directory: + +:: + + BL32=cactus.bin make PLAT=fvp fip + +Please refer to the `TF-A User guide`_ for further details. + +To run the full set of tests in Cactus, it should be used in conjunction with +the TFTF image, as the latter sends the Management Mode requests that Cactus +services. + +Summary of build options +```````````````````````` + +As much as possible, TF-A Tests dynamically detect the platform hardware +components and available features. There are a few build options to select +specific features where the dynamic detection falls short. This section lists +them. + +Unless mentioned otherwise, these options are expected to be specified at the +build command line and are not to be modified in any component makefiles. + +Note that the build system doesn't track dependencies for build options. +Therefore, if any of the build options are changed from a previous build, a +clean build must be performed. + +Build options shared across test images +''''''''''''''''''''''''''''''''''''''' + +Most of the build options listed in this section apply to TFTF, the FWU test +images and Cactus, unless otherwise specified. These do not influence the EL3 +payload, whose simplistic build system is mostly independent. + +- ``ARCH``: Choose the target build architecture for TF-A Tests. It can take + either ``aarch64`` or ``aarch32`` as values. By default, it is defined to + ``aarch64``. Not all test images support this build option. + +- ``ARM_ARCH_MAJOR``: The major version of Arm Architecture to target when + compiling TF-A Tests. Its value must be numeric, and defaults to 8. + +- ``ARM_ARCH_MINOR``: The minor version of Arm Architecture to target when + compiling TF-A Tests. Its value must be a numeric, and defaults to 0. + +- ``DEBUG``: Chooses between a debug and a release build. A debug build + typically embeds assertions checking the validity of some assumptions and its + output is more verbose. The option can take either 0 (release) or 1 (debug) + as values. 0 is the default. + +- ``ENABLE_ASSERTIONS``: This option controls whether calls to ``assert()`` are + compiled out. + + - For debug builds, this option defaults to 1, and calls to ``assert()`` are + compiled in. + - For release builds, this option defaults to 0 and calls to ``assert()`` + are compiled out. + + This option can be set independently of ``DEBUG``. It can also be used to + hide any auxiliary code that is only required for the assertion and does not + fit in the assertion itself. + +- ``LOG_LEVEL``: Chooses the log level, which controls the amount of console log + output compiled into the build. This should be one of the following: + + :: + + 0 (LOG_LEVEL_NONE) + 10 (LOG_LEVEL_ERROR) + 20 (LOG_LEVEL_NOTICE) + 30 (LOG_LEVEL_WARNING) + 40 (LOG_LEVEL_INFO) + 50 (LOG_LEVEL_VERBOSE) + + All log output up to and including the selected log level is compiled into + the build. The default value is 40 in debug builds and 20 in release builds. + +- ``PLAT``: Choose a platform to build TF-A Tests for. The chosen platform name + must be a subdirectory of any depth under ``plat/``, and must contain a + platform makefile named ``platform.mk``. For example, to build TF-A Tests for + the Arm Juno board, select ``PLAT=juno``. + +- ``V``: Verbose build. If assigned anything other than 0, the build commands + are printed. Default is 0. + +TFTF build options +'''''''''''''''''' + +- ``NEW_TEST_SESSION``: Choose whether a new test session should be started + every time or whether the framework should determine whether a previous + session was interrupted and resume it. It can take either 1 (always + start new session) or 0 (resume session as appropriate). 1 is the default. + +- ``SHELL_COLOR``: Choose whether text messages should use shell's color escape + sequences to ease identifying which CPU displays it. If enabled, this makes + each CPU write part of the message in a different color. It can take either + 0 (disabled) or 1 (enabled) as values. 0 is the default. + +- ``TEST_REPORTS``: List of desired test reports. Test reports are described by + a space-separated list of colon-separated pairs of report destination and + report type. Valid destinations are: 'uart' and 'semihosting'. Valid report + types are 'raw' (text output) or 'junit' (XML Junit format). The default is + 'uart:raw', that is a text report printed on the UART. Here's an example of + multiple reports: 'uart:raw semihosting:junit'. The files stored on + semihosting are named 'tftf_report_junit.xml' and 'tftf_report_raw.txt'. + +- ``TESTS_FILE``: Path to the XML file listing the tests to run. Default is + ``plat/<platform>/tests.xml`` if it exists, otherwise it falls back to + ``tftf/tests/tests-common.xml``. + +- ``USE_NVM``: Used to select the location of test results. It can take either 0 + (RAM) or 1 (non-volatile memory like flash) as test results storage. Default + value is 0, as writing to the flash significantly slows tests down. + +FWU test images build options +''''''''''''''''''''''''''''' + +- ``FIRMWARE_UPDATE``: Whether the Firmware Update test images (i.e. + ``NS_BL1U`` and ``NS_BL2U``) should be built. The default value is 0. The + platform makefile is free to override this value if Firmware Update is + supported on this platform. + +Checking source code style +-------------------------- + +When making changes to the source for submission to the project, the source must +be in compliance with the Linux style guide. To assist with this, the project +Makefile provides two targets, which both utilise the ``checkpatch.pl`` script +that ships with the Linux source tree. + +To check the entire source tree, you must first download copies of +``checkpatch.pl``, ``spelling.txt`` and ``const_structs.checkpatch`` available +in the `Linux master tree`_ scripts directory, then set the ``CHECKPATCH`` +environment variable to point to ``checkpatch.pl`` (with the other 2 files in +the same directory). + +Then use the following command: + +:: + + make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkcodebase + +To limit the coding style checks to your local changes, use: + +:: + + make CHECKPATCH=<path-to-linux>/linux/scripts/checkpatch.pl checkpatch + +By default, this will check all patches between ``origin/master`` and your local +branch. If you wish to use a different reference commit, this can be specified +using the ``BASE_COMMIT`` variable. + +Running the TF-A Tests +---------------------- + +Refer to the sections `Running the software on FVP`_ and `Running the software +on Juno`_ in `TF-A User Guide`_. The same instructions mostly apply to run the +TF-A Tests on those 2 platforms. The difference is that the following images are +not needed here: + +- Normal World bootloader. The TFTF replaces it in the boot flow; + +- Linux Kernel; + +- Device tree; + +- Filesystem. + +In other words, only the following software images are needed: + +- ``BL1`` firmware image; + +- ``FIP`` image containing the following images: + - ``BL2``; + - ``SCP_BL2`` if required by the platform (e.g. Juno); + - ``BL31``; + - ``BL32`` (optional); + - ``tftf.bin`` (standing as the BL33 image). + +Running the FWU tests +````````````````````` + +As previously mentioned in section `Putting it all together`_, there are a +couple of extra images involved when running the FWU tests. They need to be +loaded at the right addresses, which depend on the platform. + +FVP +''' + +In addition to the usual BL1 and FIP images, the following extra images must be +loaded: + +- ``NS_BL1U`` image at address ``0x0BEB8000`` (i.e. NS_BL1U_BASE macro in TF-A) +- ``FWU_FIP`` image at address ``0x08400000`` (i.e. NS_BL2U_BASE macro in TF-A) +- ``Backup FIP`` image at address ``0x09000000`` (i.e. FIP_BKP_ADDRESS macro in + TF-A tests). + +An example script is provided in `scripts/run_fwu_fvp.sh`_. + +Juno +'''' + +The same set of extra images and load addresses apply for Juno as for FVP. + +The new images must be programmed in flash memory by adding some entries in the +``SITE1/HBI0262x/images.txt`` configuration file on the Juno SD card (where +``x`` depends on the revision of the Juno board). Refer to the `Juno Getting +Started Guide`_, section 2.3 "Flash memory programming" for more +information. Users should ensure these do not overlap with any other entries in +the file. + +Addresses in this file are expressed as an offset from the base address of the +flash (that is, ``0x08000000``). + +:: + + NOR10UPDATE: AUTO ; Image Update:NONE/AUTO/FORCE + NOR10ADDRESS: 0x00400000 ; Image Flash Address + NOR10FILE: \SOFTWARE\fwu_fip.bin ; Image File Name + NOR10LOAD: 00000000 ; Image Load Address + NOR10ENTRY: 00000000 ; Image Entry Point + + NOR11UPDATE: AUTO ; Image Update:NONE/AUTO/FORCE + NOR11ADDRESS: 0x03EB8000 ; Image Flash Address + NOR11FILE: \SOFTWARE\ns_bl1u.bin ; Image File Name + NOR11LOAD: 00000000 ; Image Load Address + NOR11ENTRY: 00000000 ; Image Load Address + + NOR12UPDATE: AUTO ; Image Update:NONE/AUTO/FORCE + NOR12ADDRESS: 0x01000000 ; Image Flash Address + NOR12FILE: \SOFTWARE\backup_fip.bin ; Image File Name + NOR12LOAD: 00000000 ; Image Load Address + NOR12ENTRY: 00000000 ; Image Entry Point + +-------------- + +.. [#] Therefore, the Trusted Board Boot feature must be enabled in TF-A for + the FWU test images to work. Please refer the `TF-A User guide`_ for + further details. + +.. [#] Therefore, the Secure Partition Manager must be enabled in TF-A for + Cactus to work. Please refer to the `TF-A User guide`_ for further + details. + +-------------- + +*Copyright (c) 2018, Arm Limited. All rights reserved.* + +.. _Development Studio 5 (DS-5): https://developer.arm.com/products/software-development-tools/ds-5-development-studio + +.. _FVP models: https://developer.arm.com/products/system-design/fixed-virtual-platforms + +.. _AArch32 GNU cross-toolchain: http://releases.linaro.org/components/toolchain/binaries/6.2-2016.11/arm-linux-gnueabihf/gcc-linaro-6.2.1-2016.11-x86_64_arm-linux-gnueabihf.tar.xz +.. _AArch64 GNU cross-toolchain: http://releases.linaro.org/components/toolchain/binaries/6.2-2016.11/aarch64-linux-gnu/gcc-linaro-6.2.1-2016.11-x86_64_aarch64-linux-gnu.tar.xz + +.. _Linux master tree: https://github.com/torvalds/linux/tree/master/ + +.. _TF-A: https://www.github.com/ARM-software/arm-trusted-firmware +.. _Trusted Firmware-A (TF-A): TF-A_ +.. _EL3 payload boot flow: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/user-guide.rst#el3-payloads-alternative-boot-flow +.. _TF-A User Guide: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/user-guide.rst +.. _Firmware Update: FWU_ +.. _FWU: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/firmware-update.rst +.. _FWU state machine: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/firmware-update.rst#fwu-state-machine +.. _Running the software on FVP: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/user-guide.rst#running-the-software-on-fvp +.. _Running the software on Juno: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/user-guide.rst#running-the-software-on-juno +.. _Building FIP images with support for Trusted Board Boot: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/user-guide.rst#building-fip-images-with-support-for-trusted-board-boot +.. _Secure partition Manager: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/secure-partition-manager-design.rst + +.. _EL3 test payload README file: ../el3_payload/README +.. _scripts/run_fwu_fvp.sh: ../scripts/run_fwu_fvp.sh + +.. _ARM Management Mode Interface: http://infocenter.arm.com/help/topic/com.arm.doc.den0060a/DEN0060A_ARM_MM_Interface_Specification.pdf +.. _Juno Getting Started Guide: http://infocenter.arm.com/help/topic/com.arm.doc.dui0928e/DUI0928E_juno_arm_development_platform_gsg.pdf |