Prog OS API Matrix - wowjinxy/libPorpoise GitHub Wiki

Prog - OS API Matrix

Function-by-function tracking list for libPorpoise OS coverage.

Legend:

  • Status: Untriaged / Implemented / Partial / Stub / Missing
  • Check the box when status + notes are verified against behavior and tests.

Address Conversion

  • OSPhysicalToCached - Status: Implemented - Notes: Macro implemented in include/dolphin/os/OSUtil.h (address base conversion).
  • OSPhysicalToUncached - Status: Implemented - Notes: Macro implemented in include/dolphin/os/OSUtil.h (address base conversion).
  • OSCachedToPhysical - Status: Implemented - Notes: Macro implemented in include/dolphin/os/OSUtil.h (address base conversion).
  • OSUncachedToPhysical - Status: Implemented - Notes: Macro implemented in include/dolphin/os/OSUtil.h (address base conversion).
  • OSCachedToUncached - Status: Implemented - Notes: Macro implemented in include/dolphin/os/OSUtil.h (address base conversion).
  • OSUncachedToCached - Status: Implemented - Notes: Macro implemented in include/dolphin/os/OSUtil.h (address base conversion).
  • OSRoundUp32B - Status: Implemented - Notes: Macro implemented in include/dolphin/os/OSUtil.h.
  • OSRoundDown32B - Status: Implemented - Notes: Macro implemented in include/dolphin/os/OSUtil.h.

Alarm

  • OSInitAlarm - Status: Implemented - Notes: Explicitly initializes alarm backend (InitAlarmSystem) in src/os/OSAlarm.c.
  • OSSetAlarm - Status: Implemented - Notes: One-shot scheduling via sorted queue; now safely re-arms existing alarm object by dequeuing before insert.
  • OSSetPeriodicAlarm - Status: Implemented - Notes: Periodic schedule/reschedule works and now safely re-arms existing alarm object.
  • OSCancelAlarm - Status: Implemented - Notes: Queue removal path hardened via shared locked remove helper with queue-membership validation.

Arena

  • OSAllocFromArenaHi - Status: Implemented - Notes: Implemented in src/os/OS.c; alignment-aware high-end bump allocator using uintptr_t math, returns NULL on unset arena or out-of-space.
  • OSAllocFromArenaLo - Status: Implemented - Notes: Implemented in src/os/OS.c; alignment-aware low-end bump allocator using uintptr_t math, returns NULL on unset arena or out-of-space.
  • OSGetArenaHi - Status: Implemented - Notes: Implemented in src/os/OS.c (returns current default arena high pointer).
  • OSGetArenaLo - Status: Implemented - Notes: Implemented in src/os/OS.c (returns current default arena low pointer).
  • OSSetArenaHi - Status: Implemented - Notes: Implemented in src/os/OS.c (sets default arena high pointer).
  • OSSetArenaLo - Status: Implemented - Notes: Implemented in src/os/OS.c (sets default arena low pointer).

Cache

  • DCFlushRange - Status: Implemented - Notes: Implemented in src/os/OSCache.c as PC no-op (API-compatible cache flush stub).
  • DCFlushRangeNoSync - Status: Implemented - Notes: Implemented in src/os/OSCache.c as PC no-op.
  • DCFreeze - Status: Implemented - Notes: Implemented in src/os/OSCache.c as PC no-op.
  • DCInvalidateRange - Status: Implemented - Notes: Implemented in src/os/OSCache.c as PC no-op.
  • DCStoreRange - Status: Implemented - Notes: Implemented in src/os/OSCache.c as PC no-op.
  • DCStoreRangeNoSync - Status: Implemented - Notes: Implemented in src/os/OSCache.c as PC no-op.
  • DCTouchRange - Status: Implemented - Notes: Implemented in src/os/OSCache.c as PC no-op prefetch stub.
  • DCUnfreeze - Status: Implemented - Notes: Implemented in src/os/OSCache.c as PC no-op.
  • DCZeroRange - Status: Implemented - Notes: Implemented in src/os/OSCache.c; zeros 32-byte aligned range via memset using uintptr_t-safe alignment math.
  • ICFreeze - Status: Implemented - Notes: Implemented in src/os/OSCache.c as PC no-op.
  • ICInvalidateRange - Status: Implemented - Notes: Implemented in src/os/OSCache.c as PC no-op with platform-hook comments for future instruction-cache flushing.
  • ICUnfreeze - Status: Implemented - Notes: Implemented in src/os/OSCache.c as PC no-op.
  • LCDisable - Status: Implemented - Notes: Implemented in src/os/OSCache.c; disables locked-cache state and Gecko locked-cache flag (when enabled).
  • LCEnable - Status: Implemented - Notes: Implemented in src/os/OSCache.c; enables locked-cache state and Gecko locked-cache flag (when enabled).
  • LCGetBase - Status: Implemented - Notes: Implemented as macro in include/dolphin/os/OSCache.h (((void*)LC_BASE)).
  • LCFlushQueue - Status: Implemented - Notes: Implemented in src/os/OSCache.c; instantaneous no-op on PC.
  • LCLoadBlocks - Status: Implemented - Notes: Implemented in src/os/OSCache.c; Gecko-memory-backed LC DMA copy when PORPOISE_USE_GECKO_MEMORY and LC enabled, otherwise no-op.
  • LCLoadData - Status: Implemented - Notes: Implemented in src/os/OSCache.c; batched wrapper over LCLoadBlocks (up to 128 blocks/transaction), uintptr_t-safe pointer stepping.
  • LCQueueLength - Status: Implemented - Notes: Implemented in src/os/OSCache.c; returns 0 on PC backend.
  • LCQueueWait - Status: Implemented - Notes: Implemented in src/os/OSCache.c; no-op wait on PC backend.
  • LCStoreBlocks - Status: Implemented - Notes: Implemented in src/os/OSCache.c; Gecko-memory-backed LC DMA copy-out when PORPOISE_USE_GECKO_MEMORY and LC enabled, otherwise no-op.
  • LCStoreData - Status: Implemented - Notes: Implemented in src/os/OSCache.c; batched wrapper over LCStoreBlocks, uintptr_t-safe pointer stepping.

Error

  • ASSERT - Status: Implemented - Notes: Implemented as macro in include/dolphin/os/OSAssert.h; in debug builds calls OSPanic(__FILE__, __LINE__, ...), in NDEBUG builds compiled out.
  • ASSERTMSG - Status: Implemented - Notes: Implemented as macro in include/dolphin/os/OSAssert.h; same behavior as ASSERT with explicit message text, compiled out in NDEBUG.
  • OSHalt - Status: Implemented - Notes: Implemented as macro in include/dolphin/os/OSAssert.h; forwards to OSPanic(__FILE__, __LINE__, "%s", msg).
  • OSReport - Status: Implemented - Notes: Implemented in src/os/OS.c; timestamped debug logging with format safety checks and thread-local recursion guard to avoid cross-thread false recursion.
  • OSSetErrorHandler - Status: Implemented - Notes: Implemented in src/os/OSError.c; validates error index, stores/replaces handler in __OSErrorTable, returns previous handler, logs FPE handler state changes.

FastCast

  • OSf32tos16 - Status: Implemented - Notes: Implemented in src/os/OSFastCast.c with pointer-based API; truncating conversion with clamp to s16 range, NaN -> 0.
  • OSf32tos8 - Status: Implemented - Notes: Implemented in src/os/OSFastCast.c; truncating conversion with clamp to s8 range, NaN -> 0.
  • OSf32tou16 - Status: Implemented - Notes: Implemented in src/os/OSFastCast.c; truncating conversion with clamp to u16 range, negative/NaN -> 0.
  • OSf32tou8 - Status: Implemented - Notes: Implemented in src/os/OSFastCast.c; truncating conversion with clamp to u8 range, negative/NaN -> 0.
  • OSInitFastCast - Status: Implemented - Notes: Implemented in src/os/OSFastCast.c; initializes FastCast state on PC backend (GQR setup not required on PC).
  • OSs16tof32 - Status: Implemented - Notes: Implemented in src/os/OSFastCast.c; pointer-based s16 -> f32 conversion.
  • OSs8tof32 - Status: Implemented - Notes: Implemented in src/os/OSFastCast.c; pointer-based s8 -> f32 conversion.
  • OSu16tof32 - Status: Implemented - Notes: Implemented in src/os/OSFastCast.c; pointer-based u16 -> f32 conversion.
  • OSu8tof32 - Status: Implemented - Notes: Implemented in src/os/OSFastCast.c; pointer-based u8 -> f32 conversion.

Idle Function

  • OSGetIdleFunction - Status: Implemented - Notes: Implemented in src/os/OSThread.c; returns active idle thread pointer, and returns NULL once the idle function thread completes.
  • OSSetIdleFunction - Status: Implemented - Notes: Implemented in src/os/OSThread.c; creates low-priority idle thread, fails (NULL) if previous idle function is still active, and supports cancel via idleFunction == NULL.

Initialization

  • OSGetConsoleType - Status: Implemented - Notes: Implemented in src/os/OS.c; returns PC-port console identifier (0x10000000).
  • OSInit - Status: Implemented - Notes: Implemented in src/os/OS.c; one-time OS bootstrap (thread init, arena defaults, startup reporting).
  • OSGetPhysicalMemSize - Status: Implemented - Notes: Implemented in src/os/OSMemory.c as legacy MEM1 wrapper (OSGetPhysicalMem1Size), currently returns 24 MB.
  • OSGetConsoleSimulatedMemSize - Status: Implemented - Notes: Implemented in src/os/OSMemory.c as legacy simulated-MEM1 wrapper (OSGetConsoleSimulatedMem1Size), currently returns 24 MB.

Interrupt

  • OSDisableInterrupts - Status: Implemented - Notes: Implemented in src/os/OSInterrupt.c; returns previous interrupt-enabled state and updates PC-side tracked interrupt flag (hardware IRQs cannot be disabled from user mode).
  • OSEnableInterrupts - Status: Implemented - Notes: Implemented in src/os/OSInterrupt.c; returns previous state and sets PC-side tracked interrupt flag to enabled.
  • OSRestoreInterrupts - Status: Implemented - Notes: Implemented in src/os/OSInterrupt.c; restores tracked interrupt state from provided level (non-zero normalized to enabled), returns previous state.

Memory Allocation

  • OSAddToHeap - Status: Implemented - Notes: Implemented in src/os/OSAlloc.c; validates heap/range, aligns boundaries, adds non-contiguous ranges, and coalesces via free-list insertion.
  • OSAlloc - Status: Implemented - Notes: Implemented as macro in include/dolphin/os/OSAlloc.h (OSAllocFromHeap(__OSCurrHeap, size)).
  • OSAllocFixed - Status: Partial - Notes: Implemented in src/os/OSAlloc.c; validates/fences fixed ranges and carves overlaps, but overlap splitting path is explicitly simplified and not a full SDK-equivalent splitter.
  • OSAllocFromHeap - Status: Implemented - Notes: Implemented in src/os/OSAlloc.c; first-fit allocation with 32-byte alignment, split/coalesce-compatible cells, NULL on OOM, and lazy default-heap bootstrap for ports/demos without explicit setup.
  • OSCheckHeap - Status: Implemented - Notes: Implemented in src/os/OSAlloc.c; validates list structure/range/alignment/size accounting and returns free bytes (or -1 on corruption).
  • OSCreateHeap - Status: Implemented - Notes: Implemented in src/os/OSAlloc.c; allocates an inactive descriptor, aligns bounds, initializes a single initial free cell, returns heap handle or -1.
  • OSDestroyHeap - Status: Implemented - Notes: Implemented in src/os/OSAlloc.c; deactivates heap descriptor, logs leaked-byte warning when not fully freed, and clears current heap if it was destroyed.
  • OSDumpHeap - Status: Implemented - Notes: Implemented in src/os/OSAlloc.c; emits diagnostic dump of heap totals and allocated/free cell lists.
  • OSFree - Status: Implemented - Notes: Implemented as macro in include/dolphin/os/OSAlloc.h (OSFreeToHeap(__OSCurrHeap, ptr)).
  • OSFreeToHeap - Status: Implemented - Notes: Implemented in src/os/OSAlloc.c; validates heap handle, pointer range/alignment, allocation ownership, then returns block to free list with coalescing.
  • OSInitAlloc - Status: Implemented - Notes: Implemented in src/os/OSAlloc.c; initializes descriptor table and arena bounds, with PC-port extension that auto-creates a default arena when NULL bounds are provided.
  • OSSetCurrentHeap - Status: Implemented - Notes: Implemented in src/os/OSAlloc.c; switches current heap with active-handle validation and returns previous heap handle.

Reset Button

  • OSGetResetSwitchState - Status: Implemented - Notes: Implemented in src/os/OSResetSW.c as compatibility alias to OSGetResetButtonState; on PC backend uses simulated reset input/debounced state (triggered via OSSimulateResetButton()).
  • OSSetResetCallback - Status: Implemented - Notes: Implemented in src/os/OSResetSW.c; installs callback and returns previous callback, with one-shot semantics honored when reset is simulated (OSSimulateResetButton() clears callback before invocation).

Stack

  • OSGetStackPointer - Status: Partial - Notes: Implemented in src/os/OSContext.c as best-effort PC stack-address approximation via compiler intrinsics (_AddressOfReturnAddress / __builtin_frame_address), not exact hardware PPC r1 semantics.
  • OSSwitchFiber - Status: Stub - Notes: Stubbed in src/os/OSContext.c; logs warning and returns without true stack/fiber switch on PC backend.
  • OSSwitchStack - Status: Stub - Notes: Stubbed in src/os/OSContext.c; logs warning and does not perform real stack register swap on PC backend.

Stopwatch

  • OSInitStopwatch - Status: Implemented - Notes: Implemented in src/os/OSStopwatch.c; initializes OSStopwatch state and sets stopwatch name.
  • OSStartStopwatch - Status: Implemented - Notes: Implemented in src/os/OSStopwatch.c; starts timing interval from current OSGetTime() when not already running.
  • OSStopStopwatch - Status: Implemented - Notes: Implemented in src/os/OSStopwatch.c; closes current interval and updates total/min/max/last/hits statistics.
  • OSCheckStopwatch - Status: Implemented - Notes: Implemented in src/os/OSStopwatch.c; returns accumulated total and includes current active interval when running.
  • OSResetStopwatch - Status: Implemented - Notes: Implemented in src/os/OSStopwatch.c; clears stopwatch statistics while preserving name.
  • OSDumpStopwatch - Status: Implemented - Notes: Implemented in src/os/OSStopwatch.c; prints stopwatch stats to debug channel (ticks plus converted micro/milliseconds).

Synchronization

  • PPCSync - Status: Implemented - Notes: Implemented in src/base/PPCArch.c (declared in include/dolphin/base/PPCArch.h); first-pass scan missed it because it lives under base, not src/os. PC backend now issues a full host memory fence (MemoryBarrier / __sync_synchronize) to approximate PPC sync.

Time

  • OSGetTime - Status: Implemented - Notes: Implemented in src/os/OSTime.c; returns monotonic tick count (40.5 MHz domain) from host high-resolution timer.
  • OSGetTick - Status: Implemented - Notes: Implemented in src/os/OSTime.c; returns low 32 bits of OSGetTime().
  • OSTicksToCycles - Status: Implemented - Notes: Implemented as macro in include/dolphin/os/OSTime.h ((ticks) * (OS_CORE_CLOCK / OS_TIMER_CLOCK)).
  • OSTicksToSeconds - Status: Implemented - Notes: Implemented as macro in include/dolphin/os/OSTime.h.
  • OSTicksToMilliseconds - Status: Implemented - Notes: Implemented as macro in include/dolphin/os/OSTime.h.
  • OSTicksToMicroseconds - Status: Implemented - Notes: Implemented as macro in include/dolphin/os/OSTime.h.
  • OSTicksToNanoseconds - Status: Implemented - Notes: Implemented as macro in include/dolphin/os/OSTime.h (SDK-style integer conversion).
  • OSSecondsToTicks - Status: Implemented - Notes: Implemented as macro in include/dolphin/os/OSTime.h.
  • OSMillisecondsToTicks - Status: Implemented - Notes: Implemented as macro in include/dolphin/os/OSTime.h.
  • OSMicrosecondsToTicks - Status: Implemented - Notes: Implemented as macro in include/dolphin/os/OSTime.h.
  • OSNanosecondsToTicks - Status: Implemented - Notes: Implemented as macro in include/dolphin/os/OSTime.h (SDK-style integer conversion).

Thread

  • OSCancelThread - Status: Partial - Notes: Implemented in src/os/OSThread.c via force-cancel (TerminateThread / pthread_cancel), but queue/mutex cleanup semantics differ from SDK.
  • OSCheckActiveThreads - Status: Stub - Notes: Stubbed in src/os/OSThread.c; currently returns constant 1 instead of sweeping active queues and validating stacks.
  • OSCreateThread - Status: Partial - Notes: Implemented in src/os/OSThread.c with PC thread wrapper and suspend-count start, but not full SDK scheduler/run-queue behavior.
  • OSDetachThread - Status: Partial - Notes: Implemented attribute set + platform detach path, but joinability/lifecycle semantics are not fully SDK-equivalent.
  • OSDisableScheduler - Status: Partial - Notes: Implemented as nested counter only; cannot actually stop host OS scheduling on PC backend.
  • OSEnableScheduler - Status: Partial - Notes: Implemented as nested counter decrement; does not re-enable a real paused scheduler on PC backend.
  • OSExitThread - Status: Partial - Notes: Implemented state/return-value update and join wake, but does not hard-terminate execution context like SDK OSExitThread.
  • OSGetCurrentThread - Status: Partial - Notes: Implemented in src/os/OSThread.c with per-thread TLS for libPorpoise-created threads plus main-thread fallback; foreign/unmanaged host threads may fall back to global current thread.
  • OSGetThreadPriority - Status: Implemented - Notes: Implemented in src/os/OSThread.c; returns stored thread priority.
  • OSInitThreadQueue - Status: Implemented - Notes: Implemented in src/os/OSThread.c; initializes queue head/tail.
  • OSIsThreadSuspended - Status: Implemented - Notes: Implemented in src/os/OSThread.c; checks suspend count > 0.
  • OSIsThreadTerminated - Status: Implemented - Notes: Implemented in src/os/OSThread.c; checks thread state OS_THREAD_STATE_MORIBUND.
  • OSJoinThread - Status: Partial - Notes: Implemented wait/join flow, but blocking relies on simplified sleep queue behavior (no full SDK queue scheduler semantics).
  • OSResumeThread - Status: Partial - Notes: Implemented suspend-count decrement and initial start, but cannot truly resume a host thread suspended mid-execution.
  • OSSetThreadPriority - Status: Partial - Notes: Implemented with priority storage + coarse host mapping; not full Dolphin scheduler priority semantics.
  • OSSleepThread - Status: Stub - Notes: Stubbed in src/os/OSThread.c as short timed sleep; does not enqueue/dequeue thread in SDK wait queues.
  • OSSuspendThread - Status: Partial - Notes: Implemented suspend-count increment only; cannot forcibly suspend already running host thread.
  • OSWakeupThread - Status: Stub - Notes: Stubbed in src/os/OSThread.c; queue wake semantics are not implemented.
  • OSYieldThread - Status: Implemented - Notes: Implemented in src/os/OSThread.c via host scheduler yield (Sleep(0) / sched_yield).

Thread Synchronization

  • OSInitCond - Status: Implemented - Notes: Implemented in src/os/OSMutex.c; initializes condition-variable wait queue.
  • OSInitMessageQueue - Status: Implemented - Notes: Implemented in src/os/OSMessage.c; initializes send/receive wait queues and circular-buffer metadata (invalid/zero capacity now guarded by send/receive paths).
  • OSInitMutex - Status: Implemented - Notes: Implemented in src/os/OSMutex.c; initializes owner/count and wait queue.
  • OSJamMessage - Status: Partial - Notes: Implemented head-insert semantics in src/os/OSMessage.c, but blocking/wakeup behavior depends on OSSleepThread/OSWakeupThread PC stubs.
  • OSLockMutex - Status: Partial - Notes: Recursive owner/count semantics implemented in src/os/OSMutex.c, but wait/wakeup relies on thread sleep/wake stubs (not full SDK scheduler queues).
  • OSReceiveMessage - Status: Partial - Notes: Circular-buffer dequeue and block/non-block modes implemented, but blocking semantics depend on stubbed thread queue wake/sleep behavior.
  • OSSendMessage - Status: Partial - Notes: Circular-buffer enqueue and block/non-block modes implemented, but blocking semantics depend on stubbed thread queue wake/sleep behavior.
  • OSSignalCond - Status: Partial - Notes: Implemented in src/os/OSMutex.c as queue wake trigger, but wake semantics are limited by OSWakeupThread stub behavior on PC backend.
  • OSTryLockMutex - Status: Partial - Notes: Implemented immediate acquire/fail semantics and recursive lock increment, but lacks full SDK queue/scheduler interaction and host-level atomic wait primitives.
  • OSUnlockMutex - Status: Partial - Notes: Owner validation + recursive decrement + release implemented, but waiter handoff depends on stubbed wake logic.
  • OSWaitCond - Status: Partial - Notes: Implemented unlock/sleep/relock flow, but does not provide full SDK-equivalent atomic wait handoff due stubbed sleep/wake queue model.