blob: 3be17e767829e24dcaf4c8e07e3c793552ccbb34 [file] [log] [blame]
// 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);
};