From 62dc83fb338951855456a067ea95118f2ef12b9b Mon Sep 17 00:00:00 2001
From: ivila <390810839@qq.com>
Date: Thu, 17 Sep 2026 16:28:17 +0800
Subject: [PATCH] docs: fix quickstart Hello World commands, paths and links

The quickstart referenced examples/hello_world-rs/ which no longer
exists (examples are split into examples/ca/ and examples/ta/),
pointed at ../cargo-optee/README.md instead of
../tools/cargo-optee/README.md, used a non-existent
#build-commands anchor, and listed stale ta/target and host/target
artifact paths.

Use the verified top-level build (make -C examples hello_world-rs),
correct workspace target paths, per-crate emulate targets, and add
expected build/run output verified end-to-end in QEMU.
---
 docs/emulate-and-dev-in-docker-std.md | 17 ++++----
 docs/emulate-and-dev-in-docker.md     | 59 +++++++++++++++++++--------
 tools/cargo-optee/README.md           | 34 ++++++++-------
 3 files changed, 71 insertions(+), 39 deletions(-)

diff --git a/docs/emulate-and-dev-in-docker-std.md b/docs/emulate-and-dev-in-docker-std.md
index 624d2928..f270818a 100644
--- a/docs/emulate-and-dev-in-docker-std.md
+++ b/docs/emulate-and-dev-in-docker-std.md
@@ -56,7 +56,7 @@ $ ln -s $RUST_STD_DIR rust
 The key difference is the **unified configuration system** that allows switching
 between std/no-std modes and different architectures on demand.
 
-And [cargo-optee](../cargo-optee/README.md#configuration-system) is available as
+And [cargo-optee](../tools/cargo-optee/README.md#configuration-system) is available as
 an alternative to the original configuration management tool: switch_config.
 
 ### If you use switch_config:
@@ -95,7 +95,7 @@ $ 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.
+system](../tools/cargo-optee/README.md#configuration-system) for details.
 
 ## 3. Building and Target Differences
 
@@ -110,21 +110,20 @@ note these important target differences:
 
 **Example std build output:**
 ```bash
-TA=ta/target/aarch64-unknown-optee/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta
+TA=examples/ta/target/aarch64-unknown-optee/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta
 ```
 
 ## 4. Hello World Example: Std vs No-Std
 
 ### Build with Default Std Configuration
 ```bash
-# Build hello world with std/aarch64 (default configuration)
-$ cd examples/hello_world-rs/
-$ make
+# From the repository root: build hello world with std/aarch64 (default configuration)
+$ make -C examples hello_world-rs
 ```
 
 **Result:** TA built with std enabled, targeting `aarch64-unknown-optee`:
 ```bash
-TA=ta/target/aarch64-unknown-optee/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta
+TA=examples/ta/target/aarch64-unknown-optee/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta
 ```
 
 ### Switch to No-Std and Rebuild
@@ -136,11 +135,11 @@ $ make clean && make
 
 **Result:** TA now targets `aarch64-unknown-linux-gnu` (no-std):
 ```bash
-TA=ta/target/aarch64-unknown-linux-gnu/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta
+TA=examples/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
+documented in the [cargo-optee appendix](../tools/cargo-optee/README.md#appendix), so
 it will not be repeated here.
 
 ## 5. Emulation and Execution
diff --git a/docs/emulate-and-dev-in-docker.md b/docs/emulate-and-dev-in-docker.md
index 839b0a92..d2110ee3 100644
--- a/docs/emulate-and-dev-in-docker.md
+++ b/docs/emulate-and-dev-in-docker.md
@@ -34,28 +34,39 @@ $ 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
+system. See the [cargo-optee documentation](../tools/cargo-optee/README.md) for
 details.
 
 ### If you use Makefile:
 
-**Still in Terminal A** (inside the Docker container):
+**Still in Terminal A** (inside the Docker container, at the repository root):
 ```bash
 # Build the Hello World example (both CA and TA)
-make -C examples/hello_world-rs/
+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:
+Under the hood, the top-level `examples/Makefile` builds both the Trusted
+Application (TA) and the Client Application (CA) separately. The example is
+split across two crates: the CA crate lives in `examples/ca/hello_world-rs/`
+and the TA crate lives in `examples/ta/hello_world-rs/`. After a successful
+build, you'll find the resulting binaries in the shared workspace target
+directories:
 ```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
+TA=examples/ta/target/aarch64-unknown-linux-gnu/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta
+HOST_APP=examples/ca/target/aarch64-unknown-linux-gnu/release/hello_world-rs
+```
+A successful build ends with the TA signing step, e.g.:
+```text
+SIGN =>  133af0ca-bdab-11eb-9130-43bf7873bf67
+```
+You can verify both artifacts exist before moving on:
+```bash
+ls $TA $HOST_APP
 ```
 
 ### 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 Quick Build for Hello
+World](../tools/cargo-optee/README.md#quick-build-for-hello-world) for details.
 
 ## 3. Make the Artifacts Accessible to the Emulator
 After building the Hello World example, the next step is to make the compiled
@@ -77,13 +88,14 @@ sync_to_emulator --host $HOST_APP
 ```
 Run `sync_to_emulator -h` for more usage options.
 
-#### Option 2: Integrate sync with TA's Makefile
+#### Option 2: Integrate sync with the example Makefiles
 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:
+into the Makefiles. Both the CA crate (`examples/ca/hello_world-rs`) and the TA
+crate (`examples/ta/hello_world-rs`) provide an `emulate` target, which builds
+the artifacts and syncs them to the emulator in one step:
 ```bash
-make -C examples/hello_world-rs/ emulate
+make -C examples/ca/hello_world-rs emulate
+make -C examples/ta/hello_world-rs emulate
 ```
 
 ## 4. Multi-Terminal Execution
@@ -164,8 +176,23 @@ Now we are ready to interact with the TA from normal world shell.
 # Execute the Hello World Client Application
 $ ./host/hello_world-rs
 ```
+Expected output in **Terminal B** (normal world):
+```text
+original value is 29
+inc value is 129
+dec value is 29
+Success
+```
 The secure world logs, including TA debug messages, are displayed in **Terminal
-C**.
+C**. You should see the TA lifecycle and command traces there, e.g.:
+```text
+[+] TA create
+[+] TA open session
+[+] TA invoke command
+[+] TA invoke command
+[+] TA close session
+[+] TA destroy
+```
 
 ## 6. Iterative Development with Frequent Code Updates and Execution
 During active development and debugging, you can leave Terminals B, C, and D
diff --git a/tools/cargo-optee/README.md b/tools/cargo-optee/README.md
index 16e68ec5..46e659e9 100644
--- a/tools/cargo-optee/README.md
+++ b/tools/cargo-optee/README.md
@@ -76,7 +76,7 @@ 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).
+guide](../../docs/emulate-and-dev-in-docker.md).
 
 #### Prerequisites
 
@@ -100,17 +100,17 @@ docker run -it --rm \
 
 > 📖 **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
+> support](../../docs/emulate-and-dev-in-docker-std.md) and use the
 > `teaclave/teaclave-trustzone-emulator-std-expand-memory:latest` image.
 
 #### Build Steps
 
-**1. Navigate to the Hello World example directory**
+**1. Work from the repository root**
 
-Inside the Docker container, execute:
-```bash
-cd examples/hello_world-rs/
-```
+Inside the Docker container, all paths below are relative to the repository
+root. The Hello World example is split across two crates:
+- TA crate: `examples/ta/hello_world-rs/`
+- CA crate: `examples/ca/hello_world-rs/`
 
 **2. Build the Trusted Application (TA)**
 
@@ -121,7 +121,7 @@ development kit is typically located at
 ```bash
 # Build aarch64 no-std TA (default configuration)
 cargo-optee build ta \
-  --manifest-path ta/Cargo.toml \
+  --manifest-path examples/ta/hello_world-rs/Cargo.toml \
   --ta-dev-kit-dir /opt/teaclave/optee/optee_os/out/arm-plat-vexpress/export-ta_arm64 \
   --arch aarch64 \
   --no-std
@@ -133,7 +133,7 @@ Build the client application:
 ```bash
 # Build aarch64 CA
 cargo-optee build ca \
-  --manifest-path host/Cargo.toml \
+  --manifest-path examples/ca/hello_world-rs/Cargo.toml \
   --optee-client-export /opt/teaclave/optee/optee_client/export_arm64 \
   --arch aarch64
 ```
@@ -142,7 +142,7 @@ cargo-optee build ca \
 > [Configuration System](#configuration-system)), you can simplify the command
 > by only specifying `--manifest-path`:
 > ```bash
-> cargo-optee build ca --manifest-path host/Cargo.toml
+> cargo-optee build ca --manifest-path examples/ca/hello_world-rs/Cargo.toml
 > ```
 
 #### Build Output
@@ -151,8 +151,9 @@ After a successful build, you can find the generated files at the following
 locations:
 
 - **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`
+  `examples/ta/target/aarch64-unknown-linux-gnu/release/133af0ca-bdab-11eb-9130-43bf7873bf67.ta`
+- **CA binary**:
+  `examples/ca/target/aarch64-unknown-linux-gnu/release/hello_world-rs`
 
 #### Next Steps
 
@@ -160,7 +161,7 @@ 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
+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
@@ -204,7 +205,12 @@ project/
         └── lib.rs
 ```
 
-See examples in the SDK for reference, such as `hello_world-rs`. The `cargo new`
+See examples in the SDK for reference, such as `hello_world-rs`. Note that in
+this SDK's `examples/` directory the layout is split by side instead of by
+project: the TA crate lives in `examples/ta/hello_world-rs/` (with `uuid.txt`
+next to it), the CA crate lives in `examples/ca/hello_world-rs/` (named `ca/`
+rather than `host/`), and the shared definitions live in the workspace crate
+`examples/ta/proto`. 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.