hermit/
lib.rs

1//! The Hermit kernel.
2//!
3//! This _library operating system_ (libOS) compiles to a static library
4//! (libhermit.a) that applications can link against to create a _Unikernel_.
5//!
6//! The API documented here does not matter to such an application.
7//! Such an application would use it's languages standard library which
8//! internally calls this kernel's system call functions ([`syscalls`]).
9//!
10//! # Using Hermit
11//!
12//! To run a Rust application with Hermit, see [hermit-rs].
13//!
14//! To run a C or C++ application with Hermit, see [hermit-c].
15//!
16//! # Building the kernel manually
17//!
18//! You can build the kernel with default features for x86-64 like this:
19//!
20//! ```sh
21//! cargo xtask build --arch x86_64
22//! ```
23//!
24//! For more information, run:
25//!
26//! ```
27//! cargo xtask build --help
28//! ```
29//!
30//! # Using an initramfs with Hermit
31//!
32//! When the `initramfs` feature is enabled, Hermit supports loading an initramfs,
33//! which is expected to be an uncompressed [tar file in UStar format](https://en.wikipedia.org/wiki/Tar_(computing)#UStar_format).
34//! It is expected to contain a `hermit.toml` file in the archive root,
35//! conforming to the format of [`hermit_entry::config::Config`](https://docs.rs/hermit-entry/latest/hermit_entry/config/enum.Config.html).
36//!
37//! When using [Uhyve], this file should be furthermore compressed using `gzip`,
38//! and passed instead of the kernel.
39//!
40//! The tar file can be created using a command line like:
41//! ```shell
42//! tar -czv -H ustar f some-image.hermit.gz hermit.toml $inputs
43//! ```
44//!
45//! # Features
46//!
47#![cfg_attr(
48	not(feature = "document-features"),
49	doc = "Activate the `document-features` Cargo feature to see feature docs here."
50)]
51#![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
52//!
53//! # Compile-time environment variables
54//!
55//! Compile-time environment variables are read from the build environment.
56//!
57//! - **`HERMIT_CAREFUL`** — Compiles the kernel with [`cargo careful`].
58//!
59//! [`cargo careful`]: https://github.com/RalfJung/cargo-careful
60//!
61//! # Run-time environment variables
62//!
63//! Run-time environment variables can be set via `env=KEY=VALUE` kernel args.
64//!
65//! ## Network environment variables
66//!
67//! - **`HERMIT_MTU`** — Sets the *maximum transmission unit* (MTU). Defaults to `1500`.
68//! - **`HERMIT_MRG_RXBUF_SIZE`** — Sets the receive buffer size. Useful for testing receive buffer merging of virtio-net devices when the feature `VIRTIO_NET_F_MRG_RXBUF` is negotiated. Defaults to unset.
69//! - **`HERMIT_PCAP_PATH`** — Sets the packet capture file path. Defaults to `/root/`. See the `write-pcap-file` feature for details.
70//!
71//! IP address, gateway and DNS are configured via the `ip=` command-line parameter for the kernel and do not have a default value:
72//!
73//! - `ip=none` or `ip=off` do not configure a network interface.
74//! - `ip=dhcp` uses DHCPv4 for configuring the network interface.
75//! - `ip=10.0.5.3/24:10.0.5.1::::1.1.1.1:1.0.0.1` would configure the static IP address `10.0.5.3`, set the gateway as `10.0.5.1` and configure two DNS servers.
76//!
77//! ## Output environment variables
78//!
79//! - **`NO_COLOR`** — Prevents the addition of ANSI colors to the kernel output. Defaults to unset. For details, see [`NO_COLOR`].
80//! - **`HERMIT_LOG_LEVEL_FILTER`** — Sets the lowest log level to print. Defaults to `info`.
81//!
82//! [`NO_COLOR`]: https://no-color.org/
83//!
84//! ## Deprecated environment variables
85//!
86//! - **`UHYVE_MOUNT`** — Sets the Uhyve mount point. Defaults to `/root`. Nowadays Uhyve supplies this to the kernel.
87//!
88//! [hermit-rs]: https://github.com/hermit-os/hermit-rs
89//! [hermit-c]: https://github.com/hermit-os/hermit-c
90//! [Uhyve]: https://github.com/hermit-os/uhyve
91
92#![allow(clippy::missing_safety_doc)]
93#![cfg_attr(
94	any(target_arch = "aarch64", target_arch = "riscv64"),
95	allow(incomplete_features)
96)]
97#![cfg_attr(target_arch = "x86_64", feature(abi_x86_interrupt))]
98#![cfg_attr(any(feature = "virtio", feature = "rtl8139"), feature(allocator_ext))]
99#![cfg_attr(docsrs, feature(doc_cfg))]
100#![cfg_attr(not(any(feature = "common-os", feature = "nostd")), feature(linkage))]
101#![feature(linked_list_cursors)]
102#![cfg_attr(
103	any(target_arch = "aarch64", target_arch = "riscv64"),
104	feature(specialization)
105)]
106#![cfg_attr(
107	not(any(feature = "common-os", feature = "nostd")),
108	feature(thread_local)
109)]
110#![cfg_attr(target_os = "none", no_std)]
111#![cfg_attr(target_os = "none", feature(custom_test_frameworks))]
112#![cfg_attr(all(target_os = "none", test), test_runner(crate::rt::test_runner))]
113#![cfg_attr(
114	all(target_os = "none", test),
115	reexport_test_harness_main = "test_main"
116)]
117#![cfg_attr(all(target_os = "none", test), no_main)]
118// FIXME: move this to `Cargo.toml` once stable
119#![feature(strict_provenance_lints)]
120#![warn(implicit_provenance_casts)]
121
122// EXTERNAL CRATES
123#[macro_use]
124extern crate alloc;
125#[macro_use]
126extern crate bitflags;
127#[macro_use]
128extern crate log;
129#[cfg(not(target_os = "none"))]
130#[macro_use]
131extern crate std;
132
133#[macro_use]
134mod macros;
135
136#[macro_use]
137mod logging;
138
139#[cfg(feature = "acpi")]
140mod acpi;
141pub mod arch;
142#[cfg(all(feature = "common-os", target_arch = "x86_64"))]
143pub mod common_os;
144pub mod config;
145pub mod console;
146mod drivers;
147mod entropy;
148mod env;
149pub mod errno;
150mod executor;
151pub mod fd;
152pub mod fs;
153mod init_buf;
154mod init_cell;
155pub mod io;
156pub mod mm;
157#[cfg(target_os = "none")]
158pub mod rt;
159pub mod scheduler;
160#[cfg(feature = "shell")]
161mod shell;
162mod synch;
163pub mod syscalls;
164pub mod time;
165#[cfg(feature = "uhyve")]
166mod uhyve;
hermit/lib.rs

hermit/
lib.rs
