Device Instrumentation and Management

The sysctl() facility is used to expose the instrumentation information maintained by the device drivers. This information is retrieved via the Device Driver Manager (DDM).

The Device Driver Manager is a system component that enables a supervisor application to manage devices. Only the devices that export a management DDI interface or that have a parent that exports this DDI can be managed in this way. The DDM is an abstraction of the DKI and the management DDI.

The DDM is implemented as a set of functions that are organized in a library, and can only be used by one client at a time.

The DDM implements a tree of manageable devices with the following properties and features:

• A device can be in one of the following three run states: DDM_RUNSTATE_ONLINE, DDM_RUNSTATE_OFFLINE, and DDM_RUNSTATE_INACTIVE.

• A device can also be in one of the following availability states simultaneously: DDM_AVSTATE_ENABLED and DDM_AVSTATE_DISABLED.

• A device in an online state is able to audit its own health, and export some statistics (in addition to standard operation).

• A device in an offline state can only perform internal diagnostics

• A device in the inactive state does not perform any operations, although it is able to change its state to another value. One of the purposes of the shut-down state is to be able to change a property of the device in the device tree.

• A device in the DDM_AVSTATE_ENABLED state is able to have a driver running to manage it. However, a device in the DDM_AVSTATE_DISABLED state is locked and no drivers can be started to manage it.

Availability and run states are completely independent of each other, despite the fact that a disabled device may eventually be inactive.

The state of a device is changed on request from the DDM client or by external events, such as hardware failure or device hot swap. In both cases the DDM client is notified of the successful state change through a handler (callback) that is defined at the time of opening.

Device Tree

The initial internal device tree is built by taking all devices that satisfy the following criteria:

• All devices that export the mngt DDI.

• All devices that export the diag DDI.

• All devices that have a bus parent that exports the mngt DDI. This means that the child drivers can be shut down or initialized via their bus parent.

The tree of devices exposed by the DDM to its client is only a subset of the internal tree managed by the DDM. This in turn is a subset of the complete device tree for the current board. The way in which it is built is described in the preceding section.

The devices that are exposed via the DDM are:

• All devices that have a parent (so that they can be shut down or reinitialized).

• All diagnostic devices, as they are generally leaf devices, and not bus parent nodes.

The device tree API is summarized in the following table:

Function	Description
svDdmAudit()	Runs non-intrusive tests on an online device
svDdmClose()	Closes a previously made connection to the device driver manager
svDdmDiag()	Runs diagnostics on a node that is currently offline
svDdmDisable()	Locks the specified device node in the disabled state
svDdmEnable()	Enables a client to set the availability state of the specified device node to DDM_AVSTATE_ENABLED
svDdmGetInfo()	Enables the client of the DDM to obtain information on the specified node in the manageable device tree
svDdmGetState()	Enables the client of the DDM to get the state value of the specified node
svDdmGetStats()	Returns raw I/O statistics (counters) for an online device
svDdmOffline()	Enables the DDM client to set the run state of the specified node to DDM_RUNSTATE_OFFLINE
svDdmOnline()	Enables the DDM client to set the run state of the specified node to DDM_RUNSTATE_ONLINE
svDdmOpen()	Opens a connection to the device driver manager and obtains access to the management of the current device driver instances
svDdmShutdown()	Enables the DDM client to request that the driver running on the specified node is shut down

Related sysctl() entries

A number of sysctl() entries are present in the sysctl tree. Each device appears as a sysctl node that holds per-device information, under the top-level dev node. Available information about the device includes:

Name

Per-device information is stored in a sysctl node whose name derives from the canonical physical pathname of the device.

Class

This string holds the device class, if provided by the DDM. If no value is supplied, the content of this entry defaults to '?'.

Status

The integer contains both the availability and run status of the device, as provided by the DDM.

Statistics

This structure holds the device-class-specific statistics. Reading this node returns an error if the device does not export statistics.

Diagnostics

This entry triggers the diagnostic process of a device by writing a magic value to it (1), retrieves the result of the last diagnostic by reading it. An error may be returned if the device does not support diagnostics or if the diagnostics cannot run because the device is not in the appropriate state.

Audit

Similar to device diagnostics, this entry triggers the audit process and retrieves the result of the previous audit.