From a31c8efa7eb9b90913476ffcadc0c3740e779d20 Mon Sep 17 00:00:00 2001 From: dkohlbre Date: Wed, 8 May 2019 13:12:03 -0700 Subject: [PATCH] =?UTF-8?q?Updated=20documentation=20based=20on=20recent?= =?UTF-8?q?=20changes,=20mostly=20removing=20statem=E2=80=A6=20(#92)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 --- README.md | 5 ++ .../Getting-Started/Guide-to-Components.rst | 2 + docs/source/Getting-Started/How-to-Debug.md | 35 ++++------ .../Running-Keystone-on-Hardware.rst | 28 ++++---- .../Running-Keystone-with-QEMU.rst | 67 ++++++++++--------- docs/source/Getting-Started/index.rst | 4 +- .../Compiling-Applications.rst | 10 +-- .../Keystone-Applications/Edge-Calls.rst | 6 +- .../Keystone-Applications/SDK-Basics.rst | 14 ++-- 9 files changed, 86 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index 2eced2537..cd07e91f0 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/source/Getting-Started/Guide-to-Components.rst b/docs/source/Getting-Started/Guide-to-Components.rst index 17d5155d6..8a41f7048 100644 --- a/docs/source/Getting-Started/Guide-to-Components.rst +++ b/docs/source/Getting-Started/Guide-to-Components.rst @@ -28,6 +28,8 @@ riscv-gnu-toolchain Unmodified toolchain for building riscv targets. Required to build all other components. +Prebuilt toolchains are available `here `. + linux-keystone-driver --------------------- diff --git a/docs/source/Getting-Started/How-to-Debug.md b/docs/source/Getting-Started/How-to-Debug.md index 69012713e..067abcd59 100644 --- a/docs/source/Getting-Started/How-to-Debug.md +++ b/docs/source/Getting-Started/How-to-Debug.md @@ -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 @@ -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: ``` @@ -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! diff --git a/docs/source/Getting-Started/Running-Keystone-on-Hardware.rst b/docs/source/Getting-Started/Running-Keystone-on-Hardware.rst index 862759a30..c8fbe227e 100644 --- a/docs/source/Getting-Started/Running-Keystone-on-Hardware.rst +++ b/docs/source/Getting-Started/Running-Keystone-on-Hardware.rst @@ -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 --------------------- @@ -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 @@ -90,18 +88,16 @@ 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 @@ -109,7 +105,7 @@ 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. @@ -148,4 +144,4 @@ Example :: insmod keystone-driver.ko - ./test.sh + ./test diff --git a/docs/source/Getting-Started/Running-Keystone-with-QEMU.rst b/docs/source/Getting-Started/Running-Keystone-with-QEMU.rst index 1e76cf221..f759001c3 100644 --- a/docs/source/Getting-Started/Running-Keystone-with-QEMU.rst +++ b/docs/source/Getting-Started/Running-Keystone-with-QEMU.rst @@ -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 `_). -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 `_). The fix will be upstreamed in the future. Installing Dependencies @@ -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. @@ -40,23 +35,36 @@ 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:/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:/riscv/bin to your .bashrc. You can also manually run ``source source.sh`` to set the environment variables. +For additional inormation, see `git 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. @@ -64,7 +72,11 @@ If you want to build all, simply run ``make``. 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`. @@ -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 ############################### @@ -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 ############################# @@ -173,8 +182,6 @@ Currently, Keystone is only compatible with a prototype runtime, ``eyrie-rt``, w ./test-runner.riscv -To run all tests, you could simply run - -:: +To run all tests:: ./test diff --git a/docs/source/Getting-Started/index.rst b/docs/source/Getting-Started/index.rst index 39a47af19..39b36f43f 100644 --- a/docs/source/Getting-Started/index.rst +++ b/docs/source/Getting-Started/index.rst @@ -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 `_ (FPGA), or the SiFive `HiFive Unleashed `_ board. diff --git a/docs/source/Keystone-Applications/Compiling-Applications.rst b/docs/source/Keystone-Applications/Compiling-Applications.rst index f175adcd8..662a15b07 100644 --- a/docs/source/Keystone-Applications/Compiling-Applications.rst +++ b/docs/source/Keystone-Applications/Compiling-Applications.rst @@ -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 --------- @@ -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. diff --git a/docs/source/Keystone-Applications/Edge-Calls.rst b/docs/source/Keystone-Applications/Edge-Calls.rst index 57a4874ea..6834adfd7 100644 --- a/docs/source/Keystone-Applications/Edge-Calls.rst +++ b/docs/source/Keystone-Applications/Edge-Calls.rst @@ -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 @@ -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 @@ -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``. diff --git a/docs/source/Keystone-Applications/SDK-Basics.rst b/docs/source/Keystone-Applications/SDK-Basics.rst index 540b10d40..c298b2049 100644 --- a/docs/source/Keystone-Applications/SDK-Basics.rst +++ b/docs/source/Keystone-Applications/SDK-Basics.rst @@ -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>`. @@ -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 @@ -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); @@ -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::