Document Update for OpenSBI port

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

@@ -34,7 +34,7 @@ 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. 
+This involves two separate workflows: one for each of the platform provider and the enclave developer.
 
 Provisioning the Security Monitor
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -43,12 +43,9 @@ 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 
+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
 ~~~~~~~~~~~~~~~~~~~~~~
 

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

@@ -8,7 +8,7 @@ RISC-V presents us with a number of benefits besides just being open-source:
 
 * RISC-V has added security-oriented primitives (notably Physical Memory Protection) that enable efficient isolation.
 
-* RISC-V is an evolving and community driven ISA. Keystone can explore the design space of useful 
+* RISC-V is an evolving and community driven ISA. Keystone can explore the design space of useful
   security features, and feed good ideas back into the standards themselves.
 
 * RISC-V has a constantly expanding world of open-source cores and products. This gives Keystone a
@@ -30,10 +30,11 @@ 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.
+* rv64gc-lp64d (Sv39 virutal addressing mode)
+* rv32gc-ilp32d (Sv32 virtual addressing mode)
 
+Recently, Keystone enclaves in M/U-only machines are prototyped in FreeRTOS.
+We are planning to upstream the version in the near future.
 
 RISC-V Privilieged ISA
 -----------------------------------

docs/source/Getting-Started/Install-Dependencies.rst

@@ -14,16 +14,16 @@ Ubuntu
   gperf libgmp-dev libmpc-dev libmpfr-dev libtool texinfo tmux \
   patchutils zlib1g-dev wget bzip2 patch vim-common lbzip2 python \
   pkg-config libglib2.0-dev libpixman-1-dev libssl-dev screen \
-  device-tree-compiler expect makeself unzip cpio rsync cmake
+  device-tree-compiler expect makeself unzip cpio rsync cmake p7zip-full
 
 .. note::
   You need Git version >= 2.11.0 to use ``./fast-setup.sh``, because the script uses
   ``--shallow-clone`` for faster submodule initializtion.
 
-In order to use the Rust version of the security monitor, you will also need to install `rustup <https://rustup.rs>`_ and `llvm-9 <https://apt.llvm.org/>`_ (available in Ubuntu repositories in versions 18.04 and above). Then, run the following commands:
+In order to use the Rust version of the security monitor (only available for 0.X versions), you will also need to install `rustup <https://rustup.rs>`_ and `llvm-9 <https://apt.llvm.org/>`_ (available in Ubuntu repositories in versions 18.04 and above). Then, run the following commands:
 
 ::
-  
+
   rustup toolchain install nightly
   rustup +nightly component add rust-src
   rustup +nightly target add riscv64gc-unknown-none-elf

docs/source/Getting-Started/QEMU-Compile-Sources.rst

@@ -1,7 +1,7 @@
 Compile Sources
 -----------------------------
 
-Build All Components (RV64)
+Build All Components
 ##############################################################
 
 We use `CMake <https://cmake.org/>`_ as a build system. It lets you generate the Makefile for a
@@ -16,32 +16,26 @@ given configuration.
   cmake ..
   make
 
+Here are some useful CMake flags you can add:
+
+* ``-Dinitramfs=y``: This will compile the Linux kernel with buildroot image as the initramfs.
+* ``-DRISCV32=y``: This will conrigure the build with RV32. You should have ran ``BITS=32 ./fast-setup.sh``.
+* ``-DLINUX_SIFIVE=y``: This is a temporary flag for HiFive Unleashed board.
+* ``-DSM_PLATFORM=<platform>``: The security monitor will be compiled with platform sources in ``sm/plat/<platform>``. The default value is "generic".
+* ``-DUSE_RUST_SM=y``: Use the Rust port of the security monitor. Curently not supported in v1.0.
+
 In order to build the driver and the tests, and have the final images for QEMU, you need to run
 
 ::
 
   # in your <build directory>
   make image
 
-This updates all components except QEMU and the boot ROM.
-
-If you want to use ``initramfs``, use the following flag when running ``cmake``
-
-::
-
-  cmake .. -Dinitramfs=y
-
-If you want to use the Rust port of the Security Monitor, run ``cmake`` with ``-DUSE_RUST_SM=y``.
-
-Please refer to the following sections if you want to learn how to build each individual component.
-Otherwise, skip to :ref:`LaunchQEMU`.
-
-Most of the components will be built out-of-tree; in ``<build directory>/<component name>.build``
-directory.
-
 If you run into any issues, check our
 ``CMakeLists.txt`` and as it will always have the up-to-date build recipes.
 
+Please refer to the following sections if you want to learn how to build each individual component.
+Otherwise, skip to :ref:`LaunchQEMU`.
 
 Build Buildroot
 ##############################################################
@@ -85,7 +79,7 @@ The patch is located at ``patches/linux/``
   # in your <build directory>
   make linux
 
-Build Berkeley Bootloader (BBL) with Keystone Security Monitor
+Build OpenSBI Firmware with Keystone Security Monitor
 ##############################################################
 
 The following command will build the M-mode security monitor.
@@ -95,18 +89,6 @@ The following command will build the M-mode security monitor.
   # in your <build directory>
   make sm
 
-Optionally, you can specify the target platform when you run ``cmake``.
-
-::
-
-  # in your <build directory>
-  cmake .. -DSM_PLATFORM=fu540
-  make sm
-
-The default platform is "default", which does not have any platform-specific features.
-See ``riscv-pk/sm/platform/`` for available platforms.
-See :doc:`../Building-Components/Security-Monitor-Platform-Build` for details.
-
 Build Root-of-Trust Boot ROM
 ##############################################################
 

docs/source/Getting-Started/QEMU-Setup-Repository.rst

@@ -13,19 +13,22 @@ Quick Setup
 
 You can quickly setup everything by running ``./fast-setup.sh``. This script requires Git >= 2.11.0.
 
+If you want to use a different version of toolchain (e.g., compiled the toolchain from source),
+make sure that your toolchain binaries are in your PATH before running this command.
+
 ::
 
   ./fast-setup.sh
 
 This will download pre-compiled RISC-V tools and extract it to
-``riscv`` directory and setup submodules.
+``riscv64`` directory and setup submodules.
 
-If you want to compile RISC-V tools from source code, run
-``./setup.sh`` instead. This may be necessary on some platforms due to
-library issues.
+.. note::
+  If you want RV32 setup, you should do ``BITS=32 ./fast-setup.sh`` instead. The toolchain will be
+  installed in ``riscv32`` directory. Also, the SDK will be compiled and installed using RV32 toolchain.
 
 The script also installs Keystone SDK if ``KEYSTONE_SDK_DIR`` environment variable is not set.
-The default install directory of Keystone SDK is ``$(pwd)/sdk/build``.
+The default install directory of Keystone SDK is ``$(pwd)/sdk/build64`` (``$(pwd)/sdk/build32`` for RV32).
 If you want to change the install directory,
 please follow `SDK's README <https://github.com/keystone-enclave/keystone-sdk/blob/master/README.md>`_
 before running ``fast-setup.sh``.
@@ -49,51 +52,3 @@ For example, if you're using bash, then try:
 
   cat source.sh >> $HOME/.bashrc
 
-.. _QEMUSetupManual:
-
-Manual Setup
-########################
-
-If you used ``./fast-setup.sh`` or ``./setup.sh``, you may skip this section.
-This section explains the manual way of setting up the repository.
-
-First, sync and update all the submodules.
-You may need these commands whenever you checkout to a different branch (e.g., ``dev``, ``master``,
-etc).
-
-::
-
-  git submodule sync --recursive
-  git submodule update --init --recursive
-
-For additional inormation, see `git submodules <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_.
-
-Install the RISC-V GNU toolchain for cross compilation.
-See `riscv-gnu-toolchain <https://github.com/riscv/riscv-gnu-toolchain>`_ for details.
-
-::
-
-  cd riscv-gnu-toolchain
-  ./configure --prefix=$(pwd)/../riscv
-  make; make linux
-
-Install the Keystone SDK by following
-`SDK's README <https://github.com/keystone-enclave/keystone-sdk/blob/master/README.md>`_.
-
-::
-
-   cd build
-   export KEYSTONE_SDK_DIR=<keystone/sdk/install/directory>
-   cmake ..
-   make
-   make install
-
-To keep environment variables, add following lines to your ``.bashrc``.
-
-::
-
-  export RISCV=<path/to/keystone>/riscv
-  export PATH=$PATH:$RISCV/bin
-  export KEYSTONE_SDK_DIR=<keystone/sdk/install/directory>
-
-You can also manually run ``source source.sh`` to set the environment variables.

docs/source/Getting-Started/Running-Keystone-with-QEMU.rst

@@ -5,15 +5,14 @@ Testing Keystone with QEMU
 The latest QEMU supports RISC-V ISA.
 
 Keystone was tested in a QEMU fork in RISC-V (`GitHub <https://github.com/riscv/riscv-qemu>`_).
-The upstream QEMU is not currently supported due to several remaining issues (Ex: `See GitHub issue <https://github.com/keystone-enclave/keystone/issues/25>`_).
-Fixes will be upstreamed in the future.
 
 If you just want to quickly test Keystone with QEMU, you can start with Docker, which will take <10
 minutes.
 Setting the environment by yourself (without Docker) will take 1-2 hours.
 
 Start With Docker
 -----------------------
+
 The fastest way to try Keystone is through our `Docker <https://www.docker.com/>`_ image (Ubuntu 18.04).
 The image contains all of our source code, as well as a compiled kernel, QEMU, example binaries, SDK, and GNU tools.
 
@@ -51,7 +50,6 @@ In the interactive mode, you can run tests with the following commands:
   cd build
   make run-tests
 
-
 Start Without Docker
 -----------------------
 

docs/source/Getting-Started/index.rst

@@ -59,22 +59,24 @@ gitmodules or directories. This is a brief overview of them.
 
 ::
 
-	+ keystone/
-  	|-- bootrom/
-  	|	# Keystone bootROM for QEMU virt board, including trusted boot chain.
-  	|-- buildroot/
-  	|	# Linux buildroot. Builds a minimal working Linux image for our test platforms.
-  	|-- docs/
-  	|	# Contains read-the-docs formatted and hosted documentation, such as this article.
-  	|-- riscv-gnu-toolchain/
-  	|	# Unmodified toolchain for building riscv targets. Required to build all other components.
-  	|-- linux-keystone-driver/
-  	|	# A loadable kernel module for Keystone enclave.
-  	|-- riscv-linux/
-  	|	# Linux kernel with RISC-V patches. We use 4.15 with patches for the loadable module support.
-  	|-- riscv-pk/
-  	|	# Berkeley Bootloader (bbl) firmware + Keystone security monitor
-	|-- riscv-qemu/
-	|	# QEMU with RISC-V patches
-	+-- sdk/
-		# Tools, libraries, and example apps for building enclaves on Keystone
+    + keystone/
+    |-- patches/
+    |  # required patches for submodules
+    |-- bootrom/
+    |  # Keystone bootROM for QEMU virt board, including trusted boot chain.
+    |-- buildroot/
+    |  # Linux buildroot. Builds a minimal working Linux image for our test platforms.
+    |-- docs/
+    |  # Contains read-the-docs formatted and hosted documentation, such as this article.
+    |-- riscv-gnu-toolchain/
+    |  # Unmodified toolchain for building riscv targets. Required to build all other components.
+    |-- linux-keystone-driver/
+    |  # A loadable kernel module for Keystone enclave.
+    |-- linux/
+    |  # Linux kernel
+    |-- sm/
+    |  # OpenSBI firmware + Keystone security monitor
+    |-- qemu/
+    |  # QEMU
+    +-- sdk/
+       # Tools, libraries, and example apps for building enclaves on Keystone

docs/source/Security-Monitor/index.rst

@@ -12,17 +12,12 @@ The SM provides the following functionality:
 4. System PMP Synchronization
 5. Side-Channel Defenses
 
-.. attention::
-
-  Version 0.1 only implements 1, 2, and 3, supporting single-threaded enclave.
-
 The security monitor must be verified by the *root of trust* in hardware before being trusted.
 After the root of trust measures the SM it generates a keypair for remote attestation, signs the public key, and then continues booting.
 See `Chain of Trust <#>`_ for details.
 
 The OS and enclaves may call SM functions using the supervisor binary interface (SBI),
-which is implemented in RISC-V environment calls (i.e., ``ecall`` instruction).
-See `SBI Documentation <#>`_ for details.
+For detailed specification, see `SBI Documentation <https://github.com/keystone-enclave/sm/tree/master/spec>`_.
 
 Specific platforms
 ------------------
@@ -161,7 +156,7 @@ You can re-configure and re-build the ``bbl`` in the build directory:
 		--enable-sm \
 		--with-target-platform=<platform> \
 		--host=riscv64-unknown-linux-gnu \
-		--with-payload=<path to vmlinux> 
+		--with-payload=<path to vmlinux>
 
 	make
 
@@ -176,7 +171,7 @@ The platform directory ``sm/platform`` contains all current platform specific su
 Currently that is:
 ``default`` and ``fu540`` directories.
 
-   
+
 System PMP Synchronization
 -------------------------------------