IOS LLE: optional IPC request/reply metadata trace (StarletOS phase 11 L2)

With DOLPHIN_IPC_TRACE=1 and the original IOS on the emulated Starlet, log
each request Broadway posts (X1: command, descriptor, argument words, an
OPEN's path) and each reply Starlet posts (Y1: original command, result).
Buffer contents are never read; nothing changes without the variable.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

.gitattributes

@@ -9,6 +9,7 @@ Source/Core/Core/Config/MainSettings.cpp -text
 Source/Core/Core/Config/MainSettings.h -text
 Source/Core/Core/ConfigManager.cpp -text
 Source/Core/Core/HW/HW.cpp -text
+Source/Core/Core/HW/WII_IPC.cpp -text
 Source/Core/Core/IOS/Starlet/ARMCore.cpp -text
 Source/Core/Core/IOS/Starlet/BootstrapELF.cpp -text
 Source/Core/Core/IOS/Starlet/BootstrapELF.h -text

Source/Core/Core/HW/WII_IPC.cpp

@@ -3,6 +3,9 @@
 
 #include "Core/HW/WII_IPC.h"
 
+#include <cstdlib>
+#include <string>
+
 #include "Common/ChunkFile.h"
 #include "Common/CommonTypes.h"
 #include "Common/Logging/Log.h"
@@ -10,6 +13,7 @@
 #include "Core/CoreTiming.h"
 #include "Core/HW/DVD/DVDInterface.h"
 #include "Core/HW/MMIO.h"
+#include "Core/HW/Memmap.h"
 #include "Core/HW/ProcessorInterface.h"
 #include "Core/IOS/IOS.h"
 #include "Core/IOS/Starlet/Starlet.h"
@@ -142,6 +146,55 @@ void WiiIPC::Shutdown()
 {
 }
 
+namespace
+{
+// StarletOS phase 11 (proposal L2): with DOLPHIN_IPC_TRACE=1 while the original IOS runs on the
+// emulated Starlet, each IPC request Broadway posts (X1) and each reply Starlet posts (Y1) is
+// logged with its metadata only: the command, the descriptor and the five argument words (an
+// OPEN's path), then the reply's result. Buffer contents are never read.
+bool IPCTraceEnabled()
+{
+  static const bool enabled = [] {
+    const char* value = std::getenv("DOLPHIN_IPC_TRACE");
+    return value != nullptr && value[0] == '1';
+  }();
+  return enabled;
+}
+
+void TraceIPCRequest(Core::System& system, u32 address)
+{
+  auto& memory = system.GetMemory();
+  if (memory.GetPointerForRange(address, 0x20) == nullptr)
+  {
+    NOTICE_LOG_FMT(WII_IPC, "IPCTRACE RQ {:08x} unreadable", address);
+    return;
+  }
+  const u32 command = memory.Read_U32(address);
+  const u32 fd = memory.Read_U32(address + 8);
+  u32 arg[5];
+  for (u32 i = 0; i < 5; ++i)
+    arg[i] = memory.Read_U32(address + 0xc + 4 * i);
+  std::string path;
+  if (command == 1 && memory.GetPointerForRange(arg[0], 64) != nullptr)
+    path = " P " + memory.GetString(arg[0], 64);
+  NOTICE_LOG_FMT(WII_IPC, "IPCTRACE RQ {:08x} C {} FD {} A {:08x} {:08x} {:08x} {:08x} {:08x}{}",
+                 address, command, static_cast<s32>(fd), arg[0], arg[1], arg[2], arg[3], arg[4],
+                 path);
+}
+
+void TraceIPCReply(Core::System& system, u32 address)
+{
+  auto& memory = system.GetMemory();
+  if (memory.GetPointerForRange(address, 0x10) == nullptr)
+  {
+    NOTICE_LOG_FMT(WII_IPC, "IPCTRACE RP {:08x} unreadable", address);
+    return;
+  }
+  NOTICE_LOG_FMT(WII_IPC, "IPCTRACE RP {:08x} C {} RC {}", address, memory.Read_U32(address + 8),
+                 static_cast<s32>(memory.Read_U32(address + 4)));
+}
+}  // namespace
+
 void WiiIPC::RegisterMMIO(MMIO::Mapping* mmio, u32 base)
 {
   // Both IPC message registers are general-purpose read/write registers on
@@ -168,6 +221,8 @@ void WiiIPC::RegisterMMIO(MMIO::Mapping* mmio, u32 base)
                      wii_ipc.m_ppc_irq_flags |= INT_CAUSE_IPC_BROADWAY;
                    if (wii_ipc.m_ctrl.X1)
                    {
+                     if (system.GetStarlet() && IPCTraceEnabled() && (val >> 0 & 1))
+                       TraceIPCRequest(system, wii_ipc.m_ppc_msg);
                      if (system.GetStarlet())
                        wii_ipc.m_arm_irq_flags |= INT_CAUSE_IPC_STARLET;
                      else if (system.GetIOS())
@@ -386,6 +441,9 @@ void WiiIPC::WriteStarletRegister(u32 offset, u32 value)
     break;
   case IPC_ARMCTRL:
     m_ctrl.arm(value);
+    // StarletOS phase 11: Y1 (bit 0) posts the reply whose pointer is in ARMMSG.
+    if (IPCTraceEnabled() && (value & 1))
+      TraceIPCReply(m_system, m_arm_msg);
     break;
   case PPC_IRQFLAG:
     m_ppc_irq_flags &= ~value;

docs/StarletOS_Checkpoint.json

@@ -46,6 +46,11 @@
       "sha256": "7e9bcfff87f526510aad149e781ae57140e32f7b32beafec00271fbcdb152848",
       "bytes": 4526
     },
+    {
+      "path": "Source/Core/Core/HW/WII_IPC.cpp",
+      "sha256": "e216d272f7653b4650481a3335989a86550eee3d90aa7e6c7f06bb1ce87822e1",
+      "bytes": 21443
+    },
     {
       "path": "Source/Core/Core/IOS/Starlet/ARMCore.cpp",
       "sha256": "40d45aed7c5edb4540105dcdee4dd8dcde88c21ba7f3279eff0a9564f2d02a29",
@@ -122,5 +127,14 @@
     "unpublishedHistoricalFileVersionsScanned": 67,
     "privateFindings": 0,
     "newFullBuildOrHardwareTest": "NOT RUN: publication of existing qualified bytes only; see companion phase reports"
-  }
+  },
+  "updates": [
+    {
+      "recordedAt": "2026-10-06",
+      "purpose": "StarletOS Phase 11 proposal L2: IPC request/reply metadata trace while the original IOS runs (DOLPHIN_IPC_TRACE=1); no behavior change otherwise",
+      "files": [
+        "Source/Core/Core/HW/WII_IPC.cpp"
+      ]
+    }
+  ]
 }

docs/StarletOS_Handoff.md

@@ -81,3 +81,36 @@ Rebuilding its PPC binary under Linux remains unqualified (the exact devkitPro
 packages could not be downloaded: HTTP 403). Preserve the archived probe.
 This documentation commit changes the dependency pin, not the built code;
 the executables above still report their build's original commit.
+
+
+## Phase 11 IPC trace for the original IOS — 2026-10-06
+
+Starting checkout: master `78738093ece433e9198213f91d43a3a0d60e3fa2`, clean;
+fetch found no divergence. Companion: StarletOS Phase 11 proposal L2
+(`docs/PHASE11_PROPOSAL.md`), approved by the user.
+
+- `Source/Core/Core/HW/WII_IPC.cpp`: with the environment variable
+  `DOLPHIN_IPC_TRACE=1` and the original IOS running on the emulated Starlet
+  (`WiiIOSLLE`), every request Broadway posts (PPCCTRL X1) is logged as
+  `IPCTRACE RQ <addr> C <command> FD <fd> A <five argument words>` (an OPEN
+  adds ` P <path>`), and every reply Starlet posts (ARMCTRL Y1) as
+  `IPCTRACE RP <addr> C <original command> RC <result>`. Notice level, `WII_IPC`
+  log type. Metadata only: buffer contents are never read. Without the
+  variable, or in HLE mode, nothing changes.
+- The file is now an exact integration file (`.gitattributes -text`, hash in
+  `docs/StarletOS_Checkpoint.json`, 23 files).
+- Build: `.starlet_linux` `dolphin-emu-nogui` and `tests` rebuilt; the 95
+  selected Starlet tests (filter in the companion `docs/LINUX_QUALIFICATION.md`)
+  passed.
+- Emulation smoke run (supporting evidence only, private log in the companion
+  `target/phase11/l2/`): headless, Null video, the companion's Phase 10C NAND
+  read-only behind a private profile's COW journal, original boot chain to the
+  System Menu for 5 minutes: 74342 requests and 74337 replies traced (5
+  asynchronous requests still pending at the stop).
+- Limitation: this Linux build has no window platform (X11 disabled; the
+  system lacks the `xi` development package), so no one can point and click in
+  it yet. A separate X11 build directory is the next step once `libxi-dev` is
+  installed; the qualified headless build stays unchanged.
+
+Next: the companion's Phase 11 L2c (the user launches the Mii Channel from the
+Menu in a window with the trace on); analysis stays in the companion.