Skip to content

Commit 1bec4ef

Browse files
mkroeningmkroening
authored
Merge pull request #2273 from hermit-os/document-features
docs: document features
2 parents ba36423 + fb122b7 commit 1bec4ef

5 files changed

Lines changed: 280 additions & 25 deletions

File tree

‎Cargo.lock‎

Lines changed: 16 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml‎

Lines changed: 216 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,9 @@ exclude = [
1818
".gitignore",
1919
]
2020

21+
[package.metadata.docs.rs]
22+
all-features = true
23+
2124
[lib]
2225
name = "hermit"
2326

@@ -34,44 +37,235 @@ name = "measure_startup_time"
3437
harness = false
3538

3639
[features]
37-
default = ["kernel-stack", "pci", "pci-ids", "acpi", "fsgsbase", "smp", "tcp", "dhcpv4", "virtio-fs", "virtio-net", "virtio-vsock"]
38-
acpi = []
39-
alloc-stats = ["talc/counters"]
40+
default = [
41+
"acpi",
42+
"dhcpv4",
43+
"fsgsbase",
44+
"kernel-stack",
45+
"pci-ids",
46+
"pci",
47+
"smp",
48+
"tcp",
49+
"virtio-fs",
50+
"virtio-net",
51+
"virtio-vsock",
52+
]
53+
54+
#! ### Syscall Features
55+
56+
## Enables multiple address spaces.
57+
##
58+
## This feature makes Hermit use traditional system calls for communicating with the kernel
59+
## instead of using function calls.
60+
##
61+
## Note that this feature is not complete yet.
4062
common-os = []
41-
dhcpv4 = ["net", "smoltcp", "smoltcp/proto-dhcpv4", "smoltcp/socket-dhcpv4"]
42-
dns = ["net", "smoltcp", "smoltcp/socket-dns"]
43-
fsgsbase = []
44-
gem-net = ["net", "dep:tock-registers"]
45-
idle-poll = []
46-
instrument-mcount = [] # Inserts function instrument code for mcount-based tracing
47-
kernel-stack = []
48-
net = []
49-
net-trace = ["smoltcp?/log", "smoltcp?/verbose"]
63+
64+
## Enables support for memory management system calls.
65+
##
66+
## This feature enables functions similar to [sys/mman.h].
67+
##
68+
## For details, see [`syscalls::mman`].
69+
##
70+
## [sys/mman.h]: https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/sys_mman.h.html
5071
mman = []
51-
mmap = ["mman"] # Deprecated in favor of mman
72+
73+
## Enables support for C and C++ applications via Hermit's [Newlib].
74+
##
75+
## For details of running C and C++ applications with Hermit, see [hermit-c].
76+
##
77+
## [Newlib]: https://github.com/hermit-os/newlib
78+
## [hermit-c]: https://github.com/hermit-os/hermit-c
5279
newlib = []
80+
81+
#! ### Hardware Features
82+
#!
83+
#! [microvm]: https://www.qemu.org/docs/master/system/i386/microvm.html
84+
#! [Uhyve]: https://github.com/hermit-os/uhyve
85+
86+
## Enables _Advanced Configuration and Power Interface_ ([ACPI]) support.
87+
##
88+
## This is not useful on [microvm]s and [Uhyve].
89+
##
90+
## [ACPI]: https://uefi.org/specs/ACPI/6.6/
91+
acpi = []
92+
93+
## Enables using the [FSGSBASE] instruction family.
94+
##
95+
## This feature only applies to x86-64.
96+
##
97+
## Using the FSGSBASE instruction family over RDMSR and WRMSR is more efficient.
98+
##
99+
## According to QEMU, the FSGSBASE instruction family is supported since at least Intel's IvyBridge
100+
## (2012) and AMD's EPYC (2017).
101+
##
102+
## [FSGSBASE]: https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/best-practices/guidance-enabling-fsgsbase.html
103+
fsgsbase = []
104+
105+
## Enables _Peripheral Component Interconnect_ ([PCI]) support.
106+
##
107+
## This is not useful on [microvm]s.
108+
##
109+
## If this feature is disabled, MMIO-based transports are used for devices.
110+
##
111+
## [PCI]: https://pcisig.com/
53112
pci = ["virtio?/pci"]
54-
rtl8139 = ["net", "pci", "volatile/derive", "endian-num"]
113+
114+
## Enables semihosting support.
115+
##
116+
## Semihosting allows communicating with the host for
117+
##
118+
## - `stdin`, `stdout`, `stderr`,
119+
## - accessing the host file system,
120+
## - shutting down with an exit code,
121+
## - getting program arguments,
122+
## - getting the time, and
123+
## - generating random data.
124+
##
125+
## Note that Hermit currently only supports shutting down with an exit code.
126+
##
127+
## For details, see the [`semihosting`] crate, [Semihosting for AArch32 and Aarch64], and
128+
## [RISC-V Semihosting].
129+
##
130+
## [`semihosting`]: https://docs.rs/semihosting
131+
## [Semihosting for AArch32 and Aarch64]: https://github.com/riscv-non-isa/riscv-semihosting/releases/download/1.0/riscv-semihosting.pdf
132+
## [RISC-V Semihosting]: https://github.com/ARM-software/abi-aa/tree/2025Q4/semihosting
55133
semihosting = ["dep:semihosting"]
56-
shell = ["simple-shell"]
57-
smp = ["acpi"] # on x86_64, SMP only works together with ACPI
58-
strace = []
134+
135+
## Enables _symmetric multiprocessing_ (SMP) support.
136+
##
137+
## This allows utilizing _multi-core processors_ (MCP).
138+
##
139+
## This currently enables the `acpi` feature, since ACPI is used for booting the
140+
## _application processor_s (AP) from the _boot-strap processor_ (BSP).
141+
smp = ["acpi"]
142+
143+
#! ### Network Features
144+
145+
## Enables TCP support.
59146
tcp = ["net", "smoltcp", "smoltcp/socket-tcp"]
147+
148+
## Enables UDP support.
60149
udp = ["net", "smoltcp", "smoltcp/socket-udp"]
61-
vga = []
62-
virtio = ["dep:virtio", "dep:mem-barrier"]
150+
151+
## Enables DHCPv4 support.
152+
dhcpv4 = ["net", "smoltcp", "smoltcp/proto-dhcpv4", "smoltcp/socket-dhcpv4"]
153+
154+
## Enables DNS support.
155+
dns = ["net", "smoltcp", "smoltcp/socket-dns"]
156+
157+
## Enables pretty-printing the network traffic to the serial device.
158+
net-trace = ["smoltcp?/log", "smoltcp?/verbose"]
159+
160+
#! ### Network Drivers
161+
#!
162+
#! Currently, Hermit does not support multiple network drivers at the same time.
163+
#!
164+
#! If none of these drivers is enabled, but the `net` feature is active, a loopback driver
165+
#! will be enabled as a fallback.
166+
167+
## Enables the virtio-net driver.
168+
virtio-net = ["net", "virtio"]
169+
170+
## Enables the RTL8139 network driver.
171+
rtl8139 = ["net", "pci", "volatile/derive", "endian-num"]
172+
173+
## Enables the Cadence Gigabit Ethernet MAC (GEM) network driver.
174+
gem-net = ["net", "dep:tock-registers"]
175+
176+
#! ### Virtio Drivers
177+
178+
## Enables the virtio-console driver.
63179
virtio-console = ["virtio"]
180+
181+
## Enables the virtio-fs driver.
64182
virtio-fs = ["virtio", "dep:fuse-abi", "fuse-abi/num_enum"]
65-
virtio-net = ["net", "virtio"]
183+
184+
## Enables the virtio-vsock driver.
66185
virtio-vsock = ["virtio", "pci"]
186+
187+
#! ### Other Drivers
188+
189+
## Enables the _Video Graphics Array_ (VGA) driver.
190+
##
191+
## This is only useful on PCs (x86-64).
192+
vga = []
193+
194+
#! ### Performance Features
195+
196+
## Disables putting the CPU to sleep.
197+
##
198+
## Compared to waiting for interrupts, this improves performance but maxes out CPU utilization.
199+
idle-poll = []
200+
201+
#! ### Debugging Features
202+
203+
## Enables regularly printing allocation statistics.
204+
alloc-stats = ["talc/counters"]
205+
206+
## Inserts function instrument code for mcount-based tracing.
207+
##
208+
## This allows instrumentation-based profiling of the kernel.
209+
##
210+
## For details, see [rftrace].
211+
##
212+
## [rftrace]: https://github.com/hermit-os/rftrace
213+
instrument-mcount = []
214+
215+
## Enables switching to a Kernel-specific stack in system calls.
216+
##
217+
## This can be useful to avoid and debug stack overflows.
218+
##
219+
## This only implemented for x86-64 and AArch64 CPUs.
220+
kernel-stack = []
221+
222+
## Enables a kernel shell.
223+
##
224+
## The shell can be used for displaying the current number of received interrupts and for shutting
225+
## down the system.
226+
shell = ["simple-shell"]
227+
228+
## Enables printing system calls.
229+
strace = []
230+
231+
#! ### Internal Features
232+
233+
## Enables the network backend.
234+
##
235+
## This is automatically enabled by any network feature.
236+
net = []
237+
238+
## Enables the virtio driver backend.
239+
##
240+
## This is automatically enabled by any virtio driver.
241+
virtio = ["dep:virtio", "dep:mem-barrier"]
242+
243+
## Enables a warning that this libhermit.a was prebuilt.
67244
warn-prebuilt = []
68245

69-
# Deprecated
246+
#! ### Deprecated Features
247+
248+
## An alias for the `virtio-console` feature.
70249
console = ["virtio-console"]
250+
251+
## An alias for the `virtio-fs` feature.
71252
fs = ["virtio-fs"]
253+
254+
## An alias for the `virtio-fs` feature.
72255
fuse = ["virtio-fs"]
256+
257+
## An alias for the `mman` feature.
258+
mmap = ["mman"]
259+
260+
## Configures the kernel to be used via its unstable Rust API.
261+
##
262+
## This feature is not needed to use the kernel via its unstable Rust API.
73263
nostd = []
264+
265+
## An alias for the `net-trace` feature.
74266
trace = ["net-trace"]
267+
268+
## An alias for the `virtio-vsock` feature.
75269
vsock = ["virtio-vsock"]
76270

77271
[lints.rust]
@@ -117,6 +311,7 @@ bitflags = "2"
117311
build-time = "0.1.3"
118312
cfg-if = "1"
119313
crossbeam-utils = { version = "0.8", default-features = false }
314+
document-features = { version = "0.2", optional = true }
120315
embedded-io = { version = "0.7", features = ["alloc"] }
121316
endian-num = { version = "0.2", optional = true, features = ["linux-types"] }
122317
enum_dispatch = "0.3"

‎src/lib.rs‎

Lines changed: 39 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,42 @@
1-
//! First version is derived and adapted for Hermit from
2-
//! Philipp Oppermann's excellent series of blog posts (<http://blog.phil-opp.com/>)
3-
//! and Eric Kidd's toy OS (<https://github.com/emk/toyos-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+
//! [hermit-rs]: https://github.com/hermit-os/hermit-rs
39+
//! [hermit-c]: https://github.com/hermit-os/hermit-c
440
541
#![allow(clippy::missing_safety_doc)]
642
#![cfg_attr(

‎src/syscalls/mman.rs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
//! Memory management syscalls.
2+
//!
3+
//! These system calls are similar to [sys/mman.h].
4+
//!
5+
//! <div class="warning">These system calls are not very POSIX-like yet!</div>
6+
//!
7+
//! [sys/mman.h]: https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/sys_mman.h.html
8+
19
use core::ffi::{c_int, c_void};
210

311
use align_address::Align;

‎src/syscalls/mod.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ mod entropy;
3838
mod futex;
3939
pub(crate) mod interfaces;
4040
#[cfg(feature = "mman")]
41-
mod mman;
41+
pub mod mman;
4242
mod processor;
4343
#[cfg(feature = "newlib")]
4444
mod recmutex;

0 commit comments

Comments
 (0)