Merge pull request #152 from keystone-enclave/docs-sm_rs

docs: Suggest building the Rust SM, and building with optimizations

CMakeLists.txt

@@ -70,12 +70,13 @@ set(tests_srcdir ${CMAKE_SOURCE_DIR}/tests)
 set(final_image ${CMAKE_BINARY_DIR}/bbl.bin)
 set(initramfs_sysroot ${CMAKE_BINARY_DIR}/initramfs-sysroot)
 
-set(USE_RUST_SM FALSE CACHE BOOL "Use Rust version of the security monitor. WARNING: Applies globally.")
+set(USE_RUST_SM FALSE CACHE BOOL "Use Rust version of the security monitor.")
 if (${USE_RUST_SM})
-  set(enabled_sm sm_rs)
+  set(enabled_sm --enable-sm_rs)
 else()
-  set(enabled_sm sm_c)
+  set(enabled_sm --enable-sm)
 endif()
+set(SM_CONFIGURE_ARGS --enable-opt=2 CACHE STRING "Security Monitor configure script arguments")
 
 # add patch macro
 macro(add_patch submodule patch working_directory depend_by)
@@ -183,9 +184,9 @@ add_custom_target("driver" ALL DEPENDS ${driver_srcdir} ${linux_srcdir} "linux"
 # bbl + sm
 add_custom_command(OUTPUT ${sm_wrkdir} COMMAND mkdir -p ${sm_wrkdir})
 add_custom_target("sm" ALL DEPENDS ${sm_srcdir} ${sm_wrkdir} ${linux_vmlinux_stripped} WORKING_DIRECTORY ${sm_wrkdir}
-  COMMAND ln -rsnf ${sm_srcdir}/${enabled_sm} ${sm_srcdir}/sm
   COMMAND ${sm_srcdir}/configure --host=riscv${BITS}-unknown-linux-gnu --with-payload=${linux_vmlinux_stripped}
-    --enable-logo --with-logo=${confdir}/sifive_logo.txt --enable-sm --enable-opt=2 --with-target-platform=${platform}
+    --enable-logo --with-logo=${confdir}/sifive_logo.txt --with-target-platform=${platform}
+    --enable-logo --with-logo=${confdir}/sifive_logo.txt ${enabled_sm} ${SM_CONFIGURE_ARGS} --with-target-platform=${platform}
   COMMAND env CFLAGS='${CFLAGS} -mabi=${ABI} -march=${ISA}' $(MAKE) -C ${sm_wrkdir}
   COMMENT "Building sm"
 )

docs/source/Building-Components/Security-Monitor-Platform-Build.rst

@@ -35,7 +35,11 @@ Configure and build ``bbl``. The SM can be built by additional flags ``--enable-
 
 	make
 
-This will generate the boot image ``bbl`` in the build directory. Use it to boot the machine.
+The Keystone Security Monitor also has an experimental port to the `Rust programming language <https://rust-lang.org>`_. If you would like to try this version of the SM, specify ``--enale-sm_rs`` instead of using ``--enable-sm``.
+
+You may also wish to compile the SM with optimizations enabled. To do this, use the configure flag ``--enable-opt=2``.
+
+Running ``make`` witll generate the boot image ``bbl`` in the build directory. Use it to boot the machine.
 
 Now, we will customize the SM for a FU540 chip on HiFive Unleashed board.
 Currently, we only have one experimental platform configuration for FU540.

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

@@ -20,3 +20,11 @@ Ubuntu
   You need Git version >= 2.11.0 to use ``./fast-setup.sh``, because the script uses
   ``--shallow-clone`` for faster submodule initializtion.
 
+In order to use the Rust version of the security monitor, you will also need to install `rustup <https://rustup.rs>_` and `llvm-9 <https://apt.llvm.org/>_` (available in Ubuntu repositories in versions 18.04 and above). Then, run the following commands:
+
+::
+  rustup toolchain install nightly
+  rustup +nightly component add rust-src
+  rustup +nightly target add riscv64gc-unknown-none-elf
+  cargo +nightly install cargo-xbuild
+

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

@@ -31,6 +31,8 @@ If you want to use ``initramfs``, use the following flag when running ``cmake``
 
   cmake .. -Dinitramfs=y
 
+If you want to use the Rust port of the Security Monitor, run ``cmake`` with ``-DUSE_RUST_SM=y``.
+
 Please refer to the following sections if you want to learn how to build each individual component.
 Otherwise, skip to :ref:`LaunchQEMU`.