class DriverBase
Defined at line 89 of file ../../sdk/lib/driver/component/cpp/driver_base.h
|DriverBase| is an interface that drivers should inherit from. It provides methods
for accessing the start args, as well as helper methods for common initialization tasks.
There are four virtual methods:
|Start| which must be overridden.
|PrepareStop|, |Stop|, and the destructor |~DriverBase|, are optional to override.
In order to work with the default FUCHSIA_DRIVER_EXPORT macro,
classes which inherit from |DriverBase| must implement a constructor with the following
signature and forward said parameters to the |DriverBase| base class:
T(DriverStartArgs start_args, fdf::UnownedSynchronizedDispatcher driver_dispatcher);
The following illustrates an example:
```
class MyDriver : public fdf::DriverBase {
public:
MyDriver(fdf::DriverStartArgs start_args, fdf::UnownedSynchronizedDispatcher driver_dispatcher)
: fdf::DriverBase("my_driver", std::move(start_args), std::move(driver_dispatcher)) {}
zx::result
<
> Start() override {
incoming()->Connect(...);
outgoing()->AddService(...);
FDF_LOG(INFO, "hello world!");
inspector().Health().Ok();
node_client_.Bind(std::move(node()), dispatcher());
/* Ensure all capabilities offered have been added to the outgoing directory first. */
auto add_result = node_client_->AddChild(...); if (add_result.is_error()) {
/* Releasing the node channel signals unbind to DF. */
node_client_.AsyncTeardown(); // Or node().reset() if we hadn't moved it into the client.
return add_result.take_error();
}
return zx::ok();
}
private:
fidl::SharedClient
<fuchsia
_driver_framework::Node> node_client_;
};
```
# Thread safety
This class is thread-unsafe. Instances must be managed and used from tasks
running on the |driver_dispatcher|, and the dispatcher must be synchronized.
See
https://fuchsia.dev/fuchsia-src/development/languages/c-cpp/thread-safe-async#synchronized-dispatcher
Protected Members
unique_ptr logger_Public Methods
void DriverBase (std::string_view name, DriverStartArgs start_args, fdf::UnownedSynchronizedDispatcher driver_dispatcher)Defined at line 18 of file ../../sdk/lib/driver/component/cpp/driver_base.cc
void DriverBase (const DriverBase & )Defined at line 102 of file ../../sdk/lib/driver/component/cpp/driver_base.h
DriverBase & operator= (const DriverBase & )Defined at line 103 of file ../../sdk/lib/driver/component/cpp/driver_base.h
zx::result<> Start ()This method will be called by the factory to start the driver. This is when
the driver should setup the outgoing directory through `outgoing()->Add...` calls.
Do not call Serve, as it has already been called by the |DriverBase| constructor.
Child nodes can be created here synchronously or asynchronously as long as all of the
protocols being offered to the child has been added to the outgoing directory first.
There are two versions of this method which may be implemented depending on whether Start would
like to complete synchronously or asynchronously. The driver may override either one of these
methods, but must implement one. The asynchronous version will be called over the synchronous
version if both are implemented.
Defined at line 117 of file ../../sdk/lib/driver/component/cpp/driver_base.h
void Start (StartCompleter completer)Defined at line 118 of file ../../sdk/lib/driver/component/cpp/driver_base.h
void PrepareStop (PrepareStopCompleter completer)This provides a way for the driver to asynchronously prepare to stop. The driver should
initiate any teardowns that need to happen on the driver dispatchers. Once it is ready to stop,
the completer's Complete function can be called (from any thread/context) with a result.
After the completer is called, the framework will shutdown all of the driver's fdf dispatchers
and deallocate the driver.
Defined at line 125 of file ../../sdk/lib/driver/component/cpp/driver_base.h
void Stop ()This is called after all the driver dispatchers belonging to this driver have been shutdown.
This ensures that there are no pending tasks on any of the driver dispatchers that will access
the driver after it has been destroyed.
Defined at line 130 of file ../../sdk/lib/driver/component/cpp/driver_base.h
Logger & logger ()This can be used to log in driver factories:
`FDF_LOGL(INFO, driver->logger(), "...");`
Defined at line 134 of file ../../sdk/lib/driver/component/cpp/driver_base.h
void ~DriverBase ()The destructor is called right after the |Stop| method.
Defined at line 190 of file ../../sdk/lib/driver/component/cpp/driver_base.cc
void RegisterInitMethods (InitMethodCallback cb)Callbacks that are invoked prior to the start hook.
Defined at line 49 of file ../../sdk/lib/driver/component/cpp/driver_base.cc
zx::result<> RunInitMethods ()Runs methods registered. Meant to be invoked prior to the start hook.
Defined at line 53 of file ../../sdk/lib/driver/component/cpp/driver_base.cc
std::optional<fidl::ServerEnd<fuchsia_power_broker::ElementRunner>> take_power_element_runner ()Takes the `fuchsia.power.broker/ElementRunner` channel for this driver's power element. The
caller is expected to run the power element.
Returns std::nullopt if the driver did not specify `suspend_enabled` in its manifest's program
section, this is not a suspend enabled platform, or the channel was not provided to the driver
host.
Defined at line 64 of file ../../sdk/lib/driver/component/cpp/driver_base.cc
std::optional<fidl::ClientEnd<fuchsia_power_broker::Lessor>> take_power_element_lessor ()Takes the `fuchsia.power.broker/Lessor` channel. This allows the caller to lease the power
element.
Returns std::nullopt if the driver did not specify `suspend_enabled` in its manifest's program
section, this is not a suspend enabled platform, or the channel was not provided to the driver
host.
Defined at line 74 of file ../../sdk/lib/driver/component/cpp/driver_base.cc
std::optional<fuchsia_power_broker::DependencyToken> power_element_token ()Returns a copy of the power element token for the driver's power element. This can be called
repeatedly.
Returns std::nullopt if the driver did not specify `suspend_enabled` in its manifest's program
section, this is not a suspend enabled platform, or the token was not provided by the driver
host.
Defined at line 84 of file ../../sdk/lib/driver/component/cpp/driver_base.cc
template <typename DriverBaseImpl>DriverBaseImpl * GetInstanceFromTokenForTesting (void * token)Gets the DriverBase instance from the given token. This is only intended for testing.
Defined at line 93 of file ../../sdk/lib/driver/component/cpp/driver_base.h
Protected Methods
cpp20::span<const fuchsia_driver_framework::NodeProperty2> node_properties_2 (const std::string & parent_node_name)Returns the node properties of the node the driver is bound to or its parents.
Returns the node's own node properties if `parent_node_name` is "default" and the node is a
non-composite.
Returns the node's primary parent's node properties if `parent_node_name` is "default" and the
node is a composite.
Returns an empty vector if the parent does not exist.
Defined at line 177 of file ../../sdk/lib/driver/component/cpp/driver_base.cc
void InitInspectorExactlyOnce (inspect::Inspector inspector)Initialize the driver's Inspector exactly one time.
To avoid data races, subsequent calls are ignored are not an error.
Defined at line 114 of file ../../sdk/lib/driver/component/cpp/driver_base.cc
zx::result<OwnedChildNode> AddOwnedChild (std::string_view node_name)Creates an owned child node on the node that the driver is bound to. The driver framework will
NOT try to match and bind a driver to this child as it is owned by the current driver.
The |node()| must not have been moved out manually by the user. This is a synchronous call
and requires that the dispatcher allow sync calls.
Defined at line 140 of file ../../sdk/lib/driver/component/cpp/driver_base.cc
zx::result<fidl::ClientEnd<fuchsia_driver_framework::NodeController>> AddChild (std::string_view node_name, cpp20::span<const fuchsia_driver_framework::NodeProperty> properties, cpp20::span<const fuchsia_driver_framework::Offer> offers)Creates a child node with the given offers and properties on the node that the driver is
bound to. The driver framework will try to match and bind a driver to this child.
The |node()| must not have been moved out manually by the user. This is a synchronous call
and requires that the dispatcher allow sync calls.
Defined at line 144 of file ../../sdk/lib/driver/component/cpp/driver_base.cc
zx::result<OwnedChildNode> AddOwnedChild (std::string_view node_name, fuchsia_driver_framework::DevfsAddArgs & devfs_args)Creates an owned child node with devfs support on the node that the driver is bound to. The
driver framework will NOT try to match and bind a driver to this child as it is already owned
by the current driver.
The |node()| must not have been moved out manually by the user. This is a synchronous call
and requires that the dispatcher allow sync calls.
Defined at line 151 of file ../../sdk/lib/driver/component/cpp/driver_base.cc
zx::result<fidl::ClientEnd<fuchsia_driver_framework::NodeController>> AddChild (std::string_view node_name, fuchsia_driver_framework::DevfsAddArgs & devfs_args, cpp20::span<const fuchsia_driver_framework::NodeProperty> properties, cpp20::span<const fuchsia_driver_framework::Offer> offers)Creates a child node with devfs support and the given offers and properties on the node that
the driver is bound to. The driver framework will try to match and bind a driver to this child.
The |node()| must not have been moved out manually by the user. This is a synchronous call
and requires that the dispatcher allow sync calls.
Defined at line 156 of file ../../sdk/lib/driver/component/cpp/driver_base.cc
zx::result<fidl::ClientEnd<fuchsia_driver_framework::NodeController>> AddChild (std::string_view node_name, cpp20::span<const fuchsia_driver_framework::NodeProperty2> properties, cpp20::span<const fuchsia_driver_framework::Offer> offers)Defined at line 163 of file ../../sdk/lib/driver/component/cpp/driver_base.cc
zx::result<fidl::ClientEnd<fuchsia_driver_framework::NodeController>> AddChild (std::string_view node_name, fuchsia_driver_framework::DevfsAddArgs & devfs_args, cpp20::span<const fuchsia_driver_framework::NodeProperty2> properties, cpp20::span<const fuchsia_driver_framework::Offer> offers)Defined at line 170 of file ../../sdk/lib/driver/component/cpp/driver_base.cc
fidl::ClientEnd<fuchsia_driver_framework::Node> & node ()Client to the `fuchsia.driver.framework/Node` protocol provided by the driver framework.
This can be used to add children to the node that the driver is bound to.
Defined at line 178 of file ../../sdk/lib/driver/component/cpp/driver_base.h
const fidl::ClientEnd<fuchsia_driver_framework::Node> & node ()Defined at line 184 of file ../../sdk/lib/driver/component/cpp/driver_base.h
const std::vector<fuchsia_driver_framework::Offer> & node_offers ()Defined at line 190 of file ../../sdk/lib/driver/component/cpp/driver_base.h
template <typename StructuredConfig>StructuredConfig take_config ()Defined at line 198 of file ../../sdk/lib/driver/component/cpp/driver_base.h
zx::unowned_vmar vmar ()Defined at line 206 of file ../../sdk/lib/driver/component/cpp/driver_base.h
std::string_view name ()The name of the driver that is given to the DriverBase constructor.
Defined at line 216 of file ../../sdk/lib/driver/component/cpp/driver_base.h
const std::shared_ptr<Namespace> & incoming ()Used to access the incoming namespace of the driver. This allows connecting to both zircon and
driver transport incoming services.
Defined at line 220 of file ../../sdk/lib/driver/component/cpp/driver_base.h
fidl::UnownedClientEnd<fuchsia_io::Directory> svc ()The `/svc` directory in the incoming namespace.
Defined at line 223 of file ../../sdk/lib/driver/component/cpp/driver_base.h
std::shared_ptr<OutgoingDirectory> & outgoing ()Used to access the outgoing directory that the driver is serving. Can be used to add both
zircon and driver transport outgoing services.
Defined at line 227 of file ../../sdk/lib/driver/component/cpp/driver_base.h
const fdf::UnownedSynchronizedDispatcher & driver_dispatcher ()The unowned synchronized driver dispatcher that the driver is started with.
Defined at line 230 of file ../../sdk/lib/driver/component/cpp/driver_base.h
async_dispatcher_t * dispatcher ()The async_dispatcher_t interface of the synchronized driver dispatcher that the driver
is started with.
Defined at line 234 of file ../../sdk/lib/driver/component/cpp/driver_base.h
const std::optional<fuchsia_data::Dictionary> & program ()The program dictionary in the start args.
This is the `program` entry in the cml of the driver.
Defined at line 238 of file ../../sdk/lib/driver/component/cpp/driver_base.h
const std::optional<std::string> & url ()The url field in the start args.
This is the URL of the package containing the driver. This is purely informational,
used only to provide data for inspect.
Defined at line 243 of file ../../sdk/lib/driver/component/cpp/driver_base.h
const std::optional<std::string> & node_name ()The node_name field in the start args.
This is the name of the node that the driver is bound to.
Defined at line 247 of file ../../sdk/lib/driver/component/cpp/driver_base.h
const std::optional<std::vector<fuchsia_driver_framework::NodeSymbol>> & symbols ()The symbols field in the start args.
These come from the driver that added |node|, and are filtered to the symbols requested in the
bind program.
Defined at line 272 of file ../../sdk/lib/driver/component/cpp/driver_base.h
inspect::ComponentInspector & inspector ()A component-wide Inspector for the driver.
Defined at line 277 of file ../../sdk/lib/driver/component/cpp/driver_base.h