[Doc] Fix main menu and links

2026-09-07 06:14:02 +00:00 · 2019-12-02 16:00:23 +01:00
parent 295ef8ba6c
commit 42f00ee33f
16 changed files with 91 additions and 60 deletions
@@ -1,4 +1,4 @@
-.. _doc-howto:
+.. _howto-doc:

 How to write documentation
 ==========================
@@ -1,3 +1,6 @@
+# Debugging Graphene
+
+
 ## Running Graphene with GDB

 To enable GDB support, the PAL loader and Graphene implement the GDB protocol to notify the
@@ -1,3 +1,5 @@
+# Graphene Manifest Syntax
+
 ## Basic Syntax

 A manifest file is an application-specific configuration text file that specifies the environment
@@ -1,3 +1,5 @@
+# Graphene Quick Start
+
 (The following quick start instruction does not include the steps for running Graphene with
 sandboxing because sandboxing is an experimental feature.)

@@ -1,4 +1,6 @@
-The basic manifest syntax for Graphene is described in [[Graphene Manifest Syntax]]. If Graphene
+# Graphene SGX Manifest Syntax
+
+The basic manifest syntax for Graphene is described in [Graphene Manifest Syntax](Graphene-Manifest-Syntax.md). If Graphene
 is *not* running with SGX, the SGX-specific syntax is ignored. All keys in the SGX-specific syntax
 are optional. If the keys are not specified, Graphene will use the default values.

@@ -1,3 +1,5 @@
+# Graphene SGX Quick Start
+
 Before you run any applications in Graphene-SGX, please make sure that Intel SGX SDK and the SGX
 driver are installed on your system. We recommend using Intel SGX SDK and the SGX driver no older
 than version 2.1.
@@ -1,3 +1,5 @@
+# Implementing New System Calls in Graphene
+
 ### Step 1: Define the Interface of System Call and Name the Function in `LibOS/shim/src/shim_syscalls.c`

 For example, assume we are implementing `sched_setaffinity`. You must find the definition of
@@ -1,3 +1,5 @@
+# Introduction to Graphene SGX
+
 ## What is Intel SGX?

 SGX (Software Guard Extenstions) is a security feature of the latest Intel CPUs. According to
@@ -27,7 +29,7 @@ hashes and URIs of these binaries, is signed), similar to the Intel SGX SDK work

 ## How to Build Graphene with Intel SGX Support?

-Refer to the [[Quick Start | SGX Quick Start]] page on how to build and run Graphene-SGX.
+Refer to the [Quick Start](Graphene-SGX-Quick-Start.md) page on how to build and run Graphene-SGX.

 ### Prerequisites

@@ -38,7 +40,7 @@ users then ship the signed bundle to the untrusted host and run it inside the SG
 secure their workloads.

 The prerequisites to build Graphene are detailed in
-[[Prerequisites of Graphene | Home#what-is-the-prerequisite-of-running-my-applications-in-graphene]]).
+[Prerequisites of Graphene](Introduction-to-Graphene.html#prerequisites).

 ### Prerequisites for Developer

@@ -72,7 +74,7 @@ developer's machine. For security reasons, Graphene will not allow loading any b
 not signed/hashed.

 For applications that are prepared in the Graphene apps directory, such as GCC, Apache, and Bash
-(more are listed in [[Run Applications in Graphene]]), just type 'make SGX=1' in the corresponding
+(more are listed in [Run Applications in Graphene](Run-Applications-in-Graphene.md)), just type 'make SGX=1' in the corresponding
 directory. The scripts are automated to build the applications and sign their manifests in order
 to ship them to the untrusted host.

@@ -1,3 +1,5 @@
+# Introduction to Graphene
+
 ## What is Graphene Library OS?

 **Graphene library OS** is a lightweight guest OS that supports Linux multi-process applications.
@@ -12,7 +14,7 @@ hardware-encrypted memory regions (called SGX enclaves). SGX protects code and d
 enclave against privileged software attacks and against physical attacks on the hardware off the
 CPU package (e.g., cold-boot attacks on RAM). Graphene is able to run unmodified applications
 inside SGX enclaves, without the toll of manually porting the application to the SGX environment.
-For more information about SGX support, see [[Introduction to Graphene-SGX]].
+For more information about SGX support, see [Introduction to Graphene-SGX](Introduction-to-Graphene-SGX.md).

 ### What Hosts Does Graphene Currently Run On?

@@ -20,7 +22,7 @@ Graphene was developed to encapsulate all host-specific code in one layer, calle
 Adaptation Layer, or PAL. Thus, if there is a PAL for a given host, the library OS and applications
 will "just work".

-Porting Graphene to a new host only requires porting a PAL, by implementing the [[PAL Host ABI]]
+Porting Graphene to a new host only requires porting a PAL, by implementing the [PAL Host ABI](PAL-Host-ABI.md)
 using OS features of the host. To date, we ported Graphene to FreeBSD and Linux (the latter also
 with Intel SGX support). Support for more hosts is expected in the future.

@@ -58,7 +60,7 @@ To run tests, you also need the python3-pytest package:

 ## Build and Run Graphene

-See [[Graphene Quick Start]] for instructions how to quickly build and run Graphene.
+See [Graphene Quick Start](Graphene-Quick-Start.md) for instructions how to quickly build and run Graphene.

 ### Obtain Source Code

@@ -80,7 +82,7 @@ To build Graphene with debug symbols, run `make DEBUG=1` instead of `make`. You
 downloading the Glibc sources, use `GLIBC_MIRRORS=...` when running `make`. To build with `-Werror`,
 run `make WERROR=1`.

-Currently, Graphene has implemented [[these Linux system calls|Supported System Calls in Graphene]].
+Currently, Graphene has implemented [these Linux system calls](Supported-System-Calls-in-Graphene.md).
 Before running any application, you must confirm that all system calls required by the application
 executables and libraries are supported (or that unsupported system calls do not affect the
 functionality of the application).
@@ -94,7 +96,7 @@ See [EXPERIMENTAL/linux-reference-monitor](https://github.com/oscarlab/graphene/

 ### Build with Intel SGX Support

-See [[Graphene-SGX Quick Start]] for instructions on how to build and run Graphene with
+See [Graphene-SGX Quick Start](Graphene-SGX-Quick-Start.md) for instructions on how to build and run Graphene with
 Intel SGX support.


@@ -182,10 +184,10 @@ applications such as GCC, Bash, Redis, R, and Apache. The manifest files for the
 provided in the individual directories under `LibOS/shim/test/apps`.

 For the full documentation of the Graphene manifest syntax, please see the following pages:
-[Graphene Manifest Syntax]] and [[Graphene-SGX Manifest Syntax]].
+[Graphene Manifest Syntax](Graphene-Manifest-Syntax.md) and [Graphene-SGX Manifest Syntax](Graphene-SGX-Manifest-Syntax.md).

 For more details about running tested/benchmarked applications in Graphene, please see this page:
-[[Run Applications in Graphene]].
+[Run Applications in Graphene](Run-Applications-in-Graphene.md).


 #### Run Built-in Examples in Graphene-SGX
@@ -223,8 +225,8 @@ For more details about running tested/benchmarked applications in Graphene, plea

 Some documentation that might be helpful:

-* [[PAL Host ABI]]
-* [[Porting Graphene PAL to Other hosts]]
+* [PAL Host ABI](PAL-Host-ABI.md)
+* [Porting Graphene PAL to Other hosts](Porting-Graphene-PAL-to-Other-hosts.md)

 ## How to Contact the Maintainers?

@@ -1,3 +1,5 @@
+# PAL Host ABI
+
 ## What is Graphene's PAL Host ABI

 PAL Host ABI is the interface used by Graphene to interact with its host. It is translated into
@@ -21,7 +23,7 @@ PAL APIs. PAL does not and will not resolve other unresolved symbols, so the loa
 executables must resolve them afterwards.

 After loading the binaries, PAL needs to load and interpret the manifest files. The manifest syntax
-is described in [[Graphene Manifest Syntax]].
+is described in [Graphene Manifest Syntax](Graphene-Manifest-Syntax.md).

 ### Manifest and Executable Loading Rules

@@ -200,7 +202,7 @@ and aligned at the allocation alignment.

 This API modifies the permissions of a previously allocated memory mapping. Both `addr` and
 `size` must be non-zero and aligned at the allocation alignment. `prot` is defined as
-[[DkVirtualMemoryAlloc|PAL Host ABI#DkVirtualMemoryAlloc]].
+[DkVirtualMemoryAlloc](#dkvirtualmemoryalloc).

 ### Process Creation

@@ -318,7 +320,7 @@ write-side only, or both if 0 is given.
 This API maps a file to a virtual memory address in the current process. `address` can be NULL or
 a valid address that is aligned at the allocation alignment. `offset` and `size` have to be non-zero
 and aligned at the allocation alignment. `prot` is defined as
-[[DkVirtualMemoryAlloc|PAL Host ABI#DkVirtualMemoryAlloc]].
+[DkVirtualMemoryAlloc](#dkvirtualmemoryalloc).

 #### DkStreamUnmap

@@ -580,7 +582,7 @@ This API returns CPUID information in the array `values`, based on the leaf/subl

 This API creates a physical memory channel for the process to copy virtual memory as copy-on-write.
 Once a channel is created, other processes can connect to the physical memory channel by using
-[[DkStreamOpen|PAL Host ABI#DkStreamOpen]] with a URI `gipc:<key>`.
+[DkStreamOpen](#dkstreamopen) with a URI `gipc:<key>`.

 #### DkPhysicalMemoryCommit

@@ -1,3 +1,5 @@
+# Porting Graphene PAL to Other hosts
+
 ## Platform Compatibility of Graphene

 Graphene adopts a similar architecture to the Drawbridge Library OS, which runs a generic library
@@ -9,7 +11,7 @@ for this new host.

 To port Graphene to a new host platform, the only effort required is reimplementing the PAL on the
 desired host platform. Most of the implementation should be as simple as translating the PAL API
-to the native system interface of the host. The implemented PAL must support [[PAL Host ABI]].
+to the native system interface of the host. The implemented PAL must support [PAL Host ABI](PAL-Host-ABI.md).

 In fact, even in the PAL source code, we expect part of the code to be host-generic. To make porting
 Graphene easier, we deliberately separate the source code of PAL into three parts:
@@ -1,7 +1,9 @@
+# Process Creation in Graphene SGX
+
 (Disclaimer: This explanation is partially outdated. It is intended only as an internal
 reference for developers of Graphene, not as a general documentation for Graphene users.)

-# Fork in Graphene-SGX
+## Fork in Graphene-SGX

 Fork() system call is intercepted in the `shim_do_fork()` LibOS function. This function performs
 three tasks: (1) discovers the namespace leader, (2) creates a LibOS `shim_thread` structure for
@@ -9,7 +11,7 @@ a new thread, and (3) calls `do_migrate_process()`. The first two tasks are triv
 concentrate on the third one.


-## Parent: Fork via `do_migrate_process`
+### Parent: Fork via `do_migrate_process`

 The function `do_migrate_process()` creates a new process in the underlying OS, establishes a
 channel between the current process and the newly created child process, collects checkpoint data
@@ -44,7 +46,7 @@ faster than normal Unix streams. However, SGX PAL does not support GIPC. Thus, t
 sending to the child is done via a Unix stream.


-## Child: Initialization after Fork
+### Child: Initialization after Fork

 After the child is created, Pal-Linux-SGX enters the enclave using EENTER. The enclave code calls
 `pal_linux_main()` which in turn calls `init_child_process()`. The `init_child_process()` function
@@ -1,13 +1,15 @@
+# Run Applications in Graphene SGX
+
 We prepared and tested several applications to demonstrate Graphene-SGX usability. These applications
 can be directly built and run from the Graphene source:

-* [[LMBench (v2.5) | Run Applications in Graphene SGX#running lmbench in graphene]]
-* [[Python | Run Applications in Graphene SGX#running python in graphene]]
-* [[R | Run Applications in Graphene SGX#running r in graphene]]
-* [[Lighttpd | Run Applications in Graphene SGX#running lighttpd in graphene]]
-* [[Apache | Run Applications in Graphene SGX#running apache in graphene]]
-* [[Busybox | Run Applications in Graphene SGX#running busybox in graphene]]
-* [[Bash | Run Applications in Graphene SGX#running bash in graphene]]
+* [LMBench (v2.5)](#running-lmbench-in-graphene-sgx)
+* [Python](#running-python-in-graphene-sgx)
+* [R](#running-r-in-graphene-sgx)
+* [Lighttpd](#running-lighttpd-in-graphene-sgx)
+* [Apache](#running-apache-in-graphene-sgx)
+* [Busybox](#running-busybox-in-graphene-sgx)
+* [Bash](#running-bash-in-graphene-sgx)


 ## Running LMBench in Graphene-SGX
@@ -111,7 +113,7 @@ Apache, run the following commands:

 The commands above will compile the source code, build the manifest file for Graphene, generate
 the configuration file for Apache, and generate the HTML sample files (same as described in the
-[[lighttpd section|Run applications in Graphene#Running Lighttpd in Graphene]]).
+[lighttpd section](#running-lighttpd-in-graphene-sgx)).

 The server can be started manually via one of the following commands:

@@ -1,14 +1,16 @@
+# Run Applications in Graphene
+
 We prepared and tested several applications to demonstrate Graphene usability. These applications
 can be directly built and run from the Graphene source:

-* [[LMBench (v2.5) | Run Applications in Graphene#running lmbench in graphene]]
-* [[Python | Run Applications in Graphene#running python in graphene]]
-* [[R | Run Applications in Graphene#running r in graphene]]
-* [[GCC | Run Applications in Graphene#running gcc in graphene ]]
-* [[Lighttpd | Run Applications in Graphene#running lighttpd in graphene]]
-* [[Apache | Run Applications in Graphene#running apache in graphene]]
-* [[Busybox | Run Applications in Graphene#running busybox in graphene]]
-* [[Bash | Run Applications in Graphene#running bash in graphene]]
+* [LMBench (v2.5)](#running-lmbench-in-graphene)
+* [Python](#running-python-in-graphene)
+* [R](#running-r-in-graphene)
+* [GCC](#running-gcc-in-graphene)
+* [Lighttpd](#running-lighttpd-in-graphene)
+* [Apache](#running-apache-in-graphene)
+* [Busybox](#running-busybox-in-graphene)
+* [Bash](#running-bash-in-graphene)

 ## Running LMBench in Graphene

@@ -131,7 +133,7 @@ Apache, run the following command:

 The commands above will compile the source code, build the manifest file for Graphene, generate
 the configuration file for Apache, and generate the HTML sample files (same as described in the
-[[lighttpd section|Run applications in Graphene#Running Lighttpd in Graphene]]).
+[lighttpd section](#running-lighttpd-in-graphene)).

 The server can be started manually via one of the following commands:

@@ -1,7 +1,9 @@
+# Signal Handling in Graphene
+
 (Disclaimer: This explanation is partially outdated. It is intended only as an internal
 reference for developers of Graphene, not as a general documentation for Graphene users.)

-# Signal Handling
+## Signal Handling

 This analysis is written while Graphene's signal handling mechanisms are in flux. In future, all
 Graphene PALs should implement the same mechanism, and LibOS should adopt a better scheme to
@@ -49,9 +51,9 @@ in contrast to current LibOS approach of (1) delivering the first signal even in
 emulated syscall, and (2) pending nested signals until system-call completion.


-## Linux-SGX PAL Flows
+### Linux-SGX PAL Flows

-### Initialization of Signal Handling
+#### Initialization of Signal Handling

 ```
  Normal context
@@ -93,7 +95,7 @@ emulated syscall, and (2) pending nested signals until system-call completion.
 + + + rt_sigprocmask(SIGUNBLOCK, SIGSEGV | SIGILL | SIGFPE | SIGBUS)
 ```

-### Async Signal Arrives During Enclave Code Execution
+#### Async Signal Arrives During Enclave Code Execution

 On the example of SIGINT, until we arrive into `_DkGenericSignalHandle()`.

@@ -158,7 +160,7 @@ On the example of SIGINT, until we arrive into `_DkGenericSignalHandle()`.
          < ... >
 ```

-### Async Signal Arrives During Non-Enclave Code Execution
+#### Async Signal Arrives During Non-Enclave Code Execution

 Non-enclave code execution can only happen if Graphene process is currently executing untrusted-PAL
 code, e.g., is blocked on a `futex(wait)` system call.
@@ -208,12 +210,12 @@ On the example of SIGINT, until we arrive into `_DkGenericSignalHandle()`.
            < ... >                                              v
 ```

-### Sync Signal Arrives During Enclave Code Execution
+#### Sync Signal Arrives During Enclave Code Execution

 This case is exactly the same as for async signal. The only difference in the diagram would be that
 `_DkTerminateSighandler` is replaced by `_DkResumeSighandler`. But the logic is exactly the same.

-### Sync Signal Arrives During Non-Enclave Code Execution
+#### Sync Signal Arrives During Non-Enclave Code Execution

 Non-enclave code execution can only happen if Graphene process is currently executing untrusted-PAL
 code, e.g., is blocked on a `futex(wait)` system call.
@@ -223,7 +225,7 @@ or arithmetic exception in untrusted-PAL code. This should never happen in a cor
 of Graphene. In this case, `_DkResumeSighandler` simply kills the faulting thread (not the whole
 process!) by issuing `exit(1)` syscall.

-### DkGenericSignalHandle Logic
+#### DkGenericSignalHandle Logic

 ```
  Normal context (enclave mode)
@@ -267,9 +269,9 @@ process!) by issuing `exit(1)` syscall.
 ```


-## Linux PAL Flows
+### Linux PAL Flows

-### Initialization of Signal Handling
+#### Initialization of Signal Handling

 Very similar to the flow for Linux-SGX. In addition to 7 handled signals, Linux PAL also operates on
 these signals:
@@ -278,7 +280,7 @@ these signals:

 Describing flows for these signals is *future work*.

-### Async Signal Arrives During PAL Call Execution
+#### Async Signal Arrives During PAL Call Execution

 ```
  Normal context                                Signal context
@@ -312,7 +314,7 @@ Describing flows for these signals is *future work*.
 + +     _DkGenericSignalHandle(event, NULL, NULL)
 ```

-### Async Signal Arrives During Non-PAL Call Execution
+#### Async Signal Arrives During Non-PAL Call Execution

 ```
  Normal context                                Signal context
@@ -338,7 +340,7 @@ Describing flows for these signals is *future work*.
 +
 ```

-### Sync Signal Arrives During PAL Call Execution
+#### Sync Signal Arrives During PAL Call Execution

 ```
  Normal context                                Signal context
@@ -361,7 +363,7 @@ Describing flows for these signals is *future work*.
 ... thread is dead ...
 ```

-### Sync Signal Arrives During Non-PAL Call Execution
+#### Sync Signal Arrives During Non-PAL Call Execution

 ```
  Normal context                                Signal context
@@ -387,7 +389,7 @@ Describing flows for these signals is *future work*.
 +
 ```

-### DkGenericSignalHandle Logic
+#### DkGenericSignalHandle Logic

 ```
  Normal context (enclave mode)
@@ -430,11 +432,11 @@ Describing flows for these signals is *future work*.
 ```


-## Current LibOS Flows
+### Current LibOS Flows

 Note that LibOS flows are the same for all PALs.

-### Non-Nested Signal Case
+#### Non-Nested Signal Case

 On the example of `suspend_upcall()`.

@@ -488,7 +490,7 @@ On the example of `suspend_upcall()`.
 + DkExceptionReturn(event)
 ```

-### Nested Signal Case
+#### Nested Signal Case

 On the example of `suspend_upcall()`. Assumes `tcb.context.preempt = 1` (in a signal handler).
 ```
@@ -544,7 +546,7 @@ On the example of `suspend_upcall()`. Assumes `tcb.context.preempt = 1` (in a si
 + + +     + < handles pended SIGINT from tcb.thread.signal_logs[SIGINT]
 ```

-### Available Signal Handlers and Their Differences
+#### Available Signal Handlers and Their Differences

 (Notation: <Linux signal> -> PAL signal -> LibOS signal handler (purpose))

@@ -647,7 +649,7 @@ illegal_upcall(event, context)
 ```


-# Alarm() Emulation
+## Alarm() Emulation

 SIGALRM signal is blocked in Graphene. Therefore, on `alarm()` syscall, SIGALRM is generated and
 raised purely by LibOS.
@@ -713,7 +715,7 @@ shim_do_alarm(seconds)                          ... no alive host thread ...
 ```


-# Bugs and Issues
+## Bugs and Issues

 * BUG? Graphene LibOS performs `DkThreadYieldExecution()` in `__handle_signal()` (i.e., yield
 thread execution after handling one pending signal). Looks useless.
@@ -1,3 +1,5 @@
+# Supported System Calls in Graphene
+
 The following is a list of system calls that are currently implemented.

 ## System Calls that are Fully Implemented