Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ jobs:
run: ctest --test-dir build --output-on-failure

macos:
runs-on: macos-14
runs-on: macos-15
steps:
- uses: actions/checkout@v4
- name: Toolchain
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ jobs:
runner: ubuntu-22.04-arm
# One universal binary; its x86_64 slice is run under Rosetta.
- platform: macos-universal
runner: macos-14
runner: macos-15
- platform: windows-x86_64
runner: windows-2022
runs-on: ${{ matrix.runner }}
Expand Down
37 changes: 37 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,35 @@ if(RETRO_RUNTIME_TOOLS)
-DRUNNER=$<TARGET_FILE:retro-core-runner> -DCORE=$<TARGET_FILE:rcore_fake_core>
-DLINK=$<TARGET_FILE:retro-core-link-test> -DOUT=${CMAKE_CURRENT_BINARY_DIR}/route-integration
-P ${CMAKE_CURRENT_SOURCE_DIR}/tests/route_test.cmake)
add_test(NAME cpu_target_routes COMMAND ${CMAKE_COMMAND}
-DRUNNER=$<TARGET_FILE:retro-core-runner> -DCORE=$<TARGET_FILE:rcore_fake_core>
-DLINK=$<TARGET_FILE:retro-core-link-test> -DOUT=${CMAKE_CURRENT_BINARY_DIR}/cpu-target-routes
-P ${CMAKE_CURRENT_SOURCE_DIR}/tests/route_test.cmake)
set_tests_properties(cpu_target_routes PROPERTIES ENVIRONMENT "FAKE_CORE_CPU_TARGET=2")
add_test(NAME cpu_target_link COMMAND ${CMAKE_COMMAND}
-DRUNNER=$<TARGET_FILE:retro-core-runner> -DCORE=$<TARGET_FILE:rcore_fake_core>
-DLINK_TEST=$<TARGET_FILE:retro-core-link-test> -DROM=${CMAKE_CURRENT_SOURCE_DIR}/LICENSE
-DOUT=${CMAKE_CURRENT_BINARY_DIR}/cpu-target-link
-P ${CMAKE_CURRENT_SOURCE_DIR}/tests/cpu_target_test.cmake)
set_tests_properties(cpu_target_link PROPERTIES ENVIRONMENT "FAKE_CORE_CPU_TARGET=1")
add_test(NAME cpu_target_refusal COMMAND ${CMAKE_COMMAND}
-DRUNNER=$<TARGET_FILE:retro-core-runner> -DCORE=$<TARGET_FILE:rcore_fake_core>
-DLINK_TEST=$<TARGET_FILE:retro-core-link-test> -DROM=${CMAKE_CURRENT_SOURCE_DIR}/LICENSE
-DOUT=${CMAKE_CURRENT_BINARY_DIR}/cpu-target-refusal -DREFUSE=ON
-P ${CMAKE_CURRENT_SOURCE_DIR}/tests/cpu_target_test.cmake)
set_tests_properties(cpu_target_refusal PROPERTIES ENVIRONMENT "FAKE_CORE_CPU_TARGET=3")
add_test(NAME cpu_repeat_link COMMAND ${CMAKE_COMMAND}
-DRUNNER=$<TARGET_FILE:retro-core-runner> -DCORE=$<TARGET_FILE:rcore_fake_core>
-DLINK_TEST=$<TARGET_FILE:retro-core-link-test> -DROM=${CMAKE_CURRENT_SOURCE_DIR}/LICENSE
-DOUT=${CMAKE_CURRENT_BINARY_DIR}/cpu-repeat-link
-P ${CMAKE_CURRENT_SOURCE_DIR}/tests/cpu_repeat_test.cmake)
set_tests_properties(cpu_repeat_link PROPERTIES ENVIRONMENT "FAKE_CORE_CPU_TARGET=4")
add_test(NAME cpu_pixel_pairs_link COMMAND ${CMAKE_COMMAND}
-DRUNNER=$<TARGET_FILE:retro-core-runner> -DCORE=$<TARGET_FILE:rcore_fake_core>
-DLINK_TEST=$<TARGET_FILE:retro-core-link-test> -DROM=${CMAKE_CURRENT_SOURCE_DIR}/LICENSE
-DOUT=${CMAKE_CURRENT_BINARY_DIR}/cpu-pixel-pairs-link
-P ${CMAKE_CURRENT_SOURCE_DIR}/tests/cpu_pixel_pairs_test.cmake)
set_tests_properties(cpu_pixel_pairs_link PROPERTIES ENVIRONMENT "FAKE_CORE_CPU_TARGET=5")
add_test(NAME route_watch COMMAND ${CMAKE_COMMAND}
-DRUNNER=$<TARGET_FILE:retro-core-runner> -DCORE=$<TARGET_FILE:rcore_fake_core>
-DLINK=$<TARGET_FILE:retro-core-link-test> -DOUT=${CMAKE_CURRENT_BINARY_DIR}/route-watch
Expand Down Expand Up @@ -277,6 +306,14 @@ if(RETRO_RUNTIME_TOOLS)
add_executable(retro-presentation-protocol-test tests/presentation_protocol_test.cpp)
target_link_libraries(retro-presentation-protocol-test PRIVATE retro_corelink)
add_test(NAME presentation_protocol COMMAND retro-presentation-protocol-test)
add_test(NAME link_video_demand
COMMAND ${CMAKE_COMMAND}
-DLINK_TEST=$<TARGET_FILE:retro-core-link-test>
-DRUNNER=$<TARGET_FILE:retro-core-runner>
-DCORE=$<TARGET_FILE:rcore_fake_core>
-DROM=${CMAKE_CURRENT_SOURCE_DIR}/LICENSE
-DOUT=${CMAKE_CURRENT_BINARY_DIR}/test-video-demand
-P ${CMAKE_CURRENT_SOURCE_DIR}/tests/video_demand_test.cmake)
# Link 2.2: FrameDone carries the game's count and the runner's timing.
add_test(NAME link_frame_stats
COMMAND retro-core-link-test --runner $<TARGET_FILE:retro-core-runner>
Expand Down
11 changes: 10 additions & 1 deletion corelink/core_link.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -293,6 +293,11 @@ void CoreLink::handle_packet(const std::vector<unsigned char>& buf,
}

bool CoreLink::grant(const rcore_pad pads[RCORE_MAX_SEATS], std::uint32_t width, std::uint32_t height) {
return grant(pads,width,height,true);
}

bool CoreLink::grant(const rcore_pad pads[RCORE_MAX_SEATS], std::uint32_t width, std::uint32_t height,
bool video_requested) {
if (!can_grant()) return false;
GrantMsg g{};
g.h.type = Msg::Grant;
Expand All @@ -302,7 +307,11 @@ bool CoreLink::grant(const rcore_pad pads[RCORE_MAX_SEATS], std::uint32_t width,
g.presentation_width = width;
g.presentation_height = height;
}
const auto bytes = link_has_presentation_size(identity_.protocol_minor) ? sizeof(g) : kGrantSize22;
if (!video_requested) g.flags |= kGrantSkipVideo;
if (spec_.cpu_pixel_pairs && link_has_cpu_pixel_pairs(identity_.protocol_minor))
g.flags |= kGrantCpuPixelPairs;
const auto bytes = link_has_video_demand(identity_.protocol_minor) ? sizeof(g)
: link_has_presentation_size(identity_.protocol_minor) ? kGrantSize25 : kGrantSize22;
if (!send_msg_sized(channel_, g, bytes)) return false;
++granted_;
++outstanding_;
Expand Down
5 changes: 5 additions & 0 deletions corelink/core_link.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ struct LaunchSpec {
fs::path session_dir; // runner.log, core.log, events.tsv, the core's cache
bool gl = true;
bool strict = false;
// Actual frontend can reconstruct exact horizontal pairs before filtering.
bool cpu_pixel_pairs = false;
rcore_gpu_capabilities gpu_capabilities{}; // actual local import support, sampled once
std::map<std::string, std::string> options;
std::optional<fs::path> load_state;
Expand Down Expand Up @@ -160,6 +162,9 @@ class CoreLink {
// Available physical pixels before letterboxing; zeros when unknown.
bool grant(const rcore_pad pads[RCORE_MAX_SEATS], std::uint32_t width = 0,
std::uint32_t height = 0);
// Presentation-only permission; old runners/cores may still send video.
bool grant(const rcore_pad pads[RCORE_MAX_SEATS], std::uint32_t width,
std::uint32_t height, bool video_requested);
std::uint64_t frames_granted() const { return granted_; }
std::uint64_t frames_done() const { return done_; }
const FrameStats& frame_stats() const { return stats_; }
Expand Down
12 changes: 10 additions & 2 deletions corelink/link_protocol.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,11 @@ constexpr std::uint32_t kProtocolMajor = 2;
// 2.3: Grant appends the available drawable pixel area (rcore rev 9).
// 2.4: optional core-owned GPU rings, native handle transfer and release events.
// 2.5: between-frame replay recording controls and authoritative status.
constexpr std::uint32_t kProtocolMinor = 5;
// 2.6: Grant appends presentation-only permission to omit unobserved video.
// 2.7: optional Grant flag enables exact RGBA8 horizontal-pair reconstruction.
constexpr std::uint32_t kProtocolMinor = 7;
constexpr bool link_has_cpu_pixel_pairs(std::uint32_t peer_minor) { return peer_minor >= 7; }
constexpr bool link_has_video_demand(std::uint32_t peer_minor) { return peer_minor >= 6; }
constexpr bool link_has_replays(std::uint32_t peer_minor) { return peer_minor >= 5; }
constexpr bool link_has_gpu_frames(std::uint32_t peer_minor) {
return kProtocolMajor > 2 || peer_minor >= 4;
Expand Down Expand Up @@ -299,8 +303,12 @@ struct GrantMsg {
rcore_pad pads[RCORE_MAX_SEATS];
// 2.3: before letterboxing; both zero means unavailable.
std::uint32_t presentation_width, presentation_height;
std::uint32_t flags, _pad26;
};
constexpr std::size_t kGrantSize22 = 240;
constexpr std::size_t kGrantSize25 = 248;
constexpr std::uint32_t kGrantSkipVideo = 1;
constexpr std::uint32_t kGrantCpuPixelPairs = 2; // optional logical-width2 RGBA8 reconstruction

struct EmptyMsg {
MsgHeader h;
Expand Down Expand Up @@ -432,7 +440,7 @@ static_assert(offsetof(ExitingMsg, reason) == 12, "ExitingMsg::reason");
static_assert(sizeof(SavesFilledMsg) == 232 && alignof(SavesFilledMsg) == 4, "SavesFilledMsg");
static_assert(offsetof(SavesFilledMsg, h) == 0, "SavesFilledMsg::h");
static_assert(offsetof(SavesFilledMsg, pads) == 8, "SavesFilledMsg::pads");
static_assert(sizeof(GrantMsg) == 248 && alignof(GrantMsg) == 8, "GrantMsg");
static_assert(sizeof(GrantMsg) == 256 && alignof(GrantMsg) == 8, "GrantMsg");
static_assert(offsetof(GrantMsg, h) == 0, "GrantMsg::h");
static_assert(offsetof(GrantMsg, frame_number) == 8, "GrantMsg::frame_number");
static_assert(offsetof(GrantMsg, pads) == 16, "GrantMsg::pads");
Expand Down
65 changes: 57 additions & 8 deletions corelink/link_test_main.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,9 @@ using namespace retro::corelink;
namespace {
constexpr std::uint32_t kLeft = 1u << 20, kRight = 1u << 21,
kUp = 1u << 22, kDown = 1u << 23;
constexpr std::uint32_t kStick = kLeft | kRight | kUp | kDown;
constexpr std::uint32_t kRLeft = 1u << 24, kRRight = 1u << 25,
kRUp = 1u << 26, kRDown = 1u << 27;
constexpr std::uint32_t kStick = kLeft | kRight | kUp | kDown | kRLeft | kRRight | kRUp | kRDown;

[[noreturn]] void die(const std::string& m) {
std::fprintf(stderr, "retro-core-link-test: %s\n", m.c_str());
Expand Down Expand Up @@ -70,6 +72,10 @@ std::uint32_t script_buttons(const std::string& s) {
else if (t == "right") b |= kRight;
else if (t == "up") b |= kUp;
else if (t == "down") b |= kDown;
else if (t == "rleft") b |= kRLeft;
else if (t == "rright") b |= kRRight;
else if (t == "rup") b |= kRUp;
else if (t == "rdown") b |= kRDown;
else die("--input-script: unknown button '" + t + "'");
if (plus == std::string::npos) break;
start = plus + 1;
Expand All @@ -86,8 +92,12 @@ int main(int argc, char** argv) {
LaunchSpec spec;
spec.gl = false;
std::uint64_t frames = 60;
std::uint64_t video_every = 1, pictures = 0;
bool pcm_hash = false;
std::uint64_t pcm = 0xcbf29ce484222325ull, audio_frames = 0;
bool seat0 = true;
bool presentation_test = false;
bool unpaced = false, cpu_repeat_test = false, cpu_pairs_test = false;
bool expect_route_end = false;
std::string restart_route;
std::vector<std::pair<std::uint64_t, std::uint32_t>> script;
Expand Down Expand Up @@ -134,6 +144,12 @@ int main(int argc, char** argv) {
else if (a == "--title-dir") spec.title_dir = utf8_path(val());
else if (a == "--out") spec.session_dir = utf8_path(val());
else if (a == "--frames") frames = std::strtoull(val().c_str(), nullptr, 10);
else if (a == "--video-every") video_every = std::strtoull(val().c_str(), nullptr, 10);
else if (a == "--pcm-hash") pcm_hash = true;
else if (a == "--cpu-pixel-pairs") spec.cpu_pixel_pairs = true;
else if (a == "--unpaced") { unpaced = true; spec.extra_args.push_back("--unpaced"); }
else if (a == "--cpu-repeat-test") cpu_repeat_test = true;
else if (a == "--cpu-pixel-pairs-test") cpu_pairs_test = true;
else if (a == "--load-state") spec.load_state = utf8_path(val());
else if (a.size() >= 11 && a.compare(0, 6, "--tpak") == 0 && a[6] >= '1' && a[6] <= '4') {
const std::size_t seat = static_cast<std::size_t>(a[6] - '1');
Expand Down Expand Up @@ -273,11 +289,14 @@ int main(int argc, char** argv) {
pads[0].buttons &= ~kStick;
pads[0].axes[RCORE_AXIS_LX] = held & kLeft ? -32767 : held & kRight ? 32767 : 0;
pads[0].axes[RCORE_AXIS_LY] = held & kUp ? 32767 : held & kDown ? -32767 : 0;
pads[0].axes[RCORE_AXIS_RX] = held & kRLeft ? -32767 : held & kRRight ? 32767 : 0;
pads[0].axes[RCORE_AXIS_RY] = held & kRUp ? 32767 : held & kRDown ? -32767 : 0;
}
// Fixture exercises resize, unavailable/minimized, then recovery.
const std::uint32_t pw = presentation_test && k != 3 ? (k == 1 ? 1280 : 2560) : 0;
const std::uint32_t ph = presentation_test && k != 3 ? (k == 1 ? 720 : 1080) : 0;
if (!link.grant(pads, pw, ph)) {
const bool video_requested = k==frames || (video_every && k%video_every==0);
if (!link.grant(pads, pw, ph, video_requested)) {
if (expect_route_end) {
link.pump(100);
if (link.state()==LinkState::Ended && !link.exit_code()) break;
Expand All @@ -288,9 +307,35 @@ int main(int argc, char** argv) {
print_notifies();
const bool clean_route_end = expect_route_end && link.state()==LinkState::Ended && !link.exit_code();
if (link.state() != LinkState::Ready && !clean_route_end) ok = false;
link.take_frame();
if (link.take_frame()) ++pictures;
if (cpu_repeat_test) {
const auto* f = link.frame_info();
const auto* pixels = link.frame_pixels();
const auto published = unpaced && !(k & 1) ? k - 1 : k;
if (!f || !pixels || f->frame_number != published || f->width != 64 || f->height != 48 ||
link.frame_stats().game_frame != k / 2) die("CPU repeat changed metadata or lost progress");
for (std::size_t i = 0; i < std::size_t(f->stride) * f->height; ++i)
if (pixels[i] != (k + 1) / 2) die("CPU repeat changed per-field pixels");
}
if (cpu_pairs_test) {
const auto* f=link.frame_info(); const auto* px=link.frame_pixels();
if(!f || !px || f->height!=48 || link.frame_stats().game_frame!=k/2)
die("CPU pixel pairs lost progress/geometry");
const auto repeat=f->pixel_format==RCORE_PIXEL_RGBA8_X2 ? 2u : 1u;
if(f->width*repeat!=64 || f->stride!=f->width*4)
die("CPU pixel pairs changed logical geometry");
for(unsigned y=0;y<48;++y) for(unsigned x=0;x<64;++x) for(unsigned c=0;c<4;++c)
if(px[y*f->stride+(x/repeat)*4+c]!=static_cast<unsigned char>((k+1)/2+x/2+3*y+c))
die("CPU pixel pairs changed a logical pixel");
}
std::int16_t sink[4096];
while (link.drain_audio(sink, 2048)) {
while (const auto n = link.drain_audio(sink, 2048)) {
audio_frames += n;
if (pcm_hash) for (std::size_t i=0;i<n*2;++i) {
const auto v=static_cast<std::uint16_t>(sink[i]);
pcm=(pcm^(v&255u))*0x100000001b3ull;
pcm=(pcm^(v>>8))*0x100000001b3ull;
}
}
if (clean_route_end) break;
for (const StateOp& op : record_ops) {
Expand Down Expand Up @@ -343,11 +388,12 @@ int main(int argc, char** argv) {
// ---- the artifacts headless mode writes ----------------------------------
if (const FrameInfo* f = link.frame_info()) {
std::ofstream shot(spec.session_dir / "shot.ppm", std::ios::binary);
shot << "P6\n" << f->width << ' ' << f->height << "\n255\n";
const std::uint32_t repeat = f->pixel_format == RCORE_PIXEL_RGBA8_X2 ? 2 : 1;
shot << "P6\n" << f->width * repeat << ' ' << f->height << "\n255\n";
const std::uint8_t* px = link.frame_pixels();
for (std::size_t i = 0; i < std::size_t(f->width) * f->height; ++i) {
shot.write(reinterpret_cast<const char*>(px + i * 4), 3);
}
for (std::uint32_t y = 0; y < f->height; ++y)
for (std::uint32_t x = 0; x < f->width * repeat; ++x)
shot.write(reinterpret_cast<const char*>(px + std::size_t(y) * f->stride + (x / repeat) * 4), 3);
}
{
std::ifstream log(spec.session_dir / "core.log");
Expand All @@ -366,6 +412,9 @@ int main(int argc, char** argv) {
std::printf("picture: first byte %u\n", unsigned(link.frame_pixels()[0]));
}
// 2.2: what the overlay's readout is made of.
std::printf("pictures received: %llu\n",static_cast<unsigned long long>(pictures));
if (pcm_hash) std::printf("PCM_HASH %016llx over %llu samples\n",
static_cast<unsigned long long>(pcm),static_cast<unsigned long long>(audio_frames*2));
std::printf("frame stats: game %llu work %s\n",
static_cast<unsigned long long>(link.frame_stats().game_frame),
link.frame_stats().work_ns ? "measured" : "none");
Expand Down
3 changes: 3 additions & 0 deletions docs/CORE_ABI.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,9 @@ only the shape of the contract and why.
| Rev | Date | Change |
|---|---|---|
| 1 | 2026-09-23 | First draft. |
| 14 | 2026-11-15 | CPU targets append `flags` and padding after the rev13 prefix. An explicitly unpaced host may advertise `RCORE_CPU_VIDEO_REPEAT_PREVIOUS`: submitting the exact previous image with unchanged geometry and aspect advances observers/progress without copying or republishing shared storage. Pixels stay read-only at the same address until a non-repeat publication. Hosts clip output to the caller's supplied target size; older targets remain supported. The host callback/table and link layout are unchanged. |
| 13 | 2026-11-15 | Optional appended host `video_acquire_cpu` lends a writable CPU image for the current field. Existing `video_submit` commits the exact active loan without a copy. A committed image remains read-only until the next publication; previous-image geometry is explicit. Missing/refused acquisition retains ordinary submission. Loans expire at submission or field return; cores preserve their own scanout history across fallback, omitted output, resize and restore. No shared frame-region or link layout change. |
| 12 | 2026-11-15 | Optional appended host `video_requested(ctx, field, game_frame)` permits omitting video on an unobserved field. An absent callback requests every picture. Simulation, audio, input, device completion and correctness observers still run; internal display history may require a scanout despite permission to omit. Presentation state only, excluded from saves and netplay identity. |
| 11 | 2026-10-19 | Optional `RCORE_CAP_GPU_FRAMES` and five appended host callbacks for a fixed actual-device offer, image-ring registration, resource status, shared-frame submission and retirement. CPU RGBA8 remains the fallback; no generated game ABI change. See [GPU_FRAMES.md](GPU_FRAMES.md). |
| 10 | 2026-10-14 | Optional pre-init `execution_profiles()` capability/qualification query; appended init `execution_profile` index, valid with `RCORE_INIT_PROFILE_AGREED`. The runner exchanges offers/ACKs before init/guest boot, folds the common profile and canonical capability transcript into existing netplay identity, and keeps selection fixed through replay/reset/rollback. Old runners retain the core's conservative startup default. |
| 9 | 2026-10-14 | Optional host `presentation_size(ctx, width, height)`: the available drawable physical pixel area before letterboxing, stable for a granted frame. Returns 0 and zeros when unavailable. Core checks host `struct_size` before reading the appended callback. Presentation policy only; never guest input or serialized simulation state. |
Expand Down
9 changes: 9 additions & 0 deletions docs/CORE_LINK.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,15 @@ protocol is the same on all three.

## Transport

**2.6 (2026-11-15):** `Grant` appends flags and padding (256 bytes).
`kGrantSkipVideo` permits omitting CPU/GPU video for that field; zero flags
retain every picture. The runner exposes rcore revision 12 `video_requested`
and retains field/game-picture progress even without pixels. Input, audio,
simulation and `FrameDone` still occur on every grant. Recording and replay
routes request every picture. Peers speaking 2.3–2.5 receive the unchanged
248-byte grant; peers through 2.2 receive 240 bytes. Older cores may ignore
the hint. This is local presentation policy, not serialized or netplay input.

**2.4 (2026-10-19):** optional GPU ring/frame/retirement messages 10–12,
startup capabilities 70, ownership status 71 and explicit save thumbnail 72.
The existing shared frame-region layout is unchanged. These messages require
Expand Down
Loading
Loading