/*
 * kido-pl011.h — Kido PL011 UART driver, public interface.
 *
 * The full PrimeCell UART (PL011) device: init (baud divisor from a
 * caller-supplied clock), polled TX, polled RX. Companion to the
 * HAL's minimal TX-only helper, which this driver does NOT replace
 * this session (fence: the HAL file is untouched; rewiring it onto
 * this driver is a future Gate item).
 *
 * REGISTERS (ARM PrimeCell UART PL011 TRM, DDI 0183, register
 * summary): DR 0x000, RSR/ECR 0x004, FR 0x018, ILPR 0x020,
 * IBRD 0x024, FBRD 0x028, LCR_H 0x02C, CR 0x030, IFLS 0x034,
 * IMSC 0x038, RIS 0x03C, MIS 0x040, ICR 0x044, DMACR 0x048.
 * Baud law: divisor = UARTCLK / (16 x baud) = IBRD + FBRD/64;
 * FBRD = round(fraction x 64) (the TRM's "+0.5" rule).
 * FR bits: BUSY 3, RXFE 4, TXFF 5, RXFF 6, TXFE 7.
 * LCR_H bits: FEN 4, WLEN 6:5 (0b11 = 8 bits), STP2 3, PEN 1.
 * CR bits: UARTEN 0, TXE 8, RXE 9. IMSC bits SET unmask, so a
 * polled driver writes IMSC = 0 (all masked), never 0x7FF.
 *
 * KNOWN BASES (verified 2026-10-24, see the deliberation record):
 *   QEMU virt PL011: 0x09000000, UARTCLK 24 MHz (DTB).
 *   RPi4 PL011 (uart0): 0xFE201000 (kernel log: fe201000.serial,
 *     ttyAMA0, PL011 rev2). Its UARTCLK is NOT named here: no
 *     verified source supplied it this session, and a guessed
 *     clock would silently mistune every baud rate. A Pi4 caller
 *     supplies the clock — one day plausibly from
 *     kido_mbox_clock_rate(KIDO_MBOX_CLOCK_UART), a candidate,
 *     not a claim, until a Pi4 run confirms it.
 *
 * HONESTY LAW:
 *  - Stateless: base is passed per call; no per-port state is kept.
 *    putc works on a firmware-configured UART with no init call
 *    (the HAL's current QEMU use, preserved). init is required
 *    only when Kido owns the baud rate; re-init is idempotent.
 *  - Polled only: IMSC = 0, DMACR = 0. No IRQ delivery exists
 *    (no GIC module yet); interrupt-driven RX is a named future.
 *  - Every poll is bounded (1 << 20 spins, a loop count, no
 *    timer dependency). A wedged UART returns KIDO_ERR_EARLY_ENV,
 *    never a hang. No new header code (N8toriousAi's call).
 *  - RX contract split, deliberately: poll() reports presence as
 *    a flag (no data is normal); getc() is the waiting path
 *    (bounded poll, EARLY_ENV on expiry = wedged UART). getc
 *    rejects any byte with OE/BE/PE/FE error bits set (bits
 *    11:8 of DR): it clears ECR and delivers nothing, loud.
 *  - GPIO pin muxing is the BOARD layer's job, never this
 *    driver's: init on unmuxed pins configures a UART nobody
 *    can hear. Stated, not hidden.
 *  - WRITTEN, NOT EXECUTED ON HARDWARE. The hosted double pins
 *    the divisor table, the init register image, TX, RX, and
 *    every loud failure; a real QEMU/Pi4 run is N8toriousAi's to
 *    witness.
 *  - NOT wired into the HAL this session. The seam is declared:
 *    a future HAL init calls kido_pl011_init() and a future
 *    HAL putc calls kido_pl011_putc().
 *
 * FUTURES (named, not built): interrupt-driven RX (needs a GIC
 * module), hardware flow control (CTS/RTS), DMA, IrDA mode,
 * multi-port instances (the driver is stateless, so a caller
 * can already drive two bases; only the hosted double models
 * one port).
 *
 * Draft status: DRAFT (2026-10-24, session 26). No bootable kernel
 * is finalized without N8toriousAi; first boot is his to witness.
 */
#ifndef KIDO_PL011_H
#define KIDO_PL011_H

#include "kido-boot.h"

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

/* Verified bases and clock (see the header's KNOWN BASES note). */
#define KIDO_PL011_QEMU_VIRT_BASE    0x09000000u
#define KIDO_PL011_QEMU_VIRT_CLK_HZ  24000000u
#define KIDO_PL011_RPI4_BASE         0xFE201000u
/* No KIDO_PL011_RPI4_CLK_HZ: unverified this session (see above). */

/* Configure a PL011 at base for baud, given its UART clock in Hz.
 * Line format is fixed 8N1, FIFOs enabled, no flow control, no IRQ,
 * no DMA. Safe to call on a firmware-configured UART (reproduces
 * its setup on QEMU virt at 24 MHz / 115200); safe to call twice.
 * Returns EARLY_ENV on bad args, an unrepresentable divisor
 * (IBRD 0 or > 0xFFFF), or a BUSY wait that never clears. No
 * register is touched when an argument check fails first. */
kido_status_t kido_pl011_init(uint64_t base, uint32_t uartclk_hz,
                              uint32_t baud);

/* Transmit one byte. Bounded TXFF wait; EARLY_ENV if the
 * transmitter never drains (wedged UART) or base is 0. Works
 * without a prior init call on a firmware-configured UART. */
kido_status_t kido_pl011_putc(uint64_t base, char c);

/* Transmit a NUL-terminated string. Stops at the first error and
 * propagates it; NULL string is EARLY_ENV. */
kido_status_t kido_pl011_puts(uint64_t base, const char *s);

/* Non-waiting RX probe: *ready = 1 when a byte waits in the RX
 * FIFO, 0 when empty. Never an error for an empty FIFO. */
kido_status_t kido_pl011_poll(uint64_t base, uint8_t *ready);

/* Receive one byte (the waiting path). Bounded RXFE wait;
 * EARLY_ENV on expiry (wedged UART), on a byte with OE/BE/PE/FE
 * error bits (ECR cleared, byte discarded, never delivered),
 * or on bad args. Pair with poll() when waiting is unwanted. */
kido_status_t kido_pl011_getc(uint64_t base, char *out);

#endif /* KIDO_PL011_H */
