Merge pull request #51 from dkohlbre/dev-docs-hw

Added new page on building and running Keystone on the hifive board. …

docs/source/Contributing-to-Keystone/How-to-Contribute.rst

@@ -9,8 +9,8 @@ bootloader modifications, to make compilers and toolchains for programming encla
 support for novel use-cases for end users.
 
 
-Knwon Issues and Ongoing Projects
---------------------------------
+Known Issues and Ongoing Projects
+---------------------------------
 
 Known issues are updated in `github issues <https://github.com/keystone-enclave/keystone/issues>`_.
 We also post ongoing projects on `github projects <https://github.com/keystone-enclave/keystone/projects>`_.
@@ -37,4 +37,4 @@ General Contributions
 --------------------------------
 
 Fork ``keystone`` repo to your own account, mess around, and submit a pull request (PR) to the remote ``develop`` branch.
-A PR must be separated if it contains multiple patches for different parts.
+A PR must be separated if it contains multiple patches for different parts.

docs/source/Getting-Started/Running-Keystone-on-Hardware.rst

@@ -0,0 +1,152 @@
+Running Keystone on Hardware
+============================
+
+Currently we only support the SiFive HiFive Unleashed development
+board (referred to as HiFive for the rest of this document) with an
+FU540 chip.
+
+With some reconfiguration of ``riscv-pk`` and ``buildroot`` it should be
+possible to build and run Keystone on other Linux-booting RISC-V
+platforms.
+
+
+Building for HiFive
+-------------------
+
+Building for the HiFive is straight-forward, run ``make hifive``.
+
+This will build a new copy of the kernel, driver, and generate a full
+buildroot Linux image.
+
+All HiFive specific build elements are done in ``keystone/hifive-work``.
+
+
+Setting up the HiFive
+---------------------
+
+Setup Bootloader
+################
+
+First, you will need to get a working custom first-stage bootloader
+(FSBL) working on your board. This will require creating a new
+partition on your SD card as well as setting the MSEL2 dipswitch. See
+https://github.com/sifive/freedom-u540-c000-bootloader/issues/9#issuecomment-424162283
+for details.
+
+For the bootloader itself, you'll need to build our copy of the bootloader:
+https://github.com/keystone-enclave/freedom-u540-c000-bootloader .
+
+Make sure to flash this to the right partition type (see github thread
+or example script below).
+
+Load Linux Image
+################
+
+The hifive build process generates a bbl.bin in
+``hifive-work/bbl.bin``. Flash this to the Linux partition on the
+card.
+
+
+Example loading script
+######################
+
+This is an example of a script to load the FSBL and BBL into a card
+for use on the HiFive. Be careful as this will repartition the target
+disk!
+
+You only need to reprogram the FSBL when modifying
+
+::
+
+  #!/bin/bash
+
+  set -e
+
+  # Relevant partition type codes
+  BBL=2E54B353-1271-4842-806F-E436D6AF6985
+  LINUX=0FC63DAF-8483-4772-8E79-3D69D8477DE4
+  FSBL=5B193300-FC78-40CD-8002-E86C45580B47
+
+  MKE2FS=/usr/local/opt/e2fsprogs/sbin/mke2fs
+  DISK=$1
+  echo "Operating on $DISK"
+  test -b $DISK
+
+  echo "$DISK exists, paritioning..."
+
+  # Configure the partitions on the disk.
+  # NOTE: The block ranges given here are for the 8GB card we are using
+  #       You may wish to use different partition sizes.
+  sgdisk --clear \
+         --new=1:2048:67583  --change-name=1:bootloader --typecode=1:$BBL   \
+         --new=2:264192:     --change-name=2:root       --typecode=2:$LINUX \
+         --new=3:67584:69631 --change-name=3:siv-fsbl   --typecode=3:$FSBL \
+         $DISK
+  sleep 1
+
+  PART_BBL=$DISK"1"
+  PART_LINUX=$DISK"2"
+  PART_FSBL=$DISK"4"
+
+  echo "Copying FSBL"
+
+  # Setup the FSBL FS and copy the bin into it
+  $MKE2FS -t ext3 $PART2
+  echo "COPYING FSBL to $PART_FSBL"
+  dd if=fsbl.bin of=$PART_FSBL
+
+  echo "Copying Linux image"
+
+  # Copy the Linux image in
+  echo "COPYING BBL to $PART_BBL"
+  dd if=bbl.bin of=$PART_BBL bs=4096
+
+
+Running on the HiFive
+---------------------
+
+Our default build process does not copy any of the binaries or driver
+onto the Linux image.
+
+You will need to ``scp`` these files over to the board.
+
+You can also copy these into the HiFive initramfs work directory and
+rebuild the image to avoid setting up the network/etc.
+
+Setup network
+#############
+
+Attach to the serial console on the HiFive board.
+
+Boot the HiFive with the custom FSBL/Linux as described above.
+
+Once booted, setup the netowrk such that you can connect to it from
+your development machine. (Either a local network or a simple
+unmanaged switch works)
+
+Copy Files
+##########
+
+You'll want to copy over the driver, runtime, and any binaries you
+wish to run.
+
+Ex: to run SDK tests on a board available at 10.10.10.3
+
+::
+
+  mkdir hifive-bins
+  cp keystone/keystone/sdk/runtime/eyrie-rt ~/keystone/keystone/hifive-work/linux-keystone-driver/*.ko ~/keystone/keystone/sdk/bin/* hifive-bins/
+
+  scp -o "UserKnownHostsFile /dev/null" hifive-bins/* root@10.10.10.3:
+
+
+Run binaries
+############
+
+Insert the Keystone driver, and run whatever test binaries you wish.
+
+Example
+::
+
+   insmod keystone-driver.ko
+   ./test.sh

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

@@ -15,6 +15,7 @@ We tested Keystone with QEMU on CentOS and Ubuntu 16.04/18.04
 
 Cent OS
 ###########
+NOTE: This package list is known to be incorrect. It will be updated.
 
 ::
 
@@ -31,8 +32,8 @@ 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
+  libtool texinfo tmux patchutils zlib1g-dev wget bzip2 patch vim-common lbzip2 \
+  python pkg-config libglib2.0-dev libpixman-1-dev libssl-dev
 
 Quick Setup
 ----------------------------
@@ -57,7 +58,7 @@ Compile Sources
 Build All
 ########################
 
-If you want to build all, simply run ``make``. 
+If you want to build all, simply run ``make``.
 
 ``PATH`` must include the RISC-V tool path.
 
@@ -66,14 +67,14 @@ If you want to build all, simply run ``make``.
   make
 
 If you want to manually build each individual component, please follow the instructions below.
-Otherwise, skip to :ref:`LaunchQEMU`. 
+Otherwise, skip to :ref:`LaunchQEMU`.
 
 .. attention::
 
   Currently, ``make`` requires sudo previlege to build Busybear image.
   We are going to get rid of this requirement in the future.
 
-Build Busybear 
+Build Busybear
 ################################
 
 See `Busybear repo <https://github.com/michaeljclark/busybear-linux>`_ for more information.
@@ -126,7 +127,7 @@ Make sure to add ``--enable-sm`` when you run ``configure`` so that the security
   make
   cd ../..
 
-Build Root-of-Trust Boot ROM 
+Build Root-of-Trust Boot ROM
 ###############################
 
 ::
@@ -205,4 +206,3 @@ To run all tests, you could simply run
 ::
 
   ./test
-

docs/source/Getting-Started/index.rst

@@ -20,12 +20,11 @@ You can migrate the Keystone enclave into arbitrary RISC-V processor, with a ver
   We recommend you to use Keystone only for research purposes until it gets stablized.
   We appreciate any contribution for making Keystone better.
 
-See the Keystone-Demo section for temporary documentation for running on the HiFive board. Detailed instructions will be forthcoming.
-
 Quick Start
 ----------------------------------------
 .. toctree::
    :maxdepth: 2
 
    Running-Keystone-with-QEMU
    Running-Keystone-with-FireSim
+   Running-Keystone-on-Hardware