Platform: RSE: Rename RSE platform files
Renames all 'rss' files to 'rse'. Avoids changes unrelated to moving
files in this commit to keep to commit history clearer.
Signed-off-by: Jamie Fox <jamie.fox@arm.com>
Change-Id: I321aa2cdff6117c869a7128d2866207efd9b3309
diff --git a/docs/platform/arm/rse/readme.rst b/docs/platform/arm/rse/readme.rst
new file mode 100644
index 0000000..0052f4d
--- /dev/null
+++ b/docs/platform/arm/rse/readme.rst
@@ -0,0 +1,189 @@
+Runtime Security Engine (RSE)
+=============================
+
+Introduction
+------------
+
+Runtime Security Engine (RSE) is an Arm subsystem that provides a reference
+implementation of the HES Host in the
+`Arm Confidential Compute Architecture (CCA) <https://www.arm.com/architecture/security-features/arm-confidential-compute-architecture>`_.
+It is designed to be integrated into A-profile compute subsystems that implement
+Arm CCA, where it serves as the Root of Trust.
+
+RSE initially boots from immutable code (BL1_1) in its internal ROM, before
+jumping to BL1_2, which is provisioned and hash-locked in RSE OTP. The updatable
+MCUBoot BL2 boot stage is loaded from host system flash into RSE SRAM, where it
+is authenticated. BL2 loads and authenticates the TF-M runtime into RSE SRAM
+from host flash. BL2 is also responsible for loading initial boot code into
+other subsystems within the host.
+
+The RSE platform port supports the TF-M Crypto, TF-M Initial Attestation,
+Measured Boot and TF-M Platform services along with the corresponding
+regression tests. It supports the IPC model in multi-core topology with
+Isolation Level 1 and 2.
+
+Building TF-M
+-------------
+
+Follow the instructions in :doc:`Build instructions </building/tfm_build_instruction>`.
+Build TF-M with platform name: `arm/rse/<rse platform name>`
+
+For example for building RSE for Total Compute platforms:
+``-DTFM_PLATFORM=arm/rse/tc``
+
+Signing host images
+-------------------
+
+RSE BL2 can load boot images into other subsystems within the host system. It
+expects images to be signed, with the signatures attached to the images in the
+MCUBoot metadata format.
+
+The `imgtool Python package <https://pypi.org/project/imgtool/>`_ can be used to
+sign images in the required format. To sign a host image using the development
+key distributed with TF-M, use the following command::
+
+ imgtool sign \
+ -k <TF-M base directory>/bl2/ext/mcuboot/root-RSA-3072.pem \
+ --public-key-format full \
+ --max-align 8 \
+ --align 1 \
+ -v "0.0.1" \
+ -s 1 \
+ -H 0x2000 \
+ --pad-header \
+ -S 0x80000 \
+ --pad \
+ -L <load address> \
+ <binary infile> \
+ <signed binary outfile>
+
+The ``load address`` is the logical address in the RSE memory map to which BL2
+will load the image. RSE FW expects the first host image to be loaded to address
+``0x70000000`` (the beginning of the RSE ATU host access region), and each
+subsequent host image to be loaded at an offset of ``0x1000000`` from the
+previous image. The RSE ATU should be configured to map these logical addresses
+to the physical addresses in the host system that the images need to be loaded
+to.
+
+For more information on the ``imgtool`` parameters, see the MCUBoot
+`imgtool documentation <https://docs.mcuboot.com/imgtool.html>`_.
+
+.. warning::
+
+ The TF-M development key must never be used in production. To generate a
+ production key, follow the imgtool documentation.
+
+Running the code
+----------------
+
+To run the built images, first the ROM image must be created from the bl1_1
+binary and the ROM DMA Initial Command Sequence (ICS).::
+
+ srec_cat \
+ bl1_1.bin -Binary -offset 0x0 \
+ rom_dma_ics.bin -Binary -offset 0x1F000 \
+ -o rom.bin -Binary
+
+Then, the flash image must be created by concatenating the images that are
+output from the build. To create the flash image, the following ``fiptool``
+command should be run. ``fiptool`` documentation can be found `here
+<https://trustedfirmware-a.readthedocs.io/en/latest/getting_started/tools-build.html?highlight=fiptool#building-and-using-the-fip-tool>`_.
+Note that an up-to-date fiptool that supports the RSE UUIDs must be used.::
+
+ fiptool create \
+ --align 8192 --rss-bl2 bl2_signed.bin \
+ --align 8192 --rss-ns tfm_ns_signed.bin \
+ --align 8192 --rss-s tfm_s_signed.bin \
+ --align 8192 --rss-scp-bl1 <signed Host SCP BL1 image> \
+ --align 8192 --rss-ap-bl1 <signed Host AP BL1 image> \
+ fip.bin
+
+If you already have a ``fip.bin`` containing host firmware images, RSE FIP
+images can be patched in::
+
+ fiptool update --align 8192 --rss-bl2 bl2_signed.bin fip.bin
+ fiptool update --align 8192 --rss-ns tfm_ns.bin fip.bin
+ fiptool update --align 8192 --rss-s tfm_s.bin fip.bin
+
+If XIP mode is enabled, the following ``fiptool`` command should be run to
+create the flash image::
+
+ fiptool create \
+ --align 8192 --rss-bl2 bl2_signed.bin \
+ --align 8192 --rss-ns tfm_ns_encrypted.bin \
+ --align 8192 --rss-s tfm_s_encrypted.bin \
+ --align 8192 --rss-sic-tables-ns tfm_ns_sic_tables_signed.bin \
+ --align 8192 --rss-sic-tables-s tfm_s_sic_tables_signed.bin \
+ --align 8192 --rss-scp-bl1 <signed Host SCP BL1 image> \
+ --align 8192 --rss-ap-bl1 <signed Host AP BL1 image> \
+ fip.bin
+
+Once the FIP is prepared, a host flash image can be created using ``srec_cat``::
+
+ srec_cat \
+ fip.bin -Binary -offset 0x0 \
+ -o host_flash.bin -Binary
+
+If GPT support is enabled, and a host ``fip.bin`` and ``fip_gpt.bin`` has been
+obtained, RSE images can be inserted by first patching the host FIP and then
+inserting that patched FIP into the GPT image::
+
+ sector_size=$(gdisk -l fip_gpt.bin | grep -i "sector size (logical):" | \
+ sed 's/.*logical): \([0-9]*\) bytes/\1/')
+
+ fip_label=" FIP_A$"
+ fip_start_sector=$(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $2}')
+ fip_sector_am=$(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $3 - $2}')
+
+ dd if=fip.bin of=fip_gpt.bin bs=$sector_size seek=$fip_start_sector \
+ count=$fip_sector_am conv=notrunc
+
+ fip_label = " FIP_B$"
+ fip_start_sector = $(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $2}')
+ fip_sector_am = $(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $3 - $2}')
+
+ dd if=fip.bin of=fip_gpt.bin bs=$sector_size seek=$fip_start_sector \
+ count=$fip_sector_am conv=notrunc
+
+To patch a ``fip_gpt.bin`` without having an initial ``fip.bin``, the FIP can be
+extracted from the GPT image using the following commands (and can then be
+patched and reinserted using the above commands)::
+
+ sector_size=$(gdisk -l fip_gpt.bin | grep -i "sector size (logical):" | \
+ sed 's/.*logical): \([0-9]*\) bytes/\1/')
+
+ fip_label=" FIP_A$"
+ fip_start_sector=$(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $2}')
+ fip_sector_am=$(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $3 - $2}')
+
+ dd if=fip_gpt.bin of=fip.bin bs=$sector_size skip=$fip_start_sector \
+ count=$fip_sector_am conv=notrunc
+
+Once the ``fip_gpt.bin`` is prepared, it is placed at the base of the host flash
+image::
+
+ srec_cat \
+ fip_gpt.bin -Binary -offset 0x0 \
+ -o host_flash.bin -Binary
+
+The RSE ROM binary should be placed in RSE ROM at ``0x11000000`` and the host
+flash binary should be placed at the base of the host flash. For the TC
+platform, this is at ``0x80000000``.
+
+The RSE OTP must be provisioned. On a development platform with
+``TFM_DUMMY_PROVISIONING`` enabled, BL1_1 expects provisioning bundles to be
+preloaded into SRAM. Preload ``encrypted_cm_provisioning_bundle_0.bin`` to the
+base of VM0, and ``encrypted_dm_provisioning_bundle.bin`` to the base of VM1.
+
+If ``TFM_DUMMY_PROVISIONING`` is disabled and provisioning is required, then
+BL1_1 will first wait for the TP mode to be set by a debugger (setting the
+``tp_mode`` variable in the current stack frame is easiest). BL1_1 will then
+wait for provisioning bundles to be loaded to VM0 and VM1 in the same way as
+when ``TFM_DUMMY_PROVISIONING`` is enabled, except that it will not
+automatically perform the reset once each provisioning state is complete. For
+more details about provisioning flows, see
+:doc:`RSE provisioning </platform/arm/rse/rse_provisioning>`.
+
+--------------
+
+*Copyright (c) 2022-2023, Arm Limited. All rights reserved.*