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