/*
 * kido-hal-arm64.h — Kido ARM64 bare-metal HAL, public interface.
 *
 * The per-arch shim that kido-boot's HAL function-pointer table calls
 * into. ARM64 specifics live HERE and nowhere else; portable logic
 * stays out. This closes the PARTIAL item from the boot conformance
 * review (the ARM64 bare-metal prober was a declared STUB).
 *
 * ARCH DISCIPLINE: this file refuses to compile for unknown arch.
 * KIDO_HAL_ARM64_SYNTAX_TEST is a test-only macro permitting a syntax
 * check of the ARM64 paths on a non-ARM64 dev host; it must never be
 * defined in a real build (execution under it is meaningless).
 *
 * ENTRY-SHIM CONTRACT: probe() must run at EL1 or higher — the
 * ID_AA64* reads trap at EL0. The shim must also fill kido_bootinfo_t
 * from the firmware handoff (DTB/UEFI memory map, board ID) before
 * calling probe(); without it, memory discovery fails LOUD.
 *
 * Draft status: generic timer, FPU/MMU-presence/MIDR probing, the
 * QEMU 'virt' PL011 console, and the RPi4 AUX mini-UART (init sequence
 * + polled TX) are REAL. Memory map without bootinfo and MMU bring-up
 * are loud STUBs. The RPi4 sequence is WRITTEN, NOT EXECUTED ON
 * HARDWARE (see PROOF STATUS in kido-hal-arm64.c) — a real Pi4 run is
 * N8toriousAi's to witness. No bootable kernel is finalized without
 * N8toriousAi; first boot is his to witness.
 */
#ifndef KIDO_HAL_ARM64_H
#define KIDO_HAL_ARM64_H

#include "kido-boot.h"

#if !defined(__aarch64__) && !defined(KIDO_HOSTED_TEST) && \
    !defined(KIDO_HAL_ARM64_SYNTAX_TEST)
#error "kido-hal-arm64: refusing to compile for unknown arch. Per-arch code lives in per-arch files; define KIDO_HOSTED_TEST for the hosted draft harness."
#endif

/* ------------------------------------------------------------------ */
/* Board IDs. The entry shim reports which board we are on; the HAL    */
/* selects the UART from this table at boot (probe-then-adapt — never  */
/* a compile-time guess). Unknown board = loud NO_CONSOLE, never a    */
/* scribble at a guessed address.                                      */
/* ------------------------------------------------------------------ */
#define KIDO_BOARD_UNKNOWN   0u
#define KIDO_BOARD_QEMU_VIRT 1u  /* PL011 @ 0x09000000 — REAL           */
#define KIDO_BOARD_RPI4      2u  /* AUX mini-UART @ 0xFE215040 — REAL   */

/* ------------------------------------------------------------------ */
/* Firmware handoff from the entry shim. Filled from DTB/UEFI before   */
/* probe() runs. mem_valid==0 means "no firmware map" -> probe fails  */
/* LOUD with KIDO_ERR_STUB_REACHED (memory discovery needs kido-mem).  */
/* ------------------------------------------------------------------ */
typedef struct kido_bootinfo {
    uint64_t mem_base;    /* first usable RAM byte, from firmware      */
    uint64_t mem_size;    /* usable RAM bytes, from firmware            */
    uint8_t  mem_valid;   /* 1 = firmware supplied a memory map         */
    uint32_t board_id;    /* KIDO_BOARD_* as reported by the shim      */
} kido_bootinfo_t;

/* ------------------------------------------------------------------ */
/* Probe: fill caps from ARM64 arch registers + bootinfo.              */
/*  REAL: arch_name, timer_hz (CNTFRQ_EL0; 0 = firmware didn't set),   */
/*        has_fpu (ID_AA64PFR0_EL1), has_mmu presence                   */
/*        (ID_AA64MMFR0_EL1; bring-up remains a STUB), mem_* from       */
/*        bootinfo.                                                    */
/*  STUB (loud): mem_* when bootinfo->mem_valid == 0.                  */
/* ------------------------------------------------------------------ */
kido_status_t kido_hal_arm64_probe(const kido_bootinfo_t *bi,
                                   kido_caps_t *caps);

/* ------------------------------------------------------------------ */
/* Fill: wire the four kido_hal_t pointers for this board.             */
/*  REAL: QEMU virt -> PL011 console + generic-timer functions         */
/*        (firmware owns the UART; init hook is NULL).                 */
/*        RPi4 -> AUX mini-UART init sequence + polled TX (real;       */
/*        WRITTEN NOT EXECUTED ON HARDWARE — PROOF STATUS in the .c).  */
/*  STUB (loud): unknown board -> KIDO_ERR_NO_CONSOLE.                 */
/* All four pointers are non-NULL on KIDO_OK.                          */
/*                                                                     */
/* WIRING NOTE (for N8toriousAi's review): kido-boot.c's adapt() bare-metal */
/* branch is still its approved STUB table. The one-line change to     */
/* call kido_hal_arm64_fill() there is the explicit next step — NOT    */
/* made here, because the boot module was approved at the Gate as-is.  */
/* ------------------------------------------------------------------ */
kido_status_t kido_hal_arm64_fill(kido_hal_t *hal, uint32_t board_id);

#endif /* KIDO_HAL_ARM64_H */
