WIP: make this crate a library that includes a binary

src/backend/mod.rs

@@ -1,5 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 
+//! # Backend
+//! TODO: this is a placeholder for proper module documentation
+
 #[cfg(feature = "backend-kvm")]
 pub mod kvm;
 
@@ -15,6 +18,9 @@ use std::sync::Arc;
 use anyhow::Result;
 use sallyport::Block;
 
+/// The Backend trait is an abstraction over the various hardware TEE backends
+/// (Intel SGX, AMD SEV, and so on).
+/// TODO: explain better
 pub trait Backend {
     /// The name of the backend
     fn name(&self) -> &'static str;
@@ -34,6 +40,7 @@ pub trait Backend {
     fn build(&self, shim: Component, code: Component) -> Result<Arc<dyn Keep>>;
 }
 
+/// A single piece of data about the host's support for a given Backend.
 pub struct Datum {
     /// The name of this datum.
     pub name: String,
@@ -48,19 +55,35 @@ pub struct Datum {
     pub mesg: Option<String>,
 }
 
+/// The `Keep` trait gives an interface for spawning a Thread inside a Keep.
+/// (TODO: more docs...)
 pub trait Keep {
     /// Creates a new thread in the keep.
     fn spawn(self: Arc<Self>) -> Result<Option<Box<dyn Thread>>>;
 }
 
+/// The `Thread` trait enters the Thread in the Keep and then returns a Command,
+/// which indicates why the thread has paused/ceased execution and what we
+/// need to do about it. See Command for details.
+/// TODO: I made this up; someone should edit/approve it
+/// TODO: Link "Command" to the `Command` enum
 pub trait Thread {
     /// Enters the keep.
     fn enter(&mut self) -> Result<Command>;
 }
 
+/// The Command enum gives the reason we stopped execution of the Thread, and
+/// tells us what to do next - either we need to handle a Syscall or we can
+/// simply Continue on our way.
+/// TODO: uhhh I made that explanation up, someone should rewrite/verify this..
 pub enum Command<'a> {
+    /// This indicates that we need to handle a SysCall.
+    /// TODO: ...or does it mean we just handled one?
+    /// TODO: also, explain Block?
     #[allow(dead_code)]
     SysCall(&'a mut Block),
+
+    /// No need to handle a SysCall, we can just continue on our way
     #[allow(dead_code)]
     Continue,
 }

src/main.rs → src/bin/enarx-keepldr.rs

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 
-//! This crate provides the `enarx-keepldr` executable which loads `static-pie`
+//! This file provides the `enarx-keepldr` executable which loads `static-pie`
 //! binaries into an Enarx Keep - that is a hardware isolated environment using
 //! technologies such as Intel SGX or AMD SEV.
 //!
@@ -53,18 +53,10 @@
 //!     $ cargo build --features=backend-sgx,backend-kvm
 
 #![deny(clippy::all)]
-#![deny(missing_docs)]
 #![feature(asm)]
 
-mod backend;
-mod binary;
-mod protobuf;
-
-// workaround for sallyport tests, until we have internal crates
-pub use sallyport::Request;
-
-use backend::{Backend, Command};
-use binary::Component;
+use enarx_keepldr::backend::{Backend, Command};
+use enarx_keepldr::binary::Component;
 
 use anyhow::Result;
 use structopt::StructOpt;
@@ -96,9 +88,9 @@ enum Options {
 fn main() -> Result<()> {
     let backends: &[Box<dyn Backend>] = &[
         #[cfg(feature = "backend-sgx")]
-        Box::new(backend::sgx::Backend),
+        Box::new(enarx_keepldr::backend::sgx::Backend),
         #[cfg(feature = "backend-kvm")]
-        Box::new(backend::kvm::Backend),
+        Box::new(enarx_keepldr::backend::kvm::Backend),
     ];
 
     match Options::from_args() {

src/binary/mod.rs

@@ -1,5 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 
+//! # Binary
+//! TODO: fill in docs for this module
+
 mod component;
 
 pub use component::*;

src/lib.rs

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! This crate provides the `enarx-keepldr` library and binary which
+//! loads `static-pie` binaries into an Enarx Keep - that is a hardware
+//! isolated environment using technologies such as Intel SGX or AMD SEV.
+//!
+//! # Building
+//!
+//! Please see **BUILD.md** for instructions.
+//!
+//! # Run Tests
+//!
+//!     $ cargo test
+//!
+//! # Build and Run an Application
+//!
+//!     $ cat > test.c <<EOF
+//!     #include <stdio.h>
+//!
+//!     int main() {
+//!         printf("Hello World!\n");
+//!         return 0;
+//!     }
+//!     EOF
+//!
+//!     $ musl-gcc -static-pie -fPIC -o test test.c
+//!     $ target/debug/enarx-keepldr exec ./test
+//!     Hello World!
+//!
+//! # Select a Different Backend
+//!
+//! `enarx-keepldr exec` will probe the machine it is running on
+//! in an attempt to deduce an appropriate deployment backend unless
+//! that target is already specified in an environment variable
+//! called `ENARX_BACKEND`.
+//!
+//! To see what backends are supported on your system, run:
+//!
+//!     $ target/debug/enarx-keepldr info
+//!
+//! To manually select a backend, set the `ENARX_BACKEND` environment
+//! variable:
+//!
+//!     $ ENARX_BACKEND=sgx target/debug/enarx-keepldr exec ./test
+//!
+//! Note that some backends are conditionally compiled. They can all
+//! be compiled in like so:
+//!
+//!     $ cargo build --all-features
+//!
+//! Or specific backends can be compiled in:
+//!
+//!     $ cargo build --features=backend-sgx,backend-kvm
+
+#![deny(clippy::all)]
+#![feature(asm)]
+
+// FIXME: write docs and change this back to `deny`!
+#![allow(missing_docs)]
+
+pub mod backend;
+pub mod binary;
+pub mod protobuf;
+
+// workaround for sallyport tests, until we have internal crates
+pub use sallyport::Request;