Skip to content

Commit

Permalink
Updated documentation based on recent changes, mostly removing statem… (
Browse files Browse the repository at this point in the history
keystone-enclave#92)

* Updated documentation based on recent changes, mostly removing statements or clarifying builds.

* Link corrections, updated index page language

* Updated readme to suggest using dev branch specifically in workflow
  • Loading branch information
dkohlbre authored May 8, 2019
1 parent 5d4f076 commit a31c8ef
Show file tree
Hide file tree
Showing 9 changed files with 86 additions and 85 deletions.
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,11 @@ 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
```

Checkout branch (optional)
```
git checkout dev
```

Setup Tools and Submodules
```
./fast-setup.sh
Expand Down
2 changes: 2 additions & 0 deletions docs/source/Getting-Started/Guide-to-Components.rst
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,8 @@ riscv-gnu-toolchain
Unmodified toolchain for building riscv targets. Required to build all
other components.

Prebuilt toolchains are available `here <https://github.com/keystone-enclave/firesim-riscv-tools-prebuilt/releases>`.

linux-keystone-driver
---------------------

Expand Down
35 changes: 14 additions & 21 deletions docs/source/Getting-Started/How-to-Debug.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,23 @@

## How to debug the security monitor (bbl) and the linux kernel?

We use QEMU+GDB to debug the security monitor or the kernel.
QEMU is an effective way to debug them.

First, add `-s -S` flags to the QEMU command.
You can simply edit `run-qemu.sh` to add `-s -S` flags.
We use QEMU+GDB to debug the security monitor or the kernel.
QEMU is an effective way to debug them.

```bash
./riscv-qemu/riscv64-softmmu/qemu-system-riscv64 -s -S #...etc...
./scripts/run-qemu.sh -debug
```

All cores will immediately hang at the first instruction (i.e., bootrom), waiting for `gdb` to be attached.

Now, run `gdb` in another terminal.
You can feed it with the bbl binary or the kernel image to add debug information.
(You may want to compile them with the debugging flag `-g`)
Now, run a riscv `gdb` in another terminal. You can feed it with the
bbl binary or the kernel image to add debug information. (You may
want to compile them with the debugging flag `-g`)

For example, if you want to debug with the `bbl` symbols

```bash
riscv64-unknown-linux-gnu-gdb ./riscv-pk/build/bbl
riscv64-unknown-linux-gnu-gdb ./hifive-work/riscv-pk/bbl
```

If you want to debug with the kernel's debug information
Expand All @@ -36,9 +33,9 @@ Then, attach to QEMU:
(gdb) target remote localhost:1234
```

Now, you can start debugging the SM (bbl) or the kernel.
Try to set breakpoints and run.
Now, you can start debugging the SM (bbl) or the kernel.
Try to set breakpoints and run.

Before setting breakpoints, you should run following command:

```
Expand All @@ -49,16 +46,12 @@ To see why we need that command, see [this issue](https://github.com/riscv/riscv

## Logging QEMU debug messages

QEMU provides a great option to collect the logs.
If you add `-D [filename]` flag to the QEMU command, it will print out the logs into `[filename]`.
You can also choose which kind of logs you want to print out, using `-d [options]` flag.
QEMU provides a great option to collect the logs.
If you add `-D [filename]` flag to the QEMU command, it will print out the logs into `[filename]`.

You can also choose which kind of logs you want to print out, using `-d [options]` flag.
For example,

```bash
./riscv-qemu/riscv64-softmmu/qemu-system-riscv64 -d in_asm -D debug.log #...etc...
```

## Using `debug.sh`
Actually, `debug.sh` contains everything you need.
run `debug.sh`, run gdb, and attach to QEMU!
28 changes: 12 additions & 16 deletions docs/source/Getting-Started/Running-Keystone-on-Hardware.rst
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,6 @@ build will work on the board.
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
---------------------

Expand All @@ -45,7 +42,8 @@ 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.
card. (Note that this is a relocated version of the bbl binary used
for QEMU)


Example loading script
Expand Down Expand Up @@ -90,26 +88,24 @@ bootloader itself. (Likely never)
PART_LINUX=$DISK"2"
PART_FSBL=$DISK"4"

echo "Copying FSBL"

# Setup the FSBL FS and copy the bin into it
$MKE2FS -t ext3 $PART_FSBL
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"
test -b $PART_BBL
dd if=bbl.bin of=$PART_BBL bs=4096
echo "Copy done"

echo "COPYING FSBL to $PART_FSBL"
test -b $PART_FSBL
$MKE2FS -t ext3 $PART_FSBL
dd if=fsbl.bin of=$PART_FSBL bs=1024
echo "Copy done"


Running on the HiFive
---------------------

The needed driver, bins, etc are included in the base image.

If you need to add files or change them we suggest ``scp``ing them to
If you need to add files or change them we suggest ``scp`` ing them to
the board after boot.


Expand Down Expand Up @@ -148,4 +144,4 @@ Example
::

insmod keystone-driver.ko
./test.sh
./test
67 changes: 37 additions & 30 deletions docs/source/Getting-Started/Running-Keystone-with-QEMU.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Running Keystone with QEMU
The latest QEMU supports RISC-V ISA.

Keystone is tested in the latest RISC-V QEMU (`GitHub <https://github.com/riscv/riscv-qemu>`_).
The upstream QEMU might not work because it has a bug in the PMP module (`See GitHub issue <>`.
The upstream QEMU might not work because it has a bug in the PMP module (`See GitHub issue <https://github.com/keystone-enclave/keystone/issues/25>`_).
The fix will be upstreamed in the future.

Installing Dependencies
Expand All @@ -18,19 +18,14 @@ 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
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

.. note::

Some of the utilities also use ``expect`` so we recommend that you install that as well though it is not strictly necessary.
::
sudo apt install expect

Quick Setup
Setup
----------------------------

In this stage, you will (1) install RISC-V toolchain, and (2) checkout git submodules.
Expand All @@ -40,31 +35,48 @@ You can quickly setup everything by running ``./fast-setup.sh``

./fast-setup.sh

NOTE: the prebuilt toolchain in fast-setup is known to have problems
on Ubuntu 18.04 due to library versioning mismatches.
This will download pre-compiled RISC-V tools and extract it to
``riscv`` 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.

To keep environment variables, add export
PATH=$PATH:<path/to/keystone>/riscv/bin to your .bashrc. You can also
manually run ``source source.sh`` to set the environment variables.

This will download pre-compiled RISC-V tools and extract it to ``riscv`` directory.
Init and Sync Submodules
########################

If you did not use ``fast-setup`` after checkout of the relevant
branch (``dev``, ``master``, etc)::

If you want to compile RISC-V tools from source code, run ``./setup.sh`` instead.
git submodule update --init --recursive

To keep environment variables, add export PATH=$PATH:<path/to/keystone>/riscv/bin to your .bashrc. You can also manually run ``source source.sh`` to set the environment variables.
For additional inormation, see `git submodules <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_.


Compile Sources
-----------------------------

Build All
########################
#########

If you want to build all, simply run ``make``.
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 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`.


Expand Down Expand Up @@ -94,7 +106,7 @@ 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/
platform specific set of files for the security monitor (defined in ``riscv-pk/sm/platform/``)

Build Root-of-Trust Boot ROM
###############################
Expand All @@ -108,11 +120,8 @@ Build Root-of-Trust Boot ROM
Build Keystone Driver
##############################

::
cd linux-keystone-driver
make
cd ..
This is handled as part of the top-level make, see ``hifive.mk`` for
details.

Build Keystone SDK
#############################
Expand Down Expand Up @@ -173,8 +182,6 @@ Currently, Keystone is only compatible with a prototype runtime, ``eyrie-rt``, w

./test-runner.riscv <user elf> <runtime elf>

To run all tests, you could simply run

::
To run all tests::

./test
4 changes: 2 additions & 2 deletions docs/source/Getting-Started/index.rst
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
Getting Started
==================================

What is Keystone Enclave
What is Keystone?
-----------------------------------

Keystone Enclave is an open source secure enclave for RISC-V processors.
Keystone is an open-source TEE framework for RISC-V processors.

You can currently run Keystone on qemu, `FireSim <https://fires.im/>`_ (FPGA), or the SiFive `HiFive Unleashed <https://www.sifive.com/boards/hifive-unleashed>`_ board.

Expand Down
10 changes: 6 additions & 4 deletions docs/source/Keystone-Applications/Compiling-Applications.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@ Toolchain
---------

All compilation will need to be done using the riscv64- toolchain.
This is provided by the riscv-gnu-toolchain submodule, and must be built first.

Libraries
---------
Expand All @@ -23,6 +22,9 @@ Applications will want to link against the enclave app library ``libkeystone-app
Applications
------------

Eapps need to be linked in a specific way. As this may change, please
see the ``app.lds`` linker script in the sdk/tests directory to see
the most up to date linking requirements.
eapps may be a standard unmodified statically linked binary. This
requires most options for the `eyrie` runtime to be enabled.

Otherwise, eapps need to be linked in a specific way. As this may
change, please see the ``app.lds`` linker script in the sdk/tests
directory to see the most up to date linking requirements.
6 changes: 3 additions & 3 deletions docs/source/Keystone-Applications/Edge-Calls.rst
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ sizeof(unsigned long), 0, 0);`` It passes a pointer to the value, the
size of the argument, and any needed return buffer information. (None
in this case)

The runtime then allocates an ``edge_call_t`` structure in the shared
The runtime then allocates an ``edge_call`` structure in the shared
memory region, fills out the call type, copies the value into another
part of the shared memory, and sets up the offset to the argument
value. Note that edge calls do not use pointers, but instead offset
Expand All @@ -54,7 +54,7 @@ The Keystone kernel driver resumes execution, checks the exit status
of the enclave, notes a pending ocall, and passes execution to the
userspace host process.

The userspace host process consumes the ``edge_call_t`` and dispatches
The userspace host process consumes the ``edge_call`` and dispatches
the registered ocall handler wrapper for ``OCALL_PRINT_VALUE``. The
wrapper generates a pointer to the argument value from the offset in
the shared memory region, and calls ``print_value`` with the value as
Expand All @@ -64,7 +64,7 @@ an argument.

On return, the host wrapper checks if any return values need to be
copied into the shared memory region (none in this case.) Sets the
``edge_call_t`` return status to SUCCESS, and returns into the
``edge_call`` return status to SUCCESS, and returns into the
driver.

The driver re-enters the enclave runtime via an ``SBI_CALL``.
Expand Down
14 changes: 5 additions & 9 deletions docs/source/Keystone-Applications/SDK-Basics.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ SDK Overview
============

.. attention::

Keystone SDK is work in progress, so programming enclaves requires a lot of manual efforts.
However, it still provides enough libraries to run simple enclaves such as :doc:`Keystone Demo <../Keystone-Demo/Demo-Basics>`.

Expand All @@ -26,7 +26,7 @@ applications via the `Keystone` class. Most of this library will work
regardless of the runtime, but is tied directly to the kernel driver
provided in the `riscv-linux` repository branches.

EApp Libraries
eapp Libraries
--------------

The eapp libraries provide both simple enclave tools (EXIT, etc) as
Expand Down Expand Up @@ -82,7 +82,8 @@ the host library. To start an enclave application, first create one::
Keystone enclave;
Params params;

params.setEnclaveEntry(ENTRY_VADDR);
[... Optional params settings ...]

enclave.init(PATH_TO_EAPP_ELF, PATH_TO_RUNTIME, params);

edge_init(&enclave);
Expand All @@ -105,12 +106,7 @@ when the enclave exits, or when an edgecall is made.
Writing an eapp
---------------

An enclave application has a main equivalent::

void EAPP_ENTRY eapp_entry(){}

This is the entry point that the runtime will start at in the enclave
application.
A generic RISC-V statically compiled ELF binary will run.

As with the host, the first action should be::

Expand Down

0 comments on commit a31c8ef

Please sign in to comment.