doc: polish migration guide

docs/migrating-to-new-building-env.md

@@ -11,45 +11,182 @@ to follow these steps to migrate their TA to the new environment.
 
 ### Step 1: Migrate Old Code to the New Environment
 
-To migrate an example project (e.g., `tls_server-rs` in `examples/`), you 
-can refer to the following shell script and adjust it for your TA:
+1) No need to modify the code of your old application. Keep the `src/` and 
+`Cargo.toml` files and clean up these files in `ta/`: `ta_arm.lds`, 
+`ta_aarch64.lds`, `ta_static.rs`, and `build.rs`.
 
 ```bash
-TARGET_EXAMPLE="tls_server-rs"
-OLD_ROOT_PATH="/path/to/old/sdk"
-NEW_PATH="/path/to/current/sdk"
-
-# Duplicate the hello-world example in the new path as a template
-cp -r ${NEW_PATH}/examples/hello_world-rs ${NEW_PATH}/examples/${TARGET_EXAMPLE}
-
-# Remove the source code directory and copy from the old path to the new path
-# including: src/ and Cargo.toml in host, ta, proto
-(cd ${NEW_PATH}/examples/${TARGET_EXAMPLE}/host && rm -rf src/ Cargo.* && \
-cp -r ${OLD_ROOT_PATH}/examples/${TARGET_EXAMPLE}/host/src . && \
-cp ${OLD_ROOT_PATH}/examples/${TARGET_EXAMPLE}/host/Cargo.toml .)
-(cd ${NEW_PATH}/examples/${TARGET_EXAMPLE}/ta && rm -rf src/ Cargo.* && \
-cp -r ${OLD_ROOT_PATH}/examples/${TARGET_EXAMPLE}/ta/src . && \
-cp ${OLD_ROOT_PATH}/examples/${TARGET_EXAMPLE}/ta/Cargo.toml .)
-(cd ${NEW_PATH}/examples/${TARGET_EXAMPLE}/proto && rm -rf src/ Cargo.* && \
-cp -r ${OLD_ROOT_PATH}/examples/${TARGET_EXAMPLE}/proto/src . && \
-cp ${OLD_ROOT_PATH}/examples/${TARGET_EXAMPLE}/proto/Cargo.toml .)
-
-# Copy the UUID file from the old path to the new path
-cp ${OLD_ROOT_PATH}/examples/${TARGET_EXAMPLE}/uuid.txt \
-${NEW_PATH}/examples/${TARGET_EXAMPLE}/uuid.txt
-
-# Update binary names in host/Cargo.toml and host/Makefile
-sed -i "s/hello_world-rs/${TARGET_EXAMPLE}/g" \
-${NEW_PATH}/examples/${TARGET_EXAMPLE}/host/Cargo.toml
-sed -i "s/hello_world-rs/${TARGET_EXAMPLE}/g" \
-${NEW_PATH}/examples/${TARGET_EXAMPLE}/host/Makefile
+$ (cd ta/ && rm ta_arm.lds ta_aarch64.lds ta_static.rs build.rs)
+```
+
+2) Copy the current `ta_static.rs` and `build.rs` from other examples. 
+Since they are the same for all examples, you can copy them from 
+another example, such as hello-world.
+
+```bash
+$ HELLO_WORLD_PATH=/path/to/current/sdk/examples/hello_world-rs/
+$ (cd ta/ && cp $HELLO_WORLD_PATH/ta/build.rs . && cp $HELLO_WORLD_PATH/ta/ta_static.rs .)
+```
+
+3) Replace the old Makefiles with the new ones. Since Makefiles are the same 
+for examples, you can copy them from another example (no-std TA refer to 
+`hello_world-rs`, std TA refer to `tls_client-rs`) but don't forget to change
+the binary name in `host/Makefile` and `host/Cargo.toml`. 
+The diff for these Makefiles are (e.g. tls_client example):
+
+```
+diff --git a/examples/tls_client-rs/Makefile b/examples/tls_client-rs/Makefile
+index 09679cd..c266055 100644
+--- a/examples/tls_client-rs/Makefile
++++ b/examples/tls_client-rs/Makefile
+@@ -15,10 +15,19 @@
+ # specific language governing permissions and limitations
+ # under the License.
+ 
++# If _HOST or _TA specific compiler/target are not specified, then use 
++common
++# compiler/target for both
++CROSS_COMPILE_HOST ?= aarch64-linux-gnu-
++CROSS_COMPILE_TA ?= aarch64-linux-gnu-
++TARGET_HOST ?= aarch64-unknown-linux-gnu
++TARGET_TA ?= aarch64-unknown-linux-gnu
++
+ all:
+-	@make -s -C host
+-	@make -s -C ta
++	$(q)make -C host TARGET_HOST=$(TARGET_HOST) \
++		CROSS_COMPILE_HOST=$(CROSS_COMPILE_HOST)
++	$(q)make -C ta TARGET_TA=$(TARGET_TA) \
++		CROSS_COMPILE_TA=$(CROSS_COMPILE_TA)
+ 
+ clean:
+-	@make -s -C host clean
+-	@make -s -C ta clean
++	$(q)make -C host clean
++	$(q)make -C ta clean
+```
+
+```
+diff --git a/examples/tls_client-rs/host/Makefile b/examples/tls_client-rs/host/Makefile
+index 85e49da..7920865 100644
+--- a/examples/tls_client-rs/host/Makefile
++++ b/examples/tls_client-rs/host/Makefile
+@@ -16,32 +16,21 @@
+ # under the License.
+ 
+ NAME := tls_client-rs
+-ARCH ?= aarch64
+ 
+-OPTEE_DIR ?= ../../../optee
++TARGET_HOST ?= aarch64-unknown-linux-gnu
++CROSS_COMPILE_HOST ?= aarch64-linux-gnu-
++OBJCOPY := $(CROSS_COMPILE_HOST)objcopy
++LINKER_CFG := target.$(TARGET_HOST).linker=\"$(CROSS_COMPILE_HOST)gcc\"
+ 
+-ifeq ($(ARCH), arm)
+-	OPTEE_BIN := $(OPTEE_DIR)/toolchains/aarch32/bin
+-	OBJCOPY := $(OPTEE_BIN)/arm-linux-gnueabihf-objcopy
+-	TARGET := arm-unknown-linux-gnueabihf
+-else
+-	OPTEE_BIN := $(OPTEE_DIR)/toolchains/$(ARCH)/bin
+-	OBJCOPY := $(OPTEE_BIN)/aarch64-linux-gnu-objcopy
+-	TARGET := aarch64-unknown-linux-gnu
+-endif
+-
+-OUT_DIR := $(CURDIR)/target/$(TARGET)/release
++OUT_DIR := $(CURDIR)/target/$(TARGET_HOST)/release
+ 
+ 
+ all: host strip
+ 
+ host:
+-	@cargo build --target $(TARGET) --release
+-
+-fmt:
+-	@cargo fmt
++	@cargo build --target $(TARGET_HOST) --release --config $(LINKER_CFG)
+ 
+-strip:
++strip: host
+ 	@$(OBJCOPY) --strip-unneeded $(OUT_DIR)/$(NAME) $(OUT_DIR)/$(NAME)
+ 
+```
+
+```
+diff --git a/examples/tls_client-rs/ta/Makefile b/examples/tls_client-rs/ta/Makefile
+index f7b32fb..74aeb33 100644
+--- a/examples/tls_client-rs/ta/Makefile
++++ b/examples/tls_client-rs/ta/Makefile
+@@ -15,42 +15,36 @@
+ # specific language governing permissions and limitations
+ # under the License.
+ 
+-OPTEE_DIR ?= ../../../optee
+-OPTEE_OS_DIR ?= $(OPTEE_DIR)/optee_os
+-UUID ?= $(shell cat "../uuid.txt")
++# STD-ONLY example
+ 
+-ARCH ?= aarch64
++UUID ?= $(shell cat "../uuid.txt")
+ 
+-ifeq ($(ARCH), arm)
+-	TA_SIGN_KEY ?= $(OPTEE_OS_DIR)/out/arm/export-ta_arm32/keys/default_ta.pem
+-	SIGN := $(OPTEE_OS_DIR)/out/arm/export-ta_arm32/scripts/sign_encrypt.py
+-	OPTEE_BIN := $(OPTEE_DIR)/toolchains/aarch32/bin
+-	OBJCOPY := $(OPTEE_BIN)/arm-linux-gnueabihf-objcopy
+-	TARGET := arm-unknown-optee
+-else
+-	TA_SIGN_KEY ?= $(OPTEE_OS_DIR)/out/arm/export-ta_arm64/keys/default_ta.pem
+-	SIGN := $(OPTEE_OS_DIR)/out/arm/export-ta_arm64/scripts/sign_encrypt.py
+-	OPTEE_BIN := $(OPTEE_DIR)/toolchains/$(ARCH)/bin
+-	OBJCOPY := $(OPTEE_BIN)/aarch64-linux-gnu-objcopy
+-	TARGET := aarch64-unknown-optee
+-endif
++TARGET_TA ?= aarch64-unknown-linux-gnu
++CROSS_COMPILE_TA ?= aarch64-linux-gnu-
++OBJCOPY := $(CROSS_COMPILE_TA)objcopy
++LINKER_CFG := target.$(TARGET_TA).linker=\"$(CROSS_COMPILE_TA)ld.bfd\"
+ 
+-OUT_DIR := $(CURDIR)/target/$(TARGET)/release
++TA_SIGN_KEY ?= $(TA_DEV_KIT_DIR)/keys/default_ta.pem
++SIGN := $(TA_DEV_KIT_DIR)/scripts/sign_encrypt.py
++OUT_DIR := $(CURDIR)/target/$(TARGET_TA)/release
+ 
++ifeq ($(STD),)
++all:
++	@echo "Please export STD=y to build the STD version"
++else
+ all: ta strip sign
++endif
+ 
++# set the cross compile for building inner libraries, such as C libraries in ring
+ ta:
+-	@xargo build --target $(TARGET) --release --verbose
+-
+-fmt:
+-	@cargo fmt
++	@CROSS_COMPILE=$(CROSS_COMPILE_TA) xargo build --target $(TARGET_TA) --release --config $(LINKER_CFG)
+ 
+-strip:
++strip: ta
+ 	@$(OBJCOPY) --strip-unneeded $(OUT_DIR)/ta $(OUT_DIR)/stripped_ta
+ 
+-sign:
++sign: strip
+ 	@$(SIGN) --uuid $(UUID) --key $(TA_SIGN_KEY) --in $(OUT_DIR)/stripped_ta --out $(OUT_DIR)/$(UUID).ta
+ 	@echo "SIGN =>  ${UUID}"
+ 
+ clean:
+-	@xargo clean
++	@cargo clean
 ```
 
 ### Step 2: Update `Cargo.toml`
 
 You may need to update your `Cargo.toml` to use newer versions of crates. 
 The Rust toolchain for the current build environment can be found in 
-`rust-toolchain.toml`.
+`rust-toolchain.toml`. Note that if you upgrade your crates, code 
+modifications may be needed for new interfaces.
 
 ### Step 3: Build and Fix Errors