From 344dff9e47fa8e81ac38d50f67fd7ab5f28269a8 Mon Sep 17 00:00:00 2001 From: haosanzi Date: Wed, 12 Aug 2020 19:47:52 +0800 Subject: [PATCH] rune/libenclave/pal: Reformat PAL API spec Reformat spec_v1.md and spec_v2.md Signed-off-by: Shirong Hao --- .../internal/runtime/pal/spec_v1.md | 102 +++++++--- .../internal/runtime/pal/spec_v2.md | 177 ++++++++++++++---- 2 files changed, 224 insertions(+), 55 deletions(-) diff --git a/rune/libenclave/internal/runtime/pal/spec_v1.md b/rune/libenclave/internal/runtime/pal/spec_v1.md index c1090b6..a2fcd9a 100644 --- a/rune/libenclave/internal/runtime/pal/spec_v1.md +++ b/rune/libenclave/internal/runtime/pal/spec_v1.md @@ -1,23 +1,83 @@ -# Enclave Runtime PAL API Specification +# Enclave Runtime PAL API Specification v1 Enclave Runtime PAL API defines a common interface to interact between `rune` and enclave runtime. -## pal_init() -| **Description** | Initialize enclave runtime with specific attributes. | -| :-: | :- | -| **Prototype** | struct pal_attr_t {
const char \*args;
const char \*log_level;
};
int pal_init(const struct pal_attr_t *attr); | -| **Parameters** | @args: the enclave runtime specific argument string.
@log_level: the output log level of enclave runtime. | -| **Return value** | 0: Success
-ENOENT: Invalid instance path of enclave runtime
Others: Enclave runtime specific error codes | - -## pal_exec() -| **Description** | Pass the path of the application to be executed, and synchronously wait for the end of the application to run and return the result. | -| :-: | :- | -| **Prototype** | struct pal_stdio_fds {
int stdin, stdout, stderr;
};
int pal_exec(char \*path, char \*argv[],
struct pal_stdio_fds \*stdio,
int \*exit_code); | -| **Parameters** | @path: The path of the application to be run
@argv: The array of argument strings passed to the application, terminated by a NULL pointer
@stdio: The stdio fds consumed by the application
@exit_code: Return the exit code of an application | -| **Return value** | 0: success
-ENOENT: The path does not exist
-EACCES: Permission denied
-ENOEXEC: The path is not an executable file
-ENOMEM:
-EINVAL: Invalid argument | - -## pal_destroy() -| **Description** | Destroy the enclave runtime instance | -| :-: | :- | -| **Prototype** | int pal_destroy(); | -| **Parameters** | N/A | -| **Return value** | 0: Success
-ENOSYS: The function is not supported | +## 1.pal_init() + +### Description +Initialize enclave runtime with specific attributes. + +### Prototype +```c +struct pal_attr_t { + const char *args; + const char *log_level; +}; + +int pal_init(const struct pal_attr_t *attr); +``` + +### Parameters +``` +@args: the enclave runtime specific argument string. +@log_level: the output log level of enclave runtime. +``` + +### Return value +``` +0: Success +-ENOENT: Invalid instance path of enclave runtime +Others: Enclave runtime specific error codes +``` + +## 2.pal_exec() + +### Description +Pass the path of the application to be executed, and synchronously wait for the end of the application to run and return the result. + +### Prototype +```c +struct pal_stdio_fds { + int stdin, stdout, stderr; +}; + +int pal_exec(char *path, char *argv[], struct pal_stdio_fds *stdio, int *exit_code); +``` + +### Parameters +``` +@path: The path of the application to be run. +@argv: The array of argument strings passed to the application, terminated by a NULL pointer. +@stdio: The stdio fds consumed by the application. +@exit_code: Return the exit code of an application. +``` + +### Return value +``` +0: success +-ENOENT: The path does not exist +-EACCES: Permission denied +-ENOEXEC: The path is not an executable file +-ENOMEM: No Memory +-EINVAL: Invalid argument +``` + +## 3.pal_destroy() + +### Description +Destroy the enclave runtime instance + +### Prototype +```c +int pal_destroy(); +``` + +### Parameters +``` +N/A +``` + +### Return value +``` +0: Success +-ENOSYS: The function is not supported +``` diff --git a/rune/libenclave/internal/runtime/pal/spec_v2.md b/rune/libenclave/internal/runtime/pal/spec_v2.md index f665e76..d41f6ef 100644 --- a/rune/libenclave/internal/runtime/pal/spec_v2.md +++ b/rune/libenclave/internal/runtime/pal/spec_v2.md @@ -1,43 +1,152 @@ # 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 | +## 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 +```c +int pal_version(); +``` + +### Parameters +``` +N/A +``` + +### Return value +``` +N/A +``` ## 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 | - -## 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 | - -## 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. | + +### Description +Do libos initialization according to the incoming attr parameters. + +### Prototype +```c +struct pal_attr_t { + const char *args; + const char *log_level; +}; + +int pal_init(struct pal_attr_t *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 +``` + +## 3.pal_create_process() + +### Description +Create a new process, but do not run it; the real run is triggered by pal_exec(). + +### Prototype +```c +struct pal_stdio_fds { + int stdin, stdout, stderr; +}; + +struct pal_create_process_args { + char *path; + char *argv[]; + char *env[]; + struct pal_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 +``` + +## 4.pal_exec() + +### Description +Execute the program corresponding to pid. + +### Prototype +```c +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 | + +### Description +Send signals to processes running in enclave runtime. + +### Prototype +```c +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 +``` ## 6.pal_destroy() -| **Description** | Destroy libos instance. | -| :---: | :--- | -| **Prototype** | int pal_destroy(); | -| **Parameters** | NA. | -| **Return value** | 0: Success
-ENOSYS: The function is not supported | + +### Description +Destroy libos instance. + +### Prototype +```c +int pal_destroy(); +``` + +### Parameters +``` +N/A +``` + +### Return value +``` +0: Success +-ENOSYS: The function is not supported +``` -- GitLab