# uk-linux

**Repository Path**: hzc1998/uk-linux

## Basic Information

- **Project Name**: uk-linux
- **Description**: an user mode linux service for microkernel system
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-24
- **Last Updated**: 2026-05-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# uKernel-on-Linux

**A microkernel operating system built on top of the Linux kernel.**

> Just as KVM turns Linux into a hypervisor by adding a thin kernel module,
> uKernel turns Linux into a microkernel host by adding IPC routing and
> capability-based access control — without modifying the Linux kernel itself.

---

## What is uKernel-on-Linux?

uKernel-on-Linux is a microkernel architecture implementation that leverages the
Linux kernel as its foundation. Instead of building a microkernel from scratch
or surgically splitting the Linux kernel, we take the **KVM approach**: add a
kernel module (`ukernel.ko`) that provides IPC routing, capability management,
and service orchestration, while delegating scheduling, memory management, and
device drivers to the existing Linux kernel.

### Why this approach?

| Approach | Problem |
|----------|---------|
| Build from scratch (seL4, Fiasco) | No driver ecosystem, years to boot on real hardware |
| Split Linux kernel | 30+ years of implicit dependencies, impractical |
| **uKernel-on-Linux (this project)** | **Add a layer, don't modify the base** |

### Key Principles

1. **Linux as foundation** — Reuse scheduling, memory management, drivers, VFS, networking
2. **KVM analogy** — `ukernel.ko` is to microkernel what `kvm.ko` is to virtualization
3. **POSIX compatible** — Applications link against `libc-uk` and run unmodified
4. **Capability-based security** — Every IPC call is validated against capability tokens
5. **Zero-copy data plane** — Shared memory for data, lightweight IPC for control

---

## Architecture Overview

```
┌─────────────────────────────────────────────────────┐
│                    Applications                      │
│              (linked with libc-uk)                   │
├─────────────────────────────────────────────────────┤
│  libc-uk (POSIX compatibility layer)                │
│  open() → uk_fs_open IPC  |  socket() → uk_net IPC │
├─────────────────────────────────────────────────────┤
│              ukernel-lib (IPC client)                │
│         shared memory + eventfd + ioctl              │
├──────┬──────┬──────┬──────┬──────────────────────────┤
│  FS  │ NET  │ DEV  │ PROC │  Service Processes       │
│Service│Service│Service│Service│  (user-space)         │
│(FUSE)│(XDP) │(VFIO)│      │                          │
├──────┴──────┴──────┴──────┴──────────────────────────┤
│              ukernel.ko (kernel module)              │
│  IPC router │ Capability │ SHM manager │ Registry    │
├─────────────────────────────────────────────────────┤
│              Linux Kernel (unmodified)               │
│  Scheduler │ Memory │ Drivers │ VFS │ Networking    │
└─────────────────────────────────────────────────────┘
```

---

## Project Structure

```
ukernel-on-linux/
├── kernel/             # ukernel.ko kernel module source
├── service/
│   ├── libc-uk/        # POSIX-compatible C library
│   ├── fs/             # File system service (FUSE-based)
│   ├── net/            # Network stack service (AF_XDP-based)
│   ├── dev/            # Device management service (VFIO-based)
│   ├── proc/           # Process management service
│   └── svc-registry/   # Service discovery and registry
├── include/
│   └── ukernel/        # Shared header files
│       ├── ipc.h       # IPC message definitions
│       ├── cap.h       # Capability definitions
│       ├── svc.h       # Service interface definitions
│       └── ukernel.h   # Core API definitions
├── tools/              # Build and testing utilities
├── tests/              # Test suites
├── docs/               # Documentation
│   ├── DESIGN.md       # Detailed design document
│   ├── API.md          # API reference
│   └── ROADMAP.md      # Development roadmap
├── DESIGN.md           # Core design document (this repo root)
├── CONTRIBUTING.md     # Contribution guidelines
├── LICENSE             # Apache 2.0
└── README.md           # This file
```

---

## Quick Start

### Prerequisites

- Linux kernel 6.1+ (with CONFIG_FUSE, CONFIG_VFIO, CONFIG_XDP_SOCKETS)
- GCC 12+ or Clang 15+
- Make, CMake 3.20+
- Linux kernel headers for your running kernel

### Build

```bash
# Clone the repository
git clone https://github.com/your-org/ukernel-on-linux.git
cd ukernel-on-linux

# Build the kernel module
make -C kernel/

# Build user-space services and libc
make -C service/

# Install (requires root)
sudo make install
```

### Run

```bash
# Load the ukernel kernel module
sudo modprobe ukernel

# Start the service registry
uk-svc-registry &

# Start the file system service
uk-fs --mountpoint /opt/uk-rootfs &

# Start the network service
uk-net &

# Run an application through libc-uk
LD_PRELOAD=libuk-preload.so /bin/ls /opt/uk-rootfs
```

---

## Performance Targets

| Metric | Target | Rationale |
|--------|--------|-----------|
| Single IPC (control) | < 200 ns | L4-class performance |
| Shared memory read | < 10 ns | Direct memory access |
| `open()` via libc-uk | < 2 μs | 1 IPC + FUSE roundtrip |
| `read()` via libc-uk | < 500 ns | Shared memory data path |
| POSIX overhead vs native | < 15% | Acceptable for most workloads |

---

## Documentation

- [Design Document](DESIGN.md) — Complete architecture and design details
- [API Reference](docs/API.md) — Interface specifications for all components
- [Roadmap](docs/ROADMAP.md) — Development phases and milestones

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. We welcome contributions
in all areas: kernel module, services, libc, documentation, and testing.

---

## License

Apache License 2.0 — see [LICENSE](LICENSE) for details.

---

## Acknowledgments

This project draws inspiration from:

- **KVM** — The "add a layer, don't modify the base" philosophy
- **seL4 / L4** — Microkernel IPC performance benchmarks
- **gVisor** — User-space kernel / POSIX compatibility layer design
- **FUSE / AF_XDP / VFIO** — Linux user-space subsystem foundations
- **QNX** — Production microkernel system design