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_IP`** — Sets the IPv4 address. Defaults to `10.0.5.3`.
55//! - **`HERMIT_GATEWAY`** — Sets the gateway IPv4 address. Defaults to `10.0.5.1`. Is only used when DHCP is not successful.
56//! - **`HERMIT_MASK`** — Sets the network mask. Defaults to `255.255.255.0`. Is only used when DHCP is not successful.
57//! - **`HERMIT_DNS1`** — Sets the first DNS server. Defaults to `9.9.9.9`. Is only used when DHCP is not successful.
58//! - **`HERMIT_DNS2`** — Sets the second DNS server. Defaults to `1.1.1.1`. Is only used when DHCP is not successful.
59//! - **`HERMIT_PCAP_PATH`** — Sets the packet capture file path. Defaults to `/root/`. See the `write-pcap-file` feature for details.
60//!
61//! ## Output environment variables
62//!
63//! - **`NO_COLOR`** — Prevents the addition of ANSI colors to the kernel output. Defaults to unset. For details, see [`NO_COLOR`].
64//! - **`HERMIT_LOG_LEVEL_FILTER`** — Sets the lowest log level to print. Defaults to `info`.
65//!
66//! [`NO_COLOR`]: https://no-color.org/
67//!
68//! ## Deprecated environment variables
69//!
70//! - **`UHYVE_MOUNT`** — Sets the Uhyve mount point. Defaults to `/root`. Nowadays Uhyve supplies this to the kernel.
71//!
72//! [hermit-rs]: https://github.com/hermit-os/hermit-rs
73//! [hermit-c]: https://github.com/hermit-os/hermit-c
74
75#![allow(clippy::missing_safety_doc)]
76#![cfg_attr(
77	any(target_arch = "aarch64", target_arch = "riscv64"),
78	allow(incomplete_features)
79)]
80#![cfg_attr(target_arch = "x86_64", feature(abi_x86_interrupt))]
81#![feature(allocator_api)]
82#![cfg_attr(docsrs, feature(doc_cfg))]
83#![cfg_attr(not(any(feature = "common-os", feature = "nostd")), feature(linkage))]
84#![feature(linked_list_cursors)]
85#![cfg_attr(
86	any(target_arch = "aarch64", target_arch = "riscv64"),
87	feature(specialization)
88)]
89#![cfg_attr(
90	not(any(feature = "common-os", feature = "nostd")),
91	feature(thread_local)
92)]
93#![cfg_attr(target_os = "none", no_std)]
94#![cfg_attr(target_os = "none", feature(custom_test_frameworks))]
95#![cfg_attr(all(target_os = "none", test), test_runner(crate::rt::test_runner))]
96#![cfg_attr(
97	all(target_os = "none", test),
98	reexport_test_harness_main = "test_main"
99)]
100#![cfg_attr(all(target_os = "none", test), no_main)]
101// FIXME: move this to `Cargo.toml` once stable
102#![feature(strict_provenance_lints)]
103#![warn(implicit_provenance_casts)]
104
105// EXTERNAL CRATES
106#[macro_use]
107extern crate alloc;
108#[macro_use]
109extern crate bitflags;
110#[macro_use]
111extern crate log;
112#[cfg(not(target_os = "none"))]
113#[macro_use]
114extern crate std;
115
116#[macro_use]
117mod macros;
118
119#[macro_use]
120mod logging;
121
122pub mod arch;
123#[cfg(all(feature = "common-os", target_arch = "x86_64"))]
124pub mod common_os;
125pub mod config;
126pub mod console;
127mod drivers;
128mod entropy;
129mod env;
130pub mod errno;
131mod executor;
132pub mod fd;
133pub mod fs;
134mod init_buf;
135mod init_cell;
136pub mod io;
137pub mod mm;
138#[cfg(target_os = "none")]
139pub mod rt;
140pub mod scheduler;
141#[cfg(feature = "shell")]
142mod shell;
143mod synch;
144pub mod syscalls;
145pub mod time;
146#[cfg(feature = "uhyve")]
147mod uhyve;
hermit/lib.rs

hermit/
lib.rs
