[src/netbsd-1-5]: src/share/man/man4/man4.i386 Pullup 1.5-1.8 [soda, hubertf]:

[tv <tv%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/821ef0fa666f
branches:  netbsd-1-5
changeset: 490150:821ef0fa666f
user:      tv <tv%NetBSD.org@localhost>
date:      Sun Nov 05 01:09:49 2000 +0000

description:
Pullup 1.5-1.8 [soda, hubertf]:
Add documentation of several PCIBIOS options; see log.

diffstat:

 share/man/man4/man4.i386/pcibios.4 |  194 +++++++++++++++++++++++++++++++++---
 1 files changed, 176 insertions(+), 18 deletions(-)

diffs (237 lines):

diff -r 33d6f71352c6 -r 821ef0fa666f share/man/man4/man4.i386/pcibios.4
--- a/share/man/man4/man4.i386/pcibios.4        Sun Nov 05 01:06:55 2000 +0000
+++ b/share/man/man4/man4.i386/pcibios.4        Sun Nov 05 01:09:49 2000 +0000
@@ -1,6 +1,6 @@
-.\" $NetBSD: pcibios.4,v 1.4 2000/06/11 01:13:44 augustss Exp $
+.\" $NetBSD: pcibios.4,v 1.4.2.1 2000/11/05 01:09:49 tv Exp $
 .\"
-.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
+.\" Copyright (c) 1999, 2000 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
 .\" This code is derived from software contributed to The NetBSD Foundation
@@ -34,7 +34,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd February 27, 2000
+.Dd July 22, 2000
 .Dt PCIBIOS 4
 .Os
 .Sh NAME
@@ -42,12 +42,14 @@
 .Nd introduction to PCI BIOS support
 .Sh SYNOPSIS
 .Cd "options   PCIBIOS"
-.Cd "#options  PCIBIOSVERBOSE"
+.Cd "options   PCIBIOSVERBOSE"
+.Cd "options   PCIBIOS_ADDR_FIXUP"
+.Cd "options   PCIBIOS_BUS_FIXUP"
 .Cd "options   PCIBIOS_INTR_FIXUP"
-.Cd "#options  PCIBIOS_IRQS_HINT=""0x0a00"" #IRQ 9,11"
+.Cd "#options  PCIBIOS_IRQS_HINT=0x0a00 #IRQ 9,11"
+.Cd "#options  PCIBIOS_INTR_FIXUP_FORCE"
+.Cd "options   PCIBIOS_INTR_GUESS"
 .Cd "#options  PCIINTR_DEBUG"
-.Cd "options   PCIBIOS_BUS_FIXUP"
-.Cd "options   PCIBIOS_ADDR_FIXUP"
 .Pp
 .Sh INTRODUCTION
 .Nx
@@ -62,25 +64,176 @@
 boots.
 .Pp
 Options:
-.Bl -tag -width PCIBIOS_INTR_FIXUP -offset 3n -compact
+.Bl -tag -width PCIBIOS_INTR_FIXUP -offset 3n
+
 .It Nm PCIBIOS
 turn on the PCI BIOS support.
+
 .It Nm PCIBIOSVERBOSE
 make the setup procedure verbose.
-.It Nm PCIBIOS_INTR_FIXUP
-fixup PCI interrupt routing.
-.It Nm PCIBIOS_IRQS_HINT
-hint for IRQ use.
-When the PCI BIOS support cannot
-guess an adequate IRQ for a device the hint is used.
-.It Nm PCIINTR_DEBUG
-super-verbose PCI interrupt fixup.
+
+.It Nm PCIBIOS_ADDR_FIXUP
+fixup PCI I/O and memory addresses.
+.Pp
+Some BIOS implementations don't allocate I/O space and
+memory space for some PCI devices. Especially, a BIOS
+which is
+.Qq PnP OS mode enabled
+shows this behavior.
+Since necessary space isn't allocated, those devices
+will not work without special handling.
+
+This option allocates I/O space and memory space
+instead of relying upon the BIOS to do so.
+
+If necessary space is already correctly assigned to the devices,
+this option leaves the space as is.
+
+Although many BIOS implementations leave CardBus bridges'
+space unallocated, the CardBus bridge device driver doesn't
+require this option, since the driver allocates necessary space
+by itself.
+
 .It Nm PCIBIOS_BUS_FIXUP
 fixup PCI bus numbering; needed for many 
 .Xr cardbus 4
 bridges.
-.It Nm PCIBIOS_ADDR_FIXUP
-fixup PCI I/O and memory addresses.
+.Pp
+Each PCI bus and CardBus should have a unique bus number. 
+But some BIOS implementations don't assign a bus number
+for subordinate PCI buses. And many BIOS implementations
+don't assign a bus number for CardBuses.
+
+A typical symptom of this is the following boot message:
+.D1 Sy cardbus0 at cardslot0: bus 0 device 0...
+Please note that this cardbus0 has a bus number
+.Sq 0 ,
+but normally the bus number 0 is used by the machine's
+primary PCI bus. Thus, this bus number for cardbus is
+incorrect
+.Pq not assigned .
+In this situation, a device located in cardbus0 doesn't 
+show correct device ID,
+because its bus number 0 incorrectly refers to the primary 
+PCI bus, and a device ID in the primary PCI bus is shown
+in the boot message instead of the device's ID in the cardbus0.
+
+This option assigns bus numbers for all subordinate
+PCI buses and CardBuses.
+
+Since this option renumbers all PCI buses and CardBuses,
+all bus numbers of subordinate buses become different
+when this option is enabled.
+
+.It Nm PCIBIOS_INTR_FIXUP
+fixup PCI interrupt routing.
+.Pp
+Some BIOS implementations don't assign an interrupt for
+some devices.
+
+This option assigns an interrupt for such devices instead
+of relying upon the BIOS to do so.
+
+If the BIOS has already assigned an interrupt to a device, this
+option leaves the interrupt as is.
+
+.It Nm PCIBIOS_IRQS_HINT
+hint for IRQ use.
+When the
+.Em PCIBIOS_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" Em "\tIRQ Value" Em "\tIRQ Value" Em "\tIRQ Value"
+.It    "\& 0 0x0001"    "\t 4 0x0010"    "\t 8 0x0100"    "\t12 0x1000"
+.It    "\& 1 0x0002"    "\t 5 0x0020"    "\t 9 0x0200"    "\t13 0x2000"
+.It    "\& 2 0x0004"    "\t 6 0x0040"    "\t10 0x0400"    "\t14 0x4000"
+.It    "\& 3 0x0008"    "\t 7 0x0080"    "\t11 0x0800"    "\t15 0x8000"
+.El
+For example,
+.Qq Sy options PCIBIOS_IRQS_HINT=0x0a00
+allows IRQ 9 and IRQ 11.
+
+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
+.Pp
+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.
+
+If
+.Em PCIBIOS_INTR_FIXUP_FORCE
+is specified in addition to the
+.Em PCIBIOS_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.
+
+The necessity of this option is doubtful, and we may
+remove this option in the future. If you find that this
+option is worth preserving, please report it with send-pr.
+
+.It Nm PCIBIOS_INTR_GUESS
+make
+.Em PCIBIOS_INTR_FIXUP
+work with unknown interrupt router.
+.Pp
+If a PCI interrupt router is not known, normally interrupt
+configuraion will not be touched.
+
+But if
+.Em PCIBIOS_INTR_GUESS
+is specified in addition to the
+.Em PCIBIOS_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 PCIBIOS_INTR_FIXUP
+procedure verbose.
+
 .El
 .Sh SEE ALSO
 .Xr cardbus 4 ,
@@ -90,3 +243,8 @@
 .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.