blob: 09be39d3dc370f9b84e8e6dfc23f976c65145f01 [file] [view]
# Using Inspect in drivers
This guide explains how to instrument Fuchsia Driver Framework (DFv2) drivers
with [Inspect][inspect_overview] and how to query Inspect data from driver
components.
## Overview
In Fuchsia's Driver Framework (DFv2), **drivers are components**. Drivers participate
directly in Fuchsia's component diagnostics architecture and publish Inspect data
using the standard `fuchsia.inspect.InspectSink` capability, just like any other
Fuchsia component.
```mermaid
graph LR
subgraph Driver Component ["Driver Component (e.g. bootstrap/boot-drivers:...)"]
DriverCode["Driver Implementation (C++ DriverBase2 / Rust Driver)"]
Inspector["Inspector"]
DriverCode --> Inspector
end
Archivist["Archivist (Diagnostics Subsystem)"]
Tooling["Host (ffx inspect) / Target (iquery)"]
Inspector -- "fuchsia.inspect.InspectSink" --> Archivist
Tooling -- "Query Inspect Selectors" --> Archivist
```
Key characteristics of Inspect in DFv2:
- **Standard capability routing**: The driver component manifest requests
`fuchsia.inspect.InspectSink` using the standard `inspect/client.shard.cml` shard.
- **Component-attributed Inspect**: Inspect hierarchies are attributed to each
individual driver component under its component moniker (e.g. under
`bootstrap/boot-drivers` or `bootstrap/base-drivers`).
- **Standard tooling**: Driver Inspect data is inspected using `ffx inspect` or
`iquery` with standard component selectors or component URL matching.
## Prerequisites
If you are unfamiliar with Inspect basics, review the following guides:
- [Inspect overview][inspect_overview]
- [Inspect codelab][inspect_codelab]
- [Inspect selectors][selectors]
## Include Inspect in a driver
### 1. Update the component manifest (`.cml`)
Include the Inspect client shard in your driver's `.cml` file:
```json5
{
include: [
"inspect/client.shard.cml",
"syslog/client.shard.cml",
],
program: {
runner: "driver",
binary: "driver/my_driver.so",
bind: "meta/bind/my_driver.bindbc",
},
}
```
The `inspect/client.shard.cml` shard routes the `fuchsia.inspect.InspectSink` protocol
from the parent diagnostics directory into the driver's incoming namespace.
### 2. Add build dependencies
* {C++}
Add `//sdk/lib/inspect/component/cpp` to your driver's `BUILD.gn`:
```gn
fuchsia_cc_driver("my_driver") {
deps = [
"//sdk/lib/driver/component/cpp",
"//sdk/lib/inspect/component/cpp",
]
}
```
If building with Bazel, add `@fuchsia_sdk//pkg/inspect_component_cpp` in `BUILD.bazel`:
```bazel
fuchsia_cc_driver(
name = "my_driver",
deps = [
"@fuchsia_sdk//pkg/driver_component_cpp",
"@fuchsia_sdk//pkg/inspect_component_cpp",
],
)
```
* {Rust}
In your driver's `BUILD.gn`, depend on `//sdk/lib/driver/component/rust`, `//src/lib/diagnostics/inspect/rust`, and `//src/lib/fuchsia-async`:
```gn
fuchsia_rust_driver("my_driver") {
deps = [
"//sdk/lib/driver/component/rust",
"//src/lib/diagnostics/inspect/rust",
"//src/lib/fuchsia-async",
]
}
```
### 3. Initialize and publish Inspect
* {C++}
In C++, drivers inheriting from [`fdf::DriverBase2`][write-a-minimal-dfv2-driver]
can publish an Inspect tree using `context.CreateInspector(this)`:
```cpp
#include <lib/driver/component/cpp/driver_base2.h>
#include <lib/driver/component/cpp/driver_export2.h>
#include <lib/inspect/component/cpp/component.h>
class MyDriver : public fdf::DriverBase2 {
public:
MyDriver() : fdf::DriverBase2("my_driver") {}
zx::result<> Start(fdf::DriverContext context) override {
// 1. Create and publish the ComponentInspector.
// Must be called before context.take_incoming() if transferring ownership.
component_inspector_ = context.CreateInspector(this);
// 2. Build the Inspect hierarchy from the root node.
hardware_node_ = component_inspector_->root().CreateChild("hardware_status");
revision_prop_ = hardware_node_.CreateUint("revision_id", 0x10);
requests_count_ = hardware_node_.CreateUint("requests_count", 0);
// 3. For values that do not change, use Record* helpers to avoid storing handles:
hardware_node_.RecordString("serial_number", "ABC-1234");
// 4. (Optional) Report component health:
component_inspector_->Health().Ok();
return zx::ok();
}
void HandleDeviceRequest() {
requests_count_.Add(1);
}
// Accessor for unit tests:
const inspect::Inspector& inspector() const {
return component_inspector_->inspector();
}
private:
std::optional<inspect::ComponentInspector> component_inspector_;
inspect::Node hardware_node_;
inspect::UintProperty revision_prop_;
inspect::UintProperty requests_count_;
};
FUCHSIA_DRIVER_EXPORT2(MyDriver);
```
**Key points:**
- **`context.CreateInspector(this)`**: Automatically connects to `fuchsia.inspect.InspectSink`
in the incoming namespace and publishes the Inspect tree with the tree name set to the driver's
`name()`. Invoke `context.CreateInspector(this)` *before* taking the namespace via
`context.take_incoming()`.
- **Node & Property Lifetimes (RAII)**: Inspect properties are RAII objects. If a property
will change over time (such as `requests_count_`), store the property object as a class
member or store it in an `inspect::ValueList`. If you do not keep the property alive, it is
removed from the Inspect VMO. For immutable values, use `Record*` helper methods
(e.g., `RecordString`, `RecordUint`), which commit the value directly into the VMO without
requiring an object handle.
- **Component Health**: Use `component_inspector_->Health().Ok()`, `.Starting()`, or
`.Unhealthy(reason)` to report standard [component health][health-metrics].
* {Rust}
In Rust drivers implementing `fdf_component::Driver`:
```rust
use fdf_component::{Driver, DriverContext, DriverError};
use fuchsia_async::Scope;
use fuchsia_inspect::{Inspector, NumericProperty, UintProperty};
pub struct MyDriver {
// Keep the scope alive for the lifetime of the driver so that
// the Inspect publishing task continues running.
_inspect_scope: Scope,
inspector: Inspector,
requests_count: UintProperty,
}
impl Driver for MyDriver {
const NAME: &str = "my_driver";
async fn start(mut context: DriverContext) -> Result<Self, DriverError> {
let inspector = Inspector::default();
// Build hierarchy
let hardware = inspector.root().create_child("hardware_status");
hardware.record_string("serial_number", "ABC-1234");
let requests_count = hardware.create_uint("requests_count", 0);
inspector.root().record(hardware);
// Publish Inspect via InspectSink.
let inspect_scope = Scope::new_with_name("my_driver_inspect");
context.publish_inspect(&inspector, inspect_scope.to_handle())?;
Ok(Self {
_inspect_scope: inspect_scope,
inspector,
requests_count,
})
}
}
impl MyDriver {
pub fn handle_device_request(&self) {
self.requests_count.add(1);
}
}
```
**Key points:**
- **Retain the `Scope`**: `context.publish_inspect` spawns a background task on
the provided `ScopeHandle`. Keep the `Scope` stored in your driver struct so the
task is not cancelled when `start()` completes.
- **Tree Name**: Rust's `context.publish_inspect` publishes using the default
tree name (`None`). Unlike C++ drivers published via `CreateInspector`, do not
pass a `--name` tree filter when querying unless using custom publish options.
## Query driver Inspect data
Because drivers are components, you query their Inspect data using standard Fuchsia
diagnostics commands.
### Driver monikers
Driver component monikers reflect the device topology and the collection where the driver runs:
- **Boot drivers**: `bootstrap/boot-drivers:<device_node_path>` (e.g., `bootstrap/boot-drivers:dev.sys.platform.00_00_2d`)
- **Packaged drivers (base)**: `bootstrap/base-drivers:<device_node_path>`
- **Packaged drivers (full/universe)**: `bootstrap/full-drivers:<device_node_path>`
### Using `ffx inspect`
From the host development workstation:
- **Query by driver component URL / component name**:
```sh
ffx inspect show my_driver.cm
```
- **Query all driver components**:
```sh
ffx inspect show "bootstrap/*-drivers*:root"
```
- **Filter by C++ driver tree name**:
```sh
ffx inspect show --name my_driver "bootstrap/*-drivers*:root"
```
- **Query a specific driver by moniker**:
Because collection child names are separated by a colon, the colon in the component moniker
must be escaped in selectors:
```sh
ffx inspect show "bootstrap/boot-drivers\:suspend"
```
### Using `iquery` on target
Important: if you are working in a product other than `bringup` please
read [this section](#include-iquery-bootfs) to learn how to include
`iquery` in bootfs. If you are working on a product in which networking and
`ffx` are available, you can use `ffx inspect` instead of `iquery` without
the need of including `iquery` in `bootfs`.
When connected to a target device via serial or `ffx target ssh`:
```sh
iquery show my_driver.cm
iquery show "bootstrap/*-drivers*:root"
```
## Testing driver Inspect
### Unit tests
In C++ driver unit tests using the [driver unit testing library][driver-unit-testing], validate
Inspect trees directly from the driver's inspector:
```cpp
#include <lib/driver/testing/cpp/driver_test.h>
#include <lib/fpromise/single_threaded_executor.h>
#include <lib/inspect/cpp/reader.h>
#include <lib/inspect/testing/cpp/inspect.h>
#include <gtest/gtest.h>
TEST_F(MyDriverTestFixture, InspectMetrics) {
// Run driver methods that modify inspect state...
dut_.RunInDriverContext([&](MyDriver& driver) {
auto hierarchy = fpromise::run_single_threaded(
inspect::ReadFromInspector(driver.inspector()))
.take_value();
const auto* hw_node = hierarchy.GetByPath({"hardware_status"});
ASSERT_NE(hw_node, nullptr);
const auto* prop = hw_node->node().get_property<inspect::UintPropertyValue>("requests_count");
ASSERT_NE(prop, nullptr);
EXPECT_EQ(prop->value(), 1u);
});
}
```
### Integration tests with `DriverTestRealm`
In integration tests running inside [`DriverTestRealm`][driver-test-realm], query
Inspect using `diagnostics_reader::ArchiveReader`. Note that the colon separating the collection
and child moniker must be escaped (`\\:`) in the selector string:
```rust
use diagnostics_assertions::assert_data_tree;
use diagnostics_reader::ArchiveReader;
let moniker = format!("realm_builder\\:{}/driver_test_realm/boot-drivers\\:dev.sys.my_node", instance.root.child_name());
let hierarchy = ArchiveReader::inspect()
.add_selector(format!("{}:[name=my_driver]root", moniker))
.snapshot()
.await?
.into_iter()
.next()
.and_then(|result| result.payload)
.expect("driver inspect hierarchy not found");
assert_data_tree!(hierarchy, root: contains {
hardware_status: contains {
requests_count: 0u64,
}
});
```
[inspect_overview]: /docs/development/diagnostics/inspect/README.md
[inspect_codelab]: /docs/development/diagnostics/inspect/codelab.md
[selectors]: /docs/reference/diagnostics/selectors.md
[health-metrics]: /docs/development/diagnostics/inspect/health.md
[write-a-minimal-dfv2-driver]: /docs/development/drivers/developer_guide/write-a-minimal-dfv2-driver.md
[driver-unit-testing]: /docs/development/sdk/driver-testing/driver-unit-testing-quick-start.md
[driver-test-realm]: /docs/development/drivers/testing/driver_test_realm.md