/*
 * kido-boot.h — Kido outer-kernel boot sequence, public interface.
 *
 * Kido is the second BUBO-line kernel-node: portable and adaptive from
 * birth, compensating BUBO's x86-bound C heritage. This module takes the
 * outer kernel from power-on to its first adaptive breath.
 *
 * Draft status: boot state machine + portable HAL are real. Bare-metal
 * entry shims and MMU/cache bring-up are STUBs. No bootable kernel is
 * finalized without N8toriousAi; first boot is his to witness.
 */
#ifndef KIDO_BOOT_H
#define KIDO_BOOT_H

#include <stdint.h>
#include <stddef.h>

/* ------------------------------------------------------------------ */
/* Architecture selection. Kido never assumes x86. Unknown arch is a   */
/* compile-time error, not a silent default.                          */
/* ------------------------------------------------------------------ */
#if defined(__aarch64__)
#  define KIDO_ARCH_ARM64 1
#  define KIDO_ARCH_NAME "arm64"
#elif defined(__x86_64__)
#  define KIDO_ARCH_X86_64 1
#  define KIDO_ARCH_NAME "x86_64"
#elif defined(KIDO_HOSTED_TEST)
#  define KIDO_ARCH_HOSTED 1
#  define KIDO_ARCH_NAME "hosted"
#else
#  error "Kido: unknown architecture. Define KIDO_HOSTED_TEST for the hosted draft harness."
#endif

/* ------------------------------------------------------------------ */
/* Status codes. Every stage returns one; failures halt LOUD.          */
/* ------------------------------------------------------------------ */
typedef enum kido_status {
    KIDO_OK                = 0,
    KIDO_ERR_EARLY_ENV     = 1,  /* C environment not sane (stack/bss)   */
    KIDO_ERR_NO_CONSOLE    = 2,  /* no usable early console after adapt  */
    KIDO_ERR_NO_TIMER      = 3,  /* no usable timer after adapt          */
    KIDO_ERR_NO_MEMORY     = 4,  /* no usable memory region after adapt  */
    KIDO_ERR_HANDOFF       = 5,  /* kido_main refused the handoff        */
    KIDO_ERR_STUB_REACHED  = 6   /* a STUB marked mandatory was reached  */
} kido_status_t;

/* ------------------------------------------------------------------ */
/* Capability probe result: what the platform actually offers.         */
/* ------------------------------------------------------------------ */
typedef struct kido_caps {
    const char *arch_name;   /* KIDO_ARCH_NAME                            */
    uint64_t    mem_base;    /* first usable RAM byte (probe result)      */
    uint64_t    mem_size;    /* usable RAM bytes (probe result)           */
    uint32_t    timer_hz;    /* timer ticks per second (0 = unknown)      */
    uint8_t     has_fpu;     /* floating point available                 */
    uint8_t     has_mmu;     /* MMU present (bring-up is a STUB)          */
} kido_caps_t;

/* ------------------------------------------------------------------ */
/* Hardware Abstraction Layer. Bare-metal fills this from real         */
/* drivers; the hosted draft fills it from libc. Function pointers,    */
/* never #ifdef spaghetti at call sites.                              */
/* ------------------------------------------------------------------ */
typedef struct kido_hal {
    void     (*console_putc)(char c);
    void     (*console_puts)(const char *s);
    uint64_t (*timer_ticks)(void);   /* monotonic ticks; STUB if none    */
    uint32_t (*timer_hz)(void);
} kido_hal_t;

/* ------------------------------------------------------------------ */
/* Boot stages. Call in order; stop and kido_halt() on first failure.  */
/* ------------------------------------------------------------------ */
kido_status_t kido_boot_early(void);                 /* sane C env       */
kido_status_t kido_boot_probe(kido_caps_t *caps);    /* detect platform  */
kido_status_t kido_boot_adapt(const kido_caps_t *caps,
                              kido_hal_t *hal);      /* select drivers   */
kido_status_t kido_boot_breath(kido_hal_t *hal);     /* first breath     */

/* Full sequence: early -> probe -> adapt -> breath. Returns status.   */
kido_status_t kido_boot(void);

/* Loud halt: report code on the console, then spin forever.           */
void kido_halt(kido_status_t code);

/* Handoff target after the first breath. STUB in this draft.          */
kido_status_t kido_main(kido_hal_t *hal);

#endif /* KIDO_BOOT_H */
