[src/trunk]: src/share/man/man9 Add documentation for pci_conf_hook().

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

details:   https://anonhg.NetBSD.org/src/rev/21ec753119de
branches:  trunk
changeset: 522134:21ec753119de
user:      kleink <kleink%NetBSD.org@localhost>
date:      Mon Feb 11 18:43:39 2002 +0000

description:
Add documentation for pci_conf_hook().

diffstat:

 share/man/man9/pci_configure_bus.9 |  76 ++++++++++++++++++++++++++++++++++++-
 1 files changed, 73 insertions(+), 3 deletions(-)

diffs (107 lines):

diff -r 91520006e5dc -r 21ec753119de share/man/man9/pci_configure_bus.9
--- a/share/man/man9/pci_configure_bus.9        Mon Feb 11 18:16:48 2002 +0000
+++ b/share/man/man9/pci_configure_bus.9        Mon Feb 11 18:43:39 2002 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: pci_configure_bus.9,v 1.3 2001/12/26 01:02:01 wiz Exp $
+.\"    $NetBSD: pci_configure_bus.9,v 1.4 2002/02/11 18:43:39 kleink Exp $
 .\"
 .\" Copyright 2001 Wasabi Systems, Inc.
 .\" All rights reserved.
@@ -33,11 +33,12 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd February 9, 2001
+.Dd February 11, 2002
 .Dt PCI_CONFIGURE_BUS 9
 .Os
 .Sh NAME
-.Nm pci_configure_bus
+.Nm pci_configure_bus ,
+.Nm pci_conf_hook ,
 .Nm pci_conf_interrupt
 .Nd perform PCI bus configuration
 .Sh SYNOPSIS
@@ -93,6 +94,55 @@
 In this case, prefetchable memory allocations will be made from the
 non-prefetchable region.
 .Pp
+An implementation may choose to not have full configuration performed
+by
+.Fn pci_configure_bus
+on certain PCI devices, such as PCI host bridges or PCI bus analyzers
+which are instantiated as devices on the bus.  In order for this to
+take place, the header
+.Aq Pa machine/pci_machdep.h
+must define the
+.Dv __HAVE_PCI_CONF_HOOK
+symbol (without a value), and a machine-dependent function
+.Fn pci_conf_hook
+(declared in the same header)
+must be defined.  The prototype for this function is
+.Pp
+.Fn "int pci_conf_hook" "pci_chipset_tag_t pc" "int id" \
+    "int bus" "int device" "int function"
+.Pp
+In this function,
+.Fa bus ,
+.Fa device ,
+and
+.Fa function
+uniquely identify the item being configured;
+in addition to this, the value of the device's PCI identification
+register is passed in
+.Fa id .
+For each device
+.Fn pci_conf_hook
+can then decide upon the amount of configuration to be performed by
+returning a bitwise inclusive-or of the following flags:
+.Bl -tag -width PCI_CONF_ENABLE_MEM -offset indent
+.It Dv PCI_CONF_MAP_IO
+Configure Base Address Registers that map I/O space
+.It Dv PCI_CONF_MAP_MEM
+Configure Base Address Registers that map memory space
+.It Dv PCI_CONF_MAP_ROM
+Configure Expansion ROM Base Address register
+.It Dv PCI_CONF_ENABLE_IO
+Enable I/O space accesses
+.It Dv PCI_CONF_ENABLE_MEM
+Enable memory space accesses
+.It Dv PCI_CONF_ENABLE_BM
+Enable bus mastering
+.El
+.Pp
+In addition,
+.Dv PCI_CONF_ALL
+specifies all of the above.
+.Pp
 One of the functions of
 .Fn pci_configure_bus
 is to configure interrupt
@@ -136,6 +186,26 @@
 option enabled.
 .Sh EXAMPLES
 The
+.Fn pci_conf_hook
+function in the walnut implementation looks like:
+.Pp
+.Bd -literal -compact
+int
+pci_conf_hook(pci_chipset_tag_t pc, int bus, int dev, int func, int id)
+{
+
+       if ((PCI_VENDOR(id) == PCI_VENDOR_IBM &&
+            PCI_PRODUCT(id) == PCI_PRODUCT_IBM_405GP) ||
+           (PCI_VENDOR(id) == PCI_VENDOR_INTEL &&
+            PCI_PRODUCT(id) == PCI_PRODUCT_INTEL_80960_RP)) {
+               /* Don't configure the bridge and PCI probe. */
+               return 0;
+       }
+       return (PCI_CONF_ALL & ~PCI_CONF_MAP_ROM);
+}
+.Ed
+.Pp
+The
 .Fn pci_conf_interrupt
 function in the sandpoint implementation looks like:
 .Pp