sdk/fidl/fuchsia.driver.test/realm.fidl

// 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.
@available(added=7)
library fuchsia.driver.test;

using zx;
using fuchsia.io;
using fuchsia.component.resolution;
using fuchsia.component.test;
using fuchsia.diagnostics;
using fuchsia.diagnostics.types;

/// A driver name is the name defined in ZIRCON_DRIVER_BEGIN begin macro
/// for a specific driver.
alias DriverName = string:MAX;

@available(added=HEAD)
const MAX_SOFTWARE_DEVICES uint32 = 20;

@available(replaced=27)
type DriverLog = struct {
    name DriverName;
    log_level fuchsia.diagnostics.Severity;
};

@available(added=27)
type DriverLog = struct {
    name DriverName;
    log_level fuchsia.diagnostics.types.Severity;
};

@available(added=HEAD)
type Collection = strict enum {
    UNKNOWN = 0;
    BOOT_DRIVERS = 1;
    PACKAGE_DRIVERS = 2;
};

@available(added=HEAD)
type Offer = struct {
    protocol_name string:MAX;
    collection Collection;
};

@available(added=HEAD)
type Expose = struct {
    service_name string:MAX;
    collection Collection;
};

@available(added=HEAD)
type SoftwareDevice = struct {
    device_name string:MAX;
    device_id uint32;
};

/// A list of arguments that can be used to configure DriverTestRealm.
type RealmArgs = resource table {
    /// This is what DriverManager will see as its boot directory.
    /// Default: DriverTestRealm's package directory
    1: boot client_end:fuchsia.io.Directory;

    /// The URL for the driver that will be bound to root.
    /// Default: fuchsia-boot:///dtr#meta/test-parent-sys.cm
    /// NOTE: The test parent driver is not included by default. This must
    ///  be included in your package to work correctly.
    2: root_driver string:MAX;

    /// If this is true, then DriverManager will load DFv2 drivers.
    /// Default: false
    @available(removed=18)
    3: use_driver_framework_v2 bool;

    /// If this is true, then DriverManager will enable the unit tests
    /// for each driver that is loaded.
    /// Default: false
    4: driver_tests_enable_all bool;

    /// If this is true, then DriverManager will enable the unit tests
    /// for each driver in this vector.
    /// Default: empty
    5: driver_tests_enable vector<DriverName>:MAX;

    /// If this is true, then DriverManager will disable the unit tests
    /// for each driver in this vector. This overrides both a specific
    /// request for enabling a test and the 'driver_tests_enable_all'
    /// parameter.
    /// Default: empty
    6: driver_tests_disable vector<DriverName>:MAX;

    /// Set a log level for the specific driver.
    /// Default: Log levels are set to INFO
    7: driver_log_level vector<DriverLog>:MAX;

    /// Disable specific drivers. These drivers will not be bound or loaded.
    /// Default: empty
    8: driver_disable vector<DriverName>:MAX;

    /// Specify drivers to bind 'eagerly'. This turns a driver that normally
    /// binds as a fallback driver into a driver that will be bound normally.
    /// Default: empty
    9: driver_bind_eager vector<DriverName>:MAX;

    /// Specify the board name that drivers are aware of.
    /// Default: driver-integration-test
    10: board_name string:MAX;

    /// DEPRECATED: Use dtr_offers.
    /// Specify additional offers from the test to a driver collection
    /// Default: empty
    @available(added=HEAD)
    11: offers vector<Offer>:MAX;

    /// DEPRECATED: Use dtr_exposes.
    /// Specify services to expose from the test to a driver collection
    /// Default: empty
    @available(added=HEAD)
    12: exposes vector<Expose>:MAX;

    /// DEPRECATED: Use test_component to provide resolved test component.
    /// The driver test realm can load drivers packaged with the test suite
    /// through this directory. Note that this directory must be readable
    /// and executable.
    ///
    /// This can be used if the test suite needs to use some drivers packaged
    /// with the DriverTestRealm in addition to drivers packaged with the test
    /// suite. In that case, the user can leave RealmArgs::boot unset and use
    /// RealmArgs::pkg and RealmArgs::driver_urls.
    ///
    /// Drivers in this directory can be registered using the `driver_urls`
    /// argument below.
    ///
    /// Default: DriverTestRealm's package directory.
    @available(added=HEAD)
    13: pkg client_end:fuchsia.io.Directory;

    /// Specify offers from the test to the driver test realm.
    /// The driver test realm will forward these to the driver collections.
    /// Default: empty
    @available(added=22)
    14: dtr_offers vector<fuchsia.component.test.Capability>:MAX;

    /// Specify exposes from the driver test realm to the test.
    /// The driver test realm will forward these from the driver collections.
    /// Default: empty
    @available(added=22)
    15: dtr_exposes vector<fuchsia.component.test.Capability>:MAX;

    /// The resolved component information of the test component that is starting
    /// the driver test realm. This will be used to discover drivers that the test
    /// wants to provide to the driver test realm. Drivers can be both in the test
    /// component package, or a subpackage of the test component package.
    /// By default all drivers discovered that don't also exist in the |boot| directory
    /// will be considered to be base drivers.
    /// Use |boot_driver_components| to provide a list of drivers that should be
    /// boot drivers.
    /// Default: empty
    @available(added=23)
    16: test_component fuchsia.component.resolution.Component;

    /// How long the driver index waits idle before it saves state, escrows its handles
    /// with the component framework, and shuts down.
    /// Default: never shuts down
    @available(added=HEAD)
    17: driver_index_stop_timeout_millis int64;

    /// A list of software only devices that should be created. Typically this is used
    /// to create fake hardware for tests. Devices will be spawned as platform devices
    /// under the platform bus. Note that the platform bus must be the root driver for
    /// this to do anything meaningful.
    @available(added=HEAD)
    18: software_devices vector<SoftwareDevice>:MAX_SOFTWARE_DEVICES;

    /// The list of driver component names that should be considered as boot drivers.
    /// Boot drivers are started in the boot-drivers collection which has more
    /// capabilities available to it.
    /// Entries should be the component name (eg: "my_driver_component.cm").
    /// Default: empty
    @available(added=24)
    19: boot_driver_components vector<string:MAX>:MAX;

    /// Devicetree blob that should be handed to the board driver.
    @available(added=27)
    20: devicetree zx.Handle:VMO;

    /// Platform Vendor ID which should be specified to the platform bus driver.
    @available(added=27)
    21: platform_vid uint32;

    /// Platform ID which should be specified to the platform bus driver.
    @available(added=27)
    22: platform_pid uint32;
};

/// This protocol is for the DriverTestRealm. It is an integration test
/// framework for drivers.
@discoverable
open protocol Realm {
    /// Start the realm. Calling this will cause DriverTestRealm to start
    /// servicing other protocols (like /dev/). `args` is used to configure
    /// the DriverTestRealm.
    ///
    /// * error `ZX_ERR_ALREADY_EXISTS` the realm has already had `Start` called.
    flexible Start(resource struct {
        args RealmArgs;
    }) -> () error zx.Status;
};

@available(added=HEAD)
type GetManifestRequest = table {
    1: using_subpackage bool;
};

@available(added=HEAD)
@discoverable(server="platform")
closed protocol ManifestProvider {
    strict GetManifest(GetManifestRequest) -> (resource struct {
        manifest zx.Handle:STREAM;
    }) error zx.Status;
};