Merge pull request #516 from pareenaverma/rme-cca-branch

CCA basics on an FVP LP

content/learning-paths/servers-and-cloud-computing/rme-cca-basics/_index.md

@@ -0,0 +1,37 @@
+---
+title: Learn how to create a virtual machine in a realm using Arm CCA
+
+minutes_to_complete: 120
+
+who_is_this_for: This is an introductory topic for software developers who want to learn about Arm Confidential Compute Architecture (CCA).
+
+learning_objectives:
+    - Learn about the reference software stack used in Arm CCA
+    - Build and run the software stack on an Armv-A AEM Base FVP platform with support for RME extensions
+    - Create a virtual machine in a realm running guest linux
+
+prerequisites:
+    - An aarch64 or x86_64 computer running Ubuntu 22.04. Cloud instances can be used, refer to the list of [Arm cloud service providers](/learning-paths/servers-and-cloud-computing/csp/).
+    - If you use a client application to access your computer running Ubuntu, make sure that X11 forwarding is enabled.
+
+author_primary: Pareena Verma
+
+### Tags
+skilllevels: Introductory
+subjects: Performance and Architecture
+armips:
+    - Neoverse 
+operatingsystems:
+    - Linux 
+tools_software_languages:
+    - GCC
+    - FVP
+    - RME
+    - CCA
+
+### FIXED, DO NOT MODIFY
+# ================================================================================
+weight: 1                       # _index.md always has weight of 1 to order correctly
+layout: "learningpathall"       # All files under learning paths have this same wrapper
+learning_path_main_page: "yes"  # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
+---

content/learning-paths/servers-and-cloud-computing/rme-cca-basics/_next-steps.md

@@ -0,0 +1,40 @@
+---
+# ================================================================================
+#       Edit
+# ================================================================================
+
+next_step_guidance: >
+   You now have an understanding of the Arm Confidential Compute Architecture. With a complete software stack available, you can validate your applications on an Arm FVP ahead of silicon availability.
+
+# 1-3 sentence recommendation outlining how the reader can generally keep learning about these topics, and a specific explanation of why the next step is being recommended.
+
+recommended_path: "/learning-paths/cross-platform/intrinsics"
+# Link to the next learning path being recommended(For example this could be /learning-paths/servers-and-cloud-computing/mongodb).
+
+
+# further_reading links to references related to this path. Can be:
+    # Manuals for a tool / software mentioned   (type: documentation)
+    # Blog about related topics                 (type: blog)
+    # General online references                 (type: website) 
+
+further_reading:
+    - resource:
+        title: Arm Confidential Compute Architecture
+        link: https://www.arm.com/architecture/security-features/arm-confidential-compute-architecture
+        type: website
+    - resource:
+        title: Arm Confidential Compute Architecture open source enablement
+        link: https://www.youtube.com/watch?v=JXrNkYysuXw
+        type: video
+    - resource:
+        title: Learn the architecture - Realm Management Extension
+        link: https://developer.arm.com/documentation/den0126
+        type: documentation
+
+# ================================================================================
+#       FIXED, DO NOT MODIFY
+# ================================================================================
+weight: 21                  # set to always be larger than the content in this path, and one more than 'review'
+title: "Next Steps"         # Always the same
+layout: "learningpathall"   # All files under learning paths have this same wrapper
+---

content/learning-paths/servers-and-cloud-computing/rme-cca-basics/_review.md

@@ -0,0 +1,32 @@
+---
+# ================================================================================
+#       Edit
+# ================================================================================
+
+# Always 3 questions. Should try to test the reader's knowledge, and reinforce the key points you want them to remember.
+    # question:         A one sentence question
+    # answers:          The correct answers (from 2-4 answer options only). Should be surrounded by quotes.
+    # correct_answer:   An integer indicating what answer is correct (index starts from 0)
+    # explanation:      A short (1-3 sentence) explanation of why the correct answer is correct. Can add additional context if desired
+
+
+review:
+    - questions:
+        question: >
+            Is RME supported on all Arm v8-A and Arm v9-A processors?
+        answers:
+            - "Yes"
+            - "No"
+        correct_answer: 2                
+        explanation: >
+            RME is an Armv9-A extension and is one component of the Arm Confidential Compute Architecture.
+
+
+
+# ================================================================================
+#       FIXED, DO NOT MODIFY
+# ================================================================================
+title: "Review"                 # Always the same title
+weight: 20                      # Set to always be larger than the content in this path
+layout: "learningpathall"       # All files under learning paths have this same wrapper
+---

content/learning-paths/servers-and-cloud-computing/rme-cca-basics/kconfig.patch

@@ -0,0 +1,18 @@
+diff --git a/arch/arm64/Kconfig b/arch/arm64/Kconfig
+index 0aac44a993ac..2c311236c21a
+--- a/arch/arm64/Kconfig
++++ b/arch/arm64/Kconfig
+@@ -2200,6 +2200,12 @@ config CMDLINE_FROM_BOOTLOADER
+          the boot loader doesn't provide any, the default kernel command
+          string provided in CMDLINE will be used.
+
++config CMDLINE_EXTEND
++       bool "Extend bootloader kernel arguments"
++       help
++         The command-line arguments provided by the boot loader will be
++         appended to the default kernel command string.
++
+ config CMDLINE_FORCE
+        bool "Always use the default kernel command string"
+        help
+

content/learning-paths/servers-and-cloud-computing/rme-cca-basics/rme-cca-fvp.md

@@ -0,0 +1,195 @@
+---
+# User change
+title: "Build and run the Arm CCA stack on an Arm FVP"
+
+weight: 2 # 1 is first, 2 is second, etc.
+
+# Do not modify these elements
+layout: "learningpathall"
+---
+
+
+## Before you begin
+
+You need atleast 30 GB of free disk space on your machine to build the Arm CCA reference software stack.
+
+Install the necessary packages:
+
+```console
+sudo apt update && sudo apt install git gcc telnet xterm net-tools build-essential
+```
+
+## Overview
+
+The Arm Confidential Compute Architecture (Arm CCA) enables the construction of protected execution
+environments called Realms. Realms allow lower-privileged software, such as an application or a virtual machine to
+protect its content and execution from attacks by higher-privileged software, such as an OS or a hypervisor. Realms provide an environment for confidential computing, without requiring the Realm owner to trust the software components that manage the resources used by the Realm.
+
+The Arm Realm Management Extension (RME) is an Arm v9-A architecture extension and defines the set of hardware features and properties that are required to comply with the Arm CCA architecture. RME introduces a new security state "Realm world", in addition to the traditional Secure and Non-Secure states.
+
+In this learning path, you will learn how to build and run the reference integration software stack for Arm CCA which demonstrates support for Arm's RME architecture feature. You will also learn how to create a realm that runs a guest linux kernel. 
+
+## Build the docker container
+
+You can build the Arm CCA reference software stack in a docker container which contains all the build dependencies. 
+Install [docker engine](/install-guides/docker/docker-engine) on your machine.
+
+Clone the repository that contains the docker container file and utility scripts:
+
+```console
+git clone --branch AEMFVP-A-RME-2023.09.29 https://git.gitlab.arm.com/arm-reference-solutions/docker.git
+```
+Build the docker container:
+
+```console
+cd docker
+./container.sh build
+```
+The script `container.sh` defines the docker file and image name used to create the container.
+
+Confirm that the docker container image was built successfully:
+
+```
+docker image list
+```
+
+The expected output is:
+
+```output
+REPOSITORY        TAG       IMAGE ID       CREATED       SIZE
+aemfvp-builder    latest    2fa7ce18f57a   7 mins ago    1.83GB
+```
+
+Create a directory on your host machine to store the software source files. Then run the container and mount this directory inside the container:
+
+```console
+mkdir ~/cca-stack
+./container.sh -v ~/cca-stack run
+```
+
+You should see the following output:
+
+```output
+Running docker image: aemfvp-builder ...
+ubuntu@ip-172-16-0-235:/$
+```
+
+You are now inside the root directory of the `aemfvp-builder` container and ready to build the software stack.
+
+## Build the reference Arm CCA software stack
+
+You can build the Arm CCA software stack in your running container using a manifest file. Inspect the [manifest file](https://git.gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-manifest/-/blob/AEMFVP-A-RME-2023.09.29/pinned-aemfvp-a-rme.xml) to view all the component repositories needed to build this reference stack. 
+
+Inside the running container, change directory into the mounted directory.
+Use the repo tool and the manifest file to download the software stack:
+
+```console
+cd ~/cca-stack
+repo init -u https://git.gitlab.arm.com/arm-reference-solutions/arm-reference-solutions-manifest.git -m pinned-aemfvp-a-rme.xml -b refs/tags/AEMFVP-A-RME-2023.09.29
+repo sync -c -j $(nproc) --fetch-submodules --force-sync --no-clone-bundle
+```
+
+Patch the linux kernel Kconfig file for arm64 targets. This patch enables extending the bootloader provided command line arguments. It is required to speed up execution of the software stack. 
+
+```console
+cd linux
+wget https://raw.githubusercontent.com/ArmDeveloperEcosystem/arm-learning-paths/main/content/learning-paths/servers-and-cloud-computing/rme-cca-basics/kconfig.patch
+git apply --ignore-space-change --whitespace=warn --inaccurate-eof -v kconfig.patch
+```
+The output should be similar to:
+
+```output
+Checking patch arch/arm64/Kconfig...
+Hunk #1 succeeded at 2260 (offset 60 lines).
+Applied patch arch/arm64/Kconfig cleanly.
+```
+Build the stack:
+
+```console
+cd ..
+./build-scripts/aemfvp-a-rme/build-test-buildroot.sh -p aemfvp-a-rme all
+```
+
+{{% notice Note %}}
+The build process can take a while to complete as it's building the entire collection of software components for the Arm CCA stack.
+{{% /notice %}}
+
+The binary executables are built in the `~/cca-stack/output/aemfvp-a-rme` directory.
+You can now exit the docker container.
+
+```console
+exit
+```
+
+## Run the software stack
+
+The binary executables built in the previous step can run on an Armv-A Base Architecture Envelop Model (AEM) FVP with support for RME extensions. AEM FVPs are fixed configuration virtual platforms of Armv8-A and  Armv9-A architectures with comprehensive system IP. You can download and run the FVP on either x64_64 or aarch64 host machines.
+
+Dependent on the architecture of your host machine, run the steps below to download and extract this FVP. Create an environment variable `MODEL` and set it to point to the FVP executable.
+
+### aarch64
+```console
+cd ~/cca-stack
+wget https://developer.arm.com/-/media/Files/downloads/ecosystem-models/FVP_Base_RevC-2xAEMvA_11.23_9_Linux64_armv8l.tgz
+tar -xvzf FVP_Base_RevC-2xAEMvA_11.23_9_Linux64_armv8l.tgz
+export MODEL=~/cca-stack/Base_RevC_AEMvA_pkg/models/Linux64_armv8l_GCC-9.3/FVP_Base_RevC-2xAEMvA
+```
+
+### x86_64
+```console
+cd ~/cca-stack
+wget https://developer.arm.com/-/media/Files/downloads/ecosystem-models/FVP_Base_RevC-2xAEMvA_11.23_9_Linux64.tgz
+tar -xvzf FVP_Base_RevC-2xAEMvA_11.23_9_Linux64.tgz
+export MODEL=~/cca-stack/Base_RevC_AEMvA_pkg/models/Linux64_GCC-9.3/FVP_Base_RevC-2xAEMvA
+```
+
+Launch the `boot.sh` script to run the binaries on the FVP:
+
+```console
+./model-scripts/aemfvp-a-rme/boot.sh -p aemfvp-a-rme shell
+```
+
+{{% notice Note %}}
+A number of `Info` and `Warning` messages will be emitted by the FVP. These can safely be ignored.
+
+If you see an error of the form `xterm: Xt error: Can't open display:`, ensure that your terminal application (e.g. `PuTTY`) has `X11 forwarding` enabled.
+{{% /notice %}}
+
+The FVP boots up with four terminal windows. 
+
+You should see the host linux kernel boot on `terminal_0`. You will be prompted to login to buildroot. Enter `root` as both the username and password.
+
+![img_1 #center](./cca-img1.png)
+
+
+`terminal_3` of the FVP is connected to the Realm Management Monitor(RMM). The RMM is the software component of Arm CCA that is responsible for the management of Realms.
+
+The output from the RMM should look like:
+
+![img_2 #center](./cca-img2.png)
+
+You have successfully booted four worlds (Root, Secure, Non-secure and Realm) on the FVP at this point. Trusted Firmware-A is running in root, RMM in realm, host linux in non-secure and Hafnium in secure. 
+
+## Create a virtual guest in a realm
+
+Guest VMs can be launched in a realm using `kvmtool` from your host linux prompt. The kernel `Image` and filesystem `realm-fs.ext4` for the realm are packaged into the buildroot host file system.
+
+```console
+lkvm run --realm -c 2 -m 256 -k /realm/Image -d /realm/realm-fs.ext4 -p earlycon
+```
+
+You should see the guest linux kernel starting to boot in a realm. This step can take several minutes.
+
+During this time, you should see output messages on the RMM console `terminal_3` that indicate that the realm is being created and activated.
+
+```console
+SMC_RMM_REC_CREATE            88232d000 8817b2000 88231a000 > RMI_SUCCESS
+SMC_RMM_REALM_ACTIVATE        8817b2000 > RMI_SUCCESS
+```
+
+After boot up, you will be prompted to login at the guest linux buildroot prompt. Use `root` again as both the username and password.
+
+![img_3 #center](./cca-img3.png)
+
+
+You have successfully created a virtual guest in a realm using the Arm CCA reference software stack.