Architecture Tier 3 Core API

Architecture: Tier 3 - Core API

The LinApple Core API is the primary interface between the platform-specific frontend and the emulator. It is defined in src/core/LinAppleCore.h as a C-compatible ABI to ensure cross-language support and stability.

Note on Alpha Status: The Core API is currently in Alpha (Version 0). It is subject to change as the project's tiered architecture is finalized. Backwards compatibility will be guaranteed only after a future date when the API is officially locked down (planned for Version 1.0).

Primary Lifecycle Functions

Linapple_Init()

Initializes all emulator-agnostic subsystems.

• Allocates main/aux memory.
• Loads ROMs from the file system.
• Resets the CPU and prepares the video core.

Linapple_RunFrame(uint32_t cycles)

The most critical function in the API. It represents one "heartbeat" of the emulator, typically called once per 16.6ms (60Hz) by the frontend.

1. CPU Execution: Executes the 6502 core for the requested number of cycles (e.g., 17,030).
2. Peripheral Manager Think: Drains the thread-safe command queue and allows each peripheral to update its state for the elapsed cycle count.
3. Video & Timer Logic: Updates VBlank signals and processes the high-frequency system clock.
4. Callback Dispatch: If a video frame is complete, it invokes the LinappleVideoCallback.

Linapple_Shutdown()

Cleans up all virtual hardware, shuts down peripherals, and frees all allocated memory.

Peripheral Interactions

Peripheral_Command (Thread-Safe)

PeripheralStatus Peripheral_Command(int slot, uint32_t cmd_id, const void* data, size_t size);

Used by the frontend to interact with specific cards. Commands are queued and processed synchronously with the CPU execution to prevent race conditions.

• slot: The virtual slot number (0-7).
• cmd_id: A peripheral-specific command ID (e.g., DISK_CMD_INSERT).

Peripheral_Query (Synchronous)

PeripheralStatus Peripheral_Query(int slot, uint32_t cmd_id, void* out, size_t* out_size);

Used to retrieve status information (e.g., "Is Disk 1 spinning?"). Must be called from the emulation thread to ensure consistency.

Output Callbacks

Frontends provide implementations for these to receive the results of emulation:

• LinappleVideoCallback: Receives a const uint32_t* pointer to the finished 560x384 RGBA pixel buffer.
• LinappleAudioCallback: Receives interleaved 16-bit signed stereo samples.
• LinappleTitleCallback: Receives strings to be displayed in the host's window title (e.g., "LinApple - Disk 1: Master.dsk").

---

Back: Tier 3 Overview | Next: Tier 4 - Hardware