blob: b25ff457575c4651b6d1399edcbb3a56187760e3 [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;
type BufferHandleType = strict enum : uint32 {
INVALID = 0;
BUFFER = 1;
COLOR_BUFFER = 2;
};
/// 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.
type ColorBufferFormatType = strict enum : uint32 {
// Equals to GL_LUMINANCE
LUMINANCE = 0x1909;
// Equals to GL_RG
RG = 0x8227;
// Equals to GL_RGBA
RGBA = 0x1908;
// Equals to GL_BGRA
BGRA = 0x80E1;
};
/// 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.
const MEMORY_PROPERTY_DEVICE_LOCAL uint32 = 0x00000001;
/// `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()`.
const MEMORY_PROPERTY_HOST_VISIBLE uint32 = 0x00000002;
/// Input arguments of `ControlDevice.CreateColorBuffer2()` method.
/// Includes necessary properties of a Vulkan-backed color buffer.
type CreateColorBuffer2Params = table {
/// Width of the color buffer (unit: pixel).
///
/// This argument is mandatory. `CreateColorBuffer2()` method returns
/// `ZX_ERR_INVALID_ARGS` if `width` is missing.
1: width uint32;
/// Height of the color buffer (unit: pixel).
///
/// This argument is mandatory. `CreateColorBuffer2()` method returns
/// `ZX_ERR_INVALID_ARGS` if `height` is missing.
2: height uint32;
/// Color format type of the color buffer.
///
/// This argument is mandatory. `CreateColorBuffer2()` method returns
/// `ZX_ERR_INVALID_ARGS` if `format` is missing.
3: format ColorBufferFormatType;
/// 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.
4: memory_property uint32;
/// 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.
5: physical_address uint64;
};
/// Input arguments of `ControlDevice.CreateBuffer2()` method.
/// Includes necessary properties of a Vulkan-backed data buffer.
type CreateBuffer2Params = table {
/// Size of the buffer (unit: byte).
///
/// This argument is mandatory. `CreateBuffer2()` method returns
/// `ZX_ERR_INVALID_ARGS` if `size` is missing.
1: size uint64;
/// 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.
2: memory_property uint32;
/// 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.
3: physical_address uint64;
};
/// Basic info of a control device buffer handle.
type BufferHandleInfo = table {
// The ColorBuffer/Buffer ID.
1: id uint32;
// Type of the buffer handle.
2: type BufferHandleType;
// Memory property flags the buffer should support. Only bits
// from `fuchsia.hardware.goldfish.MEMORY_PROPERTY_*` are allowed.
3: memory_property uint32;
};
/// Interface for the Goldfish control driver providing color buffers and
/// data buffers.
protocol ControlDevice {
/// 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.
CreateColorBuffer2(resource struct {
vmo zx.handle:VMO;
create_params CreateColorBuffer2Params;
}) -> (struct {
res zx.status;
hw_address_page_offset int32;
});
/// 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.
CreateBuffer2(resource struct {
vmo zx.handle:VMO;
create_params CreateBuffer2Params;
}) -> (struct {
hw_address_page_offset int32;
}) error zx.status;
/// 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
GetBufferHandle(resource struct {
vmo zx.handle:VMO;
}) -> (struct {
res zx.status;
id uint32;
type BufferHandleType;
});
/// 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.
GetBufferHandleInfo(resource struct {
vmo zx.handle:VMO;
}) -> (struct {
info BufferHandleInfo;
}) error zx.status;
/// 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.
CreateSyncFence(resource struct {
event zx.handle:EVENTPAIR;
}) -> (struct {}) error zx.status;
};