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//! # Features
31//!
32#![cfg_attr(
33	not(feature = "document-features"),
34	doc = "Activate the `document-features` Cargo feature to see feature docs here."
35)]
36#![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
37//!
38//! # Compile-time environment variables
39//!
40//! Compile-time environment variables are read from the build environment.
41//!
42//! - **`HERMIT_CAREFUL`** — Compiles the kernel with [`cargo careful`].
43//!
44//! [`cargo careful`]: https://github.com/RalfJung/cargo-careful
45//!
46//! # Run-time environment variables
47//!
48//! Run-time environment variables can be set via `env=KEY=VALUE` kernel args.
49//!
50//! ## Network environment variables
51//!
52//! - **`HERMIT_MTU`** — Sets the *maximum transmission unit* (MTU). Defaults to `1500`.
53//! - **`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.
54//! - **`HERMIT_PCAP_PATH`** — Sets the packet capture file path. Defaults to `/root/`. See the `write-pcap-file` feature for details.
55//!
56//! IP address, gateway and DNS are configured via the `ip=` command-line parameter for the kernel and do not have a default value:
57//!
58//! - `ip=none` or `ip=off` do not configure a network interface.
59//! - `ip=dhcp` uses DHCPv4 for configuring the network interface.
60//! - `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.
61//!
62//! ## Output environment variables
63//!
64//! - **`NO_COLOR`** — Prevents the addition of ANSI colors to the kernel output. Defaults to unset. For details, see [`NO_COLOR`].
65//! - **`HERMIT_LOG_LEVEL_FILTER`** — Sets the lowest log level to print. Defaults to `info`.
66//!
67//! [`NO_COLOR`]: https://no-color.org/
68//!
69//! ## Deprecated environment variables
70//!
71//! - **`UHYVE_MOUNT`** — Sets the Uhyve mount point. Defaults to `/root`. Nowadays Uhyve supplies this to the kernel.
72//!
73//! [hermit-rs]: https://github.com/hermit-os/hermit-rs
74//! [hermit-c]: https://github.com/hermit-os/hermit-c
75
76#![allow(clippy::missing_safety_doc)]
77#![cfg_attr(
78	any(target_arch = "aarch64", target_arch = "riscv64"),
79	allow(incomplete_features)
80)]
81#![cfg_attr(target_arch = "x86_64", feature(abi_x86_interrupt))]
82#![feature(allocator_api)]
83#![cfg_attr(docsrs, feature(doc_cfg))]
84#![cfg_attr(not(any(feature = "common-os", feature = "nostd")), feature(linkage))]
85#![feature(linked_list_cursors)]
86#![cfg_attr(
87	any(target_arch = "aarch64", target_arch = "riscv64"),
88	feature(specialization)
89)]
90#![cfg_attr(
91	not(any(feature = "common-os", feature = "nostd")),
92	feature(thread_local)
93)]
94#![cfg_attr(target_os = "none", no_std)]
95#![cfg_attr(target_os = "none", feature(custom_test_frameworks))]
96#![cfg_attr(all(target_os = "none", test), test_runner(crate::rt::test_runner))]
97#![cfg_attr(
98	all(target_os = "none", test),
99	reexport_test_harness_main = "test_main"
100)]
101#![cfg_attr(all(target_os = "none", test), no_main)]
102// FIXME: move this to `Cargo.toml` once stable
103#![feature(strict_provenance_lints)]
104#![warn(implicit_provenance_casts)]
105
106// EXTERNAL CRATES
107#[macro_use]
108extern crate alloc;
109#[macro_use]
110extern crate bitflags;
111#[macro_use]
112extern crate log;
113#[cfg(not(target_os = "none"))]
114#[macro_use]
115extern crate std;
116
117#[macro_use]
118mod macros;
119
120#[macro_use]
121mod logging;
122
123pub mod arch;
124#[cfg(all(feature = "common-os", target_arch = "x86_64"))]
125pub mod common_os;
126pub mod config;
127pub mod console;
128mod drivers;
129mod entropy;
130mod env;
131pub mod errno;
132mod executor;
133pub mod fd;
134pub mod fs;
135mod init_buf;
136mod init_cell;
137pub mod io;
138pub mod mm;
139#[cfg(target_os = "none")]
140pub mod rt;
141pub mod scheduler;
142#[cfg(feature = "shell")]
143mod shell;
144mod synch;
145pub mod syscalls;
146pub mod time;
147#[cfg(feature = "uhyve")]
148mod uhyve;
hermit/lib.rs

hermit/
lib.rs
