kellito
bf80e1145d
This round-6 pass addresses the CRITICAL and WARNING findings
from the round-6 stub scan and stale-doc audit.
relibc (v5.7): replace all active unimplemented!() and todo!()
stubs with real implementations:
_aio/mod.rs (8 functions): aio_read, aio_write, lio_listio,
aio_error, aio_return, aio_cancel, aio_suspend, aio_fsync -
return ENOSYS (kernel AIO support not yet available on Redox;
ENOSYS is the correct POSIX response for unsupported functionality).
unistd/mod.rs: gethostid - return 0x7F000001 (127.0.0.1
localhost identifier; POSIX fallback when /etc/hostid is absent).
time/mod.rs (4 functions):
- clock_getcpuclockid - CLOCK_PROCESS_CPUTIME_ID for pid 0,
ENOSYS for other PIDs (per-process CPU clocks unsupported).
- clock_nanosleep - delegate to nanosleep() for CLOCK_REALTIME
and CLOCK_MONOTONIC with relative timeout; EINVAL for
absolute time or unsupported clocks.
- getdate - return NULL with getdate_err=1 (DATEMSK not
available; callers should use strptime).
- timer_getoverrun - return 0 (no timer coalescing on Redox).
stdlib/mod.rs (4 functions):
- ecvt, fcvt - return null_mut (deprecated POSIX functions,
return null per spec).
- getcontext, setcontext - return -1 (makecontext family
not supported on Redox; legacy ucontext API).
semaphore/mod.rs (3 functions): sem_close, sem_open,
sem_unlink - the three 'todo!("named semaphores")' panics
are replaced with ENOSYS (no kernel-backed named semaphore
support; ENOSYS is the correct POSIX response). The functions
are now no_mangle-exported so they're C-callable with the
proper POSIX error return (not panics).
Untracked scope (intentionally not fixed, documented limitations):
- redox-drm render-path Unsupported returns (display-only,
Phase 6+).
- ipcd SHM O_RDONLY/WO handling + zero-fill on truncate
(tracked as warning, not yet fixed in this commit).
- redox-scheme ECANCELED propagation in wrappers.rs.
- Untracked redox-driver-sys, linux-kpi, libredox, etc. internals.
Stale doc fixes (5 docs):
- DBUS-INTEGRATION-PLAN.md: resolved internal contradiction
(line 116 claimed session .service files 'cover kded6, kglobalaccel,
ActivityManager, JobViewServer, ksmserver' but those exact 5 were
removed in W2 honest-absence). Updated line 116 and the service
files row to reflect W2 removal. Also removed pcid-spawner
references (replaced with driver-manager).
- QUIRKS-AUDIT.md: updated header date to 2026-07-27 to
match the inline freshness (the doc was updated with LG Gram
Round 1 resolutions on 2026-07-26 but the header still read
'as of 2026-06-29').
- SCRIPT-BEHAVIOR-MATRIX.md: reconciled the self-contradiction
about apply-patches.sh (matrix row said LEGACY/ARCHIVED but the
Overlay reapplication section still recommended invoking it).
Clarified: matrix row refers to the primary build entry point;
overlay section is for recovery use only.
- archived/README.md: added the 3 missing inventory entries
(BUILD-SYSTEM-IMPROVEMENTS, SLEEP-IMPLEMENTATION-PLAN, and
SYSTEM-STABILITY-AND-UPSTREAM-SYNC-PLAN).
- legacy-obsolete-2026-07-25/SUPERSEDED.md: minor entry added
to track the round-6 relibc fix.
Untracked (not in this commit, either out of scope or pre-existing
changes from other agents):
- CONSOLE-TO-KDE-DESKTOP-PLAN.md (v5.9) — needs a v6.0 bump
to reflect v5.0/v5.2/v5.3/v5.6 fixes. Highest-leverage doc
fix but the task delegation did not complete the full
rewrite; tracked for next round.
- UPSTREAM-SYNC-PROCEDURE.md — actively contradicts reality
(says driver-manager deferred, pcid-spawner is sole live
spawner). Highest-impact stale doc; needs full rewrite or
archived move. Tracked for next round.
- HARDWARE-VALIDATION-MATRIX.md — modified by another agent
pre-round-6; not part of this commit.
Per local/AGENTS.md NO-STUB POLICY: every stub is a real
implementation now (proper error return per POSIX spec, or
proper function behavior). No panics on real POSIX calls.
150 lines
15 KiB
Markdown
150 lines
15 KiB
Markdown
# Red Bear OS Script Behavior Matrix
|
||
|
||
## Purpose
|
||
|
||
This document centralizes what the main repository scripts do and do not handle under the Red Bear
|
||
release fork model.
|
||
|
||
The goal is to remove guesswork from the sync/fetch/apply/build workflow.
|
||
|
||
> **SUPERSEDES: v5.x overlay model.** As of v6.0, Red Bear OS is a **full fork**.
|
||
> The "release fork" in this document refers to Red Bear's owned code in
|
||
> `local/sources/`, `local/recipes/`, `config/redbear-*.toml`, and
|
||
> `local/patches/<component>/` (Rule 2 external patches for big external
|
||
> projects). There is **no overlay layer** of `apply-patches.sh`-style
|
||
> symlinks between `recipes/` and `local/recipes/`. See
|
||
> `local/AGENTS.md` "NO OVERLAY-STYLE PATCHES — SCOPED POLICY" for the
|
||
> two-rule model. Where this document references the historical
|
||
> `apply-patches.sh` script, that is **legacy/archived** behavior; the
|
||
> canonical build flow is `local/scripts/build-redbear.sh <profile>`,
|
||
> which never invokes `apply-patches.sh`.
|
||
|
||
## Matrix
|
||
|
||
| Script | Primary role | What it handles | What it does **not** guarantee |
|
||
|---|---|---|---|
|
||
| `local/scripts/provision-release.sh` | Refresh top-level upstream repo state | fetches upstream, reports conflict risk, rebases repo commits. Under v6.0 the "release fork reapplication" step is no longer needed because `local/sources/`, `local/recipes/`, and `local/patches/<component>/` already live in the main repo (Rule 1 + Rule 2). | does not automatically solve every subsystem release fork conflict; does not by itself make upstream WIP recipes safe shipping inputs |
|
||
| `local/scripts/apply-patches.sh` | **LEGACY / ARCHIVED** — historical overlay only | under v5.x, applied build-system patches and relinked recipe patch symlinks; under v6.0 this is a no-op for in-tree components (Rule 1 direct edits) and is replaced by `cookbook_apply_patches` for big external projects (Rule 2). See `local/AGENTS.md`. | do not invoke during a v6.0 build. The `local/scripts/build-redbear.sh <profile>` canonical entry point never calls it. |
|
||
| `local/scripts/build-redbear.sh` | **Canonical build entry point** for Red Bear profiles | under v6.0 it does NOT call `apply-patches.sh` — the release fork is already in `local/`. It enforces: (1) local-over-WIP recipe priority, (2) overlay integrity verification, (3) submodule dirty-state stash, (4) firmware presence warning, (5) profile validation, (6) cookbook build if needed, (7) image build. `--upstream` triggers explicit source immutable archived for non-protected recipes. | does not guarantee every nested upstream source tree is fresh; does not replace explicit subsystem/runtime validation |
|
||
| `scripts/fetch-all-sources.sh` | Fetch mainline recipe source inputs for builds | downloads mainline/upstream recipe sources, reports status/preflight, and supports config-scoped fetches while leaving local release fork in place | does not mean fetched upstream WIP source is the durable shipping source of truth |
|
||
| `local/scripts/fetch-sources.sh` | Fetch mainline recipe sources for browsing and patching | when passed `--upstream`, fetches `recipes/*` source trees so the upstream-managed side is locally available for reading, editing, and patch preparation | does not decide whether upstream should replace the local release fork |
|
||
| `local/scripts/build-redbear-wifictl-redox.sh` | Build `redbear-wifictl` for the Redox target with the repo toolchain | prepends `prefix/x86_64-unknown-redox/sysroot/bin` to `PATH` and runs `cargo build --target x86_64-unknown-redox` in the `redbear-wifictl` crate | does not prove runtime Wi-Fi behavior; only closes the target-build environment gap for this crate |
|
||
| `local/scripts/test-iwlwifi-driver-runtime.sh` | Exercise the bounded Intel driver lifecycle inside a target runtime | validates bounded probe/prepare/init/activate/scan/connect/disconnect/retry surfaces for `redbear-iwlwifi` on a live target runtime | does not prove real AP association, packet flow, DHCP success over Wi-Fi, or end-to-end connectivity |
|
||
| `local/scripts/test-wifi-control-runtime.sh` | Exercise the bounded Wi-Fi control/profile lifecycle inside a target runtime | validates `/scheme/wifictl` control nodes, bounded connect/disconnect behavior, and profile-manager/runtime reporting surfaces on a live target runtime | does not prove real AP association or end-to-end connectivity |
|
||
| `local/scripts/test-wifi-baremetal-runtime.sh` | Exercise bounded Intel Wi-Fi runtime lifecycle on a target system | validates driver probe, control probe, bounded connect/disconnect, profile-manager start/stop via the `wifi-open-bounded` profile, Wi-Fi lifecycle reporting, and writes `/tmp/redbear-phase5-wifi-capture.json` on the target | does not prove real AP association, packet flow, DHCP success over Wi-Fi, or end-to-end hardware connectivity |
|
||
| `local/scripts/test-wifi-passthrough-qemu.sh` | Launch Red Bear with VFIO-passed Intel Wi-Fi hardware | boots a Red Bear guest with a passed-through Intel Wi-Fi PCI function, auto-runs the in-guest bounded Wi-Fi validation command, and can copy the packaged capture bundle back to a host-side file during `--check` | depends on host VFIO setup and still does not by itself guarantee real AP association or end-to-end Wi-Fi connectivity |
|
||
| `local/scripts/test-bluetooth-runtime.sh` | Compatibility guest entrypoint for the bounded Bluetooth Battery Level slice | runs the packaged `redbear-bluetooth-battery-check` helper inside a Redox guest or target runtime | does not run on the host and does not expand the Bluetooth support claim beyond the packaged checker’s bounded scope |
|
||
| `local/scripts/test-bluetooth-qemu.sh` | Launch or validate the bounded Bluetooth Battery Level slice in QEMU | boots `redbear-bluetooth-experimental`, auto-runs the packaged checker during `--check`, reruns it in one boot, and reruns it again after a clean reboot | does not by itself guarantee that the current QEMU proof passes; does not prove real controller bring-up, generic BLE/GATT maturity, write/notify support, or real hardware Bluetooth behavior |
|
||
| `local/scripts/test-drm-display-runtime.sh` | Run the bounded DRM/KMS display checker in a target runtime | invokes the packaged `redbear-drm-display-check` helper for AMD or Intel, proving scheme/card reachability, connector/mode enumeration, and bounded direct modeset proof over the Red Bear DRM ioctl surface when requested | does not prove render command submission, fence semantics, or hardware rendering |
|
||
| `local/scripts/test-amd-gpu.sh` | AMD wrapper for the bounded DRM/KMS display checker | runs `test-drm-display-runtime.sh --vendor amd` | still only display-path evidence |
|
||
| `local/scripts/test-intel-gpu.sh` | Intel wrapper for the bounded DRM/KMS display checker | runs `test-drm-display-runtime.sh --vendor intel` | still only display-path evidence |
|
||
| `local/scripts/test-msix-qemu.sh` | Bounded MSI-X proof in QEMU | validates that the current virtio-net guest path reaches MSI-X-capable interrupt delivery and emits normalized `IRQ_DRIVER`, `IRQ_MODE`, `IRQ_REASON`, and `IRQ_LOG` output for the bounded guest/runtime proof | does not prove broad hardware MSI-X reliability or per-device fallback behavior outside the bounded guest path |
|
||
| `local/scripts/test-iommu-qemu.sh` | Bounded IOMMU first-use proof in QEMU | validates guest-visible AMD-Vi initialization and bounded event/drain behavior through the current `iommu` runtime path | does not prove real-hardware interrupt remapping quality or full DMA-remapping correctness |
|
||
| `local/scripts/test-xhci-irq-qemu.sh` | Bounded xHCI interrupt-mode proof in QEMU | validates that the xHCI guest path reaches an interrupt-driven mode under the current bounded runtime checker and emits normalized `IRQ_DRIVER`, `IRQ_MODE`, `IRQ_REASON`, and `IRQ_LOG` output | does not prove full USB topology maturity or broad hardware interrupt robustness |
|
||
| `local/scripts/test-lowlevel-controllers-qemu.sh` | Aggregate bounded low-level controller proof wrapper | runs MSI-X, xHCI IRQ, IOMMU first-use, PS/2/serio, and monotonic timer proofs in one sequence, defaulting to `redbear-mini` while automatically upgrading only the IOMMU leg to `redbear-full` because that runtime currently ships `/usr/bin/iommu`; if the required `redbear-full` image is absent, that single IOMMU leg is explicitly skipped rather than aborting the rest of the bounded wrapper | does not replace the individual proof helpers and does not prove real-hardware controller quality |
|
||
| `local/scripts/prepare-wifi-vfio.sh` | Prepare or restore an Intel Wi-Fi PCI function for passthrough | binds a chosen PCI function to `vfio-pci` or restores it to a specified host driver | does not verify guest Wi-Fi functionality and must be used carefully on a host with a safe detachable target device |
|
||
| `local/scripts/validate-wifi-vfio-host.sh` | Check whether a host looks ready for Wi-Fi VFIO testing | validates PCI presence, current driver, UEFI firmware, Red Bear image presence, QEMU/expect availability, VFIO module state, and IOMMU group visibility; exits non-zero when blockers are found | does not bind devices or prove the guest Wi-Fi stack works |
|
||
| `local/scripts/run-wifi-passthrough-validation.sh` | End-to-end host-side passthrough validation wrapper | prepares VFIO, runs the packaged in-guest Wi-Fi validation path, captures the guest JSON artifact to the host, writes a host-side metadata sidecar, and restores the host driver afterwards | still depends on real VFIO/hardware support and does not itself guarantee end-to-end Wi-Fi connectivity |
|
||
| `local/scripts/package-wifi-validation-artifacts.sh` | Bundle Wi-Fi validation evidence into one archive | packages common capture/log artifacts from bare-metal or VFIO validation runs into a single tarball | does not create missing artifacts or validate their contents |
|
||
| `local/scripts/summarize-wifi-validation-artifacts.sh` | Summarize Wi-Fi validation evidence quickly | extracts key runtime signals from a capture JSON or packaged tarball for fast triage | does not replace full artifact review or prove runtime correctness |
|
||
| `local/scripts/finalize-wifi-validation-run.sh` | One-shot post-run Wi-Fi triage helper | runs the packaged analyzer on a capture JSON and then packages the chosen artifacts into a tarball | still depends on a real target run having produced the capture/artifacts first |
|
||
|
||
The packaged companion command for those scripts is `redbear-phase5-wifi-check`, which performs the
|
||
bounded in-target Wi-Fi lifecycle checks from inside the guest/runtime itself.
|
||
|
||
The packaged Bluetooth companion command is `redbear-bluetooth-battery-check`, which is intended to
|
||
perform the bounded Bluetooth Battery Level checks from inside the guest/runtime itself, including
|
||
repeated helper runs, daemon-restart coverage, failure-path honesty checks, and stale-state cleanup
|
||
checks within the current slice boundary.
|
||
|
||
The packaged DRM display companion command is `redbear-drm-display-check`, which is intended to
|
||
perform bounded DRM/KMS display-side checks from inside the guest/runtime itself. It now covers
|
||
direct connector/mode enumeration and bounded direct modeset proof over the Red Bear DRM ioctl
|
||
surface, and explicitly does not claim render or hardware-accelerated graphics completion.
|
||
|
||
The packaged evidence companion is `redbear-phase5-wifi-capture`, which collects the bounded driver,
|
||
control, profile-manager, reporting, interface-listing, and scheme-state surfaces — plus `lspci`
|
||
and active-profile contents — into a single JSON artifact.
|
||
|
||
The packaged link-oriented companion is `redbear-phase5-wifi-link-check`, which focuses on whether
|
||
the target runtime is exposing interface/address/default-route signals in addition to the bounded
|
||
Wi-Fi lifecycle state.
|
||
|
||
> **Coverage note (2026-07-26):** The matrix above catalogues the build/sync
|
||
> and Wi-Fi/Bluetooth/DRM/low-level-controller validation scripts as of the
|
||
> round-5 sync. Newer scripts that have landed since — including the
|
||
> driver-manager audit/QEMU-gate helpers, the low-level-controller wrappers
|
||
> (`test-ps2-qemu.sh`, `test-timer-qemu.sh`,
|
||
> `test-lowlevel-controllers-qemu.sh`), the USB-maturity wrappers
|
||
> (`test-usb-qemu.sh`, `test-usb-maturity-qemu.sh`,
|
||
> `test-usb-storage-qemu.sh`), and the greeter QEMU proof
|
||
> (`test-greeter-qemu.sh`) — live in `local/scripts/` and are documented in
|
||
> `local/AGENTS.md` § "HOW TO BUILD RED BEAR OS". They are not yet given
|
||
> individual matrix rows here; treat `local/AGENTS.md` as authoritative for
|
||
> their invocation and scope.
|
||
|
||
For Redox-target Rust builds of Wi-Fi components such as `redbear-wifictl`, a missing
|
||
`x86_64-unknown-redox-gcc` on `PATH` should first be treated as a host toolchain/path issue if the
|
||
repo already contains `prefix/x86_64-unknown-redox/sysroot/bin/x86_64-unknown-redox-gcc`.
|
||
|
||
## Policy Mapping
|
||
|
||
### Resilience / offline-first package sourcing
|
||
|
||
Default Red Bear behavior is local-first:
|
||
|
||
- use locally available package/source trees and release fork state for normal builds,
|
||
- treat upstream immutable archived as an explicit operator action only (`--upstream`, dedicated fetch/sync),
|
||
- do not fail policy-level expectations just because upstream network access is temporarily broken.
|
||
|
||
This is required so builds and recovery workflows remain operable during upstream outages or
|
||
connectivity failures.
|
||
|
||
### Upstream sync
|
||
|
||
Use `local/scripts/provision-release.sh` when the goal is to immutable archived the top-level upstream Redox base.
|
||
|
||
This is a repository sync operation, not a guarantee that every local subsystem release fork is already
|
||
rebased cleanly.
|
||
|
||
### Overlay reapplication (recovery only — not a normal build step)
|
||
|
||
> **Note:** This subsection documents the *recovery* role of
|
||
> `apply-patches.sh`, consistent with its matrix row above. The matrix row's
|
||
> "do not invoke" warning applies to the **normal build entry** — the canonical
|
||
> `build-redbear.sh <profile>` never calls `apply-patches.sh`. The script is
|
||
> retained **only** for disaster recovery: reconstructing Red Bear's owned
|
||
> state (build-system patches + recipe patch symlinks) on top of a fresh,
|
||
> pristine upstream tree after a total loss of `local/` state. Do not invoke
|
||
> it as part of day-to-day or CI builds.
|
||
|
||
Use `local/scripts/apply-patches.sh` **only** when the goal is to reconstruct
|
||
Red Bear's release-fork patch linkages on top of a fresh upstream tree as a
|
||
last-resort recovery operation.
|
||
|
||
This is the core durable-state recovery path, not a normal build step.
|
||
|
||
### Build execution
|
||
|
||
Use `local/scripts/build-redbear.sh` when the goal is to build a tracked Red Bear profile from the
|
||
current upstream base plus local release fork. Add `--upstream` only when you explicitly want Redox/upstream
|
||
recipe sources immutable archived during that build.
|
||
|
||
### Source immutable archived
|
||
|
||
Use `scripts/fetch-all-sources.sh` and `local/scripts/fetch-sources.sh --upstream` when the goal is to
|
||
immutable archived recipe source inputs, but do not confuse fetched upstream WIP source with a trusted shipping
|
||
source.
|
||
|
||
## WIP Rule in Script Terms
|
||
|
||
If a subsystem is still upstream WIP, the scripts should be interpreted this way:
|
||
|
||
- fetching upstream WIP source is allowed and useful through the explicit upstream fetch commands or
|
||
`--upstream` where a wrapper requires it,
|
||
- syncing upstream WIP source is allowed and useful through the explicit upstream sync command,
|
||
- but shipping decisions should still prefer the local release fork until upstream promotion and reevaluation happen.
|
||
|
||
That means “script fetched it successfully” is not the same as “Red Bear should now ship upstream’s
|
||
WIP version directly.”
|