occlum/docs/resource_config_guide.md

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. SGX protected file I/O error:

   • Error message: SGX protected file I/O error: EIO (#5, I/O error): Cannot allocate memory (os error: 12)

   • Solution: Enlarge resource_limits.kernel_space_heap_size

6. 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.