// Copyright 2018 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 fuchsia.hardware.platform.bus;

using fuchsia.hardware.platform.device;
using zx;

type PbusMmio = struct {
    /// Physical address of MMIO region.
    /// Does not need to be page aligned.
    base uint64;
    /// Length of MMIO region in bytes.
    /// Does not need to be page aligned.
    length uint64;
};

type PbusIrq = struct {
    irq uint32;
    /// `ZX_INTERRUPT_MODE_*` flags
    mode uint32;
};

type PbusBti = struct {
    iommu_index uint32;
    bti_id uint32;
};

type PbusSmc = struct {
    /// The device is granted the ability to make SMC calls with service call numbers ranging from
    /// service_call_num_base to service_call_num_base + count - 1.
    service_call_num_base uint32;
    count uint32;
    /// The device has exclusive access to this smc range.
    exclusive bool;
};

/// Device metadata.
type PbusMetadata = struct {
    /// Metadata type.
    type uint32;
    /// Pointer to metadata.
    @buffer
    data vector<uint8>:MAX;
};

/// Device metadata to be passed from bootloader via a ZBI record.
type PbusBootMetadata = struct {
    /// Metadata type (matches `zbi_header_t.type` for bootloader metadata).
    zbi_type uint32;
    /// Matches `zbi_header_t.extra` for bootloader metadata.
    /// Used in cases where bootloader provides multiple metadata records of the same type.
    zbi_extra uint32;
};

type PbusDev = struct {
    name string:MAX;
    /// `BIND_PLATFORM_DEV_VID`
    vid uint32;
    /// `BIND_PLATFORM_DEV_PID`
    pid uint32;
    /// `BIND_PLATFORM_DEV_DID`
    did uint32;
    /// Instance ID. Contributes to device-name if non-zero.
    /// `BIND_PLATFORM_DEV_INSTANCE_ID`
    instance_id uint32;
    mmio vector<PbusMmio>:MAX;
    irq vector<PbusIrq>:MAX;
    bti vector<PbusBti>:MAX;
    smc vector<PbusSmc>:MAX;
    metadata vector<PbusMetadata>:MAX;
    boot_metadata vector<PbusBootMetadata>:MAX;
};

/// Subset of pdev_board_info_t to be set by the board driver.
type PbusBoardInfo = struct {
    /// Board name from the boot image platform ID record,
    /// (or from the BIOS on x86 platforms).
    board_name string:32;
    /// Board specific revision number.
    board_revision uint32;
};

type PbusBootloaderInfo = struct {
    vendor string:32;
};

@transport("Banjo")
@banjo_layout("ddk-callback")
closed protocol PbusSysSuspend {
    strict Callback(struct {
        requested_state uint8;
        enable_wake bool;
        suspend_reason uint8;
    }) -> (struct {
        out_status zx.Status;
        out_state uint8;
    });
};

@transport("Banjo")
@banjo_layout("ddk-protocol")
@default_protocol
closed protocol PBus {
    /// Adds a new platform device to the bus, using configuration provided by |dev|.
    /// Platform devices are created in their own separate devhosts.
    strict DeviceAdd(struct {
        dev PbusDev;
    }) -> (struct {
        s zx.Status;
    });
    /// Adds a device for binding a protocol implementation driver.
    /// These devices are added in the same devhost as the platform bus.
    /// After the driver binds to the device it calls `pbus_register_protocol()`
    /// to register its protocol with the platform bus.
    /// `pbus_protocol_device_add()` blocks until the protocol implementation driver
    /// registers its protocol (or times out).
    strict ProtocolDeviceAdd(struct {
        proto_id uint32;
        dev PbusDev;
    }) -> (struct {
        s zx.Status;
    });
    /// Called by protocol implementation drivers to register their protocol
    /// with the platform bus.
    strict RegisterProtocol(struct {
        proto_id uint32;
        @buffer
        protocol vector<uint8>:MAX;
    }) -> (struct {
        s zx.Status;
    });
    /// Board drivers may use this to get information about the board, and to
    /// differentiate between multiple boards that they support.
    strict GetBoardInfo() -> (struct {
        s zx.Status;
        info fuchsia.hardware.platform.device.PdevBoardInfo;
    });
    /// Board drivers may use this to set information about the board
    /// (like the board revision number).
    /// Platform device drivers can access this via `pdev_get_board_info()`.
    strict SetBoardInfo(struct {
        info PbusBoardInfo;
    }) -> (struct {
        s zx.Status;
    });
    /// Board drivers may use this to set information about the bootloader.
    strict SetBootloaderInfo(struct {
        info PbusBootloaderInfo;
    }) -> (struct {
        s zx.Status;
    });
    strict RegisterSysSuspendCallback(resource struct {
        suspend_cb client_end:PbusSysSuspend;
    }) -> (struct {
        s zx.Status;
    });
    /// Deprecated, use AddComposite() instead.
    /// Adds a composite platform device to the bus. The platform device specified by |dev|
    /// is the zeroth fragment and the |fragments| array specifies fragments 1 through n.
    /// The composite device is started in a the driver host of the
    /// |primary_fragment| if it is specified, or a new driver host if it is is
    /// NULL. It is not possible to set the primary fragment to "pdev" as that
    /// would cause the driver to spawn in the platform bus's driver host.
    // Note: fragments is of type device_fragment_t*.
    // TODO(https://fxbug.dev/42148112): restore type.
    strict CompositeDeviceAdd(struct {
        dev PbusDev;
        fragments uint64;
        fragments_count uint64;
        primary_fragment string:MAX;
    }) -> (struct {
        s zx.Status;
    });

    /// Adds a composite platform device to the bus.
    // TODO(https://fxbug.dev/42148112): Restore |fragments| to device_fragment_t* type.
    strict AddComposite(struct {
        dev PbusDev;
        fragments uint64;
        fragment_count uint64;
        primary_fragment string:MAX;
    }) -> (struct {
        s zx.Status;
    });
};