// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library zbi;

// TODO(https://fxbug.dev/42062786): Figure out documentation convention.

/// ZBI_TYPE_KERNEL_DRIVER item types (for zbi_header_t.extra)
type KernelDriver = enum : uint32 {
    /// 'PSCI'
    ArmPsci = 0x49435350;

    /// 'GIC2'
    ArmGicV2 = 0x32434947;

    /// 'GIC3'
    ArmGicV3 = 0x33434947;

    /// 'ATIM'
    ArmGenericTimer = 0x4d495441;

    /// 'PL0U'
    Pl011Uart = 0x55304c50;

    /// 'AMLU'
    AmlogicUart = 0x554c4d41;

    /// 'AMLH'
    AmlogicHdcp = 0x484c4d41;

    /// 'DW8U'
    Dw8250Uart = 0x44573855;

    /// 'RMLH' (typoed, originally intended to by 'AMLR')
    AmlogicRngV1 = 0x484c4d52;

    /// 'AMLR'
    AmlogicRngV2 = 0x524c4d41;

    /// 'WD32'
    Generic32Watchdog = 0x32334457;

    /// 'GENI'
    GeniUart = 0x494E4547;

    /// '8250'
    I8250PioUart = 0x30353238;

    /// '825M'
    I8250Mmio32Uart = 0x4d353238;

    /// '825B'
    I8250Mmio8Uart = 0x42353238;

    /// 'MMTU'
    MotmotUart = 0x4d4d5455;

    /// 'MMTP'
    MotmotPower = 0x4d4d5450;

    /// '370P'
    As370Power = 0x50303733;

    /// 'IMXU'
    ImxUart = 0x55584d49;

    /// 'PLIC'
    RiscvPlic = 0x43494C50;

    /// 'RTIM'
    RiscvGenericTimer = 0x4D495452;
};

/// Kernel driver struct that can be used for simple drivers.
/// Used by ZBI_KERNEL_DRIVER_PL011_UART, ZBI_KERNEL_DRIVER_AMLOGIC_UART, and
/// ZBI_KERNEL_DRIVER_GENI_UART, ZBI_KERNEL_DRIVER_I8250_MMIO_UART.
type DcfgSimple = struct {
    mmio_phys uint64;
    irq uint32;
    flags uint32;
};

type KernelDriverIrqFlags = bits : uint32 {
    /// When no flag is set, implies no information was obtained, and the
    /// kernel will apply default configuration as it sees fit.
    EDGE_TRIGGERED = 0x00000001;
    LEVEL_TRIGGERED = 0x00000002;

    /// Interpretation depends on whether is edge or level triggered.
    /// When `LEVEL_TRIGGERED` refers to `ACTIVE_LOW`.
    /// When `EDGE_TRIGGERED` refers to `HIGH_TO_LOW`.
    POLARITY_LOW = 0x00000004;

    /// Interpretation depends on whether is edge or level triggered.
    /// When `LEVEL_TRIGGERED` refers to `ACTIVE_HIGH`.
    /// When `EDGE_TRIGGERED` refers to `LOW_TO_HIGH`.
    POLARITY_HIGH = 0x00000008;
};

/// Used by ZBI_KERNEL_DRIVER_I8250_PIO_UART.
type DcfgSimplePio = struct {
    base uint16;
    reserved uint16;
    irq uint32;
};

/// for ZBI_KERNEL_DRIVER_ARM_PSCI
type DcfgArmPsciDriver = struct {
    use_hvc uint8;
    reserved array<uint8, 7>;
    shutdown_args array<uint64, 3>;
    reboot_args array<uint64, 3>;
    reboot_bootloader_args array<uint64, 3>;
    reboot_recovery_args array<uint64, 3>;
};

/// for ZBI_KERNEL_DRIVER_ARM_GIC_V2
type DcfgArmGicV2Driver = struct {
    mmio_phys uint64;
    msi_frame_phys uint64;
    gicd_offset uint64;
    gicc_offset uint64;
    gich_offset uint64;
    gicv_offset uint64;
    ipi_base uint32;
    optional uint8;
    use_msi uint8;
    reserved uint16;
};

/// for ZBI_KERNEL_DRIVER_ARM_GIC_V3
type DcfgArmGicV3Driver = struct {
    mmio_phys uint64;
    gicd_offset uint64;
    gicr_offset uint64;
    gicr_stride uint64;
    reserved0 uint64;
    ipi_base uint32;
    optional uint8;
    reserved1 array<uint8, 3>;
};

/// for ZBI_KERNEL_DRIVER_ARM_GENERIC_TIMER
type DcfgArmGenericTimerDriver = struct {
    irq_phys uint32;
    irq_virt uint32;
    irq_sphys uint32;
    freq_override uint32;
};

/// for ZBI_KERNEL_DRIVER_AMLOGIC_HDCP
type DcfgAmlogicHdcpDriver = struct {
    preset_phys uint64;
    hiu_phys uint64;
    hdmitx_phys uint64;
};

/// for ZBI_KERNEL_DRIVER_AMLOGIC_RNG_V1
/// for ZBI_KERNEL_DRIVER_AMLOGIC_RNG_V2
type DcfgAmlogicRngDriver = struct {
    rng_data_phys uint64;
    rng_status_phys uint64;
    rng_refresh_interval_usec uint64;
};

/// Defines a register write action for a generic kernel watchdog driver.  An
/// action consists of the following steps.
///
/// 1) Read from the register located a physical address |addr|
/// 2) Clear all of the bits in the value which was read using the |clr_mask|
/// 3) Set all of the bits in the value using the |set_mask|
/// 4) Write this value back to the address located at addr
type DcfgGeneric32WatchdogAction = struct {
    addr uint64;
    clr_mask uint32;
    set_mask uint32;
};

type KernelDriverGeneric32WatchdogFlags = bits : uint32 {
    ENABLED = 0x00000001;
};

/// 1ms
const KERNEL_DRIVER_GENERIC32_WATCHDOG_MIN_PERIOD int64 = 1000000;

/// Definitions of actions which may be taken by a generic 32 bit watchdog timer
/// kernel driver which may be passed by a bootloader.  Field definitions are as
/// follows.
type DcfgGeneric32Watchdog = struct {
    /// The address and masks needed to "pet" (aka, dismiss) a hardware watchdog timer.
    pet_action DcfgGeneric32WatchdogAction;

    /// The address and masks needed to enable a hardware watchdog timer.  If enable
    /// is an unsupported operation, the addr of the |enable_action| shall be zero.
    enable_action DcfgGeneric32WatchdogAction;

    /// The address and masks needed to disable a hardware watchdog timer.  If
    /// disable is an unsupported operation, the addr of the |disable_action| shall
    /// be zero.
    disable_action DcfgGeneric32WatchdogAction;

    /// The period of the watchdog timer given in nanoseconds.  When enabled, the
    /// watchdog timer driver must pet the watch dog at least this often.  The value
    /// must be at least 1 mSec, typically much larger (on the order of a second or
    /// two).
    watchdog_period_nsec int64;

    /// Storage for additional flags.  Currently, only one flag is defined,
    /// "FLAG_ENABLED".  When this flag is set, it indicates that the watchdog timer
    /// was left enabled by the bootloader at startup.
    flags KernelDriverGeneric32WatchdogFlags;

    reserved uint32;
};

/// for ZBI_KERNEL_DRIVER_RISCV_PLIC
type DcfgRiscvPlicDriver = struct {
    mmio_phys uint64;
    num_irqs uint32;
    reserved uint32;
};

/// for ZBI_KERNEL_DRIVER_RISCV_GENERIC_TIMER
type DcfgRiscvGenericTimerDriver = struct {
    freq_hz uint32;
    reserved uint32;
};