From 492d9b3075fb255eb28a6b468d7b8e762ddeada2 Mon Sep 17 00:00:00 2001 From: wangxiaozhe Date: Tue, 30 Jun 2020 17:40:01 +0800 Subject: [PATCH] rune: Add Enclave Runtime PAL API v2 spec and programming guide Signed-off-by: jack.wxz --- rune/docs/pal_programming_guide.md | 117 ++++++++++++++++++ .../internal/runtime/pal/spec_v2.md | 48 +++++++ 2 files changed, 165 insertions(+) create mode 100644 rune/docs/pal_programming_guide.md create mode 100644 rune/libenclave/internal/runtime/pal/spec_v2.md diff --git a/rune/docs/pal_programming_guide.md b/rune/docs/pal_programming_guide.md new file mode 100644 index 0000000..38df80b --- /dev/null +++ b/rune/docs/pal_programming_guide.md @@ -0,0 +1,117 @@ +# Enclave Runtime Programming Guide v2 + +# 1. Background +The enclave runtime currently supported by runE is occlum. In order to facilitate other libos programs to run in runE, a set of enclave rumtime API interfaces is defined. Libos only needs to support this set of API interfaces to run as an enclave runtime in runE. + +# 2. enclave runtime in runE +runE enclave runtime is bounded by the enclave runtime pal API layer, below the API layer is runE, above the API layer is the enclave runtime, and the operating mode is libos. + +## 2.1 enclave runtime pal API definition +```c +struct pal_attr_t { + const char* args; + const char* log_level; +}; + +struct stdio_fds { + int stdin, stdout, stderr; +}; + +struct pal_create_process_args { + char *path; + char *argv[]; + char *env[]; + struct stdio_fds *stdio; + int *pid; +}__attribute__((packed)); + +struct pal_exec_args { + int pid; + int *exit_value; +}__attribute__((packed)); + +struct pal_kill_args { + int pid; + int sig; +}__attribute__((packed)); + +struct pal_opt { + int pal_version(); + int pal_init(struct pal_attr_t *attr); + int pal_create_process(struct pal_create_process_args *args); + int pal_exec(struct pal_exec_args *args); + int pal_kill(struct pal_kill_args *args); + int pal_destroy(); +}; +``` + +## 2.2 encalve runtime Library file naming and function naming rules +The enclave runtime is generated as a so dynamic library, which is dynamically loaded by rune using dlopen; the enclave runtime needs to export symbols according to the function named in the previous chapter.
+ +# 3. pal interface + +## 3.1 pal_version +The value of this global variable is the version of pal_api, refer to the implementation: +```c +int pal_version() +{ + return 2; +} +``` + +## 3.2 pal_init +The main task of this interface should be to create an enclave space and complete the memory layout of the enclave space; libos also needs to complete the initialization of components such as VM, FS, and NET. Reference implementation: +```c +int pal_init(const struct pal_attr_t *attr) +{ + ... + sgx_launch_token_t token; + get_token(&token); + sgx_create_enclave(..., token, ...); + ... +} +``` + +## 3.3 pal_create_process +The main job of this interface is to create a new process, reference implementation: +```c +int pal_create_process(struct pal_create_process_args *args) +{ + ... + args->pid = libos_create_process(...); + ... +} +``` + +## 3.4 pal_exec +The main job of this interface is to run a program created by pal_create_process, refer to the implementation: +```c +int pal_exec(struct pal_exec_args *args) +{ + ... + libos_exec(...); + ... +} +``` + +## 3.5 pal_kill +The main job of this interface is to send a signal to the specified pid, refer to the implementation: +```c +int pal_kill(int pid, int sig) +{ + ... + libos_kill(...) + ... +} +``` + +## 3.6 pal_destroy +The main job of this interface is to destroy the entire enclave space. If it is libos, you need to do component de-initialization before destroying the enclave. Reference implementation: +```c +int pal_destroy(void) { + ... + libos_uninitialize(); + sgx_destroy_enclave(global_eid); + ... +} +``` diff --git a/rune/libenclave/internal/runtime/pal/spec_v2.md b/rune/libenclave/internal/runtime/pal/spec_v2.md new file mode 100644 index 0000000..cf40bfa --- /dev/null +++ b/rune/libenclave/internal/runtime/pal/spec_v2.md @@ -0,0 +1,48 @@ +# Enclave Runtime PAL API Specification v2 +Enclave Runtime PAL API defines a common interface to interact between `rune` and enclave runtime. + +## 1. pal_version +| **Description** | Indicate PAL API version number implemented by runelet and enclave runtime; runelet is compatible with any enclave runtimes equal to or less than the indicated value. If this symbol is undefined in enclave runtime, version 1 is assuemd by runelet. | +| :---: | :--- | +| **Prototype** | `int pal_version();` | +| **Parameters** | N/A | +| **Return value** | N/A | +| **Availability ** | >=v2 | + +## 2.pal_init() +| **Description** | Do libos initialization according to the incoming attr parameters. | +| :---: | :--- | +| **Prototype** | struct pal_attr_t {
const char *args;
const char *log_level;
};
int pal_init(struct palattrt *attr); | +| **Parameters** | @args: Pass the required parameters of libos (can be instance path etc.)
@log_level: Log level. | +| **Return value** | 0: Success
-EINVAL: Invalid argument
-ENOSYS: The function is not supported | +| **Availability ** | >=v2 | + +## 3. pal_create_process +| **Description** | Create a new process, but do not run it; the real run is triggered by pal_exec(). | +| :---: | :--- | +| **Prototype** | struct stdio_fds {
int stdin, stdout, stderr;
};
struct pal_create_process_args {
char *path;
char *argv[];
char *env[];
struct stdio_fds *stdio;
int *pid;
}__attribute__((packed));
int pal_create_process(struct pal_create_process_args *args); | +| **Parameters** | @path: The path of the binary file to be run (relative path in the libos file system).
@argv: Binary parameters, ending with a null element.
@env: Binary environment variables, ending with a null element.
@stdio: The fd of stdio.
@pid: If the function return value is 0, pid stores the pid of the new process in libos. | +| **Return value** | 0: Success
-EINVAL: Invalid argument
-ENOSYS: The function is not supported | +| **Availability ** | >=v2 | + +## 4. pal_exec +| **Description** | Execute the program corresponding to pid. | +| :---: | :--- | +| **Prototype** | struct pal_exec_args {
int pid;
int *exit_value;};
}__attribute__((packed));
int pal_exec(struct pal_exec_args *attr); | +| **Parameters** | @pid: The pid of the generation process.
@exit_value: The exit value of the process. | + +## 5.pal_kill() +| **Description** | Send signals to processes running in enclave runtime. | +| :---: | :--- | +| **Prototype** | int pal_kill(int pid, int sig); | +| **Parameters** | @pid: Send to all processes if equal to -1, or send to current process if equal to 0, or send to the process that owns the pid if others.
@sig: Signal number to be sent | +| **Return value** | 0: Success
-EINVAL: Invalid argument
-ENOSYS: The function is not supported | +| **Availability ** | >=v2 | + +## 6.pal_destroy() +| **Description** | Destroy libos instance. | +| :---: | :--- | +| **Prototype** | int pal_destroy(); | +| **Parameters** | NA. | +| **Return value** | 0: Success
-ENOSYS: The function is not supported | +| **Availability ** | >=v2 | -- GitLab