[src/uebayasi-xip]: src/share/man/man9 Document pci_chipset_tag_create(9) and...

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

details:   https://anonhg.NetBSD.org/src/rev/70d368755e45
branches:  uebayasi-xip
changeset: 751699:70d368755e45
user:      dyoung <dyoung%NetBSD.org@localhost>
date:      Wed Apr 28 21:15:48 2010 +0000

description:
Document pci_chipset_tag_create(9) and pci_chipset_tag_destroy(9).

diffstat:

 share/man/man9/pci.9 |  748 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 748 insertions(+), 0 deletions(-)

diffs (truncated from 752 to 300 lines):

diff -r 49c86684eded -r 70d368755e45 share/man/man9/pci.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/pci.9      Wed Apr 28 21:15:48 2010 +0000
@@ -0,0 +1,748 @@
+.\"     $NetBSD: pci.9,v 1.31.2.2 2010/04/28 21:15:48 dyoung Exp $
+.\"
+.\" Copyright (c) 2001, 2003 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Gregory McGarry.
+.\"
+.\" 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.
+.\"
+.\" 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 April 28, 2010
+.Dt PCI 9
+.Os
+.Sh NAME
+.Nm PCI ,
+.Nm pci_activate ,
+.Nm pci_chipset_tag_create ,
+.Nm pci_chipset_tag_destroy ,
+.Nm pci_conf_read ,
+.Nm pci_conf_write ,
+.Nm pci_conf_print ,
+.Nm pci_conf_capture ,
+.Nm pci_conf_restore ,
+.Nm pci_find_device ,
+.Nm pci_get_capability ,
+.Nm pci_mapreg_type ,
+.Nm pci_mapreg_map ,
+.Nm pci_mapreg_info ,
+.Nm pci_intr_map ,
+.Nm pci_intr_string ,
+.Nm pci_intr_evcnt ,
+.Nm pci_intr_establish ,
+.Nm pci_intr_disestablish ,
+.Nm pci_get_powerstate ,
+.Nm pci_set_powerstate ,
+.Nm pci_vpd_read ,
+.Nm pci_vpd_write ,
+.Nm pci_make_tag ,
+.Nm pci_decompose_tag ,
+.Nm pci_findvendor ,
+.Nm pci_devinfo ,
+.Nm PCI_VENDOR ,
+.Nm PCI_PRODUCT ,
+.Nm PCI_REVISION
+.Nd Peripheral Component Interconnect
+.Sh SYNOPSIS
+.In machine/bus.h
+.In dev/pci/pcivar.h
+.In dev/pci/pcireg.h
+.In dev/pci/pcidevs.h
+.Ft int
+.Fn pci_activate "pci_chipset_tag_t pc" "pcitag_t tag" "device_t dev" \
+"int (*wakeup)(pci_chipset_tag_t pc, pcitag_t tag" \
+"\t\tdevice_t dev, pcireg_t reg)"
+.Ft int
+.Fn pci_chipset_tag_create "pci_chipset_tag_t opc" "uint64_t present" \
+"const struct pci_overrides *ov" "void *ctx" "pci_chipset_tag_t *pcp"
+.Ft void
+.Fn pci_chipset_tag_destroy "pci_chipset_tag_t pc"
+.Ft pcireg_t
+.Fn pci_conf_read "pci_chipset_tag_t pc" "pcitag_t tag" "int reg"
+.Ft void
+.Fn pci_conf_write "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" \
+"pcireg_t val"
+.Ft void
+.Fn pci_conf_print "pci_chipset_tag_t pc" "pcitag_t tag" \
+"void (*func)(pci_chipset_tag_t, pcitag_t, const pcireg_t *)"
+.Ft void
+.Fn pci_conf_capture "pci_chipset_tag_t pc" "pcitag_t tag" \
+"struct pci_conf_state *"
+.Ft void
+.Fn pci_conf_restore "pci_chipset_tag_t pc" "pcitag_t tag" \
+"struct pci_conf_state *"
+.Ft int
+.Fn pci_find_device "struct pci_attach_args *pa" \
+"int (*func)(struct pci_attach_args *)"
+.Ft int
+.Fn pci_get_capability "pci_chipset_tag_t pc" "pcitag_t tag" \
+"int capid" "int *offsetp" "pcireg_t *valuep"
+.Ft pcireg_t
+.Fn pci_mapreg_type "pci_chipset_tag_t pc" "pcitag_t tag" "int reg"
+.Ft int
+.Fn pci_mapreg_map "struct pci_attach_args *pa" "int reg" \
+"pcireg_t type"  "int busflags" "bus_space_tag_t *tagp" \
+"bus_space_handle_t *handlep" "bus_addr_t *basep" "bus_size_t *sizep"
+.Ft int
+.Fn pci_mapreg_info "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" \
+"pcireg_t type" "bus_addr_t *basep" "bus_size_t *sizep" "int *flagsp"
+.Ft int
+.Fn pci_find_rom "struct pci_attach_args *pa" \
+"bus_space_tag_t bst" "bus_space_handle_t bsh" "int code" \
+"bus_space_handle_t *handlep" "bus_space_size_t *sizep"
+.Ft int
+.Fn pci_intr_map "struct pci_attach_args *pa" "pci_intr_handle_t *ih"
+.Ft const char *
+.Fn pci_intr_string "pci_chipset_tag_t pc" "pci_intr_handle_t ih"
+.Ft const struct evcnt *
+.Fn pci_intr_evcnt "pci_chipset_tag_t pc" "pci_intr_handle_t ih"
+.Ft void *
+.Fn pci_intr_establish "pci_chipset_tag_t pc" "pci_intr_handle_t ih" \
+"int level" "int (*handler)(void *)" "void *arg"
+.Ft void
+.Fn pci_intr_disestablish "pci_chipset_tag_t pc" "void *ih"
+.Ft int
+.Fn pci_set_powerstate "pci_chipset_tag_t pc" "pcitag_t tag" \
+"pcireg_t newstate"
+.Ft int
+.Fn pci_get_powerstate "pci_chipset_tag_t pc" "pcitag_t tag" "pcireg_t *state"
+.Ft int
+.Fn pci_vpd_read "pci_chipset_tag_t pc" "pcitag_t tag" "int offset" \
+"int count" "pcireg_t *data"
+.Ft int
+.Fn pci_vpd_write "pci_chipset_tag_t pc" "pcitag_t tag" "int offset" \
+"int count" "pcireg_t *data"
+.Ft pcitag_t
+.Fn pci_make_tag "pci_chipset_tag_t pc" "int bus" "int device" \
+"int function"
+.Ft void
+.Fn pci_decompose_tag "pci_chipset_tag_t pc" "pcitag_t tag" \
+"int *busp" "int *devicep" "int *functionp"
+.Ft char *
+.Fn pci_findvendor "pcireg_t id"
+.Ft void
+.Fn pci_devinfo "pcireg_t id" "pcireg_t class" "int show" "char *cp" "size_t len"
+.Ft int
+.Fn PCI_VENDOR "pcireg_t id"
+.Ft int
+.Fn PCI_PRODUCT "pcireg_t id"
+.Ft int
+.Fn PCI_REVISION "pcireg_t id"
+.Sh DESCRIPTION
+The machine-independent
+.Nm
+subsystem provides support for PCI devices.
+.Pp
+The PCI bus was initially developed by Intel in the early 1990's to
+replace the ISA bus for interfacing with their Pentium processor.
+The PCI specification is widely regarded as well designed, and the
+PCI bus has found widespread acceptance in machines ranging from
+Apple's PowerPC-based systems to Sun's UltraSPARC-based machines.
+.Pp
+The PCI bus is a multiplexed bus, allowing addresses and data on the same
+pins for a reduced number of pins.
+Data transfers can be 8-bit, 16-bit or 32-bit.
+A 64-bit extended PCI bus is also defined.
+Multi-byte transfers are little-endian.
+The PCI bus operates up to 33MHz and any device on the bus can be
+the bus master.
+.Pp
+AGP is a version of PCI optimised for high-throughput data rates,
+particularly for accelerated frame buffers.
+.Pp
+The PCI bus is a "plug and play" bus, in the sense that devices can be
+configured dynamically by software.
+The PCI interface chip on a PCI device bus presents a small window
+of registers into the PCI configuration space.
+These registers contain information about the device such as the vendor
+and a product ID.
+The configuration registers can also be written to by software to alter
+how the device interfaces to the PCI bus.
+An important register in the configuration space is the Base Address
+Register (BAR).
+The BAR is written to by software to map the device registers into a
+window of processor address space.
+Once this mapping is done, the device registers can be accessed relative
+to the base address.
+.Sh DATA TYPES
+Drivers for devices attached to the
+.Nm
+will make use of the following data types:
+.Bl -tag -width compact
+.It Fa pcireg_t
+Configuration space register.
+.It Fa pci_chipset_tag_t
+Chipset tag for the PCI bus.
+.It Fa pcitag_t
+Configuration tag describing the location and function of the PCI
+device.
+It contains the tuple
+.Ao
+bus, device, function
+.Ac .
+.It Fa pci_intr_handle_t
+The opaque handle describing an established interrupt handler.
+.It Fa struct pci_attach_args
+Devices have their identity recorded in this structure.
+It contains the following members:
+.Bd -literal
+       bus_space_tag_t pa_iot;         /* pci i/o space tag */
+       bus_space_tag_t pa_memt;        /* pci mem space tag */
+       bus_dma_tag_t pa_dmat;          /* DMA tag */
+       pci_chipset_tag_t pa_pc;
+       int pa_flags;                   /* flags */
+       pcitag_t pa_tag;
+       pcireg_t pa_id;
+       pcireg_t pa_class;
+.Ed
+.It Fa struct pci_conf_state
+Stores the PCI configuration state of a device.
+It contains the following member:
+.Bd -literal
+       pcireg_t reg[16];                       /* pci conf register */
+.Ed
+.It Fa struct pci_overrides
+Stores pointers to functions that override the architecture's
+default
+.Xr pci 9
+and
+.Xr pci_intr 9
+implementation.
+It contains the following members:
+.Bd -literal
+       pcireg_t (*ov_conf_read)(void *,
+           pci_chipset_tag_t, pcitag_t, int);
+       void (*ov_conf_write)(void *,
+           pci_chipset_tag_t, pcitag_t, int, pcireg_t);
+       int (*ov_intr_map)(void *,
+          struct pci_attach_args *, pci_intr_handle_t *);
+       const char *(*ov_intr_string)(void *,
+           pci_chipset_tag_t, pci_intr_handle_t);
+       const struct evcnt *(*ov_intr_evcnt)(void *,
+           pci_chipset_tag_t, pci_intr_handle_t);
+       void *(*ov_intr_establish)(void *,
+           pci_chipset_tag_t, pci_intr_handle_t,
+           int, int (*)(void *), void *);
+       void (*ov_intr_disestablish)(void *,
+           pci_chipset_tag_t, void *);
+       pcitag_t (*ov_make_tag)(void *,
+           pci_chipset_tag_t, int, int, int);
+       void (*ov_decompose_tag)(void *,
+           pci_chipset_tag_t, pcitag_t, int *, int *, int *);
+.Ed
+.El
+.Sh FUNCTIONS
+.Bl -tag -width compact
+.It Fn pci_activate "pc" "tag" "dev" "fun"
+Attempt to bring the device to state D0.
+If the device is not in the D0 state call
+.Fa fun
+to restore its state.
+If
+.Fa fun
+is
+.Dv NULL
+then restoring from state D3 is going to fail.
+.It Fn pci_chipset_tag_create "opc" "present" "ov" "ctx" "pcp"
+Create a copy of the tag
+.Fa opc
+at
+.Fa *pcp .
+Except for the behavior
+overridden by
+.Fa ov ,
+.Fa *pcp
+inherits the behavior of
+.Fa opc
+under
+.Nm
+calls.
+.Pp
+.Fa ov
+contains function pointers corresponding to
+.Nm
+routines.
+Each function pointer has a corresponding bit in
+.Fa present ,
+and if that bit is 1, the function pointer overrides the corresponding
+.Nm
+call for the new tag.
+Any combination of these bits may be set in
+.Fa present :
+.Pp
+.Bl -tag -width PCI_OVERRIDE_INTR_DISESTABLISH -compact
+.It Dv PCI_OVERRIDE_CONF_READ
+.It Dv PCI_OVERRIDE_CONF_WRITE
+.It Dv PCI_OVERRIDE_INTR_MAP
+.It Dv PCI_OVERRIDE_INTR_STRING