share/man/man9/pci_configure_bus.9

   1 .\"     $NetBSD: pci_configure_bus.9,v 1.13 2006/02/22 03:07:40 garbled Exp $
   2 .\"
   3 .\" Copyright 2001 Wasabi Systems, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Written by Allen Briggs for Wasabi Systems, Inc.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"      This product includes software developed for the NetBSD Project by
  19 .\"      Wasabi Systems, Inc.
  20 .\" 4. The name of Wasabi Systems, Inc. may not be used to endorse
  21 .\"    or promote products derived from this software without specific prior
  22 .\"    written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  26 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  27 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL WASABI SYSTEMS, INC
  28 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  29 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  30 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  31 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  32 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  33 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  34 .\" POSSIBILITY OF SUCH DAMAGE.
  35 .\"
  36 .Dd February 21, 2006
  37 .Dt PCI_CONFIGURE_BUS 9
  38 .Os
  39 .Sh NAME
  40 .Nm pci_configure_bus ,
  41 .Nm pci_conf_hook ,
  42 .Nm pci_conf_interrupt
  43 .Nd perform PCI bus configuration
  44 .Sh SYNOPSIS
  45 .In dev/pci/pciconf.h
  46 .Ft int
  47 .Fo pci_configure_bus
  48 .Fa "pci_chipset_tag_t pc"
  49 .Fa "struct extent *ioext"
  50 .Fa "struct extent *memext"
  51 .Fa "struct extent *pmemext"
  52 .Fa "int firstbus"
  53 .Fa "int cacheline_size"
  54 .Fc
  55 .Sh DESCRIPTION
  56 The
  57 .Fn pci_configure_bus
  58 function configures a PCI bus for use.
  59 This involves:
  60 .Bl -bullet
  61 .It
  62 Defining bus numbers for all busses on the system,
  63 .It
  64 Setting the Base Address Registers for all devices,
  65 .It
  66 Setting up the interrupt line register for all devices,
  67 .It
  68 Configuring bus latency timers for all devices, and
  69 .It
  70 Configuring cacheline sizes for all devices.
  71 .El
  72 .Pp
  73 In traditional PCs and Alpha systems, the BIOS or firmware takes care
  74 of this task, but that is not the case for all systems.
  75 .Fn pci_configure_bus
  76 should be called prior to the autoconfiguration of the bus.
  77 .Pp
  78 The
  79 .Fa pc
  80 argument is a machine-dependent tag used to specify the PCI chipset to the
  81 system.
  82 This should be the same value used with
  83 .Fn pci_make_tag .
  84 The extent arguments
  85 define memory extents from which the address space for the cards will be
  86 taken.
  87 These addresses should be in the PCI address space.
  88 The
  89 .Fa ioext
  90 extent is for PCI I/O accesses.
  91 The
  92 .Fa memext
  93 extent is for PCI memory accesses that might have side effects.
  94 I.e., that can not be cached.
  95 The
  96 .Fa pmemext
  97 extent is for PCI memory accesses that can be cached.
  98 The
  99 .Fa pmemext
 100 extent will be used for any ROMs and any memory regions that are marked as
 101 .Dq prefetchable
 102 in their BAR.
 103 If an implementation does not distinguish between
 104 prefetchable and non-prefetchable memory, it may pass NULL for
 105 .Fa pmemext .
 106 In this case, prefetchable memory allocations will be made from the
 107 non-prefetchable region.
 108 The
 109 .Fa firstbus
 110 argument indicates the number of the first bus to be configured.
 111 The
 112 .Fa cacheline_size
 113 argument is used to configure the PCI Cache Line Size Register; it
 114 should be the size, in bytes, of the largest D-cache line on the system.
 115 .Pp
 116 An implementation may choose to not have full configuration performed
 117 by
 118 .Fn pci_configure_bus
 119 on certain PCI devices, such as PCI host bridges or PCI bus analyzers
 120 which are instantiated as devices on the bus.
 121 In order for this to take place, the header
 122 .Aq Pa machine/pci_machdep.h
 123 must define the
 124 .Dv __HAVE_PCI_CONF_HOOK
 125 symbol (without a value), and a machine-dependent function
 126 .Fn pci_conf_hook
 127 (declared in the same header)
 128 must be defined.
 129 The prototype for this function is
 130 .Pp
 131 .Fn "int pci_conf_hook" "pci_chipset_tag_t pc" "int bus" \
 132     "int device" "int function" "pcireg_t id"
 133 .Pp
 134 In this function,
 135 .Fa bus ,
 136 .Fa device ,
 137 and
 138 .Fa function
 139 uniquely identify the item being configured;
 140 in addition to this, the value of the device's PCI identification
 141 register is passed in
 142 .Fa id .
 143 For each device
 144 .Fn pci_conf_hook
 145 can then decide upon the amount of configuration to be performed by
 146 returning a bitwise inclusive-or of the following flags:
 147 .Bl -tag -width PCI_CONF_ENABLE_MEM -offset indent
 148 .It Dv PCI_CONF_MAP_IO
 149 Configure Base Address Registers that map I/O space
 150 .It Dv PCI_CONF_MAP_MEM
 151 Configure Base Address Registers that map memory space
 152 .It Dv PCI_CONF_MAP_ROM
 153 Configure Expansion ROM Base Address register
 154 .It Dv PCI_CONF_ENABLE_IO
 155 Enable I/O space accesses
 156 .It Dv PCI_CONF_ENABLE_MEM
 157 Enable memory space accesses
 158 .It Dv PCI_CONF_ENABLE_BM
 159 Enable bus mastering
 160 .El
 161 .Pp
 162 In addition,
 163 .Dv PCI_CONF_ALL
 164 specifies all of the above.
 165 .Pp
 166 One of the functions of
 167 .Fn pci_configure_bus
 168 is to configure interrupt
 169 .Dq line
 170 information.
 171 This must be done on a machine-dependent basis, so a
 172 machine-dependent function
 173 .Fn pci_conf_interrupt
 174 must be defined.
 175 The prototype for this function is
 176 .Pp
 177 .Fn "void pci_conf_interrupt" "pci_chipset_tag_t pc" "int bus" \
 178     "int device" "int pin" "int swiz" "int *iline"
 179 .Pp
 180 In this function,
 181 .Fa bus ,
 182 .Fa device ,
 183 and
 184 .Fa pin ,
 185 uniquely identify the item being configured.
 186 The
 187 .Fa swiz
 188 argument is a
 189 .Dq swizzle ,
 190 a sum of the device numbers of the primary interface of the bridges between
 191 the host bridge and the current device.
 192 The function is responsible for setting the value of
 193 .Fa iline .
 194 See chapter 9 of the
 195 .Dq PCI-to-PCI Bridge Architecture Specification
 196 for more information on swizzling (also known as interrupt routing).
 197 .Sh RETURN VALUES
 198 If successful
 199 .Fn pci_configure_bus
 200 returns 0.
 201 A non-zero return value means that the bus was not completely
 202 configured for some reason.
 203 A description of the failure will be displayed on the console.
 204 .Sh ENVIRONMENT
 205 The
 206 .Fn pci_configure_bus
 207 function is only included in the kernel if the kernel is compiled with
 208 the
 209 .Dv PCI_NETBSD_CONFIGURE
 210 option enabled.
 211 .Sh EXAMPLES
 212 The
 213 .Fn pci_conf_hook
 214 function in evbppc's walnut implementation looks like:
 215 .Pp
 216 .Bd -literal -compact
 217 int
 218 pci_conf_hook(pci_chipset_tag_t pc, int bus, int dev, int func,
 219     pcireg_t id)
 220 {
 221
 222         if ((PCI_VENDOR(id) == PCI_VENDOR_IBM \*[Am]\*[Am]
 223              PCI_PRODUCT(id) == PCI_PRODUCT_IBM_405GP) ||
 224             (PCI_VENDOR(id) == PCI_VENDOR_INTEL \*[Am]\*[Am]
 225              PCI_PRODUCT(id) == PCI_PRODUCT_INTEL_80960_RP)) {
 226                 /* Don't configure the bridge and PCI probe. */
 227                 return 0;
 228         }
 229         return (PCI_CONF_ALL \*[Am] ~PCI_CONF_MAP_ROM);
 230 }
 231 .Ed
 232 .Pp
 233 The
 234 .Fn pci_conf_interrupt
 235 function in the sandpoint implementation looks like:
 236 .Pp
 237 .Bd -literal -compact
 238 void
 239 pci_conf_interrupt(pci_chipset_tag_t pc, int bus, int dev, int pin,
 240     int swiz, int *iline)
 241 {
 242         if (bus == 0) {
 243                 *iline = dev;
 244         } else {
 245                 *iline = 13 + ((swiz + dev + 3) \*[Am] 3);
 246         }
 247 }
 248 .Ed
 249 .Pp
 250 The BeBox has nearly 1GB of PCI I/O memory starting at processor address
 251 0x81000000 (PCI I/O address 0x01000000), and nearly 1GB of PCI memory
 252 starting at 0xC0000000 (PCI memory address 0x00000000).
 253 The
 254 .Fn pci_configure_bus
 255 function might be called as follows:
 256 .Pp
 257 .Bd -literal -compact
 258         struct extent *ioext, *memext;
 259         ...
 260         ioext  = extent_create("pciio",  0x01000000, 0x0fffffff, M_DEVBUF,
 261             NULL, 0, EX_NOWAIT);
 262         memext = extent_create("pcimem", 0x00000000, 0x0fffffff, M_DEVBUF,
 263             NULL, 0, EX_NOWAIT);
 264         ...
 265         pci_configure_bus(0, ioext, memext, NULL);
 266         ...
 267         extent_destroy(ioext);
 268         extent_destroy(memext);
 269         ...
 270 .Ed
 271 .Pp
 272 Note that this must be called before the PCI bus is attached during
 273 autoconfiguration.
 274 .Sh SEE ALSO
 275 .Xr pci 4 ,
 276 .Xr extent 9
 277 .Sh HISTORY
 278 .Fn pci_configure_bus
 279 was added in
 280 .Nx 1.6 .