docs

litecreator · litecreator · commit cabc5d124323 · 2026-02-20T19:10:15.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,22 @@ All notable changes to the XDV Kernel are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-02-20
+
+### Added
+
+- Added `docs/` documentation set:
+  - `docs/README.md`
+  - `docs/boot_runtime_flow.md`
+  - `docs/sector_reference.md`
+
+### Changed
+
+- Refreshed `README.md` to align with current repository behavior:
+  - clarified kernel runtime entry profiles (`kernel.ds` and `kernel_runtime_shell.asm`),
+  - clarified integration contract with `xdv-boot` and `xdv-os`,
+  - updated documentation and related-project references.
+
 ## [0.2.0] - 2026-02-12 (DPL v0.2)
 
 ### Added
@@ -78,4 +94,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-Copyright © 2026 Dust LLC
+Copyright © 2026 Dust LLC
diff --git a/README.md b/README.md
@@ -1,117 +1,56 @@
-# XDV Kernel v0.2
+# XDV Kernel
 
-A Cross-Domain Virtualizer operating system kernel for x86-64, written entirely in the Dust Programming Language (DPL).
+Version: 0.2.x  
+Language: Dust Programming Language (DPL)
 
-For `xdv-os` bare-metal image boot/runtime, the kernel sector also provides
-`sector/xdv_kernel/src/kernel_runtime_shell.asm`, which implements the runtime
-keyboard (US layout), command buffer, and builtin shell dispatch profile used by VirtualBox validation.
+The XDV kernel is the x64 kernel component for XDV OS. It provides the
+K-Domain runtime and defines hardware-gated Q-Domain and Phi-Domain service
+surfaces.
 
-## Overview
+## Runtime Paths
 
-XDV v0.2 is a multi-domain operating system kernel that supports three computational domains:
+The repository currently contains two kernel runtime entry profiles:
 
-- **K-Domain (Classical)**: Traditional von Neumann computing on x64 (FULL SUPPORT)
-- **Q-Domain (Quantum)**: Hardware-gated quantum services (returns ERR_DOMAIN_NOT_AVAILABLE when unavailable)
-- **Φ-Domain (Phase-Native)**: Hardware-gated phase services (returns ERR_DOMAIN_NOT_AVAILABLE when unavailable)
+- `sector/xdv_kernel/src/kernel.ds`  
+  Dust kernel entry (`kernel_start`) and core runtime boot sequence.
+- `sector/xdv_kernel/src/kernel_runtime_shell.asm`  
+  bare-metal runtime shell profile (US keyboard layout, command buffer,
+  dispatcher, and console command execution path used in VM bring-up flows).
 
-The kernel runs on classical x86-64 hardware with full K-Domain functionality.
+## Domain Model
 
-## Dependencies
+- `K-Domain`: classical x64 execution path (active on supported hardware).
+- `Q-Domain`: hardware-gated quantum domain interfaces.
+- `Phi-Domain`: hardware-gated phase-native interfaces.
 
-- **dustlib**: Core types (Result, Option, Str)
-- **dustlib_k**: Memory allocation, threading, I/O operations
+When Q/Phi hardware is not present, domain probes and operations are expected
+to report domain-not-available behavior.
 
-## Kernel Sectors
+## Sectors
 
-The kernel is organized into 13 sectors:
+The workspace defines 13 sectors:
 
-| Sector | Purpose | Status |
-|--------|---------|--------|
-| `xdv_boot` | Boot and early initialization | ✅ |
-| `xdv_memory` | Physical and virtual memory management | ✅ |
-| `xdv_cpu` | CPU management, interrupts, exceptions | ✅ |
-| `xdv_drivers` | Device drivers (VGA, keyboard, storage, network) | ✅ |
-| `xdv_kernel` | Core kernel functionality and main loop | ✅ |
-| `xdv_dal` | Domain Abstraction Layer - unified domain interfaces | ✅ |
-| `xdv_qdomain` | Quantum domain subsystem (hardware-gated) | ✅ |
-| `xdv_phidomain` | Phase-Native domain subsystem (hardware-gated) | ✅ |
-| `xdv_cds` | Cross-Domain Scheduler | ✅ |
-| `xdv_umf` | Unified Memory Fabric | ✅ |
-| `xdv_hypervisor` | Domain Hypervisor | ✅ |
-| `xdv_sdbm` | Secure Domain Boundary Manager | ✅ |
-| `xdv_odt` | Observability & Deterministic Trace Layer | ✅ |
+- `xdv_boot`
+- `xdv_memory`
+- `xdv_cpu`
+- `xdv_drivers`
+- `xdv_kernel`
+- `xdv_dal`
+- `xdv_qdomain`
+- `xdv_phidomain`
+- `xdv_cds`
+- `xdv_umf`
+- `xdv_hypervisor`
+- `xdv_sdbm`
+- `xdv_odt`
 
-## Directory Structure
+Each sector contains `src/*.ds` and sector tests (`*_tests.ds`).
 
-```
-xdv-kernel/
-├── State.toml
-├── README.md
-├── LICENSE
-├── sector/
-│   ├── xdv_boot/           # Boot sector
-│   │   ├── boot.ds
-│   │   └── boot_tests.ds
-│   ├── xdv_memory/        # Memory management
-│   │   ├── memory.ds
-│   │   └── memory_tests.ds
-│   ├── xdv_cpu/          # CPU management
-│   │   ├── cpu.ds
-│   │   └── cpu_tests.ds
-│   ├── xdv_drivers/     # Device drivers
-│   │   ├── drivers.ds
-│   │   └── drivers_tests.ds
-│   ├── xdv_kernel/      # Core kernel
-│   │   ├── kernel.ds
-│   │   ├── kernel_runtime_shell.asm
-│   │   └── kernel_tests.ds
-│   ├── xdv_dal/         # Domain Abstraction Layer
-│   │   ├── dal.ds
-│   │   └── dal_tests.ds
-│   ├── xdv_qdomain/     # Quantum domain (hardware-gated)
-│   │   ├── qdomain.ds
-│   │   └── qdomain_tests.ds
-│   ├── xdv_phidomain/   # Phase-native domain (hardware-gated)
-│   │   ├── phidomain.ds
-│   │   └── phidomain_tests.ds
-│   ├── xdv_cds/         # Cross-Domain Scheduler
-│   │   ├── cds.ds
-│   │   └── cds_tests.ds
-│   ├── xdv_umf/         # Unified Memory Fabric
-│   │   ├── umf.ds
-│   │   └── umf_tests.ds
-│   ├── xdv_hypervisor/  # Domain Hypervisor
-│   │   ├── hypervisor.ds
-│   │   └── hypervisor_tests.ds
-│   ├── xdv_sdbm/        # Secure Domain Boundary Manager
-│   │   ├── sdbm.ds
-│   │   └── sdbm_tests.ds
-│   └── xdv_odt/         # Observability & Trace
-│       ├── odt.ds
-│       └── odt_tests.ds
-```
-
-## Domain Support
-
-### K-Domain (Classical) - FULL
-Traditional computing on x86-64 architecture with full kernel support:
-- Process scheduling and management
-- Virtual memory with page tables
-- Device I/O
-- System calls
+## Build and Validation
 
-### Q-Domain (Quantum) - HARDWARE GATED
-Operations return ERR_DOMAIN_NOT_AVAILABLE (100) when quantum hardware is not detected.
-- Check availability: `q_available()` returns 0
-
-### Φ-Domain (Phase-Native) - HARDWARE GATED
-Operations return ERR_DOMAIN_NOT_AVAILABLE (100) when phase-native hardware is not detected.
-- Check availability: `phi_available()` returns 0
-
-## Building
+Validate all sector source directories:
 
 ```bash
-# Check all kernel sectors
 dust check sector/xdv_boot/src
 dust check sector/xdv_memory/src
 dust check sector/xdv_cpu/src
@@ -127,60 +66,29 @@ dust check sector/xdv_sdbm/src
 dust check sector/xdv_odt/src
 ```
 
-## CI/CD
-
-The kernel uses GitHub Actions for continuous integration:
-
-```yaml
-# .github/workflows/ci.yml
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Clone dust compiler
-        run: git clone --depth 1 https://github.com/dustlang/dust.git ../dust
-      - name: Build Dust compiler
-        run: cd ../dust && cargo build --workspace
-      - name: Check all kernel sectors
-        run: |
-          for sector in xdv_boot xdv_memory xdv_cpu xdv_drivers xdv_kernel xdv_dal xdv_qdomain xdv_phidomain xdv_cds xdv_umf xdv_hypervisor xdv_sdbm xdv_odt; do
-            dust check "sector/$sector/src"
-          done
-```
+## Integration Notes
 
-## Features
+- `xdv-boot` is responsible for loading `kernel.bin` and transferring control.
+- `xdv-os` image build composes `boot.bin` + `kernel.bin` into the xdvfs image.
+- kernel runtime output should be validated in VirtualBox against the expected
+  boot contract chain.
 
-### Memory Management
-- Physical memory allocator (buddy system)
-- Virtual memory with page tables
-- Domain-specific memory protections
-- Unified Memory Fabric
-
-### Cross-Domain Scheduling
-- Unified scheduler for K, Q, and Φ domains
-- Priority-based and round-robin scheduling
-- Coherence-aware scheduling
-
-### Security
-- Capability-based access control
-- Domain isolation enforcement
-- Cross-domain message validation
-
-### Observability
-- Domain-specific telemetry collection
-- System health monitoring
-- Deterministic tracing
-
-## Related Components
+## Documentation
 
-- [xdv-boot](../xdv-boot) - Bootloader
-- [xdv-xdvfs](../xdv-xdvfs) - Native file system
+- `docs/README.md`
+- `docs/boot_runtime_flow.md`
+- `docs/sector_reference.md`
+- `spec/XDV-Kernel-v0.2-Specification.md`
+- `xdv-kernel_white_paper.md`
+- `CHANGELOG.md`
 
-## Documentation
+## Related Projects
 
-- [Specification](./spec/XDV-Kernel-v0.2-Specification.md) - Full kernel specification
+- [xdv-os](../xdv-os)
+- [xdv-boot](../xdv-boot)
+- [xdv-runtime](../xdv-runtime)
+- [xdv-xdvfs](../xdv-xdvfs)
 
 ## License
 
-Copyright © 2026 Dust LLC - See LICENSE file
+Copyright (c) 2026 Dust LLC. See `LICENSE`.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,14 @@
+# XDV Kernel Docs
+
+This directory documents current `xdv-kernel` behavior and integration
+contracts.
+
+## Files
+
+- `boot_runtime_flow.md`: kernel boot/runtime flow and handoff contract.
+- `sector_reference.md`: sector-by-sector source map.
+
+For broader architecture and rationale, also see:
+
+- `../xdv-kernel_white_paper.md`
+- `../spec/XDV-Kernel-v0.2-Specification.md`
diff --git a/docs/boot_runtime_flow.md b/docs/boot_runtime_flow.md
@@ -0,0 +1,58 @@
+# Boot and Runtime Flow
+
+This document describes the current kernel runtime flow used in XDV OS bring-up.
+
+## Boot Contract Boundary
+
+1. `xdv-os` stage0 loads `boot.bin`.
+2. `xdv-boot` locates and loads `kernel.bin`.
+3. `xdv-boot` transfers control to kernel entry.
+4. `xdv-kernel` starts runtime path.
+
+`xdv-kernel` assumes loader handoff is complete and begins kernel/runtime
+initialization from its entry profile.
+
+## Kernel Entry Profiles
+
+## Dust entry (`kernel.ds`)
+
+- File: `sector/xdv_kernel/src/kernel.ds`
+- Primary routine: `kernel_start()`
+- High-level steps:
+  1. print boot/banner messages,
+  2. apply boot contract initialization hooks,
+  3. load runtime bridge,
+  4. start userspace bootstrap,
+  5. enter kernel main loop.
+
+## Bare-metal shell profile (`kernel_runtime_shell.asm`)
+
+- File: `sector/xdv_kernel/src/kernel_runtime_shell.asm`
+- Provides:
+  - VGA console output path,
+  - PS/2 keyboard input (US layout, set-1 mapping),
+  - command line buffer parsing,
+  - shell command dispatch for xdv-shell, xdv-core, and xdv-xdvfs-utils
+    bring-up command sets,
+  - runtime status/metrics output used during VM validation.
+
+## Runtime Signals
+
+The kernel/runtime log stream includes:
+
+- loader handoff confirmation,
+- kernel initialization banner and build date,
+- runtime bridge and userspace bootstrap status,
+- shell bridge/dispatcher status when shell path is active.
+
+## Validation
+
+Recommended checks:
+
+```bash
+dust check sector/xdv_kernel/src
+dust check sector/xdv_memory/src
+dust check sector/xdv_cpu/src
+```
+
+and integration boot validation through the `xdv-os` build and VM run path.
diff --git a/docs/sector_reference.md b/docs/sector_reference.md
@@ -0,0 +1,51 @@
+# Sector Reference
+
+The kernel workspace is split into sectors under `sector/`.
+
+## Core sectors
+
+- `sector/xdv_boot/src/boot.ds`
+  - early boot/kernel bootstrap sector logic.
+- `sector/xdv_kernel/src/kernel.ds`
+  - kernel top-level start path and runtime initialization.
+- `sector/xdv_kernel/src/kernel_runtime_shell.asm`
+  - bare-metal runtime shell command/input path.
+
+## Platform/runtime sectors
+
+- `sector/xdv_memory/src/memory.ds`
+  - memory model interfaces.
+- `sector/xdv_cpu/src/cpu.ds`
+  - CPU/interrupt model interfaces.
+- `sector/xdv_drivers/src/drivers.ds`
+  - core driver abstraction and bring-up interfaces.
+
+## Cross-domain sectors
+
+- `sector/xdv_dal/src/dal.ds`
+  - domain abstraction layer.
+- `sector/xdv_qdomain/src/qdomain.ds`
+  - Q-Domain model and hardware-gated interfaces.
+- `sector/xdv_phidomain/src/phidomain.ds`
+  - Phi-Domain model and hardware-gated interfaces.
+- `sector/xdv_cds/src/cds.ds`
+  - cross-domain scheduler model.
+- `sector/xdv_umf/src/umf.ds`
+  - unified memory fabric model.
+- `sector/xdv_hypervisor/src/hypervisor.ds`
+  - domain hypervisor model.
+- `sector/xdv_sdbm/src/sdbm.ds`
+  - secure domain boundary management model.
+- `sector/xdv_odt/src/odt.ds`
+  - observability and deterministic trace model.
+
+## Tests
+
+Each sector includes matching test modules, for example:
+
+- `sector/xdv_kernel/src/kernel_tests.ds`
+- `sector/xdv_memory/src/memory_tests.ds`
+- `sector/xdv_cpu/src/cpu_tests.ds`
+
+Use `dust check` over each sector `src` directory to validate parser/type
+coverage in CI and local workflows.
