Prepare for v0.3 Release (#103)

(1) Move `tests` from `sdk/examples` to `keystone/tests/tests`

Test programs are not example applications, they are "test programs" for `keystone`.
Also, moving them will remove the custom commands (i.e., `make -C sdk tests`) for building tests from `sdk` repo.

(2) Separate `make`, `make run-tests`, and `make image`

Currently `make` compiles everything and then also copies driver/tests into disk and re-run `make`.
This can be better separated into two process, `make` and `make run-tests`:
`make` just builds everything; `make run-tests` copies the driver/tests and rebuild with init ram disk, and and then run scripts to boot machine/run tests (like in travis test).
This will make it easy to explain in the docs.
+ `make images` will be used for re-building initrd image.

(3) Documentation Updates for v0.3

* Corrected type for keystone demo doc entry in getting started
* Newline added
* Added some brief descriptions of building and configuring Eyrie
* Tutorials typo fixes
* Update docs to make more sense
* Update README.md

(4) Others

* Bump SDK for valid eyrie.version
* Changed Travis: travis was ALWAYS building buildroot twice because of buildroot/dl directory. We used a hacky way (i.e., `mkdir -p buildroot/dl` before build) to avoid this.
This resulted in reduced build time in Travis.
* Removing unused parts of hifive.mk

Co-authored-by: dkohlbre <dkohlbre@cs.ucsd.edu>

.gitignore

@@ -1 +1,2 @@
+*.swp
 riscv/

.travis.yml

@@ -53,6 +53,7 @@ addons:
     - libpixman-1-dev
     - libssl-dev
     - makeself
+    - unzip
 
 branches:
   only:
@@ -79,7 +80,7 @@ jobs:
       script:
         - source ./source.sh
         - travis_wait 120 make -j2
-        - travis_wait 10 ./scripts/travis.sh
+        - travis_wait 10 make run-tests
         - cd riscv-qemu; git clean -fxd > /dev/null;git reset --hard > /dev/null;rm -rf .git;mv ../riscv-qemu-git  .git;cd ..
         - cd riscv-linux;git clean -fxd > /dev/null;git reset --hard > /dev/null;rm -rf .git;mv ../riscv-linux-git .git;cd ..
       after_failure:

Makefile

@@ -14,10 +14,20 @@ qemu:
 
 .PHONY: hifive
 hifive: $(QEMU) $(BOOTROM)
+	mkdir -p buildroot/dl
 	$(MAKE) -f hifive.mk
+
+image:
+	mkdir -p buildroot/dl
 	$(MAKE) -C hifive-work/buildroot_initramfs
 	$(MAKE) -f hifive.mk
 
+run-tests: $(hifive)
+	./tests/tests/vault.sh
+	$(MAKE) -C hifive-work/buildroot_initramfs
+	$(MAKE) -f hifive.mk
+	./scripts/travis.sh
+
 $(QEMU):
 	./scripts/apply-patch.sh
 	cd $(QEMU_DIR); ./configure --target-list=riscv64-softmmu,riscv32-softmmu;
@@ -26,5 +36,8 @@ $(QEMU):
 $(BOOTROM):
 	cd bootrom; make; cd ..
 
+sdk:
+	$(MAKE) -C sdk
+
 clean:
 	$(MAKE) -f hifive.mk clean

README.md

@@ -1,4 +1,4 @@
-# Keystone Enclave: An Open-Source Secure Enclave for RISC-V Processors
+# Keystone: An Open-Source Secure Enclave Framework for RISC-V Processors
 
 ![Documentation Status](https://readthedocs.org/projects/keystone-enclave/badge/)
 [![Build Status](https://travis-ci.org/keystone-enclave/keystone.svg?branch=master)](https://travis-ci.org/keystone-enclave/keystone/)
@@ -19,10 +19,12 @@ Install Dependencies (Ubuntu)
 
 ```
 sudo apt update
-sudo apt install autoconf automake autotools-dev bc bison build-essential curl \
-expat libexpat1-dev flex gawk gcc git 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 device-tree-compiler expect
+sudo apt install autoconf automake autotools-dev bc \
+bison build-essential curl expat libexpat1-dev flex gawk gcc git \
+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 \
+device-tree-compiler expect makeself unzip
 ```
 
 Checkout branch (optional)
@@ -40,31 +42,25 @@ Build All
 make
 ```
 
-Run QEMU
-```
-./scripts/run-qemu.sh
-```
-
-Test
-
-login with `root`/`sifive`.
-
-```
-[in QEMU machine]
-insmod keystone-driver.ko
-./test
-```
+## Test
 
-Terminate QEMU
 ```
-poweroff
+make run-tests
 ```
 
 ## Rebuilding
 
 Any modifications in a submodule should be built with the top-level
 `make` in Keystone.
 
+## Adding Files
+
+Any additional files/binaries to be included in the image should be
+placed in `keystone/buildroot_overlay/root/`.
+
+The top-level `make image` will rebuild the image to contain any new files
+added.
+
 # Documentation
 
 See [docs](http://docs.keystone-enclave.org) for detailed

docs/source/Building-Components/Eyrie.rst

@@ -1,4 +1,29 @@
 Configuring and building Eyrie
 ==============================
 
-Upcoming
+The Eyrie runtime can be configured and built either with standard
+``make`` and setting the ``OPTIONS_FLAGS`` environment variable, or by
+using the ``build.sh`` wrapper script.
+
+OPTIONS_FLAGS
+-------------
+
+Eyrie supports specifiying plugins via the ``OPTIONS_FLAGS``
+environment variable. See the Eyrie Makefile and ``build.sh`` wrapper
+for an up-to-date list of plugins.
+
+
+build.sh wrapper
+----------------
+
+``build.sh`` supports automatically setting and rebuilding the Eyrie
+runtime based on commandline options.
+
+Example::
+
+  ./build.sh freemem env_setup
+
+Will cleanly rebuild Eyrie with free memory management and libc-style
+environment initialization.
+
+An example of using the wrapper can be seen in :doc:`vault.sh<Vault>`.

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

@@ -0,0 +1,17 @@
+Install Dependencies
+----------------------------
+
+We tested Keystone with QEMU Ubuntu 16.04/18.04 and derivatives.
+
+Ubuntu
+#######################
+
+::
+
+  sudo apt update 
+  sudo apt install autoconf automake autotools-dev bc \
+  bison build-essential curl expat libexpat1-dev flex gawk gcc git \
+  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 \
+  device-tree-compiler expect makeself unzip

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

@@ -0,0 +1,80 @@
+Compile Sources
+-----------------------------
+
+Build All
+#################
+
+If you want to build all, simply run ``make``. This also rebuilds any
+modifications.
+
+``PATH`` must include the RISC-V tool path.
+
+::
+
+  make
+
+If you want to manually build each individual component, please follow
+the instructions below. If you run into any issues, check our
+``Makefile`` and ``hifive.mk`` as they will always have up-to-date
+build instructions.
+
+Otherwise, skip to :ref:`LaunchQEMU`.
+
+Build Buildroot
+########################
+
+This is handled as part of the top-level make, see ``hifive.mk`` for
+details.
+
+Buildroot configuration is in ``hifive-conf/buildroot_initramfs_config``.
+
+Build RISC-V QEMU
+##################
+
+You should apply patches before building QEMU/Linux.
+
+::
+
+  ./scripts/apply-patch.sh
+
+
+::
+
+  cd riscv-qemu
+  ./configure --target-list=riscv64-linux-user,riscv64-softmmu,riscv32-linux-user,riscv32-softmmu
+  make
+  cd ..
+
+Build Linux Kernel
+################################################
+
+This is handled as part of the top-level make, see ``hifive.mk`` for
+details.
+
+Kernel configuration is in ``hifive-conf/linux_cma_config``.
+
+
+Build Berkeley Bootloader (BBL) with Keystone Security Monitor
+##############################################################
+
+This is handled as part of the top-level make, see ``hifive.mk`` for
+details.
+
+Optionally, add ``--with-target-platform=PLATFORM`` if you have a
+platform specific set of files for the security monitor (defined in ``riscv-pk/sm/platform/``). See
+:doc:`../Building-Components/Security-Monitor-Platform-Build` for details.
+
+Build Root-of-Trust Boot ROM
+###############################
+
+::
+
+  cd bootrom
+  make
+  cd ..
+
+Build Keystone Driver
+##############################
+
+This is handled as part of the top-level make, see ``hifive.mk`` for
+details.

docs/source/Getting-Started/QEMU-Run-Tests.rst

@@ -0,0 +1,86 @@
+.. _LaunchQEMU:
+
+Run Tests
+--------------------------------------
+
+Now, you're ready to use QEMU to boot Keystone Security Monitor and Linux on top of it.
+
+Simply running following command will build and run tests in QEMU.
+
+::
+
+  make run-tests
+
+If you wish to compile and run tests by your self, follow the following instructions.
+
+Build Test Binaries
+#############################
+
+Simple tests live under ``tests/tests``.
+You can build the tests by executing ``tests/tests/vault.sh`` (See :doc:`../Building-Components/Vault`).
+Note that ``KEYSTONE_SDK_DIR`` must be set to a built SDK path.
+
+::
+
+  ./tests/tests/vault.sh
+
+This command will generate the enclave package named ``tests.ke`` in
+``buildroot_overlay/root/tests`` directory.
+
+Build Disk Image (initrd)
+#############################
+
+Next, you need to copy the enclave package into the disk image that you're going to boot on.
+
+We use `Buildroot Overlay <https://buildroot.org/downloads/manual/manual.html#rootfs-custom>`_ for
+injecting the test binaries into the disk image.
+The buildroot overlay directory is ``buildroot_overlay``.
+
+::
+
+  make image
+
+This command will re-generate the Linux kernel with ``initrd`` containing overlay root file system
+in ``buildroot_overlay``.
+
+Launch QEMU
+#############################
+
+The following script will run QEMU, start executing from the emulated silicon root of trust.
+The root of trust then jumps to the SM, and the SM boots Linux!
+
+::
+
+   ./scripts/run-qemu.sh
+
+Login as ``root`` with the password ``sifive``.
+
+
+You can exit QEMU by ``ctrl-a``+``x`` or using ``poweroff`` command
+
+Note that the launch scripts for QEMU will start ssh on a random
+forwarded localhost port (this is to allow multiple qemu test runs on
+the same development machine). The script will print what port it has
+forwarded ssh to on start.
+
+Insert Keystone Driver
+##################################
+
+Insert the keystone driver.
+
+::
+
+    insmod keystone-driver.ko
+
+Run Tests
+##################################
+
+`fast-setup.sh` or `setup.sh` script has already built the SDK and small test enclaves and put the binaries into the buildroot root file system.
+The source code of test enclaves are in `sdk/examples/tests` directory.
+
+You can run the test enclaves by using a self-extracting keystone archive called `tests.ke` generated by the SDK.
+
+::
+
+  cd ./tests
+  ./tests.ke