/*
 * kido-mbox.h — Kido VideoCore mailbox driver, public interface.
 *
 * The firmware door for BCM2711 (Raspberry Pi 4): property-tags
 * channel 8 to the VideoCore. Its first job is the one session 24
 * named: query the real VPU clock rate so the RPi4 mini-UART baud
 * divisor stops being a named constant (500 MHz + config.txt
 * core_freq_min=500) and becomes a measurement.
 *
 * PROTOCOL (verified 2026-10-24 against OSDev Pi4 iomem, rpi4os
 * Part 5, the Pi forum mailbox example, and the Linux
 * rpi_firmware_property driver):
 *   base 0xFE00B880 (ARM-physical, Low Peripheral Mode);
 *   READ 0x00, STATUS0 0x18 (EMPTY 0x40000000), WRITE1 0x20,
 *   STATUS1 0x38 (FULL 0x80000000); mail = (buf & ~0xF) | 8;
 *   buffer 16-byte aligned; response code 0x80000000 = success.
 *   Get-clock-rate tag 0x00030002; packet [clock_id, rate_hz];
 *   firmware returns rate 0 on an unknown clock (Linux driver note)
 *   — so 0 is a LOUD failure here, never a divisor input.
 *
 * CLOCK IDS: the id is a CALLER fact, not module logic. The
 * firmware clock table reads EMMC 1, UART 2, ARM 3, CORE 4, VPU 5,
 * ... The VPU id (5) was NOT re-fetched from the firmware wiki
 * this session; the first Pi4 run must show a sane VPU rate (near
 * 500 MHz under core_freq_min=500) before the HAL adopts the query.
 * A wrong id fails loud (rate 0), never silently.
 *
 * HONESTY LAW:
 *  - Single-flight: one static BSS buffer, no allocator, no timer,
 *    no HAL dependency. Call only when MMU is off or identity-
 *    mapped (kido-mmu's identity map qualifies): the mail carries
 *    the ARM physical address, so virtual must equal physical.
 *  - Every failure is KIDO_ERR_EARLY_ENV with *hz untouched:
 *    timeout, wrong mail echo, bad response code, wrong tag/clock
 *    echo, short response length, zero rate, unaligned or
 *    over-32-bit buffer address. No new header code (N8toriousAi's call).
 *  - WRITTEN, NOT EXECUTED ON HARDWARE. The hosted double pins the
 *    exchange; a real Pi4 run is N8toriousAi's to witness.
 *  - NOT wired into the HAL this session. The seam is declared:
 *    a future HAL init calls kido_mbox_vpu_hz() and computes
 *    BAUD = hz / (8 * 115200) - 1. Until the Pi4 run confirms the
 *    query, the HAL keeps its named constant.
 *
 * FUTURES (named, not built): other channels, multi-tag batching,
 * clock setting, board-revision / temperature tags, IRQ delivery.
 *
 * Draft status: DRAFT (2026-10-24, session 25). No bootable kernel
 * is finalized without N8toriousAi; first boot is his to witness.
 */
#ifndef KIDO_MBOX_H
#define KIDO_MBOX_H

#include "kido-boot.h"

#if !defined(__aarch64__) && !defined(KIDO_HOSTED_TEST)
#error "kido-mbox: refusing to compile for unknown arch. BCM2711 MMIO lives in per-arch files; define KIDO_HOSTED_TEST for the hosted draft harness."
#endif

/* Clock ids from the firmware clock table (caller facts; see the
 * header's CLOCK IDS note — VPU 5 awaits first-hardware-run
 * confirmation before the HAL adopts it). */
#define KIDO_MBOX_CLOCK_EMMC 1u
#define KIDO_MBOX_CLOCK_UART 2u
#define KIDO_MBOX_CLOCK_ARM  3u
#define KIDO_MBOX_CLOCK_CORE 4u
#define KIDO_MBOX_CLOCK_VPU  5u

/* Query one firmware clock rate (Hz) over the property-tags channel.
 * clock_id is validated only by the firmware (unknown id -> rate 0
 * -> EARLY_ENV, loud). hz must be non-NULL; untouched on failure. */
kido_status_t kido_mbox_clock_rate(uint32_t clock_id, uint32_t *hz);

/* Convenience: the VPU clock the RPi4 mini-UART baud law needs. */
kido_status_t kido_mbox_vpu_hz(uint32_t *hz);

#endif /* KIDO_MBOX_H */
