/*
  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_mailbox.h - VideoCore mailbox property-interface framebuffer
 * setup, for the native (non-UEFI) Raspberry Pi 5 boot path
 * (FABRIC-3.md §IV.3 item 3).
 *
 * Register layout, message/tag format, and property-tag IDs confirmed
 * against multiple sources before writing `rpi5_mailbox.c` — see that
 * file's own doc comment for exactly which, and what (if anything)
 * remains unverified against real hardware (not in hand until
 * 2026-09-17; this driver has never run on real silicon).
 */

#ifndef STARKERNEL_RPI5_MAILBOX_H
#define STARKERNEL_RPI5_MAILBOX_H

#include <stdint.h>

/* Mirrors uefi.h's FramebufferInfo exactly -- populated by
 * rpi5_mailbox_get_framebuffer() the same shape UEFI GOP already
 * populates it, so console.c/vt100.c/framebuffer.c need no changes at
 * all for this path. Not #include-ing uefi.h here (that header is a
 * large UEFI-protocol grab-bag; this driver only needs this one
 * struct's shape) -- callers that already have a `FramebufferInfo*`
 * (from uefi.h) can pass it directly, since the two struct
 * definitions are kept in exact field-for-field sync by convention.
 */
typedef struct {
    void*    base;
    uint64_t size;
    uint32_t width;
    uint32_t height;
    uint32_t pixels_per_scanline;
    uint32_t pixel_format; /* 0 = RGB, matches uefi.h's
                             * PixelRedGreenBlueReserved8BitPerColor --
                             * this driver always requests RGB pixel
                             * order explicitly (tag 0x00048006), never
                             * leaves it at hardware/firmware default. */
} Rpi5FramebufferInfo;

/**
 * @brief Request a framebuffer from the VideoCore firmware via the
 * mailbox property interface, at the requested resolution/depth.
 *
 * Sends one buffer with all six setup tags (physical size, virtual
 * size, depth, pixel order, virtual offset, allocate) plus a
 * get-pitch tag, in one request/response round trip.
 *
 * @param dtb     Devicetree blob (passed to `rpi5_mailbox_base()`).
 * @param width   Requested physical+virtual width, pixels.
 * @param height  Requested physical+virtual height, pixels.
 * @param bpp     Requested bits per pixel (32 is the only depth this
 *                driver has been designed against; others are not
 *                refused outright but are unverified).
 * @param out     Populated on success; untouched on failure.
 * @return 0 on success, negative on failure (mailbox node not found
 *         in the DTB, VC firmware rejected the request, or a response
 *         tag came back with an unexpected size).
 */
int rpi5_mailbox_get_framebuffer(const void* dtb, uint32_t width, uint32_t height,
                                  uint32_t bpp, Rpi5FramebufferInfo* out);

#endif /* STARKERNEL_RPI5_MAILBOX_H */