Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: capitalize Uhyve #709

Merged
merged 1 commit into from
Jun 14, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
<img width="200" align="right" src="img/uhyve.svg" />

# uhyve - A minimal hypervisor for Hermit
# Uhyve - A minimal hypervisor for Hermit

[![crates.io](https://img.shields.io/crates/v/uhyve.svg)](https://crates.io/crates/uhyve)
[![Zulip Badge](https://img.shields.io/badge/chat-hermit-57A37C?logo=zulip)](https://hermit.zulipchat.com/)

## Introduction

uhyve is small hypervisor to boot the [Hermit kernel](https://github.com/hermitcore/kernel), which is a unikernel operating system targeting a scalable and predictable runtime behavior for HPC and cloud environments.
Uhyve is small hypervisor to boot the [Hermit kernel](https://github.com/hermitcore/kernel), which is a unikernel operating system targeting a scalable and predictable runtime behavior for HPC and cloud environments.

**Warning:** At the moment uhyve grants full host file system access from within the unikernel with the permissions of the user running uhyve.
**Warning:** At the moment Uhyve grants full host file system access from within the unikernel with the permissions of the user running Uhyve.
Thus, it should not be used for applications which require isolation from the host system.

## Installation

An installation of the Rust toolchain is required.
Please visit the [Rust website](https://www.rust-lang.org/) and follow the installation instructions.

Install uhyve with
Install Uhyve with

```console
$ cargo install --locked uhyve
Expand All @@ -33,7 +33,7 @@ To check if your system supports virtualization, you can use the following comma
if egrep -c '(vmx|svm)' /proc/cpuinfo > /dev/null; then echo "Virtualization support found"; fi
```

On Linux, uhyve depends on the virtualization solution [KVM](https://www.linux-kvm.org/page/Main_Page) (Kernel-based Virtual Machine).
On Linux, Uhyve depends on the virtualization solution [KVM](https://www.linux-kvm.org/page/Main_Page) (Kernel-based Virtual Machine).
If the following command gives you some output, you are ready to go!

```sh
Expand All @@ -44,7 +44,7 @@ lsmod | grep kvm

### macOS

**Disclaimer:** Currently, uhyve is mainly developed for Linux.
**Disclaimer:** Currently, Uhyve is mainly developed for Linux.
The macOS version has not been tested extensively and does not support all features of the Linux version.

Apple's *Command Line Tools* must be installed.
Expand Down Expand Up @@ -75,7 +75,7 @@ cd uhyve
cargo build --release
```

## Signing uhyve to run on macOS Big Sur
## Signing Uhyve to run on macOS Big Sur

`uhyve` can be self-signed with the following command.

Expand All @@ -98,7 +98,7 @@ The file `app.entitlements` must have following content:

For further details have a look at [Apple's documentation](https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_security_hypervisor).

## Running Hermit apps within uhyve
## Running Hermit apps within Uhyve

Use the hypervisor to start the unikernel.
```sh
Expand All @@ -107,13 +107,13 @@ uhyve /path/to/the/unikernel/binary

### Configuration

uhyve can be configured via environment variables.
Uhyve can be configured via environment variables.
The following variables are supported.

- `HERMIT_CPUS`: specifies the number of cores the virtual machine may use.
- `HERMIT_MEM`: defines the memory size of the virtual machine. The suffixes *M* and *G* can be used to specify a value in megabytes or gigabytes, respectively.
- setting `HERMIT_VERBOSE` to `1` makes the hypervisor print kernel log messages to the terminal.
- `HERMIT_GDB_PORT=port` activate a gdb server for the application running inside uhyve. _See below_
- `HERMIT_GDB_PORT=port` activate a gdb server for the application running inside Uhyve. _See below_

By default, the loader initializes a system with one core and 512 MiB RAM.

Expand All @@ -125,9 +125,9 @@ HERMIT_CPUS=4 HERMIT_MEM=8G uhyve /path/to/the/unikernel/binary

## Debugging of Hermit apps (unstable)

Basic support of (single-core) applications is already integrated into uhyve.
By specifying variable `HERMIT_GDB_PORT=port`, uhyve is working as gdbserver and is waiting on port `port` for a connection to a gdb.
For instance, with the following command uhyve is waiting on port `6677` for a connection.
Basic support of (single-core) applications is already integrated into Uhyve.
By specifying variable `HERMIT_GDB_PORT=port`, Uhyve is working as gdbserver and is waiting on port `port` for a connection to a gdb.
For instance, with the following command Uhyve is waiting on port `6677` for a connection.

```bash
HERMIT_GDB_PORT=6677 uhyve /path_to_the_unikernel/hello_world
Expand Down
2 changes: 1 addition & 1 deletion src/arch/aarch64/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,7 @@ pub fn init_guest_mem(mem: &mut [u8]) {
)
};
pgt_slice.fill(0);
// map uhyve ports into the virtual address space
// map Uhyve ports into the virtual address space
pgt_slice[0] = PT_MEM_CD;
// map BootInfo into the virtual address space
pgt_slice[BOOT_INFO_ADDR.as_u64() as usize / PAGE_SIZE] = BOOT_INFO_ADDR.as_u64() + PT_MEM;
Expand Down
2 changes: 1 addition & 1 deletion tests/common.rs
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ pub fn build_hermit_bin(kernel: impl AsRef<Path>) -> PathBuf {
}

/// Small wrapper around [`Uhyve::run`] with default parameters for a small and
/// simple uhyve vm
/// simple Uhyve vm
pub fn run_simple_vm(kernel_path: PathBuf) {
let params = Params {
verbose: true,
Expand Down
6 changes: 3 additions & 3 deletions uhyve-interface/src/elf.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
//! Utility to place the uhyve interface version in the elf header of the hermit kernel.
//! Utility to place the Uhyve interface version in the elf header of the hermit kernel.

/// Defines the uhyve interface version in the note section.
/// Defines the Uhyve interface version in the note section.
///
/// This macro must be used in a module that is guaranteed to be linked.
/// See <https://github.com/rust-lang/rust/issues/99721>.
Expand All @@ -13,7 +13,7 @@ macro_rules! define_uhyve_interface_version {
};
}

/// Note type for specifying the uhyve interface version in an elf header.
/// Note type for specifying the Uhyve interface version in an elf header.
pub const NT_UHYVE_INTERFACE_VERSION: u32 = 0x5b00;

/// A elf note header entry containing the used Uhyve interface version as little-endian 32-bit value.
Expand Down
6 changes: 3 additions & 3 deletions uhyve-interface/src/lib.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
//! # Uhyve Hypervisor Interface
//!
//! The uhyve hypercall interface works as follows:
//! The Uhyve hypercall interface works as follows:
//!
//! - On `x86_64` you use an out port instruction. The address of the `out`-port corresponds to the
//! hypercall you want to use. You can obtain it from the [`IoPorts`] enum. The data send to
Expand Down Expand Up @@ -28,7 +28,7 @@ pub use ::x86_64::addr::VirtAddr as GuestVirtAddr;
compile_error!("Using uhyve-interface on a non-64-bit system is not (yet?) supported");
use parameters::*;

/// The version of the uhyve interface. Note: This is not the same as the semver of the crate but
/// The version of the Uhyve interface. Note: This is not the same as the semver of the crate but
/// should be increased on every version bump that changes the API.
pub const UHYVE_INTERFACE_VERSION: u32 = 1;

Expand Down Expand Up @@ -87,7 +87,7 @@ impl From<Hypercall<'_>> for HypercallAddress {
}
}

/// Hypervisor calls available in uhyve with their respective parameters. See the [module level documentation](crate) on how to invoke them.
/// Hypervisor calls available in Uhyve with their respective parameters. See the [module level documentation](crate) on how to invoke them.
#[non_exhaustive]
#[derive(Debug)]
pub enum Hypercall<'a> {
Expand Down