[PR] setup: add docker for quick start [incubator-teaclave-trustzone-sdk]

["DemesneGH (via GitHub)" <gi...@apache.org>]

DemesneGH opened a new pull request, #193:
URL: https://github.com/apache/incubator-teaclave-trustzone-sdk/pull/193

   As discussed in https://github.com/apache/incubator-teaclave-trustzone-sdk/issues/189, providing a Docker image for quick start can significantly improve the onboarding experience for developers using the SDK — especially first-time users.
   
   This PR introduces a Dockerfile that pre-builds the essential dependencies, reducing build time and allowing developers to quickly set up their environment and perform a minimal build with ease.
   
   ### Current Usage
   
   This Dockerfile enables a simple and streamlined workflow:
   
   ```bash
   # Clone the SDK repository
   $ git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git && cd incubator-teaclave-trustzone-sdk
   
   # Build the Docker image (will support docker pull after we publish on dockerhub)
   $ docker build -f Dockerfile.quickstart -t teaclave-trustzone-sdk-quickstart .
   
   # Launch the container
   $ docker run -it --rm \
     -v$(pwd):/root/teaclave_sdk_src \
     -w /root/teaclave_sdk_src \
     teaclave-trustzone-sdk-quickstart bash
   ```
   
   Once inside the container, build and test the Hello World example:
   
   ```bash
   $ source environment
   $ make -C examples/hello_world-rs/
   $ cd tests/
   $ ./test_hello_world.sh
   ```
   
   The README is also updated for the quick start workflow.
   
   ### Future Plans & TODOs
   
   This is the initial version and there's room for improvement. Possible enhancements include:
   
   * Currently supports only `no-std` mode; add support for `std`.
   * Parameterize options like `PLATFORM`.
   * Consider building OP-TEE images inside the Docker image. I had a quick try and the considerations are as follows:
     * Pros: Tests will use locally built images, no dependency on downloading from`nightlies.apache.org`.
     * Cons: Increases image size to \~22GB. Need to experiment with cache cleanup to reduce size.
     * Other notes: OP-TEE needs to be patched with expanded memory settings to run all tests reliably.
   * Quick Development: Add a helper script to quickly initialize a new TA project by name.
   * Quick Debug: Add tooling for quick setup TA debugging environment:
     * A script to launch the emulator and split terminals.
     * Support multi-arch prebuilt QEMU for debugging (initially support `aarch64` only).
   * Simplify CI jobs by reusing this image to cut down build time.
   


-- 
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-unsubscribe@teaclave.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@teaclave.apache.org
For additional commands, e-mail: dev-help@teaclave.apache.org

Re: [PR] setup: add docker for quick start [incubator-teaclave-trustzone-sdk]

["DemesneGH (via GitHub)" <gi...@apache.org>]

DemesneGH commented on PR #193:
URL: https://github.com/apache/incubator-teaclave-trustzone-sdk/pull/193#issuecomment-2904038261

   This PR is marked as a draft and will be refined further.


-- 
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-unsubscribe@teaclave.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@teaclave.apache.org
For additional commands, e-mail: dev-help@teaclave.apache.org

Re: [PR] dev-env: prebuilt docker image for development and emulation [incubator-teaclave-trustzone-sdk]

["DemesneGH (via GitHub)" <gi...@apache.org>]

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-unsubscribe@teaclave.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@teaclave.apache.org
For additional commands, e-mail: dev-help@teaclave.apache.org

Re: [PR] dev-env: prebuilt docker image for development and emulation [incubator-teaclave-trustzone-sdk]

["DemesneGH (via GitHub)" <gi...@apache.org>]

DemesneGH commented on PR #193:
URL: https://github.com/apache/incubator-teaclave-trustzone-sdk/pull/193#issuecomment-2948714629

   LGTM. I’ll try out the workflow and publish the Docker image later.


-- 
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-unsubscribe@teaclave.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@teaclave.apache.org
For additional commands, e-mail: dev-help@teaclave.apache.org

Re: [PR] dev-env: prebuilt docker image for development and emulation [incubator-teaclave-trustzone-sdk]

["DemesneGH (via GitHub)" <gi...@apache.org>]

DemesneGH merged PR #193:
URL: https://github.com/apache/incubator-teaclave-trustzone-sdk/pull/193


-- 
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-unsubscribe@teaclave.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@teaclave.apache.org
For additional commands, e-mail: dev-help@teaclave.apache.org

Re: [PR] setup: add docker for quick start [incubator-teaclave-trustzone-sdk]

["ivila (via GitHub)" <gi...@apache.org>]

ivila commented on code in PR #193:
URL: https://github.com/apache/incubator-teaclave-trustzone-sdk/pull/193#discussion_r2110799286


##########
tests/test_tls_server.sh:
##########
@@ -24,8 +24,8 @@ NEED_EXPANDED_MEM=true
 source setup.sh
 
 # Copy TA and host binary
-cp ../examples/tls_server-rs/ta/target/$TARGET_TA/release/*.ta shared
-cp ../examples/tls_server-rs/host/target/$TARGET_HOST/release/tls_server-rs shared
+cp ../examples/tls_server-rs/ta/target/$TARGET_TA/release/*.ta$QEMU_HOST_SHARE_DIR

Review Comment:
   Missing an empty space.



-- 
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-unsubscribe@teaclave.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@teaclave.apache.org
For additional commands, e-mail: dev-help@teaclave.apache.org

Re: [PR] dev-env: prebuilt docker image for development and emulation [incubator-teaclave-trustzone-sdk]

["DemesneGH (via GitHub)" <gi...@apache.org>]

DemesneGH commented on PR #193:
URL: https://github.com/apache/incubator-teaclave-trustzone-sdk/pull/193#issuecomment-2961102567

   The docker image has been published as `teaclave/teaclave-trustzone-emulator-nostd-optee-4.5.0-expand-memory:latest`. 


-- 
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-unsubscribe@teaclave.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@teaclave.apache.org
For additional commands, e-mail: dev-help@teaclave.apache.org

Re: [PR] setup: add docker for quick start [incubator-teaclave-trustzone-sdk]

["DemesneGH (via GitHub)" <gi...@apache.org>]

DemesneGH commented on PR #193:
URL: https://github.com/apache/incubator-teaclave-trustzone-sdk/pull/193#issuecomment-2911805038

   Updates:
   - Reorganized scripts into a new `scripts/` directory with subfolders `setup/` and `debug/`.
   - Dockerfile now reuses `scripts/setup/`, also allowing developers to customize the build environment by running the setup scripts manually when they doesn't want to use our docker.
   - Quick Debug: A new debug workflow is introduced—see details in the section below.
   - The `README` has not been updated yet in this review stage. Please see the below workflow.
   
   Current workflow:
   --------------
   ### Quick Start Guide
   
   ```bash
   # Build the quick-start Docker image (use docker pull after publish)
   git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git && cd incubator-teaclave-trustzone-sdk
   docker build -f Dockerfile.quickstart -t teaclave-trustzone-sdk-quick-start .
   
   # Start the container
   docker run -it --rm \
     --name teaclave_sdk_dev \
     -v $(pwd):/root/teaclave_sdk_src \
     -w /root/teaclave_sdk_src \
     teaclave-trustzone-sdk-quick-start \
     bash
   ```
   
   Inside the container, build the `hello_world` example with the default `ARCH` setting:
   
   ```bash
   source environment
   make -C examples/hello_world-rs/
   ```
   
   **Optional**: Run a quick CI test:
   
   ```bash
   cd tests/ && ./test_hello_world.sh
   ```
   
   ### Run CA and TA in the Emulator
   
   By default, the test scripts use a `screen` session to run QEMU and capture the logs automatically.  
   For developers who want to **run the CA and TA manually**, use the **debug mode**. This mode gives you full visibility and control of QEMU and serial output, and **requires three terminals**:
   
   Currently, we have one terminal (**Terminal A**) for building and preparing the environment.
   
   Open two additional terminals:
   
   **Terminal B** – Boot guest rootfs:
   
   ```bash
   docker exec -it teaclave_sdk_dev /root/teaclave_sdk_src/scripts/emulator/boot_guest_rootfs.exp
   ```
   
   **Terminal C** – Listen on TA output:
   
   ```bash
   docker exec -it teaclave_sdk_dev /root/teaclave_sdk_src/scripts/emulator/listen_on_ta_output.sh
   ```
   
   Back in **Terminal A**, copy the built applications and launch QEMU in debug mode:
   
   ```bash
   cp examples/hello_world-rs/host/target/aarch64-unknown-linux-gnu/release/hello_world-rs $QEMU_HOST_SHARE_DIR
   cp examples/hello_world-rs/ta/target/aarch64-unknown-linux-gnu/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta $QEMU_HOST_SHARE_DIR
   cd scripts/emulator && DEBUG=1 ./optee-qemuv8.sh
   ```
   
   In **Terminal B** (inside QEMU guest):
   
   ```bash
   # ls
   133af0ca-bdab-11eb-9130-43bf7873bf67.ta
   hello_world-rs
   
   # Install and run
   cp 133af0ca-bdab-11eb-9130-43bf7873bf67.ta /lib/optee_armtz/
   ./hello_world-rs
   ```
   
   Expected output from guest vm:
   
   ```
   original value is 29
   inc value is 129
   dec value is 29
   Success
   ```
   
   ### Customize the Build Environment from Scratch
   
   If you prefer not to use our Docker image, you can set up the build environment manually by running the scripts in `scripts/setup/`:
   
   ```bash
   git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git && cd incubator-teaclave-trustzone-sdk
   cd scripts/setup
   
   source setup_env && \
     bash setup_optee_dependencies.sh && \
     bash setup_toolchain.sh && \
     bash build_optee_libraries.sh && \
     echo "source /root/teaclave_sdk_prebuilt/scripts/setup/setup_env" >> /root/.bashrc
   ```


-- 
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-unsubscribe@teaclave.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@teaclave.apache.org
For additional commands, e-mail: dev-help@teaclave.apache.org

Re: [PR] setup: add docker for quick start [incubator-teaclave-trustzone-sdk]

["DemesneGH (via GitHub)" <gi...@apache.org>]

DemesneGH commented on PR #193:
URL: https://github.com/apache/incubator-teaclave-trustzone-sdk/pull/193#issuecomment-2911818032

   The CI failed due to recent changes in the scripts. This does not affect the current review stage and can be addressed in a later phase.


-- 
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-unsubscribe@teaclave.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@teaclave.apache.org
For additional commands, e-mail: dev-help@teaclave.apache.org

Re: [PR] setup: add docker for quick start [incubator-teaclave-trustzone-sdk]

["DemesneGH (via GitHub)" <gi...@apache.org>]

DemesneGH commented on PR #193:
URL: https://github.com/apache/incubator-teaclave-trustzone-sdk/pull/193#issuecomment-2919152539

   Updated according to previous discussion with @m4sterchain .
   This is the current workflow:
   
   #### Full workflow of quick build and run:
   ```
   Open a Terminal and we called it Terminal A:
   $ git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git && cd incubator-teaclave-trustzone-sdk
   $ docker build -f Dockerfile.dev -t teaclave-trustzone-sdk-dev .  # or use docker pull after publish
   $ docker run -it --rm \
     --name teaclave_sdk_dev \
     -v $(pwd):/root/teaclave_sdk_src \
     -w /root/teaclave_sdk_src \
     teaclave-trustzone-sdk-dev \
     bash
   
   build and sync: also in Terminal A, after we enter the docker container:
   $ make -C examples/hello_world-rs/
   $ sync_to_emulator examples/hello_world-rs/
   
   run: needs two new terminals: B and C
   1. In Terminal B: Connect to guest VM shell to run commands inside the emulated environment  
   $ docker exec -it teaclave_sdk_dev listen_on_guest_vm_shell
   
   2. In Terminal C: Monitor TA (Trusted Application) output logs  
   $ docker exec -it teaclave_sdk_dev listen_on_ta_output
   
   3. In Terminal A: Start the QEMU emulator and connect to two listening port
   $ DEBUG=1 start_qemuv8
   
   4. In Terminal B: Run the example Trusted Application after get the guest VM shell  
   $ ./host/hello_world-rs
   ```
   
   #### For frequent rebuild and debugging (open additional Terminal D for building and enter docker):  
   ```
   In Terminal D:
   $ docer exec -it teaclave_sdk_dev bash
   After enter the docker container, re-build and sync to emulator:
   $ make -C examples/hello_world-rs/  
   $ sync_to_emulator examples/hello_world-rs/
   
   Then in Terminal B:  
   $ ./host/hello_world-rs
   ```
   
   Please feel free to try the current workflow and share your feedback.


-- 
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-unsubscribe@teaclave.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@teaclave.apache.org
For additional commands, e-mail: dev-help@teaclave.apache.org