fuchsia.hardware.goldfish

PROTOCOLS

AddressSpaceChildDriver

Defined in fuchsia.hardware.goldfish/goldfish_address_space.fidl

AllocateBlock

Allocates goldfish address space of given size.

Request

Name	Type
size	uint64

Response

Name	Type
res	zx/status
paddr	uint64
vmo	handle<vmo>?

ClaimSharedBlock

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.

Request

Name	Type
offset	uint64
size	uint64

Response

Name	Type
res	zx/status
vmo	handle<vmo>?

DeallocateBlock

Free goldfish address space associated with given ID.

Request

Name	Type
paddr	uint64

Response

Name	Type
res	zx/status

Ping

Ping (General notification for child drivers)

Request

Name	Type
ping	AddressSpaceChildDriverPingMessage

Response

Name	Type
res	zx/status
ping	AddressSpaceChildDriverPingMessage

UnclaimSharedBlock

Unclaim a hardware-shared region. This must correspond to an existing claimed region in the current connection. Otherwise, ZX_ERROR_INVALID_ARGS is returned.

Request

Name	Type
offset	uint64

Response

Name	Type
res	zx/status

AddressSpaceDevice

Defined in fuchsia.hardware.goldfish/goldfish_address_space.fidl

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.

OpenChildDriver

Request

Name	Type
type	AddressSpaceChildDriverType
req	request<AddressSpaceChildDriver>

ControlDevice

Defined in fuchsia.hardware.goldfish/goldfish_control.fidl

Interface for the Goldfish control driver providing color buffers and data buffers.

CreateBuffer2

Create shared data buffer. Buffer is automatically freed when all references to vmo have been closed. Fails if VMO is not associated with goldfish heap memory.

Arguments Refer to CreateBuffer2Params for input arguments.

Return value Error: - ZX_ERR_ALREADY_EXISTS if a buffer or color buffer has already been created for this VMO. - ZX_ERR_INVALID_ARGS if arguments are invalid. (see CreateBuffer2Params)

 `hw_address_page_offset`:
     Memory page offset of the buffer's hardware-mapped memory.
     For buffers with HOST_VISIBLE memory property bits, this
     value is a non-negative integer in [0, 4095]. For
     non-HOST_VISIBLE memory, this value is negative.

Request

Name	Type
vmo	handle<vmo>
create_params	CreateBuffer2Params

Response

Name	Type
result	ControlDevice_CreateBuffer2_Result

CreateColorBuffer2

Create shared color buffer. Color buffer is automatically freed when all references to vmo have been closed. Fails if VMO is not associated with goldfish heap memory.

Arguments Refer to CreateColorBuffer2Params for input arguments.

Return value res: ZX_ERR_ALREADY_EXISTS if a buffer or color buffer has already been created for this VMO. ZX_ERR_INVALID_ARGS if arguments are invalid. (see CreateColorBuffer2Params) Otherwise returns ZX_OK. hw_address_page_offset: memory page offset of the buffer's hardware-mapped memory. For color buffers with HOST_VISIBLE memory property bits, this value is a non-negative integer in [0, 4095]. For non-HOST_VISIBLE memory or failed allocation, this value is negative.

Request

Name	Type
vmo	handle<vmo>
create_params	CreateColorBuffer2Params

Response

Name	Type
res	zx/status
hw_address_page_offset	int32

CreateSyncFence

Create a sync fence on goldfish control device. Client pass half of an eventpair to this method, and event will signal its peer when all the graphics work already queued on the EGL display context associated with the control device when it is created has finished.

Errors: - ZX_ERR_INTERNAL if device fail to create the fence or fail to trigger the wait.

Request

Name	Type
event	handle<eventpair>

Response

Name	Type
result	ControlDevice_CreateSyncFence_Result

GetBufferHandle

Get a buffer handle for VMO and the type of the handle. Fails if VMO is not associated with neither a color buffer nor a buffer.

Deprecated. Use GetBufferHandleInfo() instead.

DEPRECATED

Request

Name	Type
vmo	handle<vmo>

Response

Name	Type
res	zx/status
id	uint32
type	BufferHandleType

GetBufferHandleInfo

Get the info of buffer handle from a given VMO.

Return value Error: - ZX_ERR_INVALID_ARGS if given vmo is invalid. - ZX_ERR_NOT_FOUND if vmo is not associated with any created goldfish Buffer or ColorBuffer.

 `info`: a BufferHandleInfo object containing the buffer id, type
         and memory information.

Request

Name	Type
vmo	handle<vmo>

Response

Name	Type
result	ControlDevice_GetBufferHandleInfo_Result

Pipe

Defined in fuchsia.hardware.goldfish/goldfish_pipe.fidl

DoCall

Writes count bytes from the IO buffer at specified write offset. Returns ZX_ERR_SHOULD_WAIT if pipe device is not writable.

If it writes to device successfully, it subsequently reads read_count bytes into the IO buffer at specified read_offset. Returns ZX_ERR_SHOULD_WAIT if pipe device is not readable.

Return value actual is the total bytes read from and written to the IO buffer.

The name "DoCall" (instead of "Call") is to avoid collision with LLCPP generated code "class Call" (generated per protocol). We don't want this method attempting to compile as if it were a constructor.

Request

Name	Type
count	uint64
offset	uint64
read_count	uint64
read_offset	uint64

Response

Name	Type
res	zx/status
actual	uint64

GetBuffer

Acquire VMO for IO buffer. Can be called multiple times. Each call returns a new handle to the VMO.

Request

<EMPTY>

Response

Name	Type
res	zx/status
vmo	handle<vmo>?

Read

Attempt to read up to count bytes into IO buffer at specified offset. Returns ZX_ERR_SHOULD_WAIT if pipe device is not readable.

Request

Name	Type
count	uint64
offset	uint64

Response

Name	Type
res	zx/status
actual	uint64

SetBufferSize

Request new IO buffer size. Can fail if out of memory. Discards contents of existing buffer on success. Leaves existing buffer intact on failure.

Request

Name	Type
size	uint64

Response

Name	Type
res	zx/status

SetEvent

Set event used to signal device state. Discards existing event after having transferred device state to the new event.

Request

Name	Type
event	handle<event>

Write

Writes up to count bytes from the IO buffer at specified offset. Returns ZX_ERR_SHOULD_WAIT if pipe device is not writable.

Request

Name	Type
count	uint64
offset	uint64

Response

Name	Type
res	zx/status
actual	uint64

PipeDevice

Defined in fuchsia.hardware.goldfish/goldfish_pipe.fidl

Interface for the Goldfish pipe driver.

OpenPipe

Open pipe. A protocol request pipe_request provides an interface to the pipe. Multiple pipes can be opened for a single device. Closing the device connection will also close all pipe connections. TODO(fxbug.dev/6547): Unify device and pipe.

Request

Name	Type
pipe_request	request<Pipe>

SyncDevice

Defined in fuchsia.hardware.goldfish/goldfish_sync.fidl

Goldfish sync device provides a simple and lightweight path to let device (or "host") run specific commands (mostly graphics-related, such as waiting on GPU command completion) triggered by Fuchsia (or "guest") and notify Fuchsia once the command finishes.

A sync device could maintain multiple "Timelines", each of which can wait on multiple commands (i.e. "guest->host" commands) and signal specific Fuchsia events once a command finishes executing on device.

CreateTimeline

Create a new sync timeline.

A protocol request timeline_req provides an interface to the SyncTimeline. Each device can have multiple timelines at the same time.

Request

Name	Type
timeline_req	request<SyncTimeline>

Response

<EMPTY>

SyncTimeline

Defined in fuchsia.hardware.goldfish/goldfish_sync.fidl

Timelines can run "guest->host" commands and notifies Fuchsia once a command finishes executing.

The SyncTimeline should be kept alive until both the timeline connection and all events returned from SyncTimeline are closed by clients.

TriggerHostWait

Runs CMD_TRIGGER_HOST_WAIT command: Starts a wait on the sync device ("host") with the given GlSync object and sync thread handles. Once the command ends, event will signal its peer.

Request

Name	Type
host_glsync_handle	uint64
host_syncthread_handle	uint64
event	handle<eventpair>

STRUCTS

AddressSpaceChildDriverPingMessage

Defined in fuchsia.hardware.goldfish/goldfish_address_space.fidl

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.

Field	Type	Description	Default
offset	uint64		No default
size	uint64		No default
metadata	uint64		No default
data0	uint64		No default
data1	uint64		No default
data2	uint32		No default
data3	uint32		No default

ControlDevice_CreateBuffer2_Response

Defined in fuchsia.hardware.goldfish/goldfish_control.fidl

Field	Type	Description	Default
hw_address_page_offset	int32		No default

ControlDevice_CreateSyncFence_Response

Defined in fuchsia.hardware.goldfish/goldfish_control.fidl

<EMPTY>

ControlDevice_GetBufferHandleInfo_Response

Defined in fuchsia.hardware.goldfish/goldfish_control.fidl

Field	Type	Description	Default
info	BufferHandleInfo		No default

ENUMS

AddressSpaceChildDriverType strict

Type: uint32

Defined in fuchsia.hardware.goldfish/goldfish_address_space.fidl

Interface for the Goldfish address space driver.

Name	Value	Description
DEFAULT	0	The DEFAULT child driver type is for graphics.

BufferHandleType strict

Type: uint32

Defined in fuchsia.hardware.goldfish/goldfish_control.fidl

Name	Value	Description
INVALID	0
BUFFER	1
COLOR_BUFFER	2

ColorBufferFormatType strict

Type: uint32

Defined in fuchsia.hardware.goldfish/goldfish_control.fidl

Color buffer formats.

Goldfish control device accepts GL format values as "internalFormat" argument when creating color buffers. All format types should be defined using their format definitions in GL headers.

Name	Value	Description
LUMINANCE	6409
RG	33319
RGBA	6408
BGRA	32993

TABLES

BufferHandleInfo

Defined in fuchsia.hardware.goldfish/goldfish_control.fidl

Basic info of a control device buffer handle.

Ordinal	Field	Type	Description
1	id	uint32
2	type	BufferHandleType
3	memory_property	uint32

CreateBuffer2Params

Defined in fuchsia.hardware.goldfish/goldfish_control.fidl

Input arguments of ControlDevice.CreateBuffer2() method. Includes necessary properties of a Vulkan-backed data buffer.

Ordinal	Field	Type	Description
1	size	uint64	Size of the buffer (unit: byte). This argument is mandatory. CreateBuffer2() method returns ZX_ERR_INVALID_ARGS if size is missing.
2	memory_property	uint32	Memory property flags the buffer should support. Only bits from fuchsia.hardware.goldfish.MEMORY_PROPERTY_* are allowed. This argument is mandatory. CreateBuffer2() method returns ZX_ERR_INVALID_ARGS if memory_property is missing.
3	physical_address	uint64	Goldfish address space device allocates a physical memory address for each host-visible buffer. This address is mapped to a corresponding hardware address when that host-visible buffer is created, and is unmapped when the buffer is torn down. This field stores the physical memory address allocated by address space device. If memory_property has the bit MEMORY_PROPERTY_HOST_VISIBLE set, this argument is mandatory. If physical_address is missing, CreateBuffer2() returns ZX_ERR_INVALID_ARGS. If memory_property doesn't have the MEMORY_PROPERTY_HOST_VISIBLE bit, this argument is ignored.

CreateColorBuffer2Params

Defined in fuchsia.hardware.goldfish/goldfish_control.fidl

Input arguments of ControlDevice.CreateColorBuffer2() method. Includes necessary properties of a Vulkan-backed color buffer.

Ordinal	Field	Type	Description
1	width	uint32	Width of the color buffer (unit: pixel). This argument is mandatory. CreateColorBuffer2() method returns ZX_ERR_INVALID_ARGS if width is missing.
2	height	uint32	Height of the color buffer (unit: pixel). This argument is mandatory. CreateColorBuffer2() method returns ZX_ERR_INVALID_ARGS if height is missing.
3	format	ColorBufferFormatType	Color format type of the color buffer. This argument is mandatory. CreateColorBuffer2() method returns ZX_ERR_INVALID_ARGS if format is missing.
4	memory_property	uint32	Memory property flags the color buffer should support. Only bits from fuchsia.hardware.goldfish.MEMORY_PROPERTY_* are allowed. This argument is mandatory. CreateColorBuffer2() method returns ZX_ERR_INVALID_ARGS if memory_property is missing.
5	physical_address	uint64	Goldfish address space device allocates a physical memory address for each host-visible color buffer. This address is mapped to a corresponding hardware address when that host-visible color buffer is created, and is unmapped when the color buffer is torn down. This field stores the physical memory address allocated by address space device. If memory_property has the bit MEMORY_PROPERTY_HOST_VISIBLE set, this argument is mandatory. If physical_address is missing, CreateColorBuffer2() returns ZX_ERR_INVALID_ARGS. If memory_property doesn't have the MEMORY_PROPERTY_HOST_VISIBLE bit, this argument is ignored.

UNIONS

ControlDevice_CreateBuffer2_Result strict

Defined in fuchsia.hardware.goldfish/goldfish_control.fidl

Ordinal	Variant	Type	Description
1	response	ControlDevice_CreateBuffer2_Response
2	err	zx/status

ControlDevice_CreateSyncFence_Result strict

Defined in fuchsia.hardware.goldfish/goldfish_control.fidl

Ordinal	Variant	Type	Description
1	response	ControlDevice_CreateSyncFence_Response
2	err	zx/status

ControlDevice_GetBufferHandleInfo_Result strict

Defined in fuchsia.hardware.goldfish/goldfish_control.fidl

Ordinal	Variant	Type	Description
1	response	ControlDevice_GetBufferHandleInfo_Response
2	err	zx/status

CONSTANTS

Name	Value	Type	Description
MEMORY_PROPERTY_DEVICE_LOCAL	1	uint32	Memory property flags for color buffers and data buffers. MEMORY_PROPERTY_DEVICE_LOCAL corresponds to Vulkan's memory property VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT. Memory allocated with this type is the most efficient for device access.
MEMORY_PROPERTY_HOST_VISIBLE	2	uint32	MEMORY_PROPERTY_HOST_VISIBLE corresponds to Vulkan's memory property VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT. Memory allocated with this type can be mapped for host access using vkMapMemory().
SIGNAL_HANGUP	67108864	uint32	Signal that will be active on event handle if the device has been disconnected.
SIGNAL_READABLE	16777216	uint32	Signal that will be active on event handle if the Read() method will return data.
SIGNAL_WRITABLE	33554432	uint32	Signal that will be active on event handle if the Write() method will accept data.