pcibios manual

2 files changed, 262 insertions, 2 deletions

diff --git a/share/man/man4/man4.i386/Makefile b/share/man/man4/man4.i386/Makefile
index ca0221931ec..e50f0d0a352 100644
--- a/share/man/man4/man4.i386/Makefile
+++ b/share/man/man4/man4.i386/Makefile
@@ -1,9 +1,9 @@
-#	$OpenBSD: Makefile,v 1.33 2000/05/20 17:19:52 deraadt Exp $
+#	$OpenBSD: Makefile,v 1.34 2000/08/17 20:20:46 mickey Exp $
 #	from: @(#)Makefile	5.1 (Berkeley) 2/12/91
 #	Id: Makefile,v 1.4 1995/12/14 05:41:38 deraadt Exp $
 
 MAN=	apm.4 autoconf.4 bktr.4 gus.4 ie.4 intro.4 iy.4 joy.4 le.4 lms.4 \
-	lpt.4 mcd.4 mem.4 mms.4 mtrr.4 npx.4 pctr.4 pms.4 pss.4 sb.4 \
+	lpt.4 mcd.4 mem.4 mms.4 mtrr.4 npx.4 pcibios.4 pctr.4 pms.4 pss.4 sb.4 \
 	scd.4 sea.4 speaker.4 uha.4 wdt.4 wss.4 wt.4 xf86.4
 
 MLINKS+= speaker.4 spkr.4
diff --git a/share/man/man4/man4.i386/pcibios.4 b/share/man/man4/man4.i386/pcibios.4
new file mode 100644
index 00000000000..124308b6c6f
--- /dev/null
+++ b/share/man/man4/man4.i386/pcibios.4
@@ -0,0 +1,260 @@
+.\" $OpenBSD: pcibios.4,v 1.1 2000/08/17 20:20:46 mickey Exp $
+.\" $NetBSD: pcibios.4,v 1.7 2000/08/03 13:32:39 soda Exp $
+.\"
+.\" Copyright (c) 2000 Michale Shalayeff, All rights reserved.
+.\" 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.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" 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 July 22, 2000
+.Dt PCIBIOS 4
+.Os
+.Sh NAME
+.Nm pcibios
+.Nd introduction to PCI BIOS support
+.Sh SYNOPSIS
+.Cd "pcibios0 at bios0 flags 0x0000"
+.Cd "option	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"
+.Pp
+.Sh INTRODUCTION
+.Ox
+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
+.Ox
+boots.
+.Pp
+Flags is a bit mask each bit of which specifies which fixup procedures to
+ommit. The following list specifies these procedures and gives
+flags bit values to disable them in case they cause problems.
+
+.Bl -tag -width 0x0000 -offset 3n
+
+.It 0x0001
+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.
+
+Without this flag force allocation of 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 0x0002
+fixup PCI bus numbering; needed for many 
+.Xr cardbus 4
+bridges.
+.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.
+
+Without this flag force assignment of bus numbers for all subordinate
+PCI buses and CardBuses.
+
+Since this procedure renumbers all PCI buses and CardBuses,
+all bus numbers of subordinate buses become different
+when this option is enabled.
+
+.It 0x0004
+fixup PCI interrupt routing.
+.Pp
+Some BIOS implementations don't assign an interrupt for
+some devices.
+
+This procedure 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
+procedure 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 ,
+.Xr pci 4
+.Sh HISTORY
+The
+.Nm
+code appeared in
+.Nx 1.5 .
+.Ox
+support was added in
+.Ox 2.8 .
+In contrast to
+.Nx
+implementation
+.Nm
+in
+.Ox
+is a real device, where options control is done through the
+.Nm flags
+wich are modifiable through the
+.Xr boot_config 8
+interface.
+.Sh BUGS
+The
+.Em PCIBIOS Adress Fixup
+option may conflict with the PCI CardBus driver's own
+address fixup.