Skip to content

Commit 6eff76d

Browse files
Nathanclaude
Nathan
and
claude
committed
docs: rewrite README v0.11.0 — highlight March-April work for followers
New "What's New" section up front: AMD SDMA validated, HDA audio driver saga, Ring 3 userland, 6 hwdiag modules, ThinkPad EC, CoreMark 25K, security audit. Cleaned up GPU section (no internal tooling details). Version bump to v0.11.0. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 5cb150e commit 6eff76d

1 file changed

Lines changed: 97 additions & 96 deletions

File tree

‎README.md‎

Lines changed: 97 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -12,69 +12,107 @@
1212
[![Build](https://img.shields.io/badge/build-passing-brightgreen?style=for-the-badge)]()
1313
[![Rust](https://img.shields.io/badge/100%25%20Rust-F74C00?style=for-the-badge&logo=rust&logoColor=white)]()
1414
[![Architectures](https://img.shields.io/badge/arch-x86__64%20%7C%20ARM64%20%7C%20RISC--V-blueviolet?style=for-the-badge)]()
15-
[![Version](https://img.shields.io/badge/version-0.10.8-orange?style=for-the-badge)]()
15+
[![Version](https://img.shields.io/badge/version-0.11.0-orange?style=for-the-badge)]()
1616
[![License](https://img.shields.io/badge/license-Apache%202.0-blue?style=for-the-badge)](LICENSE)
17+
[![Lines](https://img.shields.io/badge/163K%2B%20lines-Rust-F74C00?style=for-the-badge)]()
1718
[![Author](https://img.shields.io/badge/created%20by-Nated0ge-ff69b4?style=for-the-badge&logo=github&logoColor=white)](https://github.com/nathan237)
1819

1920
---
2021

22+
</div>
23+
24+
## What's New (March–April 2026)
25+
26+
Since v0.10.1, TrustOS has seen **40 commits** and over **1.2 million lines of changes** across 2,000+ files. Here are the highlights.
27+
28+
### AMD GPU — SDMA Engine Validated on Real Hardware
29+
30+
<div align="center">
2131
<img src="win2.png" alt="GPU AMD SDMA OK" width="900"/>
32+
</div>
2233

23-
### AMD GPU WORKING: SDMA Polaris 10 (RX 580X) validated on TrustOS
34+
After weeks of bring-up work on an AMD RX 580X (Polaris 10), the **SDMA pipeline is running on bare metal**. Ring buffer allocated in GART, firmware responsive, read/write pointers advancing. The Graphics Memory Controller (L1/L2 TLB, system aperture, VM flat mode) was the missing piece — 14+ debug iterations on real hardware to track it down.
2435

25-
**Motherboard**: BTC-250PRO (Skylake, LGA1151)
26-
**GPU**: AMD RX 580X (Polaris 10, 1002:67DF)
27-
**SDMA**: RUNNING, GART ring, RPTR/WPTR OK, VRAM/GART mapping matches Linux
28-
**Debug**: MMIO mapping, full audit, SDMA test → success
29-
**Capture**: TrustOS Monitor v4, netconsole log, real hardware test
36+
**Hardware**: BTC-250PRO (Skylake), RX 580X via PCIe riser, entirely headless (UDP shell + PXE reboot).
3037

31-
> After weeks of reverse engineering, auditing, and hardware testing, the AMD SDMA pipeline is validated on TrustOS. RPTR/WPTR OK, GART ring, VRAM/GART mapping, sequence matches Linux.
38+
**Next**: CP/graphics ring, compute dispatch, GPU-accelerated JARVIS training.
3239

33-
**Next step:** compute acceleration, CP/graphics support, JARVIS GPU-native benchmarks.
40+
### Intel HDA Audio — From Silence to Sound
3441

35-
---
42+
We wrote a complete **Intel HD Audio driver** from scratch in `no_std` Rust. Tested on ThinkPad T61 with an AD1984 codec — a notoriously tricky chip.
3643

37-
</div>
44+
This was a 12-iteration debugging saga:
45+
- **Root cause**: amp gain bits were swapped in our register encoding — output amplifiers were never actually being set
46+
- GPIO polarity fix (T61 needs HIGH for amplifier power, not LOW)
47+
- Triangle wave i16 overflow causing audio tearing
48+
- Stream reset logic, full DAC configuration, codec dump tool
49+
- Gain range validation against hardware-reported amp capabilities
3850

39-
## What is TrustOS?
51+
Result: working audio output on real hardware, from a bare-metal OS, in pure Rust.
4052

41-
TrustOS is a bare-metal operating system that boots directly on real hardware — no Linux, no BIOS services, no runtime dependencies. Once running, it gives you complete visibility into your machine: every PCI device, every CPU register, every GPU engine, every ACPI table, every DIMM slot.
53+
### Ring 3 Userland (v0.10.5)
4254

43-
The core use case: **boot on any x86_64 machine (USB or PXE), and get a full hardware diagnostic report in seconds — remotely, over the network.**
55+
TrustOS now has a **protected userland**. Full Ring 3 integration with an 85-check conformance audit:
56+
- User-mode processes running in isolated address spaces
57+
- Syscall interface validated against expected behavior
58+
- Foundation for running untrusted code safely on bare metal
4459

45-
It ships with a Python remote monitor (`scripts/remote_screen.py`) that lets you see the screen and interact with the shell from any PC on the same network — no physical access required.
60+
### Hardware Diagnostic Suite — 6 New Modules (v0.10.4)
4661

47-
---
62+
The `hwdbg` toolkit now has **15+ subcommands** for deep hardware inspection:
4863

49-
## 🔥 Work in Progress — AMD GPU Bare-Metal Driver
64+
| Tool | What it does |
65+
|------|-------------|
66+
| `pciraw` | Raw PCI/PCIe config space hex dump (256B legacy / 4KB extended) |
67+
| `regdiff` | Register snapshot & bit-level diff (PCI, MSR, I/O ports) |
68+
| `ioscan` | I/O port range scanner (legacy devices, COM/UART, IDE controllers) |
69+
| `regwatch` | Live register monitor with automatic change detection |
70+
| `aer` | PCIe Advanced Error Reporting — scan, decode, clear |
71+
| `timing` | TSC-based boot profiling with per-subsystem checkpoint timeline |
5072

51-
We're building a **from-scratch AMD GPU driver** in pure `no_std` Rust — no Linux, no Mesa, no libdrm. Direct MMIO register control on real silicon.
73+
### ThinkPad EC Driver + CPU Frequency Control (v0.10.2)
5274

53-
**Hardware**: AMD RX 580X (Polaris 10, `1002:67DF`, 8 GB GDDR5) on a BTC-250PRO mining board via PCIe riser. All debugging done **headless** — UDP shell + netconsole + PXE reboot. No monitor, no keyboard.
75+
- Embedded Controller driver for ThinkPad laptops — fan control, thermal readout, battery status
76+
- CPU frequency scaling via MSR writes
77+
- Proves TrustOS runs and interacts with real laptop hardware, not just server boards
5478

55-
### Milestones
79+
### CoreMark Benchmark — 25,000 iter/sec
5680

57-
| What | Status | Proof |
58-
|------|--------|-------|
59-
| PCI enumeration & BAR decode | ✅ | GPU found, 6 BARs mapped (VRAM 256 MB, MMIO 512 KB, Doorbell 2 MB) |
60-
| MMIO register access | ✅ | Direct BAR5 reads/writes validated against Linux amdgpu source |
61-
| VRAM detection | ✅ | 8 GB GDDR5 from CONFIG_MEMSIZE, FB_LOCATION physical range parsed |
62-
| Graphics Memory Controller | ✅ | L1/L2 TLB, system aperture, VM flat mode, TLB invalidation |
63-
| Firmware loading | ✅ | SDMA0/1, PFP, ME, MEC microcode loaded via MMIO (no PSP on Polaris) |
64-
| SDMA ring buffer | ✅ | Ring allocated, firmware alive — IP_BUSY toggles confirm |
65-
| PSP bootstrap (Navi) | 🔧 | Bootloader protocol scaffolded (SOS, GPCOM, TMR) — needs real Navi HW |
66-
| Compute dispatch | 🔧 | PM4 packets + HQD init ready, pending ring validation |
67-
| GPU-accelerated AI | 📋 | INT8 GEMM (`V_DOT4_I32_I8`) across 36 CUs for JARVIS training |
81+
Added the industry-standard **EEMBC CoreMark** benchmark. TrustOS achieves **25,000 iterations/second** on bare metal (Intel G4400). A verifiable, comparable number that shows the kernel isn't just functional — it's performant.
6882

69-
### Key Discovery
83+
### Security Audit
7084

71-
After **14+ debug iterations**, the SDMA read pointer was stuck at 0. We systematically eliminated: PCIe riser effects, VT-d passthrough, doorbell ordering, HDP flush timing, VMID field widths, SAM bit positions, and more.
85+
Preemptive vulnerability fixes from a cross-OS security audit. Hardened before shipping, not after.
7286

73-
**Root cause**: the Graphics Memory Controller was never initialized — L1 TLB had system-access-mode disabled, so firmware couldn't resolve ring buffer addresses. Not a register bug, not a PCIe issue — it was the memory subsystem.
87+
---
7488

75-
### Goal
89+
## What is TrustOS?
7690

77-
Train JARVIS (4.4M-param byte-level transformer embedded in the kernel) directly on GPU compute units. No CPU fallback for matrix ops.
91+
TrustOS is a bare-metal operating system that boots directly on real hardware — no Linux, no BIOS services, no runtime dependencies. Once running, it gives you complete visibility into your machine: every PCI device, every CPU register, every GPU engine, every ACPI table, every DIMM slot.
92+
93+
The core use case: **boot on any x86_64 machine (USB or PXE), and get a full hardware diagnostic report in seconds — remotely, over the network.**
94+
95+
It ships with a Python remote monitor (`scripts/remote_screen.py`) that lets you see the screen and interact with the shell from any PC on the same network — no physical access required.
96+
97+
---
98+
99+
## AMD GPU Bring-Up — Milestones
100+
101+
From-scratch AMD GPU driver in pure `no_std` Rust — no Linux, no Mesa, no libdrm. Direct MMIO register control on real silicon.
102+
103+
| Milestone | Status |
104+
|-----------|--------|
105+
| PCI enumeration & BAR decode (VRAM 256 MB, MMIO 512 KB, Doorbell 2 MB) | Done |
106+
| MMIO register access — validated against Linux amdgpu source | Done |
107+
| VRAM detection — 8 GB GDDR5 from CONFIG_MEMSIZE | Done |
108+
| Graphics Memory Controller — L1/L2 TLB, system aperture, VM flat mode | Done |
109+
| Firmware loading — SDMA0/1, PFP, ME, MEC via MMIO | Done |
110+
| SDMA ring buffer — GART ring, RPTR/WPTR advancing | Done |
111+
| PSP bootstrap (Navi) — bootloader protocol scaffolded | In Progress |
112+
| Compute dispatch — PM4 packets, HQD init | In Progress |
113+
| GPU-accelerated AI — INT8 GEMM across 36 CUs for JARVIS | Planned |
114+
115+
**Key Discovery**: After 14+ iterations, SDMA's read pointer was stuck at 0. Root cause: the Graphics Memory Controller was never initialized — L1 TLB had system-access-mode disabled, so firmware couldn't resolve ring buffer addresses. Not a PCIe issue, not a register bug — the memory subsystem.
78116

79117
---
80118

@@ -87,16 +125,16 @@ TrustOS probes hardware at the register level. No abstraction layers between you
87125
| **PCI Bus** | Full enumeration: vendor/device IDs, class, BARs, capability chains (MSI, PCIe, PM), bus mastering |
88126
| **CPU** | CPUID all leaves, brand string, feature flags (SSE/AVX/AES), family/model/stepping, MSR scan |
89127
| **SMBIOS/DMI** | Board manufacturer, BIOS version, DIMM slots (size/speed/type), chassis, serials |
90-
| **ACPI** | RSDP → XSDT walk, all tables (MADT, FADT, HPET, MCFG, SSDT), raw hex dump |
128+
| **ACPI** | RSDP -> XSDT walk, all tables (MADT, FADT, HPET, MCFG, SSDT), raw hex dump |
91129
| **AMD GPU** | MMIO registers, GRBM status, SDMA engine state, VRAM size, memory controller config |
92130
| **NVIDIA GPU** | PMC/PBUS registers, GPU identity, diagnostic dump |
131+
| **Intel HDA** | Codec enumeration, widget tree, amplifier capabilities, pin configuration |
132+
| **ThinkPad EC** | Fan speed, thermal sensors, battery, embedded controller registers |
93133
| **Memory Map** | Full UEFI memory map: type, physical range, page count |
94-
| **Boot Timing** | TSC-based per-subsystem boot profiling (µs precision) |
134+
| **Boot Timing** | TSC-based per-subsystem boot profiling (us precision) |
95135
| **Network** | NIC detection, MAC address, PCI config |
96136
| **Storage** | NVMe/AHCI controller detection, BAR decode |
97137

98-
**Running on real hardware (Intel G4400 + AMD RX 580X, BTC-250PRO LR):**
99-
100138
<img src="media/screenshots/hwdbg_real_hardware.jpg" alt="TrustOS hardware diagnostic on real hardware" width="720"/>
101139

102140
*CPUID full decode, CPU registers dump — bare-metal framebuffer output.*
@@ -107,34 +145,6 @@ TrustOS probes hardware at the register level. No abstraction layers between you
107145

108146
---
109147

110-
## Build Your Own Tools
111-
112-
TrustOS gives you **direct register access** and a **shell framework**. From there — you build whatever diagnostics you need.
113-
114-
The project ships the primitives, not a fixed toolkit:
115-
116-
- **MMIO helpers** — Read/write any GPU register by offset. BAR mapping is done for you.
117-
- **PCI config space** — Full access to any device: config registers, capability chains, BAR decode.
118-
- **Shell commands** — Add a command in `kernel/src/shell/`, it's live at next boot.
119-
- **Netconsole** — Every `serial_println!()` streams to UDP 6666. Pipe debug output to any host.
120-
- **Remote shell** — Commands via UDP 7777. Automate with Python scripts.
121-
- **PXE boot** — Edit → rebuild → copy to TFTP → remote reboot. Full cycle under 60 seconds.
122-
123-
**Example** — probe a GPU register:
124-
125-
```rust
126-
// In your shell command handler:
127-
let mmio = gpu_state.mmio_base; // Already mapped
128-
let val = unsafe { core::ptr::read_volatile((mmio + 0x2004) as *const u32) };
129-
serial_println!("GRBM_STATUS2: {:#010x}", val);
130-
```
131-
132-
No ioctl, no syscall, no permission model — you're in ring 0, talking to silicon.
133-
134-
We built our own GPU diagnostic toolkit this way during the RX 580X bring-up. You can build yours for any hardware TrustOS sees.
135-
136-
---
137-
138148
## Remote Monitor
139149

140150
TrustOS streams its framebuffer over UDP and accepts shell commands remotely:
@@ -151,7 +161,7 @@ python scripts/remote_screen.py --ip 10.0.0.110 --interval 2
151161

152162
<img src="media/screenshots/monitor_gpu_init.png" alt="TrustOS Monitor showing live GPU init" width="720"/>
153163

154-
*Monitor v3.0 — AMD GPU init streamed over UDP netconsole in real time.*
164+
*Monitor v3.0 — GPU init streamed over UDP netconsole in real time.*
155165

156166
---
157167

@@ -170,7 +180,7 @@ Type `help` for all commands. `hwdbg auto` dumps CPU + memory + PCI + SMBIOS in
170180
### Bare Metal (USB)
171181

172182
1. Download ISO from [**Releases**](https://github.com/nathan237/TrustOS/releases)
173-
2. Flash with [**Rufus**](https://rufus.ie/) → **DD Image mode**
183+
2. Flash with [**Rufus**](https://rufus.ie/) — **DD Image mode**
174184
3. Boot (F12 / DEL). Works on **UEFI** and **Legacy BIOS**.
175185

176186
### PXE Network Boot
@@ -201,15 +211,17 @@ Tested on: ThinkPad T61, BTC-250PRO LR (mining board), QEMU/VirtualBox.
201211
TrustOS/
202212
kernel/src/
203213
main.rs — Entry point (Limine boot protocol)
204-
drivers/ — AMD GPU (Polaris/Navi), NVIDIA, RTL8139/8169, AHCI, XHCI
214+
drivers/ — AMD GPU (Polaris/Navi), NVIDIA, Intel HDA, ThinkPad EC
205215
netstack/ — TCP/IP, UDP, ARP, DHCP, DNS, IPv6
206216
memory/ — Physical frame allocator, paging, heap
207217
interrupts/ — IDT, APIC, exception handlers
208218
shell/ — 200+ commands (hwdbg, pci, gpu, sensors, etc.)
219+
hwdiag/ — Hardware diagnostic modules (pciraw, regdiff, ioscan, aer, timing...)
209220
jarvis/ — JARVIS AI (4.4M-param transformer, guardian system)
210221
framebuffer/ — Rendering, POST codes
211-
scheduler/ — Process scheduler
222+
scheduler/ — Process scheduler, Ring 3 userland
212223
vfs/ — Virtual filesystem
224+
userland/ — Ring 3 processes, syscall interface
213225
scripts/
214226
remote_screen.py — Remote monitor (screencap + input injection)
215227
pxe_server.py — DHCP + TFTP for PXE boot
@@ -231,32 +243,21 @@ Requires: Rust nightly, `x86_64-unknown-none` target, `llvm-tools-preview`.
231243

232244
## Changelog
233245

234-
### v0.10.8 — AMD GPU Memory Controller & SDMA Bring-up (April 5, 2026)
235-
236-
- **GMC init** — Full Polaris Graphics Memory Controller: L1/L2 TLB, system aperture, VM flat mode. Root cause of SDMA hang identified and fixed.
237-
- **SDMA engine alive** — Ring buffer operational on real hardware (RX 580X). Firmware responsive.
238-
- **14+ debug iterations** — Systematic elimination on real hardware: PCIe, TLB, doorbell, HDP, VMID.
239-
- **Compute pipeline** — PM4 packet builders, hardware queue descriptors, shader agent framework.
240-
- **Remote GPU bring-up** — Entire driver development done headless via UDP + PXE.
241-
242-
### v0.10.7 — AMD PSP Driver & Boot Timing (March 25, 2026)
243-
244-
- **PSP driver** — Platform Security Processor bootloader interface for Navi10 GPUs.
245-
- **Firmware pipeline** — Polaris direct MMIO path, Navi10 PSP path, staged init.
246-
- **Boot timing** — TSC-based `boot_timing!` macro, µs precision per subsystem.
247-
248-
### v0.10.6 — Remote Desktop & Hardware Drivers (March 24, 2026)
246+
### v0.11.0 — Audio, Userland, GPU, Benchmarks (April 2026)
249247

250-
- **Remote desktop** — Input injection, screencap streaming, remote ACPI reboot.
251-
- **NIC drivers** — RTL8139/RTL8169 rewritten, hardware-tested.
252-
- **Visual POST codes** — Boot progress on framebuffer.
253-
- **GPU init hardening** — Deferred init prevents network driver conflicts.
248+
- **AMD SDMA validated** — Ring buffer running on RX 580X, GMC fully initialized, firmware responsive
249+
- **Intel HDA audio** — Complete driver for AD1984 codec, 12-iteration debug to working audio on ThinkPad T61
250+
- **Ring 3 userland** — Protected user-mode processes, 85-check conformance audit
251+
- **Hardware diagnostics** — 6 new modules (pciraw, regdiff, ioscan, regwatch, aer, timing), 15+ hwdbg subcommands
252+
- **ThinkPad EC** — Embedded Controller driver, fan/thermal/battery readout, CPU frequency control
253+
- **CoreMark** — 25,000 iter/sec on bare metal (EEMBC standard benchmark)
254+
- **Security** — Preemptive fixes from cross-OS vulnerability audit
255+
- **CI** — Fixed `build-std` compatibility with rust-src component
254256

255-
### v0.10.5 — Hypervisor & Userland (March 20, 2026)
257+
### v0.10.1 — Settings GUI & Network (March 13, 2026)
256258

257-
- **AMD SVM** — VMCB, NPT, unified backend with Intel VT-x.
258-
- **Ring 3 userland** — 104 Linux-compatible syscalls, ELF64 loader, COW fork, signals, pipes.
259-
- **VirtIO** — Stable virtio-blk and virtio-console.
259+
- Settings GUI, NetScan GUI, shell scrollback fix, ACPI shutdown hardening
260+
- T61 hardware optimization, matrix rain, GitHub Pages site
260261

261262
---
262263

@@ -268,4 +269,4 @@ Apache 2.0 — see [LICENSE](LICENSE).
268269

269270
## AI Disclosure
270271

271-
This project was built with AI assistance (GitHub Copilot). All code is reviewed and understood by the author. No generated code is shipped without verification.
272+
This project was built with AI assistance (GitHub Copilot, Claude). All code is reviewed and understood by the author. No generated code is shipped without verification.

0 commit comments

Comments
 (0)