Crate hermit 

The Hermit kernel.

This library operating system (libOS) compiles to a static library (libhermit.a) that applications can link against to create a Unikernel.

The API documented here does not matter to such an application. Such an application would use it’s languages standard library which internally calls this kernel’s system call functions (syscalls).

Using Hermit

To run a Rust application with Hermit, see hermit-rs.

To run a C or C++ application with Hermit, see hermit-c.

Building the kernel manually

You can build the kernel with default features for x86-64 like this:

cargo xtask build --arch x86_64

For more information, run:

cargo xtask build --help

Features

Syscall Features

• common-os — Enables multiple address spaces.

  This feature makes Hermit use traditional system calls for communicating with the kernel instead of using function calls.

  Note that this feature is not complete yet.

• mman — Enables support for memory management system calls.

  This feature enables functions similar to sys/mman.h.

  For details, see syscalls::mman.

• newlib — Enables support for C and C++ applications via Hermit’s Newlib.

  For details of running C and C++ applications with Hermit, see hermit-c.

Hardware Features

• acpi (enabled by default) — Enables Advanced Configuration and Power Interface (ACPI) support.

  This is not useful on microvms and Uhyve.

• fsgsbase (enabled by default) — Enables using the FSGSBASE instruction family.

  This feature only applies to x86-64.

  Using the FSGSBASE instruction family over RDMSR and WRMSR is more efficient.

  According to QEMU, the FSGSBASE instruction family is supported since at least Intel’s IvyBridge (2012) and AMD’s EPYC (2017).

• pci (enabled by default) — Enables Peripheral Component Interconnect (PCI) support.

  This is not useful on microvms.

  If this feature is disabled, MMIO-based transports are used for devices.

• pci-ids (enabled by default) — Embeds the PCI ID database into the kernel.

  This enables displaying human-readable names for PCI devices.

• semihosting — Enables semihosting support.

  Semihosting allows communicating with the host for

  • stdin, stdout, stderr,
  • accessing the host file system,
  • shutting down with an exit code,
  • getting program arguments,
  • getting the time, and
  • generating random data.

  Note that Hermit currently only supports shutting down with an exit code.

  For details, see the semihosting crate, Semihosting for AArch32 and Aarch64, and RISC-V Semihosting.

• smp (enabled by default) — Enables symmetric multiprocessing (SMP) support.

  This allows utilizing multi-core processors (MCP).

  This currently enables the acpi feature, since ACPI is used for booting the _application processor_s (AP) from the boot-strap processor (BSP).

Network Features

• tcp (enabled by default) — Enables TCP support.
• udp — Enables UDP support.
• dhcpv4 (enabled by default) — Enables DHCPv4 support.
• dns — Enables DNS support.
• net-trace — Enables pretty-printing the network traffic to the serial device.

Network Drivers

Currently, Hermit does not support multiple network drivers at the same time.

If none of these drivers is enabled, but the net feature is active, a loopback driver will be enabled as a fallback.

• virtio-net (enabled by default) — Enables the virtio-net driver.
• rtl8139 — Enables the RTL8139 network driver.
• gem-net — Enables the Cadence Gigabit Ethernet MAC (GEM) network driver.

Virtio Drivers

• virtio-console — Enables the virtio-console driver.
• virtio-fs (enabled by default) — Enables the virtio-fs driver.
• virtio-vsock (enabled by default) — Enables the virtio-vsock driver.

Other Drivers

• vga — Enables the Video Graphics Array (VGA) driver.

  This is only useful on PCs (x86-64).

Performance Features

• idle-poll — Disables putting the CPU to sleep.

  Compared to waiting for interrupts, this improves performance but maxes out CPU utilization.

Debugging Features

• alloc-stats — Enables regularly printing allocation statistics.

• instrument-mcount — Inserts function instrument code for mcount-based tracing.

  This allows instrumentation-based profiling of the kernel.

  For details, see rftrace.

• kernel-stack (enabled by default) — Enables switching to a Kernel-specific stack in system calls.

  This can be useful to avoid and debug stack overflows.

  This only implemented for x86-64 and AArch64 CPUs.

• shell — Enables a kernel shell.

  The shell can be used for displaying the current number of received interrupts and for shutting down the system.

• strace — Enables printing system calls.

Internal Features

• document-features — Documents the Cargo features in the crate docs.

• net (enabled by default) — Enables the network backend.

  This is automatically enabled by any network feature.

• virtio (enabled by default) — Enables the virtio driver backend.

  This is automatically enabled by any virtio driver.

• warn-prebuilt — Enables a warning that this libhermit.a was prebuilt.

Deprecated Features

• console — An alias for the virtio-console feature.

• fs — An alias for the virtio-fs feature.

• fuse — An alias for the virtio-fs feature.

• mmap — An alias for the mman feature.

• nostd — Configures the kernel to be used via its unstable Rust API.

  This feature is not needed to use the kernel via its unstable Rust API.

• trace — An alias for the net-trace feature.

• vsock — An alias for the virtio-vsock feature.

Modules

arch

Architecture-specific architecture abstraction.

console

errno

System error numbers.

fd

fs

io

mm

Memory management.

scheduler

syscalls

time

Macros

dbgtarget_os=none

Prints and returns the value of a given expression for quick and dirty debugging.

panic_printlntarget_os=none

Emergency output.

printtarget_os=none

Prints to the standard output.

printlntarget_os=none

Prints to the standard output, with a newline.

Constants

DEFAULT_STACK_SIZE