// Copyright 2021 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.

/// AGIS - Android GPU Inspector Service
library fuchsia.gpu.agis;

using zx;

/// AGIS provides FIDL services that facilitate Vulkan command tracing.
/// It acts as an intermediary between gapii, the Android GPU Inspector
/// interposing shared library and Vulkan layer, and the host Android GPU
/// Inspector application.
///
/// Vtc == Vulkan Traceable Component
type Vtc = resource table {
    1: process_koid zx.koid;
    2: process_name string:zx.MAX_NAME_LEN;
    3: agi_socket zx.handle:SOCKET;
};

/// Max vtcs that may be registered.
/// ZX_CHANNEL_MAX_MESSAGE_BYTES = 64KiB.  At an approximate message size
/// of 50B, rounding up to 64B, we easily fit 512 vtcs in a message
/// with ample headroom for message size growth.
///
/// The number of vtcs is determined by developers, rather than users.
/// The typical expected vtc count is 1 considering a developer
/// performing Vulkan tracing on 1 component at a time.
const MAX_VTCS uint32 = 512;

type Error = flexible enum {
    NOT_FOUND = 1;
    ALREADY_REGISTERED = 2;
    VTCS_EXCEEDED = 3;
    INTERNAL_ERROR = 4;
};

/// The AGIS ComponentRegistry protocol allows traceable components to register as
/// Vulkan traceable.
@discoverable
protocol ComponentRegistry {
    /// Register a process as traceable and retrieve its bound socket.
    /// For AGI, gapii will be the only client of this Register interface.
    Register(struct {
        /// Client assigned unique ID for the vtc.
        id uint64;

        /// Process koid.
        process_koid zx.koid;

        /// Must match ZX_PROP_NAME of the kernel object.
        process_name string:zx.MAX_NAME_LEN;
    }) -> (resource struct {
        gapii_socket zx.handle:SOCKET;
    }) error Error;

    /// Remove an entry from the registry.
    Unregister(struct {
        id uint64;
    }) -> (struct {}) error Error;
};

/// The AGIS Observer protocol provides the interface to retrieve registered
/// Vulkan Traceable Components.
@discoverable
protocol Observer {
    /// Retrieve registered components.
    /// For AGI, gapis will be the only client of this Vtcs interface.
    Vtcs() -> (resource struct {
        vtcs vector<Vtc>:MAX_VTCS;
    }) error Error;
};