From 9d66381b3de80e261ce2e5d8f75a8008a864205d Mon Sep 17 00:00:00 2001 From: Yaya48 <34249303+Yaya48@users.noreply.github.com> Date: Sun, 1 Nov 2026 18:36:14 +0100 Subject: [PATCH] StarletBootstrapProbe: --stage-spk StarOS's I2-C image admits its User services from an SPK1 package that the loader stages in MEM2 before the Starlet's first instruction (StarOS docs/contracts/spk-staging.md). --stage-spk places the file at the package window's base, 0x13720000, once the image is loaded: the address is the contract's, never an argument. The bytes are copied as the file holds them (big-endian words) and read back before the first instruction; a window that does not read back fails the run. The file is read and checked before anything is set up. A missing or unreadable file, an empty one, one whose length is not whole 32-bit words or that exceeds the 128 KiB window ends the run with its reason on stderr and exit status 4, before StarOS starts. The option given twice or without its file is a usage error (exit 2). The probe checks none of SPK1's fields or digests: that is StarOS's job. The size rule and the window are in ProbeStaging.h, tested by StarletProbeStagingTest. Without the option the probe runs as before. Co-Authored-By: Claude Opus 5.5 --- Source/UnitTests/Core/CMakeLists.txt | 3 + .../Core/IOS/Starlet/ProbeStagingTest.cpp | 42 ++++++++++ Tools/StarletBootstrapProbe/ProbeStaging.h | 37 +++++++++ .../StarletBootstrapProbe.cpp | 77 +++++++++++++++++-- 4 files changed, 153 insertions(+), 6 deletions(-) create mode 100644 Source/UnitTests/Core/IOS/Starlet/ProbeStagingTest.cpp create mode 100644 Tools/StarletBootstrapProbe/ProbeStaging.h diff --git a/Source/UnitTests/Core/CMakeLists.txt b/Source/UnitTests/Core/CMakeLists.txt index 52a00f237c..833426f78d 100644 --- a/Source/UnitTests/Core/CMakeLists.txt +++ b/Source/UnitTests/Core/CMakeLists.txt @@ -25,6 +25,9 @@ target_include_directories(StarletProbeBudgetTest PRIVATE ${CMAKE_SOURCE_DIR}/To # StarletBootstrapProbe's SBR1 ring text (Tools/StarletBootstrapProbe/ProbeRing.h). add_dolphin_test(StarletProbeRingTest IOS/Starlet/ProbeRingTest.cpp) target_include_directories(StarletProbeRingTest PRIVATE ${CMAKE_SOURCE_DIR}/Tools/StarletBootstrapProbe) +# StarletBootstrapProbe's --stage-spk checks (Tools/StarletBootstrapProbe/ProbeStaging.h). +add_dolphin_test(StarletProbeStagingTest IOS/Starlet/ProbeStagingTest.cpp) +target_include_directories(StarletProbeStagingTest PRIVATE ${CMAKE_SOURCE_DIR}/Tools/StarletBootstrapProbe) add_dolphin_test(StarletDMATest IOS/Starlet/DMATest.cpp) add_dolphin_test(StarletSRAMReadTest IOS/Starlet/SRAMReadTest.cpp) add_dolphin_test(StarletSRAMWriteTest IOS/Starlet/SRAMWriteTest.cpp) diff --git a/Source/UnitTests/Core/IOS/Starlet/ProbeStagingTest.cpp b/Source/UnitTests/Core/IOS/Starlet/ProbeStagingTest.cpp new file mode 100644 index 0000000000..c453b01049 --- /dev/null +++ b/Source/UnitTests/Core/IOS/Starlet/ProbeStagingTest.cpp @@ -0,0 +1,42 @@ +// Copyright 2026 Dolphin Emulator Project +// SPDX-License-Identifier: GPL-2.0-or-later + +#include + +#include "ProbeStaging.h" + +namespace StarletBootstrapProbe +{ +namespace +{ +TEST(StarletProbeStaging, TheWindowIsTheContracts) +{ + // StarOS docs/contracts/spk-staging.md: 0x13720000..0x13740000, in MEM2. + EXPECT_EQ(SPK_WINDOW_BASE, u32{0x13720000}); + EXPECT_EQ(SPK_WINDOW_SIZE, u32{128 * 1024}); + EXPECT_EQ(SPK_WINDOW_BASE % 4, u32{0}); + EXPECT_LE(u64{SPK_WINDOW_BASE} + SPK_WINDOW_SIZE, u64{0x14000000}); +} + +TEST(StarletProbeStaging, AcceptsWholeWordsUpToTheWindow) +{ + for (const u64 size : + {u64{4}, u64{16}, u64{10800}, u64{SPK_WINDOW_SIZE - 4}, u64{SPK_WINDOW_SIZE}}) + { + EXPECT_FALSE(StagingRefusal(size).has_value()) << size; + } +} + +TEST(StarletProbeStaging, RefusesEmptyPartialOrOversizedFiles) +{ + EXPECT_EQ(StagingRefusal(0), "it is empty"); + for (const u64 size : {u64{1}, u64{2}, u64{3}, u64{5}, u64{10801}, u64{SPK_WINDOW_SIZE - 1}}) + EXPECT_EQ(StagingRefusal(size), "its length is not a whole number of 32-bit words") << size; + for (const u64 size : {u64{SPK_WINDOW_SIZE + 4}, u64{16} * 1024 * 1024, u64{1} << 40}) + EXPECT_EQ(StagingRefusal(size), "it is larger than the 128 KiB package window") << size; + // Not whole words and too large: the words' refusal first. + EXPECT_EQ(StagingRefusal(SPK_WINDOW_SIZE + 1), + "its length is not a whole number of 32-bit words"); +} +} // namespace +} // namespace StarletBootstrapProbe diff --git a/Tools/StarletBootstrapProbe/ProbeStaging.h b/Tools/StarletBootstrapProbe/ProbeStaging.h new file mode 100644 index 0000000000..95714ea8da --- /dev/null +++ b/Tools/StarletBootstrapProbe/ProbeStaging.h @@ -0,0 +1,37 @@ +// Copyright 2026 Dolphin Emulator Project +// SPDX-License-Identifier: GPL-2.0-or-later + +#pragma once + +#include +#include + +#include "Common/CommonTypes.h" + +// StarletBootstrapProbe's --stage-spk : StarOS's SPK1 service package, placed in MEM2 at +// the package window's base once the image is loaded, before the first ARM instruction (StarOS +// docs/contracts/spk-staging.md). The window is the contract's, never an argument, so that a run +// cannot stage elsewhere. The probe only places bytes: SPK1's fields and digests are StarOS's to +// check. +namespace StarletBootstrapProbe +{ +constexpr u32 SPK_WINDOW_BASE = 0x13720000; +constexpr u32 SPK_WINDOW_SIZE = 0x20000; + +// Exit status of a run whose package file is refused before StarOS starts (1: failed +// expectation, 2: usage, 3: Dolphin alert). +constexpr int STAGING_EXIT_STATUS = 4; + +// Why a package file of `size` bytes cannot be staged, or nullopt when it can: not empty, whole +// 32-bit words, at most the window. +inline std::optional StagingRefusal(u64 size) +{ + if (size == 0) + return "it is empty"; + if (size % 4 != 0) + return "its length is not a whole number of 32-bit words"; + if (size > SPK_WINDOW_SIZE) + return "it is larger than the 128 KiB package window"; + return std::nullopt; +} +} // namespace StarletBootstrapProbe diff --git a/Tools/StarletBootstrapProbe/StarletBootstrapProbe.cpp b/Tools/StarletBootstrapProbe/StarletBootstrapProbe.cpp index bf228fb6d4..98201fc45e 100644 --- a/Tools/StarletBootstrapProbe/StarletBootstrapProbe.cpp +++ b/Tools/StarletBootstrapProbe/StarletBootstrapProbe.cpp @@ -20,6 +20,7 @@ #include "Core/System.h" #include "ProbeBudget.h" #include "ProbeRing.h" +#include "ProbeStaging.h" #include "StarOSPanicCheck.h" namespace @@ -50,8 +51,39 @@ bool FailOnAlert(const char* caption, const char* text, bool, Common::MsgType) std::_Exit(ALERT_EXIT_STATUS); } +// Reads the package file for --stage-spk: its bytes, or nullopt once the reason is on stderr (a +// missing or unreadable file; a length StagingRefusal refuses). +std::optional> ReadPackage(const std::string& path) +{ + std::ifstream file(path, std::ios::binary | std::ios::ate); + if (!file) + { + std::cerr << "--stage-spk: cannot open the package file: " << path << '\n'; + return std::nullopt; + } + const std::streamoff end = file.tellg(); + if (end < 0) + { + std::cerr << "--stage-spk: cannot size the package file: " << path << '\n'; + return std::nullopt; + } + if (const auto refusal = StagingRefusal(static_cast(end))) + { + std::cerr << "--stage-spk: refused " << path << " (" << end << " bytes): " << *refusal << '\n'; + return std::nullopt; + } + std::vector package(static_cast(end)); + file.seekg(0); + if (!file.read(reinterpret_cast(package.data()), end)) + { + std::cerr << "--stage-spk: cannot read the package file: " << path << '\n'; + return std::nullopt; + } + return package; +} + bool Run(const std::string& path, bool jit, bool mmu_faults, SBR1Mode sbr1, - ExpectedOutcome expected, u64 cycles) + ExpectedOutcome expected, u64 cycles, const std::vector* package) { std::ifstream file(path, std::ios::binary | std::ios::ate); if (!file || file.tellg() <= 0 || file.tellg() > 16 * 1024 * 1024) @@ -80,6 +112,22 @@ bool Run(const std::string& path, bool jit, bool mmu_faults, SBR1Mode sbr1, std::cerr << error << '\n'; return false; } + if (package) + { + // The image loaded, then the package at the window's base, its bytes as the file holds them + // (big-endian words, as the Starlet reads them); read back before the first instruction. + auto& mem2 = system.GetMemory(); + mem2.CopyToEmu(SPK_WINDOW_BASE, package->data(), package->size()); + std::vector staged(package->size()); + mem2.CopyFromEmu(staged.data(), SPK_WINDOW_BASE, staged.size()); + if (staged != *package) + { + std::cerr << "--stage-spk: the package window does not read back as staged\n"; + return false; + } + std::cerr << "Staged SPK package: " << package->size() << " bytes at 0x" << std::hex + << SPK_WINDOW_BASE << std::dec << '\n'; + } IOS::LLE::ARMCore core(memory); // Declared after memory, so destroyed first. @@ -212,12 +260,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 > 8) + if (argc < 2 || argc > 10) { std::cerr << "Usage: StarletBootstrapProbe [--jit] [--mmu-faults] " "[--sbr1-record|--sbr1-absent] " "[--expect-panic|--expect-fatal-data|--expect-undefined-fault|--expect-phase2] " - "[--cycles ]\n"; + "[--cycles ] [--stage-spk ]\n"; return 2; } bool jit = false; @@ -226,10 +274,21 @@ int main(int argc, char** argv) ExpectedOutcome expected = ExpectedOutcome::Idle; bool outcome_selected = false; std::optional cycles; + std::optional package_path; for (int index = 2; index < argc; ++index) { const std::string_view option = argv[index]; - if (option == "--cycles") + if (option == "--stage-spk") + { + // One package file, given once (ProbeStaging.h). + if (package_path || index + 1 == argc) + { + std::cerr << "--stage-spk takes one package file, once\n"; + return 2; + } + package_path = argv[++index]; + } + else if (option == "--cycles") { // A whole number of slices, at most MAX_CYCLES (ProbeBudget.h); given once. if (cycles || index + 1 == argc || !(cycles = ParseCycles(argv[index + 1]))) @@ -274,6 +333,12 @@ int main(int argc, char** argv) } } + // The package file read and checked before anything is set up: a refused file ends the run + // before StarOS starts. + std::optional> package; + if (package_path && !(package = ReadPackage(*package_path))) + return STAGING_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 // header at 0x00200000, is an access to unmapped memory and raises an alert. @@ -292,8 +357,8 @@ int main(int argc, char** argv) memory.Write_U32(SBR1_RELAY_JUMPING, SBR1_BASE + SBR1_RELAY_STATUS); memory.Write_U32(SBR1_MAGIC, SBR1_BASE); } - const bool passed = - Run(argv[1], jit, mmu_faults, sbr1, expected, cycles.value_or(DEFAULT_CYCLES)); + const bool passed = Run(argv[1], jit, mmu_faults, sbr1, expected, cycles.value_or(DEFAULT_CYCLES), + package ? &*package : nullptr); if (sbr1 != SBR1Mode::None) { // The record's summary after the run; with --sbr1-absent every word must still be zero (an