Docs: add licensing info and user docs
Adding md files for user guides and licensing.
Using tables in md files requires breaking the 80 column limit.
Change-Id: I97a312e1adb5a36229fe2d806ccca6c7081edc85
Signed-off-by: Abhishek Pandit <Abhishek.Pandit@arm.com>
Co-Authored-By: Marc Moreno Berengue <marc.morenoberengue@arm.com>
Co-Authored-By: Gyorgy Szing <gyorgy.szing@arm.com>
Co-Authored-By: Antonio de Angelis <antonio.deangelis@arm.com>
diff --git a/contributing.md b/contributing.md
new file mode 100644
index 0000000..1b4fba5
--- /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 0000000..8201f99
--- /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 0000000..2d9d14b
--- /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 <TF-M base folder>
+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 <TF-M base folder>
+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 <TF-M base folder>
+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 0000000..e0d78ab
--- /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 0000000..182fe74
--- /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=<DS-5_PATH>/sw/ARMCompiler6.7.1/bin:$PATH
+export ARM_TOOL_VARIANT="ult"
+export ARM_PRODUCT_PATH="<DS-5_PATH>/sw/mappings"
+export ARMLMD_LICENSE_FILE="<LICENSE_FILE_PATH>"
+~~~
+To import cmake in your bash shell console:
+~~~
+export PATH=<CMAKE_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/<DS-5 path>/sw/ARMCompiler6.7.1/bin":$PATH
+export ARM_PRODUCT_PATH="C:/<DS-5 path>/sw/mappings"
+~~~
+
+**Keil**
+~~~
+export PATH="/cygdrive/c/<uVison path>/ARM/ARMCLANG/bin":$PATH
+export ARM_PRODUCT_PATH="C:/<uVison path>/ARM/sw/mappings"
+~~~
+
+**Shared settings**
+~~~
+export ARM_TOOL_VARIANT="ult"
+export ARMLMD_LICENSE_FILE="<LICENSE_FILE_PATH>"
+~~~
+To import cmake in your bash shell console:
+~~~
+export PATH=/cygdrive/c/<CMAKE_PATH>/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 0000000..8a31845
--- /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
+
+```
+<DS5_PATH>/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=<build_dir>/app/tfm_ns.axf \
+--application cpu0=<build_dir>/app/secure_fw/tfm_s.axf
+```
+#### Regression tests
+```
+<DS5_PATH>/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=<build_dir>/app/tfm_ns.axf \
+--application cpu0=<build_dir>/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
+`<MPS2 device name>/MB/HBI0263<board revision letter>/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 <MPS2 device name>/SOFTWARE/
+2. Open <MPS2 device name>/MB/HBI0263<board revision letter>/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 <MPS2 device name>/MB/HBI0263C/AN521/images.txt
+5. Unmount/eject the <MPS2 device name> 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 0000000..dc9bb8f
--- /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 0000000..f794972
--- /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 0000000..ed59e0c
--- /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 0000000..4c8f2fe
--- /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 0000000..6e75bc5
--- /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 0000000..7385827
--- /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.*