Device and Driver Registration

The driver and device registry mechanisms, described briefly in Chapter 8, Introduction to the ChorusOS Driver Framework, are explained in more detail below.

Device Tree

The device tree is a data structure providing a description of the hardware topology and device properties of a given device. The hardware topology is specified in terms of parent/child relationships. Device properties associated with each device node in the tree are device specific.

A device property is a name/value pair. The property name is a null terminated ASCII string. The property value is a stream of bytes specified by the length/address pair. Note that the property value format is property-specific and has to be standardized between the property producer and its consumers.

For instance, among all device node properties, there are some related to the bus resources allocated to the device (for example, interrupt lines, I/O registers, DMA channels). These properties must be standardized to be understood by the bus driver, as well as any device drivers connected to the given bus.

The device tree data structure may be built either statically or dynamically.

• In the static case, the device tree is populated by the system boot.

  For instance, the system boot may include a predefined sequence of device tree function calls. Another possibility for the system boot is to build the device tree from a hardware description provided by firmware.

• In the dynamic case, the device tree is populated at system initialization time using an enumeration/probing mechanism. The device tree is populated by propagating from parent to children.

Note that it is possible to combine both methods. In other words, an initial (incomplete) device tree may be provided by the ChorusOS operating system boot, which will later be completed dynamically using an enumeration/probing mechanism. In any case, the device tree structure can be modified (extended/truncated) dynamically at run time using hot-plug insertion/removal service (for example, when using PCMCIA cards).

Device tree related services are described below. See the man pages for complete descriptions of the calls listed:

Device Tree Browsing

dtreeNodeRoot()

returns the root device node

dtreeNodeChild()

returns the first child node

dtreeNodePeer()

returns the next "sibling" device node

dtreeNodeParent()

returns the parent device node

dtreePathLeng()

returns the pathname length of the given device node

dtreePathGet()

returns, in buf, the absolute pathname of the given device node. The trailing part of the pathname is the name of the node and is read in a node property. If this property does not exist, the trailing part of the returned pathname is set to '???'.

Device Tree Modification

dtreeNodeAlloc()

allocates a new device node object

dtreeNodeFree()

releases all memory and properties attached to the node

dtreeNodeAttach()

adds a child node to the specified parent

dtreeNodeDetach()

detaches a node from its parent

Device Node Properties

dtreePropFind()

returns the first property of a node

dtreePropFindNext()

returns the next property of a node

dtreePropLength()

returns the property value length (in bytes)

dtreePropValue()

returns a pointer to the first byte of the property value

dtreePropName()

returns a pointer to the property name

dtreePropAlloc()

allocates a new device property object

dtreePropFree()

releases the memory allocated by the property object

dtreePropAttach()

attaches a property object to a device node

dtreePropDetach()

detaches a property object from a device node

Device tree high-level services

dtreeNodeAdd()

adds a named device node to the tree

dtreeNodeFind()

looks for a named node in the list of children of a given device node

dtreePropAdd()

allocates a new property, sets its value and attaches it to a given device node

Driver Registry

The driver registry module implements a database of drivers registered in the ChorusOS operating system. The driver registry database is populated by drivers that perform self-registration (using svDriverRegister()) at driver initialization time.

The bus/nexus drivers perform a search in the driver registry database to find a driver they are interested in. Typically, there are two kinds of searches used by the bus/nexus drivers. The first one is done at device enumeration/probing time when the bus/nexus driver is interested in all drivers matching the bus/nexus class (specified as the parent device class). The second is at device instance creation time, when the bus/nexus driver looks for a driver which must be started for a particular device node.

Driver Registry related services are described below. See the man pages for complete descriptions of the calls listed:

svDriverRegister()

adds a driver entry to the driver registry

svDriverLookupFirst()

returns the id of the first driver entity

svDriverLookupNext()

returns the id of the next driver entity

svDriverRelease()

releases the lock of a driver

svDriverEntry()

returns a pointer to the driver entry structure (using an id)

svDriverCap()

returns a pointer to the driver actor capability (using an id)

svDriverUnregister()

removes a driver entry from the registry

Device Registry

The device registry microkernel module implements a database of driver instances servicing devices currently supported by the system. The device registry database is populated by drivers that perform self-registration (using svDeviceRegister()) at device initialization time.

The device registry database is accessed by driver clients in order to obtain a pointer to the driver instance servicing a given (logical) device.

The device registry API is described in detail in the man pages. Note that only the svDeviceLookup(), svDeviceRelease() and svDeviceEntry() microkernel calls should be used by driver clients. The rest of API is dedicated to device drivers.

Device Registry related services are described below. See the man pages for complete descriptions of listed calls:

svDeviceAlloc()

allocates a device registry entry for a given device driver instance

svDeviceRegister()

adds a given entry to the device registry

svDeviceUnregister()

removes an entry from the device registry

svDeviceEvent()

notifies the device registry module that a given event has occurred

svDeviceFree()

releases a previously allocated device registry entry

svDeviceLookup()

searches a device entry in the registry, matching given device class and logical unit.

svDeviceEntry()

returns the device entry associated to a client identifier returned by svDeviceLookup

svDeviceRelease()

releases the lock on a looked-up device entry