sdk/fidl/fuchsia.driver.loader/driver_loader.fidl

// Copyright 2024 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.driver.loader;

using fuchsia.io;
using zx;

/// ABI that exports the immutable dynamic linking data structures
/// for the loaded modules.
alias DynamicLinkingPassiveAbi = uint64;

/// The root module that can be loaded.
type RootModule = resource table {
    /// Module name.
    1: name string:fuchsia.io.MAX_NAME_LENGTH;
    /// Binary to load.
    2: binary zx.Handle:VMO;
};

/// Protocol through which drivers can be loaded into a driver host process
/// using out-of-process dynamic linking.
@discoverable
open protocol DriverHost {
    /// Loads a driver into the driver host.
    flexible LoadDriver(resource table {
        /// Soname of the driver.
        1: driver_soname string:fuchsia.io.MAX_NAME_LENGTH;
        /// Binary to load.
        2: driver_binary zx.Handle:VMO;
        /// Library dependencies of the driver.
        3: driver_libs client_end:fuchsia.io.Directory;
        /// Additional root modules to be loaded, such as the
        /// DFv1 driver module when running in DFv2 compatibility mode.
        4: additional_root_modules vector<RootModule>:MAX;
    }) -> (table {
        /// The dynamic linking passive ABI for the loaded modules.
        1: dynamic_linking_abi DynamicLinkingPassiveAbi;
    }) error zx.Status;
};

/// Protocol through which a driver host can be launched into a process,
/// with loading done using remote dynamic linking.
@discoverable
open protocol DriverHostLauncher {
    /// Launches |driver_host_binary| into |process|. This includes:
    ///  - Setting up the address space for driver host module and dependencies
    ///    using remote dynamic linking.
    ///  - Creating the stack for the process.
    ///  - Starting the process.
    ///  - Sending the bootstrap messages to the process.
    flexible Launch(resource table {
        /// Process to load the driver host into.
        /// This process must not already be running.
        1: process zx.Handle:PROCESS;
        /// Vmar object that was created when the process was created.
        2: root_vmar zx.Handle:VMAR;
        /// Binary to load.
        3: driver_host_binary zx.Handle:VMO;
        /// vDSO to use for the driver host.
        4: vdso zx.Handle:VMO;
        /// /pkg/lib directory from the driver host package, where library dependencies are found.
        5: driver_host_libs client_end:fuchsia.io.Directory;
        /// Server end of the driver host that will be used to load drivers.
        6: driver_host server_end:DriverHost;
    }) -> () error zx.Status;
};