sdk/fidl/fuchsia.hardware.goldfish/goldfish_control.fidl - fuchsia - Git at Google

 // 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;

 enum BufferHandleType : 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.
 enum ColorBufferFormatType : 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 uint32 MEMORY_PROPERTY_DEVICE_LOCAL = 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 uint32 MEMORY_PROPERTY_HOST_VISIBLE = 0x00000002;

 /// Input arguments of `ControlDevice.CreateColorBuffer2()` method.
 /// Includes necessary properties of a Vulkan-backed color buffer.
 table CreateColorBuffer2Params {
     /// Width of the color buffer (unit: pixel).
     ///
     /// This argument is mandatory. `CreateColorBuffer2()` method returns
     /// `ZX_ERR_INVALID_ARGS` if `width` is missing.
     1: uint32 width;

     /// Height of the color buffer (unit: pixel).
     ///
     /// This argument is mandatory. `CreateColorBuffer2()` method returns
     /// `ZX_ERR_INVALID_ARGS` if `height` is missing.
     2: uint32 height;

     /// Color format type of the color buffer.
     ///
     /// This argument is mandatory. `CreateColorBuffer2()` method returns
     /// `ZX_ERR_INVALID_ARGS` if `format` is missing.
     3: ColorBufferFormatType format;

     /// 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: uint32 memory_property;

     /// 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: uint64 physical_address;
 };

 /// Input arguments of `ControlDevice.CreateBuffer2()` method.
 /// Includes necessary properties of a Vulkan-backed data buffer.
 table CreateBuffer2Params {
     /// Size of the buffer (unit: byte).
     ///
     /// This argument is mandatory. `CreateBuffer2()` method returns
     /// `ZX_ERR_INVALID_ARGS` if `size` is missing.
     1: uint64 size;

     /// 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: uint32 memory_property;

     /// 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: uint64 physical_address;
 };

 /// Basic info of a control device buffer handle.
 table BufferHandleInfo {
     // The ColorBuffer/Buffer ID.
     1: uint32 id;

     // Type of the buffer handle.
     2: BufferHandleType type;

     // Memory property flags the buffer should support. Only bits
     // from `fuchsia.hardware.goldfish.MEMORY_PROPERTY_*` are allowed.
     3: uint32 memory_property;
 };

 /// 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(zx.handle:VMO vmo,
                        CreateColorBuffer2Params create_params)
         -> (zx.status res, int32 hw_address_page_offset);

     /// 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(zx.handle:VMO vmo, CreateBuffer2Params create_params)
         -> (int32 hw_address_page_offset) 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(zx.handle:VMO vmo)
         -> (zx.status res, uint32 id, BufferHandleType type);

     /// 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(zx.handle:VMO vmo) -> (BufferHandleInfo info) 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(zx.handle:EVENTPAIR event) -> () error zx.status;
 };
	// 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;

	enum BufferHandleType : 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.
	enum ColorBufferFormatType : 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 uint32 MEMORY_PROPERTY_DEVICE_LOCAL = 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 uint32 MEMORY_PROPERTY_HOST_VISIBLE = 0x00000002;

	/// Input arguments of `ControlDevice.CreateColorBuffer2()` method.
	/// Includes necessary properties of a Vulkan-backed color buffer.
	table CreateColorBuffer2Params {
	/// Width of the color buffer (unit: pixel).
	///
	/// This argument is mandatory. `CreateColorBuffer2()` method returns
	/// `ZX_ERR_INVALID_ARGS` if `width` is missing.
	1: uint32 width;

	/// Height of the color buffer (unit: pixel).
	///
	/// This argument is mandatory. `CreateColorBuffer2()` method returns
	/// `ZX_ERR_INVALID_ARGS` if `height` is missing.
	2: uint32 height;

	/// Color format type of the color buffer.
	///
	/// This argument is mandatory. `CreateColorBuffer2()` method returns
	/// `ZX_ERR_INVALID_ARGS` if `format` is missing.
	3: ColorBufferFormatType format;

	/// 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: uint32 memory_property;

	/// 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: uint64 physical_address;
	};

	/// Input arguments of `ControlDevice.CreateBuffer2()` method.
	/// Includes necessary properties of a Vulkan-backed data buffer.
	table CreateBuffer2Params {
	/// Size of the buffer (unit: byte).
	///
	/// This argument is mandatory. `CreateBuffer2()` method returns
	/// `ZX_ERR_INVALID_ARGS` if `size` is missing.
	1: uint64 size;

	/// 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: uint32 memory_property;

	/// 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: uint64 physical_address;
	};

	/// Basic info of a control device buffer handle.
	table BufferHandleInfo {
	// The ColorBuffer/Buffer ID.
	1: uint32 id;

	// Type of the buffer handle.
	2: BufferHandleType type;

	// Memory property flags the buffer should support. Only bits
	// from `fuchsia.hardware.goldfish.MEMORY_PROPERTY_*` are allowed.
	3: uint32 memory_property;
	};

	/// 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(zx.handle:VMO vmo,
	CreateColorBuffer2Params create_params)
	-> (zx.status res, int32 hw_address_page_offset);

	/// 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(zx.handle:VMO vmo, CreateBuffer2Params create_params)
	-> (int32 hw_address_page_offset) 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(zx.handle:VMO vmo)
	-> (zx.status res, uint32 id, BufferHandleType type);

	/// 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(zx.handle:VMO vmo) -> (BufferHandleInfo info) 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(zx.handle:EVENTPAIR event) -> () error zx.status;
	};