From d3429e15b74abf96a8ba2bdf5684e69f2b9cbc43 Mon Sep 17 00:00:00 2001
From: He Sun <bochang.sh@antgroup.com>
Date: Thu, 13 Aug 2020 13:24:26 +0800
Subject: [PATCH] Add guide to configure the resource of Occlum

---
 README.md                     |  4 ++--
 docs/resource_config_guide.md | 45 +++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+), 2 deletions(-)
 create mode 100644 docs/resource_config_guide.md

diff --git a/README.md b/README.md
index 8ff808ca..fcade5d6 100644
--- a/README.md
+++ b/README.md
@@ -64,9 +64,9 @@ Hello World!
 ```
 The `occlum run` command starts up an Occlum SGX enclave, which, behind the scene, verifies and loads the associated Occlum FS image, spawns a new LibOS process to execute `/bin/hello_world`, and eventually prints the message.
 
-### Config Occlum
+### Configure Occlum
 
-Occlum can be configured easily via a config file named `Occlum.json`, which is generated by the `occlum init` command in the Occlum instance directory. The user can modify `Occlum.json` to config Occlum. A sample of `Occlum.json` is shown below. Some comments are added to provide a brief explanation.
+Occlum can be configured easily via a configuration file named `Occlum.json`, which is generated by the `occlum init` command in the Occlum instance directory. The user can modify `Occlum.json` to configure Occlum. A sample of `Occlum.json` is shown below. Some comments are added to provide a brief explanation. If you are not sure how to set the `resource_limits` or `process` for your application, please check out [Resource Configuration Guide](docs/resource_config_guide.md).
 ```js
 {
     // Resource limits
diff --git a/docs/resource_config_guide.md b/docs/resource_config_guide.md
new file mode 100644
index 00000000..a2382b4d
--- /dev/null
+++ b/docs/resource_config_guide.md
@@ -0,0 +1,45 @@
+# Resource Configuration Guide
+
+Due to SGX hardware limitations, Occlum needs users' assistance to specify some
+resource limits or hints in `Occlum.json`. These configuration values must
+be tuned on a per-application basis.
+
+If you already know the memory usage of your application, set the memory usage
+in the `process` field. Otherwise, use the default configuration file generated
+after `occlum init`. During the tuning process, the log of Occlum should be
+turned on by setting the `OCCLUM_LOG_LEVEL` environment variable (e.g.,
+`OCCLUM_LOG_LEVEL=error`, `OCCLUM_LOG_LEVEL=info`).
+
+To make the tuning process smooth, some troubleshooting instructions are listed
+below. They can cover common types of errors resulting from the lack of
+resources.
+
+1. Mmap syscall error:
+    - Error message: `[____Mmap] Error = ENOMEM (#12, Out of memory): not
+      enough memory`
+
+    - Solution: Enlarge `process.default_mmap_size`
+
+2. Brk syscall error:
+    - Error message: `[_____Brk] Error = EINVAL (#22, Invalid argument): New
+      brk address is too high`
+
+    - Solution: Enlarge `process.default_heap_size`
+
+3. Process creation error:
+    - Error message: `ENOMEM (#12, Out of memory): run out of reserved memory`
+
+    - Solution: Enlarge `resource_limits.user_space_size`
+
+4. Malloc of Rust SDK error:
+    - Error message: `memory allocation of XXX bytes failed`
+
+    - Solution: Enlarge `resource_limits.kernel_space_heap_size`
+
+5. LibOS thread execution error:
+    - Error message: `[ERROR] occlum-pal: Failed to enter the enclave to
+      execute a LibOS thread (host tid = XXX): Unknown SGX error`
+
+    - Solution: There are many reasons resulting in the above errors. Try to
+      enlarge `resource_limits.max_num_of_threads` if your application has
+      threads far more than it.