/*
 * sprinter_mem.h — banking-aware page allocator and bank-data accessors.
 *
 * For data that doesn't fit in window 2's heap, allocate physical pages
 * directly through ESTEX EMM and access them via bank_read / bank_write
 * (which swap a CPU window internally).
 *
 *   mem_alloc_pages(N) — reserve N contiguous 16 KB pages, return block id.
 *   mem_free_block(id) — release a previously-allocated block.
 *   mem_get_page(id, i) — translate (block, page-index) to physical page.
 *   mem_info(&total, &free) — query EMM about total/free 16 KB pages.
 *
 *   bank_load_byte / bank_store_byte — single-byte access through W3.
 *   bank_read / bank_write           — bulk copy through W3.
 *   bank_*_w1                        — same family but through W1 (for
 *                                      memory modes where code lives in
 *                                      W2 and W1 is free for data).
 *
 * Each helper saves the previous window-mapping, swaps to the target
 * physical page, does the access, restores the saved page.
 *
 * SAFETY by memory mode (-memory FLAG to sprinter-cc):
 *
 *   `tiny`       : both bank_*  and bank_*_w1  are safe.
 *   `small`/`huge`: only bank_*  (W3) is safe; bank_*_w1 CRASHES
 *                   because code lives in W1.
 *   `big`        : only bank_*  (W3) is safe; bank_*_w1 would clobber
 *                   the banked-code segment in W1.
 *   `huge` (data path through W3 banked code): bank_* (W3) is unsafe;
 *                   avoid banking via W3 in huge programs.
 *
 * In short: `_w1` accessors are a `tiny`-mode optimisation, useful when
 * the program is small enough to fit in W2 and wants both W1 and W3 as
 * independent banked-data windows.
 */

#ifndef SPRINTER_MEM_H
#define SPRINTER_MEM_H

#include <stdint.h>

/* ===================================================================
 * ESTEX EMM allocator wrappers
 * =================================================================== */

/* Allocate `n` contiguous 16-KB physical pages from the EMM pool.
 *   n     : 1..255
 *   ret   : blk_id (1..255) on success; 0 on failure with errno set.
 * The id is opaque — pass it to mem_get_page() and mem_free_block(). */
uint8_t mem_alloc_pages_estex(uint8_t n);
uint8_t mem_alloc_pages_bios(uint8_t n);

/* Release a block previously returned by mem_alloc_pages().
 * On error errno is set (e.g. EINVAL for unknown id).  Double-free is
 * NOT idempotent: the second call sets errno. */
void    mem_free_block_estex(uint8_t blk_id);
void    mem_free_block_bios(uint8_t blk_id);

/* Translate (block, page-index) into a physical page number suitable
 * for sprinter_page_w1/w2/w3() or the bank_*() helpers below.
 *   blk_id: from mem_alloc_pages()
 *   idx   : 0..(n-1)
 *   ret   : physical page (1..255) on success; 0 on failure (errno set). */
uint8_t mem_get_page_bios(uint8_t blk_id, uint8_t idx);

/* Query the EMM allocator state.  Both pointers must be non-NULL.
 * Cannot fail (no error path). */
void    mem_info_estex(uint16_t *total, uint16_t *free_pages);
void    mem_info_bios(uint16_t *total, uint16_t *free_pages);

#define MEM_MANAGE_MODE_BIOS

#ifdef MEM_MANAGE_MODE_ESTEX

#define mem_alloc_pages   mem_alloc_pages_estex
#define mem_free_block    mem_free_block_estex
#define mem_info          mem_info_estex

#define mem_get_page mem_get_page_bios

#elif defined MEM_MANAGE_MODE_BIOS

#define mem_alloc_pages   mem_alloc_pages_bios
#define mem_free_block    mem_free_block_bios
#define mem_info          mem_info_bios

#define mem_get_page mem_get_page_bios

#endif


/* ===================================================================
 * Far-page accessors via window 3 (base 0xC000, port 0xE2)
 *
 * Each call saves the current W3 mapping, sets W3 to `phys_page`, does
 * the access at (base + off_in_window), then restores the saved page.
 * Safe in `tiny`, `small`, `big` memory modes (W3 is free for data).
 * NOT safe in `huge` — banked code lives in W3 there.
 * =================================================================== */

/* Read one byte from phys_page at offset off_in_window (0..0x3FFF). */
uint8_t bank_load_byte(uint8_t phys_page, uint16_t off_in_window);

/* Write byte `v` into phys_page at offset off_in_window. */
void    bank_store_byte(uint8_t phys_page, uint16_t off_in_window, uint8_t v);

/* Copy `n` bytes from phys_page[off..off+n-1] into the near buffer `dst`. */
void    bank_read(uint8_t phys_page, uint16_t off, void *dst, uint16_t n);

/* Copy `n` bytes from near buffer `src` into phys_page[off..off+n-1]. */
void    bank_write(uint8_t phys_page, uint16_t off, const void *src, uint16_t n);

/* ===================================================================
 * Far-page accessors via window 1 (base 0x4000, port 0xA2)
 *
 * Same semantics as the W3 family but swap W1 instead.  SAFE ONLY in
 * `--memory tiny` builds — in any other mode code lives in (or uses) W1
 * and swapping it mid-call will crash.  See header notes above for the
 * full safety matrix.
 * =================================================================== */

uint8_t bank_load_byte_w1(uint8_t phys_page, uint16_t off_in_window);
void    bank_store_byte_w1(uint8_t phys_page, uint16_t off_in_window, uint8_t v);
void    bank_read_w1(uint8_t phys_page, uint16_t off, void *dst, uint16_t n);
void    bank_write_w1(uint8_t phys_page, uint16_t off, const void *src, uint16_t n);

#endif