f7/sdk/fidl/fuchsia.hardware.goldfish/README.md

<link rel="stylesheet" href="../style.css" />

[TOC]
# fuchsia.hardware.goldfish

<p><b>Added:7</b></p>

## **PROTOCOLS**

## AddressSpaceChildDriver {#AddressSpaceChildDriver}
*Defined in [fuchsia.hardware.goldfish/goldfish_address_space.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_address_space.fidl;l=74)*

### AllocateBlock {#AddressSpaceChildDriver.AllocateBlock}

<p>Allocates goldfish address space of given size.</p>

#### Request {#AddressSpaceChildDriver.AllocateBlock_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>size</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
</table>


#### Response {#AddressSpaceChildDriver.AllocateBlock_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>res</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
        </tr>
        <tr>
            <td><code>paddr</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
        <tr>
            <td><code>vmo</code></td>
            <td>
                <code>handle&lt;vmo&gt;?</code>
            </td>
        </tr>
</table>

### ClaimSharedBlock {#AddressSpaceChildDriver.ClaimSharedBlock}

<p>Claim a region at <code>[offset, offset + size)</code> 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,
<code>ZX_ERROR_INVALID_ARGS1</code> is returned.</p>

#### Request {#AddressSpaceChildDriver.ClaimSharedBlock_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>offset</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
        <tr>
            <td><code>size</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
</table>


#### Response {#AddressSpaceChildDriver.ClaimSharedBlock_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>res</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
        </tr>
        <tr>
            <td><code>vmo</code></td>
            <td>
                <code>handle&lt;vmo&gt;?</code>
            </td>
        </tr>
</table>

### DeallocateBlock {#AddressSpaceChildDriver.DeallocateBlock}

<p>Free goldfish address space associated with given ID.</p>

#### Request {#AddressSpaceChildDriver.DeallocateBlock_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>paddr</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
</table>


#### Response {#AddressSpaceChildDriver.DeallocateBlock_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>res</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
        </tr>
</table>

### Ping {#AddressSpaceChildDriver.Ping}

<p>Ping (General notification for child drivers)</p>

#### Request {#AddressSpaceChildDriver.Ping_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>ping</code></td>
            <td>
                <code><a class='link' href='#AddressSpaceChildDriverPingMessage'>AddressSpaceChildDriverPingMessage</a></code>
            </td>
        </tr>
</table>


#### Response {#AddressSpaceChildDriver.Ping_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>res</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
        </tr>
        <tr>
            <td><code>ping</code></td>
            <td>
                <code><a class='link' href='#AddressSpaceChildDriverPingMessage'>AddressSpaceChildDriverPingMessage</a></code>
            </td>
        </tr>
</table>

### UnclaimSharedBlock {#AddressSpaceChildDriver.UnclaimSharedBlock}

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

#### Request {#AddressSpaceChildDriver.UnclaimSharedBlock_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>offset</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
</table>


#### Response {#AddressSpaceChildDriver.UnclaimSharedBlock_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>res</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
        </tr>
</table>

## AddressSpaceDevice {#AddressSpaceDevice}
*Defined in [fuchsia.hardware.goldfish/goldfish_address_space.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_address_space.fidl;l=35)*
<p>State
The driver consists of three main pieces of state:</p>
<ol>
<li>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.</li>
</ol>
<p>The next two pieces of state are for child driver connections.</p>
<ol start="2">
<li>
<p>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 &quot;child&quot; driver of goldfish
address space.</p>
</li>
<li>
<p>A set of command pages, one per connection. This is used as a shared
device/host memory to support the &quot;Ping&quot; command. The &quot;Ping&quot; 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.</p>
</li>
</ol>

### OpenChildDriver {#AddressSpaceDevice.OpenChildDriver}


#### Request {#AddressSpaceDevice.OpenChildDriver_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>type</code></td>
            <td>
                <code><a class='link' href='#AddressSpaceChildDriverType'>AddressSpaceChildDriverType</a></code>
            </td>
        </tr>
        <tr>
            <td><code>req</code></td>
            <td>
                <code>request&lt;<a class='link' href='#AddressSpaceChildDriver'>AddressSpaceChildDriver</a>&gt;</code>
            </td>
        </tr>
</table>


## ControlDevice {#ControlDevice}
*Defined in [fuchsia.hardware.goldfish/goldfish_control.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_control.fidl;l=135)*
<p>Interface for the Goldfish control driver providing color buffers and
data buffers.</p>

### CreateBuffer2 {#ControlDevice.CreateBuffer2}

<p>Create shared data buffer. Buffer is automatically freed when
all references to <code>vmo</code> have been closed. Fails if VMO is not
associated with goldfish heap memory.</p>
<p>Arguments
Refer to <code>CreateBuffer2Params</code> for input arguments.</p>
<p>Return value
Error:
- <code>ZX_ERR_ALREADY_EXISTS</code> if a buffer or color buffer has
already been created for this VMO.
- <code>ZX_ERR_INVALID_ARGS</code> if arguments are invalid.
(see <code>CreateBuffer2Params</code>)</p>
<pre><code> `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.
</code></pre>

#### Request {#ControlDevice.CreateBuffer2_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>vmo</code></td>
            <td>
                <code>handle&lt;vmo&gt;</code>
            </td>
        </tr>
        <tr>
            <td><code>create_params</code></td>
            <td>
                <code><a class='link' href='#CreateBuffer2Params'>CreateBuffer2Params</a></code>
            </td>
        </tr>
</table>


#### Response {#ControlDevice.CreateBuffer2_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>result</code></td>
            <td>
                <code><a class='link' href='#ControlDevice_CreateBuffer2_Result'>ControlDevice_CreateBuffer2_Result</a></code>
            </td>
        </tr>
</table>

### CreateColorBuffer2 {#ControlDevice.CreateColorBuffer2}

<p>Create shared color buffer. Color buffer is automatically freed when
all references to <code>vmo</code> have been closed. Fails if VMO is not
associated with goldfish heap memory.</p>
<p>Arguments
Refer to <code>CreateColorBuffer2Params</code> for input arguments.</p>
<p>Return value
<code>res</code>: <code>ZX_ERR_ALREADY_EXISTS</code> if a buffer or color buffer has
already been created for this VMO.
<code>ZX_ERR_INVALID_ARGS</code> if arguments are invalid.
(see <code>CreateColorBuffer2Params</code>)
Otherwise returns <code>ZX_OK</code>.
<code>hw_address_page_offset</code>: 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.</p>

#### Request {#ControlDevice.CreateColorBuffer2_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>vmo</code></td>
            <td>
                <code>handle&lt;vmo&gt;</code>
            </td>
        </tr>
        <tr>
            <td><code>create_params</code></td>
            <td>
                <code><a class='link' href='#CreateColorBuffer2Params'>CreateColorBuffer2Params</a></code>
            </td>
        </tr>
</table>


#### Response {#ControlDevice.CreateColorBuffer2_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>res</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
        </tr>
        <tr>
            <td><code>hw_address_page_offset</code></td>
            <td>
                <code>int32</code>
            </td>
        </tr>
</table>

### CreateSyncFence {#ControlDevice.CreateSyncFence}

<p>Create a sync fence on goldfish control device. Client pass half of an
eventpair to this method, and <code>event</code> 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.</p>
<p>Errors:
- ZX_ERR_INTERNAL if device fail to create the fence or fail to
trigger the wait.</p>

#### Request {#ControlDevice.CreateSyncFence_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>event</code></td>
            <td>
                <code>handle&lt;eventpair&gt;</code>
            </td>
        </tr>
</table>


#### Response {#ControlDevice.CreateSyncFence_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>result</code></td>
            <td>
                <code><a class='link' href='#ControlDevice_CreateSyncFence_Result'>ControlDevice_CreateSyncFence_Result</a></code>
            </td>
        </tr>
</table>

### GetBufferHandle {#ControlDevice.GetBufferHandle}

<p>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.</p>
<p>Deprecated. Use <code>GetBufferHandleInfo()</code> instead.</p>
<p><b>DEPRECATED </b></p>
#### Request {#ControlDevice.GetBufferHandle_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>vmo</code></td>
            <td>
                <code>handle&lt;vmo&gt;</code>
            </td>
        </tr>
</table>


#### Response {#ControlDevice.GetBufferHandle_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>res</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
        </tr>
        <tr>
            <td><code>id</code></td>
            <td>
                <code>uint32</code>
            </td>
        </tr>
        <tr>
            <td><code>type</code></td>
            <td>
                <code><a class='link' href='#BufferHandleType'>BufferHandleType</a></code>
            </td>
        </tr>
</table>

### GetBufferHandleInfo {#ControlDevice.GetBufferHandleInfo}

<p>Get the info of buffer handle from a given VMO.</p>
<p>Return value
Error:
- <code>ZX_ERR_INVALID_ARGS</code> if given <code>vmo</code> is invalid.
- <code>ZX_ERR_NOT_FOUND</code> if <code>vmo</code> is not associated with any created
goldfish Buffer or ColorBuffer.</p>
<pre><code> `info`: a BufferHandleInfo object containing the buffer id, type
         and memory information.
</code></pre>

#### Request {#ControlDevice.GetBufferHandleInfo_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>vmo</code></td>
            <td>
                <code>handle&lt;vmo&gt;</code>
            </td>
        </tr>
</table>


#### Response {#ControlDevice.GetBufferHandleInfo_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>result</code></td>
            <td>
                <code><a class='link' href='#ControlDevice_GetBufferHandleInfo_Result'>ControlDevice_GetBufferHandleInfo_Result</a></code>
            </td>
        </tr>
</table>

## Pipe {#Pipe}
*Defined in [fuchsia.hardware.goldfish/goldfish_pipe.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_pipe.fidl;l=31)*

### DoCall {#Pipe.DoCall}

<p>Writes <code>count</code> bytes from the IO buffer at specified write
<code>offset</code>. Returns <code>ZX_ERR_SHOULD_WAIT</code> if pipe device is not writable.</p>
<p>If it writes to device successfully, it subsequently reads <code>read_count</code>
bytes into the IO buffer at specified <code>read_offset</code>. Returns
<code>ZX_ERR_SHOULD_WAIT</code> if pipe device is not readable.</p>
<p>Return value <code>actual</code> is the total bytes read from and written to
the IO buffer.</p>
<p>The name &quot;DoCall&quot; (instead of &quot;Call&quot;) is to avoid collision with LLCPP
generated code &quot;class Call&quot; (generated per protocol).  We don't want
this method attempting to compile as if it were a constructor.</p>

#### Request {#Pipe.DoCall_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>count</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
        <tr>
            <td><code>offset</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
        <tr>
            <td><code>read_count</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
        <tr>
            <td><code>read_offset</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
</table>


#### Response {#Pipe.DoCall_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>res</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
        </tr>
        <tr>
            <td><code>actual</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
</table>

### GetBuffer {#Pipe.GetBuffer}

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

#### Request {#Pipe.GetBuffer_Request}

&lt;EMPTY&gt;


#### Response {#Pipe.GetBuffer_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>res</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
        </tr>
        <tr>
            <td><code>vmo</code></td>
            <td>
                <code>handle&lt;vmo&gt;?</code>
            </td>
        </tr>
</table>

### Read {#Pipe.Read}

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

#### Request {#Pipe.Read_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>count</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
        <tr>
            <td><code>offset</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
</table>


#### Response {#Pipe.Read_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>res</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
        </tr>
        <tr>
            <td><code>actual</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
</table>

### SetBufferSize {#Pipe.SetBufferSize}

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

#### Request {#Pipe.SetBufferSize_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>size</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
</table>


#### Response {#Pipe.SetBufferSize_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>res</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
        </tr>
</table>

### SetEvent {#Pipe.SetEvent}

<p>Set event used to signal device state. Discards existing event
after having transferred device state to the new event.</p>

#### Request {#Pipe.SetEvent_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>event</code></td>
            <td>
                <code>handle&lt;event&gt;</code>
            </td>
        </tr>
</table>


### Write {#Pipe.Write}

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

#### Request {#Pipe.Write_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>count</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
        <tr>
            <td><code>offset</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
</table>


#### Response {#Pipe.Write_Response}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>res</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
        </tr>
        <tr>
            <td><code>actual</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
</table>

## PipeDevice {#PipeDevice}
*Defined in [fuchsia.hardware.goldfish/goldfish_pipe.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_pipe.fidl;l=21)*
<p>Interface for the Goldfish pipe driver.</p>

### OpenPipe {#PipeDevice.OpenPipe}

<p>Open pipe. A protocol request <code>pipe_request</code> 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 <code>device</code> and <code>pipe</code>.</p>

#### Request {#PipeDevice.OpenPipe_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>pipe_request</code></td>
            <td>
                <code>request&lt;<a class='link' href='#Pipe'>Pipe</a>&gt;</code>
            </td>
        </tr>
</table>


## SyncDevice {#SyncDevice}
*Defined in [fuchsia.hardware.goldfish/goldfish_sync.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_sync.fidl;l=16)*
<p>Goldfish sync device provides a simple and lightweight path to let
device (or &quot;host&quot;) run specific commands (mostly graphics-related, such as
waiting on GPU command completion) triggered by Fuchsia (or &quot;guest&quot;) and
notify Fuchsia once the command finishes.</p>
<p>A sync device could maintain multiple &quot;Timelines&quot;, each of which can wait on
multiple commands (i.e. &quot;guest-&gt;host&quot; commands) and signal specific Fuchsia
events once a command finishes executing on device.</p>

### CreateTimeline {#SyncDevice.CreateTimeline}

<p>Create a new sync timeline.</p>
<p>A protocol request <code>timeline_req</code> provides an interface to the
<code>SyncTimeline</code>. Each device can have multiple timelines at the same
time.</p>

#### Request {#SyncDevice.CreateTimeline_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>timeline_req</code></td>
            <td>
                <code>request&lt;<a class='link' href='#SyncTimeline'>SyncTimeline</a>&gt;</code>
            </td>
        </tr>
</table>


#### Response {#SyncDevice.CreateTimeline_Response}

&lt;EMPTY&gt;

## SyncTimeline {#SyncTimeline}
*Defined in [fuchsia.hardware.goldfish/goldfish_sync.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_sync.fidl;l=32)*
<p>Timelines can run &quot;guest-&gt;host&quot; commands and notifies Fuchsia once a
command finishes executing.</p>
<p>The SyncTimeline should be kept alive until both the timeline connection
and all events returned from SyncTimeline are closed by clients.</p>

### TriggerHostWait {#SyncTimeline.TriggerHostWait}

<p>Runs <code>CMD_TRIGGER_HOST_WAIT</code> command: Starts a wait on the sync device
(&quot;host&quot;) with the given GlSync object and sync thread handles.
Once the command ends, <code>event</code> will signal its peer.</p>

#### Request {#SyncTimeline.TriggerHostWait_Request}

<table>
    <tr><th>Name</th><th>Type</th></tr>
        <tr>
            <td><code>host_glsync_handle</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
        <tr>
            <td><code>host_syncthread_handle</code></td>
            <td>
                <code>uint64</code>
            </td>
        </tr>
        <tr>
            <td><code>event</code></td>
            <td>
                <code>handle&lt;eventpair&gt;</code>
            </td>
        </tr>
</table>



## **STRUCTS**

### AddressSpaceChildDriverPingMessage  {#AddressSpaceChildDriverPingMessage data-text="AddressSpaceChildDriverPingMessage"}
*Defined in [fuchsia.hardware.goldfish/goldfish_address_space.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_address_space.fidl;l=64)*
<p>Child driver protocol</p>
<p>By default, creating connection to the driver does not associate any child
driver with the connection.</p>
<p>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</p>
<p>In Fuchsia, we currently only support the DEFAULT type, which is used for
graphics.</p>
<p>After opening the child driver, the client and hardware communicate via a
child driver-specific protocol, with notifications driven by <code>Ping()</code>, each
of which writes and reads messages to the hardware that follow this
<code>AddressSpaceChildDriverPingMessage</code> 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.</p>

<table>
    <tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
        <tr id="AddressSpaceChildDriverPingMessage.offset">
            <td><code>offset</code></td>
            <td>
                <code>uint64</code>
            </td>
            <td></td>
            <td>No default</td>
        </tr>
        <tr id="AddressSpaceChildDriverPingMessage.size">
            <td><code>size</code></td>
            <td>
                <code>uint64</code>
            </td>
            <td></td>
            <td>No default</td>
        </tr>
        <tr id="AddressSpaceChildDriverPingMessage.metadata">
            <td><code>metadata</code></td>
            <td>
                <code>uint64</code>
            </td>
            <td></td>
            <td>No default</td>
        </tr>
        <tr id="AddressSpaceChildDriverPingMessage.data0">
            <td><code>data0</code></td>
            <td>
                <code>uint64</code>
            </td>
            <td></td>
            <td>No default</td>
        </tr>
        <tr id="AddressSpaceChildDriverPingMessage.data1">
            <td><code>data1</code></td>
            <td>
                <code>uint64</code>
            </td>
            <td></td>
            <td>No default</td>
        </tr>
        <tr id="AddressSpaceChildDriverPingMessage.data2">
            <td><code>data2</code></td>
            <td>
                <code>uint32</code>
            </td>
            <td></td>
            <td>No default</td>
        </tr>
        <tr id="AddressSpaceChildDriverPingMessage.data3">
            <td><code>data3</code></td>
            <td>
                <code>uint32</code>
            </td>
            <td></td>
            <td>No default</td>
        </tr>
</table>

### ControlDevice_CreateBuffer2_Response  {#ControlDevice_CreateBuffer2_Response data-text="ControlDevice_CreateBuffer2_Response"}
*Defined in [fuchsia.hardware.goldfish/goldfish_control.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_control.fidl;l=184)*

<table>
    <tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
        <tr id="ControlDevice_CreateBuffer2_Response.hw_address_page_offset">
            <td><code>hw_address_page_offset</code></td>
            <td>
                <code>int32</code>
            </td>
            <td></td>
            <td>No default</td>
        </tr>
</table>

### ControlDevice_CreateSyncFence_Response  {#ControlDevice_CreateSyncFence_Response data-text="ControlDevice_CreateSyncFence_Response"}
*Defined in [fuchsia.hardware.goldfish/goldfish_control.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_control.fidl;l=227)*

&lt;EMPTY&gt;

### ControlDevice_GetBufferHandleInfo_Response  {#ControlDevice_GetBufferHandleInfo_Response data-text="ControlDevice_GetBufferHandleInfo_Response"}
*Defined in [fuchsia.hardware.goldfish/goldfish_control.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_control.fidl;l=213)*

<table>
    <tr><th>Field</th><th>Type</th><th>Description</th><th>Default</th></tr>
        <tr id="ControlDevice_GetBufferHandleInfo_Response.info">
            <td><code>info</code></td>
            <td>
                <code><a class='link' href='#BufferHandleInfo'>BufferHandleInfo</a></code>
            </td>
            <td></td>
            <td>No default</td>
        </tr>
</table>


## **ENUMS**

### AddressSpaceChildDriverType [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#AddressSpaceChildDriverType data-text="AddressSpaceChildDriverType"}
Type: <code>uint32</code>

*Defined in [fuchsia.hardware.goldfish/goldfish_address_space.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_address_space.fidl;l=9)*
<p>Interface for the Goldfish address space driver.</p>

<table>
    <tr><th>Name</th><th>Value</th><th>Description</th></tr>
        <tr id="AddressSpaceChildDriverType.DEFAULT">
<td><h3 id="AddressSpaceChildDriverType.DEFAULT" class="add-link hide-from-toc">DEFAULT</h3></td>
            <td><code>0</code></td>
            <td><p>The <code>DEFAULT</code> child driver type is for graphics.</p>
</td>
        </tr>
</table>

### BufferHandleType [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#BufferHandleType data-text="BufferHandleType"}
Type: <code>uint32</code>

*Defined in [fuchsia.hardware.goldfish/goldfish_control.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_control.fidl;l=8)*

<table>
    <tr><th>Name</th><th>Value</th><th>Description</th></tr>
        <tr id="BufferHandleType.INVALID">
<td><h3 id="BufferHandleType.INVALID" class="add-link hide-from-toc">INVALID</h3></td>
            <td><code>0</code></td>
            <td></td>
        </tr>
        <tr id="BufferHandleType.BUFFER">
<td><h3 id="BufferHandleType.BUFFER" class="add-link hide-from-toc">BUFFER</h3></td>
            <td><code>1</code></td>
            <td></td>
        </tr>
        <tr id="BufferHandleType.COLOR_BUFFER">
<td><h3 id="BufferHandleType.COLOR_BUFFER" class="add-link hide-from-toc">COLOR_BUFFER</h3></td>
            <td><code>2</code></td>
            <td></td>
        </tr>
</table>

### ColorBufferFormatType [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#ColorBufferFormatType data-text="ColorBufferFormatType"}
Type: <code>uint32</code>

*Defined in [fuchsia.hardware.goldfish/goldfish_control.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_control.fidl;l=19)*
<p>Color buffer formats.</p>
<p>Goldfish control device accepts GL format values as &quot;internalFormat&quot;
argument when creating color buffers. All format types should be
defined using their format definitions in GL headers.</p>

<table>
    <tr><th>Name</th><th>Value</th><th>Description</th></tr>
        <tr id="ColorBufferFormatType.LUMINANCE">
<td><h3 id="ColorBufferFormatType.LUMINANCE" class="add-link hide-from-toc">LUMINANCE</h3></td>
            <td><code>6409</code></td>
            <td></td>
        </tr>
        <tr id="ColorBufferFormatType.RG">
<td><h3 id="ColorBufferFormatType.RG" class="add-link hide-from-toc">RG</h3></td>
            <td><code>33319</code></td>
            <td></td>
        </tr>
        <tr id="ColorBufferFormatType.RGBA">
<td><h3 id="ColorBufferFormatType.RGBA" class="add-link hide-from-toc">RGBA</h3></td>
            <td><code>6408</code></td>
            <td></td>
        </tr>
        <tr id="ColorBufferFormatType.BGRA">
<td><h3 id="ColorBufferFormatType.BGRA" class="add-link hide-from-toc">BGRA</h3></td>
            <td><code>32993</code></td>
            <td></td>
        </tr>
</table>


## **TABLES**

### BufferHandleInfo  {#BufferHandleInfo data-text="BufferHandleInfo"}


*Defined in [fuchsia.hardware.goldfish/goldfish_control.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_control.fidl;l=121)*
<p>Basic info of a control device buffer handle.</p>

<table>
    <tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
        <tr id="BufferHandleInfo.id">
<td><h3 id="BufferHandleInfo.id" class="add-link hide-from-toc">1</h3></td>
            <td><code>id</code></td>
            <td>
                <code>uint32</code>
            </td>
            <td></td>
        </tr>
        <tr id="BufferHandleInfo.type">
<td><h3 id="BufferHandleInfo.type" class="add-link hide-from-toc">2</h3></td>
            <td><code>type</code></td>
            <td>
                <code><a class='link' href='#BufferHandleType'>BufferHandleType</a></code>
            </td>
            <td></td>
        </tr>
        <tr id="BufferHandleInfo.memory_property">
<td><h3 id="BufferHandleInfo.memory_property" class="add-link hide-from-toc">3</h3></td>
            <td><code>memory_property</code></td>
            <td>
                <code>uint32</code>
            </td>
            <td></td>
        </tr>
</table>

### CreateBuffer2Params  {#CreateBuffer2Params data-text="CreateBuffer2Params"}


*Defined in [fuchsia.hardware.goldfish/goldfish_control.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_control.fidl;l=89)*
<p>Input arguments of <code>ControlDevice.CreateBuffer2()</code> method.
Includes necessary properties of a Vulkan-backed data buffer.</p>

<table>
    <tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
        <tr id="CreateBuffer2Params.size">
<td><h3 id="CreateBuffer2Params.size" class="add-link hide-from-toc">1</h3></td>
            <td><code>size</code></td>
            <td>
                <code>uint64</code>
            </td>
            <td><p>Size of the buffer (unit: byte).</p>
<p>This argument is mandatory. <code>CreateBuffer2()</code> method returns
<code>ZX_ERR_INVALID_ARGS</code> if <code>size</code> is missing.</p>
</td>
        </tr>
        <tr id="CreateBuffer2Params.memory_property">
<td><h3 id="CreateBuffer2Params.memory_property" class="add-link hide-from-toc">2</h3></td>
            <td><code>memory_property</code></td>
            <td>
                <code>uint32</code>
            </td>
            <td><p>Memory property flags the buffer should support. Only bits
from <code>fuchsia.hardware.goldfish.MEMORY_PROPERTY_*</code> are allowed.</p>
<p>This argument is mandatory. <code>CreateBuffer2()</code> method returns
<code>ZX_ERR_INVALID_ARGS</code> if <code>memory_property</code> is missing.</p>
</td>
        </tr>
        <tr id="CreateBuffer2Params.physical_address">
<td><h3 id="CreateBuffer2Params.physical_address" class="add-link hide-from-toc">3</h3></td>
            <td><code>physical_address</code></td>
            <td>
                <code>uint64</code>
            </td>
            <td><p>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.</p>
<p>This field stores the physical memory address allocated by address
space device.</p>
<p>If <code>memory_property</code> has the bit <code>MEMORY_PROPERTY_HOST_VISIBLE</code> set,
this argument is mandatory. If <code>physical_address</code> is missing,
<code>CreateBuffer2()</code> returns <code>ZX_ERR_INVALID_ARGS</code>.</p>
<p>If <code>memory_property</code> doesn't have the <code>MEMORY_PROPERTY_HOST_VISIBLE</code>
bit, this argument is ignored.</p>
</td>
        </tr>
</table>

### CreateColorBuffer2Params  {#CreateColorBuffer2Params data-text="CreateColorBuffer2Params"}


*Defined in [fuchsia.hardware.goldfish/goldfish_control.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_control.fidl;l=43)*
<p>Input arguments of <code>ControlDevice.CreateColorBuffer2()</code> method.
Includes necessary properties of a Vulkan-backed color buffer.</p>

<table>
    <tr><th>Ordinal</th><th>Field</th><th>Type</th><th>Description</th></tr>
        <tr id="CreateColorBuffer2Params.width">
<td><h3 id="CreateColorBuffer2Params.width" class="add-link hide-from-toc">1</h3></td>
            <td><code>width</code></td>
            <td>
                <code>uint32</code>
            </td>
            <td><p>Width of the color buffer (unit: pixel).</p>
<p>This argument is mandatory. <code>CreateColorBuffer2()</code> method returns
<code>ZX_ERR_INVALID_ARGS</code> if <code>width</code> is missing.</p>
</td>
        </tr>
        <tr id="CreateColorBuffer2Params.height">
<td><h3 id="CreateColorBuffer2Params.height" class="add-link hide-from-toc">2</h3></td>
            <td><code>height</code></td>
            <td>
                <code>uint32</code>
            </td>
            <td><p>Height of the color buffer (unit: pixel).</p>
<p>This argument is mandatory. <code>CreateColorBuffer2()</code> method returns
<code>ZX_ERR_INVALID_ARGS</code> if <code>height</code> is missing.</p>
</td>
        </tr>
        <tr id="CreateColorBuffer2Params.format">
<td><h3 id="CreateColorBuffer2Params.format" class="add-link hide-from-toc">3</h3></td>
            <td><code>format</code></td>
            <td>
                <code><a class='link' href='#ColorBufferFormatType'>ColorBufferFormatType</a></code>
            </td>
            <td><p>Color format type of the color buffer.</p>
<p>This argument is mandatory. <code>CreateColorBuffer2()</code> method returns
<code>ZX_ERR_INVALID_ARGS</code> if <code>format</code> is missing.</p>
</td>
        </tr>
        <tr id="CreateColorBuffer2Params.memory_property">
<td><h3 id="CreateColorBuffer2Params.memory_property" class="add-link hide-from-toc">4</h3></td>
            <td><code>memory_property</code></td>
            <td>
                <code>uint32</code>
            </td>
            <td><p>Memory property flags the color buffer should support. Only bits
from <code>fuchsia.hardware.goldfish.MEMORY_PROPERTY_*</code> are allowed.</p>
<p>This argument is mandatory. <code>CreateColorBuffer2()</code> method returns
<code>ZX_ERR_INVALID_ARGS</code> if <code>memory_property</code> is missing.</p>
</td>
        </tr>
        <tr id="CreateColorBuffer2Params.physical_address">
<td><h3 id="CreateColorBuffer2Params.physical_address" class="add-link hide-from-toc">5</h3></td>
            <td><code>physical_address</code></td>
            <td>
                <code>uint64</code>
            </td>
            <td><p>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.</p>
<p>This field stores the physical memory address allocated by address
space device.</p>
<p>If <code>memory_property</code> has the bit <code>MEMORY_PROPERTY_HOST_VISIBLE</code> set,
this argument is mandatory. If <code>physical_address</code> is missing,
<code>CreateColorBuffer2()</code> returns <code>ZX_ERR_INVALID_ARGS</code>.</p>
<p>If <code>memory_property</code> doesn't have the <code>MEMORY_PROPERTY_HOST_VISIBLE</code>
bit, this argument is ignored.</p>
</td>
        </tr>
</table>


## **UNIONS**

### ControlDevice_CreateBuffer2_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute}  {#ControlDevice_CreateBuffer2_Result data-text="ControlDevice_CreateBuffer2_Result"}
*Defined in [fuchsia.hardware.goldfish/goldfish_control.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_control.fidl;l=184)*
<table>
    <tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
        <tr id="ControlDevice_CreateBuffer2_Result.response">
<td><h3 id="ControlDevice_CreateBuffer2_Result.response" class="add-link hide-from-toc">1</h3></td>
            <td><code>response</code></td>
            <td>
                <code><a class='link' href='#ControlDevice_CreateBuffer2_Response'>ControlDevice_CreateBuffer2_Response</a></code>
            </td>
            <td></td>
        </tr>
        <tr id="ControlDevice_CreateBuffer2_Result.err">
<td><h3 id="ControlDevice_CreateBuffer2_Result.err" class="add-link hide-from-toc">2</h3></td>
            <td><code>err</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
            <td></td>
        </tr>
</table>

### ControlDevice_CreateSyncFence_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute}  {#ControlDevice_CreateSyncFence_Result data-text="ControlDevice_CreateSyncFence_Result"}
*Defined in [fuchsia.hardware.goldfish/goldfish_control.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_control.fidl;l=227)*
<table>
    <tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
        <tr id="ControlDevice_CreateSyncFence_Result.response">
<td><h3 id="ControlDevice_CreateSyncFence_Result.response" class="add-link hide-from-toc">1</h3></td>
            <td><code>response</code></td>
            <td>
                <code><a class='link' href='#ControlDevice_CreateSyncFence_Response'>ControlDevice_CreateSyncFence_Response</a></code>
            </td>
            <td></td>
        </tr>
        <tr id="ControlDevice_CreateSyncFence_Result.err">
<td><h3 id="ControlDevice_CreateSyncFence_Result.err" class="add-link hide-from-toc">2</h3></td>
            <td><code>err</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
            <td></td>
        </tr>
</table>

### ControlDevice_GetBufferHandleInfo_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute}  {#ControlDevice_GetBufferHandleInfo_Result data-text="ControlDevice_GetBufferHandleInfo_Result"}
*Defined in [fuchsia.hardware.goldfish/goldfish_control.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_control.fidl;l=213)*
<table>
    <tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
        <tr id="ControlDevice_GetBufferHandleInfo_Result.response">
<td><h3 id="ControlDevice_GetBufferHandleInfo_Result.response" class="add-link hide-from-toc">1</h3></td>
            <td><code>response</code></td>
            <td>
                <code><a class='link' href='#ControlDevice_GetBufferHandleInfo_Response'>ControlDevice_GetBufferHandleInfo_Response</a></code>
            </td>
            <td></td>
        </tr>
        <tr id="ControlDevice_GetBufferHandleInfo_Result.err">
<td><h3 id="ControlDevice_GetBufferHandleInfo_Result.err" class="add-link hide-from-toc">2</h3></td>
            <td><code>err</code></td>
            <td>
                <code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#status'>status</a></code>
            </td>
            <td></td>
        </tr>
</table>



## **CONSTANTS**

<table>
    <tr><th>Name</th><th>Value</th><th>Type</th><th>Description</th></tr>
        <tr id="MEMORY_PROPERTY_DEVICE_LOCAL">
            <td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_control.fidl;l=35">MEMORY_PROPERTY_DEVICE_LOCAL</a></td>
                <td>
                    <code>1</code>
                </td>
                <td><code>uint32</code></td>
            <td><p>Memory property flags for color buffers and data buffers.</p>
<p><code>MEMORY_PROPERTY_DEVICE_LOCAL</code> corresponds to Vulkan's memory property
<code>VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT</code>. Memory allocated with this type
is the most efficient for device access.</p>
</td>
        </tr>
        <tr id="MEMORY_PROPERTY_HOST_VISIBLE">
            <td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_control.fidl;l=39">MEMORY_PROPERTY_HOST_VISIBLE</a></td>
                <td>
                    <code>2</code>
                </td>
                <td><code>uint32</code></td>
            <td><p><code>MEMORY_PROPERTY_HOST_VISIBLE</code> corresponds to Vulkan's memory property
<code>VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT</code>. Memory allocated with this type
can be mapped for host access using <code>vkMapMemory()</code>.</p>
</td>
        </tr>
        <tr id="SIGNAL_HANGUP">
            <td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_pipe.fidl;l=18">SIGNAL_HANGUP</a></td>
                <td>
                    <code>67108864</code>
                </td>
                <td><code>uint32</code></td>
            <td><p>Signal that will be active on event handle if the device has been
disconnected.</p>
</td>
        </tr>
        <tr id="SIGNAL_READABLE">
            <td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_pipe.fidl;l=10">SIGNAL_READABLE</a></td>
                <td>
                    <code>16777216</code>
                </td>
                <td><code>uint32</code></td>
            <td><p>Signal that will be active on event handle if the Read() method
will return data.</p>
</td>
        </tr>
        <tr id="SIGNAL_WRITABLE">
            <td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.hardware.goldfish/goldfish_pipe.fidl;l=14">SIGNAL_WRITABLE</a></td>
                <td>
                    <code>33554432</code>
                </td>
                <td><code>uint32</code></td>
            <td><p>Signal that will be active on event handle if the Write() method
will accept data.</p>
</td>
        </tr>
</table>