// 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.diagnostics;

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

type DriverLog = struct {
    name DriverName;
    log_level fuchsia.diagnostics.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;
};

/// 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;

    // TODO(https://fxbug.dev/42073139): This parameter should either be updated
    // or removed.
    /// Specify additional offers from the test to a driver collection
    /// Default: empty
    @available(added=HEAD)
    11: offers vector<Offer>:MAX;

    // TODO(https://fxbug.dev/42073139): This parameter should either be updated
    // or removed.
    /// Specify services to expose from the test to a driver collection
    /// Default: empty
    @available(added=HEAD)
    12: exposes vector<Expose>:MAX;

    /// 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;
};

/// 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;
};