add some uffd documentation and metadata, panickify a couple errors

Leaving the question of errors in the handler alone for this commit, since that'll be a more major
change.

Author: acfoltzer

lucet-runtime/Cargo.toml

@@ -49,7 +49,9 @@ assets = [
 ]
 
 [features]
-default = []
-
-concurrent_testpoints = []
+default-features = []
 uffd = ["lucet-runtime-internals/uffd"]
+concurrent_testpoints = []
+
+[package.metadata.docs.rs]
+features = ["uffd"]

lucet-runtime/lucet-runtime-internals/Cargo.toml

@@ -37,7 +37,10 @@ byteorder = "1.2"
 cc = "1.0"
 
 [features]
-default = []
+default-features = []
 
-concurrent_testpoints = []
 uffd = ["userfaultfd"]
+concurrent_testpoints = []
+
+[package.metadata.docs.rs]
+features = ["uffd"]

lucet-runtime/lucet-runtime-internals/src/region/uffd.rs

@@ -1,7 +1,3 @@
-//! Region backend for `lucet-runtime` backed by
-//! [`userfaultfd(2)`](http://man7.org/linux/man-pages/man2/userfaultfd.2.html) via the
-//! `userfaultfd-rs` crate.
-
 use crate::alloc::{host_page_size, instance_heap_offset, AddrLocation, Alloc, Limits, Slot};
 use crate::embed_ctx::CtxMap;
 use crate::error::Error;
@@ -18,32 +14,32 @@ use std::sync::{Arc, Mutex, Weak};
 use std::thread::{self, JoinHandle};
 use userfaultfd::{IoctlFlags, Uffd, UffdBuilder};
 
-/// A [`Region`](../trait.Region.html) backed by `mmap` and managed by `userfaultfd`.
+/// A [`Region`](trait.Region.html) backed by `mmap` and managed by `userfaultfd`.
 ///
-/// Much like [`MmapRegion`](../mmap/struct.MmapRegion.html) `UffdRegion` lays out virtual memory
-/// in a contiguous block. See [`MmapRegion`](../mmap/struct.MmapRegion.html) for details of the
-/// memory layout.
+/// Much like [`MmapRegion`](struct.MmapRegion.html) `UffdRegion` lays out virtual memory in a
+/// contiguous block. See [`MmapRegion`](struct.MmapRegion.html) for details of the memory layout.
 ///
-/// The difference is that `UffdRegion` is lazy. Only the minimum required physical memory is set
-/// up to back that virtual memory before an `Instance` begins running. The stack and the heap
-/// are both lazily allocated at runtime.
+/// The difference is that `UffdRegion` is lazy. Only the minimum required physical memory is set up
+/// to back that virtual memory before an `Instance` begins running. The stack and the heap are both
+/// lazily allocated at runtime.
 ///
-/// That lazy allocation is handled by the [`userfaultfd`](http://man7.org/linux/man-pages/man2/userfaultfd.2.html)
-/// system in recent Linux kernels. The entire Region is registered with `userfaultfd` handle.
-/// When page faults occur due to attempts by the `Guest` to access the lazy memory, the `Guest`
-/// thread is paused and a message is sent over the `userfaultfd` handle.
+/// That lazy allocation is handled by the [`userfaultfd`][userfaultfd] system, using extensions
+/// available in Linux version 4.11 or newer. The entire `Region` is registered with `userfaultfd`
+/// handle.  When page faults occur due to attempts by the guest to access the lazy memory, the
+/// guest thread is paused and a message is sent over the `userfaultfd` handle.
 ///
-/// That message is picked up a separate thread which has the job of handling page faults. How
-/// it is handled is dependent on where the page fault occurred. In the case where it occurs in
-/// the stack, we just zero out the page. In the case it occurs in the heap, it is handled
-/// differently depending on whether the page should contain data defined in the WebAssembly
-/// module. In the case it should be blank we again just zero it out. In the case that it should
-/// contain data, we copy the data into the page. In any case we finish by reawakening the `Guest`
-/// thread.
+/// That message is picked up a separate thread which has the job of handling page faults. How it is
+/// handled is dependent on where the page fault occurred. In the case where it occurs in the stack,
+/// we just zero out the page. In the case it occurs in the heap, it is handled differently
+/// depending on whether the page should contain data defined in the WebAssembly module. In the case
+/// it should be blank we again just zero it out. In the case that it should contain data, we copy
+/// the data into the page. In any case we finish by reawakening the guest thread.
 ///
 /// If the fault occurs in a guard page, we do nothing, and reawaken the thread without allocating
-/// the backing physical memory. This ends up causing the `Guest` thread to throw a SIGBUS. Which
-/// is caught and handled as normal.
+/// the backing physical memory. This ends up causing the guest thread to raise a SIGBUS, which is
+/// treated as a fatal error by the Lucet signal handler.
+///
+/// [userfaultfd]: http://man7.org/linux/man-pages/man2/userfaultfd.2.html
 pub struct UffdRegion {
     uffd: Arc<Uffd>,
     start: *mut c_void,
@@ -380,7 +376,7 @@ impl UffdRegion {
     /// Create a new `UffdRegion` that can support a given number of instances, each subject to the
     /// same runtime limits.
     ///
-    /// The region is turned in an `Arc`, because any instances created from it carry a reference
+    /// The region is returned in an `Arc`, because any instances created from it carry a reference
     /// back to the region.
     ///
     /// This also creates and starts a separate thread that is responsible for handling page faults
@@ -406,7 +402,7 @@ impl UffdRegion {
             if let Some(sz) = instance_capacity.checked_mul(limits.total_memory_size()) {
                 sz
             } else {
-                lucet_bail!("region size overflowed");
+                return Err(Error::InvalidArgument("requested region size too large"));
             };
         let start = unsafe {
             mmap(
@@ -424,7 +420,7 @@ impl UffdRegion {
             .register(start, total_region_size)
             .map_err(|e| Error::InternalError(e.into()))?;
         if !ioctls.contains(IoctlFlags::WAKE | IoctlFlags::COPY | IoctlFlags::ZEROPAGE) {
-            lucet_bail!("required uffd ioctls not supported; found: {:?}", ioctls);
+            panic!("required uffd ioctls not supported; found: {:?}", ioctls);
         }
 
         let (handler_pipe_recv, handler_pipe) = nix::unistd::pipe()?;
@@ -464,7 +460,7 @@ impl UffdRegion {
                 }
                 res
             })
-            .map_err(|e| lucet_format_err!("error spawning uffd region handler: {}", e))?;
+            .expect("error spawning uffd region handler");
 
         let region = Arc::new(UffdRegion {
             uffd,

lucet-runtime/src/lib.rs

@@ -23,7 +23,10 @@
 //! [`InstanceHandle`](struct.InstanceHandle.html) smart pointer.
 //!
 //! - [`Region`](trait.Region.html): the memory from which instances are created. This crate
-//! includes [`MmapRegion`](struct.MmapRegion.html), an implementation backed by `mmap`.
+//! includes [`MmapRegion`](struct.MmapRegion.html), an implementation backed by `mmap`, and
+//! optionally [`UffdRegion`](struct.UffdRegion.html), which is backed by the
+//! [`userfaultfd`](http://man7.org/linux/man-pages/man2/userfaultfd.2.html) feature available on
+//! newer Linux kernels ([see below](index.html#userfaultfd-backed-region)).
 //!
 //! - [`Limits`](struct.Limits.html): upper bounds for the resources a Lucet instance may
 //! consume. These may be larger or smaller than the limits described in the WebAssembly module
@@ -374,6 +377,16 @@
 //! this number could change between Lucet releases or even Rust compiler versions.
 //!
 //! [default-sigstack-size]: constant.DEFAULT_SIGNAL_STACK_SIZE.html
+//!
+//! ## `userfaultfd`-Backed Region
+//!
+//! [`UffdRegion`](struct.UffdRegion.html) is a [`Region`](trait.Region.html) backed by the
+//! [`userfaultfd`](http://man7.org/linux/man-pages/man2/userfaultfd.2.html) feature available in
+//! newer Linux kernels. It allows Lucet instances to lazily copy in the initial heap contents of an
+//! `Instance`, reducing startup time. Instance stack pages can also be lazily initialized, reducing
+//! the memory footprint of instances that only use a small portion of their available stack space.
+//!
+//! To use `UffdRegion`, enable the `uffd` Cargo feature, which is off by default.
 
 #![deny(bare_trait_objects)]