[src/trunk]: src/share/man/man4/man4.i386 - describe details

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

details:   https://anonhg.NetBSD.org/src/rev/243f2c1f7998
branches:  trunk
changeset: 495133:243f2c1f7998
user:      soda <soda%NetBSD.org@localhost>
date:      Sat Jul 22 17:53:53 2000 +0000

description:
- describe details
 - add PCIBIOS_INTR_FIXUP_FORCE

English correction by John Hawkinson <jhawk%MIT.EDU@localhost>.
Technical correction is still welcome.

diffstat:

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

diffs (222 lines):

diff -r e9b171319675 -r 243f2c1f7998 share/man/man4/man4.i386/pcibios.4
--- a/share/man/man4/man4.i386/pcibios.4        Sat Jul 22 17:43:36 2000 +0000
+++ b/share/man/man4/man4.i386/pcibios.4        Sat Jul 22 17:53:53 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.5 2000/07/22 17:53:53 soda 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,13 @@
 .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  PCIINTR_DEBUG"
-.Cd "options   PCIBIOS_BUS_FIXUP"
-.Cd "options   PCIBIOS_ADDR_FIXUP"
 .Pp
 .Sh INTRODUCTION
 .Nx
@@ -62,25 +63,162 @@
 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 a I/O space and a 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:
+.Bd -literal
+.Em "IRQ Val      IRQ Val      IRQ Val       IRQ Val"
+ 0  0x0001    4  0x0010    8  0x0100    12  0x1000
+ 1  0x0002    5  0x0020    9  0x0200    13  0x2000
+ 2  0x0004    6  0x0040   10  0x0400    14  0x4000
+ 3  0x0008    7  0x0080   11  0x0800    15  0x8000
+.Ed
+.Pp
+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
+.It
+To specify this value on the fly, type
+.Qq Ic boot -d
+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).
+Specify
+.Qq Ic write pcibios_irqs_hint 0x0a00
+on
+.Qq Sy db>
+prompt and type
+.Qq Ic c
+to continue to boot.
+.It
+To modify kernel image without kernel recompilation,
+run
+.Qq Ic gdb --write /netbsd
+on shell, type
+.Qq Ic set pcibios_irqs_hint=0xa00
+at the
+.Qq Sy (gdb)
+prompt, and type
+.Qq 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 PCIINTR_DEBUG
+make the
+.Em PCIBIOS_INTR_FIXUP
+procedure verbose.
+
 .El
 .Sh SEE ALSO
 .Xr cardbus 4 ,
@@ -90,3 +228,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.