plus some related functions.
i didnt know which of the int arguments is used as the flags argument to
the bus_space_map call it wraps. students tell me that having to read
the source code instead of some doco is literally (figuratively) the
worst, so here's some doco so i don't have to read the code next time.
the wording isnt the best, but i reckon it is a good start.
ok?
Index: Makefile
===================================================================
RCS file: /cvs/src/share/man/man9/Makefile,v
retrieving revision 1.291
diff -u -p -r1.291 Makefile
--- Makefile 12 Nov 2018 15:13:12 -0000 1.291
+++ Makefile 22 Feb 2019 06:32:12 -0000
@@ -25,8 +25,8 @@ MAN= aml_evalnode.9 atomic_add_int.9 ato
malloc.9 membar_sync.9 memcmp.9 mbuf.9 mbuf_tags.9 md5.9 mi_switch.9 \
microtime.9 ml_init.9 mq_init.9 mutex.9 \
namei.9 \
- panic.9 pci_conf_read.9 pci_intr_map.9 physio.9 pmap.9 \
- pool.9 pool_cache_init.9 ppsratecheck.9 printf.9 psignal.9 \
+ panic.9 pci_conf_read.9 pci_mapreg_map.9 pci_intr_map.9 physio.9 \
+ pmap.9 pool.9 pool_cache_init.9 ppsratecheck.9 printf.9 psignal.9 \
RBT_INIT.9 \
radio.9 arc4random.9 rasops.9 ratecheck.9 refcnt_init.9 resettodr.9 \
rssadapt.9 route.9 rt_ifa_add.9 rt_timer_add.9 rtalloc.9 rtable_add.9 \
Index: pci_mapreg_map.9
===================================================================
RCS file: pci_mapreg_map.9
diff -N pci_mapreg_map.9
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ pci_mapreg_map.9 22 Feb 2019 06:32:12 -0000
@@ -0,0 +1,151 @@
+.\" $OpenBSD$
+.\"
+.\" Copyright (c) 2019 David Gwynne <d...@openbsd.org>
+.\" All rights reserved.
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: June 4 2013 $
+.Dt PCI_MAPREG_MAP 9
+.Os
+.Sh NAME
+.Nm pci_mapreg_map ,
+.Nm pci_mapreg_info ,
+.Nm pci_mapreg_probe ,
+.Nm pci_mapreg_type
+.\" .Nm pci_mem_find ,
+.\" .Nm pci_io_find
+.Nd PCI register mappings
+.Sh SYNOPSIS
+.In dev/pci/pcivar.h
+.Ft int
+.Fo pci_mapreg_map
+.Fa "struct pci_attach_args *paa"
+.Fa "int reg"
+.Fa "pcireg_t type"
+.Fa "int flags"
+.Fa "bus_space_tag_t *tagp"
+.Fa "bus_space_handle_t *handlep"
+.Fa "bus_addr_t *basep"
+.Fa "bus_size_t *sizep"
+.Fa "bus_size_t maxsize"
+.Fc
+.Ft int
+.Fo pci_mapreg_info
+.Fa "pci_chipset_tag_t pc"
+.Fa "pcitag_t tag"
+.Fa "int reg"
+.Fa "pcireg_t type"
+.Fa "bus_addr_t *basep"
+.Fa "bus_size_t *sizep"
+.Fa "int *flagsp"
+.Fc
+.Ft int
+.Fo pci_mapreg_probe
+.Fa "pci_chipset_tag_t pc"
+.Fa "pcitag_t tag"
+.Fa "int reg"
+.Fa "pcireg_t *typep"
+.Fc
+.Ft pcireg_t
+.Fo pci_mapreg_type
+.Fa "pci_chipset_tag_t pc"
+.Fa "pcitag_t tag"
+.Fa "int reg"
+.Fc
+.\" .Ft int
+.\" .Fo pci_mem_find
+.\" .Fa "pci_chipset_tag_t pc"
+.\" .Fa "pcitag_t pcitag"
+.\" .Fa "int reg"
+.\" .Fa "bus_addr_t *basep"
+.\" .Fa "bus_size_t *sizep"
+.\" .Fa "int *cacheablep"
+.\" .Fc
+.\" .Ft int
+.\" .Fo pci_io_find
+.\" .Fa "pci_chipset_tag_t pc"
+.\" .Fa "pcitag_t pcitag"
+.\" .Fa "int reg"
+.\" .Fa "bus_addr_t *basep"
+.\" .Fa "bus_size_t *sizep"
+.\" .Fa "int *cacheablep"
+.\" .Fc
+.Sh DESCRIPTION
+These functions provide wrappers and helpers around
+.Xr bus_space 9
+mappings for device registers described by the Base Address Registers
+(BARs) in a PCI devices configuration space.
+.Pp
+.Nm pci_mapreg_map
+wraps a call to
+.Xr bus_space_map 9
+using information from the BAR referenced by
+.Fa reg
+for the device being attached with
+.Fa paa .
+Memory or I/O mappings are derived from the
+.Fa type
+argument.
+The size of the register mapping can be restricted by specifying a
+non-zero value in
+.Fa maxsize .
+The bus space tag and handle used for the mapping, and the base
+address and size of the mapping will be provided to the caller via
+the optional
+.Fa tagp ,
+.Fa handlep ,
+.Fa basep ,
+and
+.Fa sizep
+pointers.
+.Pp
+.Nm pci_mapreg_info
+provides bus space mapping information from the BAR referenced by
+.Fa reg .
+The
+.Fa type
+argument specifies whether the mapping provides Memory or I/O access.
+The base address, size, and bus space flags are optionally provided
+to the caller via the
+.Fa basep ,
+.Fa sizep ,
+and
+.Fa flagsp
+pointers.
+.Pp
+.Nm pci_mapreg_probe
+attempts to determine if the BAR referenced by
+.Fa reg
+describes a valid register mapping.
+.Pp
+.Nm pci_mapreg_type
+returns the type of register access for the registers at the BAR
+referenced by
+.Fa reg .
+.Sh RETURN VALUES
+.Nm pci_mapreg_map ,
+.Nm pci_mapreg_info ,
+and
+.Nm pci_mapreg_probe
+return 0 on success, or an errno style value on failure.
+.Pp
+.Nm pci_mapreg_type
+returns either
+.Dv PCI_MAPREG_TYPE_IO
+or
+.Dv PCI_MAPREG_TYPE_MEM .
+.Sh SEE ALSO
+.Xr pci 4 ,
+.Xr bus_space 9 ,
+.Xr pci_conf_read 9
