/*
  StarForth — Steady-State Virtual Machine Runtime
  Copyright (c) 2023–2025 Robert A. James. All rights reserved.
  Licensed under the StarForth License, Version 1.0.
 */

/**
 * rpi5_dtb.h - Raspberry Pi 5 (BCM2712) devicetree-based peripheral
 * discovery, for the native (non-UEFI) boot path (FABRIC-3.md §IV.3).
 *
 * Two lookups: the PL011 UART (early console) and the VideoCore mailbox
 * property interface (framebuffer setup, §IV.3 item 3). Both peripherals
 * live under BCM2712's own devicetree "soc" simple-bus node, which
 * applies one fixed address translation to every child `reg` value —
 * see `rpi5_dtb.c`'s own doc comment for the confirmed offset and where
 * it was verified. `fdt.c`'s reader deliberately does not do general
 * `ranges`-property translation (it is "not a general devicetree
 * library"); this file applies the one, fixed, SoC-wide offset by name
 * instead of teaching `fdt.c` a general mechanism for a single known
 * hardware fact.
 */

#ifndef STARKERNEL_RPI5_DTB_H
#define STARKERNEL_RPI5_DTB_H

#include <stdint.h>

/**
 * @brief Find the PL011 UART's CPU-physical base address from the DTB.
 *
 * @param dtb  Devicetree blob, as passed to the native boot entry (or
 *             `BootInfo->dtb`); NULL is safe.
 * @return Final CPU-physical MMIO base address, or 0 if the node is
 *         absent, malformed, or @p dtb is invalid.
 */
uint64_t rpi5_uart_base(const void* dtb);

/**
 * @brief Find the VideoCore mailbox property interface's CPU-physical
 * base address from the DTB.
 *
 * @param dtb  Devicetree blob; NULL is safe.
 * @return Final CPU-physical MMIO base address, or 0 if the node is
 *         absent, malformed, or @p dtb is invalid.
 */
uint64_t rpi5_mailbox_base(const void* dtb);

#endif /* STARKERNEL_RPI5_DTB_H */