| blob | 74979a8affbb494499e8e737403de9e2b6e1dde5 |
1 .\" $NetBSD: pci.3,v 1.10 2014/12/16 13:38:36 msaitoh Exp $
2 .\"
3 .\" Copyright 2001 Wasabi Systems, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" Written by Jason R. Thorpe for Wasabi Systems, Inc.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. All advertising materials mentioning features or use of this software
17 .\" must display the following acknowledgement:
18 .\" This product includes software developed for the NetBSD Project by
19 .\" Wasabi Systems, Inc.
20 .\" 4. The name of Wasabi Systems, Inc. may not be used to endorse
21 .\" or promote products derived from this software without specific prior
22 .\" written permission.
23 .\"
24 .\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
26 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
27 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC
28 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 .\" POSSIBILITY OF SUCH DAMAGE.
35 .\"
36 .Dd December 16, 2014
37 .Dt PCI 3
38 .Os
39 .Sh NAME
40 .Nm pci
41 .Nd library interface for PCI bus access
42 .Sh LIBRARY
43 .Lb libpci
44 .Sh SYNOPSIS
45 .In pci.h
46 .Ft int
47 .Fn pcibus_conf_read "int pcifd" "u_int bus" "u_int dev" "u_int func" \
48 "u_int reg" "pcireg_t *valp"
49 .Ft int
50 .Fn pcibus_conf_write "int pcifd" "u_int bus" "u_int dev" "u_int func" \
51 "u_int reg" "pcireg_t val"
52 .Ft int
53 .Fn pcidev_conf_read "int devfd" "u_int reg" "pcireg_t *valp"
54 .Ft int
55 .Fn pcidev_conf_write "int devfd" "u_int reg" "pcireg_t val"
56 .Ft char *
57 .Fn pci_findvendor "pcireg_t id_reg"
58 .Ft void
59 .Fn pci_devinfo "pcireg_t id_reg" "pcireg_t class_reg" "int showclass" "char *devinfo" "size_t len"
60 .Ft void
61 .Fn pci_conf_print "int pcifd" "u_int bus" "u_int dev" "u_int func"
62 .Ft int
63 .Fn pci_drvname "int pcifd" "u_int dev" "u_int func" "char *drvname" "size_t len"
64 .Sh DESCRIPTION
65 The
66 .Nm
67 library provides support for accessing the PCI bus by user programs.
68 .Pp
69 These functions are available in the
70 .Nm libpci
71 library.
72 Programs should be linked with
73 .Fl lpci .
74 .Sh CONFIGURATION SPACE FUNCTIONS
75 The following functions are used to access PCI configuration space:
76 .Bl -tag -width 4n
77 .It Fn pcibus_conf_read
78 Access the PCI configuration register
79 .Fa reg
80 on the device located at
81 .Fa bus ,
82 .Fa dev ,
83 .Fa func ,
84 and place the result in
85 .Fa *valp .
86 .Fa pcifd
87 must be an open file descriptor to a PCI bus within the target PCI domain.
88 .It Fn pcibus_conf_write
89 Write the value specified by
90 .Fa val
91 into the PCI configuration register
92 .Fa reg
93 on the device located at
94 .Fa bus ,
95 .Fa dev ,
96 .Fa func .
97 .Fa pcifd
98 must be an open file descriptor to a PCI bus within the target PCI domain.
99 .It Fn pcidev_conf_read
100 Access the PCI configuration register
101 .Fa reg
102 on the device associated with the open file descriptor
103 .Fa devfd
104 and place the result in
105 .Fa *valp .
106 .It Fn pcidev_conf_write
107 Write the value specified by
108 .Fa val
109 into the PCI configuration register
110 .Fa reg
111 on the device associated with the open file descriptor
112 .Fa devfd .
113 .El
114 .Sh MISCELLANEOUS FUNCTIONS
115 The following miscellaneous functions are available:
116 .Bl -tag -width 4n
117 .It Fn pci_findvendor
118 Return an ASCII description of the PCI vendor in the
119 PCI ID register
120 .Fa id_reg .
121 .It Fn pci_devinfo
122 Return an ASCII description of the PCI vendor, PCI product,
123 and PCI class specified by the PCI ID register
124 .Fa id_reg
125 and PCI class ID register
126 .Fa class_reg .
127 The description is placed into the buffer pointed to by
128 .Fa devinfo ;
129 the size of that buffer is specified in
130 .Fa len .
131 If
132 .Fa showclass
133 is not 0, the class, subclass and interface are added into the buffer.
134 .It Fn pci_conf_print
135 Print the PCI configuration information for the device located
136 at
137 .Fa bus ,
138 .Fa dev ,
139 .Fa func .
140 .Fa pcifd
141 must be an open file descriptor to a PCI bus within the target PCI domain.
142 .It Fn pci_drvname
143 For the PCI bus opened on
144 .Fa pcifd ,
145 return the driver name for
146 .Fa dev
147 and
148 .Fa func
149 into
150 .Fa drvname
151 using
152 .Fa len
153 as the buffer length.
154 .El
155 .Sh RETURN VALUES
156 The
157 .Fn pcibus_conf_read ,
158 .Fn pcibus_conf_write ,
159 .Fn pcidev_conf_read ,
160 .Fn pcidev_conf_write ,
161 .Fn pci_devinfo ,
162 and
163 .Fn pci_drvname
164 functions return 0 on success and \-1 on failure.
165 .Pp
166 The
167 .Fn pci_findvendor
168 function returns
169 .Dv NULL
170 if the PCI vendor description cannot be found.
171 .Sh SEE ALSO
172 .Xr pci 4
173 .Sh HISTORY
174 The
175 .Fn pcibus_conf_read ,
176 .Fn pcibus_conf_write ,
177 .Fn pcidev_conf_read ,
178 .Fn pcidev_conf_write ,
179 .Fn pci_findvendor ,
180 .Fn pci_devinfo ,
181 and
182 .Fn pci_conf_print
183 functions first appeared in
184 .Nx 1.6 .
185 The
186 .Fn pci_drvname
187 function first appeared in
188 .Nx 7.0 .