Source-Changes-HG archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

[src/trunk]: src/share/man/man9 Update pci_configure_bus(9) to reflect the ne...



details:   https://anonhg.NetBSD.org/src/rev/b0a64dd2b576
branches:  trunk
changeset: 1011765:b0a64dd2b576
user:      thorpej <thorpej%NetBSD.org@localhost>
date:      Fri Jul 10 02:27:13 2020 +0000

description:
Update pci_configure_bus(9) to reflect the new reality -- no more manual
fiddling with extent maps, use pciconf_resource_{init,add,fini}() instead.

diffstat:

 distrib/sets/lists/comp/mi         |   11 ++-
 share/man/man9/Makefile            |    7 +-
 share/man/man9/pci_configure_bus.9 |  129 +++++++++++++++++++++---------------
 3 files changed, 91 insertions(+), 56 deletions(-)

diffs (261 lines):

diff -r 7afc4258c743 -r b0a64dd2b576 distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Fri Jul 10 00:42:53 2020 +0000
+++ b/distrib/sets/lists/comp/mi        Fri Jul 10 02:27:13 2020 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: mi,v 1.2338 2020/06/16 01:29:01 thorpej Exp $
+#      $NetBSD: mi,v 1.2339 2020/07/10 02:27:13 thorpej Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 ./etc/mtree/set.comp                           comp-sys-root
@@ -11801,6 +11801,9 @@
 ./usr/share/man/cat9/pci_set_powerstate.0      comp-sys-catman         .cat
 ./usr/share/man/cat9/pci_vpd_read.0            comp-sys-catman         .cat
 ./usr/share/man/cat9/pci_vpd_write.0           comp-sys-catman         .cat
+./usr/share/man/cat9/pciconf_resource_add.0    comp-sys-catman         .cat
+./usr/share/man/cat9/pciconf_resource_fini.0   comp-sys-catman         .cat
+./usr/share/man/cat9/pciconf_resource_init.0   comp-sys-catman         .cat
 ./usr/share/man/cat9/pckbport.0                        comp-sys-catman         .cat
 ./usr/share/man/cat9/pckbport_attach.0         comp-sys-catman         .cat
 ./usr/share/man/cat9/pckbport_attach_slot.0    comp-sys-catman         .cat
@@ -19946,6 +19949,9 @@
 ./usr/share/man/html9/pci_set_powerstate.html  comp-sys-htmlman        html
 ./usr/share/man/html9/pci_vpd_read.html                comp-sys-htmlman        html
 ./usr/share/man/html9/pci_vpd_write.html       comp-sys-htmlman        html
+./usr/share/man/html9/pciconf_resource_add.html        comp-sys-htmlman        html
+./usr/share/man/html9/pciconf_resource_fini.html       comp-sys-htmlman        html
+./usr/share/man/html9/pciconf_resource_init.html       comp-sys-htmlman        html
 ./usr/share/man/html9/pckbport.html            comp-sys-htmlman        html
 ./usr/share/man/html9/pckbport_attach.html     comp-sys-htmlman        html
 ./usr/share/man/html9/pckbport_attach_slot.html comp-sys-htmlman       html
@@ -28250,6 +28256,9 @@
 ./usr/share/man/man9/pci_set_powerstate.9      comp-sys-man            .man
 ./usr/share/man/man9/pci_vpd_read.9            comp-sys-man            .man
 ./usr/share/man/man9/pci_vpd_write.9           comp-sys-man            .man
+./usr/share/man/man9/pciconf_resource_add.9    comp-sys-man            .man
+./usr/share/man/man9/pciconf_resource_fini.9   comp-sys-man            .man
+./usr/share/man/man9/pciconf_resource_init.9   comp-sys-man            .man
 ./usr/share/man/man9/pckbport.9                        comp-sys-man            .man
 ./usr/share/man/man9/pckbport_attach.9         comp-sys-man            .man
 ./usr/share/man/man9/pckbport_attach_slot.9    comp-sys-man            .man
diff -r 7afc4258c743 -r b0a64dd2b576 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Fri Jul 10 00:42:53 2020 +0000
+++ b/share/man/man9/Makefile   Fri Jul 10 02:27:13 2020 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.451 2020/06/16 01:29:00 thorpej Exp $
+#       $NetBSD: Makefile,v 1.452 2020/07/10 02:27:13 thorpej Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -631,7 +631,10 @@
        pci_msi.9 pci_msix_establish.9 \
        pci_msi.9 pci_msix_disestablish.9
 MLINKS+=pci_configure_bus.9 pci_conf_hook.9 \
-       pci_configure_bus.9 pci_conf_interrupt.9
+       pci_configure_bus.9 pci_conf_interrupt.9 \
+       pci_configure_bus.9 pciconf_resource_add.9 \
+       pci_configure_bus.9 pciconf_resource_fini.9 \
+       pci_configure_bus.9 pciconf_resource_init.9
 MLINKS+=pckbport.9 pckbport_attach.9 \
        pckbport.9 pckbport_attach_slot.9 \
        pckbport.9 pckbport_cnattach.9 \
diff -r 7afc4258c743 -r b0a64dd2b576 share/man/man9/pci_configure_bus.9
--- a/share/man/man9/pci_configure_bus.9        Fri Jul 10 00:42:53 2020 +0000
+++ b/share/man/man9/pci_configure_bus.9        Fri Jul 10 02:27:13 2020 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: pci_configure_bus.9,v 1.17 2017/07/03 21:28:48 wiz Exp $
+.\"    $NetBSD: pci_configure_bus.9,v 1.18 2020/07/10 02:27:13 thorpej Exp $
 .\"
 .\" Copyright 2001 Wasabi Systems, Inc.
 .\" All rights reserved.
@@ -33,25 +33,29 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd February 21, 2006
+.Dd July 7, 2020
 .Dt PCI_CONFIGURE_BUS 9
 .Os
 .Sh NAME
 .Nm pci_configure_bus ,
 .Nm pci_conf_hook ,
-.Nm pci_conf_interrupt
+.Nm pci_conf_interrupt ,
+.Nm pciconf_resource_init ,
+.Nm pciconf_resource_add ,
+.Nm pciconf_resource_fini
 .Nd perform PCI bus configuration
 .Sh SYNOPSIS
 .In dev/pci/pciconf.h
 .Ft int
-.Fo pci_configure_bus
-.Fa "pci_chipset_tag_t pc"
-.Fa "struct extent *ioext"
-.Fa "struct extent *memext"
-.Fa "struct extent *pmemext"
-.Fa "int firstbus"
-.Fa "int cacheline_size"
-.Fc
+.Fn pci_configure_bus "pci_chipset_tag_t pc" "struct pciconf_resources *res" \
+    "int firstbus" "int cacheline_size"
+.Ft struct pciconf_resources *
+.Fn pciconf_resource_init "void"
+.Ft void
+.Fn pciconf_resource_add "struct pciconf_resources *res" "int type" \
+    "bus_addr_t addr" "bus_size_t size"
+.Ft void
+.Fn pciconf_resource_fini "struct pciconf_resources *res"
 .Sh DESCRIPTION
 The
 .Fn pci_configure_bus
@@ -81,30 +85,10 @@
 system.
 This should be the same value used with
 .Fn pci_make_tag .
-The extent arguments
-define memory extents from which the address space for the cards will be
-taken.
-These addresses should be in the PCI address space.
 The
-.Fa ioext
-extent is for PCI I/O accesses.
-The
-.Fa memext
-extent is for PCI memory accesses that might have side effects.
-I.e., that can not be cached.
-The
-.Fa pmemext
-extent is for PCI memory accesses that can be cached.
-The
-.Fa pmemext
-extent will be used for any ROMs and any memory regions that are marked as
-.Dq prefetchable
-in their BAR.
-If an implementation does not distinguish between
-prefetchable and non-prefetchable memory, it may pass NULL for
-.Fa pmemext .
-In this case, prefetchable memory allocations will be made from the
-non-prefetchable region.
+.Fa res
+argument is a container for PCI bus resources that will be used to
+configure the bus.
 The
 .Fa firstbus
 argument indicates the number of the first bus to be configured.
@@ -126,10 +110,11 @@
 .Fn pci_conf_hook
 (declared in the same header)
 must be defined.
-The prototype for this function is
+The prototype for this function is:
 .Pp
-.Fn "int pci_conf_hook" "pci_chipset_tag_t pc" "int bus" \
-    "int device" "int function" "pcireg_t id"
+.Ft int
+.Fn "pci_conf_hook" "pci_chipset_tag_t pc" "int bus" \
+    "int device" "int function" "pcireg_t id" ;
 .Pp
 In this function,
 .Fa bus ,
@@ -174,7 +159,8 @@
 must be defined.
 The prototype for this function is
 .Pp
-.Fn "void pci_conf_interrupt" "pci_chipset_tag_t pc" "int bus" \
+.Ft void
+.Fn "pci_conf_interrupt" "pci_chipset_tag_t pc" "int bus" \
     "int device" "int pin" "int swiz" "int *iline"
 .Pp
 In this function,
@@ -194,6 +180,41 @@
 See chapter 9 of the
 .Dq PCI-to-PCI Bridge Architecture Specification
 for more information on swizzling (also known as interrupt routing).
+.Pp
+The resources used to configure the PCI bus are encapsulated into a
+resource container.
+The
+.Fn pciconf_resource_init
+function allocates and initializes one of these containers, and the
+.Fn pciconf_resource_add
+function adds resources to the container, specifying the type, start
+address, and size of the resource being added.
+The following resource types are supported:
+.Bl -tag -width PCICONF_RESOURCE_PREFETCHABLE_MEM -offset indent
+.It Dv PCICONF_RESOURCE_IO
+An adddress region used for PCI I/O accesses.
+.It Dv PCICONF_RESOURCE_MEM
+An address region used for PCI memory accesses where reads may have side
+effects.
+.It Dv PCICONF_RESOURCE_PREFETCHABLE_MEM
+An address region used for PCI memory accesses where reads do not have
+side effects
+.Po
+e.g. ROMs, frame buffers, other memory-like regions that are marked as
+prefetchable in their BAR
+.Pc .
+.El
+.Pp
+If an implementation does not distinguish between prefetchable and
+non-prefetchable memory, then adding a
+.Dv PCICONF_RESOURCE_PREFETCHABLE_MEM
+resource is not required;
+.Dv PCICONF_RESOURCE_MEM
+resources will be used for ROMs and BARs that are marked as prefetchable.
+.Pp
+Once the bus has been successfully configured, the resource container should
+be disposed of by calling
+.Fn pciconf_resource_fini .
 .Sh RETURN VALUES
 If successful
 .Fn pci_configure_bus
@@ -247,25 +268,28 @@
 }
 .Ed
 .Pp
-The BeBox has nearly 1GB of PCI I/O memory starting at processor address
-0x81000000 (PCI I/O address 0x01000000), and nearly 1GB of PCI memory
-starting at 0xC0000000 (PCI memory address 0x00000000).
-The
-.Fn pci_configure_bus
-function might be called as follows:
+This configuration example is taken from the bebox port.
 .Pp
 .Bd -literal -compact
-       struct extent *ioext, *memext;
+#define PCI_IO_START    0x00008000
+#define PCI_IO_END      0x0000ffff
+#define PCI_IO_SIZE     ((PCI_IO_END - PCI_IO_START) + 1)
+
+#define PCI_MEM_START   0x00000000
+#define PCI_MEM_END     0x0fffffff
+#define PCI_MEM_SIZE    ((PCI_MEM_END - PCI_MEM_START) + 1)
+       ...
+       struct pciconf_resources *pcires;
        ...
-       ioext  = extent_create("pciio",  0x01000000, 0x0fffffff,
-           NULL, 0, EX_NOWAIT);
-       memext = extent_create("pcimem", 0x00000000, 0x0fffffff,
-           NULL, 0, EX_NOWAIT);
+       pcires = pciconf_resource_init();
+       pciconf_resource_add(pcires, PCICONF_RESOURCE_IO,
+           PCI_IO_START, PCI_IO_SIZE);
+       pciconf_resource_add(pcires, PCICONF_RESOURCE_MEM,
+           PCI_MEM_START, PCI_MEM_SIZE);
        ...
-       pci_configure_bus(0, ioext, memext, NULL);
+       pci_configure_bus(pc, pcires, 0, CACHELINESIZE);
        ...
-       extent_destroy(ioext);
-       extent_destroy(memext);
+       pciconf_resource_fini(pcires);
        ...
 .Ed
 .Pp
@@ -273,7 +297,6 @@
 autoconfiguration.
 .Sh SEE ALSO
 .Xr pci 4 ,
-.Xr extent 9
 .Sh HISTORY
 .Fn pci_configure_bus
 was added in



Home | Main Index | Thread Index | Old Index