Prog OS - wowjinxy/libPorpoise GitHub Wiki

Prog - OS

Scope

Core OS services used by libPorpoise and demos: threads, alarms, message queues, heaps, timing, panic/report, reset flow, memory helpers.

API Coverage

  • Implemented (runtime-critical):
    • OS.c, OSAlloc.c, OSThread.c/.cpp, OSMessage.c, OSAlarm.c, OSMutex.c, OSSemaphore.c, OSTime.c, OSReset.c
  • Partial (works, but parity caveats):
    • OSInterrupt.c, OSMemory.c, OSFont.c, OSRtc.c
  • Stub-heavy / compatibility-only:
    • OSContext.c, OSUart.c, init stubs in os/init/*

Behavior Notes

  • Heap auto-init exists for PC convenience (OSAlloc: Auto-initialized default heap).
  • Alarm API is wired, but OSCreateAlarm is effectively a compatibility no-op on PC because alarm core setup happens in OSInit.
  • Shutdown/reset pipeline is implemented for desktop process lifecycle.
  • OSReport recursion guard is active and has appeared in real runs.

Known Issues

  • Threading parity: replace current TLS placeholder path in OSThread.c with true per-thread storage.
  • Scheduler/queue parity: remove remaining thread queue/scheduler stubs in OSThread.c.
  • Context fidelity: OSContext.c still uses no-op/placeholder behavior for PPC context semantics.
  • Memory protection parity: finish advanced protection path in OSMemory.c (TODO noted in source).
  • RTC parity: __OSSetRTC currently logs as not implemented on PC.
  • Font system parity: several OSFont.c functions are compatibility stubs.

Validation

  • Demos tested: multiple GX demos stable through long runs (thread/alarm/message usage).
  • Pikmin impact: startup, loading threads, message queues, retrace loop, and reset/shutdown paths are active.
  • Last verified commit: 6879cd0 (project), 3c58a4c (wiki scaffold).

Next Work (Checklist)

  1. Build an OS conformance matrix page mapping each public OS API to: implemented / partial / stub.
  2. Add focused stress tests for OSSendMessage/OSReceiveMessage queue behavior under contention.
  3. Replace OSThread.c scheduler stubs with deterministic condition-variable backed behavior.
  4. Define and document explicit "intentional deviations" from SDK semantics (PC-only behavior).
  5. Add regression notes for every observed [OSReport] Recursion detected! event (root cause + fix).

API Matrix

First-pass Matrix Scan

  • Functions listed in matrix: 128
  • Symbol-present in src/os + include/dolphin/os: 107
  • Marked Missing by first-pass scan: 21
  • Note: this is symbol-presence triage, not full behavior parity verification.