From f67ca0748050a4e8554b6873e1d8b802c82c1f40 Mon Sep 17 00:00:00 2001 From: Sandrine Bailleux Date: Thu, 18 Sep 2014 17:36:12 +0100 Subject: Update documentation Update the porting guide: * structure of the document * list platform #defines and functions to port Update the user guide: * structure of the document * modify the build instructions to work around bug GENFW-385 Change-Id: Ia9bd7857ff2048a257ce26730be018beef01deb6 --- docs/porting-guide.md | 207 +++++++++++++++++++++++++++++++++++++++++++++++++- docs/user-guide.md | 99 ++++++++++++++++++++++-- 2 files changed, 296 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/porting-guide.md b/docs/porting-guide.md index 7582764..91af786 100644 --- a/docs/porting-guide.md +++ b/docs/porting-guide.md @@ -1,8 +1,207 @@ -*** tftf/tftf_platform.c +EL3 Firmware Test framework Porting Guide +========================================= - All functions in tftf/tftf_platform.c are weak definitions and most of - them do nothing. It is up to the platform to provide its own implementation - of those functions. +Contents +-------- + +1. Introduction +2. Platform requirements +3. Mandatory modifications +4. Optional modifications +5. Storage abstraction layer + +- - - - - - - - - - - - - - - - - - + +1. Introduction +---------------- + +Porting the EL3 Firmware Test Framework 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. + + +2. Platform requirements +------------------------- + +The Test Framework relies 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 Test Framework must include software +drivers for those features. + + +3. 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/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_CACHE_LINE_SIZE** + + Defines the size (in bytes) of the largest cache line across all the cache + levels in the platform. + +* **#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_MAX_CPUS_PER_CLUSTER** + + Defines the maximum number of CPUs that can be implemented within a cluster + on the platform. + +* **#define : PLATFORM_NUM_AFFS** + + Defines the total number of nodes in the affinity hierarchy at all affinity + levels used by the platform. + +* **#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. + +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`. + +### 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. + + +4. 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. + +In the FVP port, this function terminates the model by sending an EOT +(End Of Transmission) character on the UART. + + +5. 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 +`/io_storage.h`. The implementation of the common library is in +`/io_storage.c` and the driver files are located in `drivers/io/`. + + +------------------------------------------------------ +Old documentation *** (Optional) plat//tests_platform/tests_to_skip.txt diff --git a/docs/user-guide.md b/docs/user-guide.md index 519be3d..6506624 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -1,7 +1,56 @@ -### Building the test framework +EL3 Firmware Test Framework User Guide +====================================== -2 platforms are supported at the moment: - * FVP models +Contents : + +1. Introduction +2. Host machine requirements +3. Tools +4. Building the Test Framework + +- - - - - - - - - - - - - - - - - - + +1. Introduction +---------------- + +This document describes how to build the EL3 Firmware Test Framework for +the Juno ARM development platform and ARM Fixed Virtual Platform (FVP) +models. + + +2. 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 12.04.04 (64-bit). Packages used +for building the software were installed from that distribution unless +otherwise specified. + + +3. Tools +--------- + +The following tools are required to use the EL3 Firmware Test Framework: + +* Baremetal GNU GCC tools. Verified packages can be downloaded from [Linaro] + [Linaro Toolchain]. The rest of this document assumes that the + `gcc-linaro-aarch64-none-elf-4.9-2014.07_linux.tar.xz` tools are used. + + wget http://releases.linaro.org/14.07/components/toolchain/binaries/gcc-linaro-aarch64-none-elf-4.9-2014.07_linux.tar.xz + tar -xf gcc-linaro-aarch64-none-elf-4.9-2014.07_linux.tar.xz + +* (Optional) For debugging, ARM [Development Studio 5 (DS-5)][DS-5] v5.19. + + +4. Building the Test framework +--------------------------------- + +Two platforms are supported at the moment: + * FVP models: Foundation, Base AEM, Base Cortex * Juno board To build the software for one of these two platforms, follow these steps: @@ -9,7 +58,7 @@ To build the software for one of these two platforms, follow these steps: 1. Specify the cross-compiler prefix, the targeted platform and build: CROSS_COMPILE=/bin/aarch64-none-elf- \ - make PLAT= + make PLAT= all ... where `` is either `fvp` or `juno`. @@ -17,18 +66,56 @@ To build the software for one of these two platforms, follow these steps: debug version instead, CROSS_COMPILE=/bin/aarch64-none-elf- \ - make PLAT= DEBUG=1 + make PLAT= DEBUG=1 all To make the build verbose, use: CROSS_COMPILE=/bin/aarch64-none-elf- \ - make PLAT= V=1 + make PLAT= V=1 all 2. The build process creates products in a `build` directory tree. The resulting binary is in `build///tftf.bin` where `` is either `debug` or `release`. The resulting ELF file is in `build///tftf/tftf.elf` +### Summary of build options + +The Test Framework build system supports the following build options. 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 dependency for build options. Therefore, if any +of the build options are changed from a previous build, a clean build must be +performed. + +* `CROSS_COMPILE`: Prefix to toolchain binaries. Please refer to examples in + this document for usage. + +* `DEBUG`: Choose between a debug and release build. It can take either 0 + (release) or 1 (debug) as values. 0 is the default. + +* `PLAT`: Choose a platform to build the Test Framework for. The chosen + platform name must be the name of one of the directories under the `plat/` + directory other than `common`. + +* `TEST_REPORT_FORMAT`: Format of the test report. It can take either 'raw' + (text output on the console) or 'junit' (XML Junit format). The default is + 'raw'. + +* `V`: Verbose build. If assigned anything other than 0, the build commands + are printed. Default is 0. + +- - - - - - - - - - - - - - - - - - - - - - - - - - + +_Copyright (c) 2014, ARM Limited and Contributors. All rights reserved._ + + +[ARM FVP website]: http://www.arm.com/fvp +[Linaro Toolchain]: http://releases.linaro.org/14.07/components/toolchain/binaries/ +[DS-5]: http://www.arm.com/products/tools/software-tools/ds-5/index.php + + +--------------------------------------------------------- +Old documentation ### Overview of TFTF behaviour -- cgit v1.2.3