// Copyright 2023 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.
@available(added=HEAD)
library fuchsia.hardware.amlogiccanvas;

using zx;

type CanvasFlags = flexible bits : uint32 {
    READ = 0b0001;
    WRITE = 0b0010;
    /// Wrap accesses outside of [0, height).
    WRAP_VERTICAL = 0b0100;
    /// Wrap accesses outside of [0, width).
    WRAP_HORIZONTAL = 0b1000;
};

type CanvasBlockMode = flexible enum : uint32 {
    LINEAR = 0x0;
    BLOCK_32X32 = 0x1;
    BLOCK_64X32 = 0x2;
};

/// Describes the byte ordering ("endianness") in each 128-bit (16-bytes) chunk
/// of pixel data.
///
/// The default byte ordering for canvas images is called "128-bit
/// little-endian". For example, each little-endian chunk in an R8G8B8A8 image
/// contains 4 pixels, laid out as follows:
///   R0, G0, B0, A0, R1, G1, B1, A1, R2, G2, B2, A2, R3, G3, B3, A3.
///
/// Hardware modules may write to the memory interface using different byte
/// orderings. The byte ordering (endianness) is expressed as a sequence of
/// pairwise swaps of all 8/16/32/64-bit sub-chunks in a chunk. These swap
/// operations are commutative, so their ordering does not matter.
///
/// For example, if hardware writes images in 64-bit (8-byte) big-endian,
/// [`SWAP_8BIT_PAIRS`], [`SWAP_16BIT_PAIRS`] and [`SWAP_32BIT_PAIRS`] will be
/// needed:
///   The original bytes written by the hardware:
///     A1, B1, G1, R1, A0, B0, G0, R0,   A3, B3, G3, R3, A2, B2, G2, R2,...
///   Swapping every 8-bit pair we get:
///     B1, A1, R1, G1, B0, A0, R0, G0,   B3, A3, R3, G3, B2, A2, R2, G2,...
///   Then we swap every 16-bit pair:
///     R1, G1, B1, A1, R0, G0, B0, A0,   R3, G3, B3, A3, R2, G2, B2, A2,...
///   Then we swap every 32-bit pair:
///     R0, G0, B0, A0, R1, G1, B1, A1,   R2, G2, B2, A2, R3, G3, B3, A3,...
///   to get the correct interpretation.
type CanvasEndianness = flexible bits : uint32 {
    // The ordering involves pairwise swaps of all 8-bit sub-chunks.
    SWAP_8BIT_PAIRS = 0b0001;
    // The ordering involves pairwise swaps of all 16-bit sub-chunks.
    SWAP_16BIT_PAIRS = 0b0010;
    // The ordering involves pairwise swaps of all 32-bit sub-chunks.
    SWAP_32BIT_PAIRS = 0b0100;
    // The ordering involves pairwise swaps of all 64-bit sub-chunks.
    SWAP_64BIT_PAIRS = 0b1000;
};

/// CanvasInfo corresponds to the DMC_CAV_LUT_DATAL/DATAH registers used to
/// program memory layout and format for a single canvas.
type CanvasInfo = struct {
    /// Height in rows.
    height uint32;
    /// Offset between rows of pixels, in bytes.
    stride_bytes uint32;
    /// Use a tiled layout if non-zero.
    blkmode CanvasBlockMode;
    /// Ordering of bytes in each 128-bit (16-byte) chunk of pixel data.
    endianness CanvasEndianness;
    /// Flags to control access to canvas memory.
    flags CanvasFlags;
};

@discoverable
closed protocol Device {
    /// Configures a canvas. Canvases are a special construct in the AMLogic
    /// memory controller, used to turn image data accesses into memory accesses
    /// while respecting block/tiling, stride, and endianness.
    ///
    /// `vmo` is the backing memory to use for this canvas.
    /// `offset` is the relative address for image data within `vmo`.
    /// `info` describes the canvas layout (see CanvasInfo for details).
    strict Config(resource struct {
        vmo zx.Handle:VMO;
        offset uint64;
        info CanvasInfo;
    }) -> (struct {
        canvas_idx uint8;
    }) error zx.Status;
    /// Frees up a canvas.
    strict Free(struct {
        canvas_idx uint8;
    }) -> () error zx.Status;
};

service Service {
    device client_end:Device;
};