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:
- 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.
-
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.
-
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.
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
Name | Type |
---|
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
Name | Type |
---|
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.
Name | 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
Name | Type | Description | Default |
---|---|---|---|
hw_address_page_offset |
int32
|
No default |
ControlDevice_CreateSyncFence_Response
Defined in fuchsia.hardware.goldfish/goldfish_control.fidl
Name | Type | Description | Default |
---|
ControlDevice_GetBufferHandleInfo_Response
Defined in fuchsia.hardware.goldfish/goldfish_control.fidl
Name | Type | Description | Default |
---|---|---|---|
info |
BufferHandleInfo
|
No default |
ENUMS
AddressSpaceChildDriverType
Type: uint32
Defined in fuchsia.hardware.goldfish/goldfish_address_space.fidl
Interface for the Goldfish address space driver.
Name | Value | Description |
---|---|---|
DEFAULT |
0 |
The |
BufferHandleType
Type: uint32
Defined in fuchsia.hardware.goldfish/goldfish_control.fidl
Name | Value | Description |
---|---|---|
INVALID |
0 |
|
BUFFER |
1 |
|
COLOR_BUFFER |
2 |
ColorBufferFormatType
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 | Name | 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 | Name | Type | Description |
---|---|---|---|
1 | size |
uint64
|
Size of the buffer (unit: byte). This argument is mandatory. |
2 | memory_property |
uint32
|
Memory property flags the buffer should support. Only bits
from This argument is mandatory. |
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 If |
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 | Name | Type | Description |
---|---|---|---|
1 | width |
uint32
|
Width of the color buffer (unit: pixel). This argument is mandatory. |
2 | height |
uint32
|
Height of the color buffer (unit: pixel). This argument is mandatory. |
3 | format |
ColorBufferFormatType
|
Color format type of the color buffer. This argument is mandatory. |
4 | memory_property |
uint32
|
Memory property flags the color buffer should support. Only bits
from This argument is mandatory. |
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 If |
UNIONS
ControlDevice_CreateBuffer2_Result
Defined in fuchsia.hardware.goldfish/goldfish_control.fidl
Name | Type | Description |
---|---|---|
response |
ControlDevice_CreateBuffer2_Response
|
|
err |
zx/status
|
ControlDevice_CreateSyncFence_Result
Defined in fuchsia.hardware.goldfish/goldfish_control.fidl
Name | Type | Description |
---|---|---|
response |
ControlDevice_CreateSyncFence_Response
|
|
err |
zx/status
|
ControlDevice_GetBufferHandleInfo_Result
Defined in fuchsia.hardware.goldfish/goldfish_control.fidl
Name | Type | Description |
---|---|---|
response |
ControlDevice_GetBufferHandleInfo_Response
|
|
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_HOST_VISIBLE |
2
|
uint32 |
|
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. |