From a853c9250ea864c945cda07f498fd0a674fdbbfc Mon Sep 17 00:00:00 2001
From: vasilito <adminpupkin@gmail.com>
Date: Thu, 18 Jun 2026 22:22:29 +0300
Subject: [PATCH] docs: document known issues and fixes from 2026-06-18
 upstream sync

Author: vasilito <adminpupkin@gmail.com>
---
 local/docs/UPSTREAM-SYNC-PROCEDURE.md | 83 +++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/local/docs/UPSTREAM-SYNC-PROCEDURE.md b/local/docs/UPSTREAM-SYNC-PROCEDURE.md
index fb31a4e3ae..3aef6cbfa1 100644
--- a/local/docs/UPSTREAM-SYNC-PROCEDURE.md
+++ b/local/docs/UPSTREAM-SYNC-PROCEDURE.md
@@ -373,3 +373,86 @@ Is the feature in upstream now?
 - [ ] Dependent components rebuilt
 - [ ] Full image build succeeds
 - [ ] QEMU boot test passes
+
+## Known Issues and Solutions (2026-06-18 Sync)
+
+### Kernel: `-Zjson-target-spec` Rejected by Cargo in Redoxer
+
+**Problem:** The upstream kernel Makefile passes `-Zjson-target-spec` as a
+cargo CLI flag. The redoxer build environment's cargo (at
+`~/.redoxer/x86_64-unknown-redox/toolchain/bin/cargo`) lists this flag in
+`cargo -Z help` but rejects it when invoked through `make` inside
+`redoxer env bash -ex`.
+
+**Root cause:** The `make` subprocess inside redoxer env does not properly
+propagate all cargo unstable feature flags from the CLI. The env-var form
+(`CARGO_UNSTABLE_<FEATURE>=true`) works reliably.
+
+**Fix (applied to kernel Makefile):**
+```makefile
+# Replace -Zjson-target-spec CLI flag with env var
+export CARGO_UNSTABLE_JSON_TARGET_SPEC=true
+# Remove -Zjson-target-spec from the cargo rustc command line
+```
+
+### Base: `map_bar()` API Change
+
+**Problem:** Upstream changed `pcid_handle.map_bar(N)` to
+`pcid_handle.map_bar(N, MemoryType::Uncacheable)`.
+
+**Fix:** Update all Red Bear drivers that call `map_bar()` to pass
+`common::MemoryType::Uncacheable` as the second argument. Affected drivers:
+`amd-mp2-i2cd`, `intel-thc-hidd`. The upstream drivers (`ahcid`, `nvmed`,
+`xhcid`) already use the new API.
+
+### Base: `if let` Guards in pcid
+
+**Problem:** Upstream `drivers/pcid/src/cfg_access/mod.rs` uses experimental
+`if let` guards in match arms.
+
+**Fix:** Add `#![feature(if_let_guard)]` to `drivers/pcid/src/main.rs`.
+
+### Base: XHCI Quirk Integration Dropped
+
+**Problem:** The Red Bear xhci quirk integration (`XhciControllerQuirkFlags`,
+`staged_port_states`, `ZERO_64B_REGS` handling) was deeply coupled with the
+old xhci module code and conflicts with upstream's evolved API.
+
+**Resolution:** Reverted `drivers/usb/xhcid/src/xhci/mod.rs` and
+`irq_reactor.rs` to upstream. The quirk system will be re-integrated as
+follow-up work on top of the new upstream xhci code.
+
+### Base: Workspace Members Missing After Sync
+
+**Problem:** Taking upstream's `Cargo.toml` drops Red Bear-specific workspace
+members (I2C, GPIO, HID, thermald, ucsid, acpi-resource).
+
+**Fix:** Add all 13 Red Bear workspace members back to the `members` list.
+Also fix the `[patch]` section to point to `../../sources/relibc/` (not the
+stale `../../relibc/source/` path).
+
+### Systemic: `redox_syscall` Version Alignment
+
+**Problem:** All Red Bear custom recipes used `redox_syscall = "0.7"`, but the
+synced base and relibc use `0.8.x`.
+
+**Fix:** Bulk-replaced `"0.7"` → `"0.8"` across all 23 Red Bear recipe
+Cargo.toml files.
+
+### Installer: Switch to Local Fork
+
+**Problem:** The installer recipe used `git = "..."` + `patches = [...]`, but
+the patch (`redox.patch`) fails against the synced upstream code (368 commits
+of drift).
+
+**Fix:** Switched recipe to `path = "../../../local/sources/installer"` (local
+fork mode). The ext4/GRUB installer changes need to be re-applied to the fork
+as follow-up work.
+
+### Kernel: Switch to Local Fork
+
+**Problem:** The kernel recipe used `git = "..."` + 5 patches, all of which
+fail against the synced upstream code.
+
+**Fix:** Switched recipe to `path = "../../../local/sources/kernel"` (local
+fork mode). All patches were already squash-merged into the fork.