1.\" $NetBSD: pci_configure_bus.9,v 1.15 2010/03/22 18:58:33 joerg 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 56The 57.Fn pci_configure_bus 58function configures a PCI bus for use. 59This involves: 60.Bl -bullet 61.It 62Defining bus numbers for all busses on the system, 63.It 64Setting the Base Address Registers for all devices, 65.It 66Setting up the interrupt line register for all devices, 67.It 68Configuring bus latency timers for all devices, and 69.It 70Configuring cacheline sizes for all devices. 71.El 72.Pp 73In traditional PCs and Alpha systems, the BIOS or firmware takes care 74of this task, but that is not the case for all systems. 75.Fn pci_configure_bus 76should be called prior to the autoconfiguration of the bus. 77.Pp 78The 79.Fa pc 80argument is a machine-dependent tag used to specify the PCI chipset to the 81system. 82This should be the same value used with 83.Fn pci_make_tag . 84The extent arguments 85define memory extents from which the address space for the cards will be 86taken. 87These addresses should be in the PCI address space. 88The 89.Fa ioext 90extent is for PCI I/O accesses. 91The 92.Fa memext 93extent is for PCI memory accesses that might have side effects. 94I.e., that can not be cached. 95The 96.Fa pmemext 97extent is for PCI memory accesses that can be cached. 98The 99.Fa pmemext 100extent will be used for any ROMs and any memory regions that are marked as 101.Dq prefetchable 102in their BAR. 103If an implementation does not distinguish between 104prefetchable and non-prefetchable memory, it may pass NULL for 105.Fa pmemext . 106In this case, prefetchable memory allocations will be made from the 107non-prefetchable region. 108The 109.Fa firstbus 110argument indicates the number of the first bus to be configured. 111The 112.Fa cacheline_size 113argument is used to configure the PCI Cache Line Size Register; it 114should be the size, in bytes, of the largest D-cache line on the system. 115.Pp 116An implementation may choose to not have full configuration performed 117by 118.Fn pci_configure_bus 119on certain PCI devices, such as PCI host bridges or PCI bus analyzers 120which are instantiated as devices on the bus. 121In order for this to take place, the header 122.In machine/pci_machdep.h 123must define the 124.Dv __HAVE_PCI_CONF_HOOK 125symbol (without a value), and a machine-dependent function 126.Fn pci_conf_hook 127(declared in the same header) 128must be defined. 129The 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 134In this function, 135.Fa bus , 136.Fa device , 137and 138.Fa function 139uniquely identify the item being configured; 140in addition to this, the value of the device's PCI identification 141register is passed in 142.Fa id . 143For each device 144.Fn pci_conf_hook 145can then decide upon the amount of configuration to be performed by 146returning 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 149Configure Base Address Registers that map I/O space 150.It Dv PCI_CONF_MAP_MEM 151Configure Base Address Registers that map memory space 152.It Dv PCI_CONF_MAP_ROM 153Configure Expansion ROM Base Address register 154.It Dv PCI_CONF_ENABLE_IO 155Enable I/O space accesses 156.It Dv PCI_CONF_ENABLE_MEM 157Enable memory space accesses 158.It Dv PCI_CONF_ENABLE_BM 159Enable bus mastering 160.El 161.Pp 162In addition, 163.Dv PCI_CONF_ALL 164specifies all of the above. 165.Pp 166One of the functions of 167.Fn pci_configure_bus 168is to configure interrupt 169.Dq line 170information. 171This must be done on a machine-dependent basis, so a 172machine-dependent function 173.Fn pci_conf_interrupt 174must be defined. 175The 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 180In this function, 181.Fa bus , 182.Fa device , 183and 184.Fa pin , 185uniquely identify the item being configured. 186The 187.Fa swiz 188argument is a 189.Dq swizzle , 190a sum of the device numbers of the primary interface of the bridges between 191the host bridge and the current device. 192The function is responsible for setting the value of 193.Fa iline . 194See chapter 9 of the 195.Dq PCI-to-PCI Bridge Architecture Specification 196for more information on swizzling (also known as interrupt routing). 197.Sh RETURN VALUES 198If successful 199.Fn pci_configure_bus 200returns 0. 201A non-zero return value means that the bus was not completely 202configured for some reason. 203A description of the failure will be displayed on the console. 204.Sh ENVIRONMENT 205The 206.Fn pci_configure_bus 207function is only included in the kernel if the kernel is compiled with 208the 209.Dv PCI_NETBSD_CONFIGURE 210option enabled. 211.Sh EXAMPLES 212The 213.Fn pci_conf_hook 214function in evbppc's walnut implementation looks like: 215.Pp 216.Bd -literal -compact 217int 218pci_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 233The 234.Fn pci_conf_interrupt 235function in the sandpoint implementation looks like: 236.Pp 237.Bd -literal -compact 238void 239pci_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 250The BeBox has nearly 1GB of PCI I/O memory starting at processor address 2510x81000000 (PCI I/O address 0x01000000), and nearly 1GB of PCI memory 252starting at 0xC0000000 (PCI memory address 0x00000000). 253The 254.Fn pci_configure_bus 255function 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 272Note that this must be called before the PCI bus is attached during 273autoconfiguration. 274.Sh SEE ALSO 275.Xr pci 4 , 276.Xr extent 9 277.Sh HISTORY 278.Fn pci_configure_bus 279was added in 280.Nx 1.6 . 281