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