Massive documentation update (#97)

* Massive documentation update
Contains rewrites, new tutorials, and re-organization of documentation.

docs/source/Building-Components/Eyrie.rst

@@ -0,0 +1,4 @@
+Configuring and building Eyrie
+==============================
+
+Upcoming

docs/source/Building-Components/Security-Monitor-Platform-Build.rst

@@ -0,0 +1,42 @@
+Building the Keystone Security Monitor
+===========================================
+
+The security monitor (SM) is the core component of Keystone.
+
+The SM is implemented on top of Berkeley Bootloader (bbl).
+You can find the latest SM at `<https://github.com/keystone-enclave/riscv-pk>`_ (upstream bbl:
+`<https://github.com/riscv/riscv-pk>`_).
+Most of the Keystone SM source code lives in ``sm`` directory.
+
+::
+
+	git clone https://github.com/keystone-enclave/riscv-pk
+	cd riscv-pk
+
+If you have followed :doc:`Quick Start <../Getting-Started/Running-Keystone-with-QEMU>`, the build directory is
+already created at ``hifive-work/riscv-pk``.
+Otherwise, create a build directory.
+
+::
+
+	mkdir build
+	cd build
+
+Configure and build ``bbl``. The SM can be built by additional flags ``--enable-sm`` and
+``--with-target-platform`` at configuration.
+
+::
+
+	../configure \
+		--enable-sm \
+		--with-target-platform=default \
+		--host=riscv64-unknown-linux-gnu \
+		--with-payload=<path to vmlinux> 
+
+	make
+
+This will generate the boot image ``bbl`` in the build directory. Use it to boot the machine.
+
+Now, we will customize the SM for a FU540 chip on HiFive Unleashed board.
+Currently, we only have one experimental platform configuration for FU540.
+If you wish to add your platform as a target, please submit a proposal to `GitHub <https://github.com/keystone-enclave/riscv-pk/issues>`_.

docs/source/Building-Components/Vault.rst

@@ -0,0 +1,72 @@
+Vault.sh
+========
+
+``vault.sh`` is a sample build script for building eapps/hosts,
+building an appropriate Eyrie configuration, and packaging all three
+into a self-extracting archive.
+
+In most cases, changing the variables in the script will be sufficient
+to build a custom enclave.
+
+The hello world
+:doc:`tutorial<../Getting-Started/Tutorials/Build-Enclave-App-Hello-World>`
+vault script is as follows:
+
+.. code-block:: bash
+
+	################################################################
+	#                   Replace the variables                      #
+	################################################################
+	NAME=hello
+	VAULT_DIR=`dirname $0`
+	BUILD_COMMAND="make -C eapp && make -C host"
+	OUTPUT_DIR=$KEYSTONE_SDK_DIR/../buildroot_overlay/root/$NAME
+	EYRIE_DIR=$KEYSTONE_SDK_DIR/rts/eyrie
+	EYRIE_PLUGINS="freemem untrusted_io_syscall linux_syscall env_setup"
+	PACKAGE_FILES="eapp/hello \
+	               host/runner \
+	               $EYRIE_DIR/eyrie-rt"
+	PACKAGE_SCRIPT="./runner hello eyrie-rt"
+
+We will go through what each variable is for, and how the script builds the enclave.
+
+``NAME`` defines the name of the enclave. It will be used to generate the final enclave package.
+
+``VAULT_DIR`` is the path to the script. The script will change the directory to ``$VAULT_DIR``
+before running the build commands.
+
+``BUILD_COMMAND`` defines the build commands. This example has ``Makefile`` in each of the
+directory, so the script just needs to execute ``make`` at each directory to build both the eapp and
+the host.
+
+``OUTPUT_DIR`` is the path to the output files. Since we started from :doc:`Quick Start
+<../Getting-Started/Running-Keystone-with-QEMU>`, we put the build outputs to the buildroot overlay directory so
+that we can see them in the QEMU disk image.
+
+``EYRIE_DIR`` is the path to the Eyrie runtime source code.
+
+``EYRIE_PLUGINS`` defines what plugins you want to include in the runtime.
+
+``PACKAGE_FILES`` defines which files you want to include in the final enclave package. 
+``vault.sh`` uses `Makeself <https://makeself.io/>`_ to generate a self-extracting archive for the
+enclave.
+The package usually includes the host binary (i.e., ``host/runner``), the eapp binary (i.e.,
+``eapp/hello``), and the runtime binary (i.e., ``$EYRIE_DIR/eyrie-rt``)
+
+``PACKAGE_SCRIPT`` defines the input command to ``makeself``. The self-extracting archive will
+execute this command after the decompression.
+
+Eyrie Runtime
+------------------------------
+
+If you have completed :doc:`Quick Start <../Getting-Started/Running-Keystone-with-QEMU>`, the runtime source code
+would have been already located at ``$EYRIE_DIR``.
+
+You can find the following command in ``vault.sh``, which builds the Eyrie runtime.
+
+::
+
+	$EYRIE_DIR/build.sh $EYRIE_PLUGINS
+
+
+

docs/source/Getting-Started/How-Keystone-Works/Keystone-Basics.rst

@@ -0,0 +1,107 @@
+Keystone Basics
+=========================================
+
+Keystone is an open framework for architecting trusted execution environments (TEEs) based on hardware enclaves.
+Keystone aims to provide an easy way of architecting and building a customized TEE for an arbitrary RISC-V platform with a simple workflow.
+This allows the TEE to be highly optimized for better performance, smaller trusted computing base (TCB),
+and programmability with a given workload and a threat model.
+
+Overview
+-------------------------------
+
+A Keystone-capable system consists of several components in different privilege modes.
+
+.. figure:: /_static/images/keystone_overview.png
+
+**Trusted Hardware** is a CPU package built by a trustworthy vendor, and must contain Keystone-compatible *standard RISC-V cores* and *root of trust*.
+The hardware may also contain optional features such as cache partitioning, memory encryption, cryptographically-secure source of randomness, etc.
+The Security Monitor requires platform specific plug-ins for optional feature support.
+
+**Security Monitor (SM)** is M-mode software with small TCB.
+The SM provides an interface for managing the lifecycle of enclave as well as for utilizing platform-specific features.
+The SM enforces most of Keystone's security guarantees since it manages the isolation boundary between the enclaves and the untrusted OS.
+
+**Enclaves** are environments isolated from the untrusted OS and other enclaves. Each enclave is given a private physical memory region which is accessible by only the enclave and SM.
+Each enclave consists of a user-level enclave application *eapp* and a supervisor-level *runtime*.
+
+**Enclave Application (eapp)** is the user-level application that executes in the enclave. One can build a custom eapp from the scratch, or just run an existing RISC-V executable in Keystone.
+
+**Runtime** is S-mode software which implements functionality such as system calls, trap handling, virtual memory management and so on.
+
+Keystone Workflow
+-------------------------------
+
+.. figure:: /_static/images/keystone_workflow.png
+
+Keystone is a framework wherein both *platform provider* and *enclave developer* customize elements of the system to their needs.
+This involves two separate workflows: one for each of the platform provider and the enclave developer. 
+
+Provisioning the Security Monitor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A **platform provider** the party who provides a machine which can run
+Keystone enclaves. In the *provisioning* stage, the platform provider
+compiles the security monitor and deploys it to the machine.
+
+The platform provider 
+configures(❶), builds(❷), and then deploys(❸) the security monitor with target hardware.
+
+See :doc:`/Building-Components/Security-Monitor-Platform-Build` to learn how to build and
+deploy the security monitor.
+
+Developing the Enclave
+~~~~~~~~~~~~~~~~~~~~~~
+
+A **enclave developer** develops an enclave with the Keystone SDK.
+The developer builds the eapp, the host, and the runtime binaries, and
+(optionally) packages them together into a single file (❹).
+
+The enclave components are then sent to the remote machine running
+Keystone and deployed (❺, ❻, and ❼).
+
+See :doc:`/Getting-Started/Tutorials/Build-Enclave-App-Hello-World` to learn how to build an
+enclave.
+
+Remote Attestation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Keystone supports basic remote attestation workflows. In these
+setups the enclave may present proof of its initial state and
+measurement by the SM to a remote party for validation (❽).
+
+See :doc:`/Getting-Started/Tutorials/Remote-Attestation` to learn how to implement a simple remote attestation flow.
+
+Enclave Lifecycle
+-------------------------------
+
+.. figure:: /_static/images/enclave_lifecycle.png
+
+
+Creation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An enclave starts with a contiguous range of physical memory called enclave private memory (EPM).
+The untrusted host first allocates the EPM, and initializes it with the enclave's page table (PT),
+the runtime (RT), and the eapp.
+Once the host calls the SM to create an enclave the SM isolates and protects the EPM using a PMP entry.
+The PMP status is propagated through all cores in the system so that the EPM is protected from any
+cores.
+After creation, but before execution, the SM measures and verifies the initial state of the enclave.
+
+Execution
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The host asks the SM to enter the enclave on one of the cores.
+The SM releases the PMP permission to the core, and the core starts to execute the enclave.
+The runtime can exit or re-enter the enclave any time.
+When a core exits/enters the enclave, it accordingly switches the PMP permissions to keep the
+isolation.
+
+Destruction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The host may destroy the enclave at any time.
+
+On destruction, the SM clears the EPM and releases the PMP entry.
+
+The host then finally reclaims the now-free memory.

docs/source/Getting-Started/How-Keystone-Works/RISC-V-Background.rst

@@ -23,6 +23,18 @@ To understand why this is true, see the next section explaining why using M-mode
   This document only contains high-level ideas of several components in the privileged ISA.
   For more details, please refer to `RISC-V Spec Documentations <https://riscv.org/specifications/>`_.
 
+
+ISA Compatibility
+----------------------------------
+
+Currently, Keystone is compatible with a specific subset of RISC-V ISA as follows:
+
+* Keystone requires all of three privilege modes (M/S/U) to support dynamic user-level isolation in Linux machines.
+* Keystone only supports RV64 (64-bit) with Sv39 addressing mode which translates 39-bit virtual addresses into 50-bit physical addresses based on a 3-level page table.
+
+We're actively working on extending compatibility of Keystone by supporting static isolation in M/U-only systems as well as RV32.
+
+
 RISC-V Privilieged ISA
 -----------------------------------
 
@@ -40,11 +52,10 @@ Common usage of each privilege level is as follows:
 * S-mode: kernel (including kernel modules and device drivers), hypervisor
 * M-mode: bootloader, firmware
 
+Some embedded devices may have only M-mode or only M/U modes.
 
-Only M-mode is required, and some embedded devices may have only M-mode or only M/U modes.
-
-M-mode is the highest privilege mode and controls all physical resources and events.
-M-mode is somewhat similar to microcode in complex instruction set computer (CISC) ISAs such as x86,
+M-mode is the highest privilege mode and controls all physical resources and interrupts.
+M-mode is analogous to microcode in complex instruction set computer (CISC) ISAs such as x86,
 in that it is not interruptible and free from interference of lower modes.
 
 Keystone uses M-mode for running the *security monitor (SM)*, the trusted computing base (TCB) of the system.
@@ -82,12 +93,11 @@ security. While the actual hardware implementation of PMP may vary
 among processors, the basic guarantees are part of the standard.
 
 
-:doc:`Keystone-Security-Monitor` relies on PMP for implementing memory isolation.
+:doc:`/Security-Monitor/index` relies on PMP for implementing memory isolation.
 
 Interrupts and Exceptions
 ----------------------------------
 
-
 By default, M-mode is the first receiver of any interrupts or
 exceptions (i.e., traps) in the system.  Thus, M-mode has complete
 authority over CPU scheduling and configuration, but may delegate this
@@ -112,11 +122,6 @@ addressing mode.
 The ``satp`` CSR determines which addressing mode MMU should use and which physical page contains the
 root page table for beginning page table walks.
 
-.. attention::
-
-  Keystone currently only supports RV64 with Sv39 addressing mode, which translates 39-bit virtual addresses into
-  50-bit physical addresses based on a 3-level page table.
-
 Although S-mode (the OS) may change ``satp`` arbitrarily, Keystone
 enclaves are not susceptible to any attacks based on altering the page
 table.  Enclaves are protected from external access by the OS with

docs/source/Getting-Started/How-Keystone-Works/index.rst

@@ -5,6 +5,4 @@ How Keystone Works
    :maxdepth: 2
 
    RISC-V-Background
-   Keystone-Security-Monitor
-   Platform-Integration
-   Runtime-And-SDK
+   Keystone-Basics