driver.conf - driver configuration files




     Driver configuration files  pass  information  about  device
     drivers  and  their configuration to the system. Most device
     drivers do not have to have configuration files. Drivers for
     devices  that are self-identifying, such as the SBus devices
     on many systems, can usually obtain all the information they
     need from the FCode PROM on the SBus card using the DDI pro-
     perty    interfaces.    See     ddi_prop_get_int(9F)     and
     ddi_prop_lookup(9F) for details.

     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  ver-
     sion  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 (see the name  field,  below)
     needs  to  match the binding name of the device. The binding
     name is the name chosen by the system to bind a driver to  a
     device  and is either an alias associated with the driver or
     the hardware node name of the device.

     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 a  simple  nexus
     driver  name  to match all instances of that parent/node, or
     the parent name can be a specific full  pathname,  beginning
     with  a slash (/) character, identifying a specific instance
     of a parent bus.

     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  may  have
     different  names  on  different  platforms,  but  the target
     drivers can use class scsi to insulate themselves from these

     Entries of either form above correspond to a device informa-
     tion (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 it will be
     connected to. Any number of name-value pairs may  be  speci-
     fied  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  specifica-
     tion 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

     The  configuration  file  may  contain  several  entries  to
     specify  different  device  configurations and parent nodes.
     The system may 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 partic-
     ular, property names should contain only  printable  charac-
     ters,  and  should  not  contain  at-sign  (@),  slash  (/),
     backslash (\fR), colon (:), or square  brackets  ([]).  Pro-
     perty 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

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


     Example 1: Configuration File for a PCI Bus Frame Buffer

     The following is an example of a configuration  file  called
     ACME,simple.conf   for   a   PCI  bus  frame  buffer  called

     # 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"

     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

     Example 2: 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

     # Copyright (c) 1993, ACME Fictitious Devices, Inc.
     #ident    "@(#)ACME,example.conf   1.2  93/09/09"
     name="ACME,example" parent="pseudo" instance=0

     name="ACME,example" parent="pseudo" instance=1;


     This creates two devinfo  nodes  called  ACME,example  which
     will attach 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 will be created on the first devinfo node  which
     will  have  the  value 1. The example driver will be able to
     fetch the value of this property using ddi_prop_get_int(9F).

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


     pci(4),    pseudo(4),    sbus(4),    scsi(4),     probe(9E),
     ddi_getlongprop(9F),   ddi_getprop(9F),  ddi_getproplen(9F),

     Writing Device Drivers


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


     The update_drv(1M) command should be used to prompt the ker-
     nel  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.

Man(1) output converted with man2html