Merge pull request #574 from RonanSynnottArm/cca-rme

CCA intro re-push

content/learning-paths/cross-platform/cca_rme/_index.md

@@ -0,0 +1,49 @@
+---
+title: Get started with the Realms Management Extension (RME)
+
+minutes_to_complete: 30
+
+who_is_this_for: This is an introductory topic for developers interested in learning the concepts of the Realms Management Extension and Arm Confidential Compute Architecture.
+
+learning_objectives: 
+    - Understand the Arm Confidential Compute Architecture
+    - Understand simple bare-metal example as provided with Arm Development Studio
+
+prerequisites:
+    - Some understanding of the Arm architecture
+    - Arm Development Studio installation
+
+author_primary: Ronan Synnott
+
+### Tags
+skilllevels: Introductory
+subjects: Performance and Architecture
+armips:
+    - Neoverse
+    - Cortex-A
+    - Cortex-X
+    - Armv9-A
+
+operatingsystems:
+    - Bare-metal
+    - Linux
+    - Android
+
+tools_software_languages:
+    - Coding
+    - Trusted Firmware
+    - Arm Development Studio
+
+### Cross-platform metadata only
+shared_path: true
+shared_between:
+    - servers-and-cloud-computing
+    - laptops-and-desktops
+    - smartphones-and-mobile
+
+### 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/cross-platform/cca_rme/_next-steps.md

@@ -0,0 +1,40 @@
+---
+# ================================================================================
+#       Edit
+# ================================================================================
+
+next_step_guidance: >
+   You now have an understanding of the Arm Confidential Compute Architecture infrastructure. You can now explore a complete software stack implementing CCA.
+
+# 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/content/servers-and-cloud-computing/rme-cca-basics"
+# 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/cross-platform/cca_rme/_review.md

@@ -0,0 +1,41 @@
+---
+# ================================================================================
+#       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: >
+            Arm Confidential Compute Architecture (CCA) is available on all Arm devices
+        answers:
+            - "True"
+            - "False"
+        correct_answer: 2
+        explanation: >
+            CCA requires the Realm Management Extension (RME) of Armv9-A architecture, as well as support within the software stack running on the device.
+    - questions:
+        question: >
+            The secure monitor would run in which world?
+        answers:
+            - "Normal"
+            - "Secure"
+            - "Root"
+            - "Realm"
+        correct_answer: 3
+        explanation: >
+            The Secure Monitor runs in Root world. The Hypervisor runs in Normal world.
+
+# ================================================================================
+#       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/cross-platform/cca_rme/bare-metal.md

@@ -0,0 +1,164 @@
+---
+# User change
+title: Bare-metal example
+
+weight: 3 # 1 is first, 2 is second, etc.
+
+# Do not modify these elements
+layout: "learningpathall"
+---
+Consider a bare-metal example that illustrates the `Realm Management Extension` (`RME`) architectural feature of an Arm processor necessary to implement a CCA system.
+
+The full example is provided with Arm Development Studio, 2023.0 and later. It executes on the `Arm Architecture Envelope Model (AEM)` Fixed Virtual Platform (FVP), supplied with Development Studio.
+
+The example also illustrates features of the Arm Debugger to enable you to debug such a system.
+
+## Import the example
+
+Open the Arm Development Studio IDE. Navigate to `File` > `Import...` > `Arm Development Studio` > `Examples & Programming Libraries` > `Examples` > `Armv9 Bare-Metal`, and select the `RME` example. Using the text filter at the top of the pane can help locate the example. Click `Finish` to import.
+
+Alternatively extract the example on the command line from the `<install_dir>\examples\Bare-metal_examples_Armv9.zip` archive. For interactive debug (see later) using the IDE is recommended.
+
+Though the project is provided pre-compiled, you can also rebuild with the `Build` icon, or the `make` command from the command line.
+
+See the supplied `readme.html` for more information.
+
+## Load the example
+
+There is a supplied `gpc_el10_rl_FVP.launch` debug connection which has all necessary settings configured.
+
+Double-click on the `.launch` file to open.
+
+The `Arm Architecture Envelope Model (AEM)` is a generic Arm implementation, which can be configured appropriately to enable Arm architectural features.
+
+The model is launched with appropriate settings to implement full RME support, including:
+```command
+-C cluster0.has_arm_v9-0=1 -C cluster0.rme_support_level=2 -C cluster0.has_16k_granule=1
+```
+
+Click `Debug` to launch the FVP and load the image.
+
+Execution can be controlled by the `Debug Control` pane icon bar (eg `Step Instruction` ), the command line (`stepi`), or short-cut keys (`F5`).
+
+## Understand the example
+
+
+### EL3
+
+The example sets up a `Granule Protection Table` (`GPT`) that defines the access permissions of various 16KB `granules` of memory. These granules are the smallest memory size that can be individually managed.
+
+These settings are made at `EL3` running in `Root world`, and so will be invisible to any application executing within a Realm.
+
+The location of this table is set in the [Granule Protection Table Base Register (GPTBR_EL3)](https://developer.arm.com/documentation/ddi0601/2023-06/AArch64-Registers/GPTBR-EL3--Granule-Protection-Table-Base-Register).
+
+The high level configuration is defined in the [Granule Protection Check Control Register (GPCCR_EL3)](https://developer.arm.com/documentation/ddi0601/2023-06/AArch64-Registers/GPCCR-EL3--Granule-Protection-Check-Control-Register--EL3-).
+
+Notable fields in this register are:
+
+* `Granule Protection Check Enable (GPC)` bit
+* `Level 0 GPT Size (L0GPTSZ)` field, defining the size of the level 0 entries in this table, 1GB in this example. This will further be separated in the L1 table.
+* `Physical Granule Size (PGS)` field, which in this example defines the granule size as 16KB (note that this matches the AEM configuration).
+* `Protected Physical Address Size (PPS)` field, which defines the size of the `Realms` in your system (4GB in this example).
+
+The `L0` table is at `0x80018000` and defines a flat memory translation (at `EL3`), but with access permissions defined in an `L1` table.
+
+The `L1 table` defines permissions for each 16KB granule.
+
+Use the Arm Debugger `MMU/MPU` pane to observe these attributes:
+
+![0xA0000000 #center](_images/l1gpt_0xA.png)
+
+![0x80000000 #center](_images/l1gpt_0x8.png)
+
+
+### EL2
+
+The `EL2` translation table provides an `Intermediate Physical Address` (`IPA`), which is the Physical Address (from the Realm point of view) that addresses will be translated to. This would be the role of a Hypervisor in a realistic implementation.
+
+This table is located by the [Virtualization Translation Table Base Register (VTTBR-EL2)](https://developer.arm.com/documentation/ddi0601/latest/AArch64-Registers/VTTBR-EL2--Virtualization-Translation-Table-Base-Register).
+
+The example maps `0x5xxxxxxx` to the Physical Address `0xBxxxxxxx`.
+
+![0x50000000 #center](_images/l2gpt.png)
+
+### EL1 (and EL0)
+
+The code moves to `EL1` (Realms are only defined for `EL1` and `EL0`), and translation tables mapping virtual addresses to the EL2 memory map are set up.
+
+The debugger uses [address space prefixes](https://developer.arm.com/documentation/101471/latest/Arm-Debugger-commands/Conformance-and-usage-rules-for-Arm-Debugger-commands/Address-space-prefixes) to help understand how these addresses are used.
+
+For the addresses used in the example:
+
+```command
+mmu translate EL1RL:0xD0000020
+```
+outputs:
+```output
+Realm EL1&0 Stage 1 (AArch64):
+  EL1RL:0x00000000D0000020 -> RLP:0x0000000050000020
+Realm EL1&0 Stage 2 (AArch64):
+  RLP:0x0000000050000020 -> NP:0x00000000B0000020
+```
+
+These addresses can be read from the memory pane or the command line:
+```command
+x/g EL1RL:0xD0000020
+x/g NP:0xB0000020
+```
+outputs:
+```output
+EL1RL:0x00000000D0000020:  0x0000000011111111
+NP:0x00000000B0000020:  0x0000000011111111
+```
+
+Similarly:
+
+```command
+mmu translate EL1RL:0xffffffff00000100
+```
+outputs:
+```output
+Realm EL1&0 Stage 1 (AArch64):
+  EL1RL:0xFFFFFFFF00000100 -> RLP:0x0000000060000100
+Realm EL1&0 Stage 2 (AArch64):
+  RLP:0x0000000060000100 -> RLP:0x00000000A0000100
+```
+
+## Demonstrate protection that RME provides
+
+The reference example successfully completes. We can make changes to the translation tables to see the effect of the protection that RME provides.
+
+Disconnect the debugger, and reconnect.
+
+Before execution, change the translation table entry defining Realms access for the 16KB region at `0xA0000000`.
+
+For example, to set for Secure access only, set that least-significant half-byte to 0x8:
+```command
+memory set 0x80024000 64 0x8
+```
+
+Set a breakpoint on the `STR` instruction that writes to `0xFFFFFFFF00000100`, which translates to `0xA0000100`:
+
+```asm
+    MOV64 X1, 0xFFFFFFFF00000100 // mapped to 0xA0000100 RL via IPA 0x60000100
+    MOV32 X0, 0x22222222
+*   STR X0, [X1]
+```
+And run (`F8`) to there. Observe that physical address (`0xA0000100`) requires secure access permissions:
+
+![0xA0000000 #center](_images/l1gpt_change.png)
+
+However the Realm (`0xFFFFFFFF00000100`) MMU is unchanged.
+
+![0xFFFFFFFF0000000 #center](_images/el1.png)
+
+Execute (`F5`) the `STR` instruction, and a memory exception correctly occurs, and the code branches to the vector table (at `0x200`).
+
+```output
+Execution stopped in EL1h mode at EL1RL:0x0000000000000200
+```
+{{% notice Note %}}
+The example has not configured the Realm vector table, and so there will also be a memory access error at the vector table.
+
+This can be ignored for the purposes of understanding RME behavior.
+{{% /notice %}}

content/learning-paths/cross-platform/cca_rme/cca.md

@@ -0,0 +1,32 @@
+---
+# User change
+title: Arm Confidential Compute Architecture
+
+weight: 2 # 1 is first, 2 is second, etc.
+
+# Do not modify these elements
+layout: "learningpathall"
+---
+
+[Arm Confidential Compute Architecture ](https://www.arm.com/architecture/security-features/arm-confidential-compute-architecture) (`CCA`) is a system solution consisting of hardware and software components to maximize the security of your data on devices and cloud.
+
+CCA enhances the virtualization capabilities of your platform by seperating management of resources from access to those resources. It does this by extending the `Trustzone for Cortex-A` concepts of `Normal world` and `Secure world`, to add a `Realm world`, and an underlying `Root world`. A secure monitor runs in `Root world`, and manages the transitions between these security states.
+
+![Architecture #center](_images/realms.png)
+
+For a detailed explanation of how CCA is implemented, review the [Learn the Architecture](https://developer.arm.com/documentation/den0125/) documentation.
+
+
+## Realms
+
+The `Realm Management Extension` (`RME`) is the principal hardware Armv9-A architectural feature to enable CCA.
+
+A `Realm` is an Arm CCA environment that can be dynamically allocated by the Normal world Host. The Host is the supervisory software that manages an application or Virtual Machine (VM).
+
+The initial state of a Realm, and of the platform on which it executes, can be attested. Attestation allows the Realm owner to establish trust in the Realm. The Realm does not have to inherit the trust from the Non-secure hypervisor which controls it.
+
+Memory can be dynamically assigned to different worlds by the MMU through `Granule Protection Tables`.
+
+For a detailed explanation of RME, review the [Learn the Architecture](https://developer.arm.com/documentation/den0126) documentation.
+
+In this learning path we will explore the basics of how Realms are managed.