.\" $NetBSD: pcibios.4,v 1.19 2017/07/03 21:30:59 wiz Exp $
.\"
.\" Copyright (c) 1999, 2000 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Lennart Augustsson.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd October 9, 2005
.Dt PCIBIOS 4 i386
.Os
.Sh NAME
.Nm pcibios
.Nd introduction to PCI BIOS support
.Sh SYNOPSIS
.Cd "options   PCIBIOS"
.Cd "options   PCIBIOSVERBOSE"
.Cd "#options  PCIBIOS_IRQS_HINT=0x0a00 #IRQ 9,11"
.Cd "#options  PCIBIOS_INTR_FIXUP_FORCE"
.Cd "options   PCIBIOS_INTR_GUESS"
.Cd "#options  PCIINTR_DEBUG"
.Sh INTRODUCTION
.Nm
provides support for setting up PCI controllers, bridges, and devices
using information extracted from the BIOS.
.Pp
Ideally, the boot firmware of a machine (a.k.a. BIOS) should set
up all PCI devices; assigning them I/O and memory addresses and
interrupts.
Alas, this does not always happen, so there is some
PC specific code that can do the initialization when
.Nx
boots.
.Pp
Options:
.Bl -tag -width PCIBIOS_IRQS_HINT -offset 3n
.It Nm PCIBIOS
turn on the PCI BIOS support.
.It Nm PCIBIOSVERBOSE
make the setup procedure verbose.
.It Nm PCIBIOS_IRQS_HINT
hint for IRQ use.
When
.Em PCI_INTR_FIXUP
cannot guess an adequate IRQ for a device, the hint is used.
.Pp
The value is a logical or of power-of-2s of allowable interrupts:
.Bl -column "XX-0xffff" "XX-0xffff" "XX-0xffff" "XX-0xffff" -compact -offset 2n
.It Em "IRQ Value"   Ta Em "IRQ Value" Ta Em "IRQ Value" Ta Em "IRQ Value"
.It    "\& 0 0x0001" Ta    " 4 0x0010"  Ta    " 8 0x0100" Ta    "12 0x1000"
.It    "\& 1 0x0002" Ta    " 5 0x0020"  Ta    " 9 0x0200" Ta    "13 0x2000"
.It    "\& 2 0x0004" Ta    " 6 0x0040"  Ta    "10 0x0400" Ta    "14 0x4000"
.It    "\& 3 0x0008" Ta    " 7 0x0080"  Ta    "11 0x0800" Ta    "15 0x8000"
.El
For example,
.Qq Sy options PCIBIOS_IRQS_HINT=0x0a00
allows IRQ 9 and IRQ 11.
.Pp
The kernel global variable
.Va pcibios_irqs_hint
holds this value,
so a user can override this value without kernel recompilation.
For example:
.Bl -bullet -compact
.It
To specify this value on the fly, type the following command
at the boot prompt to drop into DDB (the in-kernel debugger;
you have to specify
.Qq Sy options DDB
to make kernel with DDB):
.Dl Ic boot -d
And type the following command on
.Qq Sy db>
prompt:
.Dl Ic write pcibios_irqs_hint 0x0a00
Then type the following to continue to boot:
.Dl Ic c
.It
To modify kernel image without kernel recompilation,
run the following command on shell:
.Dl Ic gdb --write /netbsd
And type the following commands at the
.Qq Sy (gdb)
prompt:
.Dl Ic set pcibios_irqs_hint=0xa00
.Dl Ic quit
.El
.It Nm PCIBIOS_INTR_FIXUP_FORCE
Some buggy BIOS implementations provide inconsistent
information between the PCI Interrupt Configuration Register
and the PCI Interrupt Routing table.
In such case, the PCI Interrupt Configuration Register takes precedence
by default.
If this happens, a kernel with
.Em PCIBIOSVERBOSE
shows
.Qq Sy WARNING: preserving irq XX
in the PCI routing table.
.Pp
If
.Em PCIBIOS_INTR_FIXUP_FORCE
is specified in addition to the
.Em PCI_INTR_FIXUP ,
the PCI Interrupt Routing table takes precedence.
In this case, a kernel with
.Em PCIBIOSVERBOSE
shows
.Qq Sy WARNING: overriding irq XX
in the PCI routing table.
.It Nm PCIBIOS_INTR_GUESS
make
.Em PCI_INTR_FIXUP
work with unknown interrupt router.
.Pp
If a PCI interrupt router is not known, normally interrupt
configuration will not be touched.
.Pp
But if
.Em PCIBIOS_INTR_GUESS
is specified in addition to the
.Em PCI_INTR_FIXUP ,
and if a PCI interrupt routing table entry indicates that only
one IRQ is available for the entry, the IRQ is assumed to be already
connected to the device, and corresponding PCI Interrupt
Configuration Register will be configured accordingly.
.It Nm PCIINTR_DEBUG
make the
.Em PCI_INTR_FIXUP
procedure verbose.
.El
.Sh SEE ALSO
.Xr cardbus 4 ,
.Xr pci 4
.Sh HISTORY
The
.Nm
code appeared in
.Nx 1.5 .
.Sh BUGS
The
.Em PCIBIOS_ADDR_FIXUP
option may conflict with the PCI CardBus driver's own
address fixup.