/*
 * kido-alloc.h — Kido memory allocator, public interface.
 *
 * The allocation layer that replaces the scheduler's explicit stack
 * carving: first-fit free-list with immediate coalescing, over an
 * explicit region list (kido-mem's discovery output on bare metal, a
 * static arena on hosted, synthetic regions in tests).
 *
 * HONESTY LAW:
 *  - First-fit fragments. Fragmentation is declared; kido_alloc_stats
 *    exposes largest_free so callers observe it. No VM, no demand
 *    paging — loud DEFERRED.
 *  - The allocator dereferences firmware physical addresses as
 *    pointers: correct only under identity mapping. The MMU module
 *    will revisit this. Stated, not assumed.
 *  - Exhaustion is a status code (KIDO_ERR_NO_MEMORY), never a silent
 *    NULL. Double-free / invalid-free / free(NULL) are defined and
 *    loud (KIDO_ERR_EARLY_ENV) via header magic.
 *
 * THREAD LAW: uniprocessor kernel, cooperative scheduler — no locking.
 * SMP is a future module (see kido-sched.h).
 *
 * Draft status: first-fit + coalescing is REAL and tested. Reservation
 * carve-out is REAL and tested; the scheduler passes the kido-image
 * bounds since 2026-10-16 (sched deliberation D2 closed).
 */
#ifndef KIDO_ALLOC_H
#define KIDO_ALLOC_H

#include "kido-boot.h"  /* kido_status_t */
#include "kido-mem.h"   /* kido_mem_region_t */

/* Minimum payload alignment. AAPCS64 wants 16; callers may ask higher. */
#define KIDO_ALLOC_MIN_ALIGN 16u

typedef struct kido_alloc_stats {
    uint64_t total_bytes;     /* region bytes under management        */
    uint64_t allocated_bytes; /* payload bytes currently allocated    */
    uint64_t free_bytes;      /* bytes in free blocks (incl. headers) */
    uint64_t largest_free;    /* largest single free payload          */
    uint64_t allocs;          /* successful kido_alloc count          */
    uint64_t frees;           /* successful kido_free count           */
} kido_alloc_stats_t;

/* ------------------------------------------------------------------ */
/* kido_alloc_init: take ownership of the region list.                 */
/*  regions/n : backing store (copied; the caller's array may be       */
/*               transient). n==0 or NULL regions -> EARLY_ENV.        */
/*  reserve_base/reserve_size : carved out of the regions before the   */
/*               free list is built (kernel image bounds go here —     */
/*               kido_sched_init passes the kido-image bounds; D2       */
/*               closed 2026-10-16). 0,0 only on hosted-uninjected,     */
/*               where the reservation is vacuously empty.             */
/*  Returns KIDO_OK, EARLY_ENV on bad input (incl. region arithmetic  */
/*  overflow), NO_MEMORY when nothing usable survives. Re-init resets  */
/*  the allocator; documented, not for use with live allocations.      */
/* ------------------------------------------------------------------ */
kido_status_t kido_alloc_init(const kido_mem_region_t *regions, size_t n,
                              uint64_t reserve_base, uint64_t reserve_size);

/* ------------------------------------------------------------------ */
/* kido_alloc: first-fit allocate.                                     */
/*  size  : payload bytes wanted (>0).                                 */
/*  align : power of two (>=1; raised to 16 internally). 0 or non-     */
/*           power-of-two -> EARLY_ENV, loud.                          */
/*  out   : set to the aligned payload, or NULL on failure.           */
/*  Returns KIDO_OK, EARLY_ENV (bad args / not initialized), or        */
/*  NO_MEMORY (no fitting block — loud, never a silent NULL).          */
/* ------------------------------------------------------------------ */
kido_status_t kido_alloc(uint64_t size, uint64_t align, void **out);

/* ------------------------------------------------------------------ */
/* kido_free: return a block. Defined and loud: NULL, double-free, or  */
/* a pointer the allocator never issued -> KIDO_ERR_EARLY_ENV.         */
/* Coalesces with address neighbors on success.                        */
/* ------------------------------------------------------------------ */
kido_status_t kido_free(void *ptr);

/* ------------------------------------------------------------------ */
/* kido_alloc_stats: accounting snapshot for tests and callers.        */
/* ------------------------------------------------------------------ */
kido_status_t kido_alloc_stats(kido_alloc_stats_t *out);

#endif /* KIDO_ALLOC_H */
