The system associates a driver with its configuration file by name. For
example, a driver in /usr/kernel/drv called wombat has the driver configuration file
wombat.conf, also stored in /usr/kernel/drv, associated with it. On systems capable of support
64-bit drivers, the driver configuration file should be placed in the directory
in which the 32-bit driver is (or would be) located, even if
only a 64-bit version is provided. For example, a 64–bit driver stored
in /usr/kernel/drv/sparcv9 stores its driver configuration file in /usr/kernel/drv.

The value of the name property is the node name. In a
driver.conf file, where the generic node name and compatible property associated with
a self-identifying devices are typically not used, the node name must be
a binding name. The binding name is the name chosen by the system
to bind a driver to the device. The binding name is either
an alias associated with the driver established by add_drv(1M) or the driver
name itself.

The syntax of a single entry in a driver configuration file takes
one of three forms:

name="node name" parent="parent name" [property-name=value ...];

In this form, the parent name can be either the binding name
of the parent nexus driver or a specific full pathname, beginning with
a slash (/) character, identifying a specific instance of a parent bus.
If a binding name is used then all parent nodes bound to
that driver match. A generic name (for example, pci) is not a valid
binding name even though it can appear in the full pathname of
all intended parents.

Alternatively, the parent can be specified by the type of interface it
presents to its children.

name="node name" class="class name" [property-name=value ...];

For example, the driver for the SCSI host adapter can have different
names on different platforms, but the target drivers can use class scsi
to insulate themselves from these differences.

Entries of either form above correspond to a device information (devinfo) node
in the kernel device tree. Each node has a name which is
usually the name of the driver, and a parent name which is
the name of the parent devinfo node to which it will be
connected. Any number of name-value pairs can be specified to create properties
on the prototype devinfo node. These properties can be retrieved using the
DDI property interfaces (for example, ddi_prop_get_int(9F) and ddi_prop_lookup(9F)). The prototype devinfo node
specification must be terminated with a semicolon (;).

The third form of an entry is simply a list of properties.

[property-name=value ...];

A property created in this way is treated as global to the
driver. It can be overridden by a property with the same name
on a particular devinfo node, either by creating one explicitly on the
prototype node in the driver.conf file or by the driver.

Items are separated by any number of newlines, SPACE or TAB characters.

The configuration file can contain several entries to specify different device configurations
and parent nodes. The system can call the driver for each possible
prototype devinfo node, and it is generally the responsibility of the drivers
probe(9E) routine to determine if the hardware described by the prototype devinfo
node is really present.

Property names must not violate the naming conventions for Open Boot PROM
properties or for IEEE 1275 names. In particular, property names should contain
only printable characters, and should not contain at-sign (@), slash (/), backslash
(\), colon (:), or square brackets ([]). Property values can be decimal integers
or strings delimited by double quotes ("). Hexadecimal integers can be constructed
by prefixing the digits with 0x.

A comma separated list of integers can be used to construct properties
whose value is an integer array. The value of such properties can
be retrieved inside the driver using ddi_prop_lookup_int_array(9F).

Comments are specified by placing a # character at the beginning of
the comment string, the comment string extends for the rest of the
line.

In addition to the vendor driver.conf files provided by the system and
driver providers in /kernel and /platform, user-administered driver.conf files may be added
in /etc/driver/drv. Files in /etc/driver/drv are available for local customizations to supplement the
vendor driver configuration.

The format of an /etc/driver/drvdriver.conf file is identical to that of
a vendor driver.conf file.

For each driver, the vendor and admin driver.conf files are merged together
and made available to the driver and system, as a merged set
of device specifications with per-device properties and a global set of properties
visible to every device instance bound to this driver.

These merged per-device and global properties are visible to an instance of
the driver via the ddi_prop_lookup(9F) and related interfaces automatically, with no intervention
by the driver required.

A driver that does provide configurable options by way of driver.conf should
keep this property merge behavior in mind. Inverting the meaning of
an option from one release to the next could cause problems for
users that may have configured a system with the previous interpretation of that
option.

A driver which has converted its configurable options from one revision to
another may find it useful to convert older option configurations to the
new supported set. The system maintains two separate property lists providing
the default vendor properties and the admin customizations.

Each property originally derived from the vendor driver.conf file and then merged
with an updated value will be entered both the vendor and admin
property lists. Each list may be searched via ddi_prop_lookup(9F) as either
the DDI_PROP_VENDOR or DDI_PROP_ADMIN, respectively. The property on the vendor list
records the property's original value, while the property on the admin list
provides the customization.

There is no property entry on the vendor list for a property
derived solely from the admin driver.conf. Such properties have entries on
the admin list only, providing the admin-specified value.

Supplementing the Vendor Driver Configuration

First, it is important to understand the format of a driver.conf entry.
Each entry can be one of two types, specifying either a
device information (devinfo) node as a parent specification or a set of
properties globally available to all device instances bound to this driver.

An entry defining a device info node must specify the node's parent
as either the binding name of the parent nexus driver, a pathname
or by the class of interface presented to its children. Other
properties on the parent specification define qualifiers required to correctly identify the specific
device, and depend upon the parent driver or class of interface.
An example of such a device qualifier property is 'target', used by
SCSI hba adapters to identifier a specific device on its bus.
Such qualifiers must be retained unchanged so that the system will continue
to properly enumerate that device instance.

To modify one or more property values on such a parent specification,
the targeted parent specification in the vendor driver.conf must be duplicated in
the admin driver.conf, preserving each device qualifying property. Then the admin
entry can be customized, supplementing it with additional or modified configurable options.

Parent specifications in the admin driver.conf that do not correspond to a
match in the vendor driver.conf file are added to the list of
device information nodes available to be potentially enumerated by the system for
that driver.

The second type of driver.conf entry defines global properties for that driver.
The admin driver.conf file can both update existing properties in the
vendor driver.conf file with new values, and provide new global property name-value pairs
available to all device instances bound to that driver.

Considerations for Driver Writers

The process of upgrading a Solaris system from one release to another
involving delivering new versions of drivers including that driver's vendor driver.conf.
It is desired that a system's earlier configuration should continue to work
as before, with the new drivers and vendor driver.conf files together with the
admin customized driver.conf files.

For a driver to work well under this model, each driver needs
to be properly designed to present a disciplined set of configurable options.
It would be best to carefully define a driver's options with
this in mind and to fully describe the model presented in the
driver's documentation or man page.

If a driver makes a change in its configuration options that would
invalidate or supersede the admin settings, the driver should make the effort
to discover the admin settings via the prior options and honor them.

For example, let's say a driver supports a timeout configuration in units
of seconds. A new version of the driver now supports a
finer timeout granularity in units of milliseconds. The new property should
be named so it can be distinguished from the first. The
driver can then look up the earlier property on the admin list and
if found, continue to honor it.

This example creates a prototype devinfo node called ACME,simple under all parent
nodes of class pci. The node has device and function numbers of
3 and 1, respectively; the property debug-mode is provided for all instances of
the driver.

Example 2 Using a Configuration File for a Pseudo Device Driver

The following is an example of a configuration file called ACME,example.conf for
a pseudo device driver called ACME,example.

This creates two devinfo nodes called ACME,example which attaches below the pseudo
node in the kernel device tree. The instance property is only interpreted
by the pseudo node, see pseudo(4) for further details. A property called
debug-level is created on the first devinfo node which has the value
1. The example driver is able to fetch the value of this
property using ddi_prop_get_int(9F).

Two global driver properties are created, whizzy-mode (which has the string value
"on") and debug-level (which has the value 3). If the driver looks
up the property whizzy-mode on either node, it retrieves the value of the
global whizzy-mode property ("on"). If the driver looks up the debug-level property
on the first node, it retrieves the value of the debug-level property
on that node (1). Looking up the same property on the second node
retrieves the value of the global debug-level property (3).

Example 3 Modifying a Driver Global Property

The bge.conf provides default values for the receive and xmit rings.

#
# The properties below represents the number of receive and send ring used.
# For BCM5705, BCM5782, etc, there are only 1 receive ring and 1 send ring.
# Otherwise, there can be up to 16 receive rings and 4 send rings.
#
bge-rx-rings = 16;
bge-tx-rings = 1;

To customize the bge-tx-rings value, place a bge.conf file in /etc/driver/drv with
the following line:

bge-tx-rings = 2;

When the bge driver is next loaded, the updated value can be
observed with prtconf:

For purposes of illustration, suppose that the vendor sd.conf contains only the
following parent specification:

name="sd" class="scsi" target=0 lun=0 max-retries=4;

and that it is desired to also support a target=1 device instance.
Further suppose that target=0 should be configured with the max-retries parameter
set to 10 and queueing set to 32, and that target=1 with
max-retries to 10 and queueing to 64. Place the following lines
in the sd.conf file in /etc/driver/drv:

These changes can be observed with prtconf. For target 0, the
vendor list contains the vendor setting for the number of retries and
the updated value in the admin list. There was no specification
for this target as delivered, so the vendor list for target 1 is
empty and all specified parameters from the admin list are displayed.

Warnings

To avoid namespace collisions between multiple driver vendors, it is strongly recommended
that the name property of the driver should begin with a vendor-unique
string. A reasonably compact and unique choice is the vendor over-the-counter stock
symbol.

Notes

The update_drv(1M) command should be used to prompt the kernel to reread
driver.conf files. Using modunload(1M) to update driver.conf continues to work in release
9 of the Solaris operating environment, but the behavior will change in
a future release.

It is not currently possible to either remove or undefine a property,
or to remove a parent specification, defined in a vendor driver.conf file
with an addition to an /etc/driver/drv driver.conf file.