From 7e34c4c2510856b58c8a7acacde1d512cc963b5a Mon Sep 17 00:00:00 2001 From: vasilito Date: Wed, 8 Jul 2026 00:33:17 +0300 Subject: [PATCH] docs: create comprehensive syscall migration plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SYSCALL-MIGRATION-PLAN.md: - Detailed analysis of upstream 0.9.0 BREAKING changes (FD reservation refactor, removed syscalls, new *_into variants) - Complete consumer impact catalog: 2 bootstrap call sites, 7 kernel/relibc constant references, 26 recipes (no impact) - 5-phase migration plan: bootstrap→kernel→relibc→syscall sync→full build - Risk assessment with rollback procedure - Clear migration table: old API → new API for each deprecated function/constant - Execution order with time estimates (~1-2 days total) --- local/docs/SYSCALL-MIGRATION-PLAN.md | 242 +++++++++++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 local/docs/SYSCALL-MIGRATION-PLAN.md diff --git a/local/docs/SYSCALL-MIGRATION-PLAN.md b/local/docs/SYSCALL-MIGRATION-PLAN.md new file mode 100644 index 0000000000..a84fc49f3b --- /dev/null +++ b/local/docs/SYSCALL-MIGRATION-PLAN.md @@ -0,0 +1,242 @@ +# Syscall Migration — Upstream 0.9.0 BREAKING Changes + +**Date**: 2026-07-07 +**Status**: Assessment complete, migration plan ready +**Reference**: `local/sources/syscall/` — our fork `7e9cffd` vs upstream `1db4871` + +--- + +## 1. What Changed Upstream + +Redox OS upstream (`gitlab.redox-os.org/redox-os/syscall.git`) introduced two +breaking changes in version 0.9.0: + +### 1.1 FD Reservation Refactor (`4bb9233`) + +The old auto-allocation FD API was replaced with reservation-based allocation: + +| Old (deprecated) | New (upstream 0.9.0) | +|---|---| +| `syscall::open(path, flags)` → returns auto-allocated fd | `syscall::open_into(path, flags, reserved_fd)` | +| `syscall::dup(fd, buf)` → returns auto-allocated fd | `syscall::dup_into(fd, reserved_fd, buf)` | +| Implicit fd allocation | Explicit reservation via `syscall::reserve_fd(n)` | + +The reservation model requires callers to: +1. Call `reserve_fd(n)` to reserve N consecutive fd numbers +2. Pass the reserved fd to `*_into` variants +3. Release unused reservations via `release_fd(n)` + +### 1.2 Removed Syscalls (`1db4871`) + +These syscall numbers were removed from `src/number.rs` and `src/call.rs`: + +| Removed Constant | Reason | +|---|---| +| `SYS_OPENAT_WITH_FILTER` (985) | Replaced by `SYS_OPENAT_INTO` (987) — reservation-based | +| `SYS_UNLINKAT_WITH_FILTER` (986) | Replaced by `SYS_UNLINKAT` (263) — no filter needed | +| `SYS_SENDFD` (34) | Absorbed into `SYS_CLOSE` / scheme dispatch | +| `SYS_OPENAT` (7) | Replaced by `SYS_OPENAT_INTO` (987) | +| `SYS_DUP` (41) | Replaced by `SYS_DUP_INTO` (988) | + +The corresponding call wrappers were also removed: +- `openat_with_filter()` — removed +- `unlinkat_with_filter()` — removed + +### 1.3 New Upstream Features (unrelated, useful) + +| Commit | Change | +|---|---| +| `79cb6d9` | `AcpiVerb` — new proc scheme ACPI verb | +| `a358928` | Additional proc scheme & addrsp verbs | +| `fcce297` | `Error::new` as `const fn` | + +--- + +## 2. Our Fork State + +Our fork `7e9cffd` is based on upstream at the pre-breaking-change point +(before `4bb9233`). Five commits were added to preserve backward compatibility: + +| Our Commit | What It Preserves | +|---|---| +| `812d74e` | `SYS_OPENAT` and `SYS_DUP` aliases | +| `bf54ba8` | `SYS_SENDFD` constant | +| `488ed0c` | `SYS_OPENAT_WITH_FILTER` and `SYS_UNLINKAT_WITH_FILTER` constants | +| `2c06be3` | Legacy `openat`/`dup`/`sendfd`/`close` call wrappers | +| `7e9cffd` | `openat_with_filter` / `unlinkat_with_filter` call wrappers | + +**Current divergence**: 5 commits behind upstream HEAD (2 actual changes + 3 cosmetic). + +--- + +## 3. Consumer Impact Analysis + +### 3.1 `openat_with_filter` / `unlinkat_with_filter` Usage + +Only 1 file uses these deprecated APIs: + +| File | Usages | Migration Difficulty | +|---|---|---| +| `local/sources/base/bootstrap/src/initnsmgr.rs` | 2 (openat + unlinkat) | **Low** — straightforward replacement | + +### 3.2 Legacy Constant References + +| File | Constants Used | Action | +|---|---|---| +| `local/sources/kernel/src/syscall/mod.rs` | `SYS_OPENAT_WITH_FILTER`, `SYS_UNLINKAT_WITH_FILTER`, `SYS_SENDFD` | Update dispatch table | +| `local/sources/kernel/src/scheme/proc.rs` | `SYS_SENDFD` | Update proc scheme handler | +| `local/sources/kernel/src/syscall/debug.rs` | `SYS_OPENAT`, `SYS_DUP` | Update debug logging | +| `local/sources/syscall/src/flag.rs` | `SYS_SENDFD` | Internal — will be updated by sync | +| `local/sources/relibc/redox-rt/src/sys.rs` | `SYS_OPENAT`, `SYS_DUP`, `SYS_SENDFD` | Update redox-rt wrappers | + +### 3.3 Recipe Consumers (26 recipes) + +All 26 recipes reference `redox_syscall` via `Cargo.toml` but do NOT use the +deprecated APIs directly — they use stable APIs (`open`, `read`, `write`, etc.). +**No recipe changes needed.** + +--- + +## 4. Migration Plan + +### Phase 1: Bootstrap Migration (Low Risk, 2 call sites) + +**File**: `local/sources/base/bootstrap/src/initnsmgr.rs` + +Replace `openat_with_filter` with the upstream `openat_into` + reservation pattern: + +```rust +// OLD: +let scheme_fd = syscall::openat_with_filter( + cap_fd, reference, flags, ctx.uid, ctx.gid +)?; + +// NEW (reservation-based): +let reserved = syscall::reserve_fd(1)?; +let scheme_fd = syscall::openat_into( + cap_fd, reference, flags, reserved, ctx.uid, ctx.gid +)?; +``` + +Replace `unlinkat_with_filter` with `unlinkat`: + +```rust +// OLD: +syscall::unlinkat_with_filter(cap_fd, reference, flags, ctx.uid, ctx.gid)?; + +// NEW: +syscall::unlinkat(cap_fd, reference, flags)?; +``` + +**Verification**: `cargo check -p bootstrap` passes. + +### Phase 2: Kernel Dispatch Update (Medium Risk, 3 files) + +Update `local/sources/kernel/src/syscall/mod.rs` — replace deprecated constants in +the syscall dispatch match: + +| Old | New | +|---|---| +| `SYS_OPENAT_WITH_FILTER` | `SYS_OPENAT_INTO` | +| `SYS_UNLINKAT_WITH_FILTER` | Remove (no longer dispatched) | +| `SYS_SENDFD` | Remove (absorbed into scheme dispatch) | +| `SYS_OPENAT` | `SYS_OPENAT_INTO` | +| `SYS_DUP` | `SYS_DUP_INTO` | + +Update `local/sources/kernel/src/scheme/proc.rs` — remove `SYS_SENDFD` handling. + +Update `local/sources/kernel/src/syscall/debug.rs` — update constant names in log messages. + +**Verification**: `cargo check -p kernel` passes. Boot test in QEMU. + +### Phase 3: relibc redox-rt Update (Medium Risk, 1 file) + +Update `local/sources/relibc/redox-rt/src/sys.rs` — replace deprecated constant +references with the new names. The redox-rt module wraps kernel syscalls for +relibc's POSIX layer. + +**Verification**: `cargo check` in relibc passes. `sys_socket` tests pass. + +### Phase 4: Syscall Fork Sync (High Risk, entire fork) + +Squash-merge the upstream changes into our fork: + +```bash +cd local/sources/syscall +git fetch upstream +git checkout -b sync-0.9.0 upstream/master +git merge --squash master # re-apply our preservation commits on top of upstream +# Resolve conflicts in: +# src/call.rs — keep upstream's reservation API, drop our legacy wrappers +# src/number.rs — keep upstream's constants, drop our legacy constants +# src/flag.rs — merge minimally +``` + +**After sync, our fork drops all 5 preservation commits** since: +1. `openat_with_filter` / `unlinkat_with_filter` are no longer needed (bootstrap migrated) +2. `SYS_OPENAT_WITH_FILTER` etc. are no longer needed (kernel migrated) +3. The reservation API is the canonical path + +**Verification**: +- `cargo check` in syscall passes +- All 26 recipes compile against new syscall +- Kernel compiles against new syscall +- relibc compiles against new syscall +- Full `redbear-mini` ISO builds + +### Phase 5: Full Image Build + Validation + +```bash +touch syscall && make prefix +./local/scripts/build-redbear.sh --upstream redbear-mini +# QEMU boot test +# DHCP + curl test +``` + +--- + +## 5. Risk Assessment + +| Risk | Severity | Mitigation | +|---|---|---| +| Kernel panic from missing syscall dispatch | **HIGH** | Test each syscall removal individually in QEMU | +| FD leak from reservation API misuse | **MEDIUM** | Audit all `reserve_fd` / `release_fd` call pairs | +| relibc ABI break | **MEDIUM** | Run full `sys_socket` test suite | +| Recipe compile failure | **LOW** | All 26 recipes use stable APIs — no changes needed | +| Bootstrap fails to init | **LOW** | Only 2 call sites, simple replacement | + +--- + +## 6. Execution Order + +``` +Phase 1 (bootstrap) → Phase 2 (kernel) → Phase 3 (relibc) → Phase 4 (syscall sync) → Phase 5 (full build) + 30 min 2-4 hours 1 hour 1-2 hours 2-4 hours +``` + +**Total estimated duration**: 1-2 days. + +**Prerequisite**: None — all phases are independent except Phase 4 depends on 1-3 completing +first (consumers must be migrated before syscall drops legacy support). + +--- + +## 7. Rollback Plan + +If the migration fails, revert each component: + +```bash +# Revert syscall fork to pre-sync state +cd local/sources/syscall && git checkout master + +# Revert kernel (git stash or checkout) +cd local/sources/kernel && git checkout -- . + +# Revert bootstrap +cd local/sources/base && git checkout -- bootstrap/ + +# Revert relibc +cd local/sources/relibc && git checkout -- redox-rt/ +``` + +The legacy constants and wrappers are preserved in our fork's git history at `7e9cffd`. \ No newline at end of file