soso

soso is a bare-metal x86_64 operating system written in Rust: own kernel, copy-on-write filesystem with checksums (sosofs), a second read-only disk for LLM models (sosomfs), real SSH, WiFi and Ethernet on real hardware, voice recognition, a minimal web browser, over-the-air updates, and a native NVIDIA GPU stack (L6). Single-user by design — one session at a time, no Unix permissions.

Use it in QEMU for development, on a live USB on real machines, or installed to NVMe with UEFI dual-boot alongside Linux.

End-user guide (Spanish): MANUAL-USUARIO.md

Operational docs (Spanish): docs/GUIA-OPERATIVA.md, docs/ESTADO.md. Hardware matrix: docs/HW-MATRIX.md.

At a glance

Area	What you get
Shell	sosh — pipes, redirections, cd/pwd, WiFi builtins, ask to the LLM
LLM	soso-llm + ask (resident daemon); models in /models/; MoE, MLA, Qwen, GPU offload
Models	soso-hf pulls GGUF from Hugging Face inside soso; host tools convert GGUF → .som
Voice	soso-voz / voz — Whisper ASR via mic or WAV; push-to-talk (F4)
Web	soso-web — HTTPS fetch, HTML→text or framebuffer GUI (no JavaScript)
Install	soso-install — clone live USB to NVMe from soso, no Linux required
Updates	soso-update — apply GitHub Releases (rootfs + kernel with rollback)
Network	DHCP, SSH-2, WiFi (Intel AX211/AX200), Realtek r8169 on live USB
GPU	lxdde + nouveau/nvkm; matvec on GB205; optional CUDA hybrid (L6-H)

Version: VERSION (e.g. 0.2.2); shown at boot and in /etc/soso-release.

Requirements

Tool	Purpose
rustup	Builds kernel and userspace (nightly pinned in rust-toolchain.toml; required because bootloader 0.11 uses -Zbuild-std)
qemu-system-x86_64	Run the VM (sudo apt install qemu-system-x86)
OpenSSH client + ssh-keygen	SSH access and integration tests
clang, zstd	Optional — lxdde GPU/NIC ports and NVIDIA firmware packing

Quick start

cargo xtask build          # compile kernel → target/soso-bios.img
cargo xtask check            # host tests + builds + iwl/GSP hostchecks + hw-matrix parser
cargo xtask run            # build + QEMU q35, serial console on stdio
cargo xtask gdb            # like run, frozen at boot; gdb -ex 'target remote :1234'
cargo xtask test           # integration: FS, boot, TCP, SSH, soso-llm, halt
cargo xtask fetch-hf       # host: Hugging Face → GGUF → .som
cargo xtask convert-gguf   # host: GGUF → .som layout
cargo xtask package-usb-live   # single GPT image for live USB / install
cargo xtask release        # pack release artifacts (manifest + rootfs.pack + kernel)

Live USB on real hardware:

cargo xtask flash-usb-live /dev/sdX --yes   # flash stick (picks best model that fits)
# incremental update (kernel+rootfs only, keeps models on p3):
sudo env "PATH=$PATH" "HOME=$HOME" cargo xtask flash-usb-live /dev/sdX --yes --skip-models

With soso running (cargo xtask run), in another terminal:

nc localhost 7777                                              # TCP echo
ssh -tt -i target/soso_test_key -p 2222 soso@localhost         # encrypted shell
ask hola                                                       # LLM via resident askd
soso-llm run tiny --prompt hola                                # one-shot LLM inference
soso-web --local /etc/web-prueba.html                          # minimal browser
soso-llm run tinyllama-q4km --cuda-host 10.0.2.2:11400 --prompt hola --max 32   # L6-H (host CUDA)

Exit QEMU: Ctrl-A X (not Ctrl-C). If port 2222 is busy: pkill qemu-system-x86 before restarting.

Guest network: DHCP at boot, fallback 10.0.2.15/24 in QEMU slirp. Port forwards: 2222→22 (SSH), 7777→7 (echo).

Project layout

Path	Role
kernel/	no_std kernel (x86_64-unknown-none, outside root workspace)
boot-shim/	UEFI shim: BOOTMARK, install/update mailbox, chainload
xtask/	Disk images, mkfs, QEMU, releases, integration tests
crates/	sosofs, sosomfs, soso-abi, soso-llm-core, soso-http, soso-update-core, soso-web-core, soso-audio, soso-gpu, …
tools/	mkfs-soso, mkfs-sosomfs, mkmodel-soso, convert-gguf, convert-whisper, cuda-proxy
user/	libsoso, init, sosh, soso-llm, soso-voz, soso-web, soso-hf, soso-update, soso-install, coreutils
rootfs/	Source tree embedded into the data disk — see rootfs/README.md
lxdde/	Linux-style DDE layer (lx_emul) for ported C drivers (e1000e, nouveau/nvkm, iwlwifi)
docs/	Architecture notes (L5c on-box, L6 GPU roadmap)

What is implemented

Kernel and platform (phases 0–10)

• Boot — BIOS/UEFI via bootloader 0.11, serial console, q35 + -cpu max
• Memory — GDT/TSS, IDT, PIC+PIT 100 Hz, frame allocator, buddy heap
• PCI — ECAM enumeration
• Block I/O — virtio-blk (data + models disks), NVMe, live GPT disk reader, USB mass storage + xHCI
• Filesystem — sosofs CoW B+ tree, CRC32C checksums, dual superblocks, commits on close() and periodic flush
• VFS — routes /models/* → sosomfs (read-only); everything else → sosofs
• Userspace — ring 3 ELF processes, preemptive round-robin scheduler, spawn (no fork)
• Syscalls — file I/O, mmap/munmap, pipe, spawn/spawn_io, chdir/getcwd, sleep, halt, futex, GPU ioctls
• Network — smoltcp TCP/IPv4, DHCP client, polled virtio-net (and optional lxdde e1000e NIC)
• SSH — sunset stack (curve25519, ed25519, chacha20-poly1305), single session, reconnectable, CRLF on remote tty
• Emergency kshell — serial diagnostic shell (soso>) if userspace exits

Shell and userspace

• sosh — pipes |, redirections >, >>, <, builtins cd/pwd/help/exit/wifi/ask/voz
• Per-process cwd — relative paths resolve against the process working directory
• Coreutils — ls, cat, echo, mkdir, rm, hexdump, halt
• init — PID 1, relaunches sosh; confirms kernel updates; init test runs syscall regression suite
• soso-voz — Whisper ASR daemon (vozd), mic capture (Intel HDA), push-to-talk
• soso-web — HTTPS client, HTML reflow or framebuffer GUI (fontdue + DejaVu)
• soso-hf — download/import GGUF models from Hugging Face Hub inside soso
• soso-install — native live→NVMe installer with GPT relayout and UEFI boot entry
• soso-update — OTA updates from GitHub Releases (rootfs pack + kernel slot with rollback)
• SIMD — userspace AVX2+FMA; FPU state preserved with xsave64 across context switches

LLM stack

• sosomfs — second virtio-blk disk, model shards under /models/<name>/
• .som format — manifest, index, tokenizer, quantized tensor shards (F32, Q8_0, Q4_K)
• soso-llm-core — full Llama-style pipeline: RoPE, GQA, SwiGLU, KV cache, greedy/temp/top-p sampling, streaming decode
• soso-llm — userspace CLI (run, askd, distributed node/worker modes)
• ask — sosh builtin; talks to resident askd on 127.0.0.1:7420 (quotes and UTF-8 safe)
• Host tools — cargo xtask convert-gguf, synthetic tiny/bench models via mkmodel-soso
• Custom models — SOSO_MODELS_DIR=<dir> cargo xtask run
• Distributed inference — multi-QEMU pipeline over socket netdev (cargo xtask test-distributed-llm)
• SMP benchmark — cargo xtask bench-llm (decode tok/s vs worker count)

Deployment, install and updates

• Classic USB package — cargo xtask package-usb (UEFI + separate data/models images)
• Live USB image — cargo xtask package-usb-live (single GPT stick: ESP + sosofs + sosomfs); see docs/L5c-on-box.md
• Flash live USB — sudo env "PATH=$PATH" "HOME=$HOME" cargo xtask flash-usb-live /dev/sdX --yes (auto-picks largest GGUF that fits)
• Native installer — soso-install from live stick: safety checks, block clone, GPT relayout, UEFI Boot#### via boot-shim
• OTA updates — soso-update from installed system; releases via cargo xtask release [--publish]
• Versioning — VERSION file → /etc/soso-release + kernel banner; semver compare in updates
• Dual-boot UEFI + Linux — sudo env "PATH=$PATH" "HOME=$HOME" cargo xtask install-disk /dev/nvmeXn1 --yes (host-side), or native install
• QEMU live mode — SOSO_QEMU_LIVE=1 cargo xtask run; install flow: cargo xtask test-install; update flow: cargo xtask test-update
• Persistent logs — cargo xtask sosolog reads SOSOLOG.TXT / SOSODRV.TXT from live ESP

lxdde and native GPU (L6 — G1→G5 GO on GB205)

Optional kernel feature (SOSO_LXDDE=1) linking a freestanding C library built from ported Linux driver code:

Port	Status
spike, testdrv	DDE plumbing validated
e1000e	Linux-style NIC backend (SOSO_QEMU_NIC=lx-e1000e)
nouveau	G5 GO on GB205 (GSP-FMC → RM → CE → SASS matvec in soso-llm); Ampere GA10x path written, untested

GPU syscalls: SYS_GPU_INFO, SYS_GPU_ALLOC, SYS_GPU_MAP, SYS_GPU_SUBMIT, SYS_GPU_READ. Firmware is packed into rootfs with ./scripts/l6-pack-firmware.sh.

L6 roadmap (G1→G5):

Gate	Deliverable	Status
G1	VFIO passthrough + BAR0 (NV_PMC_BOOT_0)	Done on real GB205 (0x1b5000a1)
G2	GSP firmware blobs in sosofs	Done (gb205 + ga102 reference set)
G3a	ELF validation, GEM staging	Done
G3b	Real GSP boot (FSP/COT, radix3, WPR, libos)	Done on GB205 HW
G4a–c	GSP-RM RPC + RM objects	Done on GB205 HW
G4d	VRAM + external VA space (VER3 page tables)	Done on GB205 HW (exercised by CE/compute)
G4e	GPFIFO channel + CE copy (gsp_chan, gsp_ce)	Done (2026-07-29): CE readback verificado (G4e GO)
G4f	SAXPY / matvec SASS (SYS_GPU_SUBMIT)	Done (2026-07-29): PCAS 24 B + QMD v05, on_gpu=1
G5	Hybrid LLM matvec on GPU	GO functional (2026-07-29): soso-llm run tiny → matvec on GPU; tok/s on large models still TBD
L6-H	CUDA inference on host Linux (--cuda-host)	GO (2026-07-27): ~35 tok/s via cuda-proxy + llama-server

Details: docs/L6-native-autonomy.md, docs/L6-G1-gate.md, docs/L6-G3-nvkm-scope.md, docs/L6-H-cuda-hybrid.md. Skill: .cursor/skills/soso-gpu/ (or .claude/skills/soso-gpu/).

Daily dev without releasing the GPU (driver stays on the host):

Step	Command
Hostcheck (~1 s)	./scripts/l6-g3-gsp-hostcheck.sh
Build nouveau	SOSO_LXDDE=1 SOSO_LXDDE_MODE=nouveau cargo xtask lx-build nouveau
Build soso	SOSO_LXDDE=1 SOSO_LXDDE_MODE=nouveau cargo xtask build
QEMU (no passthrough)	SOSO_LXDDE=1 SOSO_LXDDE_MODE=nouveau cargo xtask run
L6-H host stack	See docs/L6-H-cuda-hybrid.md

Build commands

Command	Action
cargo xtask mkfs	Force-regenerate sosofs data image from rootfs/
cargo xtask package-usb-live	Single GPT image (ESP + sosofs + sosomfs) for USB or install
sudo env "PATH=$PATH" "HOME=$HOME" cargo xtask flash-usb-live /dev/sdX --yes	Flash live USB (model sized to stick)
sudo env "PATH=$PATH" "HOME=$HOME" cargo xtask flash-usb-live /dev/sdX --yes --skip-models	Incremental: ESP + rootfs only (models unchanged)
cargo xtask release [--publish]	Pack release (manifest.txt, rootfs.pack, kernel-x86_64); --publish → GitHub Releases
cargo xtask test-install	E2E native install (OVMF, 3 boots)
cargo xtask test-update	E2E OTA: apply, kernel rollback on cut, invalid manifest
cargo xtask check	Pre-commit: host FS tests, builds, hostchecks, hw-matrix parser
cargo xtask hw-matrix show	Hardware validation matrix (A8)
cargo xtask sosolog [--drv]	Read SOSOLOG.TXT / SOSODRV.TXT from live USB ESP
sudo env "PATH=$PATH" "HOME=$HOME" cargo xtask install-disk /dev/nvmeXn1 --yes	Dual-boot: write live image to empty disk + GRUB entry
cargo xtask lx-build [port|all]	Build liblxdde.a (spike, testdrv, e1000e, nouveau)
cargo xtask g1-check	Host checklist: IOMMU/VFIO, firmware, BAR0
cargo xtask g3-check	GSP bring-up checklist (firmware, modules, phases)
cargo xtask bench-llm	Measure decode tok/s under configurable SMP
cargo xtask test-distributed-llm	Two-QEMU distributed LLM smoke test
./scripts/l6-pack-firmware.sh	Pack NVIDIA GSP firmware (.zst→.bin) into rootfs
./scripts/l6-g3-gsp-hostcheck.sh	GSP bring-up hostcheck (steps 3–6 + G4d–G4f encoders, no GPU)
./scripts/l6-h-start-cuda.sh	L6-H: llama-server (native) + cuda-proxy (requires llama-server in PATH)
./scripts/l6-g1-vfio-persist.sh	Persistent VFIO bind for iterative G1–G5 / VFIO cycles
./scripts/l6-g1-vfio-test.sh	Full VFIO cycle (PCIe Gen3 cap + Gen4/5 bump GO; see soso-gpu skill)

Useful environment variables:

SOSO_MODELS_DIR=/path/to/model     # custom .som tree on models disk
SOSO_QEMU_GPU=vfio:01:00.0       # GPU passthrough (requires IOMMU)
SOSO_LXDDE=1 SOSO_LXDDE_MODE=nouveau   # enable nouveau/nvkm port
SOSO_QEMU_LIVE=1                   # boot from live GPT image in QEMU
SOSO_QEMU_NIC=lx-e1000e            # use lxdde e1000e instead of virtio-net

Testing

Layer	Command
All host checks + builds	cargo xtask check
sosofs crash-safety (host)	cargo test -p sosofs --features std
sosomfs (host)	cargo test -p sosomfs --features std
OTA recovery (host)	cargo test -p soso-update-core --features std --tests
Syscall regression (guest)	/bin/init test in QEMU
Full system E2E	cargo xtask test
OTA E2E (OVMF)	cargo xtask test-update
USB/xHCI	cargo xtask test-usb
Native install E2E	cargo xtask test-install

cargo xtask test verifies: host FS tests, QEMU boot to sosh, TCP echo, SSH authenticated session, soso-llm run tiny, LLM shutdown cycles, and clean shutdown via halt. The suite should be fully green; investigate any failure.

Do not run sudo cargo — root lacks rustup. Use sudo env "PATH=$PATH" "HOME=$HOME" cargo xtask … for flash/install.

License

Copyright (C) 2026 Jose Miguel Díez de la Lastra Jimeno.

First-party soso code (kernel, crates, userspace, tools, xtask) is distributed under GNU General Public License v2.0 only (GPL-2.0-only). See COPYING.

Third-party components with their own licenses: THIRD_PARTY.md (including optional NVIDIA firmware under proprietary terms).