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

/**
 * fdt_uart.h - the console's serial line, as a board's devicetree names it.
 *
 * A board has one serial line that is its console, and its devicetree says
 * which: /chosen/stdout-path, either the path of a node or an alias for one
 * (/aliases), with line settings after a colon that are not used here.  The
 * firmware that handed the devicetree over has already set that line up.
 * This finds what kind of UART it is, where it is as the CPU addresses it,
 * and how its registers are laid out.
 *
 * Nothing is guessed.  If the devicetree does not name a console, or names
 * one this cannot place or has no driver for, there is no line.
 *
 * Verified off the boards by tools/fdt_uart_test.c.
 */
#ifndef STARKERNEL_FDT_UART_H
#define STARKERNEL_FDT_UART_H

#include <stdint.h>

enum
{
    FDT_UART_NONE = 0,  /**< no line */
    FDT_UART_PL011,     /**< ARM PL011: 32-bit registers, four bytes apart */
    FDT_UART_16550      /**< 16550 and its kin (ns16550a, snps,dw-apb-uart), by memory */
};

typedef struct
{
    int      kind;       /**< FDT_UART_* */
    uint64_t base;       /**< address of register 0, as the CPU sees it */
    uint32_t reg_shift;  /**< register n is at base + (n << reg_shift) */
    uint32_t io_width;   /**< bytes read or written at a time: 1 or 4 */
} fdt_uart_t;

/**
 * @brief Find the console's serial line in a devicetree.
 * @param fdt  Blob; NULL and what is not a devicetree are safe.
 * @param out  Receives the line; its kind is FDT_UART_NONE when 0 is returned.
 * @return 1 if the devicetree names a console UART that was found, placed
 *         and is of a kind listed above; 0 otherwise.
 */
int fdt_console_uart(const void* fdt, fdt_uart_t* out);

#endif /* STARKERNEL_FDT_UART_H */