// Copyright 2018 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=11)
library fuchsia.vulkan.loader;

using zx;

type Features = flexible bits {
    /// Implements Get().
    GET = 1;
    /// Implements ConnectToDeviceFs().
    CONNECT_TO_DEVICE_FS = 2;
    /// Implements ConnectToManifestFs().
    CONNECT_TO_MANIFEST_FS = 4;
};

type ConnectToManifestOptions = flexible bits {
    /// Wait for the loader to finish processing current ICD loading/unloading
    /// operations before completing the connection.
    WAIT_FOR_IDLE = 1;
};

/// Error type returned by [`Loader.GetVmexResource`].
@available(added=HEAD)
type GetVmexResourceError = flexible enum {
    /// The structured config value `allow_lavapipe_icd` is false.
    LAVAPIPE_ICD_NOT_ALLOWED = 1;

    /// The loader was unable to obtain a `VmexResource` handle.
    FAILED_TO_OBTAIN_RESOURCE = 2;
};

/// Service to provide Vulkan libraries to the loader.
@discoverable
closed protocol Loader {
    /// Requests a client driver library with the given name from the Vulkan loader
    /// service. Returns a VMO suitable for loading as a dynamic library on
    /// success, a null handle on failure.
    strict Get(struct {
        name string:64;
    }) -> (resource struct {
        lib zx.Handle:<VMO, optional>;
    });

    /// Connects to a FS serving fuchsia.io containing all Vulkan ICD manifests.
    /// See
    /// <https://github.com/KhronosGroup/Vulkan-Loader/blob/master/loader/LoaderAndLayerInterface.md#icd-manifest-file-format>
    /// for a description of the manifest file format.  Manifests will always
    /// appear in this directory after the relevant device appears in
    /// `ConnectToDeviceFs()`.
    strict ConnectToManifestFs(resource struct {
        options ConnectToManifestOptions;
        channel zx.Handle:CHANNEL;
    });

    /// Connects to a FS serving fuchsia.io containing all device nodes
    /// potentially relevant to ICDs.  /dev/<devname> will be served under
    /// <devname> in this directory.
    strict ConnectToDeviceFs(resource struct {
        channel zx.Handle:CHANNEL;
    });

    /// Returns the set of features the loader service supports.
    strict GetSupportedFeatures() -> (struct {
        features Features;
    });

    /// Returns a VmexResource that can be used by Lavapipe to JIT-compile code in the client
    /// process, or an error.
    @available(added=HEAD)
    strict GetVmexResource() -> (resource struct {
        resource zx.Handle:<RESOURCE>;
    }) error GetVmexResourceError;
};