Enhance the readability of WAMR SGX docs (#442)

The global doc/linux_sgx.md needs to explicitly describe the methods to
build a debug enclave and hardware running mode. Because using debug key
to signing enclave image rather than production key is still not trivial
in reality.

For the adaption of Inclavare Containers part, add a prolog and give
more details in order to enhance the readability.

Signed-off-by: Jia Zhang <zhang.jia@linux.alibaba.com>

doc/linux_sgx.md

@@ -17,8 +17,6 @@ cmake ..
 make
 ```
 
-**Note:** By default, the generated SGX application assumes it is signed with production key and running on simulation mode. In order to build a debug enclave on hardware-based SGX platform, execute `make SGX_DEBUG=1 SGX_MODE=HW` instead.
-
 This builds two libraries required by SGX application:
  - libvmlib.a for Enclave part
  - libvmlib_untrusted.a for App part
@@ -32,6 +30,8 @@ cd enclave-sample
 make
 ```
 
+**Note:** By default, the generated SGX application assumes it is signed with production key and running on simulation mode. The user can explicitly specify the relative variables in commandline to overwrite the default settings. For example, to build a debug enclave, please build the enclave with `make SGX_DEBUG=1`. To build the enclave running on a hardware-based SGX platform, execute `make SGX_MODE=HW`.
+
 The binary file iwasm will be generated. To run the sample:
 
 ``` Bash

product-mini/platforms/linux-sgx/enclave-sample/App/README.md

@@ -1,53 +1,48 @@
-# WAMR as an Enclave Runtime for Rune
+# Running WAMR as an [Enclave Runtime](https://github.com/alibaba/inclavare-containers/blob/master/docs/design/terminology.md#enclave-runtime) for [Inclavare Containers](https://github.com/alibaba/inclavare-containers)
 
-## Build WAMR vmcore (iwasm) for Linux-SGX
+In order to establish with `rune`, a novel OCI Runtime for spawning and running enclaves in containers, it is required to implement an [enclave runtime PAL](https://github.com/alibaba/inclavare-containers/blob/master/docs/design/terminology.md#enclave-runtime-pal) to make the communications with WAMR.
 
-Please follow [this guide](https://github.com/bytecodealliance/wasm-micro-runtime/blob/main/doc/linux_sgx.md#build-wamr-vmcore-iwasm-for-linux-sgx) to build iwasm as the prerequisite.
+With the assist of `rune`, WAMR is brought to the cloud-native ecosystem beyond the basis. This is the so-called term "WAMR enclave runtime".
 
-Then build enclave image and sign it:
+This guide will provide the information about the build, integration and deployment for WAMR enclave runtime. Eventually, the resulting docker image will be launched by `rune`, and the WARM application as the entrypoint of docker image will run in Intel SGX enclave with the hardware-enforced isolation and cryptographically data protection.
 
-```shell
-cd enclave-sample
-make
-/opt/intel/sgxsdk/bin/x64/sgx_sign sign -key Enclave/Enclave_private.pem -enclave enclave.so -out enclave.signed.so -config Enclave/Enclave.config.xml
-```
+## Build WAMR vmcore (iwasm) and enclave image
 
-The generated enclave.signed.so is required by PAL.
+Please follow [this guide](https://github.com/bytecodealliance/wasm-micro-runtime/blob/main/doc/linux_sgx.md#build-wamr-vmcore-iwasm-for-linux-sgx) to build iwasm and enclave image as the prerequisite.
 
----
+The generated enclave image enclave.signed.so will be consumed by WAMR enclave runtime mentioned below.
 
-## Build PAL dynamically linked shared object
+---
 
-To build WAMR as an Enclave Runtime for [Inclavare Containers](https://github.com/alibaba/inclavare-containers), we should implement the [PAL API v2](https://github.com/alibaba/inclavare-containers/blob/master/rune/libenclave/internal/runtime/pal/spec_v2.md) in WAMR for rune to call the PAL to create the enclave with WAMR and run applications.
+## Build and install the PAL of WAMR enclave runtime
 
 ```shell
 g++ -shared -fPIC -o libwamr-pal.so App/*.o libvmlib_untrusted.a -L/opt/intel/sgxsdk/lib64 -lsgx_urts -lpthread -lssl -lcrypto
 cp ./libwamr-pal.so /usr/lib/libwamr-pal.so
 ```
 
-Note: Assuming `/opt/intel/sgxsdk/` is where you installed the SGX SDK.
-
 ---
 
 ## Build WAMR application
 
-To Build a WAMR application, please refer to [this guide](https://github.com/bytecodealliance/wasm-micro-runtime/blob/main/doc/build_wasm_app.md#build-wasm-applications)
-
-To run a WAMR application with Intel SGX enclave by `rune`, please refer to [this guide](https://github.com/bytecodealliance/wasm-micro-runtime#build-wamrc-aot-compiler) to generate wamrc AoT compiler, and then refer to [this guide](https://github.com/bytecodealliance/wasm-micro-runtime/blob/main/doc/build_wasm_app.md#compile-wasm-to-aot-module) to compile the `.wasm` file to `.aot` file.
-
-Note: the AoT file must be generated using --size-level=1 to set a bigger code size, e.g,
+As the prerequisite, please
+- refer to [this step](https://github.com/bytecodealliance/wasm-micro-runtime/blob/main/doc/build_wasm_app.md#prepare-wasm-building-environments) to install wasi-sdk. Note that the binaries of wasi-sdk must be installed at `/opt/wasi-sdk/bin/`.
+- refer to [this guide](https://github.com/bytecodealliance/wasm-micro-runtime#build-wamrc-aot-compiler) to generate wamrc AoT compiler.
 
+The sample WAMR application test.c is provided in [this guide](https://github.com/bytecodealliance/wasm-micro-runtime/blob/main/doc/build_wasm_app.md#build-wasm-applications). Don't forget to compile the `.wasm` file to `.aot` file:
 ```shell
-wamrc --size-level=1 -o test.aot test.wasm
+wamrc -sgx -o test.aot test.wasm
 ```
 
+The generated test.aot is the WAMR application launched by WAMR enclave runtime.
+
 ---
 
 ## Build WAMR docker image
 
 Under the `enclave-sample` directory, to create the WAMR docker images to load the `enclave.signed.so` and target application wasm files, please type the following commands to create a `Dockerfile`:
 
-For centos:
+For CentOS:
 
 ```shell
 cat >Dockerfile <<EOF
@@ -57,9 +52,9 @@ RUN mkdir -p /run/rune
 WORKDIR /run/rune
 
 COPY enclave.signed.so .
-COPY ${wasm_app.aot} .
-#COPY ${wasm_app2.aot} .
-#...
+COPY test.aot app
+#COPY ${wasm_app.aot} .
+ENTRYPOINT ["/run/rune/app"]
 EOF
 ```
 
@@ -73,23 +68,23 @@ RUN mkdir -p /run/rune
 WORKDIR /run/rune
 
 COPY enclave.signed.so .
-COPY ${wasm_app.aot} .
+COPY test.aot app
 #COPY ${wasm_app.aot} .
-#...
+ENTRYPOINT ["/run/rune/app"]
 EOF
 ```
 
-where `${wasm_app.aot}` files are the other applications you want to run in WAMR.
+where `${wasm_app.aot}` files are the extra WAMR applications you want to run.
 
 Then build the WAMR docker image with the command:
 
 ```shell
-docker build . -t wamr-app
+docker build . -t wamr-sgx-app
 ```
 
 ---
 
-## Run WAMR SGX with Docker and OCI Runtime rune
+## Deploy WAMR SGX Docker image
 
 The following guide provides the steps to run WAMR with Docker and OCI Runtime `rune`.
 
@@ -112,11 +107,11 @@ The following guide provides the steps to run WAMR with Docker and OCI Runtime `
 
 - The simplest way to install `rune` is to download a pre-built binary from [Inclavare Containers release page](https://github.com/alibaba/inclavare-containers/releases).
 
-### Configuring OCI Runtime rune for Docker
+### Integrate OCI Runtime rune with Docker
 
-Add the assocated configuration for `rune` in dockerd config file, e.g, `/etc/docker/daemon.json`, on your system.
+Add the associated configuration for `rune` in dockerd config file, e.g, `/etc/docker/daemon.json`, on your system.
 
-```
+```json
 {
 	"runtimes": {
 		"rune": {
@@ -141,7 +136,7 @@ The expected result would be:
 Runtimes: rune runc
 ```
 
-### Run WAMR docker image
+### Run WAMR SGX docker image
 
 You need to specify a set of parameters to `docker run` to run:
 
@@ -150,7 +145,7 @@ docker run -it --rm --runtime=rune \
   -e ENCLAVE_TYPE=intelSgx \
   -e ENCLAVE_RUNTIME_PATH=/usr/lib/libwamr-pal.so \
   -e ENCLAVE_RUNTIME_ARGS=debug \
-  wamr-app /run/rune/${wasm_app.aot}
+  wamr-sgx-app
 ```
 
 where:
@@ -161,6 +156,6 @@ where:
 
 ---
 
-## (Optional) Run WAMR bundle for rune
+## Develop and debug WAMR enclave runtime with rune
 
 Please refer to [this guide](https://github.com/leyao-daily/wasm-micro-runtime/blob/main/product-mini/platforms/linux-sgx/enclave-sample/App/wamr-bundle.md). This is optional, and suits for the developer in most cases.

product-mini/platforms/linux-sgx/enclave-sample/App/wamr-bundle.md

@@ -1,15 +1,15 @@
-# Run WAMR bundle for Rune
+# Run WAMR enclave runtime with bundle
 
 ## Create WAMR Application bundle
 
-In order to use `rune` you must have your container image in the format of an OCI bundle. If you have Docker installed you can use its `export` method to acquire a root filesystem from an existing WAMR application container image.
+`rune` can directly launch an OCI bundle converted from docker image. If you have Docker installed you can use its `export` sub-command to acquire a root filesystem from an existing WAMR application docker image.
 
 ```shell
 # create the top most bundle directory
 mkdir -p "$HOME/rune_workdir"
 cd "$HOME/rune_workdir"
-mkdir rune-container
-cd rune-container
+mkdir wamr-sgx-bundle
+cd warmr-sgx-bundle
 
 # create the rootfs directory
 mkdir rootfs
@@ -26,23 +26,23 @@ rune spec
 
 To find features and documentation for fields in the spec please refer to the [specs](https://github.com/opencontainers/runtime-spec) repository.
 
-In order to run the target applications in WAMR with `rune`, you need to change the entrypoint from `sh` to `/run/rune/${wasm_app1.wasm}`, and in order to run multi-applications in one runtime with enclave, change it to `/run/rune/${wasm_app1.aot}`, `/run/rune/${wasm_app2.aot}` ... 
+In order to run the target application in WAMR with `rune`, you need to change the entrypoint from `sh` to the target application, and in order to run multi-applications in one runtime with enclave, change it to `/run/rune/${wasm_app1.aot}`, `/run/rune/${wasm_app2.aot}` ... 
 
-```yaml
+```json
   "process": {
       "args": [
-          "/run/rune/demo.aot"
+          "/run/rune/${wasm_app}"
       ],
   }
 ```
 
 and then configure enclave runtime as following:
 
-```yaml
+```json
   "annotations": {
       "enclave.type": "intelSgx",
       "enclave.runtime.path": "/usr/lib/libwamr-pal.so",
-      "enclave.runtime.args": "./"
+      "enclave.runtime.args": "debug"
   }
 ```
 
@@ -59,7 +59,6 @@ where:
 Assuming you have an OCI bundle from the previous step you can execute the container in this way.
 
 ```shell
-cd "$HOME/rune_workdir/rune-container"
-sudo rune run ${wamr_application_container_name}
+cd "$HOME/rune_workdir/wamr-sgx-bundle"
+sudo rune run wamr-sgx-app
 ```
-