1// Copyright 2018 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5library ddk.protocol.platform.bus;
6
7using ddk.protocol.platform.device;
8using zx;
9
10struct PbusMmio {
11    /// Physical address of MMIO region.
12    /// Does not need to be page aligned.
13    zx.paddr base;
14    /// Length of MMIO region in bytes.
15    /// Does not need to be page aligned.
16    usize length;
17};
18
19struct PbusIrq {
20    uint32 irq;
21    /// `ZX_INTERRUPT_MODE_*` flags
22    uint32 mode;
23};
24
25struct PbusGpio {
26    uint32 gpio;
27};
28
29struct PbusI2cChannel {
30    uint32 bus_id;
31    uint16 address;
32};
33
34struct PbusClk {
35    uint32 clk;
36};
37
38struct PbusBti {
39    uint32 iommu_index;
40    uint32 bti_id;
41};
42
43struct PbusSmc {
44    /// The device is granted the ability to make SMC calls with service call numbers ranging from
45    /// service_call_num_base to service_call_num_base + count - 1.
46    uint32 service_call_num_base;
47    uint32 count;
48};
49
50/// Device metadata.
51struct PbusMetadata {
52    /// Metadata type.
53    uint32 type;
54    /// Pointer to metadata.
55    vector<voidptr> data;
56};
57
58/// Device metadata to be passed from bootloader via a ZBI record.
59struct PbusBootMetadata {
60    /// Metadata type (matches `zbi_header_t.type` for bootloader metadata).
61    uint32 zbi_type;
62    /// Matches `zbi_header_t.extra` for bootloader metadata.
63    /// Used in cases where bootloader provides multiple metadata records of the same type.
64    uint32 zbi_extra;
65};
66
67struct PbusDev {
68    string name;
69    /// `BIND_PLATFORM_DEV_VID`
70    uint32 vid;
71    /// `BIND_PLATFORM_DEV_PID`
72    uint32 pid;
73    /// `BIND_PLATFORM_DEV_DID`
74    uint32 did;
75    vector<PbusMmio> mmio;
76    vector<PbusIrq> irq;
77    vector<PbusGpio> gpio;
78    vector<PbusI2cChannel> i2c_channel;
79    vector<PbusClk> clk;
80    vector<PbusBti> bti;
81    vector<PbusSmc> smc;
82    vector<PbusMetadata> metadata;
83    vector<PbusBootMetadata> boot_metadata;
84    /// List of this device's child devices.
85    /// This is only used in cases where children of a platform device also need to access
86    /// platform bus resources.
87    vector<PbusDev> child;
88    /// Extra protocols to be provided to this platform device and its children.
89    /// These fields are only used for the top level `pbus_dev_t`.
90    vector<uint32> protocol;
91};
92
93/// Subset of pdev_board_info_t to be set by the board driver.
94struct PbusBoardInfo {
95    /// Board specific revision number.
96    uint32 board_revision;
97};
98
99[Layout = "ddk-callback"]
100interface PlatformProxyCb {
101    Callback(vector<voidptr> req, vector<handle> req_handle) -> (vector<voidptr> resp,
102                                                                 vector<handle> resp_handle);
103};
104
105[Layout = "ddk-protocol"]
106interface PBus {
107    /// Adds a new platform device to the bus, using configuration provided by |dev|.
108    /// Platform devices are created in their own separate devhosts.
109    DeviceAdd(PbusDev dev) -> (zx.status s);
110    /// Adds a device for binding a protocol implementation driver.
111    /// These devices are added in the same devhost as the platform bus.
112    /// After the driver binds to the device it calls `pbus_register_protocol()`
113    /// to register its protocol with the platform bus.
114    /// `pbus_protocol_device_add()` blocks until the protocol implementation driver
115    /// registers its protocol (or times out).
116    ProtocolDeviceAdd(uint32 proto_id, PbusDev dev) -> (zx.status s);
117    /// Called by protocol implementation drivers to register their protocol
118    /// with the platform bus.
119    RegisterProtocol(uint32 proto_id, vector<voidptr> protocol, PlatformProxyCb proxy_cb)
120-> (zx.status s);
121    /// Board drivers may use this to get information about the board, and to
122    /// differentiate between multiple boards that they support.
123    GetBoardInfo() -> (zx.status s, ddk.protocol.platform.device.PdevBoardInfo info);
124    /// Board drivers may use this to set information about the board
125    /// (like the board revision number).
126    /// Platform device drivers can access this via `pdev_get_board_info()`.
127    SetBoardInfo(PbusBoardInfo info) -> (zx.status s);
128};
129