Tue Apr 14 13:28:34 2015 UTC ()
Pull up following revision(s) (requested by riastradh in ticket #1272):
	share/man/man9/pci_intr.9: revision 1.18 via patch
Fix type of pc argument in pci_intr(9) man page.


(msaitoh)
diff -r1.15 -r1.15.6.1 src/share/man/man9/pci_intr.9
cvs diff -r1.15 -r1.15.6.1 src/share/man/man9/pci_intr.9 (switch to unified diff)

--- src/share/man/man9/pci_intr.9 2011/04/05 14:57:33 1.15
+++ src/share/man/man9/pci_intr.9 2015/04/14 13:28:34 1.15.6.1
@@ -1,144 +1,144 @@ @@ -1,144 +1,144 @@
1.\" $NetBSD: pci_intr.9,v 1.15 2011/04/05 14:57:33 dyoung Exp $ 1.\" $NetBSD: pci_intr.9,v 1.15.6.1 2015/04/14 13:28:34 msaitoh Exp $
2.\" 2.\"
3.\" Copyright (c) 2000 The NetBSD Foundation, Inc. 3.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Bill Sommerfeld 7.\" by Bill Sommerfeld
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in the 15.\" notice, this list of conditions and the following disclaimer in the
16.\" documentation and/or other materials provided with the distribution. 16.\" documentation and/or other materials provided with the distribution.
17.\" 17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd April 5, 2011 30.Dd February 25, 2015
31.Dt PCI_INTR 9 31.Dt PCI_INTR 9
32.Os 32.Os
33.Sh NAME 33.Sh NAME
34.Nm pci_intr , 34.Nm pci_intr ,
35.Nm pci_intr_map , 35.Nm pci_intr_map ,
36.Nm pci_intr_string , 36.Nm pci_intr_string ,
37.Nm pci_intr_establish , 37.Nm pci_intr_establish ,
38.Nm pci_intr_disestablish 38.Nm pci_intr_disestablish
39.Nd PCI bus interrupt manipulation functions 39.Nd PCI bus interrupt manipulation functions
40.Sh SYNOPSIS 40.Sh SYNOPSIS
41.In dev/pci/pcivar.h 41.In dev/pci/pcivar.h
42.Ft int 42.Ft int
43.Fn pci_intr_map "const struct pci_attach_args *pa" "pci_intr_handle_t *ih" 43.Fn pci_intr_map "const struct pci_attach_args *pa" "pci_intr_handle_t *ih"
44.Ft const char * 44.Ft const char *
45.Fn pci_intr_string "pci_chipset_t *pc" "pci_intr_handle_t ih" 45.Fn pci_intr_string "pci_chipset_tag_t pc" "pci_intr_handle_t ih"
46.Ft void * 46.Ft void *
47.Fn pci_intr_establish "pci_chipset_t *pc" "pci_intr_handle_t ih" \ 47.Fn pci_intr_establish "pci_chipset_tag_t pc" "pci_intr_handle_t ih" \
48"int ipl" "int (*intrhand)(void *)" "void *intrarg" 48"int ipl" "int (*intrhand)(void *)" "void *intrarg"
49.Ft void 49.Ft void
50.Fn pci_intr_disestablish "pci_chipset_t *pc" "void *ih" 50.Fn pci_intr_disestablish "pci_chipset_tag_t pc" "void *ih"
51.Sh DESCRIPTION 51.Sh DESCRIPTION
52The 52The
53.Nm 53.Nm
54functions exist to allow device drivers machine-independent access to 54functions exist to allow device drivers machine-independent access to
55PCI bus interrupts. 55PCI bus interrupts.
56The functions described in this page are typically declared in a port's 56The functions described in this page are typically declared in a port's
57.In machine/pci_machdep.h 57.In machine/pci_machdep.h
58header file; however, drivers should generally include 58header file; however, drivers should generally include
59.In dev/pci/pcivar.h 59.In dev/pci/pcivar.h
60to get other PCI-specific declarations as well. 60to get other PCI-specific declarations as well.
61.Pp 61.Pp
62Each driver has an 62Each driver has an
63.Fn attach 63.Fn attach
64function which has a bus-specific 64function which has a bus-specific
65.Ft attach_args 65.Ft attach_args
66structure. 66structure.
67Each driver for a PCI device is passed a pointer to an object of type 67Each driver for a PCI device is passed a pointer to an object of type
68.Ft struct pci_attach_args 68.Ft struct pci_attach_args
69which contains, among other things, information about the location 69which contains, among other things, information about the location
70of the device in the PCI bus topology sufficient to allow interrupts 70of the device in the PCI bus topology sufficient to allow interrupts
71from the device to be handled. 71from the device to be handled.
72.Pp 72.Pp
73If a driver wishes to establish an interrupt handler for the device, 73If a driver wishes to establish an interrupt handler for the device,
74it should pass the 74it should pass the
75.Ft struct pci_attach_args * 75.Ft struct pci_attach_args *
76to the 76to the
77.Fn pci_intr_map 77.Fn pci_intr_map
78function, which returns zero on success, and nonzero on failure. 78function, which returns zero on success, and nonzero on failure.
79The function sets the 79The function sets the
80.Ft pci_intr_handle_t 80.Ft pci_intr_handle_t
81pointed at by its second argument to a machine-dependent value which 81pointed at by its second argument to a machine-dependent value which
82identifies a particular interrupt source. 82identifies a particular interrupt source.
83.Pp 83.Pp
84If the driver wishes to refer to the interrupt source in an attach or 84If the driver wishes to refer to the interrupt source in an attach or
85error message, it should use the value returned by 85error message, it should use the value returned by
86.Fn pci_intr_string . 86.Fn pci_intr_string .
87.Pp 87.Pp
88Subsequently, when the driver is prepared to receive interrupts, it 88Subsequently, when the driver is prepared to receive interrupts, it
89should call 89should call
90.Fn pci_intr_establish 90.Fn pci_intr_establish
91to actually establish the handler; when the device interrupts, 91to actually establish the handler; when the device interrupts,
92.Fa intrhand 92.Fa intrhand
93will be called with a single argument 93will be called with a single argument
94.Fa intrarg , 94.Fa intrarg ,
95and will run at the interrupt priority level 95and will run at the interrupt priority level
96.Fa ipl . 96.Fa ipl .
97.Pp 97.Pp
98The return value of 98The return value of
99.Fn pci_intr_establish 99.Fn pci_intr_establish
100may be saved and passed to 100may be saved and passed to
101.Fn pci_intr_disestablish 101.Fn pci_intr_disestablish
102to disable the interrupt handler 102to disable the interrupt handler
103when the driver is no longer interested in interrupts from the device. 103when the driver is no longer interested in interrupts from the device.
104.Ss PORTING 104.Ss PORTING
105A port's implementation of 105A port's implementation of
106.Fn pci_intr_map 106.Fn pci_intr_map
107may use the following members of 107may use the following members of
108.Ft struct pci_attach_args 108.Ft struct pci_attach_args
109to determine how the device's interrupts are routed. 109to determine how the device's interrupts are routed.
110.Bd -literal 110.Bd -literal
111 pci_chipset_tag_t pa_pc; 111 pci_chipset_tag_t pa_pc;
112 pcitag_t pa_tag; 112 pcitag_t pa_tag;
113 pcitag_t pa_intrtag; /* intr. appears to come from here */ 113 pcitag_t pa_intrtag; /* intr. appears to come from here */
114 pci_intr_pin_t pa_intrpin; /* intr. appears on this pin */ 114 pci_intr_pin_t pa_intrpin; /* intr. appears on this pin */
115 pci_intr_line_t pa_intrline; /* intr. routing information */ 115 pci_intr_line_t pa_intrline; /* intr. routing information */
116 pci_intr_pin_t pa_rawintrpin; /* unswizzled pin */ 116 pci_intr_pin_t pa_rawintrpin; /* unswizzled pin */
117.Ed 117.Ed
118.Pp 118.Pp
119PCI-PCI 119PCI-PCI
120bridges swizzle (permute) interrupt wiring. 120bridges swizzle (permute) interrupt wiring.
121Depending on implementation details, it may be more convenient to use 121Depending on implementation details, it may be more convenient to use
122either original or the swizzled interrupt parameters. 122either original or the swizzled interrupt parameters.
123The original device tag and interrupt pin can be found in 123The original device tag and interrupt pin can be found in
124.Ft pa_tag 124.Ft pa_tag
125and 125and
126.Ft pa_rawintrpin 126.Ft pa_rawintrpin
127respectively, while the swizzled tag and pin can be found in 127respectively, while the swizzled tag and pin can be found in
128.Ft pa_intrtag 128.Ft pa_intrtag
129and 129and
130.Ft pa_intrpin . 130.Ft pa_intrpin .
131.Pp 131.Pp
132When a device is attached to a primary bus, both pairs of fields 132When a device is attached to a primary bus, both pairs of fields
133contain the same values. 133contain the same values.
134When a device is found behind one or more pci-pci bridges, 134When a device is found behind one or more pci-pci bridges,
135.Ft pa_intrpin 135.Ft pa_intrpin
136contains the 136contains the
137.Dq swizzled 137.Dq swizzled
138interrupt pin number, while 138interrupt pin number, while
139.Ft pa_rawintrpin 139.Ft pa_rawintrpin
140contains the original interrupt pin; 140contains the original interrupt pin;
141.Ft pa_tag 141.Ft pa_tag
142contains the PCI tag of the device itself, and 142contains the PCI tag of the device itself, and
143.Ft pa_intrtag 143.Ft pa_intrtag
144contains the PCI tag of the uppermost bridge device. 144contains the PCI tag of the uppermost bridge device.