/*
 * boot_info.h – Shared interface between the firmware loader and kernel.
 *
 * The BootInfo struct is populated by the platform-specific loader
 * (currently the UEFI loader in main.c) and passed to the kernel entry
 * point (kmain).  It exposes only generic types and function pointers so
 * that the kernel remains independent of any particular firmware API.
 */

#ifndef BOOT_INFO_H
#define BOOT_INFO_H

/*
 * Status code returned by loader-provided services (0 = success).
 * The underlying integer type (UINT64) must be provided by including
 * either the firmware headers (e.g. <efi.h>) or the kernel type
 * header before including this file.
 */
typedef UINT64 KSTATUS;

/* Simple key event used by the kernel's input path. */
typedef struct {
    UINT16 scan_code;
    CHAR16 unicode_char;
} KeyEvent;

/* Printf-style print function (typically backed by firmware console). */
typedef UINTN (*KernelPrintFn)(const CHAR16 *Format, ...);

/* Console output helpers. */
typedef KSTATUS (*ConsoleClearFn)(void);
typedef KSTATUS (*ConsoleSetAttrFn)(UINTN Attribute);

/* Keyboard input helpers. */
typedef KSTATUS (*KeyReadFn)(KeyEvent *Key);

/*
 * BootInfo – everything the kernel needs from the loader at boot time.
 *
 * All function pointers are optional: the kernel must NULL-check before
 * calling.  If a service is unavailable the corresponding field is NULL.
 */
typedef struct {
    /* Console I/O */
    KernelPrintFn    print;          /* formatted text output           */
    ConsoleClearFn   clear_screen;   /* clear the console               */
    ConsoleSetAttrFn set_attribute;  /* set text colour/attr            */
    KeyReadFn        read_key;       /* blocking key read               */
    KeyReadFn        try_read_key;   /* non-blocking key read           */

    /* System control */
    void (*shutdown)(void);          /* power-off the machine           */

    /* Physical memory */
    KSTATUS (*alloc_pages)(UINTN pages, UINT64 *addr);
    KSTATUS (*free_pages)(UINT64 addr, UINTN pages);

    /* Firmware metadata (for informational commands only). */
    const CHAR16 *firmware_vendor;
    UINT32        firmware_major;
    UINT32        firmware_minor;
} BootInfo;

/* Kernel entry point signature (called by the loader). */
typedef void (*KernelEntryFn)(BootInfo *Boot);

#endif /* BOOT_INFO_H */