You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@teaclave.apache.org by yu...@apache.org on 2026/01/16 06:24:58 UTC
(teaclave-trustzone-sdk) 06/06: docs: refactor README of cargo-optee and remove hardcoded configs in hello_world-rs
This is an automated email from the ASF dual-hosted git repository.
yuanz pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/teaclave-trustzone-sdk.git
commit 4a4322bf72d5dec294ad883af0b4b13d40be16ce
Author: asir <24...@qq.com>
AuthorDate: Fri Jan 16 00:49:55 2026 +0800
docs: refactor README of cargo-optee and remove hardcoded configs in hello_world-rs
---
cargo-optee/README.md | 374 ++++++++++++++++++++++------------
docs/emulate-and-dev-in-docker-std.md | 57 +++---
docs/emulate-and-dev-in-docker.md | 85 ++++----
examples/hello_world-rs/ta/Cargo.toml | 8 -
4 files changed, 329 insertions(+), 195 deletions(-)
diff --git a/cargo-optee/README.md b/cargo-optee/README.md
index 44601ee..d4cc47f 100644
--- a/cargo-optee/README.md
+++ b/cargo-optee/README.md
@@ -1,10 +1,14 @@
# cargo-optee
-A Cargo subcommand for building OP-TEE Trusted Applications (TAs) and Client Applications (CAs) in Rust.
+A Cargo subcommand for building OP-TEE Trusted Applications (TAs) and Client
+Applications (CAs) in Rust.
## Overview
-`cargo-optee` simplifies the development workflow for OP-TEE applications by replacing complex Makefiles with a unified, type-safe command-line interface. It handles cross-compilation, custom target specifications, environment setup, and signing automatically.
+`cargo-optee` simplifies the development workflow for OP-TEE applications by
+replacing complex Makefiles with a unified, type-safe command-line interface. It
+handles cross-compilation, custom target specifications, environment setup, and
+signing automatically.
## High-Level Design
@@ -59,83 +63,124 @@ A Cargo subcommand for building OP-TEE Trusted Applications (TAs) and Client App
### Installation
-Assume developers have Rust, Cargo, and the gcc toolchain installed and added to PATH (the guide is in future plan). Then install `cargo-optee` using Cargo:
+Assume developers have Rust, Cargo, and the gcc toolchain installed and added to
+PATH (the guide is in future plan). Then install `cargo-optee` using Cargo:
```bash
cargo install cargo-optee
```
-## Configuration System
+### Quick Build for Hello World
-`cargo-optee` uses a flexible configuration system with the following priority (highest to lowest):
+This section provides a quick start guide for building the Hello World example
+using `cargo-optee`. Before proceeding, ensure you have set up the Docker
+development environment. For detailed instructions on setting up the Docker
+environment, refer to the [QEMU emulation
+guide](../docs/emulate-and-dev-in-docker.md).
-1. **Command Line Arguments** - Direct CLI flags override everything
-2. **Cargo.toml Metadata** - Project-specific configuration in `[package.metadata.optee.*]` sections
-3. **Defaults** - Built-in sensible defaults
+#### Prerequisites
-This allows projects to define their standard configuration in `Cargo.toml` while still permitting CLI overrides for specific builds.
+First, pull and run the Docker image. We provide two types of images:
+- **no-std environment**: For building TAs without the standard library
+ (recommended for quick start)
+- **std environment**: For building TAs with Rust standard library support
-### Metadata Configuration
+**Pull and start the no-std development environment:**
+```bash
+# Pull the pre-built development environment image
+docker pull teaclave/teaclave-trustzone-emulator-nostd-expand-memory:latest
+
+# Start the development container
+docker run -it --rm \
+ --name teaclave_dev_env \
+ -v $(pwd):/root/teaclave_sdk_src \
+ -w /root/teaclave_sdk_src \
+ teaclave/teaclave-trustzone-emulator-nostd-expand-memory:latest
+```
-#### Trusted Application (TA) Metadata
+> 📖 **Note**: If you need Rust standard library (std) support, refer to the
+> [Docker development environment guide with std
+> support](../docs/emulate-and-dev-in-docker-std.md) and use the
+> `teaclave/teaclave-trustzone-emulator-std-expand-memory:latest` image.
-Configure TA builds in your `Cargo.toml`:
+#### Build Steps
-```toml
-[package.metadata.optee.ta]
-arch = "aarch64" # Target architecture: "aarch64" | "arm" (optional, default: "aarch64")
-debug = false # Debug build: true | false (optional, default: false)
-std = false # Use std library: true | false (optional, default: false)
-uuid-path = "../uuid.txt" # Path to UUID file (optional, default: "../uuid.txt")
-# Architecture-specific configuration (omitted architectures default to null/unsupported)
-ta-dev-kit-dir = { aarch64 = "/opt/optee/export-ta_arm64", arm = "/opt/optee/export-ta_arm32" }
-signing-key = "/path/to/key.pem" # Path to signing key (optional, defaults to ta-dev-kit/keys/default_ta.pem)
+**1. Navigate to the Hello World example directory**
+
+Inside the Docker container, execute:
+```bash
+cd examples/hello_world-rs/
```
-**Allowed entries:**
-- `arch`: Target architecture (`"aarch64"` or `"arm"`)
-- `debug`: Build in debug mode (`true` or `false`)
-- `std`: Enable std library support (`true` or `false`)
-- `uuid-path`: Relative or absolute path to UUID file
-- `ta-dev-kit-dir`: Architecture-specific paths to TA development kit (required)
-- `signing-key`: Path to signing key file
+**2. Build the Trusted Application (TA)**
-#### Client Application (CA) Metadata
+Build the TA using `cargo-optee`. In the Docker environment, the OP-TEE TA
+development kit is typically located at
+`/opt/teaclave/optee/optee_os/out/arm-plat-vexpress/export-ta_arm64`:
-Configure CA builds in your `Cargo.toml`:
+```bash
+# Build aarch64 no-std TA (default configuration)
+cargo-optee build ta \
+ --manifest-path ta/Cargo.toml \
+ --ta-dev-kit-dir /opt/teaclave/optee/optee_os/out/arm-plat-vexpress/export-ta_arm64 \
+ --arch aarch64 \
+ --no-std
+```
-```toml
-[package.metadata.optee.ca]
-arch = "aarch64" # Target architecture: "aarch64" | "arm" (optional, default: "aarch64")
-debug = false # Debug build: true | false (optional, default: false)
-# Architecture-specific configuration
-# if your CA only supports aarch64, you can omit arm
-optee-client-export = { aarch64 = "/opt/optee/export-client_arm64" }
+**3. Build the Client Application (CA)**
+
+Build the client application:
+```bash
+# Build aarch64 CA
+cargo-optee build ca \
+ --manifest-path host/Cargo.toml \
+ --optee-client-export /opt/teaclave/optee/optee_client/export_arm64 \
+ --arch aarch64
```
-**Allowed entries:**
-- `arch`: Target architecture (`"aarch64"` or `"arm"`)
-- `debug`: Build in debug mode (`true` or `false`)
-- `optee-client-export`: Architecture-specific paths to OP-TEE client export (required)
+> 💡 **Tip**: If you configure metadata in your `Cargo.toml` file (see
+> [Configuration System](#configuration-system)), you can simplify the command
+> by only specifying `--manifest-path`:
+> ```bash
+> cargo-optee build ca --manifest-path host/Cargo.toml
+> ```
-#### Plugin Metadata
+#### Build Output
-Configure plugin builds in your `Cargo.toml`:
+After a successful build, you can find the generated files at the following
+locations:
-```toml
-[package.metadata.optee.plugin]
-arch = "aarch64" # Target architecture: "aarch64" | "arm" (optional, default: "aarch64")
-debug = false # Debug build: true | false (optional, default: false)
-uuid-path = "../plugin_uuid.txt" # Path to UUID file (required for plugins)
-# Architecture-specific configuration
-optee-client-export = { aarch64 = "/opt/optee/export-client_arm64", arm = "/opt/optee/export-client_arm32" }
-```
+- **TA binary**:
+ `ta/target/aarch64-unknown-linux-gnu/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta`
+- **CA binary**: `host/target/aarch64-unknown-linux-gnu/release/hello_world-rs`
-**Allowed entries:**
-- `arch`: Target architecture (`"aarch64"` or `"arm"`)
-- `debug`: Build in debug mode (`true` or `false`)
-- `uuid-path`: Relative or absolute path to UUID file (required for plugins)
-- `optee-client-export`: Architecture-specific paths to OP-TEE client export (required)
+#### Next Steps
+
+After building, you can:
+1. Use the `sync_to_emulator` command to sync build artifacts to the emulator
+ environment
+2. Start the QEMU emulator for testing
+3. Refer to the [QEMU emulation guide](../docs/emulate-and-dev-in-docker.md) for
+ complete development and testing workflows
+
+> 💡 **Tip**: If you configure metadata in `Cargo.toml` (see [Configuration
+> System](#configuration-system)), you can simplify build commands by only
+> specifying `--manifest-path`.
+
+## Configuration System
+
+`cargo-optee` uses a flexible configuration system with the following priority
+(highest to lowest):
+
+1. **Command Line Arguments** - Direct CLI flags override everything (see [Build
+ through CLI](#build-through-cli))
+2. **Cargo.toml Metadata** - Project-specific configuration in
+ `[package.metadata.optee.*]` sections (see [Build through
+ metadata](#build-through-metadata))
+3. **Defaults** - Built-in sensible defaults
+
+This allows projects to define their standard configuration in `Cargo.toml`
+while still permitting CLI overrides for specific builds.
### Project Structure
@@ -159,10 +204,85 @@ project/
└── lib.rs
```
-See examples in the SDK for reference, such as `hello_world-rs`.
-The `cargo new` command (planned, not yet available) will generate a project template with this structure. For now, copy an existing example as a starting point.
+See examples in the SDK for reference, such as `hello_world-rs`. The `cargo new`
+command (planned, not yet available) will generate a project template with this
+structure. For now, copy an existing example as a starting point.
+
+### Usage Workflows (including future design)
+
+#### Development/Emulation Environment
+
+For development and emulation, developers would like to build the one project
+and deploy to a target filesystem (e.g. QEMU shared folder) quickly. Frequent
+builds and quick rebuilds are common.
+
+**Using CLI arguments:**
+```bash
+# 1. Create new project (future)
+cargo-optee new my_app
+cd my_app
+
+# 2. Build TA and CA
+cargo-optee build ta \
+ --ta-dev-kit-dir $TA_DEV_KIT_DIR \
+ --manifest-path ./ta/Cargo.toml \
+ --arch aarch64 \
+ --std
+
+cargo-optee build ca \
+ --optee-client-export $OPTEE_CLIENT_EXPORT \
+ --manifest-path ./host/Cargo.toml \
+ --arch aarch64
+
+# 3. Install to specific folder (future), e.g. QEMU shared folder for emulation
+cargo-optee install --target /tmp/qemu-shared-folder
+```
+
+**Using metadata configuration:**
+```bash
+# 1. Configure once in Cargo.toml files, then simple builds
+cd ta && cargo-optee build ta
+cd ../host && cargo-optee build ca
+
+# 2. Override specific parameters when needed
+cd ta && cargo-optee build ta --debug # Override to debug build
+cd host && cargo-optee build ca --arch arm # Override architecture
+```
+
+#### Production/CI Environment
+
+For production and CI environments, artifacts should be cleaned up after
+successful builds. It can help to avoid storage issues on CI runners.
+
+**Automated Build Pipeline:**
+```bash
+#!/bin/bash
+# CI build script
+
+set -e
+
+# Build TA (release mode)
+cargo-optee build ta \
+ --ta-dev-kit-dir $TA_DEV_KIT_DIR \
+ --manifest-path ./ta/Cargo.toml \
+ --arch aarch64 \
+ --std \
+ --signing-key ./keys/production.pem
+
+# Build CA (release mode)
+cargo-optee build ca \
+ --optee-client-export $OPTEE_CLIENT_EXPORT \
+ --manifest-path ./host/Cargo.toml \
+ --arch aarch64
+
+# Install to staging area (future)
+cargo-optee install --target ./dist
+
+# Clean build artifacts to save space (future)
+cargo-optee clean --all
+```
-### Build Commands
+### Build through CLI
#### Build Trusted Application (TA)
@@ -179,7 +299,8 @@ cargo-optee build ta \
```
**Required:**
-- `--ta-dev-kit-dir <PATH>`: Path to OP-TEE TA development kit (available after building OP-TEE OS), user must provide this for building TAs.
+- `--ta-dev-kit-dir <PATH>`: Path to OP-TEE TA development kit (available after
+ building OP-TEE OS), user must provide this for building TAs.
**Optional:**
- `--manifest-path <PATH>`: Path to Cargo.toml manifest file
@@ -187,8 +308,10 @@ cargo-optee build ta \
- `aarch64`: ARM 64-bit architecture
- `arm`: ARM 32-bit architecture
- `--std`: Build with std support (uses xargo and custom target)
-- `--no-std`: Build without std support (uses cargo, mutually exclusive with --std)
-- `--signing-key <PATH>`: Path to signing key (default: `<ta-dev-kit-dir>/keys/default_ta.pem`)
+- `--no-std`: Build without std support (uses cargo, mutually exclusive with
+ --std)
+- `--signing-key <PATH>`: Path to signing key (default:
+ `<ta-dev-kit-dir>/keys/default_ta.pem`)
- `--uuid-path <PATH>`: Path to UUID file (default: `../uuid.txt`)
- `--debug`: Build in debug mode (default: release mode)
@@ -229,7 +352,9 @@ cargo-optee build ca \
```
**Required:**
-- `--optee-client-export <PATH>`: Path to OP-TEE client library directory (available after building OP-TEE client), user must provide this for building CAs.
+- `--optee-client-export <PATH>`: Path to OP-TEE client library directory
+ (available after building OP-TEE client), user must provide this for building
+ CAs.
**Optional:**
- `--manifest-path <PATH>`: Path to Cargo.toml manifest file
@@ -262,7 +387,9 @@ cargo-optee build plugin \
```
**Required:**
-- `--optee-client-export <PATH>`: Path to OP-TEE client library directory (available after building OP-TEE client), user must provide this for building plugins.
+- `--optee-client-export <PATH>`: Path to OP-TEE client library directory
+ (available after building OP-TEE client), user must provide this for building
+ plugins.
- `--uuid-path <PATH>`: Path to UUID file for naming the plugin
**Optional:**
@@ -283,77 +410,70 @@ cargo-optee build plugin \
**Output:**
- Plugin binary: `target/<target-triple>/release/<uuid>.plugin.so`
-### Usage Workflows (including future design)
-
-#### Development/Emulation Environment
-
-For development and emulation, developers would like to build the one project and deploy to a target filesystem (e.g. QEMU shared folder) quickly. Frequent builds and quick rebuilds are common.
+### Build through metadata
-**Using CLI arguments:**
-```bash
-# 1. Create new project (future)
-cargo-optee new my_app
-cd my_app
-
-# 2. Build TA and CA
-cargo-optee build ta \
- --ta-dev-kit-dir $TA_DEV_KIT_DIR \
- --manifest-path ./ta/Cargo.toml \
- --arch aarch64 \
- --std
-
-cargo-optee build ca \
- --optee-client-export $OPTEE_CLIENT_EXPORT \
- --manifest-path ./host/Cargo.toml \
- --arch aarch64
-
-# 3. Install to specific folder (future), e.g. QEMU shared folder for emulation
-cargo-optee install --target /tmp/qemu-shared-folder
-```
+#### Trusted Application (TA) Metadata
-**Using metadata configuration:**
-```bash
-# 1. Configure once in Cargo.toml files, then simple builds
-cd ta && cargo-optee build ta
-cd ../host && cargo-optee build ca
+Configure TA builds in your `Cargo.toml`:
-# 2. Override specific parameters when needed
-cd ta && cargo-optee build ta --debug # Override to debug build
-cd host && cargo-optee build ca --arch arm # Override architecture
+```toml
+[package.metadata.optee.ta]
+arch = "aarch64" # Target architecture: "aarch64" | "arm" (optional, default: "aarch64")
+debug = false # Debug build: true | false (optional, default: false)
+std = false # Use std library: true | false (optional, default: false)
+uuid-path = "../uuid.txt" # Path to UUID file (optional, default: "../uuid.txt")
+# Architecture-specific configuration (omitted architectures default to null/unsupported)
+ta-dev-kit-dir = { aarch64 = "/opt/optee/export-ta_arm64", arm = "/opt/optee/export-ta_arm32" }
+signing-key = "/path/to/key.pem" # Path to signing key (optional, defaults to ta-dev-kit/keys/default_ta.pem)
```
-#### Production/CI Environment
+**Allowed entries:**
+- `arch`: Target architecture (`"aarch64"` or `"arm"`)
+- `debug`: Build in debug mode (`true` or `false`)
+- `std`: Enable std library support (`true` or `false`)
+- `uuid-path`: Relative or absolute path to UUID file
+- `ta-dev-kit-dir`: Architecture-specific paths to TA development kit (required)
+- `signing-key`: Path to signing key file
-For production and CI environments, artifacts should be cleaned up after successful builds. It can help to avoid storage issues on CI runners.
+#### Client Application (CA) Metadata
-**Automated Build Pipeline:**
-```bash
-#!/bin/bash
-# CI build script
+Configure CA builds in your `Cargo.toml`:
-set -e
+```toml
+[package.metadata.optee.ca]
+arch = "aarch64" # Target architecture: "aarch64" | "arm" (optional, default: "aarch64")
+debug = false # Debug build: true | false (optional, default: false)
+# Architecture-specific configuration
+# if your CA only supports aarch64, you can omit arm
+optee-client-export = { aarch64 = "/opt/optee/export-client_arm64" }
+```
-# Build TA (release mode)
-cargo-optee build ta \
- --ta-dev-kit-dir $TA_DEV_KIT_DIR \
- --manifest-path ./ta/Cargo.toml \
- --arch aarch64 \
- --std \
- --signing-key ./keys/production.pem
+**Allowed entries:**
+- `arch`: Target architecture (`"aarch64"` or `"arm"`)
+- `debug`: Build in debug mode (`true` or `false`)
+- `optee-client-export`: Architecture-specific paths to OP-TEE client export
+ (required)
-# Build CA (release mode)
-cargo-optee build ca \
- --optee-client-export $OPTEE_CLIENT_EXPORT \
- --manifest-path ./host/Cargo.toml \
- --arch aarch64
+#### Plugin Metadata
-# Install to staging area (future)
-cargo-optee install --target ./dist
+Configure plugin builds in your `Cargo.toml`:
-# Clean build artifacts to save space (future)
-cargo-optee clean --all
+```toml
+[package.metadata.optee.plugin]
+arch = "aarch64" # Target architecture: "aarch64" | "arm" (optional, default: "aarch64")
+debug = false # Debug build: true | false (optional, default: false)
+uuid-path = "../plugin_uuid.txt" # Path to UUID file (required for plugins)
+# Architecture-specific configuration
+optee-client-export = { aarch64 = "/opt/optee/export-client_arm64", arm = "/opt/optee/export-client_arm32" }
```
+**Allowed entries:**
+- `arch`: Target architecture (`"aarch64"` or `"arm"`)
+- `debug`: Build in debug mode (`true` or `false`)
+- `uuid-path`: Relative or absolute path to UUID file (required for plugins)
+- `optee-client-export`: Architecture-specific paths to OP-TEE client export
+ (required)
+
## Implementation Status
| Feature | Status | Notes |
@@ -452,7 +572,8 @@ python3 /opt/optee/export-ta_arm32/scripts/sign_encrypt.py \
--out target/arm-unknown-optee/release/<uuid>.ta
```
-**Note:** `/tmp/cargo-optee-XXXXX` is a temporary directory containing the embedded `arm-unknown-optee.json` target specification.
+**Note:** `/tmp/cargo-optee-XXXXX` is a temporary directory containing the
+embedded `arm-unknown-optee.json` target specification.
##### Example 3: Build aarch64 CA (Client Application)
@@ -485,7 +606,8 @@ aarch64-linux-gnu-objcopy --strip-unneeded \
#### Build Command Convention: Cargo to Low-Level Tools
-This section explains how cargo orchestrates low-level tools to build the TA ELF binary. We use an aarch64 no-std TA as an example.
+This section explains how cargo orchestrates low-level tools to build the TA ELF
+binary. We use an aarch64 no-std TA as an example.
**Dependency Structure:**
```
@@ -527,7 +649,8 @@ Cargo inherits from cargo-optee:
- `TA_DEV_KIT_DIR=/opt/optee/export-ta_arm64`
- `RUSTFLAGS="-C panic=abort"`
-Cargo then executes build scripts in dependency order to set up the build directives:
+Cargo then executes build scripts in dependency order to set up the build
+directives:
1. **`optee_utee_sys/build.rs`**
- Requires: `TA_DEV_KIT_DIR`
@@ -541,7 +664,8 @@ Cargo then executes build scripts in dependency order to set up the build direct
2. **`ta/build.rs`** → calls **`optee_utee_build`** crate
- Requires: `TA_DEV_KIT_DIR`, `TARGET`, `OUT_DIR`, `RUSTC_LINKER`
- - Optional: `CARGO_PKG_VERSION`, `CARGO_PKG_DESCRIPTION` (for automatic TA config)
+ - Optional: `CARGO_PKG_VERSION`, `CARGO_PKG_DESCRIPTION` (for automatic TA
+ config)
- Actions:
1. Generates TA manifest (`user_ta_header.rs`) with TA properties
2. Outputs linker directives based on target architecture and linker type
diff --git a/docs/emulate-and-dev-in-docker-std.md b/docs/emulate-and-dev-in-docker-std.md
index a6ce3b3..08e6972 100644
--- a/docs/emulate-and-dev-in-docker-std.md
+++ b/docs/emulate-and-dev-in-docker-std.md
@@ -4,21 +4,27 @@ permalink: /trustzone-sdk-docs/emulate-and-dev-in-docker-std.md
# 🚀 Developing TAs with Rust Standard Library in Docker
-This guide covers the **dev-env with std support** that enables **developing TA using Rust standard library (std)**,
-compared to the regular no-std environment documented in [emulate-and-dev-in-docker.md](emulate-and-dev-in-docker.md).
+This guide covers the **dev-env with std support** that enables **developing TA
+using Rust standard library (std)**, compared to the regular no-std environment
+documented in [emulate-and-dev-in-docker.md](emulate-and-dev-in-docker.md).
-The **dev-env with std support** provides a complete setup for building TAs that can use Rust's standard library
-features like collections, networking, etc.
+The **dev-env with std support** provides a complete setup for building TAs that
+can use Rust's standard library features like collections, networking, etc.
-> 📖 **Prerequisites**: Read the [original Docker development guide](emulate-and-dev-in-docker.md)
-> first. This document focuses only on std-specific differences and capabilities.
+> 📖 **Prerequisites**: Read the [original Docker development
+> guide](emulate-and-dev-in-docker.md) first. This document focuses only on
+> std-specific differences and capabilities.
## What the Dev-Env with Std Support Provides
-The **dev-env with std support** enables **developing TA using Rust std** by providing:
-- **Flexible configuration management** - Switch between std/no-std modes and architectures dynamically
-- **Rust standard library tailored for OP-TEE** - Build TAs using collections, networking, serialization capabilities
-- **Mixed development support** - Combine different host and TA architectures, including switching between no-std/std in the same project
+The **dev-env with std support** enables **developing TA using Rust std** by
+providing:
+- **Flexible configuration management** - Switch between std/no-std modes and
+ architectures dynamically
+- **Rust standard library tailored for OP-TEE** - Build TAs using collections,
+ networking, serialization capabilities
+- **Mixed development support** - Combine different host and TA architectures,
+ including switching between no-std/std in the same project
## 1. Setting Up the Dev-Env with Std Support
@@ -41,15 +47,17 @@ $ docker run -it --rm \
$ ln -s $RUST_STD_DIR rust
```
-> 📝 **Note**: This symlink is required for current SDK examples due to hardcoded std dependency paths in Cargo.toml.
-> Your own projects may organize std files differently.
+> 📝 **Note**: This symlink is required for current SDK examples due to
+> hardcoded std dependency paths in Cargo.toml. Your own projects may organize
+> std files differently.
## 2. Configuration Management System
-The key difference is the **unified configuration system** that allows switching between std/no-std
-modes and different architectures on demand.
+The key difference is the **unified configuration system** that allows switching
+between std/no-std modes and different architectures on demand.
-And cargo-optee is available as an alternative to the original configuration management tool: switch_config.
+And [cargo-optee](../cargo-optee/README.md#configuration-system) is available as
+an alternative to the original configuration management tool: switch_config.
### If you use switch_config:
@@ -86,12 +94,14 @@ $ switch_config --host arm32 && switch_config --ta std/aarch64
### If you use cargo-optee:
-You can see the [cargo-optee configuration system](../cargo-optee/README.md#configuration-system) for details.
+You can see the [cargo-optee configuration
+system](../cargo-optee/README.md#configuration-system) for details.
## 3. Building and Target Differences
-Follow the [original building instructions](emulate-and-dev-in-docker.md#2-build-the-hello-world-example),
-but note these important target differences:
+Follow the [original building
+instructions](emulate-and-dev-in-docker.md#2-build-the-hello-world-example), but
+note these important target differences:
| Configuration | TA Target | Build Tool | Host Target |
|---------------|-----------|------------|-------------|
@@ -129,12 +139,13 @@ $ make clean && make
TA=ta/target/aarch64-unknown-linux-gnu/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta
```
-If you are using cargo-optee, the relevant workflow is already clearly
-documented in the [cargo-optee appendix](../cargo-optee/README.md#appendix),
-so it will not be repeated here.
+If you are using cargo-optee, the relevant workflow is already clearly
+documented in the [cargo-optee appendix](../cargo-optee/README.md#appendix), so
+it will not be repeated here.
## 5. Emulation and Execution
-The emulation process is identical to the no-std environment.
-Follow [sections 3-6 of the original guide](emulate-and-dev-in-docker.md#3-make-the-artifacts-accessible-to-the-emulator)
+The emulation process is identical to the no-std environment. Follow [sections
+3-6 of the original
+guide](emulate-and-dev-in-docker.md#3-make-the-artifacts-accessible-to-the-emulator)
for complete emulation setup instructions.
\ No newline at end of file
diff --git a/docs/emulate-and-dev-in-docker.md b/docs/emulate-and-dev-in-docker.md
index f1ddedc..839b0a9 100644
--- a/docs/emulate-and-dev-in-docker.md
+++ b/docs/emulate-and-dev-in-docker.md
@@ -7,8 +7,8 @@ permalink: /trustzone-sdk-docs/emulate-and-dev-in-docker.md
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
+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.
@@ -33,8 +33,9 @@ $ docker run -it --rm \
## 2. Build the Hello World Example
-Update: cargo-optee is available as an alternative to the original Makefile system.
-See the [cargo-optee documentation](../cargo-optee/README.md) for details.
+Update: cargo-optee is available as an alternative to the original Makefile
+system. See the [cargo-optee documentation](../cargo-optee/README.md) for
+details.
### If you use Makefile:
@@ -44,8 +45,8 @@ See the [cargo-optee documentation](../cargo-optee/README.md) for details.
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:
+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
@@ -53,7 +54,8 @@ HOST_APP=host/target/aarch64-unknown-linux-gnu/release/hello_world-rs
### If you use cargo-optee:
-You can see the [cargo-optee build commands](../cargo-optee/README.md#build-commands) for details.
+You can see the [cargo-optee build
+commands](../cargo-optee/README.md#build-commands) for details.
## 3. Make the Artifacts Accessible to the Emulator
After building the Hello World example, the next step is to make the compiled
@@ -62,12 +64,13 @@ 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 (only when you use Makefile for building)
+- ⚙️ **Makefile integration**: Use `make emulate` to build and sync in one step
+ (only when you use Makefile for building)
#### 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:
+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
@@ -75,20 +78,23 @@ sync_to_emulator --host $HOST_APP
Run `sync_to_emulator -h` for more usage options.
#### Option 2: Integrate sync with TA's Makefile
-For convenience during daily development, the sync invocation can be integrated into
-the Makefile. In the `hello_world-rs` example, an `emulate` target is provided.
-This helps automatically build the artifacts and sync them to the emulator in one step:
+For convenience during daily development, the sync invocation can be integrated
+into the Makefile. In the `hello_world-rs` example, an `emulate` target is
+provided. This helps automatically build the artifacts and sync them to the
+emulator in one step:
```bash
make -C examples/hello_world-rs/ emulate
```
## 4. Multi-Terminal Execution
-The emulation workflow requires three additional terminals to monitor
-various aspects of the system:
+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 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
@@ -124,18 +130,17 @@ After the listeners are set up, we can start the QEMU emulator.
$ 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.
+> ⏳ **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 find that the artifacts synced in **Step 3** are already
-available in the current working directory. Additionally, the `ta/` and
-`plugin/` subdirectories are automatically mounted to be used by TEE OS during
-TA execution and plugin loading.
+**Terminal B** (Inside Guest VM): From this shell, you'll find that the
+artifacts synced in **Step 3** are already available in the current working
+directory. Additionally, the `ta/` and `plugin/` subdirectories are
+automatically mounted to be used by TEE OS during TA execution and plugin
+loading.
For more details on the mount configuration, refer to the
`listen_on_guest_vm_shell` command in the development environment.
@@ -159,29 +164,31 @@ Now we are ready to interact with the TA from normal world shell.
# Execute the Hello World Client Application
$ ./host/hello_world-rs
```
-The secure world logs, including TA debug messages, are displayed in **Terminal C**.
+The secure world logs, including TA debug messages, are displayed in **Terminal
+C**.
## 6. Iterative Development with Frequent Code Updates and Execution
-During active development and debugging, you can leave Terminals B, C, and D open to
-avoid restarting them each time. Simply return to Terminal A, and repeat Step 2 (build)
-and Step 3 (sync) to rebuild and update the artifacts. Once synced, switch to
-Terminal B to re-run the client application. This setup streamlines iterative
-development and testing.
+During active development and debugging, you can leave Terminals B, C, and D
+open to avoid restarting them each time. Simply return to Terminal A, and repeat
+Step 2 (build) and Step 3 (sync) to rebuild and update the artifacts. Once
+synced, switch to Terminal B to re-run the client application. This setup
+streamlines iterative development and testing.
## Summary
-By following this guide, you can emulate and debug Trusted Applications using our
-pre-configured Docker-based development environment.
+By following this guide, you can emulate and debug Trusted Applications using
+our pre-configured Docker-based development environment.
-- **Terminal A** serves as the main interface for building and syncing artifacts.
-- **Terminal B** gives access to the normal world inside the guest VM, where you
+- **Terminal A** serves as the main interface for building and syncing
+ artifacts.
+- **Terminal B** gives access to the normal world inside the guest VM, where you
can run client applications like the Hello World example.
-- **Terminal C** captures logs and debug output from the secure world, making it
+- **Terminal C** captures logs and debug output from the secure world, making it
easy to trace TA behavior.
-- **Terminal D** controls the QEMU emulator and shows system-level logs during
+- **Terminal D** controls the QEMU emulator and shows system-level logs during
boot and runtime.
-Together, these terminals provide a complete and efficient workflow for TrustZone
-development and emulation.
+Together, these terminals provide a complete and efficient workflow for
+TrustZone development and emulation.
### Development Environment Details
The setup scripts and built-in commands can be found in `/opt/teaclave/`. Please
diff --git a/examples/hello_world-rs/ta/Cargo.toml b/examples/hello_world-rs/ta/Cargo.toml
index 0148c45..e3ba323 100644
--- a/examples/hello_world-rs/ta/Cargo.toml
+++ b/examples/hello_world-rs/ta/Cargo.toml
@@ -40,11 +40,3 @@ optee-utee-build = { path = "../../../optee-utee-build" }
[profile.release]
lto = true
opt-level = 1
-
-[package.metadata.optee.ta]
-arch = "aarch64"
-debug = false
-std = false
-uuid-path = "../uuid.txt"
-ta-dev-kit-dir = { aarch64 = "/opt/teaclave/optee/optee_os/out/arm-plat-vexpress/export-ta_arm64", arm = "/opt/teaclave/optee/optee_os/out/arm-plat-vexpress/export-ta_arm32" }
-signing-key = "/opt/teaclave/optee/optee_os/out/arm-plat-vexpress/export-ta_arm64/keys/default_ta.pem"
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@teaclave.apache.org
For additional commands, e-mail: commits-help@teaclave.apache.org