blob: f30baeb5a0bdd7fef1c7b8a964af6eac311b44aa [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.
type AddressSpaceChildDriverType = strict enum : 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.
@discoverable
protocol AddressSpaceDevice {
OpenChildDriver(resource struct {
type AddressSpaceChildDriverType;
req server_end:AddressSpaceChildDriver;
});
};
/// 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.
type AddressSpaceChildDriverPingMessage = struct {
offset uint64;
size uint64;
metadata uint64;
data0 uint64;
data1 uint64;
data2 uint32;
data3 uint32;
};
protocol AddressSpaceChildDriver {
/// Allocates goldfish address space of given size.
AllocateBlock(struct {
size uint64;
}) -> (resource struct {
res zx.status;
paddr uint64;
vmo zx.handle:<VMO, optional>;
});
/// Free goldfish address space associated with given ID.
DeallocateBlock(struct {
paddr uint64;
}) -> (struct {
res zx.status;
});
/// 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_ARGS1` is returned.
ClaimSharedBlock(struct {
offset uint64;
size uint64;
}) -> (resource struct {
res zx.status;
vmo zx.handle:<VMO, optional>;
});
/// 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(struct {
offset uint64;
}) -> (struct {
res zx.status;
});
/// Ping (General notification for child drivers)
Ping(struct {
ping AddressSpaceChildDriverPingMessage;
}) -> (struct {
res zx.status;
ping AddressSpaceChildDriverPingMessage;
});
};