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