svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
driver.conf(5)
driver.conf(5) File Formats driver.conf(5)
NAME
driver.conf - driver configuration files
SYNOPSIS
driver.conf
DESCRIPTION
Driver configuration files provide values for device properties. The
values override values provided by the devices themselves. Most modern
devices provide enough property values to make a driver configuration
file unnecessary.
The system associates a driver with its configuration file by name. For
example, a driver in /usr/kernel/drv called wombat has the driver con‐
figuration file wombat.conf, also stored in /usr/kernel/drv, associated
with it. The driver configuration file should be placed in the direc‐
tory in which the 32-bit driver would be located, even though only a
64-bit driver can be used on Oracle Solaris 11. For example, a 64-bit
driver stored in /usr/kernel/drv/sparcv9 stores its driver configura‐
tion 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 asso‐
ciated with the driver established by add_drv(8) 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 (dev‐
info) 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 dev‐
info 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/drv driver.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 inter‐
faces 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 interpreta‐
tion 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 informa‐
tion (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 iden‐
tify 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 con‐
tinue 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 documen‐
tation 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.
/*
* Has the timeout been locally configured using the
* prior option of timeout in units of seconds?
*/
if (ddi_prop_lookup_int(DDI_DEV_T_ANY, dip,
DDI_PROP_ADMIN, "timeout",) ==
DDI_PROP_SUCCESS) {
if (n != 1) {
ddi_prop_free(ivalues);
return (EINVAL);
}
/* yes - convert our working timeout accordingly */
dip->ms_timeout = 1000 * ivalues[0];
/* record the new parameter setting for confirmation */
(void) ddi_prop_update_int(DDI_DEV_T_NONE,
dip, "ms-timeout", dip->ms_timeout);
ddi_prop_free(ivalues);
}
EXAMPLES
Example 1 Using a Configuration File for a PCI Bus Frame Buffer
The following is an example of a configuration file called ACME,sim‐
ple.conf for a PCI bus frame buffer called ACME,simple.
#
# Copyright (c) 1993, by ACME Fictitious Devices, Inc.
#
#ident "@(#)ACME,simple.conf 1.3 1999/09/09"
name="ACME,simple" class="pci" unit-address="3,1"
debug-mode=12;
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,exam‐
ple.conf for a pseudo device driver called ACME,example.
#
# Copyright (c) 1993, ACME Fictitious Devices, Inc.
#
#ident "@(#)ACME,example.conf 1.2 93/09/09"
name="ACME,example" parent="pseudo" instance=0
debug-level=1;
name="ACME,example" parent="pseudo" instance=1;
whizzy-mode="on";
debug-level=3;
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(5) 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. Looking up the same
property on the second node retrieves the value of the global debug-
level property.
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:
pci108e,534d (pci14e4,16a7), instance #0
System software properties:
name='bge-known-subsystems' type=int items=16
name='bge-rx-rings' type=int items=1
value=00000010
name='bge-tx-rings' type=int items=1
value=00000002
Additionally, prtconf -u can be used to display both the original
default and the updated bge-tx-rings property values:
Admin global properties:
name='bge-tx-rings' type=int items=1
value=00000002
Vendor global properties:
name='bge-tx-rings' type=int items=1
value=00000001
Example 4 Modifying configurable values on a specific device
To modify the configurable parameter 'retries' on an sd device at tar‐
get 0, lun 0 and 'queue-max' on the device target 1, lun 0, place an
sd.conf file in /etc/driver/drv with the following lines:
name="sd" class="scsi" target=0 lun=0 retries=4;
name="sd" class="scsi" target=1 lun=0 queue-max=16;
The updated values can be observed with prtconf:
sd, instance #1
System properties:
name='lun' type=int items=1
value=00000000
name='target' type=int items=1
value=00000000
name='class' type=string items=1
value='scsi'
name='retries' type=int items=1
value=00000004
name='ddi-devid-registrant' type=int items=1
value=00000001
sd, instance #2
System properties:
name='lun' type=int items=1
value=00000000
name='target' type=int items=1
value=00000001
name='class' type=string items=1
value='scsi'
name='queue-max' type=int items=1
value=00000010
name='ddi-devid-registrant' type=int items=1
value=00000001
With prtconf -u, the admin property values are displayed. The vendor
property list in this case contains no properties as the vendor
driver.conf contained no specification for such properties.
sd, instance #1
Admin properties:
name='retries' type=int items=1
value=00000004
sd, instance #2
Admin properties:
name='queue-max' type=int items=1
value=00000010
Example 5 Adding a New Device Instance
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. Fur‐
ther 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:
name="sd" class="scsi" target=0 lun=0 max-retries=8 queue=32;
name="sd" class="scsi" target=1 lun=0 max-retries=10 queue=64;
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.
sd, instance #1
System properties:
name='max-retries' type=int items=1
value=00000008
name='lun' type=int items=1
value=00000000
name='target' type=int items=1
value=00000000
name='class' type=string items=1
value='scsi'
name='queue' type=int items=1
value=00000020
name='ddi-devid-registrant' type=int items=1
value=00000001
Admin properties:
name='queue' type=int items=1
value=00000020
name='max-retries' type=int items=1
value=00000008
Vendor properties:
name='max-retries' type=int items=1
value=00000004
sd, instance #2 (driver not attached)
System properties:
name='queue' type=int items=1
value=00000040
name='max-retries' type=int items=1
value=0000000a
name='lun' type=int items=1
value=00000000
name='target' type=int items=1
value=00000001
name='class' type=string items=1
value='scsi'
name='ddi-devid-registrant' type=int items=1
value=00000001
Admin properties:
name='queue' type=int items=1
value=00000040
name='max-retries' type=int items=1
value=0000000a
name='lun' type=int items=1
value=00000000
name='target' type=int items=1
value=00000001
name='class' type=string items=1
value='scsi'
SEE ALSO
driver(5), pci(5), pseudo(5), scsi(5), add_drv(8), probe(9E), ddi_get‐
longprop(9F), ddi_getprop(9F), ddi_getproplen(9F),
ddi_prop_get_int(9F), ddi_prop_lookup(9F), ddi_prop_op(9F)
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(8) command should be used to prompt the kernel to reread
driver.conf files.
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.
Oracle Solaris 11.4 15 Apr 2019 driver.conf(5)