/*
 * kido-entry-arm64.h — Kido ARM64 bare-metal entry shim, public interface.
 *
 * The power-on entry point. _start (kido-entry-arm64.S) runs before any C
 * exists: it drops EL2->EL1 if needed, sets up the stack, zeroes BSS,
 * then calls kido_entry_c_main() with the firmware DTB pointer from x0.
 * The C continuation fills kido_bootinfo_t (the HAL's contract), then
 * calls kido_boot(). If boot ever returns, the shim halts LOUD.
 *
 * This shim is what makes kido_boot_early()'s stack/BSS checks honest:
 * on hosted they pass vacuously; on bare metal they verify THIS shim.
 *
 * ARCH DISCIPLINE: ARM64-only. The .S file is assembled for aarch64;
 * the C file compiles for __aarch64__ or KIDO_HOSTED_TEST (test double).
 *
 * Draft status: EL2->EL1 drop, stack/BSS setup, DTB-magic check, and
 * bootinfo fill are REAL. Board detection is a LOUD ASSUMPTION
 * (QEMU virt — this image's only target; kido-mem replaces it with a
 * DTB compatible-string parse). The memory map is mem_valid=0, LOUD,
 * pending kido-mem's DTB parser. Phase 2 (2026-10-17): the .S sets a
 * delta-aware SP and stashes its relocation measurement for
 * kido-reloc's crosscheck (the .S change is written, not yet
 * assembled — cross toolchain absent this session). No bootable
 * kernel is finalized without N8toriousAi; first boot is his to witness.
 */
#ifndef KIDO_ENTRY_ARM64_H
#define KIDO_ENTRY_ARM64_H

#include "kido-boot.h"
#include "kido-hal-arm64.h"

#if !defined(__aarch64__) && !defined(KIDO_HOSTED_TEST)
#error "kido-entry-arm64: ARM64 only. Define KIDO_HOSTED_TEST for the hosted draft harness."
#endif

/* ------------------------------------------------------------------ */
/* C entry, called from _start with the firmware DTB pointer (x0 on    */
/* the QEMU virt -kernel path). NEVER RETURNS: calls kido_boot(),     */
/* then kido_halt() with whatever status comes back.                   */
/* ------------------------------------------------------------------ */
void kido_entry_c_main(uint64_t dtb_ptr);

/* ------------------------------------------------------------------ */
/* Bootinfo fill. Board ID is a LOUD ASSUMPTION (see above); mem_* are */
/* mem_valid=0 (loud stub — kido-mem's DTB parser supplies the map).    */
/* The DTB pointer is magic-checked (0xd00dfeed, big-endian on the     */
/* wire) and stashed for kido-mem; an invalid/missing DTB does NOT     */
/* fake a map — probe() fails loud downstream, as designed.            */
/* Returns KIDO_OK always; the loud signal is mem_valid=0, not the     */
/* return code. NULL bi -> KIDO_ERR_EARLY_ENV.                         */
/* ------------------------------------------------------------------ */
kido_status_t kido_entry_fill_bootinfo(uint64_t dtb_ptr,
                                       kido_bootinfo_t *bi);

/* ------------------------------------------------------------------ */
/* Accessors for kido-mem and future wiring. The filled bootinfo and   */
/* the raw DTB pointer live in the shim's BSS (zeroed by _start, which */
/* is exactly why BSS zeroing matters).                                */
/* ------------------------------------------------------------------ */
const kido_bootinfo_t *kido_entry_bootinfo(void);
uint64_t kido_entry_dtb_ptr(void);
uint8_t  kido_entry_dtb_valid(void);

#endif /* KIDO_ENTRY_ARM64_H */
