Merge pull request #63 from dkohlbre/dev-docs-03

Docs cleanup and updating. Fixed some remaining incorrect build refer…

README.md

@@ -5,6 +5,9 @@
 
 Visit [Project Website](https://keystone-enclave.org) for more information.
 
+The ``dev`` branch is more up-to-date than ``master`` always. Until
+there are stable releases we suggest only using ``dev``.
+
 # Quick Start
 
 ```bash
@@ -59,7 +62,9 @@ poweroff
 
 # Documentation
 
-See [docs](http://docs.keystone-enclave.org) for detailed documentation.
+See [docs](http://docs.keystone-enclave.org) for detailed
+documentation. You may wish to switch to the dev version of the docs,
+rather than 'latest'.
 
 # Contributing
 

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

@@ -36,5 +36,17 @@ specific builds!
 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.
+General workflow is as follows:
+
+ - Fork ``keystone`` repo
+ - Create a branch (ex: ``dev-cool-feature``)
+ - PR your branch to ``keystone`` on the ``dev`` branch
+ - Make sure all CI tests pass
+ - Wait for reviews
+
+If you are modifying a submodule:
+
+ - Fork ``$submodule`` repo
+ - Create a branch (ex: ``keystone-another-fix``)
+ - PR your branch to ``$submodule`` on ``keystone`` branch
+ - Wait for reviews

docs/source/Getting-Started/Guide-to-Components.rst

@@ -9,13 +9,20 @@ bootrom
 
 Keystone bootrom, including trusted boot chain.
 
+buildroot
+---------
+
+Link: `<https://github.com/keystone-enclave/buildroot>`_
+
+Linux buildroot. Builds a minimal working Linux image for our test platforms.
+
 busybear-linux
 --------------
 
 Link: `<https://github.com/keystone-enclave/busybear-linux>`_
 
-Unmodified busybear Linux, supporting riscv. Our default untrusted
-Linux OS for testing.
+Unmodified busybear Linux, supporting riscv. Deprecated. Soon to be
+removed.
 
 docs
 ----

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

@@ -13,7 +13,8 @@ platforms.
 Building for HiFive
 -------------------
 
-Building for the HiFive is straight-forward, run ``make hifive``.
+Building for the HiFive is straight-forward, run ``make``. The default
+build will work on the board.
 
 This will build a new copy of the kernel, driver, and generate a full
 buildroot Linux image.
@@ -54,7 +55,8 @@ 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
+You only need to reprogram the FSBL when modifying the first-stage
+bootloader itself. (Likely never)
 
 ::
 
@@ -67,7 +69,7 @@ You only need to reprogram the FSBL when modifying
   LINUX=0FC63DAF-8483-4772-8E79-3D69D8477DE4
   FSBL=5B193300-FC78-40CD-8002-E86C45580B47
 
-  MKE2FS=/usr/local/opt/e2fsprogs/sbin/mke2fs
+  MKE2FS=mke2fs
   DISK=$1
   echo "Operating on $DISK"
   test -b $DISK
@@ -91,7 +93,7 @@ You only need to reprogram the FSBL when modifying
   echo "Copying FSBL"
 
   # Setup the FSBL FS and copy the bin into it
-  $MKE2FS -t ext3 $PART2
+  $MKE2FS -t ext3 $PART_FSBL
   echo "COPYING FSBL to $PART_FSBL"
   dd if=fsbl.bin of=$PART_FSBL
 
@@ -118,24 +120,23 @@ 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
+Once booted, setup the network 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.
+All tests are automatically built and added to the hifive image. If
+you wish to update them after modifying the sdk/etc on a board currently available on 10.0.0.3:
 
-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/
+  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:
+  scp -o "UserKnownHostsFile /dev/null" hifive-bins/* root@10.0.0.3:
 
 
 Run binaries

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

@@ -59,7 +59,7 @@ Build All
 If you want to build all, simply run ``make``.
 
 (You may run ``make busybear`` which will build a Busybear based
-qemu-only image, this is in the process of being depricated and
+qemu-only image, this is in the process of being deprecated and
 eventually will be removed)
 
 ``PATH`` must include the RISC-V tool path.