diff --git a/config/redbear-mini.toml b/config/redbear-mini.toml index 6baff02e0c..ecb18239c6 100644 --- a/config/redbear-mini.toml +++ b/config/redbear-mini.toml @@ -610,3 +610,4 @@ cmd = "ptyd" # stack). See ptyd/src/main.rs: it is on the SchemeDaemon/ready_with_fd path. type = { scheme = "pty" } """ + diff --git a/docs/01-REDOX-ARCHITECTURE.md b/docs/01-REDOX-ARCHITECTURE.md index 949383b871..3331fb8c39 100644 --- a/docs/01-REDOX-ARCHITECTURE.md +++ b/docs/01-REDOX-ARCHITECTURE.md @@ -143,6 +143,12 @@ usbhidd (USB HID), inputd (input multiplexor) ## 4. Orbital Display Server +> **Note (2026-07-20):** Orbital is Redox's *reference* display server, documented here as +> architecture background. It is **not** Red Bear's desktop direction — Red Bear targets a +> Wayland compositor path (KWin) on top of DRM/KMS. See +> `../local/docs/CONSOLE-TO-KDE-DESKTOP-PLAN.md` for the canonical desktop plan and +> `../local/docs/WAYLAND-IMPLEMENTATION-PLAN.md` for the Wayland subsystem path. + Orbital is Redox's display server, window manager, and compositor — all in one userspace daemon. ### Window Creation (via Scheme) diff --git a/docs/06-BUILD-SYSTEM-SETUP.md b/docs/06-BUILD-SYSTEM-SETUP.md index bb4b44bc3c..de247064ba 100644 --- a/docs/06-BUILD-SYSTEM-SETUP.md +++ b/docs/06-BUILD-SYSTEM-SETUP.md @@ -60,6 +60,13 @@ sudo apt-get install --assume-yes \ xdg-utils xxd zip zstd qemu-system-x86 qemu-kvm ``` +> **QEMU test harnesses:** the login-based QEMU proof scripts drive the guest over its +> serial console. Most still use the host `expect` package (listed above). The low-level +> controller proofs (`test-ps2-qemu.sh`, `test-timer-qemu.sh`, `test-iommu-qemu.sh`, +> `test-usb-storage-qemu.sh`) and a growing set of runtime proofs instead use +> `local/scripts/qemu-login-expect.py`, a standard-library-only Python replacement that +> needs no `expect` install. The system `expect` package remains required for the rest. + #### Fedora ```bash diff --git a/local/docs/LOCAL-FORK-SUPREMACY-POLICY.md b/local/docs/LOCAL-FORK-SUPREMACY-POLICY.md index b5ed5bcad0..eb6c43772c 100644 --- a/local/docs/LOCAL-FORK-SUPREMACY-POLICY.md +++ b/local/docs/LOCAL-FORK-SUPREMACY-POLICY.md @@ -239,7 +239,7 @@ For relibc/redox-rt specifically: ## Related Documents - `local/AGENTS.md` — full Red Bear agent guidance (branches, submodules, durability) -- `local/docs/archived/archived/SOURCE-ARCHIVAL-POLICY.md` — how sources are frozen and archived +- `AGENTS.md` (repo root) § RELEASE MODEL — how sources are frozen and archived - `local/docs/PATCH-GOVERNANCE.md` (referenced in `local/AGENTS.md`) — how patches are rebased and applied - `README.md` (project root) — high-level description including the fork model \ No newline at end of file diff --git a/local/docs/SYSTEM-STABILITY-AND-UPSTREAM-SYNC-PLAN.md b/local/docs/SYSTEM-STABILITY-AND-UPSTREAM-SYNC-PLAN.md index 5a11c06313..38dba8c8c1 100644 --- a/local/docs/SYSTEM-STABILITY-AND-UPSTREAM-SYNC-PLAN.md +++ b/local/docs/SYSTEM-STABILITY-AND-UPSTREAM-SYNC-PLAN.md @@ -3,7 +3,13 @@ **Date:** 2026-07-08 **Branch:** 0.3.1 **Source of truth:** Linux kernel 7.1 (`local/reference/linux-7.1/`) -**Status:** Authoritative — Phase 1 COMPLETE (2026-07-08 verification), Phase 2 partially done +**Status:** Historical plan — Phase 1 COMPLETE (2026-07-08), Phase 2 partially done, +Phase 3.1 upstream sync COMPLETE (2026-07-19: all 9 forks pass +`verify-fork-functions.sh`; base/kernel/relibc hand-merged onto latest upstream, +see `local/docs/fork-push-status/`). Sections describing Phase 1 WIP states +(32 uncommitted changes, prefix staleness detection, version drift to +rb0.3.1) +are resolved and retained for history. Current stability work is tracked in +`CONSOLE-TO-KDE-DESKTOP-PLAN.md` and the subsystem plans. ## Relationship to Other Plans diff --git a/local/docs/UPSTREAM-SYNC-PROCEDURE.md b/local/docs/UPSTREAM-SYNC-PROCEDURE.md index 1956732ce6..5ab1825afe 100644 --- a/local/docs/UPSTREAM-SYNC-PROCEDURE.md +++ b/local/docs/UPSTREAM-SYNC-PROCEDURE.md @@ -714,21 +714,36 @@ This applies to: - Build system patches and scripts - Any file under `local/` or `config/redbear-*` -### driver-manager: Upstream Not Ready +### driver-manager: Deferred (consolidated onto pcid-spawner, 2026-07-20) -**Status:** Red Bear internal project. Upstream Redox does NOT have an equivalent. +**Status:** Red Bear internal project, currently **deferred**. Upstream Redox +does NOT have an equivalent. `driver-manager` (`local/recipes/system/driver-manager/`) is a combined PCI -enumeration + driver matching + hotplug daemon that replaces the upstream -`pcid + pcid-spawner` pair. It was developed because upstream's PCI driver -launching was not ready for Red Bear's needs (advanced driver matching via -`/lib/drivers.d/*.toml`, ACPI device enumeration, hotplug event handling). +enumeration + driver matching + hotplug daemon intended to eventually replace +the upstream `pcid + pcid-spawner` pair. It was developed because upstream's +PCI driver launching was not ready for Red Bear's needs (advanced driver +matching via `/lib/drivers.d/*.toml`, ACPI device enumeration, hotplug event +handling). + +**As of 2026-07-20 (Task 3 consolidation), PCI driver spawning is consolidated +on `pcid-spawner`.** The driver-manager migration was stalled: it was written +and packaged, but never actually wired in — its `00_driver-manager.service` +ran `cmd="pcid-spawner"` (the legacy binary), while the base recipe's +`00_pcid-spawner.service` (`oneshot_async`) was the live spawner. Both +services launched `pcid-spawner` asynchronously, so `pcid-spawner` started +TWICE and raced to spawn the same drivers. The consolidation dropped the +unused `driver-manager = {}` package and the duplicate +`00_driver-manager.service`, and pointed `13_driver-params.service` +`requires_weak` at `00_pcid-spawner.service`. The driver-manager recipe +source is kept for the future migration. **Upstream may provide its own solution in the future.** If and when upstream Redox offers a concrete, working replacement that matches or exceeds -driver-manager's capabilities, notify the user for a route decision. - -Until then, `driver-manager` is the canonical PCI driver orchestration path. +driver-manager's capabilities — or when Red Bear completes the driver-manager +migration — notify the user for a route decision. Until then, `pcid-spawner` +(the base recipe's `00_pcid-spawner.service`, `oneshot_async`) is the sole +PCI driver spawner. ### Systemic Sync Flaw (2026-06 Incident) @@ -759,12 +774,14 @@ were silently dropped because upstream doesn't have them. 1. `pcid` creates `/scheme/pci` (PCI bus enumeration) 2. `pcid-spawner` reads `/scheme/pci` and launches drivers per `pcid.d/*.toml` -**Red Bear model (0.2.3 and forward):** +**Red Bear model (current, since the 2026-07-20 consolidation):** 1. `pcid` creates `/scheme/pci` (initfs service `35_pcid.service`) 2. `pcid-spawner --initfs` launches critical boot drivers (initfs) -3. `driver-manager --hotplug` handles full driver matching + hotplug (rootfs) +3. `pcid-spawner` (the base recipe's `00_pcid-spawner.service`, + `oneshot_async`) is the sole PCI driver spawner on the rootfs side **Key learning:** Without `35_pcid.service` in initfs, `/scheme/pci` is never created, and BOTH `pcid-spawner` (initfs and rootfs) fail with ENODEV. This -was masked in 0.2.3 because driver-manager does its own PCI enumeration via -`redox_driver_pci` and doesn't depend on `/scheme/pci`. +was masked in 0.2.3 because driver-manager did its own PCI enumeration via +`redox_driver_pci` and didn't depend on `/scheme/pci`. driver-manager is now +deferred (see above); the live path is `pcid` + `pcid-spawner`. diff --git a/local/docs/archived/SOURCE-ARCHIVAL-POLICY.md b/local/docs/archived/SOURCE-ARCHIVAL-POLICY.md deleted file mode 100644 index 0de43f550c..0000000000 --- a/local/docs/archived/SOURCE-ARCHIVAL-POLICY.md +++ /dev/null @@ -1,91 +0,0 @@ -# Source Archival Policy — Red Bear OS - -**Effective:** 2026-04-29 -**Status:** Active / Enforceable - -## Principle - -Every source archive exported to `sources//` must include the package version -number in its filename, and must contain the fully-patched source tree as it was used during the -build. No archive may be named solely by category — every archive filename must carry a version -qualifier. - -## Naming Convention - -``` -sources//--v-patched.tar.gz -``` - -| Component | Meaning | Example | -|---|---|---| -| `` | Recipe category directory | `core`, `libs`, `wip` | -| `` | Package name from recipe directory | `base`, `dbus`, `qtbase` | -| `` | Source version from recipe (tar/git rev) | `1.16.2`, `6.11.0`, `463f76b` | -| `patched` | Indicates all recipe patches are applied | always present | - -**Examples:** -``` -core-base-v463f76b-patched.tar.gz -wip-services-dbus-v1.16.2-patched.tar.gz -wip-qt-qtbase-v6.11.0-patched.tar.gz -wip-qt-qtdeclarative-v6.11.0-patched.tar.gz -core-relibc-v2025-10-03-patched.tar.gz -``` - -## Version Sources - -The version is extracted from the recipe's `[source]` block: - -| Source type | Version extraction | -|---|---| -| `tar = "https://.../pkg-X.Y.Z.tar.xz"` | Extract `X.Y.Z` from URL | -| `git = "https://...repo.git"` + `rev = "abc123"` | Use git rev short hash (`abc123`) | -| `path = "source"` (local) | Use the recipe's `[source]` section name or a manual version marker | - -## Archive Contents - -Each versioned archive must contain: - -1. The **fully patched source tree** at `recipes///source/` — after all `patches = [...]` have been applied -2. The **recipe file** (`recipe.toml`) that defines the build -3. A **metadata file** (`source-info.json`) with: package name, version, source type, patch list, and build date - -### Metadata format - -```json -{ - "package": "dbus", - "version": "1.16.2", - "source_type": "tar", - "source_url": "https://dbus.freedesktop.org/releases/dbus/dbus-1.16.2.tar.xz", - "blake3": "b1d1f22858a8f04665e5dca29d194f892620f00fd3e3f4e89dd208e78868436e", - "patches": ["redox.patch"], - "build_date": "2026-04-29T00:00:00Z", - "target": "x86_64-unknown-redox" -} -``` - -## Enforcement - -- The `packages.txt` manifest in `sources//` lists all exported packages with versions -- Every CI/documentation run that exports sources must use versioned naming -- An archive without a version number is considered incomplete — it must be regenerated -- The `make sources` target (when created) will auto-generate versioned archives - -## Existing Non-Versioned Archives (Migration) - -Current archives in `sources/x86_64-unknown-redox/` named like `core-base.tar.gz` are legacy. -They must be migrated to the versioned naming convention on next rebuild: - -| Old name | New name | -|---|---| -| `core-base.tar.gz` | `core-base-v463f76b-patched.tar.gz` | -| `core-kernel.tar.gz` | `core-kernel-v-patched.tar.gz` | -| `core-relibc.tar.gz` | `core-relibc-v-patched.tar.gz` | -| `libs-mesa.tar.gz` | `libs-mesa-v-patched.tar.gz` | - -## Related - -- `../AGENTS.md` — repository structure and durability policy -- `docs/06-BUILD-SYSTEM-SETUP.md` — build system mechanics -- `local/docs/PATCH-GOVERNANCE.md` — patch governance policy diff --git a/local/docs/fork-push-status/2026-07-12-Round-5-phase-4.1.md b/local/docs/fork-push-status/2026-07-12-Round-5-phase-4.1.md deleted file mode 100644 index 86dce1c6e9..0000000000 --- a/local/docs/fork-push-status/2026-07-12-Round-5-phase-4.1.md +++ /dev/null @@ -1,77 +0,0 @@ -# Fork-Branch Push Status — 2026-07-12 (Round 5, Phase 4.1) - -## Pushed (via push-fork-branches.sh --execute, Round 5 Phase 4.0) - -| Fork | Before | After | Origin SHA -> Local SHA | Status | -|------------|---------|---------|--------------------------|--------| -| installer | 61/0 | PUSHED | 6afa6e5..8294ecb | OK | -| kernel | 49/0 | PUSHED | 77e745a..b2a92287 | OK | -| syscall | 1/0 | PUSHED | c8bc43a..6e4e5bd | OK | -| libredox | 69/11 | PUSHED | 52c324c..b99b204 | OK | -| userutils | 202/12 | PUSHED | ac3cff2..0dc0cb7 | OK | -| relibc | 3437/60 | PUSHED | bae63d9..d157c227 | OK | - -All 6 force-pushes used `--force-with-lease=` to prevent -clobbering concurrent work we hadn't seen. All target refs now reflect -the operator's own Red Bear work (Rounds 0-4 patches + cleanup -commits) rather than the abandoned +rb0.2.5/+rb0.3.0 upstream-tracking -era. - -## PUSH BLOCKED — needs operator action - -| Fork | Ahead | Behind | Block Reason | -|------------|-------|--------|--------------| -| base | 2569 | 190 | gitea `receive.shallowUpdate=true` blocks new deeper pushes | - -The gitea server's `receive.shallowUpdate` config (default true on -gitea) refuses to accept a push that would deepen the existing -submodule/base ref. Our local base has 2569 commits, but the server -only has a shallow clone of base (probably from when the submodule -was first added). - -**Operator actions to unblock base push:** - -1. Disable receive.shallowUpdate on the gitea repo - (`gitea admin settings update receive.shallowUpdate=false` in - the gitea admin, or set via gitea config.toml per-repo) -2. OR: push via gitea's web UI (gitea can deepen the ref through - its admin interface) -3. OR: force-push from a server-side clone where the receiver - has access to deepen the ref - -Per AGENTS.md "BRANCH AND SUBMODULE POLICY" agents MUST NOT push -without operator review. The force-push for base is NOT attempted -automatically. This is a known operator-side blocker. - -## PUSH DEFERRED (Phase 2.4+ work) - -| Fork | Ahead | Behind | Reason | -|------------|-------|--------|--------| -| bootloader | 11 | 128 | 927 vs 77 file divergence, requires `upgrade-forks.sh bootloader` | - -Per fork-upstream-map.toml, bootloader is marked 'diverged' for a -reason: 856 files of legitimate Red Bear work that doesn't map to -upstream 1.0.0. The 128 commits behind on origin are upstream -bootloader evolution (Add support for live disk, Reduce prints from -UEFI bootloader, Get aarch64 UEFI bootloader building, etc.) — -none of which the Red Bear fork should accept (we have our own -decision to keep the 0.1.0-based legacy code path). - -When upgrade-forks.sh bootloader is finally run, the operator -must decide: - (a) rebase local onto a newer upstream bootloader tag (replacing - the 856-file Red Bear work) — likely breaks the Red Bear - 0.1.0 compatibility that's been preserved since 2025 - (b) accept base 128-behind + base-specific Red Bear work (so - we get the live-disk support but keep our divergence) - (c) keep current state (don't push, maintain fork supremacy) - -## Audit notes - -- After all 6 force-pushes, the parent RedBear-OS `0.3.1` branch - has its parent-side gitlinks updated to the new SHAs. No further - parent-side commits required for the fork-push part of Phase 4. -- Fork-side work: each fork's `master` branch (or `0.3.1` for kernel) - is the source of truth. Round 0-4 patches are preserved as - properly-committed changes inside the forks. -