sdk/fidl/fuchsia.driver.development/development.fidl - fuchsia - Git at Google

 // 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.
 library fuchsia.driver.development;

 using fuchsia.component.decl;
 using fuchsia.driver.framework;
 using fuchsia.driver.legacy;
 using fuchsia.pkg;
 using fuchsia.url;
 using zx;

 const BINDING_RESULT_MAX uint8 = 10;

 type DeviceInfo = table {
     /// (DFv1/DFv2) Unique ID identifying the device.
     1: id uint64;

     /// (DFv1/DFv2) List of ids representing parents. If more than one, this
     /// device is a composite device node.
     2: parent_ids vector<uint64>:MAX;

     /// (DFv1/DFv2) List of ids representing children.
     3: child_ids vector<uint64>:MAX;

     /// (DFv1/DFv2) The process KOID of the driver host the driver resides
     /// within.
     4: driver_host_koid zx.Koid;

     /// (DFv1) The topological path of the driver.
     5: topological_path string:fuchsia.driver.legacy.DEVICE_PATH_MAX;

     /// (DFv1) Path to the driver shared library.
     6: bound_driver_libname string:fuchsia.driver.legacy.DEVICE_PATH_MAX;

     /// (DFv1/DFv2) URL to the driver component manifest
     7: bound_driver_url string:fuchsia.url.MAX_URL_LENGTH;

     /// (DFv1) Properties of the device.
     8: property_list fuchsia.driver.legacy.DevicePropertyList;

     /// (DFv1) Tracks the state of the device.
     9: flags fuchsia.driver.legacy.DeviceFlags;

     /// (DFv2) The collection-relative moniker of the node.
    10: moniker string:fuchsia.driver.legacy.DEVICE_PATH_MAX;

     /// (DFv2) Properties of the node.
    11: node_property_list
             vector<fuchsia.driver.framework.NodeProperty>:fuchsia.driver.framework.MAX_PROPERTY_COUNT;

     /// (DFv2): Component offers to the node.
    12: offer_list vector<fuchsia.component.decl.Offer>:MAX;

     /// (DFv1): Banjo protocol ID
    13: protocol_id uint32;

     /// (DFv1): Banjo protocol name
    14: protocol_name string:MAX;
 };

 /// Information about a node binding to either a driver or a composite.
 type NodeBindingInfo = table {
     /// Full topological name of the node.
     1: node_name string:fuchsia.driver.legacy.DEVICE_PATH_MAX;
     /// This is the component url for the driver that bound to the node.
     /// If this is present, then |composite_parents| and |legacy_composite_parents| must not be.
     2: driver_url string:fuchsia.url.MAX_URL_LENGTH;
     /// The composite parents that this node binded to.
     /// Can be present alongside |legacy_composite_parents|, but not |driver_url|.
     3: composite_parents vector<fuchsia.driver.framework.CompositeParent>:MAX;
     /// The legacy composite parents that this node binded to.
     /// Can be present alongside |composite_parents|, but not |driver_url|.
     4: legacy_composite_parents vector<fuchsia.driver.legacy.CompositeParent>:MAX;
 };

 /// Contains information for either a composite or legacy composite.
 type CompositeInfo = strict union {
     1: legacy_composite fuchsia.driver.legacy.CompositeInfo;
     2: composite fuchsia.driver.framework.CompositeInfo;
 };

 /// Contains information for a composite node.
 type CompositeNodeInfo = table {
     /// The topological paths of the parent nodes of this composite, ordered by index.
     1: parent_topological_paths vector<string:<MAX, optional>>:MAX;

     /// The topological path of the created composite node. Empty if not created.
     2: topological_path string:MAX;

     // Information about the composite.
     3: composite CompositeInfo;
 };

 type TestNodeAddArgs = table {
     /// Name of the node.
     1: name string:fuchsia.driver.legacy.DEVICE_PATH_MAX;

     /// Properties of the node.
     2: properties
             vector<fuchsia.driver.framework.NodeProperty>:fuchsia.driver.framework.MAX_PROPERTY_COUNT;
 };

 /// These flags indicate when a |fuchsia.driver.index.DriverIndex::MatchDriver| call should be
 /// made for a node that is restarting in order to find a new driver, instead of reusing the driver
 /// that was previously bound to the node.
 type RematchFlags = flexible bits : uint32 {
     /// Rematch nodes that are currently bound to the requested driver. The requested driver is
     /// the driver url that the restart operation was initiated for.
     REQUESTED = 0x0001;
     /// Rematch nodes that are currently bound to a driver other than the requested driver. These
     /// are nodes that are affected by the restart of the requested driver, for example when
     /// it is a colocated parent.
     NON_REQUESTED = 0x0002;
     /// Rematch nodes that are legacy composite nodes.
     LEGACY_COMPOSITE = 0x0004;
     /// Rematch nodes that are created as part of a completed composite spec.
     COMPOSITE_SPEC = 0x0008;
 };

 closed protocol DriverInfoIterator {
     /// Return empty when no more entries left.
     strict GetNext() -> (struct {
         drivers vector<fuchsia.driver.framework.DriverInfo>:MAX;
     });
 };

 /// Used to page through a CompositeList.
 closed protocol CompositeInfoIterator {
     /// Returns up to 100 entries at a time. Return empty when no more
     /// composites are left.
     strict GetNext() -> (struct {
         composites vector<CompositeNodeInfo>:MAX;
     });
 };

 closed protocol CompositeNodeSpecIterator {
     /// Return empty when no more node groups are left.
     strict GetNext() -> (struct {
         specs vector<fuchsia.driver.framework.CompositeInfo>:MAX;
     });
 };

 closed protocol DeviceInfoIterator {
     /// Return empty when no more entries left.
     strict GetNext() -> (struct {
         drivers vector<DeviceInfo>:MAX;
     });
 };

 /// Interface for developing and debugging drivers.
 /// This interface should only be used for development and disabled in release builds.
 @discoverable
 open protocol DriverIndex {
     /// Returns a list of all drivers that are known to the system.
     /// If a |driver_filter| is provided, the returned list will be filtered to
     /// only include drivers specified in the filter.
     ///
     /// |iterator| is closed with following epitaphs on error:
     /// ZX_ERR_NOT_FOUND indicates that there is no driver matching the given path for at least
     /// one driver in |driver_filter|.
     /// ZX_ERR_BUFFER_TOO_SMALL indicates that the driver's bind program is longer than the
     /// maximum number of instructions (BIND_PROGRAM_INSTRUCTIONS_MAX).
     flexible GetDriverInfo(resource struct {
         driver_filter vector<string:MAX>:MAX;
         iterator server_end:DriverInfoIterator;
     });

     /// Returns a list of all composite node specs that are known to the system.
     /// If a |name_filter| is provided, the returned list will only include 1 spec,
     /// the one with that exact name.
     ///
     /// |iterator| is closed with following epitaphs on error:
     /// ZX_ERR_NOT_FOUND indicates that there are no specs or if a |name_filter| is provided,
     /// that there are no specs with that name.
     flexible GetCompositeNodeSpecs(resource struct {
         name_filter string:<MAX, optional>;
         iterator server_end:CompositeNodeSpecIterator;
     });

     /// Disable the given driver url from being returned as a match. When this is called,
     /// subsequent |fuchsia.driver.index.DriverIndex::MatchDriver| requests will not consider
     /// the driver with the given url.
     /// This can be used for all driver package types. The given driver url does not
     /// have to match existing drivers, it will apply even if the driver appears afterwards,
     /// for example through a |fuchsia.driver.registrar.Register| operation.
     flexible DisableMatchWithDriverUrl(struct {
         driver_url fuchsia.pkg.PackageUrl;
     }) -> ();

     /// Re-enables a given driver url, that was previously disabled with
     /// |DisableMatchWithDriverUrl|, for matching again. This must be called for driver urls that
     /// were previously disabled.
     /// Will return ZX_ERR_NOT_FOUND if the `driver_url` was not previously disabled.
     flexible ReEnableMatchWithDriverUrl(struct {
         driver_url fuchsia.pkg.PackageUrl;
     }) -> () error zx.Status;
 };

 /// Interface for developing and debugging drivers.
 /// This interface should only be used for development and disabled in release builds.
 @discoverable
 open protocol DriverDevelopment {
     compose DriverIndex;

     /// Restarts all driver hosts containing the driver specified by `driver path`, and returns the
     /// number of driver hosts that were restarted.
     flexible RestartDriverHosts(struct {
         driver_path string:fuchsia.driver.legacy.DEVICE_PATH_MAX;
         rematch_flags RematchFlags;
     }) -> (struct {
         count uint32;
     }) error zx.Status;

     /// Returns the list of devices that are running on the system.
     ///
     /// If a |device_filter| is provided, the returned list will be filtered to
     /// only include devices specified in the filter. If |exact_match| is true,
     /// then the filter must exactly match a device's topological path;
     /// otherwise, it performs a substring match. The list will be empty if no
     /// devices match the filter.
     ///
     /// |iterator| is closed with following epitaphs on error:
     /// ZX_ERR_BAD_PATH indicates that the given path is not valid.
     /// ZX_ERR_BUFFER_TOO_SMALL indicates either that the given path is too long,
     /// or that the device has more than the maximum number of properties (PROPERTIES_MAX).
     flexible GetDeviceInfo(resource struct {
         device_filter vector<string:MAX>:MAX;
         iterator server_end:DeviceInfoIterator;
         exact_match bool;
     });

     /// Returns the list of composites in the system. This includes composites
     /// that are not yet assembled and added into the node topology.
     flexible GetCompositeInfo(resource struct {
         iterator server_end:CompositeInfoIterator;
     });


     /// (DFv2) Attempts to bind all unbound nodes in the topology.
     /// Returns new successful binds.
     flexible BindAllUnboundNodes() -> (struct {
         /// List of new bindings that happened as a result of this.
         binding_result vector<NodeBindingInfo>:BINDING_RESULT_MAX;
     }) error zx.Status;

     // TODO(fxbug.dev/107895): Remove this method once it is no longer being
     // used.
     // Returns a boolean value of whether or not driver framework version 2 is
     // enabled.
     flexible IsDfv2() -> (struct {
         response bool;
     });

     /// (DFv2) Adds test node under the root node.
     flexible AddTestNode(struct {
         args TestNodeAddArgs;
     }) -> () error fuchsia.driver.framework.NodeError;

     /// (DFv2) Removes the test node. The node is removed asynchronously and is
     /// not guaranteed to be removed by the time this returns.
     flexible RemoveTestNode(struct {
         name string:fuchsia.driver.legacy.DEVICE_PATH_MAX;
     }) -> () error zx.Status;
 };
	// 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.
	library fuchsia.driver.development;

	using fuchsia.component.decl;
	using fuchsia.driver.framework;
	using fuchsia.driver.legacy;
	using fuchsia.pkg;
	using fuchsia.url;
	using zx;

	const BINDING_RESULT_MAX uint8 = 10;

	type DeviceInfo = table {
	/// (DFv1/DFv2) Unique ID identifying the device.
	1: id uint64;

	/// (DFv1/DFv2) List of ids representing parents. If more than one, this
	/// device is a composite device node.
	2: parent_ids vector<uint64>:MAX;

	/// (DFv1/DFv2) List of ids representing children.
	3: child_ids vector<uint64>:MAX;

	/// (DFv1/DFv2) The process KOID of the driver host the driver resides
	/// within.
	4: driver_host_koid zx.Koid;

	/// (DFv1) The topological path of the driver.
	5: topological_path string:fuchsia.driver.legacy.DEVICE_PATH_MAX;

	/// (DFv1) Path to the driver shared library.
	6: bound_driver_libname string:fuchsia.driver.legacy.DEVICE_PATH_MAX;

	/// (DFv1/DFv2) URL to the driver component manifest
	7: bound_driver_url string:fuchsia.url.MAX_URL_LENGTH;

	/// (DFv1) Properties of the device.
	8: property_list fuchsia.driver.legacy.DevicePropertyList;

	/// (DFv1) Tracks the state of the device.
	9: flags fuchsia.driver.legacy.DeviceFlags;

	/// (DFv2) The collection-relative moniker of the node.
	10: moniker string:fuchsia.driver.legacy.DEVICE_PATH_MAX;

	/// (DFv2) Properties of the node.
	11: node_property_list
	vector<fuchsia.driver.framework.NodeProperty>:fuchsia.driver.framework.MAX_PROPERTY_COUNT;

	/// (DFv2): Component offers to the node.
	12: offer_list vector<fuchsia.component.decl.Offer>:MAX;

	/// (DFv1): Banjo protocol ID
	13: protocol_id uint32;

	/// (DFv1): Banjo protocol name
	14: protocol_name string:MAX;
	};

	/// Information about a node binding to either a driver or a composite.
	type NodeBindingInfo = table {
	/// Full topological name of the node.
	1: node_name string:fuchsia.driver.legacy.DEVICE_PATH_MAX;
	/// This is the component url for the driver that bound to the node.
	/// If this is present, then \|composite_parents\| and \|legacy_composite_parents\| must not be.
	2: driver_url string:fuchsia.url.MAX_URL_LENGTH;
	/// The composite parents that this node binded to.
	/// Can be present alongside \|legacy_composite_parents\|, but not \|driver_url\|.
	3: composite_parents vector<fuchsia.driver.framework.CompositeParent>:MAX;
	/// The legacy composite parents that this node binded to.
	/// Can be present alongside \|composite_parents\|, but not \|driver_url\|.
	4: legacy_composite_parents vector<fuchsia.driver.legacy.CompositeParent>:MAX;
	};

	/// Contains information for either a composite or legacy composite.
	type CompositeInfo = strict union {
	1: legacy_composite fuchsia.driver.legacy.CompositeInfo;
	2: composite fuchsia.driver.framework.CompositeInfo;
	};

	/// Contains information for a composite node.
	type CompositeNodeInfo = table {
	/// The topological paths of the parent nodes of this composite, ordered by index.
	1: parent_topological_paths vector<string:<MAX, optional>>:MAX;

	/// The topological path of the created composite node. Empty if not created.
	2: topological_path string:MAX;

	// Information about the composite.
	3: composite CompositeInfo;
	};

	type TestNodeAddArgs = table {
	/// Name of the node.
	1: name string:fuchsia.driver.legacy.DEVICE_PATH_MAX;

	/// Properties of the node.
	2: properties
	vector<fuchsia.driver.framework.NodeProperty>:fuchsia.driver.framework.MAX_PROPERTY_COUNT;
	};

	/// These flags indicate when a \|fuchsia.driver.index.DriverIndex::MatchDriver\| call should be
	/// made for a node that is restarting in order to find a new driver, instead of reusing the driver
	/// that was previously bound to the node.
	type RematchFlags = flexible bits : uint32 {
	/// Rematch nodes that are currently bound to the requested driver. The requested driver is
	/// the driver url that the restart operation was initiated for.
	REQUESTED = 0x0001;
	/// Rematch nodes that are currently bound to a driver other than the requested driver. These
	/// are nodes that are affected by the restart of the requested driver, for example when
	/// it is a colocated parent.
	NON_REQUESTED = 0x0002;
	/// Rematch nodes that are legacy composite nodes.
	LEGACY_COMPOSITE = 0x0004;
	/// Rematch nodes that are created as part of a completed composite spec.
	COMPOSITE_SPEC = 0x0008;
	};

	closed protocol DriverInfoIterator {
	/// Return empty when no more entries left.
	strict GetNext() -> (struct {
	drivers vector<fuchsia.driver.framework.DriverInfo>:MAX;
	});
	};

	/// Used to page through a CompositeList.
	closed protocol CompositeInfoIterator {
	/// Returns up to 100 entries at a time. Return empty when no more
	/// composites are left.
	strict GetNext() -> (struct {
	composites vector<CompositeNodeInfo>:MAX;
	});
	};

	closed protocol CompositeNodeSpecIterator {
	/// Return empty when no more node groups are left.
	strict GetNext() -> (struct {
	specs vector<fuchsia.driver.framework.CompositeInfo>:MAX;
	});
	};

	closed protocol DeviceInfoIterator {
	/// Return empty when no more entries left.
	strict GetNext() -> (struct {
	drivers vector<DeviceInfo>:MAX;
	});
	};

	/// Interface for developing and debugging drivers.
	/// This interface should only be used for development and disabled in release builds.
	@discoverable
	open protocol DriverIndex {
	/// Returns a list of all drivers that are known to the system.
	/// If a \|driver_filter\| is provided, the returned list will be filtered to
	/// only include drivers specified in the filter.
	///
	/// \|iterator\| is closed with following epitaphs on error:
	/// ZX_ERR_NOT_FOUND indicates that there is no driver matching the given path for at least
	/// one driver in \|driver_filter\|.
	/// ZX_ERR_BUFFER_TOO_SMALL indicates that the driver's bind program is longer than the
	/// maximum number of instructions (BIND_PROGRAM_INSTRUCTIONS_MAX).
	flexible GetDriverInfo(resource struct {
	driver_filter vector<string:MAX>:MAX;
	iterator server_end:DriverInfoIterator;
	});

	/// Returns a list of all composite node specs that are known to the system.
	/// If a \|name_filter\| is provided, the returned list will only include 1 spec,
	/// the one with that exact name.
	///
	/// \|iterator\| is closed with following epitaphs on error:
	/// ZX_ERR_NOT_FOUND indicates that there are no specs or if a \|name_filter\| is provided,
	/// that there are no specs with that name.
	flexible GetCompositeNodeSpecs(resource struct {
	name_filter string:<MAX, optional>;
	iterator server_end:CompositeNodeSpecIterator;
	});

	/// Disable the given driver url from being returned as a match. When this is called,
	/// subsequent \|fuchsia.driver.index.DriverIndex::MatchDriver\| requests will not consider
	/// the driver with the given url.
	/// This can be used for all driver package types. The given driver url does not
	/// have to match existing drivers, it will apply even if the driver appears afterwards,
	/// for example through a \|fuchsia.driver.registrar.Register\| operation.
	flexible DisableMatchWithDriverUrl(struct {
	driver_url fuchsia.pkg.PackageUrl;
	}) -> ();

	/// Re-enables a given driver url, that was previously disabled with
	/// \|DisableMatchWithDriverUrl\|, for matching again. This must be called for driver urls that
	/// were previously disabled.
	/// Will return ZX_ERR_NOT_FOUND if the `driver_url` was not previously disabled.
	flexible ReEnableMatchWithDriverUrl(struct {
	driver_url fuchsia.pkg.PackageUrl;
	}) -> () error zx.Status;
	};

	/// Interface for developing and debugging drivers.
	/// This interface should only be used for development and disabled in release builds.
	@discoverable
	open protocol DriverDevelopment {
	compose DriverIndex;

	/// Restarts all driver hosts containing the driver specified by `driver path`, and returns the
	/// number of driver hosts that were restarted.
	flexible RestartDriverHosts(struct {
	driver_path string:fuchsia.driver.legacy.DEVICE_PATH_MAX;
	rematch_flags RematchFlags;
	}) -> (struct {
	count uint32;
	}) error zx.Status;

	/// Returns the list of devices that are running on the system.
	///
	/// If a \|device_filter\| is provided, the returned list will be filtered to
	/// only include devices specified in the filter. If \|exact_match\| is true,
	/// then the filter must exactly match a device's topological path;
	/// otherwise, it performs a substring match. The list will be empty if no
	/// devices match the filter.
	///
	/// \|iterator\| is closed with following epitaphs on error:
	/// ZX_ERR_BAD_PATH indicates that the given path is not valid.
	/// ZX_ERR_BUFFER_TOO_SMALL indicates either that the given path is too long,
	/// or that the device has more than the maximum number of properties (PROPERTIES_MAX).
	flexible GetDeviceInfo(resource struct {
	device_filter vector<string:MAX>:MAX;
	iterator server_end:DeviceInfoIterator;
	exact_match bool;
	});

	/// Returns the list of composites in the system. This includes composites
	/// that are not yet assembled and added into the node topology.
	flexible GetCompositeInfo(resource struct {
	iterator server_end:CompositeInfoIterator;
	});


	/// (DFv2) Attempts to bind all unbound nodes in the topology.
	/// Returns new successful binds.
	flexible BindAllUnboundNodes() -> (struct {
	/// List of new bindings that happened as a result of this.
	binding_result vector<NodeBindingInfo>:BINDING_RESULT_MAX;
	}) error zx.Status;

	// TODO(fxbug.dev/107895): Remove this method once it is no longer being
	// used.
	// Returns a boolean value of whether or not driver framework version 2 is
	// enabled.
	flexible IsDfv2() -> (struct {
	response bool;
	});

	/// (DFv2) Adds test node under the root node.
	flexible AddTestNode(struct {
	args TestNodeAddArgs;
	}) -> () error fuchsia.driver.framework.NodeError;

	/// (DFv2) Removes the test node. The node is removed asynchronously and is
	/// not guaranteed to be removed by the time this returns.
	flexible RemoveTestNode(struct {
	name string:fuchsia.driver.legacy.DEVICE_PATH_MAX;
	}) -> () error zx.Status;
	};