| // Copyright 2019 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.goldfish; |
| |
| using zx; |
| |
| // Interface for the Goldfish address space driver. |
| |
| enum AddressSpaceChildDriverType : uint32 { |
| /// The DEFAULT child driver type is for graphics. |
| DEFAULT = 0; |
| }; |
| |
| // State |
| // The driver consists of three main pieces of state: |
| |
| // 1. A PCI BAR that clients can suballocate into. This is used for mapping |
| // coherent memory from the hardware, such as for Vulkan HOST_COHERENT |
| // memory, or for any other buffer owned by the hardware such as video |
| // codec buffers. This also includes a mapping where each connection of the |
| // driver is associated with one or more mappings. |
| |
| // The next two pieces of state are for child driver connections. |
| |
| // 2. A set of context handles, one per driver connection that the client |
| // establishes. This is used to support higher-level/VMM-defined (child) |
| // drivers. Each such driver is considered a "child" driver of goldfish address |
| // space. |
| |
| // 3. A set of command pages, one per connection. This is used as a shared |
| // device/host memory to support the "Ping" command. The "Ping" command is used |
| // to run the child driver logic, driven by the app. There is a protocol to |
| // permanently associate a particular goldfish address space driver connection |
| // with a particular type of child driver, discussed next. |
| |
| [Layout = "Simple"] |
| protocol AddressSpaceDevice { |
| OpenChildDriver(AddressSpaceChildDriverType type, request<AddressSpaceChildDriver> req); |
| }; |
| |
| // Child driver protocol |
| |
| // By default, creating connection to the driver does not associate any child |
| // driver with the connection. |
| |
| // The client opens a child driver via OpenChildDriver, giving the type of the |
| // driver as an argument along with a request for the connection. The type of |
| // the driver is a number and the number/drivertype mapping is |
| // determined/maintained in: |
| // https://android.googlesource.com/platform/external/qemu/+/refs/heads/emu-master-dev/android/android-emu/android/emulation/AddressSpaceService.h |
| // In Fuchsia, we currently only support the DEFAULT type, which is used for |
| // graphics. |
| |
| /// After opening the child driver, the client and hardware communicate via a |
| /// child driver-specific protocol, with notifications driven by |
| /// Ping(), each of which writes and reads messages to the hardware |
| /// that follow this AddressSpaceChildDriverPingMessage struct. |
| /// Each child driver type will have its own semantics for each field. |
| /// It's common for child drivers to refer to offset/size plus a metadata |
| /// field. We also provide extra data fields for other use cases in |
| /// particular child drivers. |
| struct AddressSpaceChildDriverPingMessage { |
| uint64 offset; |
| uint64 size; |
| uint64 metadata; |
| uint64 data0; |
| uint64 data1; |
| uint32 data2; |
| uint32 data3; |
| }; |
| |
| [Layout = "Simple"] |
| protocol AddressSpaceChildDriver { |
| // Allocates goldfish address space of given size. |
| AllocateBlock(uint64 size) -> (zx.status res, uint64 paddr, handle<vmo>? vmo); |
| // Free goldfish address space associated with given ID. |
| DeallocateBlock(uint64 paddr) -> (zx.status res); |
| |
| // Claim a region at [offset, offset + size) that is a subregion of a |
| // larger region managed by hardware. It is possible to share the same |
| // regions across different connections, but within a connection, we |
| // require the claimed regions to be disjoint. Otherwise, ZX_ERROR_INVALID_ARGS |
| // is returned. |
| ClaimSharedBlock(uint64 offset, uint64 size) -> (zx.status res, handle<vmo>? vmo); |
| |
| // Unclaim a hardware-shared region. This must correspond to an existing claimed |
| // region in the current connection. Otherwise, ZX_ERROR_INVALID_ARGS is returned. |
| UnclaimSharedBlock(uint64 offset) -> (zx.status res); |
| |
| // Ping (General notification for child drivers) |
| Ping(AddressSpaceChildDriverPingMessage ping) |
| -> (zx.status res, AddressSpaceChildDriverPingMessage ping); |
| }; |