StarletBootstrapProbe: --ipc-script

The probe stands in for Broadway, so that a real request can enter StarOS's
image through the Hollywood IPC registers and its reply be read back (StarOS
docs/contracts/hollywood-ipc-injection.md, approved for development). A
script is data: whole words stored in one range of PPC memory,
0x135E0000..0x13600000, PPCMSG and PPCCTRL written, PPCCTRL and ARMMSG read,
every wait bounded in ARM cycles. Steps run between the probe's slices. The
probe knows nothing of the code under test and answers nothing for it.

A script refused when read ends the run with exit status 5, before StarOS
starts. A step that fails, or a terminal trace line with steps left, fails
the run with its line on stderr. The option given twice, or without its
file, is a usage error.

The one change in Source/Core: WiiIPC::SetStarletAttached, an opt-in flag
UpdateInterrupts reads beside GetStarlet(), because the probe runs an
ARMCore with no Starlet object in the System. The IPC cause is then raised
by the model's own line, X1 and IX1 included, with no second model of it.
Reset clears the flag, and nothing sets it without --ipc-script.

ProbeScript.h holds the parser and the runner, tested by
StarletProbeScriptTest over a fake bus; StarletProbeInterruptTest holds the
flag's behaviour with and without it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
Yaya48andClaude Opus 5.5 committed 2026-11-03 00:55:58 +01:00
1 parent 9d66381b3d
commit a709fddfa8
7 files changed
+650 -6

No files matched your search

@@ -20,6 +20,7 @@
#include "Core/System.h"
#include "ProbeBudget.h"
#include "ProbeRing.h"
#include "ProbeScript.h"
#include "ProbeStaging.h"
#include "StarOSPanicCheck.h"
@@ -82,8 +83,56 @@ std::optional<std::vector<u8>> ReadPackage(const std::string& path)
return package;
}
// Reads and parses the file of --ipc-script: its runner, or nullopt once the reason is on stderr.
std::optional<ScriptRunner> ReadScript(const std::string& path)
{
std::ifstream file(path, std::ios::binary | std::ios::ate);
if (!file)
{
std::cerr << "--ipc-script: cannot open the script: " << path << '\n';
return std::nullopt;
}
const std::streamoff end = file.tellg();
if (end < 0 || static_cast<u64>(end) > SCRIPT_MAX_BYTES)
{
std::cerr << "--ipc-script: refused " << path << ": over " << SCRIPT_MAX_BYTES << " bytes\n";
return std::nullopt;
}
std::string text(static_cast<size_t>(end), '\0');
file.seekg(0);
if (!file.read(text.data(), end))
{
std::cerr << "--ipc-script: cannot read the script: " << path << '\n';
return std::nullopt;
}
std::string error;
auto steps = ParseScript(text, &error);
if (!steps)
{
std::cerr << "--ipc-script: refused " << path << ": " << error << '\n';
return std::nullopt;
}
return ScriptRunner(std::move(*steps));
}
// What a script reaches: PPC memory and the registers, as Broadway does.
class ProbeBus final : public ScriptBus
{
public:
ProbeBus(Memory::MemoryManager& memory, IOS::WiiIPC& ipc) : m_memory(memory), m_ipc(ipc) {}
void StoreWord(u32 address, u32 word) override { m_memory.Write_U32(word, address); }
u32 LoadWord(u32 address) override { return m_memory.Read_U32(address); }
void WriteRegister(u32 offset, u32 value) override { m_ipc.WriteStarletRegister(offset, value); }
u32 ReadRegister(u32 offset) override { return m_ipc.ReadStarletRegister(offset); }
private:
Memory::MemoryManager& m_memory;
IOS::WiiIPC& m_ipc;
};
bool Run(const std::string& path, bool jit, bool mmu_faults, SBR1Mode sbr1,
ExpectedOutcome expected, u64 cycles, const std::vector<u8>* package)
ExpectedOutcome expected, u64 cycles, const std::vector<u8>* package, ScriptRunner* script)
{
std::ifstream file(path, std::ios::binary | std::ios::ate);
if (!file || file.tellg() <= 0 || file.tellg() > 16 * 1024 * 1024)
@@ -158,9 +207,22 @@ bool Run(const std::string& path, bool jit, bool mmu_faults, SBR1Mode sbr1,
std::cerr << "Starlet panic state " << memory.Read32(info.panic_state) << " code "
<< memory.Read32(info.panic_code) << '\n';
};
ProbeBus script_bus(mem1, system.GetWiiIPC());
// The model's own line raises the IPC cause: the probe has no Starlet object (ProbeScript.h).
if (script)
system.GetWiiIPC().SetStarletAttached(true);
int panic_settled = 0;
for (u64 slice = 0; slice < cycles / SLICE_CYCLES; ++slice)
{
if (script)
{
script->Advance(script_bus, slice == 0 ? 0 : SLICE_CYCLES);
if (script->Failed())
{
std::cerr << "--ipc-script: " << script->Failure() << '\n';
return false;
}
}
core.SetIRQLine(system.GetWiiIPC().IsStarletIRQAsserted());
core.SetFIQLine(system.GetWiiIPC().IsStarletFIQAsserted());
core.RunCycles(SLICE_CYCLES);
@@ -213,6 +275,11 @@ bool Run(const std::string& path, bool jit, bool mmu_faults, SBR1Mode sbr1,
std::cout << trace;
std::cout << "PC=0x" << std::hex << core.GetRegister(15) << std::dec
<< " instructions=" << core.GetExecutedInstructions() << '\n';
if (script && !script->Done())
{
std::cerr << "--ipc-script: script unfinished at line " << script->Line() << '\n';
return false;
}
const bool early_startup_ok = trace.find("REV:BOOT:ENTRY\n") != std::string::npos &&
trace.find("REV:BOOT:BSS_OK\n") != std::string::npos;
if (expected == ExpectedOutcome::FatalData)
@@ -260,12 +327,12 @@ bool Run(const std::string& path, bool jit, bool mmu_faults, SBR1Mode sbr1,
int main(int argc, char** argv)
{
Common::RegisterMsgAlertHandler(FailOnAlert);
if (argc < 2 || argc > 10)
if (argc < 2 || argc > 12)
{
std::cerr << "Usage: StarletBootstrapProbe <ELF> [--jit] [--mmu-faults] "
"[--sbr1-record|--sbr1-absent] "
"[--expect-panic|--expect-fatal-data|--expect-undefined-fault|--expect-phase2] "
"[--cycles <n>] [--stage-spk <file>]\n";
"[--cycles <n>] [--stage-spk <file>] [--ipc-script <file>]\n";
return 2;
}
bool jit = false;
@@ -275,10 +342,21 @@ int main(int argc, char** argv)
bool outcome_selected = false;
std::optional<u64> cycles;
std::optional<std::string> package_path;
std::optional<std::string> script_path;
for (int index = 2; index < argc; ++index)
{
const std::string_view option = argv[index];
if (option == "--stage-spk")
if (option == "--ipc-script")
{
// One script, given once (ProbeScript.h).
if (script_path || index + 1 == argc)
{
std::cerr << "--ipc-script takes one file, once\n";
return 2;
}
script_path = argv[++index];
}
else if (option == "--stage-spk")
{
// One package file, given once (ProbeStaging.h).
if (package_path || index + 1 == argc)
@@ -338,6 +416,9 @@ int main(int argc, char** argv)
std::optional<std::vector<u8>> package;
if (package_path && !(package = ReadPackage(*package_path)))
return STAGING_EXIT_STATUS;
std::optional<ScriptRunner> script;
if (script_path && !(script = ReadScript(*script_path)))
return SCRIPT_EXIT_STATUS;
// The Starlet shares MEM1 and MEM2 with Broadway. Back them as on a retail Wii (24 and 64 MiB,
// zeroed): without them, any Starlet access there, such as StarOS reading its SBR1 record
@@ -358,7 +439,7 @@ int main(int argc, char** argv)
memory.Write_U32(SBR1_MAGIC, SBR1_BASE);
}
const bool passed = Run(argv[1], jit, mmu_faults, sbr1, expected, cycles.value_or(DEFAULT_CYCLES),
package ? &*package : nullptr);
package ? &*package : nullptr, script ? &*script : nullptr);
if (sbr1 != SBR1Mode::None)
{
// The record's summary after the run; with --sbr1-absent every word must still be zero (an