class DriverBase2
Defined at line 223 of file ../../sdk/lib/driver/component/cpp/driver_base2.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.
|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(DriverContext
&
context, fdf::UnownedSynchronizedDispatcher driver_dispatcher);
The following illustrates an example:
```
class MyDriver : public fdf::DriverBase2 {
public:
MyDriver(fdf::DriverContext
&
context, fdf::UnownedSynchronizedDispatcher driver_dispatcher)
: fdf::DriverBase("my_driver", context, std::move(driver_dispatcher)) {}
zx::result
<
> Start(DriverContext context) override {
context.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 = 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::Client
<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 DriverBase2 (std::string_view name)Defined at line 101 of file ../../sdk/lib/driver/component/cpp/driver_base2.cc
void DriverBaseInternalInit (DriverContext & context, fdf::UnownedSynchronizedDispatcher driver_dispatcher)Defined at line 104 of file ../../sdk/lib/driver/component/cpp/driver_base2.cc
void ~DriverBase2 ()The destructor is called right after the |Stop| method.
Defined at line 159 of file ../../sdk/lib/driver/component/cpp/driver_base2.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 122 of file ../../sdk/lib/driver/component/cpp/driver_base2.cc
zx::result<fidl::ClientEnd<fuchsia_driver_framework::NodeController>> AddChild (std::string_viewnode_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 126 of file ../../sdk/lib/driver/component/cpp/driver_base2.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 133 of file ../../sdk/lib/driver/component/cpp/driver_base2.cc
zx::result<fidl::ClientEnd<fuchsia_driver_framework::NodeController>> AddChild (std::string_viewnode_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 138 of file ../../sdk/lib/driver/component/cpp/driver_base2.cc
zx::result<fidl::ClientEnd<fuchsia_driver_framework::NodeController>> AddChild (std::string_viewnode_name,cpp20::span<const fuchsia_driver_framework::NodeProperty2>properties,cpp20::span<const fuchsia_driver_framework::Offer>offers)
Defined at line 145 of file ../../sdk/lib/driver/component/cpp/driver_base2.cc
zx::result<fidl::ClientEnd<fuchsia_driver_framework::NodeController>> AddChild (std::string_viewnode_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 152 of file ../../sdk/lib/driver/component/cpp/driver_base2.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 227 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
void DriverBase2 (const DriverBase2 & )Defined at line 235 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
DriverBase2 & operator= (const DriverBase2 & )Defined at line 236 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
void RegisterInitMethods (InitMethodCallback cb)Callbacks that are invoked prior to the start hook.
Defined at line 245 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
zx::result<> Start (DriverContext context)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 |DriverBase2| 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 259 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
void Start (DriverContext context, StartCompleter completer)Defined at line 260 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
void Stop (StopCompleter 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 269 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
void SystemSuspend (SuspendCompleter completer)Optional suspend hook. Called when power_managed_dispatchers_enabled is set in the manifest's
program section. This hook is executed when the power element transitions to a suspended state,
after all pending tasks have run.
Defined at line 275 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
void SystemResume (std::optional<fuchsia_power_broker::LeaseToken> pe_lease, ResumeCompleter completer)Optional resume hook. Called when power_managed_dispatchers_enabled is set in the manifest's
program section. This hook is executed when the power element transitions to a running state or
a wake vector triggers, before any other tasks are executed. |pe_lease| contains the lease
associated with the wake if triggered by a wake vector.
Defined at line 281 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
Logger & logger ()This can be used to log in driver factories:
`driver->logger().log(fdf::INFO, "...");`
Defined at line 289 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
fidl::ClientEnd<fuchsia_driver_framework::Node> take_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 293 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
const fidl::ClientEnd<fuchsia_driver_framework::Node> & node ()Defined at line 298 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
Protected Methods
std::string_view name ()The name of the driver that is given to the DriverBase2 constructor.
Defined at line 357 of file ../../sdk/lib/driver/component/cpp/driver_base2.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 361 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
const fdf::UnownedSynchronizedDispatcher & driver_dispatcher ()The unowned synchronized driver dispatcher that the driver is started with.
Defined at line 364 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
async_dispatcher_t * dispatcher ()The async_dispatcher_t interface of the synchronized driver dispatcher that the driver
is started with.
Defined at line 368 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
Friends
class DriverContext