# protofire

**Repository Path**: RaidenLumine/protofire

## Basic Information

- **Project Name**: protofire
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-06
- **Last Updated**: 2026-11-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Protofire Kernel

This is a bare-metal `#![no_std]` monolithic kernel written in Rust, targeting
x86_64, AArch64, and RISC-V 64. It provides a file-oriented userspace ABI with
preemptive multi-threading, a native TCP/IP stack, a transactional in-memory
filesystem (PyroFs), NUMA-aware scheduling, virtio-gpu accelerated display,
MSI/MSI-X interrupt support, heap block canaries that attribute an overrun to
the allocation that caused it, and a shared `src/user/shared/` library for both
kernel and userspace programs.

## What's Distinct

The parts a reader is least likely to expect from a kernel this size, and the
shapes that explain most of the rest:

- **The filesystem drivers** — FAT32, exFAT, ext4, F2FS, btrfs, XFS, NTFS,
  ISO 9660, EROFS and SquashFS — beside PyroFs, the native transactional
  filesystem, with journal replay for ext4/XFS/F2FS.
- **A userspace runtime inside the kernel crate**: `src/user/shared/` is
  compiled on both sides of the syscall boundary, so a syscall wrapper, a
  shell builtin and an ABI record have one definition rather than one per side.
- **Two layers of mandatory access control**: a Biba integrity model and a MAC
  type-enforcement engine with allow-rules and default-deny.
- **A TLSF heap**: O(1) bounded-time allocation and free.
- **Unicode 15.1 NFC/NFD normalization** and a GB18030 codec.
- **A block cache that ages dirty blocks** on a scheduler-advanced clock and a
  transparently encrypted block device (AES-256 XTS, LUKS2 headers).

What exists, what is missing, and what is wired but not yet reachable is
[`docs/status.md`](docs/status.md) — that document is the authority; this
list is an introduction, and it does not repeat it.

## Kernel Name

| Chinese (zh) | English (en) |
| :-: | :-: |
| 源火 | Protofire |

## Environment Setup

Everything the build needs is either pinned in this repository or checked by
one command:

```bash
make doctor
```

`make doctor` prints one line per tool and Rust target, exits non-zero when
something the build depends on is missing, and is the same command CI runs on
Linux (x86_64 and arm64), Windows and macOS.

What the repository cannot pin is a short list — rustup, GNU make with a POSIX
shell, QEMU for the run targets, and your platform's own linker for host-side
binaries — so the rest of this section is only that list, and the versions the
files already pin are not repeated here.

### What the repository already pins

- **Toolchain and targets.** [`rust-toolchain.toml`](rust-toolchain.toml) is the
  single source of truth for the channel, the `rustfmt` / `clippy` /
  `llvm-tools-preview` components, and the three bare-metal targets. Install
  [rustup](https://rustup.rs/) and run any command inside the repository: the
  first one downloads the pinned toolchain with its targets, so there is no
  `rustup target add` step to remember. Do not trust a version written in
  prose — read that file.
- **No cross compiler.** All three `*-none` targets link with the `rust-lld`
  that ships inside the toolchain, so cross-compiling needs no
  `gcc-aarch64-*`, no `gcc-riscv64-*`, no `*-none-elf` binutils, and no
  `bootimage`-style helper. `make build`, `make build-aarch64` and
  `make build-riscv64` work from any host.
- **Line endings.** LF everywhere, enforced by
  [`.gitattributes`](.gitattributes); a `core.autocrlf=true` checkout still
  gives `sh`, GNU make and rustc the files they expect.
- **Host linker.** Host-side targets — the tests, build scripts and the
  `mkimage` helper — are ordinary native binaries, so they use the platform's
  own linker: `cc` on Linux, the Xcode command line tools on macOS, and the
  Visual Studio C++ build tools on an MSVC Windows host. `make check` and
  `make clippy` do not link, so they do not need any of it.

### What you install

| Platform | Command |
|----------|---------|
| Debian / Ubuntu | `sudo apt install make qemu-system-x86 qemu-system-arm qemu-system-misc` |
| Fedora / RHEL | `sudo dnf install make qemu-system-x86 qemu-system-aarch64 qemu-system-riscv` |
| Arch | `sudo pacman -S base-devel qemu-system-x86 qemu-system-aarch64 qemu-system-riscv` |
| macOS | nothing for make — Apple ships GNU Make 3.81, and the Makefile stays within it; `brew install qemu` for the run targets, or `brew install make` if you would rather have a current GNU make (it installs as `gmake`) |
| Windows | `choco install make` (or MSYS2: `pacman -S make`), then run the Makefile from Git Bash so `sh` is on `PATH`; QEMU from the [Windows installer](https://www.qemu.org/download/#windows), or `choco install qemu` / `scoop install qemu` |

QEMU provides `qemu-system-x86_64`, `qemu-system-aarch64` and
`qemu-system-riscv64`, and only the run targets and
`make check-aarch64-runtime` need it. `grub-mkrescue` and `xorriso` are
needed by `make iso`, which builds a GRUB-bootable ISO image and by
`make check-x8664-iso`, which boots it — the one boot in the tree that goes
through a real loader rather than QEMU's own hand-off.

`make iso` writes `target/protofire.iso`, and that image is what a machine
with no QEMU underneath it boots: it is a hybrid (an ISO 9660 filesystem
with an MBR/GPT partition table and an EFI system partition), so the same
file can be burnt to a CD, mounted as a virtual DVD, or **written to a USB
stick**.  For a stick:

```sh
make iso
lsblk                      # find the stick's device — /dev/sdX or /dev/nvmeX
sudo dd if=target/protofire.iso of=/dev/sdX bs=4M status=progress oflag=sync
```

`/dev/sdX` is the whole stick, not a partition on it (`/dev/sdX1` would
overwrite that partition and leave the stick unbootable); `dd` destroys
whatever is there, so check the name from `lsblk` first.

A machine that already has a disk does not need the image written over it —
it needs the kernel *installed* onto it.  `install` adds this kernel's zones
to a disk's existing **GPT**, keeping every partition that was already
there — the system zone as its A/B **pair**, so the boot takes the newer
build and a rollback has the older:

```sh
sudo cargo run -- install /dev/sdX   # shows the plan, then asks for a typed `yes`
```

The install reads and writes the disk in blocks — a few blocks of table and
the zones themselves — so it works on a disk of any size and on the machine
it is installing.  Work on a copy (`cp /dev/sdX disk.img` … `sudo dd
if=disk.img of=/dev/sdX …`) when you would rather keep the original.

The install never writes before it asks: it prints what it would do — the
partitions it would keep, each zone and the extent it would take — and
proceeds only on the typed word `yes`.  A disk it cannot help is refused
*before* the question, and `no`, an empty answer, or end of input all leave
the disk exactly as it was.  Scripts (and `make check-x8664-install`) use
`--yes`, which skips the question rather than answering it.

The disk must already carry a GPT — a disk partitioned by someone else's
tool is exactly the one this is for.  A disk with **no table at all** is
refused unless you ask for one, which the flag makes an explicit decision:

```sh
sudo cargo run -- install --new-table /dev/sdX
```

Only a disk that carries no partition information — no GPT, no MBR
entries, no GPT signature — gets the fresh table; anything else is refused
either way (`make check-x8664-install` is the gate: it makes the disk with
`sgdisk`, installs, keeps the disk's own partition, boots the result, and
boots a blank disk the flag gave a table).  A machine that
boots the stick shows the kernel's console on the display — the image's
Multiboot2 header asks the loader for a framebuffer, so GRUB sets a
graphical mode and the kernel draws on the frame it was handed, and no
serial port is needed to see or to use the shell (a machine's PS/2 keyboard
is the input the kernel expects).

### Host requirements

The checks and the bare-metal builds are host-independent: the demo disk is
built by the kernel itself, out of the payload sections each target's
cross-compilation assembles.  A *host* build cannot assemble those sections —
`mkimage` is a Mach-O or COFF binary on two of the three host platforms — so a
program whose image the disk does not carry is stood in for by the host-side
runtime that shares its name (`src/user/program/demo_runtime.rs`); that is what
keeps an `mkimage`-written demo disk bootable.

What still pins a host down is the test suite. It drives x86_64 user-mode code
(`ptrace`, user address space, exception frames) inside the test process, so
`make test` needs an x86_64 host; `make doctor`, `make check`, `make clippy`
and the cross-builds do not.

| Host | `make doctor` / `check` / `clippy` / `build*` | `make test` |
|------|-----------------------------------------------|-------------|
| Linux x86_64 | supported — the reference host, covered by CI | supported, and what CI runs |
| Windows x86_64 | supported, covered by CI | supported, covered by CI |
| macOS x86_64 (Intel) | supported, covered by CI | supported, covered by CI |
| Linux arm64 | supported, covered by CI | needs an x86_64 host |
| macOS arm64 (Apple Silicon) | supported — the same host paths as Linux arm64 | needs an x86_64 host |

An Apple Silicon Mac cross-builds every bare-metal target, runs QEMU and passes
the checks; only the in-process x86_64 test suite needs an x86_64 machine or
container (`docker run --platform linux/amd64`). Other arm64 hosts — Windows on
Arm, for instance — are untested; treat them as needing an x86_64 container.

## Build & Test

The commands below assume the environment above is in place (`make doctor` is
clean).

### Quick Start

```bash
# Host-side type-check (all targets)
make check

# Host-side unit + integration tests (requires demo-disk feature)
make test

# Fast-turnaround test subsets
make test-fast          # path, I/O, syscall, user integration regressions
make test-concurrency   # scheduler, input, condvar concurrency regressions
make test-storage       # filesystem, recovery, fault-injection regressions

# Multi-tier verification gate
make verify             # default P3 gate (fmt + clippy + test + cross-check)
make verify-p0          # fastest: fmt + checks + header coverage
make verify-p1          # p0 + host unit tests + target checks
make verify-p2          # p1 + integration tests
make verify-p3          # p2 + full cross-target build

# Bare-metal build
make build
make build-aarch64
make build-riscv64

# Run under QEMU
make run
make run-aarch64
make run-riscv64

# Clippy (all targets, warnings as errors on critical lints)
make clippy
```

### Useful make variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `PROFILE` | `debug` | `debug` or `release` build profile |
| `TARGET` | `x86_64-unknown-none` | bare-metal target used by `check-target` and `build-x8664` |
| `TARGET_DIR` | `target` | Cargo artifact directory |
| `CARGO_FLAGS` | `--offline` | passed to every cargo invocation; with no dependencies the default keeps builds hermetic — override it (e.g. `make test CARGO_FLAGS=`) to let cargo reach the network |
| `VERIFY_TIER` | `p3` | tier used by `make verify` (`p0` … `p3`) |

## Structure

```text
├── src/
│   ├── abi/               # Shared ABI records (syscall encodings, process/file/network wire shapes)
│   ├── arch/              # Architecture backends (x86_64, AArch64, RISC-V)
│   ├── drivers/           # Device drivers (block, network, display, input, audio, USB)
│   ├── fs/                # VFS, the native filesystem, and every filesystem driver
│   ├── kernel/            # Kernel core (boot, scheduler, process model, sync, IPC, security)
│   ├── memory/            # Frame allocator, TLSF heap, page tables
│   ├── network/           # The kernel's own TCP/IP stack and its protocols
│   ├── syscall/           # Syscall dispatch table and per-category handlers
│   ├── user/              # Userspace support (ELF loader, program mgmt, shell dispatch, demo payloads)
│   │   ├── demo/          # Demo ELF artifact builder (elf_builder)
│   │   └── shared/        # Shared shell/user runtime logic (ABI types, syscall wrappers, builtins)
│   └── util/              # Utility helpers (debug, formatting, crypto helpers)
├── tests/                 # Host-side integration tests (fs, io, memory, net, process, pyrofs, sync, syscall)
├── docs/                  # Architecture and subsystem documentation
├── Makefile               # Build, test, check, clippy, verification gates
├── Cargo.toml
├── build.rs               # Linker script selection
├── linker.ld              # x86_64 linker script
├── linker-aarch64.ld      # AArch64 linker script
└── linker-riscv64.ld      # RISC-V linker script
```

## Feature Flags

| Feature | Purpose |
|---------|---------|
| `demo-disk` | In-memory demo filesystem volumes, demo kernel workers, demo user programs |
| `fs_profiler` | Filesystem operation profiling counters |
| `net_profiler` | Network packet/throughput profiling counters |
| `alloc_profiler` | Kernel heap allocation profiling counters |
| `fault_profiler` | Page-fault profiling counters |
| `educational_networking` | Verbose debug logging in the network stack |

## Architecture Support

| Target | Boot Protocol | Status |
|--------|--------------|--------|
| `x86_64-unknown-none` | Multiboot2 (GRUB) / QEMU PVH | Full |
| `aarch64-unknown-none` | QEMU direct `-kernel` | Full |
| `riscv64gc-unknown-none-elf` | QEMU direct `-kernel` | Full |

All three run the same ring-3 programs.  RISC-V delivered skeleton support
longer than the other two — a fault terminated the process instead of running
the handler it installed, because `ReturnFromException` fell through
([RFC 0034](docs/rfcs/0034-deliver-a-user-exception-on-riscv64.md)) — and that
is closed: the demo payload now installs a store-page-fault handler, faults
into it, and resumes, and `make check-riscv64-runtime` fails a boot whose log
does not show all three steps.

## Documentation

- [`docs/kernel/`](docs/kernel/README.md) — how each subsystem works (boot,
  memory, process, filesystem, network, IPC, security, and the syscall and
  user-runtime boundaries).
- [`docs/status.md`](docs/status.md) — the per-module census: what exists,
  what is missing, what is reached only under QEMU.
- [`docs/fmts/`](docs/fmts/README.md) — the contributor specifications: code
  style, comments, `unsafe` discipline, testing, the syscall ABI contract, and
  commit messages.
- [`docs/rfcs/`](docs/rfcs/README.md) — design documents for changes too large
  to argue in a pull request, and the process that produces them.

## Contributing

All contributions are welcome — code, documentation, tests, issue reports, or
design discussion. Issues and PRs may be written in English or Simplified
Chinese. See:

- [CONTRIBUTING.md](CONTRIBUTING.md) — contribution guide (build, test, code style, syscall ABI rules)
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — code of conduct
- [SECURITY.md](SECURITY.md) — security policy & vulnerability reporting
- [ROADMAP.md](ROADMAP.md) — project roadmap
- [MAINTAINERS.md](MAINTAINERS.md) — maintainer list
- [NOTICE](NOTICE) — copyright notice

## License

[Apache-2.0](LICENSE)