unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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

pci(4)                           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  pro-
       vides  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. Therefore, driver configura-
       tion 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  configura-
       tion  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 properties:

       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 mappable
                       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:



                       tab(); lw(1.833333i) lw(1.833333i) lw(1.833333i).  Bits
                       0 - 78-bit register number Bits 8  -  103-bit  function
                       number  Bits  11  -  155-bit device number Bits 16 - 23
                       8-bit bus number Bits 24 - 252-bit address  space  type
                       identifier

                       The address space type identifier can be interpreted as
                       follows:



                       tab();   lw(1.833333i)   lw(1.833333i)   lw(1.833333i).
                       0x0configuration  space  0x1I/O  space 0x232-bit memory
                       space address 0x364-bit memory space address

                       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  inde-
                       pendent functions, each with its own independent set of
                       configuration registers. Each function on a  device  is
                       assigned a function number.  For a PCI device with only
                       one function, the function number must be  0.

                       The register number field selects a particular register
                       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 cor-
                       responds 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_set-
                       up(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 configuration
                       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  reg-
                       ister.

                       A driver should use an index value of  0 when register-
                       ing its interrupt handler with  ddi_add_intr(9F).



       All PCI devices support the reg property. The device number  and  func-
       tion  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  configu-
       ration  information  supplied  by  a  PCI  device.  This  change can be
       achieved by writing a driver configuration file that describes a proto-
       type  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  bind-
            ing  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 for-
            mat 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;

       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  iden-
       tifies  the  driver  and the parent property to identify the particular
       bus the card is plugged into. This example uses the parent's full  path
       name to identify 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 properties 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 attributes:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE TYPEATTRIBUTE VALUE ArchitectureSPARC, 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.10                        4 Mar 1997                            pci(4)