share/man/man4/driver.conf.4

   1 '\" te
   2 .\"  Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH DRIVER.CONF 4 "Jan 5, 2007"
   7 .SH NAME
   8 driver.conf \- driver configuration files
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBdriver.conf\fR
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 Driver configuration files provide values for device properties. The values
  19 override values provided by the devices themselves. Most modern devices provide
  20 enough property values to make a driver configuration file unnecessary.
  21 .sp
  22 .LP
  23 The system associates a driver with its configuration file by name. For
  24 example, a driver in \fB/usr/kernel/drv\fR called \fBwombat\fR has the driver
  25 configuration file \fBwombat.conf\fR, also stored in \fB/usr/kernel/drv\fR,
  26 associated with it. On systems capable of support 64-bit drivers, the driver
  27 configuration file should be placed in the directory in which the 32-bit driver
  28 is (or would be) located, even if only a 64-bit version is provided. For
  29 example, a 64-bit driver stored in \fB/usr/kernel/drv/sparcv9\fR stores its
  30 driver configuration file in \fB/usr/kernel/drv\fR.
  31 .sp
  32 .LP
  33 The value of the \fBname\fR property is the node name. In a \fBdriver.conf\fR
  34 file, where the generic node name and \fBcompatible\fR property associated with
  35 a self-identifying devices are typically not used, the node name must be a
  36 binding name. The binding name is the name chosen by the system to bind a
  37 driver to the device. The binding name is either an alias associated with the
  38 driver established by \fBadd_drv\fR(8) or the driver name itself.
  39 .sp
  40 .LP
  41 The syntax of a single entry in a driver configuration file takes one of three
  42 forms:
  43 .sp
  44 .in +2
  45 .nf
  46 \fBname\fR="\fInode name\fR" \fBparent\fR="\fIparent name\fR" [\fIproperty-name=value\fR ...]\fB;\fR
  47 .fi
  48 .in -2
  49
  50 .sp
  51 .LP
  52 In this form, the parent name can be either the binding name of the parent
  53 nexus driver or a specific full pathname, beginning with a slash (\fB/\fR)
  54 character, identifying a specific instance of a parent bus. If a binding name
  55 is used then all parent nodes bound to that driver match. A generic name (for
  56 example, \fBpci\fR) is not a valid binding name even though it can appear in
  57 the full pathname of all intended parents.
  58 .sp
  59 .LP
  60 Alternatively, the parent can be specified by the type of interface it presents
  61 to its children.
  62 .sp
  63 .in +2
  64 .nf
  65 \fBname\fR="\fInode name\fR" \fBclass\fR="\fIclass name\fR" [\fIproperty-name=value\fR ...]\fB;\fR
  66 .fi
  67 .in -2
  68
  69 .sp
  70 .LP
  71 For example, the driver for the \fBSCSI\fR host adapter can have different
  72 names on different platforms, but the target drivers can use class \fBscsi\fR
  73 to insulate themselves from these differences.
  74 .sp
  75 .LP
  76 Entries of either form above correspond to a device information (\fBdevinfo\fR)
  77 node in the kernel device tree. Each node has a \fIname\fR which is usually the
  78 name of the driver, and a \fIparent\fR name which is the name of the parent
  79 \fBdevinfo\fR node to which it will be connected. Any number of name-value
  80 pairs can be specified to create properties on the prototype \fBdevinfo\fR
  81 node. These properties can be retrieved using the DDI property interfaces (for
  82 example, \fBddi_prop_get_int\fR(9F) and \fBddi_prop_lookup\fR(9F)). The
  83 prototype \fBdevinfo\fR node specification must be terminated with a semicolon
  84 (\fB;\fR).
  85 .sp
  86 .LP
  87 The third form of an entry is simply a list of properties.
  88 .sp
  89 .in +2
  90 .nf
  91 [\fIproperty-name=value\fR ...]\fB;\fR
  92 .fi
  93 .in -2
  94 .sp
  95
  96 .sp
  97 .LP
  98 A property created in this way is treated as global to the driver. It can be
  99 overridden by a property with the same name on a particular \fBdevinfo\fR node,
 100 either by creating one explicitly on the prototype node in the driver.conf file
 101 or by the driver.
 102 .sp
 103 .LP
 104 Items are separated by any number of newlines, \fBSPACE\fR or \fBTAB\fR
 105 characters.
 106 .sp
 107 .LP
 108 The configuration file can contain several entries to specify different device
 109 configurations and parent nodes. The system can call the driver for each
 110 possible prototype \fBdevinfo\fR node, and it is generally the responsibility
 111 of the drivers \fBprobe\fR(9E) routine to determine if the hardware described
 112 by the prototype \fBdevinfo\fR node is really present.
 113 .sp
 114 .LP
 115 Property names must not violate the naming conventions for Open Boot PROM
 116 properties or for IEEE 1275 names. In particular, property names should contain
 117 only printable characters, and should not contain at-sign (\fB@\fR), slash
 118 (\fB/\fR), backslash (\fB\e\fR), colon (\fB:\fR), or square brackets
 119 (\fB[]\fR). Property values can be decimal integers or strings delimited by
 120 double quotes (\fB"\fR). Hexadecimal integers can be constructed by prefixing
 121 the digits with \fB0x\fR.
 122 .sp
 123 .LP
 124 A comma separated list of integers can be used to construct properties whose
 125 value is an integer array. The value of such properties can be retrieved inside
 126 the driver using \fBddi_prop_lookup_int_array\fR(9F).
 127 .sp
 128 .LP
 129 Comments are specified by placing a \fB#\fR character at the beginning of the
 130 comment string, the comment string extends for the rest of the line.
 131 .SH EXAMPLES
 132 .LP
 133 \fBExample 1 \fRConfiguration File for a PCI Bus Frame Buffer
 134 .sp
 135 .LP
 136 The following is an example of a configuration file called
 137 \fBACME,simple.conf\fR for a \fBPCI\fR bus frame buffer called
 138 \fBACME,simple\fR.
 139
 140 .sp
 141 .in +2
 142 .nf
 143 #
 144 # Copyright (c) 1993, by ACME Fictitious Devices, Inc.
 145 #
 146 #ident  "@(#)ACME,simple.conf   1.3     1999/09/09"
 147
 148 name="ACME,simple" class="pci" unit-address="3,1"
 149         debug-mode=12;
 150 .fi
 151 .in -2
 152
 153 .sp
 154 .LP
 155 This example creates a prototype \fBdevinfo\fR node called \fBACME,simple\fR
 156 under all parent nodes of class \fBpci\fR. The node has device and function
 157 numbers of 3 and 1, respectively; the property \fBdebug-mode\fR is provided for
 158 all instances of the driver.
 159
 160 .LP
 161 \fBExample 2 \fRConfiguration File for a Pseudo Device Driver
 162 .sp
 163 .LP
 164 The following is an example of a configuration file called
 165 \fBACME,example.conf\fR for a pseudo device driver called \fBACME,example\fR.
 166
 167 .sp
 168 .in +2
 169 .nf
 170 #
 171 # Copyright (c) 1993, ACME Fictitious Devices, Inc.
 172 #
 173 #ident  "@(#)ACME,example.conf  1.2   93/09/09"
 174 name="ACME,example" parent="pseudo" instance=0
 175     debug-level=1;
 176
 177 name="ACME,example" parent="pseudo" instance=1;
 178
 179 whizzy-mode="on";
 180 debug-level=3;
 181 .fi
 182 .in -2
 183
 184 .sp
 185 .LP
 186 This creates two \fBdevinfo\fR nodes called \fBACME,example\fR which attaches
 187 below the \fBpseudo\fR node in the kernel device tree. The \fBinstance\fR
 188 property is only interpreted by the \fBpseudo\fR node, see \fBpseudo\fR(4) for
 189 further details. A property called \fBdebug-level\fR is created on the first
 190 \fBdevinfo\fR node which has the value 1. The \fBexample\fR driver is able to
 191 fetch the value of this property using \fBddi_prop_get_int\fR(9F).
 192
 193 .sp
 194 .LP
 195 Two global driver properties are created, \fBwhizzy-mode\fR (which has the
 196 string value "on") and \fBdebug-level\fR (which has the value 3). If the driver
 197 looks up the property \fBwhizzy-mode\fR on either node, it retrieves the value
 198 of the global \fBwhizzy-mode\fR property ("on"). If the driver looks up the
 199 \fBdebug-level\fR property on the first node, it retrieves the value of the
 200 \fBdebug-level\fR property on that node (1). Looking up the same property on
 201 the second node retrieves the value of the global \fBdebug-level\fR property
 202 (3).
 203
 204 .SH SEE ALSO
 205 .sp
 206 .LP
 207 \fBadd_drv\fR(8), \fBpci\fR(4), \fBpseudo\fR(4), \fBsbus\fR(4), \fBscsi\fR(4),
 208 \fBprobe\fR(9E), \fBddi_getlongprop\fR(9F), \fBddi_getprop\fR(9F),
 209 \fBddi_getproplen\fR(9F), \fBddi_prop_get_int\fR(9F),
 210 \fBddi_prop_lookup\fR(9F), \fBddi_prop_op\fR(9F)
 211 .sp
 212 .LP
 213 \fIWriting Device Drivers\fR
 214 .SH WARNINGS
 215 .sp
 216 .LP
 217 To avoid namespace collisions between multiple driver vendors, it is strongly
 218 recommended that the \fIname\fR property of the driver should begin with a
 219 vendor-unique string. A reasonably compact and unique choice is the vendor
 220 over-the-counter stock symbol.
 221 .SH NOTES
 222 .sp
 223 .LP
 224 The \fBupdate_drv\fR(8) command should be used to prompt the kernel to reread
 225 \fBdriver.conf\fR files. Using \fBmodunload\fR(8) to update \fBdriver.conf\fR
 226 continues to work in release 9 of the Solaris operating environment, but the
 227 behavior will change in a future release.