# xHyp

**Repository Path**: BookOS/xHyp

## Basic Information

- **Project Name**: xHyp
- **Description**: https://space.bilibili.com/316666586
- **Primary Language**: C
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-09
- **Last Updated**: 2026-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xHyp

xHyp is a minimal Type-1 hypervisor project based on the **ARMv8-A (ARM64)** architecture.

The primary goal of this project is to **learn and understand modern CPU virtualization principles**. It employs a progressive code structure (from Stage 0-2 to 0-5), where each stage focuses on implementing a core subset of virtualization features, making it an ideal introductory tutorial or reference implementation for low-level system software development.

## Key Features

*   **Pure Low-Level Development**: Uses only C language and ARM assembly, with no external dependencies.
*   **Progressive Learning Path**: Code is organized into multiple stages (0-2, 0-3, 0-4, 0-5), gradually increasing in complexity.
*   **Full Debugging Support**: Integrates a simple logging system (`logcat`) and stack backtrace (`backtrace`) to aid development.
*   **Basic Virtualization Functionality**:
    *   Runs at Exception Level 2 (EL2, Hypervisor).
    *   Exception vector table and synchronous/asynchronous exception handling.
    *   Simple hypercall mechanism (for communication with the Guest).
    *   Memory Management Unit (MMU) configuration and page table mapping.
    *   Buddy System page allocator.

## Project Structure

The project is organized by functional stages:

*   **Stage 0-2 (Boot and Serial)**:
    Implements the most basic system boot process, initializes the ARM PL011 serial driver, and outputs "Hello World" via the serial port. This forms the foundation of the entire hypervisor.

*   **Stage 0-3 (Exceptions and Calls)**:
    Introduces an exception handling framework at EL2. Implements the basic logic to switch from EL2 into Guest mode (EL1) and defines standard hypercall interfaces (e.g., `HYPERCALL_CONSOLE`) for early communication.

*   **Stage 0-4 (Memory Management)**:
    Focuses on implementing 4KB page memory mapping. Establishes the foundational framework for Stage 2 address translation (IPA -> PA), enabling the hypervisor to allocate and manage physical memory for the guest OS.

*   **Stage 0-5 (Advanced Features)**:
    Enhances support for user/kernel-space C standard library functions (`libc.c`), introduces the buddy page allocator (`page.c`) to support dynamic memory allocation, and adds the `logcat` logging system to make debugging complex errors feasible.

## Build and Run

### Environment Setup

You need to install an ARM cross-compilation toolchain and QEMU emulator:

```bash
# Ubuntu/Debian example
sudo apt-get install gcc-aarch64-linux-gnu qemu-system-arm
```

### Building the Project

Run `make` from the project root directory:

```bash
make
```

This will generate executable files (e.g., `Image` or `boot.elf`) in each stage directory.

### Running and Debugging

It is recommended to run and debug using QEMU:

```bash
# Example: Run Stage 0-2
qemu-system-aarch64 -machine virt -cpu cortex-a57 -nographic -kernel 0-2/boot.elf
```

You can view serial output and debugging information in the QEMU terminal.

## License

This project is licensed under an open-source license; see the [LICENSE](LICENSE) file for details.