This is an automated email from the ASF dual-hosted git repository.
yuanz pushed a commit to branch master
in repository
https://gitbox.apache.org/repos/asf/incubator-teaclave-trustzone-sdk.git
The following commit(s) were added to refs/heads/master by this push:
new 0045c2a Restructure readme (#81)
0045c2a is described below
commit 0045c2ae3b31949b8e169fe2515f498b03e26e61
Author: Jesse <[email protected]>
AuthorDate: Thu Jun 9 04:32:41 2022 -0700
Restructure readme (#81)
---
README.md | 279 +++++++++++++++++++++++++++++---------------------------------
1 file changed, 131 insertions(+), 148 deletions(-)
diff --git a/README.md b/README.md
index 8775472..5c0aa53 100644
--- a/README.md
+++ b/README.md
@@ -7,15 +7,30 @@
Teaclave TrustZone SDK (Rust OP-TEE TrustZone SDK) provides abilities to build
safe TrustZone applications in Rust. The SDK is based on the
[OP-TEE](https://www.op-tee.org/) project which follows
-[GlobalPlatform](https://globalplatform.org/) TEE specifications and provides
-ergonomic APIs. In addition, it enables capability to write TrustZone
-applications with Rust's standard library and many third-party libraries (i.e.,
-crates). Teaclave TrustZone SDK is a sub-project of [Apache Teaclave
-(incubating)](https://teaclave.apache.org/).
-
-## Getting started
-
-### Quick start with the OP-TEE Repo for QEMUv8
+[GlobalPlatform](https://globalplatform.org/) [TEE
+specifications](https://globalplatform.org/specs-library/tee-internal-core-api-specification/)
+and provides ergonomic APIs. In addition, it enables the capability to write
+TrustZone applications with Rust's standard library (std) and many third-party
+libraries (i.e., crates). Teaclave TrustZone SDK is a sub-project of [Apache
+Teaclave (incubating)](https://teaclave.apache.org/).
+
+## Table of Contents
+
+- [Quick start with the OP-TEE Repo for
QEMUv8](#quick-start-with-the-op-tee-repo-for-qemuv8)
+- [Getting started](#getting-started)
+ - [Environment](#environment)
+ - [Develop with QEMUv8](#develop-with-qemuv8)
+ - [Develop on other platforms](#develop-on-other-platforms)
+ - [Build & Install](#build--install)
+ - [Run Rust Applications](#run-rust-applications)
+ - [Run Rust Applications in QEMUv8](#run-rust-applications-in-qemuv8)
+ - [Run Rust Applications on other
platforms](#run-rust-applications-on-other-platforms)
+- [Documentation](#documentation)
+- [Publication](#publication)
+- [Contributing](#contributing)
+- [Community](#community)
+
+## Quick start with the OP-TEE Repo for QEMUv8
Teaclave TrustZone SDK has been integrated into the OP-TEE Repo since OP-TEE
Release 3.15.0 (18/Oct/21). The aarch64 Rust examples are built and installed
@@ -23,214 +38,182 @@ into OP-TEE's default filesystem for QEMUv8. Follow [this
documentation](https://optee.readthedocs.io/en/latest/building/optee_with_rust.html)
to set up the OP-TEE repo and try the Rust examples!
-### Develop your trusted applications in Rust
+## Getting started
+
+### Environment
+
+To get started with Teaclave TrustZone SDK, you could choose either [QEMU for
+Armv8-A](#develop-with-qemuv8) (QEMUv8) or [other
+platforms](#develop-on-other-platforms) ([platforms OP-TEE
+supported](https://optee.readthedocs.io/en/latest/general/platforms.html)) as
+your development environment.
+
+#### Develop with QEMUv8
The OP-TEE libraries are needed when building Rust applications, so you should
-finish the `Quick start with the OP-TEE Repo for QEMUv8` part first. Then
+finish the [Quick start with the OP-TEE Repo for
+QEMUv8](#quick-start-with-the-op-tee-repo-for-qemuv8) part first. Then
initialize the building environment in Teaclave TrustZone SDK, build Rust
applications and copy them into the target's filesystem.
-#### 1. Update the project
-
-Teaclave TrustZone SDK is located in `YOUR_OPTEE_DIR/optee_rust/`.Teaclave
+Teaclave TrustZone SDK is located in `[YOUR_OPTEE_DIR]/optee_rust/`. Teaclave
TrustZone SDK in OP-TEE repo is pinned to the release version. Alternatively,
you can try the develop version using `git pull`:
-```
-$ cd [YOUR_OPTEE_DIR]/optee_rust/
-$ git pull github master
-```
-
-#### 2. Install Rust environment and initialize related submodules
-
-* Set the OP-TEE root directory:
-
-``` sh
-$ export OPTEE_DIR=[YOUR_OPTEE_DIR]
+```sh
+cd [YOUR_OPTEE_DIR]/optee_rust/
+git pull github master
```
-* Run the script as follows to install Rust environment and initialize
- submodules:
+#### Develop on other platforms
-```
-$ ./setup.sh
-```
-
-#### 3. Set environment variables
+If you are building trusted applications for other platforms ([platforms OP-TEE
+supported](https://optee.readthedocs.io/en/latest/general/platforms.html)).
QEMU
+and the filesystem in the OP-TEE repo are not needed. You can follow these
+steps to clone the project and build applications independently from the
+complete OP-TEE repo. In this case, the necessary OP-TEE libraries are
+initialized in the setup process.
-Before building examples, the environment should be properly setup.
+1. The complete list of prerequisites can be found here: [OP-TEE
+Prerequisites](https://optee.readthedocs.io/en/latest/building/prerequisites.html).
``` sh
-$ source environment
-```
-
-By default, the target platform is `aarch64`. If you want to build for the
`arm`
-target, you can setup `ARCH` before `source environment`:
-
-```sh
-$ export ARCH=arm
-$ source environment
+# install dependencies
+sudo apt-get install android-tools-adb android-tools-fastboot autoconf \
+ automake bc bison build-essential ccache cscope curl device-tree-compiler \
+ expect flex ftp-upload gdisk iasl libattr1-dev libc6:i386 libcap-dev \
+ libfdt-dev libftdi-dev libglib2.0-dev libhidapi-dev libncurses5-dev \
+ libpixman-1-dev libssl-dev libstdc++6:i386 libtool libz1:i386 make \
+ mtools netcat python-crypto python3-crypto python-pyelftools \
+ python3-pycryptodome python3-pyelftools python-serial python3-serial \
+ rsync unzip uuid-dev xdg-utils xterm xz-utils zlib1g-dev
```
-#### 4. Build Rust applications
-
-Before building built-in rust examples, you need to build OP-TEE libraries
using:
-
-``` sh
-$ make optee
-```
+Alternatively, you can use a docker container built with our
+[Dockerfile](Dockerfile).
-Run this command to build all Rust examples:
+2. After installing dependencies or building the Docker image, fetch the source
+ code from the official GitHub repository:
``` sh
-$ make examples
+# clone the project
+git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git
+cd incubator-teaclave-trustzone-sdk
```
-Or build your own CA and TA:
+### Build & Install
-```
-$ make -C examples/[YOUR_APPLICATION]
-```
+To build the project, the Rust environment and several related submodules are
+required.
-#### 5. Run Rust applications
+1. By default, the `OPTEE_DIR` is `incubator-teaclave-trustzone-sdk/optee/`.
+ OP-TEE submodules (`optee_os`, `optee_client` and `build`) will be
initialized
+automatically in `setup.sh`.
-The shared folder is needed to share CAs and TAs with the QEMU guest system.
-Recompile QEMU in OP-TEE to enable QEMU virtfs:
+If you are building within QEMUv8 or already have the [OP-TEE
+repository](https://github.com/OP-TEE) cloned somewhere, you can set the
OP-TEE
+root directory with:
+```sh
+export OPTEE_DIR=[YOUR_OPTEE_DIR]
```
-$ (cd $OPTEE_DIR/build && make QEMU_VIRTFS_ENABLE=y qemu)
-```
-Note: the path `/project/root/dir/` should be replaced as the root directory of
-your local project "Teaclave TrustZone SDK". Copy all the Rust examples or your
-own applications to the shared folder:
+Note: your OPTEE root directory should have `build/`, `optee_os/` and
+`optee_client/` as sub-directory.
+
+2. Run the script as follows to install the Rust environment and initialize
+ submodules:
```sh
-$ mkdir shared_folder
-$ (cd /project/root/dir/ && make examples-install)
-$ cp -r /project/root/dir/out/* shared_folder/
+./setup.sh
```
-Run QEMU.
+3. Before building examples, the environment should be properly set up with:
-```sh
-$ (cd $OPTEE_DIR/build && make run-only QEMU_VIRTFS_ENABLE=y
-QEMU_VIRTFS_HOST_DIR=$(pwd)/shared_folder)
+``` sh
+source environment
```
-After the QEMU has been booted, you need to mount the shared folder in QEMU
-guest system (username: root), in order to access the compiled CA/TA from QEMU.
-Run the command as follows in the QEMU guest terminal:
+Note: by default, the target platform is `aarch64`. If you want to build for
the
+`arm` target, you can setup `ARCH` before the `source environment` command:
```sh
-$ mkdir shared && mount -t 9p -o trans=virtio host shared
+export ARCH=arm
+source environment
```
-Then run CA and TA as
-[this
documentation](https://optee.readthedocs.io/en/latest/building/optee_with_rust.html)
- describes.
-
-## Use OP-TEE libraries as submodules
-
-If you are building trusted applications for other platforms ([platforms OP-TEE
-supported](https://optee.readthedocs.io/en/latest/general/platforms.html)).
QEMU
-and the filesystem in OP-TEE repo are not needed. You can follow these steps
to
-clone the project and build applications independently from the complete OP-TEE
-repo. In this case, the necessary OP-TEE libraries are initialized in the setup
-process.
-
-#### 1. Clone the project and install building dependencies
-
-The complete list of prerequisites can be found here: [OP-TEE
-Prerequisites](https://optee.readthedocs.io/en/latest/building/prerequisites.html).
-
-Alternatively, you can use a docker container built with our
-[Dockerfile](Dockerfile).
+4. Before building rust examples and applications, you need to build OP-TEE
+ libraries using:
``` sh
-# install dependencies
-$ sudo apt-get install android-tools-adb android-tools-fastboot autoconf \
- automake bc bison build-essential ccache cscope curl
device-tree-compiler \
- expect flex ftp-upload gdisk iasl libattr1-dev libc6:i386 libcap-dev \
- libfdt-dev libftdi-dev libglib2.0-dev libhidapi-dev libncurses5-dev \
- libpixman-1-dev libssl-dev libstdc++6:i386 libtool libz1:i386 make \
- mtools netcat python-crypto python3-crypto python-pyelftools \
- python3-pycryptodome python3-pyelftools python-serial python3-serial \
- rsync unzip uuid-dev xdg-utils xterm xz-utils zlib1g-dev
+make optee
```
-After installing dependencies or building the Docker container, fetch the
source code from the official GitHub repository:
+5. Run this command to build all Rust examples:
``` sh
-# clone the project
-$ git clone https://github.com/apache/incubator-teaclave-trustzone-sdk.git
-$ cd incubator-teaclave-trustzone-sdk
+make examples
```
-#### 2. Set your OP-TEE directory
-
-* By default, the `OPTEE_DIR` is
- `incubator-teaclave-trustzone-sdk/optee/`.OP-TEE submodules (`optee_os`,
-`optee_client` and` build`) will be initialized automatically in `setup.sh`. If
-you already have [OP-TEE repository](https://github.com/OP-TEE) cloned
-somewhere, you can set OP-TEE root directory:
+Or build your own CA and TA:
-``` sh
-$ export OPTEE_DIR=[YOUR_OPTEE_DIR]
+```sh
+make -C examples/[YOUR_APPLICATION]
```
-Note that your OPTEE root directory should have `build/`, `optee_os/` and
-`optee_client/` as sub-directory.
-
-* Run the script as follows to install Rust environment and set up submodules.
+Besides, you can collect all example CAs and TAs to
+`/incubator-teaclave-trustzone-sdk/out`:
-```
-$ ./setup.sh
+```sh
+make examples-install
```
-#### 3. Set environment variables
+### Run Rust Applications
-Before building examples, the environment should be properly setup.
+Considering the platform has been chosen
+([QEMUv8](#run-rust-applications-in-qemuv8) or
+[other](#run-rust-applications-on-other-platforms)), the ways to run the Rust
+applications are different.
-``` sh
-$ source environment
-```
+#### Run Rust Applications in QEMUv8
-By default, the target platform is `aarch64`. If you want to build for the
`arm`
-target, you can setup `ARCH` before `source environment` like this:
+1. The shared folder is needed to share CAs and TAs with the QEMU guest system.
+Recompile QEMU in OP-TEE to enable QEMU VirtFS:
```sh
-$ export ARCH=arm
-$ source environment
+(cd $OPTEE_DIR/build && make QEMU_VIRTFS_ENABLE=y qemu)
```
-#### 4. Build OP-TEE libraries
-
-Then, download ARM toolchains and build OP-TEE libraries. Note that the OP-TEE
-target is QEMUv8, and you can modify the Makefile to other targets accordingly.
+2. Copy all the Rust examples or your own applications to the shared folder:
-``` sh
-$ make optee
+```sh
+mkdir shared_folder
+cd [YOUR_OPTEE_DIR]/optee_rust/ && make examples-install)
+cp -r [YOUR_OPTEE_DIR]/optee_rust/out/* shared_folder/
```
-#### 5. Build Rust examples
-
-Run this command to build all Rust examples:
+3. Run QEMU:
-``` sh
-$ make examples
+```sh
+(cd $OPTEE_DIR/build && make run-only QEMU_VIRTFS_ENABLE=y
+QEMU_VIRTFS_HOST_DIR=$(pwd)/shared_folder)
```
-Collect all example CAs and TAs to `/incubator-teaclave-trustzone-sdk/out`:
+4. After the QEMU has been booted, you need to mount the shared folder in the
+QEMU guest system (username: root), in order to access the compiled CA/TA from
+QEMU. Run the command as follows in the QEMU guest terminal:
-``` sh
-$ make examples-install
+```sh
+mkdir shared && mount -t 9p -o trans=virtio host shared
```
-#### 6. Run Rust examples
+5. Then run CA and TA as [this
+documentation](https://optee.readthedocs.io/en/latest/building/optee_with_rust.html)
+describes.
-Copy the applications to your platform and run.
+#### Run Rust Applications on other platforms
+Copy the applications to your platform and run.
## Documentation
@@ -251,7 +234,7 @@ published in ACSAC 2020:
Applications](https://csis.gmu.edu/ksun/publications/ACSAC20_RusTEE_2020.pdf).
Here is the BiBTeX record for your reference.
-```
+```bibtex
@inproceedings{wan20rustee,
author = "Shengye Wan and Mingshen Sun and Kun Sun and Ning Zhang and Xu
He",
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
