class DriverBase2
Defined at line 229 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
template <typename DriverBaseImpl>
DriverBaseImpl * GetInstanceFromTokenForTesting (void * token)Gets the DriverBase instance from the given token. This is only intended for testing.
Defined at line 233 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
void DriverBase2 (const DriverBase2 & )Defined at line 241 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
DriverBase2 & operator= (const DriverBase2 & )Defined at line 242 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 251 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 265 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
void DriverBase2 (std::string_view name)Defined at line 266 of file ../../sdk/lib/driver/component/cpp/driver_base2.cc
void Start (DriverContext context, StartCompleter completer)Defined at line 266 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
void DriverBaseInternalInit (DriverContext & context, fdf::UnownedSynchronizedDispatcher driver_dispatcher)Defined at line 269 of file ../../sdk/lib/driver/component/cpp/driver_base2.cc
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 275 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 281 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
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 287 of file ../../sdk/lib/driver/component/cpp/driver_base2.cc
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 287 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
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)
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 291 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 298 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)
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 303 of file ../../sdk/lib/driver/component/cpp/driver_base2.cc
void HealthCheck (fuchsia_driver_framework::HealthCheckRequest request, HealthCheckCompleter completer)Optional active health check hook. By default, replies with an empty HealthCheckResponse (OK)
for HealthCheckRequest::kPing and HealthCheckError::kNotSupported for deeper levels. Drivers
may override this method to inspect hardware state (synchronously or asynchronously) and pass
structured diagnostics to `completer`.
Defined at line 305 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
void ~DriverBase2 ()The destructor is called right after the |Stop| method.
Defined at line 352 of file ../../sdk/lib/driver/component/cpp/driver_base2.cc
zx::result<fidl::ClientEnd<fuchsia_driver_framework::ResourceController>> ProvideResource (std::string_viewnode_name,cpp20::span<const fuchsia_driver_framework::NodeProperty2>properties,cpp20::span<const fuchsia_driver_framework::Offer>offers)
Provides a resource with the given offers and properties on the node that the driver is
bound to. Other nodes can depend on this resource.
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 311 of file ../../sdk/lib/driver/component/cpp/driver_base2.cc
Logger & logger ()This can be used to log in driver factories:
`driver->logger().log(fdf::INFO, "...");`
Defined at line 329 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
void ReportHealthAlert (fuchsia_driver_framework::HealthAlert alert)Proactively emits an asynchronous `OnHealthAlert` FIDL event over the `Driver` channel to the
Driver Framework. If `alert.Which()` is `HealthAlert::Tag::kSelfFault`, the self-fault
`HealthCheckResponse` is also mirrored into the driver's Inspect tree if `CreateInspector()`
was called.
Must be called from the driver dispatcher. It is a no-op once the driver has been asked to
stop (after the `Stop` completer is invoked).
`HealthAlert::Tag::kSelfFault` alerts are edge-triggered: send one when the driver's overall
status worsens and once with an empty `conditions` list (OK) on recovery, never once per
occurrence.
Defined at line 331 of file ../../sdk/lib/driver/component/cpp/driver_base2.cc
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 333 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
const fidl::ClientEnd<fuchsia_driver_framework::Node> & node ()Defined at line 338 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 399 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 403 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 406 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 410 of file ../../sdk/lib/driver/component/cpp/driver_base2.h
Friends
template <typename DriverBaseImpl>class DriverServer2class DriverContext