diff --git a/contributing.md b/contributing.md new file mode 100644 index 000000000..1b4fba562 --- /dev/null +++ b/contributing.md @@ -0,0 +1,12 @@ +Contributing to Trusted Firmware M +==================================== + +The contribution process is being finalized. + +Meanwhile, please email +[support-trustedfirmware-m@arm.com](support-trustedfirmware-m@arm.com) + with any comments, feedback or issues. + +-------------- + +*Copyright (c) 2017, Arm Limited. All rights reserved.* diff --git a/dco.txt b/dco.txt new file mode 100644 index 000000000..8201f9921 --- /dev/null +++ b/dco.txt @@ -0,0 +1,37 @@ +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +1 Letterman Drive +Suite D4700 +San Francisco, CA, 94129 + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. diff --git a/docs/user_guides/tfm_build_instruction.md b/docs/user_guides/tfm_build_instruction.md new file mode 100644 index 000000000..2d9d14bd4 --- /dev/null +++ b/docs/user_guides/tfm_build_instruction.md @@ -0,0 +1,82 @@ +# TF-M build instruction + +Please make sure you have all required software installed as explained in the +[software requirements](tfm_sw_requirement.md). + +## TF-M build steps +TF-M uses [cmake](https://cmake.org/overview/) to provide an out-of-tree build +environment. The instructions are below. + +### External dependency +* CMSIS_5 is used to import RTX for tests and apps +* mbedtls is used as crypto library on the secure side + +Both need to be cloned manually in the current release. + +### Build steps: + +``` +cd +git clone https://github.com/ARM-software/trusted-firmware-m.git +git clone https://github.com/ARMmbed/mbedtls.git -b mbedtls-2.5.1 +git clone https://github.com/ARM-software/CMSIS_5.git +cd trusted-firmware-m +mkdir cmake_build +cd cmake_build +cmake ../ -G"Unix Makefiles" +make +``` + +### Regression Tests +The default option build doesn't include regression tests. Procedure for +building the regression tests is below. + +`It is recommended that tests are built in a different directory.` + +*TF-M build regression tests on Linux* + +``` +cd +cd trusted-firmware-m +mkdir cmake_test +cd cmake_test +cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../ConfigRegression.cmake` ../ +make +``` + +*TF-M build regression tests on Windows* + +``` +cd +cd trusted-firmware-m +mkdir cmake_test +cd cmake_test +cmake -G"Unix Makefiles" -DPROJ_CONFIG=`cygpath -m ../ConfigRegression.cmake` ../ +make +``` + +## Export dependency files for NS applications + +An NS application requires a number of files to run with TF-M. The build +system can export these files using "install" target in to a single folder. + +*On Windows* + +``` +cmake -G"Unix Makefiles" -DPROJ_CONFIG=`cygpath -m ../ConfigRegression.cmake` ../ +make install +``` + +*On Linux* + +``` +cmake -G"Unix Makefiles" -DPROJ_CONFIG=`readlink -f ../ConfigRegression.cmake` ../ +make install +``` + +The [integration guide](user_guides/tfm_integration_guide.md) +explains further details of creating a new NS app. + +-------------- + +*Copyright (c) 2017, Arm Limited. All rights reserved.* diff --git a/docs/user_guides/tfm_integration_guide.md b/docs/user_guides/tfm_integration_guide.md new file mode 100644 index 000000000..e0d78ab56 --- /dev/null +++ b/docs/user_guides/tfm_integration_guide.md @@ -0,0 +1,91 @@ +# TF-M integration guide +The purpose of this document is to provide a guide on how to integrate TF-M with +other hardware platforms and operating systems. +## How to build TF-M +Follow the [Build instructions](tfm_build_instruction.md). + +## How to export files for building non-secure applications +Explained in the [Build instructions](tfm_build_instruction.md). + +## How to add a new platform +The SSE-200 sybsystem on the MPS2 board is the hardware platform currently +supported by TF-M. The files related to the platform being used are contained +under the `platform` subfolder, in particular inside `platform/target`. The TF-M +current implementation has the `platform/target/sse_200_mps2` platform, and +a `platform/target/common` folder which is used to store source and header files +which are platform generic. + +#### generic drivers and startup/scatter files +The addition of a new platform means the creation of a new subfolder inside +`target` to provide an implementation of the drivers currently used by TF-M, +in particular MPC, PPC, and USART drivers. In addition to the drivers, +startup and scatter files need to be provided for the supported toolchains, e.g. +armclang specific files can be found in `armclang` subfolder. There are also +board specific drivers which are used by the board platform to interact with the +external world, for example during tests, that have to be provided, e.g. to +blink LEDs or count time in the MPS2 board. When a new platform is added, the +files being built by the build systems need to be updated manually, as the +platform folder being used is currently hardcoded to `sse_200_mps2`. + +#### target configuration files +Inside the base root folder of the selected target, each implementation has to +provide its own copy of `target_cfg.c/.h`. This file has target specific +configuration functions and settings that are called by the TF-M during the +platform configuration step during TF-M boot. Examples of the configurations +performed during this phase are the MPC configuration, the SAU configuration, +or eventually PPC configuration if supported by the hardware platform. +Similarly, the `uart_stdout.c` is used to provide functions needed to redirect +the stdout on UART (this is currently used by TF-M to log messages). + +#### platform retarget files +An important part that each new platform has to provide is the set of retarget +files which are contained inside the `retarget` folder. These files define the +peripheral base addresses for the platform, both for the secure and non-secure +aliases (when available), and bind those addresses to the base addresses used by +the devices available in the hardware platform. + +## How to integrate another OS +To work with TF-M, the OS needs to support the Armv8-M architecture and, +in particular, it needs to be able to run in the non-secure world. Depending +upon the system configuration this may require configuring drivers to use +appropriate address ranges. + +#### interface with TF-M +The NS side is only allowed to call TF-M secure functions (veneers) from the +NS Handler mode. +For this reason, the API is a collection of SVC functions in the +`export/tfm/inc` folder. For example, the SVC interface for the Secure STorage +(SST) service is described in the file `tfm_sst_svc_handler.h` as a collection +of SVC functions which have to be registered within the SVC handler +mechanism,therefore OS needs to support user defined SVCs. +If the OS does not support user defined SVCs, it needs to be extended in +this way. Once the SVC interface functions are registered within the SVC +handler mechanism, the services can be called from the non-secure world +applications (running in Thread mode) using a wrapper API which is described in +`tfm_sst_api.h`. This API is a wrapper for the SVC interface, its purpose is +to request Handler mode through the SVC instructions encoded with the +corresponding SVC number previously registered with the SVC handler and to +handle the return value from the service to the caller. +The secure storage service also needs the NS side to provide an implementation +for the function `tfm_sst_get_cur_id()` which is used to retrieve the numerical +ID associated to the running thread. A primitive implementation is +provided in tfm_sst_id_mngr_dummy.c. It is system integrators responsibility + to implement the ID manager based on their threat model. + +#### interface with non-secure world regression tests +A non-secure application that wants to run the non-secure regression tests +needs to call the `start_integ_test()`. This function is exported into the +header file `integ_test.h` inside the `install` folder structure in the test +specific files, i.e. `install/tfm/test/inc`. The non-secure regression tests are +precompiled and delivered as a static library which is available in +`install/tfm/test/lib`, so that the non-secure application needs to link against +the library to be able to invoke the `start_integ_test()` function. +The SST non-secure side regression tests rely on some OS functionality +e.g. threads, mutexes etc. These functions comply with CMSIS RTOS2 standard and +have been exported as thin wrappers defined in `os_wrapper.h` contained in +`install/tfm/test/inc`. OS needs to provide the implementation of these wrappers +to be able to run the tests. + +-------------- + +*Copyright (c) 2017, Arm Limited. All rights reserved.* diff --git a/docs/user_guides/tfm_sw_requirement.md b/docs/user_guides/tfm_sw_requirement.md new file mode 100644 index 000000000..182fe7464 --- /dev/null +++ b/docs/user_guides/tfm_sw_requirement.md @@ -0,0 +1,70 @@ +# TF-M Software requirements +To compile TF-M code, you need ARM Compiler v6.7.1. The ARM +compiler is provided via Keil uVision v5.24.1 or DS-5 v5.27.1. + +*Note* In this version, you also need manually clone CMSIS_5 and mbedtls +repositories at the same location where tfm repo is located. + +*Note* ARM compiler specific environment variable may need updating based +on specific products and licenses as explained in +[product-and-toolkit-configuration](https://developer.arm.com/products/software-development-tools/license-management/resources/product-and-toolkit-configuration). + + +## Linux +- DS-5 v5.27.1. +- Git tools v2.10.0 +- Cmake v3.7.0 + https://cmake.org/download/ +- GNU Make v3.81 + +### Setup a shell to enable ARM Compiler v6.7.1 and cmake after installation. + +To import ARM Compiler v6.7.1 in your bash shell console: +~~~ +export PATH=/sw/ARMCompiler6.7.1/bin:$PATH +export ARM_TOOL_VARIANT="ult" +export ARM_PRODUCT_PATH="/sw/mappings" +export ARMLMD_LICENSE_FILE="" +~~~ +To import cmake in your bash shell console: +~~~ +export PATH=/bin:$PATH +~~~ + +## On Windows +- uVision v5.24.1 or DS-5 v5.27.1 (DS-5 Ultimate Edition) which provides the + ARM Compiler v6.7.1 compiler. +- Git client latest version (https://git-scm.com/download/win) +- Cmake v3.7.0 ( https://cmake.org/download/ ) +- Cygwin ( https://www.cygwin.com/ ). Tests done with version 2.877 (64 bits) +- GNU make should be installed by selecting appropriate package during cygwin installation. + +### Setup Cygwin to enable ARM Compiler v6.7.1 and cmake after installation. + +Import ARM Compiler v6.7.1 in your shell console. To make this change permanent, +add the command line into ~/.bashrc + +**DS5** +~~~ +export PATH="/cygdrive/c//sw/ARMCompiler6.7.1/bin":$PATH +export ARM_PRODUCT_PATH="C://sw/mappings" +~~~ + +**Keil** +~~~ +export PATH="/cygdrive/c//ARM/ARMCLANG/bin":$PATH +export ARM_PRODUCT_PATH="C://ARM/sw/mappings" +~~~ + +**Shared settings** +~~~ +export ARM_TOOL_VARIANT="ult" +export ARMLMD_LICENSE_FILE="" +~~~ +To import cmake in your bash shell console: +~~~ +export PATH=/cygdrive/c//bin:$PATH +~~~ +-------------- + +*Copyright (c) 2017, Arm Limited. All rights reserved.* diff --git a/docs/user_guides/tfm_user_guide.md b/docs/user_guides/tfm_user_guide.md new file mode 100644 index 000000000..8a3184509 --- /dev/null +++ b/docs/user_guides/tfm_user_guide.md @@ -0,0 +1,129 @@ +# Trusted Firmware M user guide +How to compile and run TF-M example application and tests for CoreLink SSE-200 +subsystem on the MPS2 board and the Fast Model(FVP). + +Follow [build instruction](./tfm_build_instruction.md) to build the binaries. + +## Execute TF-M example and regression tests on MPS2 boards and FVP ## +The TF-M example application and tests run correctly on SMM-SSE-200 for +MPS2 (AN521) and on the Fixed Virtual Platform model FVP_MPS2_AEMv8M +version 11.2.23. + +### To run the example code on FVP_MPS2_AEMv8M +Using FVP_MPS2_AEMv8M provided by DS-5 v5.27.1. + +*FVP reference guide can be found +[here](https://developer.arm.com/docs/100966/latest)* + +#### Example application + +``` +/sw/models/bin/FVP_MPS2_AEMv8M \ +--parameter fvp_mps2.platform_type=2 \ +--parameter cpu0.baseline=0 \ +--start cpu0=0x10000004 \ +--parameter cpu0.INITVTOR_S=0x10000000 \ +--parameter cpu0.semihosting-enable=0 \ +--parameter fvp_mps2.DISABLE_GATING=0 \ +--parameter fvp_mps2.telnetterminal0.start_telnet=1 \ +--parameter fvp_mps2.telnetterminal1.start_telnet=0 \ +--parameter fvp_mps2.telnetterminal2.start_telnet=0 \ +--parameter fvp_mps2.telnetterminal0.quiet=0 \ +--parameter fvp_mps2.telnetterminal1.quiet=1 \ +--parameter fvp_mps2.telnetterminal2.quiet=1 \ +--application cpu0=/app/tfm_ns.axf \ +--application cpu0=/app/secure_fw/tfm_s.axf +``` +#### Regression tests +``` +/sw/models/bin/FVP_MPS2_AEMv8M \ +--parameter fvp_mps2.platform_type=2 \ +--parameter cpu0.baseline=0 \ +--start cpu0=0x10000004 \ +--parameter cpu0.INITVTOR_S=0x10000000 \ +--parameter cpu0.semihosting-enable=0 \ +--parameter fvp_mps2.DISABLE_GATING=0 \ +--parameter fvp_mps2.telnetterminal0.start_telnet=1 \ +--parameter fvp_mps2.telnetterminal1.start_telnet=0 \ +--parameter fvp_mps2.telnetterminal2.start_telnet=0 \ +--parameter fvp_mps2.telnetterminal0.quiet=0 \ +--parameter fvp_mps2.telnetterminal1.quiet=1 \ +--parameter fvp_mps2.telnetterminal2.quiet=1 \ +--application cpu0=/app/tfm_ns.axf \ +--application cpu0=/app/secure_fw/tfm_s.axf +``` + +### To run the example code on SSE 200 FPGA on MPS2 board +FPGA image is available to download [here](https://developer.arm.com/products/ +system-design/development-boards/cortex-m-prototyping-systems/mps2) + +To run TF-M example application and tests in the MPS2 board, it is required to +have SMM-SSE-200 for MPS2 (AN521) image in the MPS2 board SD card. +The image should be located in +`/MB/HBI0263/AN521` + +The MPS2 board tested is HBI0263C referred also as MPS2+. + +`Note: If you change the exe names, MPS2 expects file names in 8.3 format.` + +#### Example application + +1. Copy tfm_s.axf and tfm_ns.axf files in /SOFTWARE/ +2. Open /MB/HBI0263/AN521/images.txt +3. Update the AN521/images.txt file as follows: +``` +TITLE: Versatile Express Images Configuration File +[IMAGES] +TOTALIMAGES: 2 ;Number of Images (Max: 32) +IMAGE0ADDRESS: 0x00000000 +IMAGE0FILE: \Software\tfm_s.axf ; TF-M example application secure binary +IMAGE1ADDRESS: 0x00000000 +IMAGE1FILE: \Software\tfm_ns.axf ; TF-M example application non-secure binary +``` +4. Close /MB/HBI0263C/AN521/images.txt +5. Unmount/eject the unit +6. Reset the board to execute the TF-M example application +7. After completing the procedure you should be able to visualize on the serial + port (baud 115200 8n1) the following messages: + +``` +At the moment the examples application only shows following - + +[Sec Thread] Secure image initializing! +``` + +#### Regression tests + +After completing the procedure you should be able to visualize on the serial +port (baud 115200 8n1) the following messages: + +``` +[Sec Thread] Secure image initializing! + +#### Execute test suites for the Secure area #### +Running Test Suite SST secure interface tests (TFM_SST_TEST_2XXX)... + +> Executing 'TFM_SST_TEST_2001' + Description: 'Create interface' + TEST PASSED! +> Executing 'TFM_SST_TEST_2002' + Description: 'Get handle interface' + TEST PASSED! +> Executing 'TFM_SST_TEST_2003' + Description: 'Get attributes interface' + TEST PASSED! +> Executing 'TFM_SST_TEST_2004' + Description: 'Write interface' + TEST PASSED! +> Executing 'TFM_SST_TEST_2005' + Description: 'Read interface' +.... + +``` + +Note: SST reliability tests may take more than 40 minutes to run on the + MPS2. + +-------------- + +*Copyright (c) 2017, Arm Limited. All rights reserved.* diff --git a/glossary.md b/glossary.md new file mode 100644 index 000000000..dc9bb8fce --- /dev/null +++ b/glossary.md @@ -0,0 +1,28 @@ +# TF-M glossary of terms and abbreviations + +| Term | Abbrev. | Description | +| --- | --- | --- | +| ** TF-M related ** | | | +| Trusted Firmware for M-class | TF-M | ARM TF-M provides a reference implementation of secure world software for ARMv8-M. | +| Trusted Firmware for M-class | TFM | ARM TF-M provides a reference implementation of secure world software for ARMv8-M. | +| Secure Processing Environment | SPE | PSA term. In TF-M this means the secure domain protected by TF-M| +| Non Secure Processing Enviroment| NSPE | PSA term. In TF-M this means non secure domain typically running an OS using services provided by TF-M| +| Secure Service | SS | A component within the TEE that is atomic from a security/trust point of view, i.e. which is viewed as a single entity from a TF-M point of view | +| Secure Partition | SP | A logical container for a single secure service | +| Secure Partition Manager | SPM | The TF-M component responsible for enumeration, management and isolation of multiple Secure Partitions within the TEE | +| Secure Function | SFN | An entry function to a secure service. Multiple SFN per SS are permitted | +| Secure Storage Service | SST | Secure storage service provided by TF-M | +| ** SSE-200 platform ** | | | +| Memory Protection Controller | MPC | Bus slave-side security controller for memory regions | +| Peripheral Protection Controller | PPC | Bus slave-side security controller for peripheral access | +| ** v8M-specific ** | | | +| Secure/Non-secure | S/NS | The separation provided by TrustZone hardware components in the system | +| Secure Attribution Unit | SAU | Hardware component providing isolation between Secure, Non-secure Callable and Non-secure addresses | +| ** M-class Generic ** | | | +| ARM Architecture Procedure Call Standard | AAPCS | The AAPCS defines how subroutines can be separately written, separately compiled, and separately assembled to work together. It describes a contract between a calling routine and a called routine | +| SuperVisor Call | SVC | ARMv7M assembly instruction to call a privileged handler function | +| Memory Protection Unit | MPU | Hardware component providing privilege control | + +-------------- + +*Copyright (c) 2017, Arm Limited. All rights reserved.* diff --git a/license.md b/license.md new file mode 100644 index 000000000..f79497275 --- /dev/null +++ b/license.md @@ -0,0 +1,36 @@ +Copyright (c) 2017, Arm Limited. All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + +- Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. +- Redistributions in binary form must reproduce the above copyright notice, this + list of conditions and the following disclaimer in the documentation and/or + other materials provided with the distribution. +- Neither the name of ARM nor the names of its contributors may be used to + endorse or promote products derived from this software without specific prior + written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR +ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON +ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +--- + +*Note*: +Individual files contain the following tag instead of the full license text. + + + + SPDX-License-Identifier: BSD-3-Clause + +This enables machine processing of license information based on the SPDX +License Identifiers that are here available: http://spdx.org/licenses/ diff --git a/maintainers.md b/maintainers.md new file mode 100644 index 000000000..ed59e0c09 --- /dev/null +++ b/maintainers.md @@ -0,0 +1,35 @@ +# Trusted Firmware M - Maintainers + +Trusted Firmware M is a community maintained project. Contributions can only +be approved and merged by the maintainers listed below. +Sub-maintainers' approval is required for their specific areas of ownership. + +Contributions must follow the instructions in +[Contributing Guidelines](contributing.md). + + +## Maintainers + +Abhishek Pandit ([abhishek.pandit@arm.com](abhishek.pandit@arm.com) +, [abhishek-pandit](https://github.com/abhishek-pandit)) + +Ashutosh Singh ([ashutosh.singh@arm.com](ashutosh.singh@arm.com) +, [ashutoshksingh](https://github.com/ashutoshksingh)) + +Miklos Balint ([miklos.balint@arm.com](miklos.balint@arm.com) +, [wmnt](https://github.com/wmnt)) + + +## Sub-maintainers + +### Bootloader +Tamas Ban ([Tamas.Ban@arm.com](Tamas.Ban@arm.com) +, [tamban01](https://github.com/tamban01)) + +### Secure Storage +Marc Moreno Berengue ([marc.morenoberengue@arm.com](marc.morenoberengue@arm.com) +, [mmorenobarm](https://github.com/mmorenobarm)) + +-------------- + +*Copyright (c) 2017, Arm Limited. All rights reserved.* diff --git a/platform/ext/readme.md b/platform/ext/readme.md new file mode 100644 index 000000000..4c8f2fe34 --- /dev/null +++ b/platform/ext/readme.md @@ -0,0 +1,30 @@ +# Details for the platform/ext folder + +This folder has code that has been imported from other projects. This means the +files in this folder and subfolders have Apache 2.0 license which +is different to BSD 3.0 license applied to the parent TF-M project. + + +`NOTE` This folder is strictly Apache 2.0 with the exception of cmake files. +Maintainers should be consulted if this needs to be revisited. + +## Sub-folders + +### cmsis + +This folder contains core and compiler specific header files imported from the +CMSIS_5 project. + +### drivers + +This folder contains the headers with CMSIS compliant driver definitions that +that TF-M project expects a target to provide. + +### target +This folder contains the files for individual target and also any wrapper that +can be across targets. + + +-------------- + +*Copyright (c) 2017, Arm Limited. All rights reserved.* diff --git a/platform/readme.md b/platform/readme.md new file mode 100644 index 000000000..6e75bc530 --- /dev/null +++ b/platform/readme.md @@ -0,0 +1,21 @@ +# Details for the platform folder + +`NOTE` This folder and subfolders, especially the target folder, are likely to +be refactored and updated to improve the overall structure of dependencies. + +## Sub-folders + +### include +This folder contains the interfaces that TF-M expects every target to provide. +The code in this folder is created as a part of the TF-M project +therefore it adheres to the BSD 3.0 license. + +### ext +This folder contains code that has been imported from other projects so it may +have licenses other than the BSD 3.0 used by the TF-M project. + +Please see the [readme file the ext folder](ext/readme.md) for details. + +-------------- + +*Copyright (c) 2017, Arm Limited. All rights reserved.* diff --git a/readme.md b/readme.md new file mode 100644 index 000000000..738582781 --- /dev/null +++ b/readme.md @@ -0,0 +1,129 @@ +# Trusted Firmware M - v0.1 + +Trusted Firmware M provides a reference implementation of secure world +software for ARMv8-M. + +*Note:* The software implementation contained in this project is designed to +be a reference implementation of the Arm Platform Security Architecture (PSA). +It currently does not implement all the features of that architecture, however +we expect the code to evolve over 2018 along with the specifications. + +`Terms 'TFM' and 'TF-M' are commonly used in documents and code and both +refer to Trusted Firmware M.` + +[Glossary](glossary.md) has the list of terms and abbreviations. + +## License + +The software is provided under a BSD-3-Clause [License](license.md). +Contributions to this project are accepted under the same license with developer +sign-off as described in the [Contributing Guidelines](contributing.md). + +This project contains code from other projects as listed below. The code from +external projects is limited to `app` and `platform` folders. +The original license text is included in those source files. + +* The platform folder currently contains drivers imported from external project + and the files have Apache 2.0 license. +* The app folder contains files imported from CMSIS_5 project + and the files have Apache 2.0 license. + +*Note* Any code that has license other than BSD-3-Clause is kept in +specific sub folders named `ext` so that it can isolated if required. + +## This Release + +This release includes + +* A Secure FW with support for PSA Level 1 isolation on ARMv8M. +* The Interfaces exposed by the Secure FW to NS side. +* A blocking secure fw model with NS application example. +* Example secure service (or secure function) running within this SPE. + * Only secure storage service is supported in this release. +* Testcases running baremetal and with RTX to test the functionality. +* Basic support for higher level isolation but it is `in progress with +limited testing`. +* Build system based on cmake and armclang. + +### in progress + +* GCC support +* Ongoing and incremental support for PSA features. + * Level 3 PSA isolation + * PSA Crypto API support + * PSA IPC support + * ... +* OS support and use case examples. + * mbed OS upstream support + * mbed cloud client examples + * ... +* Additional platform support. + * Musca test chip + * Cortex M23 support + * ... +* Ongoing security hardening, optimization and quality improvements. + + +### Platforms + +Current release has been tested on + +* Cortex M33 based SSE-200 system - + * [FPGA running on MPS2 board.](https://developer.arm.com/products/system-design/development-boards/cortex-m-prototyping-systems/mps2) + * [Fast model FVP_MPS2_AEMv8M.](https://developer.arm.com/products/system-design/fixed-virtual-platforms) + +## Getting Started + +### Prerequisite +Trusted Firmware M provides a reference implementation of PSA specifications. +It is assumed that the reader is familiar with PSA concepts and terms. +PSA specifications are currently not available in the public domain. + +The current TF-M implementation specifically targets TrustZone for ARMv8-M so a +good understanding of the v8-M architecture is also necessary. +A good place to get started with ARMv8-M is +[develeper.arm.com](https://developer.arm.com/technologies/trustzone). + + +### Really getting started + +Trusted Firmware M source code is available on +[github](https://github.com/ARM-software/trusted-firmware-m) + +To build & run TF-M +- Follow the + [SW requirements guide](docs/user_guides/tfm_sw_requirement.md) + to set up your environment +- Follow the + [Build instructions](docs/user_guides/tfm_build_instruction.md) + to compile and build the TF-M source +- Follow the + [User guide](docs/user_guides/tfm_user_guide.md) +for information on running the example + +To port TF-M to a another system or OS, follow the +[OS Integration Guide](docs/user_guides/tfm_integration_guide.md) + +Please also see the [glossary](glossary.md) of terms used in the project. + +[Contributing Guidelines](contributing.md) contains guidance on how to +contribute to this project. + +Further documents can be found in the [docs](docs) folder. + +## Feedback and support + +For this early access release, feedback is requested via email to +[support-trustedfirmware-m@arm.com ](support-trustedfirmware-m@arm.com). + + +## Version history + +| Version | Date | Description | +|---------|------|-------------| +| 0.1 | 2017-12-15 | Early Access Release | + + +-------------- + +*Copyright (c) 2017, Arm Limited. All rights reserved.*