Import 80d60e7 from yoctoproject.org meta-arm

To support ARMv8 SoCs.

meta-arm has several patch files.  Since they are maintained by the
upstream meta-arm community, add meta-arm to the ignore list in
run-repotest.

Change-Id: Ia87a2e947bbabd347d256eccc47a343e1c885479
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>

10 files changed, 668 insertions, 0 deletions

diff --git a/meta-arm/meta-arm-bsp/documentation/corstone500.md b/meta-arm/meta-arm-bsp/documentation/corstone500.md
new file mode 100644
index 0000000000..0f019611b7
--- /dev/null
+++ b/meta-arm/meta-arm-bsp/documentation/corstone500.md
@@ -0,0 +1,28 @@
+# Corstone-500 Platform Support in meta-arm-bsp
+
+## Howto Build and Run
+
+### Configuration:
+
+Use the kas
+
+### Build:
+
+``bash$ kas build kas/corstone500.yml
+
+### Run:
+
+Building using kas should have fetch the Fixed Virtual Platform for this
+platform and installed at:
+
+build/tmp/sysroots-components/x86_64/fvp-corstone500-native/usr/bin/./FVP_Corstone-500
+
+with this in place is possible to launch the FVP using the runfvp inside the
+scripts directory:
+
+cd scripts
+
+./runfvp ../build/tmp/deploy/images/corstone500/core-image-minimal-corstone500.fvpconf --console
+
+this will output the console in the launching terminal
+
diff --git a/meta-arm/meta-arm-bsp/documentation/fvp-base-arm32.md b/meta-arm/meta-arm-bsp/documentation/fvp-base-arm32.md
new file mode 100644
index 0000000000..54408b0d86
--- /dev/null
+++ b/meta-arm/meta-arm-bsp/documentation/fvp-base-arm32.md
@@ -0,0 +1,61 @@
+# Armv7-A Base Platform FVP Support in meta-arm-bsp
+
+## How to build and run
+
+### Configuration:
+In the local.conf file, MACHINE should be set as follows:
+MACHINE ?= "fvp-base-arm32"
+
+### Build:
+```bash$ bitbake core-image-minimal```
+
+### Run:
+To Run the Fixed Virtual Platform simulation tool you must download "Armv8-A
+Base Platform FVP" from Arm developer (This might require the user to
+register) from this address:
+https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms
+and install it on your host PC.
+
+Fast Models Fixed Virtual Platforms (FVP) Reference Guide:
+https://developer.arm.com/docs/100966/latest
+
+Armv8‑A Foundation Platform User Guide:
+https://developer.arm.com/docs/100961/latest/
+
+
+Once done, do the following to build and run an image:
+```bash$ bitbake core-image-minimal```
+```bash$ export YOCTO_DEPLOY_IMGS_DIR="<yocto-build-dir/tmp/deploy/images/fvp-base-arm32>"```
+```bash$ cd <path-to-Base_RevC_AEMv8A_pkg-dir/models/Linux64_GCC-X.X/>```
+```
+bash$ ./FVP_Base_RevC-2xAEMv8A -C bp.virtio_net.enabled=1 \
+         -C cache_state_modelled=0 \
+         -C bp.secureflashloader.fname=${YOCTO_DEPLOY_IMGS_DIR}/bl1-fvp.bin \
+         -C bp.flashloader0.fname=${YOCTO_DEPLOY_IMGS_DIR}/fip-fvp.bin \
+         --data cluster0.cpu0=${YOCTO_DEPLOY_IMGS_DIR}/Image@0x80080000 \
+         -C bp.virtioblockdevice.image_path=${YOCTO_DEPLOY_IMGS_DIR}/core-image-minimal-fvp-base-arm32.wic \
+         -C cluster0.cpu0.CONFIG64=0 \
+         -C cluster0.cpu1.CONFIG64=0 \
+         -C cluster0.cpu2.CONFIG64=0 \
+         -C cluster0.cpu3.CONFIG64=0 \
+         -C cluster1.cpu0.CONFIG64=0 \
+         -C cluster1.cpu1.CONFIG64=0 \
+         -C cluster1.cpu2.CONFIG64=0 \
+         -C cluster1.cpu3.CONFIG64=0 \
+
+```
+
+
+If you have built a configuration without a ramdisk, you can use the following
+command in U-boot to start Linux:
+```fvp32# bootz 0x80080000 - 0x82000000```
+
+## Devices supported in the kernel
+- serial
+- virtio disk
+- network
+- watchdog
+- rtc
+
+## Devices not supported or not functional
+None
diff --git a/meta-arm/meta-arm-bsp/documentation/fvp-base.md b/meta-arm/meta-arm-bsp/documentation/fvp-base.md
new file mode 100644
index 0000000000..b0026de488
--- /dev/null
+++ b/meta-arm/meta-arm-bsp/documentation/fvp-base.md
@@ -0,0 +1,53 @@
+# Armv8-A Base Platform FVP Support in meta-arm-bsp
+
+## Howto Build and Run
+
+### Configuration:
+In the local.conf file, MACHINE should be set as follow:
+MACHINE ?= "fvp-base"
+
+### Build:
+```bash$ bitbake core-image-minimal```
+
+### Run:
+To Run the Fixed Virtual Platform simulation tool you must download "Armv8-A
+Base Platform FVP" from Arm developer (This might require the user to
+register) from this address:
+https://developer.arm.com/tools-and-software/simulation-models/fixed-virtual-platforms
+and install it on your host PC.
+
+Fast Models Fixed Virtual Platforms (FVP) Reference Guide:
+https://developer.arm.com/docs/100966/latest
+
+Armv8‑A Foundation Platform User Guide:
+https://developer.arm.com/docs/100961/latest/
+
+
+Once done, do the following to build and run an image:
+```bash$ bitbake core-image-minimal```
+```bash$ export YOCTO_DEPLOY_IMGS_DIR="<yocto-build-dir/tmp/deploy/images/fvp-base>"```
+```bash$ cd <path-to-Base_RevC_AEMv8A_pkg-dir/models/Linux64_GCC-X.X/>```
+```
+bash$ ./FVP_Base_RevC-2xAEMv8A -C bp.virtio_net.enabled=1 \
+         -C cache_state_modelled=0 \
+         -C bp.secureflashloader.fname=${YOCTO_DEPLOY_IMGS_DIR}/bl1-fvp.bin \
+         -C bp.flashloader0.fname=${YOCTO_DEPLOY_IMGS_DIR}/fip-fvp.bin \
+         --data cluster0.cpu0=${YOCTO_DEPLOY_IMGS_DIR}/Image@0x80080000 \
+         --data cluster0.cpu0=${YOCTO_DEPLOY_IMGS_DIR}/fvp-base-gicv3-psci-custom.dtb@0x83000000 \
+         -C bp.virtioblockdevice.image_path=${YOCTO_DEPLOY_IMGS_DIR}/core-image-minimal-fvp-base.wic
+```
+
+
+If you have built a configuration without a ramdisk, you can use the following
+command in U-boot to start Linux:
+```VExpress64# booti 0x80080000 - 0x83000000```
+
+## Devices supported in the kernel
+- serial
+- virtio disk
+- network
+- watchdog
+- rtc
+
+## Devices not supported or not functional
+None
diff --git a/meta-arm/meta-arm-bsp/documentation/fvp-baser-aemv8r64.md b/meta-arm/meta-arm-bsp/documentation/fvp-baser-aemv8r64.md
new file mode 100644
index 0000000000..6986afd3a7
--- /dev/null
+++ b/meta-arm/meta-arm-bsp/documentation/fvp-baser-aemv8r64.md
@@ -0,0 +1,264 @@
+Armv8-R AArch64 AEM FVP Support in meta-arm-bsp
+===============================================
+
+Overview
+--------
+
+Fixed Virtual Platforms (FVP) are complete simulations of an Arm system,
+including processor, memory and peripherals. These are set out in a
+"programmer's view", which gives you a comprehensive model on which to build
+and test your software.
+
+The Armv8-R AEM FVP is a free of charge Armv8-R Fixed Virtual Platform. It
+supports the latest Armv8-R feature set.
+
+This BSP implements a reference stack for the AArch64 support in the R-class
+first announced with the Cortex-R82 processor:
+https://developer.arm.com/ip-products/processors/cortex-r/cortex-r82
+
+Fast Models Fixed Virtual Platforms (FVP) Reference Guide:
+https://developer.arm.com/docs/100966/latest
+
+
+BSP Support
+-----------
+
+The fvp-baser-aemv8r64 Yocto MACHINE supports the following BSP components,
+where either a standard or Real-Time Linux kernel (PREEMPT\_RT) can be built
+and run:
+
+ - FVP_Base_AEMv8R: v11.18.16
+ - boot-wrapper-aarch64: provides PSCI support
+ - U-Boot: v2022.04 - provides UEFI services
+ - Linux kernel: linux-yocto-5.15
+ - Linux kernel with PREEMPT\_RT support: linux-yocto-rt-5.15
+
+Note that the Real-Time Linux kernel (PREEMPT\_RT) does not use the real-time
+architectural extensions of the Armv8-R feature set.
+
+High-Level Architecture
+-----------------------
+
+The diagram below shows the current boot flow:
+
+    +---------------------------------------------------------------+
+    |                         Linux kernel                          |
+    +---------------------------------------------------------------+
+               /|\                                     /|\
+                |                                       |
+                | UEFI services                         |
+                |                         PSCI services |
+               \|/                                      |
+        +----------------+                              |     S-EL1
+    ----|     U-Boot     |------------------------------|-----------
+        +----------------+                              |     S-EL2
+               /|\                                      |
+                |                                       |
+                |                                       |
+                |                                       |
+    +--------------------------------------------------\|/----------+
+    |                        +----------------+ +----------------+  |
+    |  boot-wrapper-aarch64  |  Device tree   | |  PSCI handler  |  |
+    |                        +----------------+ +----------------+  |
+    +---------------------------------------------------------------+
+
+
+The firmware binary (generated as `linux-system.axf`) includes
+boot-wrapper-aarch64, the flattened device tree and U-Boot. U-Boot is configured
+to automatically detect a virtio block device and boot the UEFI payload at the
+path `/efi/boot/bootaa64.efi`. Using the standard build, the first partition
+contains a Grub image at this path, which boots the Linux kernel at `/Image` on
+the same partition. The second partition of the image contains the Linux root
+file system.
+
+There is no EL3 or non-secure world in the Armv8-R AArch64 architecture, so the
+reset vector starts boot-wrapper-aarch64 at S-EL2. Boot-wrapper-aarch64 is
+compiled with the `--enable-keep-el` flag, which causes it to boot U-Boot at
+S-EL2 too. U-Boot is compiled with the `CONFIG_ARMV8_SWITCH_TO_EL1` flag, which
+causes it to switch to S-EL1 before booting Linux.
+
+The bundled device tree is passed to U-Boot via register x0. U-Boot passes the
+same device tree to Linux via the UEFI system table.
+
+Power state management is provided by PSCI services in boot-wrapper-aarch64.
+Linux accesses the PSCI handler via HVC calls to S-EL2. U-Boot has been patched
+to prevent it from overriding the exception vector at S-EL2. The PSCI handler
+memory region is added to a `/memreserve/` node in the device tree.
+
+Please note that the final firmware architecture for the fvp-baser-aemv8r64 is
+not yet stabilized. The patches in this layer are provided for development and
+evaluation purposes only, and should not be used in production firmware.
+
+Quick start: Howto Build and Run
+--------------------------------
+
+### Host environment setup
+The following instructions have been tested on hosts running Ubuntu 18.04 and
+Ubuntu 20.04.
+Install the required packages for the build host:
+https://docs.yoctoproject.org/singleindex.html#required-packages-for-the-build-host
+
+Kas is a setup tool for bitbake based projects. The minimal supported version
+is 3.0, install it like so:
+
+    pip3 install --user --upgrade kas
+
+For more details on kas, see https://kas.readthedocs.io/.
+
+To build the images for the fvp-baser-aemv8r64 machine, you also need to accept
+the EULA at
+https://developer.arm.com/downloads/-/arm-ecosystem-fvps/eula
+by setting the following environment variable:
+
+    FVP_BASE_R_ARM_EULA_ACCEPT="True"
+
+**Note:** The host machine should have at least 50 GBytes of free disk space
+for the next steps to work correctly.
+
+### Fetch sources
+To fetch and build the ongoing development of the software stack follow the
+instructions on this document.
+
+To fetch and build the version 1 (single core) find instructions at https://community.arm.com/developer/tools-software/oss-platforms/w/docs/633/release-1-single-core
+
+To fetch and build the version 2 (linux smp) find instructions at https://community.arm.com/developer/tools-software/oss-platforms/w/docs/634/release-2---smp
+
+Fetch the meta-arm repository into a build directory:
+
+    mkdir -p ~/fvp-baser-aemv8r64-build
+    cd ~/fvp-baser-aemv8r64-build
+    git clone https://git.yoctoproject.org/git/meta-arm
+
+
+### Build
+Building with the standard Linux kernel:
+
+    cd ~/fvp-baser-aemv8r64-build
+    export FVP_BASE_R_ARM_EULA_ACCEPT="True"
+    kas build meta-arm/kas/fvp-baser-aemv8r64-bsp.yml
+
+Building with the Real-Time Linux kernel (PREEMPT\_RT):
+
+    cd ~/fvp-baser-aemv8r64-build
+    export FVP_BASE_R_ARM_EULA_ACCEPT="True"
+    kas build meta-arm/kas/fvp-baser-aemv8r64-rt-bsp.yml
+
+### Run
+To run an image after the build is done with the standard Linux kernel:
+
+    kas shell --keep-config-unchanged \
+       meta-arm/kas/fvp-baser-aemv8r64-bsp.yml \
+           --command "../layers/meta-arm/scripts/runfvp \
+           --console "
+
+To run an image after the build is done with the Real-Time Linux kernel
+(PREEMPT\_RT):
+
+    kas shell --keep-config-unchanged \
+       meta-arm/kas/fvp-baser-aemv8r64-rt-bsp.yml \
+           --command "../layers/meta-arm/scripts/runfvp \
+           --console "
+
+**Note:** The terminal console login is `root` without password.
+
+To finish the fvp emulation, you need to close the telnet session:
+
+ - Escape to telnet console with ``ctrl+]``.
+ - Run ``quit`` to close the session.
+
+### Networking
+The FVP is configured by default to use "user-mode networking", which simulates
+an IP router and DHCP server to avoid additional host dependencies and
+networking configuration. Outbound connections work automatically, e.g. by
+running:
+
+    wget www.arm.com
+
+Inbound connections require an explicit port mapping from the host. By default,
+port 8022 on the host is mapped to port 22 on the FVP, so that the following
+command will connect to an ssh server running on the FVP:
+
+    ssh root@localhost -p 8022
+
+Note that user-mode networking does not support ICMP, so `ping` will not work.
+For more information about user-mode networking, please see
+https://developer.arm.com/documentation/100964/1117/Introduction-to-Fast-Models/User-mode-networking?lang=en
+
+### File sharing between host and fvp
+It is possible to share a directory between the host machine and the fvp using
+the virtio P9 device component included in the kernel. To do so, create a
+directory to be mounted from the host machine:
+
+    mkdir /path/to/host-mount-dir
+
+Then, add the following parameter containing the path to the directory when
+launching the model:
+
+    --parameter 'bp.virtiop9device.root_path=/path/to/host-mount-dir'
+
+e.g. for the standard Linux kernel:
+
+    kas shell --keep-config-unchanged \
+       meta-arm/kas/fvp-baser-aemv8r64-bsp.yml \
+           --command "../layers/meta-arm/scripts/runfvp \
+           --console -- --parameter \
+           'bp.virtiop9device.root_path=/path/to/host-mount-dir'"
+
+Once you are logged into the fvp, the host directory can be mounted in a
+directory on the model using the following command:
+
+    mount -t 9p -o trans=virtio,version=9p2000.L FM /path/to/fvp-mount-dir
+
+Devices supported in the kernel
+-------------------------------
+
+- serial
+- virtio 9p
+- virtio disk
+- virtio network
+- virtio rng
+- watchdog
+- rtc
+
+Known Issues and Limitations
+----------------------------
+
+- Only PSCI CPU\_ON and CPU\_OFF functions are supported
+- Linux kernel does not support booting from secure EL2 on Armv8-R AArch64
+- Linux KVM does not support Armv8-R AArch64
+- Device DMA memory cache-coherence issue: the FVP `cache_state_modelled`
+  parameter will affect the cache coherence behavior of peripherals’ DMA. When
+  users set `cache_state_modelled=1`, they also have to set
+  `cci400.force_on_from_start=1` to force the FVP to enable snooping on upstream
+  ports.
+
+Change Log
+----------
+- Enabled the ability for U-Boot to apply device tree overlays
+- Fixed bug in U-Boot that caused changes to the `memory` node in the device
+  tree to be ignored.
+- Added boot-wrapper-aarch64 support for booting SMP payloads at S-EL2.
+- Enabled testimage support by default.
+- Added virtio\_rng to improve random number generation.
+- Added U-Boot v2022.01 for UEFI support.
+- Updated Linux kernel version from 5.14 to 5.15 for both standard and
+  Real-Time (PREEMPT\_RT) builds.
+- Updated boot-wrapper-aarch64 revision and added support for booting U-Boot.
+- Included boot-wrapper-aarch64 PSCI services in `/memreserve/` region.
+- Fixed the counter frequency initialization in boot-wrapper-aarch64.
+- Configured the FVP to use the default RAM size of 4 Gb
+- Fixed PL011 and SP805 register sizes in the device tree.
+- Added virtio\_net User Networking mode by default and removed instructions
+  about tap networking setup.
+- Updated Linux kernel version from 5.10 to 5.14 for both standard and
+  Real-Time (PREEMPT\_RT) builds.
+- Enabled SMP support via boot-wrapper-aarch64 providing the PSCI CPU\_ON and
+  CPU\_OFF functions.
+- Introduced Armv8-R64 compiler flags.
+- Added Linux PREEMPT\_RT support via linux-yocto-rt-5.10.
+- Added support for file sharing with the host machine using Virtio P9.
+- Added support for runfvp.
+- Added performance event support (PMU) in the Linux device tree.
+- Introduced the fvp-baser-aemv8r64 machine and its BSP composed of
+  boot-wrapper-aarch64 and linux-yocto-5.10 supporting serial, virtio disk,
+  virtio network, watchdog and rtc.
diff --git a/meta-arm/meta-arm-bsp/documentation/juno.md b/meta-arm/meta-arm-bsp/documentation/juno.md
new file mode 100644
index 0000000000..69e56bc22b
--- /dev/null
+++ b/meta-arm/meta-arm-bsp/documentation/juno.md
@@ -0,0 +1,75 @@
+# Juno Development Platform Support in meta-arm-bsp
+
+## Howto Build and Run
+
+### Configuration:
+In the local.conf file, MACHINE should be set as follow:
+MACHINE ?= "juno"
+
+Juno is using a USB hard drive for root filesystem by default. The distribution
+used must have ```usbhost``` and ```usbgadget``` in DISTRO_FEATURES (this is
+the case in poky distribution).
+
+### Build:
+```bash$ bitbake core-image-minimal```
+
+### Update Juno SD card:
+
+The SD card content is generated during the build here:
+tmp/deploy/images/juno/firmware-image-juno.tar.gz
+
+Its content must be written on the Juno firmware SD card.
+To do this:
+- insert the sdcard of the Juno in an SD card reader and mount it:
+```bash$ sudo mount /dev/sdx1 /mnt```
+(replace sdx by the device of the SD card)
+
+- erase its content and put the new one:
+```bash$ sudo rm -rf /mnt/*```
+```bash$ sudo tar --no-same-owner -xzf tmp/deploy/images/juno/firmware-image-juno.tar.gz -C /mnt/```
+```bash$ sudo umount /mnt```
+
+- reinsert the SD card in the Juno board
+
+### Create an USB hard drive:
+
+Linux root file system should be stored on the second partition of an USB
+drive that must be plugged on the Juno Platform.
+
+This partition should be initialized with the content of the filesystem
+generated by yocto that you can find here:
+tmp/deploy/images/juno/core-image-minimal-juno.tar.bz2
+
+To do this
+- Format a USB disk, create two primary partitions (ext4).
+- mount the secondary partition
+- untar tmp/deploy/images/juno/core-image-minimal-juno.tar.bz2 on to the
+  secondary partition.
+
+### Run:
+You must insert the SD card and the USB drive and power-on the Juno board.
+The console should be available on the second serial line:
+screen -L /dev/tty.usbserial 115200
+
+On the first boot the images will be flashed which can take some time.
+
+## Devices supported in the kernel
+- serial
+- usb
+- network
+- watchdog
+- rtc
+- mmc
+
+### Untested:
+- i2c
+- dma
+- pci
+- sata
+- sound
+
+## Devices not supported or not functional
+- framebuffer: not functional
+    The HDMI is not properly detected.
+- GPU (no user land libraries).
+    The mali-midgard-kernel can be used to have a kernel driver
diff --git a/meta-arm/meta-arm-bsp/documentation/musca-b1.md b/meta-arm/meta-arm-bsp/documentation/musca-b1.md
new file mode 100644
index 0000000000..a9af03f517
--- /dev/null
+++ b/meta-arm/meta-arm-bsp/documentation/musca-b1.md
@@ -0,0 +1,26 @@
+# Musca B1
+
+## Overview
+For a description of the hardware, go to
+https://developer.arm.com/tools-and-software/development-boards/iot-test-chips-and-boards/musca-b-test-chip-board
+
+For current supported hardware by Zephyr, go to
+https://docs.zephyrproject.org/2.3.0/boards/arm/v2m_musca/doc/index.html
+
+For emulated hardware, go to
+https://www.qemu.org/docs/master/system/arm/musca.html
+
+## Building
+In the local.conf file, MACHINE should be set as follows:
+MACHINE ?= "musca-b1"
+
+To build for Zephyr:
+```bash$ bitbake-layers layerindex-fetch meta-zephyr```
+```bash$ bitbake zephyr-philosophers```
+
+To build the trusted firmware-m (and not Zephyr):
+```bash$ bitbake trusted-firmware-m```
+
+## Running
+To run Zephyr on the QEMU based machine, execute the following command
+```bash$ runqemu qemu-musca-b1```
diff --git a/meta-arm/meta-arm-bsp/documentation/n1sdp.md b/meta-arm/meta-arm-bsp/documentation/n1sdp.md
new file mode 100644
index 0000000000..d8661a5c34
--- /dev/null
+++ b/meta-arm/meta-arm-bsp/documentation/n1sdp.md
@@ -0,0 +1,78 @@
+# N1SDP Development Platform Support in meta-arm-bsp
+
+## Overview
+The N1SDP provides access to the Arm Neoverse N1 SoC. The N1SDP enables software development for key enterprise technology
+and general Arm software development. The N1SDP consists of the N1 board containing the N1 SoC.
+The N1 SoC contains two dual-core Arm Neoverse N1 processor clusters.
+
+The system demonstrates Arm technology in the context of Cache-Coherent Interconnect for Accelerators (CCIX) protocol by:
+
+- Running coherent traffic between the N1 SoC and an accelerator card.
+- Coherent communication between two N1 SoCs.
+- Enabling development of CCIX-enabled FPGA accelerators.
+
+Further information on N1SDP can be found at
+https://community.arm.com/developer/tools-software/oss-platforms/w/docs/458/neoverse-n1-sdp
+
+## Configuration:
+In the local.conf file, MACHINE should be set as follow:
+MACHINE ?= "n1sdp"
+
+## Building
+```bash$ bitbake core-image-minimal```
+
+## Running
+
+# Update Firmware on SD card:
+
+(*) To use n1sdp board in single chip mode, flash:
+    n1sdp-board-firmware_primary.tar.gz firmware.
+
+(*) To use n1sdp board in multi chip mode, flash:
+    n1sdp-board-firmware_primary.tar.gz firmware to primary board,
+    n1sdp-board-firmware_secondary.tar.gz firmware to secondary board.
+
+The SD card content is generated during the build here:
+  tmp/deploy/images/n1sdp/n1sdp-board-firmware_primary.tar.gz
+  tmp/deploy/images/n1sdp/n1sdp-board-firmware_secondary.tar.gz
+
+
+Its content must be written on the N1SDP firmware SD card.
+To do this:
+- insert the sdcard of the N1SDP in an SD card reader and mount it:
+```bash$ sudo mount /dev/sdx1 /mnt```
+(replace sdx by the device of the SD card)
+
+- erase its content and put the new one:
+```bash$ sudo rm -rf /mnt/*```
+```bash$ sudo tar --no-same-owner -xzf tmp/deploy/images/n1sdp/n1sdp-board-firmware_primary.tar.gz -C /mnt/```
+```bash$ sudo umount /mnt```
+
+- reinsert the SD card in the N1SDP board
+
+Firmware tarball contains iofpga configuration files, scp and uefi binaries.
+
+**NOTE**:
+If the N1SDP board was manufactured after November 2019 (Serial Number greater
+than 36253xxx), a different PMIC firmware image must be used to prevent
+potential damage to the board. More details can be found in [1].
+The `MB/HBI0316A/io_v123f.txt` file located in the microSD needs to be updated.
+To update it, set the PMIC image (300k_8c2.bin) to be used in the newer models
+by running the following commands on your host PC:
+
+    $ sudo umount /dev/sdx1
+    $ sudo mount /dev/sdx1 /mnt
+    $ sudo sed -i '/^MBPMIC: pms_0V85.bin/s/^/;/g' /mnt/MB/HBI0316A/io_v123f.txt
+    $ sudo sed -i '/^;MBPMIC: 300k_8c2.bin/s/^;//g' /mnt/MB/HBI0316A/io_v123f.txt
+    $ sudo umount /mnt
+
+# Prepare an USB hard drive:
+
+Grub boot partition is placed on first partition of the *.wic image,
+Linux root file system is placed on the second partition of the *.wic image:
+  tmp/deploy/images/n1sdp/core-image-minimal-n1sdp.wic
+
+This *.wic image should be copied to USB stick with simple dd call.
+
+
+[1]: https://community.arm.com/developer/tools-software/oss-platforms/w/docs/604/notice-potential-damage-to-n1sdp-boards-if-using-latest-firmware-release
diff --git a/meta-arm/meta-arm-bsp/documentation/tc0.md b/meta-arm/meta-arm-bsp/documentation/tc0.md
new file mode 100644
index 0000000000..2ae2592c6c
--- /dev/null
+++ b/meta-arm/meta-arm-bsp/documentation/tc0.md
@@ -0,0 +1,32 @@
+# TC0 Platform Support in meta-arm-bsp
+
+## Overview
+The Total Compute platform provides an envelope for all of Arm's latest IP and
+software solutions, optimised to work together. Further information can be
+found on the Total Compute community page:
+https://community.arm.com/developer/tools-software/oss-platforms/w/docs/606/total-compute
+
+The user guide for TC0 platform with detailed instructions for
+syncing and building the source code and running on TC0 Fixed Virtual Platform
+for poky and android distributions is available at:
+https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms.git/tree/docs/tc0/user-guide.rst
+
+## Building
+In the local.conf file, MACHINE should be set as follows:
+MACHINE = "tc0"
+
+To build the required binaries for tc0, run the commmand:
+```bash$ bitbake tc-artifacts-image```
+
+Trusted-firmware-a is the final component to be built with the rest of the
+components dependent of it, therefore building tc-artifacts-image which depends
+on trusted-firmware-a will build all the required binaries.
+
+## Running
+To run the produced binaries in a TC0 Fixed Virtual Platform please get
+the run scripts at:
+https://git.linaro.org/landing-teams/working/arm/model-scripts.git/
+
+and follow the instructions in the user-guide.rst available in:
+https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms.git/tree/docs/tc0/user-guide.rst
+
diff --git a/meta-arm/meta-arm-bsp/documentation/tc1.md b/meta-arm/meta-arm-bsp/documentation/tc1.md
new file mode 100644
index 0000000000..464f77ee0a
--- /dev/null
+++ b/meta-arm/meta-arm-bsp/documentation/tc1.md
@@ -0,0 +1,32 @@
+# TC1 Platform Support in meta-arm-bsp
+
+## Overview
+The Total Compute platform provides an envelope for all of Arm's latest IP and
+software solutions, optimised to work together. Further information can be
+found on the Total Compute community page:
+https://community.arm.com/developer/tools-software/oss-platforms/w/docs/606/total-compute
+
+The user guide for TC1 platform with detailed instructions for
+syncing and building the source code and running on TC1 Fixed Virtual Platform
+for poky and android distributions is available at:
+https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms.git/tree/docs/tc1/user-guide.rst
+
+## Building
+In the local.conf file, MACHINE should be set as follows:
+MACHINE = "tc1"
+
+To build the required binaries for tc1, run the commmand:
+```bash$ bitbake tc-artifacts-image```
+
+Trusted-firmware-a is the final component to be built with the rest of the
+components dependent of it, therefore building tc-artifacts-image which depends
+on trusted-firmware-a will build all the required binaries.
+
+## Running
+To run the produced binaries in a TC1 Fixed Virtual Platform please get
+the run scripts at:
+https://git.linaro.org/landing-teams/working/arm/model-scripts.git/
+
+and follow the instructions in the user-guide.rst available in:
+https://git.linaro.org/landing-teams/working/arm/arm-reference-platforms.git/tree/docs/tc1/user-guide.rst
+
diff --git a/meta-arm/meta-arm-bsp/documentation/template.md b/meta-arm/meta-arm-bsp/documentation/template.md
new file mode 100644
index 0000000000..7beeb5950c
--- /dev/null
+++ b/meta-arm/meta-arm-bsp/documentation/template.md
@@ -0,0 +1,19 @@
+# *Hardware Name*
+
+## Overview
+
+*Brief summary of the hardware*
+
+*Link to reference documentation*
+
+## Building
+
+*Any special steps required to build successfully beyond setting MACHINE*
+
+*For example: corstone700 needs DISTRO=poky-tiny, musca only supports TF-M*
+
+## Running
+
+*A summary of how to deploy or execute the image*
+
+*For example, an overview of the N1SDP SD structure, or FVP arguments*