unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.9)
Page:
Section:
Apropos / Subsearch:
optional field



File Formats                                               pci(4)



NAME
     pci - configuration files for PCI device drivers

DESCRIPTION
     The Peripheral Component Interconnect (PCI) bus is a  little
     endian  bus.  PCI  devices are self-identifying - that is to
     say the PCI device  provides configuration parameters to the
     system,  which  allows the system to identify the device and
     its driver. The configuration parameters are represented  in
     the form of name-value pairs that can be retrieved using the
     DDI  property  interfaces.   See   ddi_prop_lookup(9F)   for
     details.

     The  PCI bus properties are derived from  PCI  configuration
     space,  or supplied by the Fcode  PROM, if it exists. There-
     fore, driver configuration  files  are  not  necessary   for
     these devices.

     On some occasions, drivers for PCI devices  can  use  driver
     configuration  files  to  provide  driver private properties
     through the global property  mechanism.  See  driver.conf(4)
     for further details.  Driver configuration files can also be
     used to  augment  or  override  properties  for  a  specific
     instance of a driver.

     All bus drivers of class  pci recognize the  following  pro-
     perties:

     reg   An arbitrary length array where each  element  of  the
           array  consists  of  a 5-tuple of 32-bit values.  Each
           array element describes a logically contiguous  mappa-
           ble resource on the PCI bus.

           The first three values in the 5-tuple describe the PCI
           address of the mappable resource. The first tuple con-
           tains the following information:


           Bits 0 - 7           8-bit register number
           Bits 8 - 10          3-bit function number
           Bits 11 - 15         5-bit device number
           Bits 16 - 23         8-bit bus number
           Bits 24 - 25         2-bit address space type identifier

           The address space type identifier can  be  interpreted
           as follows:


           0x0                  configuration space
           0x1                  I/O space
           0x2                  32-bit memory space address
           0x3                  64-bit memory space address



SunOS 5.9            Last change: 4 Mar 1997                    1






File Formats                                               pci(4)



           The bus number is a unique identifying number assigned
           to each PCI bus within a PCI domain.

           The device  number  is  a  unique  identifying  number
           assigned  to each PCI device on a PCI bus. Note that a
           device number is unique only within the set of  device
           numbers for a particular bus.

           Each PCI  device  can  have  one  to  eight  logically
           independent  functions,  each with its own independent
           set of configuration registers.  Each  function  on  a
           device  is assigned a function number.  For a PCI dev-
           ice with only one function, the function  number  must
           be  0.

           The register number field selects a particular  regis-
           ter   within   the   set  of  configuration  registers
           corresponding to the selected function.

           The second and third values in  the  reg  property  5-
           tuple  specify  the  64-bit  address  of  the mappable
           resource within the  PCI address  domain.  The  second
           32-bit  tuple corresponds to the high order four bytes
           of  the  64-bit  address.  The  third   32-bit   tuple
           corresponds to the low order bytes.

           The fourth and fifth 32-bit values in the 5-tuple  reg
           property  specify  the  size of the mappable resource.
           The size is a 64-bit value,  where  the  fourth  tuple
           corresponds to the high order bytes of the 64-bit size
           and the fifth corresponds to the low order.

           The driver can refer to the elements of this array  by
           index,   and   construct   kernel  mappings  to  these
           addresses using ddi_regs_map_setup(9F). The index into
           the  array  is  passed  as  the  rnumber  argument  of
           ddi_regs_map_setup(9F).

           At a high-level interrupt context,  you  can  use  the
           ddi_get*  and   ddi_put* family of functions to access
           I/O and memory space.  However, access  to  configura-
           tion  space  is  not  allowed when running at a  high-
           interrupt level.

     interrupts
           This property consists  of  a  single-integer  element
           array.  Valid  interrupt property values are  1, 2, 3,
           and  4. This value is derived directly from  the  con-
           tents   of  the  device's  configuration-interrupt-pin
           register.

           A  driver  should  use  an  index  value  of   0  when



SunOS 5.9            Last change: 4 Mar 1997                    2






File Formats                                               pci(4)



           registering     its     interrupt     handler     with
           ddi_add_intr(9F).

     All PCI devices support the reg property. The device  number
     and  function  number  as  derived from the reg property are
     used to construct the address part of the device name  under
     /devices.

     Only devices that generate interrupts support an  interrupts
     property.

     Occasionally it might be necessary to  override  or  augment
     the configuration information supplied by a PCI device. This
     change can be achieved by  writing  a  driver  configuration
     file  that  describes  a prototype device node specification
     containing the additional properties required.

     For the system to merge  the  prototype  node  specification
     into an actual device node, certain conditions must be met.

        o  First, the name property must be identical. The  value
           of  the  name property 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.

        o  Second, the parent property must identify the PCI bus.

        o  Third, the unit-address  property  must  identify  the
           card. The format of the unit-address property is:

           DD[,F]


     where DD is the device number and F is the function  number.
     If the function number is 0, only DD is specified.

EXAMPLES
     Example 1: A sample configuration file.

     An example configuration file called ACME,scsi-hba.conf  for
     a PCI driver called ACME,scsi-hba follows:

     #
     # Copyright (c) 1995, ACME SCSI Host Bus Adaptor
     # ident   "@(#)ACME,scsi-hba.conf  1.1  96/02/04"
     name="ACME,scsi-hba" parent="/pci@1,0/pci@1f,4000"
        unit-address="3" scsi-initiator-id=6;
     hba-advanced-mode="on";
     hba-dma-speed=10;




SunOS 5.9            Last change: 4 Mar 1997                    3






File Formats                                               pci(4)



     In this example, a property scsi-initiator-id specifies  the
     SCSI  bus initiator id that the adapter should use, for just
     one particular instance of adapter installed in the machine.
     The  name property identifies the driver and the parent pro-
     perty to identify the particular bus  the  card  is  plugged
     into. This example uses the parent's full path name to iden-
     tify the bus. The unit-address property identifies the  card
     itself, with device number of 3 and function number of 0.

     Two  global  driver  properties  are  also   created:   hba-
     advanced-mode  (which  has  the  string value  on) and  hba-
     dma-speed (which has the value  10 M bit/s).  These  proper-
     ties  apply  to  all  device nodes of the ACME,scsi-hba. The
     following  is   an   example   configuration   file   called
     ACME,foo.conf for a PCI driver called ACME,foo;

     #
     # Copyright (c) 1996, ACME Foo driver
     # ident   "@(#)ACME,foo.conf  1.1  95/11/14"
     name="ACME,foo" class="pci" unit-address="3,1"
        debug-mode=12;

     In this example, we provide a property  debug-mode  for  all
     instances  of  the ACME,foo driver with parents of class pci
     and device and function numbers of 3 and 1, respectively.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Architecture                | SPARC, x86                  |
    |_____________________________|_____________________________|


SEE ALSO
     driver.conf(4),       attributes(5),       ddi_add_intr(9F),
     ddi_prop_lookup(9F), ddi_regs_map_setup(9F)

     Writing Device Drivers

     IEEE 1275 PCI Bus Binding











SunOS 5.9            Last change: 4 Mar 1997                    4