DemesneGH commented on code in PR #193: URL: https://github.com/apache/incubator-teaclave-trustzone-sdk/pull/193#discussion_r2135186199
########## docs/emulate-and-dev-in-docker.md: ########## @@ -0,0 +1,169 @@ +--- +permalink: /trustzone-sdk-docs/dev-and-emulate-in-docker.md +--- + +# 🚀 Quick Start For QEMU Emulation + +This guide walks you through building and running QEMU emulation using the +Teaclave TrustZone SDK. + +We provide a Docker image with prebuilt QEMU and OP-TEE images to streamline +the entire Trusted Application (TA) development workflow. The image allows +developers to build TAs and emulate a guest virtual machine (VM) that includes +both the Normal World and Secure World environments. + +### 1. Pull Development Docker Image + +**Terminal A** (Main development terminal): +```bash +# Pull the pre-built development environment +$ docker pull teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest + +# Clone the repository +$ git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git && \ + cd incubator-teaclave-trustzone-sdk + +# Launch the development container +$ docker run -it --rm \ + --name teaclave_dev_env \ + -v $(pwd):/root/teaclave_sdk_src \ + teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest +``` + +### 2. Build the Hello World Example + +**Still in Terminal A** (inside the Docker container): +```bash +# Build the Hello World example (both CA and TA) +make -C examples/hello_world-rs/ +``` +Under the hood, the Makefile builds both the Trusted Application (TA) and the +Host Application separately. After a successful build, you’ll find the +resulting binaries in the `hello_world-rs` directory: +```bash +TA=ta/target/aarch64-unknown-linux-gnu/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta +Host_APP=host/target/aarch64-unknown-linux-gnu/release/hello_world-rs Review Comment: Host_APP => HOST_APP ########## docs/emulate-and-dev-in-docker.md: ########## @@ -0,0 +1,169 @@ +--- +permalink: /trustzone-sdk-docs/dev-and-emulate-in-docker.md +--- + +# 🚀 Quick Start For QEMU Emulation + +This guide walks you through building and running QEMU emulation using the +Teaclave TrustZone SDK. + +We provide a Docker image with prebuilt QEMU and OP-TEE images to streamline +the entire Trusted Application (TA) development workflow. The image allows +developers to build TAs and emulate a guest virtual machine (VM) that includes +both the Normal World and Secure World environments. + +### 1. Pull Development Docker Image + +**Terminal A** (Main development terminal): +```bash +# Pull the pre-built development environment +$ docker pull teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest + +# Clone the repository +$ git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git && \ + cd incubator-teaclave-trustzone-sdk + +# Launch the development container +$ docker run -it --rm \ + --name teaclave_dev_env \ + -v $(pwd):/root/teaclave_sdk_src \ + teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest +``` + +### 2. Build the Hello World Example + +**Still in Terminal A** (inside the Docker container): +```bash +# Build the Hello World example (both CA and TA) +make -C examples/hello_world-rs/ +``` +Under the hood, the Makefile builds both the Trusted Application (TA) and the +Host Application separately. After a successful build, you’ll find the +resulting binaries in the `hello_world-rs` directory: Review Comment: Add: It's recommended to record the paths of TA and HOST_APP for later use, like: ``` export TA=$PWD/examples/hello_world-rs/ta/target/aarch64-unknown-linux-gnu/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta export HOST_APP=$PWD/examples/hello_world-rs/host/target/aarch64-unknown-linux-gnu/release/hello_world-rs ``` ########## docs/emulate-and-dev-in-docker.md: ########## @@ -0,0 +1,169 @@ +--- +permalink: /trustzone-sdk-docs/dev-and-emulate-in-docker.md +--- + +# 🚀 Quick Start For QEMU Emulation + +This guide walks you through building and running QEMU emulation using the +Teaclave TrustZone SDK. + +We provide a Docker image with prebuilt QEMU and OP-TEE images to streamline +the entire Trusted Application (TA) development workflow. The image allows +developers to build TAs and emulate a guest virtual machine (VM) that includes +both the Normal World and Secure World environments. + +### 1. Pull Development Docker Image + +**Terminal A** (Main development terminal): +```bash +# Pull the pre-built development environment +$ docker pull teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest + +# Clone the repository +$ git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git && \ + cd incubator-teaclave-trustzone-sdk + +# Launch the development container +$ docker run -it --rm \ + --name teaclave_dev_env \ + -v $(pwd):/root/teaclave_sdk_src \ + teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest +``` + +### 2. Build the Hello World Example + +**Still in Terminal A** (inside the Docker container): +```bash +# Build the Hello World example (both CA and TA) +make -C examples/hello_world-rs/ +``` +Under the hood, the Makefile builds both the Trusted Application (TA) and the +Host Application separately. After a successful build, you’ll find the +resulting binaries in the `hello_world-rs` directory: +```bash +TA=ta/target/aarch64-unknown-linux-gnu/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta +Host_APP=host/target/aarch64-unknown-linux-gnu/release/hello_world-rs +``` + +### 3. Make the Artifacts Accessible to the Emulator +After building the Hello World example, the next step is to make the compiled +artifacts accessible to the emulator. + +There are **two approaches** to do this. You can choose either based on your +preference: +- 📦 **Manual sync**: Explicitly sync host and TA binaries to the emulator +- ⚙️ **Makefile integration**: Use `make emulate` to build and sync in one step + +#### Option 1: Manual Sync via `sync_to_emulator` +We provide a helper command called `sync_to_emulator`, which simplifies the +process of syncing the build outputs to the emulation environment. +Run the following commands inside the container: +```bash +sync_to_emulator -ta $TA Review Comment: `-ta` => `--ta` ########## docs/emulate-and-dev-in-docker.md: ########## @@ -0,0 +1,169 @@ +--- +permalink: /trustzone-sdk-docs/dev-and-emulate-in-docker.md +--- + +# 🚀 Quick Start For QEMU Emulation + +This guide walks you through building and running QEMU emulation using the +Teaclave TrustZone SDK. + +We provide a Docker image with prebuilt QEMU and OP-TEE images to streamline +the entire Trusted Application (TA) development workflow. The image allows +developers to build TAs and emulate a guest virtual machine (VM) that includes +both the Normal World and Secure World environments. + +### 1. Pull Development Docker Image + +**Terminal A** (Main development terminal): +```bash +# Pull the pre-built development environment +$ docker pull teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest + +# Clone the repository +$ git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git && \ + cd incubator-teaclave-trustzone-sdk + +# Launch the development container +$ docker run -it --rm \ + --name teaclave_dev_env \ + -v $(pwd):/root/teaclave_sdk_src \ + teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest +``` + +### 2. Build the Hello World Example + +**Still in Terminal A** (inside the Docker container): +```bash +# Build the Hello World example (both CA and TA) +make -C examples/hello_world-rs/ +``` +Under the hood, the Makefile builds both the Trusted Application (TA) and the +Host Application separately. After a successful build, you’ll find the +resulting binaries in the `hello_world-rs` directory: +```bash +TA=ta/target/aarch64-unknown-linux-gnu/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta +Host_APP=host/target/aarch64-unknown-linux-gnu/release/hello_world-rs +``` + +### 3. Make the Artifacts Accessible to the Emulator +After building the Hello World example, the next step is to make the compiled +artifacts accessible to the emulator. + +There are **two approaches** to do this. You can choose either based on your +preference: +- 📦 **Manual sync**: Explicitly sync host and TA binaries to the emulator +- ⚙️ **Makefile integration**: Use `make emulate` to build and sync in one step + +#### Option 1: Manual Sync via `sync_to_emulator` +We provide a helper command called `sync_to_emulator`, which simplifies the +process of syncing the build outputs to the emulation environment. +Run the following commands inside the container: +```bash +sync_to_emulator -ta $TA +sync_to_emulator -host $HOST_APP +``` +Run sync_to_emulator -h for more usage options. Review Comment: ``` sync_to_emulator -h Usage: /opt/teaclave/bin/sync_to_emulator [--ta|--host|--plugin|--dir] <files...> ``` what does `--dir` mean? ########## docs/emulate-and-dev-in-docker.md: ########## @@ -0,0 +1,169 @@ +--- +permalink: /trustzone-sdk-docs/dev-and-emulate-in-docker.md +--- + +# 🚀 Quick Start For QEMU Emulation + +This guide walks you through building and running QEMU emulation using the +Teaclave TrustZone SDK. + +We provide a Docker image with prebuilt QEMU and OP-TEE images to streamline +the entire Trusted Application (TA) development workflow. The image allows +developers to build TAs and emulate a guest virtual machine (VM) that includes +both the Normal World and Secure World environments. + +### 1. Pull Development Docker Image + +**Terminal A** (Main development terminal): +```bash +# Pull the pre-built development environment +$ docker pull teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest + +# Clone the repository +$ git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git && \ + cd incubator-teaclave-trustzone-sdk + +# Launch the development container +$ docker run -it --rm \ + --name teaclave_dev_env \ + -v $(pwd):/root/teaclave_sdk_src \ + teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest +``` + +### 2. Build the Hello World Example + +**Still in Terminal A** (inside the Docker container): +```bash +# Build the Hello World example (both CA and TA) +make -C examples/hello_world-rs/ +``` +Under the hood, the Makefile builds both the Trusted Application (TA) and the +Host Application separately. After a successful build, you’ll find the +resulting binaries in the `hello_world-rs` directory: +```bash +TA=ta/target/aarch64-unknown-linux-gnu/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta +Host_APP=host/target/aarch64-unknown-linux-gnu/release/hello_world-rs +``` + +### 3. Make the Artifacts Accessible to the Emulator +After building the Hello World example, the next step is to make the compiled +artifacts accessible to the emulator. + +There are **two approaches** to do this. You can choose either based on your +preference: +- 📦 **Manual sync**: Explicitly sync host and TA binaries to the emulator +- ⚙️ **Makefile integration**: Use `make emulate` to build and sync in one step + +#### Option 1: Manual Sync via `sync_to_emulator` +We provide a helper command called `sync_to_emulator`, which simplifies the +process of syncing the build outputs to the emulation environment. +Run the following commands inside the container: +```bash +sync_to_emulator -ta $TA +sync_to_emulator -host $HOST_APP +``` +Run sync_to_emulator -h for more usage options. + +#### Option 2: Use the Makefile's `emulate` Target +For convenience during daily development, this syncing step is integrated into +the Makefile under the `emulate` target. This will automatically build the +artifacts and sync them to the emulator in one step: +```bash +make -C examples/hello_world-rs/ emulate +``` +We recommend using this approach for a streamlined development workflow. + +## 4. Multi-Terminal Execution + +The emulation workflow requires three additional terminals to monitor +various aspects of the system: + +- **Terminal B**: 🖥️ **Normal World Listener** - Provides access to the guest VM shell +- **Terminal C**: 🔒 **Secure World Listener** - Monitors Trusted Application output logs +- **Terminal D**: 🚀 **QEMU Control** - Controls the QEMU emulator + +Built-in commands are provided in the Docker image. These commands are located +in `/opt/teaclave/bin/` and are included in the default user's $PATH. + +You may use `bash -l` or the full path when executing with docker exec. + +**Terminal B** (Guest VM Shell): +```bash +# Connect to the guest VM shell for running commands inside the emulated environment +$ docker exec -it teaclave_dev_env bash -l -c listen_on_guest_vm_shell + +# Alternative: Use full path +$ docker exec -it teaclave_dev_env /opt/teaclave/bin/listen_on_guest_vm_shell +``` + +**Terminal C** (Secure World Output Monitor): +```bash +# Monitor Trusted Application output logs in real-time +$ docker exec -it teaclave_dev_env bash -l -c listen_on_secure_world_log + +# Alternative: Use full path +$ docker exec -it teaclave_dev_env /opt/teaclave/bin/listen_on_secure_world_log +``` + +### 5. Start the Emulation + +After the listeners are set up, we can start the QEMU emulator. + +**Terminal D** (QEMU Control): +```bash +# Launch QEMU emulator with debug output and connect to monitoring ports +$ docker exec -it teaclave_dev_env bash -l -c "LISTEN_MODE=ON start_qemuv8" +``` + +> ⏳ **Wait for the QEMU environment to fully boot...** +You should see boot messages in Terminal D and the guest VM shell prompt +in Terminal B. + +After QEMU in Terminal D successfully launches, switch to Terminal B, which +provides shell access to the guest VM's normal world. + +**Terminal B** (Inside Guest VM): +From this shell, you’ll notice that the artifacts synced in **Step 3** are +already available in the current working directory. This shared directory is +mounted between the host and the guest VM, so any changes made—either inside +or outside QEMU—are immediately reflected on both sides. +```bash +# tree +. +|-- host +| `-- hello_world-rs +|-- plugin +`-- ta + `-- 133af0ca-bdab-11eb-9130-43bf7873bf67.ta + +3 directories, 2 files +``` +This makes it especially convenient for iterative development and frequent code +updates. + +Now we are ready to interact with the TA from normal world shell. +```bash +# Execute the Hello World Client Application +$ ./host/hello_world-rs +``` +The secure world logs, including TA debug messages, are displayed in **Terminal C**. Review Comment: Add: If you're in the development stage and need to debug multiple times, there's no need to restart terminals B, C, or D. Simply run `make emulate`, and the updated artifacts will be available in the guest under `/host`, `/ta`, and `/plugin`. ########## docs/emulate-and-dev-in-docker.md: ########## @@ -0,0 +1,169 @@ +--- +permalink: /trustzone-sdk-docs/dev-and-emulate-in-docker.md +--- + +# 🚀 Quick Start For QEMU Emulation + +This guide walks you through building and running QEMU emulation using the +Teaclave TrustZone SDK. + +We provide a Docker image with prebuilt QEMU and OP-TEE images to streamline +the entire Trusted Application (TA) development workflow. The image allows +developers to build TAs and emulate a guest virtual machine (VM) that includes +both the Normal World and Secure World environments. + +### 1. Pull Development Docker Image + +**Terminal A** (Main development terminal): +```bash +# Pull the pre-built development environment +$ docker pull teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest + +# Clone the repository +$ git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git && \ + cd incubator-teaclave-trustzone-sdk + +# Launch the development container +$ docker run -it --rm \ + --name teaclave_dev_env \ + -v $(pwd):/root/teaclave_sdk_src \ + teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest +``` + +### 2. Build the Hello World Example + +**Still in Terminal A** (inside the Docker container): +```bash +# Build the Hello World example (both CA and TA) +make -C examples/hello_world-rs/ +``` +Under the hood, the Makefile builds both the Trusted Application (TA) and the +Host Application separately. After a successful build, you’ll find the +resulting binaries in the `hello_world-rs` directory: +```bash +TA=ta/target/aarch64-unknown-linux-gnu/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta +Host_APP=host/target/aarch64-unknown-linux-gnu/release/hello_world-rs +``` + +### 3. Make the Artifacts Accessible to the Emulator +After building the Hello World example, the next step is to make the compiled +artifacts accessible to the emulator. + +There are **two approaches** to do this. You can choose either based on your +preference: +- 📦 **Manual sync**: Explicitly sync host and TA binaries to the emulator +- ⚙️ **Makefile integration**: Use `make emulate` to build and sync in one step + +#### Option 1: Manual Sync via `sync_to_emulator` +We provide a helper command called `sync_to_emulator`, which simplifies the +process of syncing the build outputs to the emulation environment. +Run the following commands inside the container: +```bash +sync_to_emulator -ta $TA +sync_to_emulator -host $HOST_APP Review Comment: --host ########## docs/emulate-and-dev-in-docker.md: ########## @@ -0,0 +1,169 @@ +--- +permalink: /trustzone-sdk-docs/dev-and-emulate-in-docker.md +--- + +# 🚀 Quick Start For QEMU Emulation + +This guide walks you through building and running QEMU emulation using the +Teaclave TrustZone SDK. + +We provide a Docker image with prebuilt QEMU and OP-TEE images to streamline +the entire Trusted Application (TA) development workflow. The image allows +developers to build TAs and emulate a guest virtual machine (VM) that includes +both the Normal World and Secure World environments. + +### 1. Pull Development Docker Image + +**Terminal A** (Main development terminal): +```bash +# Pull the pre-built development environment +$ docker pull teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest + +# Clone the repository +$ git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git && \ + cd incubator-teaclave-trustzone-sdk + +# Launch the development container +$ docker run -it --rm \ + --name teaclave_dev_env \ + -v $(pwd):/root/teaclave_sdk_src \ + teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest +``` + +### 2. Build the Hello World Example + +**Still in Terminal A** (inside the Docker container): +```bash +# Build the Hello World example (both CA and TA) +make -C examples/hello_world-rs/ +``` +Under the hood, the Makefile builds both the Trusted Application (TA) and the +Host Application separately. After a successful build, you’ll find the +resulting binaries in the `hello_world-rs` directory: +```bash +TA=ta/target/aarch64-unknown-linux-gnu/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta +Host_APP=host/target/aarch64-unknown-linux-gnu/release/hello_world-rs +``` + +### 3. Make the Artifacts Accessible to the Emulator +After building the Hello World example, the next step is to make the compiled +artifacts accessible to the emulator. + +There are **two approaches** to do this. You can choose either based on your +preference: +- 📦 **Manual sync**: Explicitly sync host and TA binaries to the emulator +- ⚙️ **Makefile integration**: Use `make emulate` to build and sync in one step + +#### Option 1: Manual Sync via `sync_to_emulator` +We provide a helper command called `sync_to_emulator`, which simplifies the +process of syncing the build outputs to the emulation environment. +Run the following commands inside the container: +```bash +sync_to_emulator -ta $TA +sync_to_emulator -host $HOST_APP +``` +Run sync_to_emulator -h for more usage options. + +#### Option 2: Use the Makefile's `emulate` Target +For convenience during daily development, this syncing step is integrated into +the Makefile under the `emulate` target. This will automatically build the +artifacts and sync them to the emulator in one step: Review Comment: Add clarification: The demo command `emulate` is provided only in the `hello-world` example. You can create a similar command for your own project if needed. ########## docs/emulate-and-dev-in-docker.md: ########## @@ -0,0 +1,169 @@ +--- +permalink: /trustzone-sdk-docs/dev-and-emulate-in-docker.md +--- + +# 🚀 Quick Start For QEMU Emulation + +This guide walks you through building and running QEMU emulation using the +Teaclave TrustZone SDK. + +We provide a Docker image with prebuilt QEMU and OP-TEE images to streamline +the entire Trusted Application (TA) development workflow. The image allows +developers to build TAs and emulate a guest virtual machine (VM) that includes +both the Normal World and Secure World environments. + +### 1. Pull Development Docker Image + +**Terminal A** (Main development terminal): +```bash +# Pull the pre-built development environment +$ docker pull teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest + +# Clone the repository +$ git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git && \ + cd incubator-teaclave-trustzone-sdk + +# Launch the development container +$ docker run -it --rm \ + --name teaclave_dev_env \ + -v $(pwd):/root/teaclave_sdk_src \ + teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest +``` + +### 2. Build the Hello World Example + +**Still in Terminal A** (inside the Docker container): +```bash +# Build the Hello World example (both CA and TA) +make -C examples/hello_world-rs/ +``` +Under the hood, the Makefile builds both the Trusted Application (TA) and the +Host Application separately. After a successful build, you’ll find the +resulting binaries in the `hello_world-rs` directory: +```bash +TA=ta/target/aarch64-unknown-linux-gnu/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta +Host_APP=host/target/aarch64-unknown-linux-gnu/release/hello_world-rs +``` + +### 3. Make the Artifacts Accessible to the Emulator +After building the Hello World example, the next step is to make the compiled +artifacts accessible to the emulator. + +There are **two approaches** to do this. You can choose either based on your +preference: +- 📦 **Manual sync**: Explicitly sync host and TA binaries to the emulator +- ⚙️ **Makefile integration**: Use `make emulate` to build and sync in one step + +#### Option 1: Manual Sync via `sync_to_emulator` +We provide a helper command called `sync_to_emulator`, which simplifies the +process of syncing the build outputs to the emulation environment. +Run the following commands inside the container: +```bash +sync_to_emulator -ta $TA +sync_to_emulator -host $HOST_APP +``` +Run sync_to_emulator -h for more usage options. + +#### Option 2: Use the Makefile's `emulate` Target +For convenience during daily development, this syncing step is integrated into +the Makefile under the `emulate` target. This will automatically build the +artifacts and sync them to the emulator in one step: +```bash +make -C examples/hello_world-rs/ emulate Review Comment: `emulate` command doesn't build the artifacts for now. I prefer the `emulate` first build then copy artifacts, if so, I can run one command `emulate` to do all steps, no need to run a build command before. ########## docs/emulate-and-dev-in-docker.md: ########## @@ -0,0 +1,169 @@ +--- +permalink: /trustzone-sdk-docs/dev-and-emulate-in-docker.md +--- + +# 🚀 Quick Start For QEMU Emulation + +This guide walks you through building and running QEMU emulation using the +Teaclave TrustZone SDK. + +We provide a Docker image with prebuilt QEMU and OP-TEE images to streamline +the entire Trusted Application (TA) development workflow. The image allows +developers to build TAs and emulate a guest virtual machine (VM) that includes +both the Normal World and Secure World environments. + +### 1. Pull Development Docker Image + +**Terminal A** (Main development terminal): +```bash +# Pull the pre-built development environment +$ docker pull teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest + +# Clone the repository +$ git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git && \ + cd incubator-teaclave-trustzone-sdk + +# Launch the development container +$ docker run -it --rm \ + --name teaclave_dev_env \ + -v $(pwd):/root/teaclave_sdk_src \ + teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest Review Comment: Add `-w` to switch to the source directory: ``` $ docker run -it --rm \ --name teaclave_dev_env \ -v $(pwd):/root/teaclave_sdk_src \ -w /root/teaclave_sdk_src \ teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest ``` By default without `-w` we will enter `/root`. ########## docs/emulate-and-dev-in-docker.md: ########## @@ -0,0 +1,169 @@ +--- +permalink: /trustzone-sdk-docs/dev-and-emulate-in-docker.md +--- + +# 🚀 Quick Start For QEMU Emulation + +This guide walks you through building and running QEMU emulation using the +Teaclave TrustZone SDK. + +We provide a Docker image with prebuilt QEMU and OP-TEE images to streamline +the entire Trusted Application (TA) development workflow. The image allows +developers to build TAs and emulate a guest virtual machine (VM) that includes +both the Normal World and Secure World environments. + +### 1. Pull Development Docker Image + +**Terminal A** (Main development terminal): +```bash +# Pull the pre-built development environment +$ docker pull teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest + +# Clone the repository +$ git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git && \ + cd incubator-teaclave-trustzone-sdk + +# Launch the development container +$ docker run -it --rm \ + --name teaclave_dev_env \ + -v $(pwd):/root/teaclave_sdk_src \ + teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest +``` + +### 2. Build the Hello World Example + +**Still in Terminal A** (inside the Docker container): +```bash +# Build the Hello World example (both CA and TA) +make -C examples/hello_world-rs/ +``` +Under the hood, the Makefile builds both the Trusted Application (TA) and the +Host Application separately. After a successful build, you’ll find the +resulting binaries in the `hello_world-rs` directory: +```bash +TA=ta/target/aarch64-unknown-linux-gnu/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta +Host_APP=host/target/aarch64-unknown-linux-gnu/release/hello_world-rs +``` + +### 3. Make the Artifacts Accessible to the Emulator +After building the Hello World example, the next step is to make the compiled +artifacts accessible to the emulator. + +There are **two approaches** to do this. You can choose either based on your +preference: +- 📦 **Manual sync**: Explicitly sync host and TA binaries to the emulator +- ⚙️ **Makefile integration**: Use `make emulate` to build and sync in one step + +#### Option 1: Manual Sync via `sync_to_emulator` +We provide a helper command called `sync_to_emulator`, which simplifies the +process of syncing the build outputs to the emulation environment. +Run the following commands inside the container: +```bash +sync_to_emulator -ta $TA +sync_to_emulator -host $HOST_APP +``` +Run sync_to_emulator -h for more usage options. + +#### Option 2: Use the Makefile's `emulate` Target +For convenience during daily development, this syncing step is integrated into +the Makefile under the `emulate` target. This will automatically build the +artifacts and sync them to the emulator in one step: +```bash +make -C examples/hello_world-rs/ emulate +``` +We recommend using this approach for a streamlined development workflow. + +## 4. Multi-Terminal Execution + +The emulation workflow requires three additional terminals to monitor +various aspects of the system: + +- **Terminal B**: 🖥️ **Normal World Listener** - Provides access to the guest VM shell +- **Terminal C**: 🔒 **Secure World Listener** - Monitors Trusted Application output logs +- **Terminal D**: 🚀 **QEMU Control** - Controls the QEMU emulator + +Built-in commands are provided in the Docker image. These commands are located +in `/opt/teaclave/bin/` and are included in the default user's $PATH. + +You may use `bash -l` or the full path when executing with docker exec. + +**Terminal B** (Guest VM Shell): +```bash +# Connect to the guest VM shell for running commands inside the emulated environment +$ docker exec -it teaclave_dev_env bash -l -c listen_on_guest_vm_shell + +# Alternative: Use full path +$ docker exec -it teaclave_dev_env /opt/teaclave/bin/listen_on_guest_vm_shell +``` + +**Terminal C** (Secure World Output Monitor): +```bash +# Monitor Trusted Application output logs in real-time +$ docker exec -it teaclave_dev_env bash -l -c listen_on_secure_world_log + +# Alternative: Use full path +$ docker exec -it teaclave_dev_env /opt/teaclave/bin/listen_on_secure_world_log +``` + +### 5. Start the Emulation + +After the listeners are set up, we can start the QEMU emulator. + +**Terminal D** (QEMU Control): +```bash +# Launch QEMU emulator with debug output and connect to monitoring ports +$ docker exec -it teaclave_dev_env bash -l -c "LISTEN_MODE=ON start_qemuv8" +``` + +> ⏳ **Wait for the QEMU environment to fully boot...** +You should see boot messages in Terminal D and the guest VM shell prompt +in Terminal B. + +After QEMU in Terminal D successfully launches, switch to Terminal B, which +provides shell access to the guest VM's normal world. + +**Terminal B** (Inside Guest VM): +From this shell, you’ll notice that the artifacts synced in **Step 3** are +already available in the current working directory. This shared directory is +mounted between the host and the guest VM, so any changes made—either inside +or outside QEMU—are immediately reflected on both sides. Review Comment: Add: The `ta/` directory is mapped to `/lib/optee_armtz`, which is the default directory OP-TEE uses to search for TAs. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: dev-unsubscr...@teaclave.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@teaclave.apache.org For additional commands, e-mail: dev-h...@teaclave.apache.org
