NAME

Solaris::DeviceTree::Overlay - Unification of multiple devicetrees

SYNOPSIS

use Solaris::DeviceTree::Overlay

Construction and destruction:

$devtree = Solaris::DeviceTree::Overlay->new( sources => { 'src1' => $tree1, ... } )

Tree traversal:

@children = $devtree->child_nodes
@siblings = $devtree->sibling_nodes
$node = $node->parent_node
$root = $node->root_node

Methods concerning tree merging:

@sources = $node->sources

Data access methods:

$path = $node->devfs_path
$instance = $devtree->instance
$id = $node->nodeid
@compat_names = $devtree->compatible_names
...

DESCRIPTION

The Solaris::DeviceTree::Overlay module implements the Solaris::DeviceTree::Node interface to access the Solaris device tree in a unified view from multiple data sources. Each data source must implement the Solaris::DeviceTree::Node interface. As a general goal the unification checks that the values of all data source comply with each other. The method used to unify the information depends on the type of the returned value:

Scalars

A defined scalar precedes an undefined scalar silently. Two defined scalars with the same value are merged together silently. Two defined scalars with different values issue a warning and the value of the first data source is used.

Arrays

Currently only the array from the first defined source is used.

Hashes

Currently only the hash from the first defined source is used.

Properties and PROM Properties

Properties and PROM properties from all source are merged together by name. If two sources define the same property or PROM property and have differing values a warning is issued and the first value is used.

Minor Nodes

Minor nodes from all sources are merged together by name. If two sources define the same minor node and the values for the attributes of the minor nodes differ a warning is issued and the first value is used.

METHODS

The following methods are available:

new

The constructor returns a reference to a Solaris::DeviceTree::Overlay object which itself implements the Solaris::DeviceTree::Node interface. The instance returned represents the root-node of the devicetree.

$devtree = Solaris::DeviceTree::Overlay->new(
  sources => { 'libdevinfo' => $libdevinfotree, 'pti' => $pathtoinsttree } ]
);

DESTROY

This methos removes all internal data structures which are associated with this object.

child_nodes

This method returns a list with the objects of the children for all data sources. The nodes are merged using the nodename and the busaddress as key.

Example:

@children = $devtree->child_nodes

sources

This method returns a list containing the names of all data sources which were used to build this node.

Example:

@sources = $node->sources

parent_node

Returns the parent node for the object. If the object is toplevel, then undef is returned.

Example:

$node = $devtree->parent_node

root_node

Returns the root node of the tree.

Example:

$node = $devtree->root_node

sibling_nodes

Returns the list of siblings for the object. A sibling is a child from our parent, but not ourselves.

Example:

@siblings = $devtree->sibling_nodes

devfs_path

Returns the physical path assocatiated with this node.

Example:

$path = $devtree->devfs_path

nodeid

Returns the type of the node. Three different strings identifying the types can be returned or undef if the type is unknown:

PSEUDO
SID
PROM

Nodes of the type PROM may have additional prom properties that are defined by the PROM. The properties can be accessed with prom_props.

Example:

$id = $node->nodeid

node_name

Returns the name of the node.

Example:

$nodename = $devtree->node_name

binding_name

Returns the binding name for this node. The binding name is the name used by the system to select a driver for the device.

Example:

$bindingname = $devtree->binding_name

bus_addr

Returns the address on the bus for this node. undef is returned if a bus address has not been assigned to the device. A zero-length string may be returned and is considered a valid bus address.

Example:

$busadr = $devtree->bus_addr

instance

Returns the instance number of the driver bound to the node. If no driver is bound to the node undef is returned.

Example:

$instance = $devtree->instance

compatible_names

Returns the list of names from compatible device for the current node. See the discussion of generic names in "Writing Device Drivers" for a description of how compatible names are used by Solaris to achieve driver binding for the node.

Example:

@compat_names = $devtree->compatible_names

driver_name

Returns the name of the driver for the node or undef if the node is not bound to any driver.

Example:

$drivername = $devtree->driver_name

minor_nodes

Returns a reference to a list of all minor nodes which are associated with this node. The minor nodes are of class Solaris::DeviceTree::Overlay::MinorNode.

Example:

@minor = @{$node->minor_nodes}

EXAMPLES

Print the device pathes contained in the /etc/path_to_inst

use Solaris::DeviceTree;

my $t = Solaris::DeviceTree->new( use => [ qw( path_to_inst ) ] );
my @nodes = ( $t );
while( @nodes > 0 ) {
  my $node = shift @nodes;
  print $node->devfs_path, "\n";
  unshift @nodes, $node->child_nodes;
}

AUTHOR

Copyright 1999-2003 Dagobert Michelsen.

SEE ALSO

Solaris::DeviceTree::PathToInst, Solaris::DeviceTree::Filesystem, Solaris::DeviceTree::Libdevinfo.

cpanm Solaris::DeviceTree::Libdevinfo::Impl

perl -MCPAN -e shell
install Solaris::DeviceTree::Libdevinfo::Impl