diff --git a/nvx-rs/Cargo.toml b/nvx-rs/Cargo.toml index 81ba16a47..d0f009ec0 100644 --- a/nvx-rs/Cargo.toml +++ b/nvx-rs/Cargo.toml @@ -39,10 +39,10 @@ host = [ # `Artifacts::bundled`. The build script downloads the release pinned in `artifacts.json`, or # copies the release directory named by `NVX_BUNDLE_DIR`. bundled = ["host", "dep:sha2"] -# Test doubles: the fake OpenVMM of `testing::fake_openvmm` and its `nvx-fake-openvmm` binary. +# NVX's own `nvx-fake-openvmm` binary, a fake OpenVMM for tests. It adds no API. testing = ["dep:getrandom", "dep:serde", "dep:serde_json", "dep:nix", "dep:windows-sys"] -# The `nvx-rs` command-line interface of `host::cli` and its `nvx-rs` binary, which runs NVX's -# microVMs and sandboxes, compiles egress policies, looks up artifacts, and downloads releases. +# NVX's own `nvx-rs` binary, the command-line interface that runs NVX's microVMs and sandboxes, +# compiles egress policies, looks up artifacts, and downloads releases. It adds no API. cli = ["host"] # The serde form of `Hypervisor`. The `host` feature enables it. serde = ["dep:serde"] diff --git a/nvx-rs/README.md b/nvx-rs/README.md index b774b43e4..c0212d428 100644 --- a/nvx-rs/README.md +++ b/nvx-rs/README.md @@ -131,8 +131,6 @@ changes only when the module's purpose does. | [`nvx::host::seal`](#nvxhostseal) | `FileSeal`: what the host reports about an open file from its metadata alone, without reading it | | [`nvx::host::session`, `platform`, `report`](#nvxhostsession-platform-report) | The authenticated control session, Linux and Windows primitives, and OpenVMM's outcome report | | [`nvx::host::sandbox`](#nvxhostsandbox) | The launch profile of `nvx-rs sandbox`: its plans, live shares, option checks, bindings, and prepared launches | -| [`nvx::testing::fake_openvmm`](#nvxtestingfake_openvmm) | A fake OpenVMM that serves the control console and runs scripted workloads without a VM | -| [`nvx::host::cli`](#nvxhostcli) | Feature `cli`: the `nvx-rs` executable; see [The nvx-rs CLI](#the-nvx-rs-cli) | | [`nvx::guest`](#nvxguest) | The programs that run in Linux guests; see [Guest binaries](#guest-binaries) | | [`nvx::guest::mappings`](#nvxguestmappings) | `Mapper` and `MappingTable`: apply host mappings beneath the descriptors of their roots, and a host's mapping table, for any guest init or agent | | [`nvx::guest::nvxs`](#nvxguestnvxs) | `GuestConnection`: the guest's role of the NVXS session over a byte stream, such as the control console | @@ -1068,17 +1066,6 @@ arguments of the launch: the plan's, those that export the adapter's shares, and those of the launch's `VmmLaunch`, and refuses a command line that Windows would not start OpenVMM with. -### `nvx::testing::fake_openvmm` - -A fake OpenVMM that serves the control console and runs scripted workloads -without a VM, for direct launches and for the managed and one-shot sandboxes of -`nvx-rs sandbox`, and runs the VMs of templates' captures, which publish a -snapshot, or fail, as a scenario asks. - -### `nvx::host::cli` - -Feature `cli`: the `nvx-rs` executable; see [The nvx-rs CLI](#the-nvx-rs-cli). - ### `nvx::guest` The programs that run in Linux guests; see [Guest binaries](#guest-binaries). @@ -2356,7 +2343,7 @@ that its snapshot saved, a cold boot with `--network-profile` alone or with explicit `--host-loopback allow` without `--restore-network-policy`. Kernel command-line tokens make it fail: `fake_exit_on_start=STATUS`, `fake_exit_status=STATUS`, `fake_guest_features=MASK`, and -`fake_legacy_guest=1`, among others; see `nvx::testing::fake_openvmm`. Like +`fake_legacy_guest=1`, among others; see `src/testing/fake_openvmm.rs`. Like OpenVMM, it opens the sandbox's block devices at the paths that its options name and holds them until it exits, after `fake_block_delay_ms=MS` if asked, and records what each held in `fake-openvmm-TOKEN-blocks.json` next to the @@ -2421,8 +2408,8 @@ caller owner. | --- | --- | | `host` (default) | The `host` module. It enables `serde`, and `sha2`, which names the children of a sandbox's aggregate share and hashes distro layers in their explicit verification | | `bundled` | Stages a release at build time; see [Bundled artifacts](#bundled-artifacts) | -| `testing` | The fake OpenVMM and the `nvx-fake-openvmm` binary | -| `cli` | The `nvx-rs` CLI of `host::cli` and its `nvx-rs` binary; it enables `host`. See [The nvx-rs CLI](#the-nvx-rs-cli) | +| `testing` | NVX's own `nvx-fake-openvmm` binary, a fake OpenVMM for tests; see [Test hooks](#test-hooks). It adds no API | +| `cli` | NVX's own `nvx-rs` binary; it adds no API, and enables `host`. See [The nvx-rs CLI](#the-nvx-rs-cli) | | `serde` | The serde form of `Hypervisor` | | `guest` | The `guest` module and the guest binaries; see [Guest binaries](#guest-binaries) | diff --git a/nvx-rs/public-api/linux.txt b/nvx-rs/public-api/linux.txt index 161dbb90d..f31eb61a3 100644 --- a/nvx-rs/public-api/linux.txt +++ b/nvx-rs/public-api/linux.txt @@ -833,10 +833,10 @@ field nvx::guest::clone::RootTemplate::scratch field nvx::guest::clone::RootTemplate::timeout fn nvx::guest::clone::apply fn nvx::guest::clone::repair -mod nvx::guest::console_pending -fn nvx::guest::console_pending::main -mod nvx::guest::device_io -fn nvx::guest::device_io::main +mod nvx::guest::console_pending (hidden) +fn nvx::guest::console_pending::main (hidden) +mod nvx::guest::device_io (hidden) +fn nvx::guest::device_io::main (hidden) mod nvx::guest::entry struct nvx::guest::entry::Account method nvx::guest::entry::Account::home @@ -1060,8 +1060,8 @@ variant nvx::guest::exec::binding::Event::Message field nvx::guest::exec::binding::Event::Message::0 variant nvx::guest::exec::binding::Event::SettlementFailed field nvx::guest::exec::binding::Event::SettlementFailed::0 -mod nvx::guest::exit -fn nvx::guest::exit::main +mod nvx::guest::exit (hidden) +fn nvx::guest::exit::main (hidden) mod nvx::guest::gpt enum nvx::guest::gpt::DeviceError variant nvx::guest::gpt::DeviceError::LogicalBlockSize @@ -1089,9 +1089,9 @@ variant nvx::guest::ingress::StartError::Socket field nvx::guest::ingress::StartError::Socket::0 variant nvx::guest::ingress::StartError::Spawn field nvx::guest::ingress::StartError::Spawn::0 -fn nvx::guest::ingress::main -mod nvx::guest::managed_agent -fn nvx::guest::managed_agent::main +fn nvx::guest::ingress::main (hidden) +mod nvx::guest::managed_agent (hidden) +fn nvx::guest::managed_agent::main (hidden) mod nvx::guest::mappings enum nvx::guest::mappings::Access variant nvx::guest::mappings::Access::ReadOnly @@ -1197,8 +1197,8 @@ struct nvx::guest::mappings::UnmountFailure method nvx::guest::mappings::UnmountFailure::error method nvx::guest::mappings::UnmountFailure::target fn nvx::guest::mappings::bind -mod nvx::guest::mmio_write -fn nvx::guest::mmio_write::main +mod nvx::guest::mmio_write (hidden) +fn nvx::guest::mmio_write::main (hidden) mod nvx::guest::nvxs struct nvx::guest::nvxs::GuestConnection method nvx::guest::nvxs::GuestConnection::acknowledge @@ -1245,7 +1245,7 @@ const nvx::guest::reseed::Seed::LENGTH method nvx::guest::reseed::Seed::from_bytes method nvx::guest::reseed::Seed::generation_id method nvx::guest::reseed::Seed::read -fn nvx::guest::reseed::main +fn nvx::guest::reseed::main (hidden) fn nvx::guest::reseed::reseed mod nvx::guest::root struct nvx::guest::root::Assembly @@ -1595,9 +1595,9 @@ struct nvx::guest::time::Violation method nvx::guest::time::Violation::code method nvx::guest::time::Violation::detail method nvx::guest::time::Violation::status -fn nvx::guest::time::main -mod nvx::guest::time_probe -fn nvx::guest::time_probe::main +fn nvx::guest::time::main (hidden) +mod nvx::guest::time_probe (hidden) +fn nvx::guest::time_probe::main (hidden) fn nvx::guest_path mod nvx::host mod nvx::host::artifacts @@ -1678,8 +1678,8 @@ const nvx::host::artifacts::PACKAGE_MANIFEST_SUFFIX fn nvx::host::artifacts::absolute fn nvx::host::artifacts::check_manifest fn nvx::host::artifacts::openvmm_executable -mod nvx::host::cli -fn nvx::host::cli::main +mod nvx::host::cli (hidden) +fn nvx::host::cli::main (hidden) mod nvx::host::filesystem struct nvx::host::filesystem::Bind field nvx::host::filesystem::Bind::child @@ -3411,9 +3411,9 @@ const nvx::protocol::status::TIME_STATUSES const nvx::protocol::status::TIME_VIOLATION fn nvx::protocol::status::describe fn nvx::resolve_guest_path -mod nvx::testing -mod nvx::testing::fake_openvmm -fn nvx::testing::fake_openvmm::main +mod nvx::testing (hidden) +mod nvx::testing::fake_openvmm (hidden) +fn nvx::testing::fake_openvmm::main (hidden) mod nvx::uuid struct nvx::uuid::ParseUuidError struct nvx::uuid::Uuid diff --git a/nvx-rs/public-api/windows.txt b/nvx-rs/public-api/windows.txt index 6535e67a1..74cd7f31e 100644 --- a/nvx-rs/public-api/windows.txt +++ b/nvx-rs/public-api/windows.txt @@ -669,8 +669,8 @@ const nvx::host::artifacts::PACKAGE_MANIFEST_SUFFIX fn nvx::host::artifacts::absolute fn nvx::host::artifacts::check_manifest fn nvx::host::artifacts::openvmm_executable -mod nvx::host::cli -fn nvx::host::cli::main +mod nvx::host::cli (hidden) +fn nvx::host::cli::main (hidden) mod nvx::host::filesystem struct nvx::host::filesystem::Bind field nvx::host::filesystem::Bind::child @@ -2401,9 +2401,9 @@ const nvx::protocol::status::TIME_STATUSES const nvx::protocol::status::TIME_VIOLATION fn nvx::protocol::status::describe fn nvx::resolve_guest_path -mod nvx::testing -mod nvx::testing::fake_openvmm -fn nvx::testing::fake_openvmm::main +mod nvx::testing (hidden) +mod nvx::testing::fake_openvmm (hidden) +fn nvx::testing::fake_openvmm::main (hidden) mod nvx::uuid struct nvx::uuid::ParseUuidError struct nvx::uuid::Uuid diff --git a/nvx-rs/src/guest/ingress/mod.rs b/nvx-rs/src/guest/ingress/mod.rs index 2a3fe4bd3..c91de1433 100644 --- a/nvx-rs/src/guest/ingress/mod.rs +++ b/nvx-rs/src/guest/ingress/mod.rs @@ -205,6 +205,7 @@ struct UdpSocket { /// and exits with 1 when it cannot open or bind its socket, or take the one that it inherited, or /// with 2 for a usage error. `start` exits with 0 once the announcer runs, or with 1 when it does /// not start. +#[doc(hidden)] pub fn main() -> ExitCode { run_main(|args| run(args, &mut sys::Stdout::new(), &mut io::stderr())) } diff --git a/nvx-rs/src/guest/mod.rs b/nvx-rs/src/guest/mod.rs index 48710b3be..e0cdc0f50 100644 --- a/nvx-rs/src/guest/mod.rs +++ b/nvx-rs/src/guest/mod.rs @@ -94,18 +94,23 @@ pub use generation::GenerationId; pub mod cgroup; #[cfg(target_arch = "x86_64")] pub mod clone; +#[doc(hidden)] pub mod console_pending; #[cfg(target_arch = "x86_64")] +#[doc(hidden)] pub mod device_io; pub mod entry; pub mod exec; #[cfg(target_arch = "x86_64")] +#[doc(hidden)] pub mod exit; pub mod gpt; pub mod ingress; +#[doc(hidden)] pub mod managed_agent; pub mod mappings; #[cfg(target_arch = "x86_64")] +#[doc(hidden)] pub mod mmio_write; pub mod nvxs; pub mod process; @@ -116,4 +121,5 @@ pub mod terminal; #[cfg(target_arch = "x86_64")] pub mod time; #[cfg(target_arch = "x86_64")] +#[doc(hidden)] pub mod time_probe; diff --git a/nvx-rs/src/guest/reseed.rs b/nvx-rs/src/guest/reseed.rs index 4706f6ead..bc88d2d97 100644 --- a/nvx-rs/src/guest/reseed.rs +++ b/nvx-rs/src/guest/reseed.rs @@ -254,6 +254,7 @@ fn reseed_through(random: &CStr, seed: &Seed) -> Result<(), ReseedError> { /// Runs `nvx-reseed` with the process's arguments. It exits with 0, 1 when an operation or a /// check fails, or 2 for a usage error. +#[doc(hidden)] pub fn main() -> ExitCode { run_main(|args| { run( diff --git a/nvx-rs/src/guest/time/mod.rs b/nvx-rs/src/guest/time/mod.rs index f00d34a73..6929810f6 100644 --- a/nvx-rs/src/guest/time/mod.rs +++ b/nvx-rs/src/guest/time/mod.rs @@ -149,6 +149,7 @@ const USAGE: &[u8] = br#"usage: nvx-time [--report-only] COMMAND /// Runs `nvx-time` with the process's arguments. It exits with 0 on success, 1 when a command /// or a check fails, or 2 for an invalid command line. +#[doc(hidden)] pub fn main() -> ExitCode { run_main(|args| run(args, &mut sys::Stdout::new(), &mut io::stderr())) } diff --git a/nvx-rs/src/host/mod.rs b/nvx-rs/src/host/mod.rs index 2ba935d71..0e4bc2254 100644 --- a/nvx-rs/src/host/mod.rs +++ b/nvx-rs/src/host/mod.rs @@ -62,6 +62,7 @@ pub mod artifacts; #[cfg(feature = "cli")] +#[doc(hidden)] pub mod cli; pub mod filesystem; pub mod instance; diff --git a/nvx-rs/src/lib.rs b/nvx-rs/src/lib.rs index 0b6f267b1..ba5d8ae25 100644 --- a/nvx-rs/src/lib.rs +++ b/nvx-rs/src/lib.rs @@ -36,8 +36,6 @@ //! platform primitives, the supervision of VM instances: starting, reattaching, executing //! workloads, and stopping, the store of a sandbox's runtime records and launch journal, and the //! manifests, compatibility keys, store, and leases of templates. -//! - `testing` (feature `testing`): a fake OpenVMM that serves the control console without -//! running a VM. //! - `guest` (feature `guest`, Linux): the programs that run in NVX guests, such as //! `nvx-console-pending`, the guest's NVXS connection, the libraries through which any guest //! init or agent opens the terminal on which it serves its session (`guest::terminal`), starts @@ -119,7 +117,10 @@ //! - `bundled`: stages the OpenVMM executable, guest kernel, and control initramfs at build time; //! see `Artifacts::bundled`. The build script downloads the release that `artifacts.json` pins, //! or copies the release directory that `NVX_BUNDLE_DIR` names. -//! - `testing`: the fake OpenVMM of `testing::fake_openvmm` and its `nvx-fake-openvmm` binary. +//! - `testing`: NVX's own `nvx-fake-openvmm` binary, a fake OpenVMM that serves the control +//! console without running a VM. It adds no API. +//! - `cli`: NVX's own `nvx-rs` binary, the command-line interface that runs NVX's microVMs and +//! sandboxes. It adds no API, and enables `host`. //! - `serde`: the serde form of [`Hypervisor`]. //! - `guest`: the `guest` module and the guest binaries, which the `guest` profile builds as //! static `x86_64-unknown-linux-musl` executables. @@ -139,6 +140,7 @@ pub mod guest; #[cfg(feature = "host")] pub mod host; #[cfg(feature = "testing")] +#[doc(hidden)] pub mod testing; #[cfg(test)] mod tests;