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/incubator-teaclave-trustzone-sdk.git
commit 7bd1ed46ce4831fcf5e65195ef1a8240251b8f78 Author: Yuan Zhuang <[email protected]> AuthorDate: Fri Oct 18 17:55:21 2024 +0800 Polish migrating-to-new-building-env.md --- docs/migrating-to-new-building-env.md | 135 +++++++++++++++++++++++++++++++--- 1 file changed, 123 insertions(+), 12 deletions(-) diff --git a/docs/migrating-to-new-building-env.md b/docs/migrating-to-new-building-env.md index 6673241..8b2cabc 100644 --- a/docs/migrating-to-new-building-env.md +++ b/docs/migrating-to-new-building-env.md @@ -7,15 +7,87 @@ permalink: /trustzone-sdk-docs/migrating-to-new-building-env.md Since the `main` branch (after October 2024) introduces breaking changes to the build environment, if users of the legacy `master` branch want to keep upstream or use a new version of the Rust toolchain, they will need -to follow these steps to migrate their TA to the new environment. +to migrate their TA to the new environment. -### Step 1: Migrate Old Code to the New Environment +Note that the migration is mainly for building scripts to support both +`no-std` and `std` building for TA, no need for modifying your application +code. -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: +### Changes in Build Scripts + +1. **TA linking script**: `ta_arm.lds` and `ta_aarch64.lds`. + These linking scripts define the low-level TA ELF sections arrangement + (e.g., `.text` section in ELF). They have been removed, and we now use + the `lds` file from OP-TEE's TA dev-kit, for example, located in + `optee_os/out/arm-plat-vexpress/export-ta_arm64/src/ta.ld.S`. This + change helps to stay upstream with OP-TEE OS and makes it more stable + when running on OP-TEE OS. + +2. **`ta_static.rs`**: C FFI primitives, such as `ta_heap_size` and `ta_props`. + This file helps to set TA properties in a C-like manner in the TA ELF + for OP-TEE OS to load. + The change involves modifying imports of primitives, e.g., from + `libc::c_int` to `core::c_int`, and from `std::u64::MAX` to + `core::primitive::u64::MAX`. This helps ensure support for both `no_std` + and `std`-based environments. + +3. **`build.rs`**: + Since TA is not a normal ELF, it has a header before the ELF sections. + This file is the main entry point for building a TA as ELF and adding + the specific header. It uses configurations such as `ta_static.rs`, + `user_ta_header.rs`, and the linking script `ta.ld.S`. It also defines + the linking with OP-TEE's C libraries (`libutee` and `libutils`) from + OP-TEE's TA dev-kit. + + The changes are: + + a. Move linking parameters from the original + [`/.cargo/config`](https://github.com/apache/incubator-teaclave-trustzone-sdk/blob/master/.cargo/config): + This change is primarily designed to accommodate more complex build targets. + For standard TAs, the specific build targets are `aarch64-unknown-optee-trustzone` + and `arm-unknown-optee-trustzone`. + For example, in the no-std mode for aarch64, both no-std TAs and CAs are built + with the `aarch64-unknown-linux-gnu` target. However, in std mode, TAs are + built with the `aarch64-unknown-optee-trustzone` target, while CAs remain + built with the `aarch64-unknown-linux-gnu` target. + This change allows us to decouple TA's linking parameters from the target, as + they are now defined within TA's `build.rs`. + + b. Add `cargo:rustc-link-arg=--no-warn-mismatch` to work around + the EABI version mismatch linking error: symbols.o with EABI version 0 + and other objects are EABI version 5. + +5. **ENV variables**: + The original script for setting the toolchain path has some modifications. + Due to the more complex building options mentioned above, `CROSS_COMPILE_{HOST, TA}` + and `TARGET_{HOST, TA}` should be set by `source environment`. + You should also set whether you want to build in `STD` mode (`export STD=y`) + and specify the target architecture (`ARM32` or `AArch64`) for both CA and TA. + Running `source environment` will set up all toolchains and libraries. + +6. **Makefile Polishing**: + a. Top-level Makefile (`examples/*/Makefile`): Reads the `CROSS_COMPILE_{HOST, TA}` + and `TARGET_{HOST, TA}`. + b. `host/Makefile`: Simplified and polished for the changes in ENV variables. + c. `ta/Makefile`: For `std` TAs, checks if the `STD` environment variable is set, + and further simplifications and polish are done. + +### Step 1: Migrating Projects + +#### Case 1: Default Migration (No Custom Modifications to Build Scripts) +If you have developed based on one of our example structures and haven't +modified the build scripts mentioned above, you can simply copy a current +example and move your code into it. +Note that the `Makefile` for `std` TAs has tiny differences from the `no_std` +one. If you are using a `no_std` TA, refer to `hello_world-rs`. For `std` TAs, +refer to `serde-rs`. + +We provide a shell script to assist with this migration (you may need to make +small adjustments based on whether you are building in `no_std` or `std` mode). +Here is an example for `no_std`: ```bash -TARGET_EXAMPLE="tls_server-rs" +TARGET_EXAMPLE="your_project" OLD_ROOT_PATH="/path/to/old/sdk" NEW_PATH="/path/to/current/sdk" @@ -45,13 +117,52 @@ sed -i "s/hello_world-rs/${TARGET_EXAMPLE}/g" \ ${NEW_PATH}/examples/${TARGET_EXAMPLE}/host/Makefile ``` -### Step 2: Update `Cargo.toml` +#### Case 2: Custom Migration (With Modified Build Scripts) + +If you have made changes to your build scripts, follow the steps below to +manually migrate those files: + +1. **TA linking script `ta_arm.lds` and `ta_aarch64.lds`**: + Usually, developers don't need to modify those files. If you have made any + changes, compare the diff between your file and + `optee_os/out/arm-plat-vexpress/export-ta_{arm64, arm32}/src/ta.ld.S` in the + current SDK. + This `ta.ld.S` file is currently not included in SDK but in OPTEE_OS repo. + +3. **`ta_static.rs`**: + Usually, developers don't need to modify this file. If you have made + modifications to this file, compare them with the latest version here: + [ta_static.rs diff](https://github.com/apache/incubator-teaclave-trustzone-sdk/compare/cd19ac2e1c3cb1a848d5131d4af8138d84be8708..9e3906e9d82f0471e96bf892afe0df37dd90a86e#diff-c0cdd7b28f558bd417069b8e60ed35b70ac1cd01e68e3c0ba6c7311a5a444e22) + +4. **`build.rs`**: + Usually, developers don't need to modify this file. If you have made + changes to link other libraries or dependencies in `build.rs`, compare + the two versions and migrate accordingly: + [build.rs diff](https://github.com/apache/incubator-teaclave-trustzone-sdk/compare/cd19ac2e1c3cb1a848d5131d4af8138d84be8708..9e3906e9d82f0471e96bf892afe0df37dd90a86e#diff-c07432a8a8ecbc1f00799a2bd008bd8dcbba9d58fd0a9e5815b835e4ed425e86) + +5. **Makefiles**: +You may have modified some of the Makefiles. Please compare them +with the current versions to ensure compatibility: + +- **For `no_std` builds**: + - [Top-level Makefile](https://github.com/apache/incubator-teaclave-trustzone-sdk/compare/cd19ac2e1c3cb1a848d5131d4af8138d84be8708..dc1523cbcf6c716213854d9a16d39b8d498a9bb6#diff-df315bfec3c0b8e84c64b31e4450660ea66c33aa833f5b1b9d76250481c15887) + - [Host Makefile](https://github.com/apache/incubator-teaclave-trustzone-sdk/compare/cd19ac2e1c3cb1a848d5131d4af8138d84be8708..dc1523cbcf6c716213854d9a16d39b8d498a9bb6#diff-96468cc392cceb21806dbfb2dd24007d772f19992955ed81c4979a45f753378a) + - [TA Makefile](https://github.com/apache/incubator-teaclave-trustzone-sdk/compare/cd19ac2e1c3cb1a848d5131d4af8138d84be8708..dc1523cbcf6c716213854d9a16d39b8d498a9bb6#diff-29c530c8f83308f34fae9b3516015f07fa80c1b879cc9a8834c4dfaa497af1a5) -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`. +- **For `std` builds**: + - [Top-level Makefile](https://github.com/apache/incubator-teaclave-trustzone-sdk/compare/cd19ac2e1c3cb1a848d5131d4af8138d84be8708..dc1523cbcf6c716213854d9a16d39b8d498a9bb6#diff-15685120d44f0ca4ea11ac90799a621f19378cebf5b018792ebc25bee68c3824) + - [Host Makefile](https://github.com/apache/incubator-teaclave-trustzone-sdk/compare/cd19ac2e1c3cb1a848d5131d4af8138d84be8708..dc1523cbcf6c716213854d9a16d39b8d498a9bb6#diff-dfb3cbc25e6b4bad652b716b9d051c9fb7c45d2d8303caa936666774c49a624a) + - [TA Makefile](https://github.com/apache/incubator-teaclave-trustzone-sdk/compare/cd19ac2e1c3cb1a848d5131d4af8138d84be8708..dc1523cbcf6c716213854d9a16d39b8d498a9bb6#diff-e0618a8a49e0ac65dd1acd48a0108c280a3821bcfb233f46f4baa56c77369001) -### Step 3: Build and Fix Errors +### Step 2: **Update `Cargo.toml`** +You may need to update your `Cargo.toml` file to include newer +versions of crates that depend on the new Rust toolchain. Refer to +the `rust-toolchain.toml` file to verify the current toolchain. If +you update any crates, be prepared for potential code changes to +accommodate new interfaces. -After updating, run the build process. Some errors might occur due to the -crate version upgrades—fix them as necessary. +### Step 3: **Build and Resolve Errors** +After updating the necessary files, rebuild the project. During the +process, errors might arise due to crate version mismatches or +other updates. Make sure to resolve these errors by adjusting your +code accordingly. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
