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.