/*
 * pop_arc.h — архив ресурсов PBA1: много файлов в одном, один open на всех.
 *
 * ЗАЧЕМ.  Замер в MAME (2026-08-25): `open` стоит 51,4 мс, а чтение 16 КБ из
 * уже открытого файла — 32,6 мс.  То есть 61 % времени загрузки уходит на
 * открытие, а не на данные, и одна только стартовая пачка ресурсов (~142
 * файла) — это 7,3 секунды чистого `open`.  Архив открывается ОДИН раз на
 * группу, и эта цена платится один раз вместо сотни.
 *
 * ФОРМАТ (генерирует toolchain/pop_pack_arc.py):
 *   0..3  'PBA1'   магия и версия
 *   4     count    число записей, 1..126
 *   8..   записи по 4 байта: offset в СЕКТОРАХ по 512 (uint16),
 *                            size в байтах (uint16)
 *   данные с 512, каждый элемент выровнен на 512.
 * Оффсет в секторах, потому что архив может быть больше 64 КБ (pv — мегабайт);
 * размер в байтах, потому что ни один ресурс не крупнее 16 КБ — он обязан
 * помещаться в EMM-страницу.
 *
 * ТАБЛИЦУ ДЕРЖИТ ВЫЗЫВАЮЩИЙ, на своём стеке: 4 байта на запись, у самой
 * большой группы 320 байт.  В W2 её класть нельзя — там осталось около сотни
 * байт, — а стека в точке загрузки ресурсов израсходовано 75 байт из 1279
 * (замер там же).  Так модуль не занимает постоянной памяти вовсе.
 */
#ifndef POP_ARC_H
#define POP_ARC_H

#include <stdint.h>

#define POP_ARC_HEADER   512
#define POP_ARC_SECTOR   512
#define POP_ARC_MAX      126     /* (512-8)/4 */
#define POP_ARC_REC      4       /* байт на запись таблицы */

typedef struct {
    int     fd;
    uint8_t count;
} pop_arc_t;

/* Открыть архив и вычитать таблицу в буфер вызывающего (count*4 байт).
 * tbl_max — сколько записей помещается в буфер.
 * Возврат: число записей; -1 — не открылся, не PBA1 либо таблица не влезла. */
int8_t pop_arc_open(pop_arc_t *a, const char *path,
                    uint8_t *tbl, uint8_t tbl_max) __banked;

/* Размер элемента idx по таблице (0, если индекс за пределами). */
uint16_t pop_arc_size(const uint8_t *tbl, uint8_t idx);

/* Прочитать кусок элемента idx в EMM-страницу: skip байт от его начала,
 * size байт, в страницу page со смещением off.  size == 0 — весь элемент.
 * Возврат: сколько прочитано, -1 — ошибка. */
int pop_arc_read(pop_arc_t *a, const uint8_t *tbl, uint8_t idx, uint16_t skip,
                 uint8_t page, uint16_t off, uint16_t size) __banked;

void pop_arc_close(pop_arc_t *a) __banked;

#endif /* POP_ARC_H */