Devicetree visitors are responsible for converting devicetree data into
driver-specific metadata and bind rules. They parse the relevant devicetree
nodes with respect to a particular devicetree binding
and produce driver metadata and driver framework node properties. Devicetree
visitor objects implement the interfaces in the
driver-visitor.h
header file and all Visitor::Visit
calls are invoked during the devicetree manager's Walk
call.
Visitor types
There are two types of devicetree visitors: default visitors and driver visitors.
Default visitors
Default visitors are for the properties or bind rules
mentioned as standard properties in the devicetree specification. Additionally,
a number of visitors are for the properties that are generic in the Fuchsia
platform (that is, the properties explicitly mentioned in the
fuchsia_hardware_platform_bus::Node
protocol). These visitors are considered
default for Fuchsia and are also added to the default visitor set.
Driver visitors
Driver visitors correspond to driver-specific metadata or
dependencies. These visitors are built as shared libraries using the
devicetree_visitor
GN target. Creating a shared library of the visitor helps
Fuchsia keep the list of visitors dynamic, that is, visitors can be added and
removed from the board driver without having to recompile it.
This also helps Fuchsia update and contribute visitors independent of the board
driver.
Writing a new visitor
A new visitor will be needed when a new devicetree binding is created. Typically, a new devicetree binding is created because either a new metadata is introduced or a composite node needs to be created from the board driver.
You can use the following fx
command as a starting point for writing a new
visitor:
fx create devicetree visitor --lang cpp --path <VISITOR_PATH>
All visitors must include a devicetree schema file (for example, see
smc.yaml
) representing the bindings that it is parsing.
For a complete devicetree visitor example, see the
example-visitor
directory.
Helper libraries
The following helper libraries are available for writing a new visitor:
- Driver visitors: This library provides a constructor that takes in a list of compatible strings and only calls the visitor when the node with the matching compatible string is found.
- Property parser: This library provides a parser object which can be configured to parse all relevant properties for a node. It also reduces some of the complexity involved around parsing phandle (pointer handle) references.
- Multi-visitor: Used for combining multiple visitors into a single object
that can be passed to the devicetree manager's
Walk
call. - Load visitors: This can be used by the board driver to load shared library
visitors packaged with the driver in its
/lib/visitors
folder.
Testing a visitor
A visitor integration test can be created using the visitor-test-helper
library to test the parsing and creation of metadata and bind rules by the
visitor. The helper library creates an instance of the devicetree manager along
with fakes for platform-bus protocols. The DTB containing the test nodes for the
visitor is passed during the initialization of the test helper. All of the
properties set by the visitor (that is, metadata and properties or bind rules)
are recorded by the test helper and can be used to verify the visitor's
behavior.