1.\" $NetBSD: pci.3,v 1.14 2017/10/22 15:28:48 abhinav 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 September 23, 2016 37.Dt PCI 3 38.Os 39.Sh NAME 40.Nm pci , 41.Nm pcibus_conf_read , 42.Nm pcibus_conf_write , 43.Nm pcidev_conf_read , 44.Nm pcidev_conf_write , 45.Nm pci_findvendor , 46.Nm pci_devinfo , 47.Nm pci_conf_print , 48.Nm pci_drvname , 49.Nm pci_drvnameonbus 50.Nd library interface for PCI bus access 51.Sh LIBRARY 52.Lb libpci 53.Sh SYNOPSIS 54.In pci.h 55.Ft int 56.Fn pcibus_conf_read "int pcifd" "unsigned int bus" "unsigned int dev" "unsigned int func" \ 57"unsigned int reg" "pcireg_t *valp" 58.Ft int 59.Fn pcibus_conf_write "int pcifd" "unsigned int bus" "unsigned int dev" "unsigned int func" \ 60"unsigned int reg" "pcireg_t val" 61.Ft int 62.Fn pcidev_conf_read "int devfd" "unsigned int reg" "pcireg_t *valp" 63.Ft int 64.Fn pcidev_conf_write "int devfd" "unsigned int reg" "pcireg_t val" 65.Ft char * 66.Fn pci_findvendor "pcireg_t id_reg" 67.Ft void 68.Fn pci_devinfo "pcireg_t id_reg" "pcireg_t class_reg" "int showclass" "char *devinfo" "size_t len" 69.Ft void 70.Fn pci_conf_print "int pcifd" "unsigned int bus" "unsigned int dev" "unsigned int func" 71.Ft int 72.Fn pci_drvname "int pcifd" "unsigned int dev" "unsigned int func" "char *drvname" "size_t len" 73.Ft int 74.Fn pci_drvnameonbus "int pcifd" "u_int bus" "u_int dev" "u_int func" "char *drvname" "size_t len" 75.Sh DESCRIPTION 76The 77.Nm 78library provides support for accessing the PCI bus by user programs. 79.Pp 80These functions are available in the 81.Nm libpci 82library. 83Programs should be linked with 84.Fl lpci . 85.Sh CONFIGURATION SPACE FUNCTIONS 86The following functions are used to access PCI configuration space: 87.Bl -tag -width 4n 88.It Fn pcibus_conf_read 89Access the PCI configuration register 90.Fa reg 91on the device located at 92.Fa bus , 93.Fa dev , 94.Fa func , 95and place the result in 96.Fa *valp . 97.Fa pcifd 98must be an open file descriptor to a PCI bus within the target PCI domain. 99.It Fn pcibus_conf_write 100Write the value specified by 101.Fa val 102into the PCI configuration register 103.Fa reg 104on the device located at 105.Fa bus , 106.Fa dev , 107.Fa func . 108.Fa pcifd 109must be an open file descriptor to a PCI bus within the target PCI domain. 110.It Fn pcidev_conf_read 111Access the PCI configuration register 112.Fa reg 113on the device associated with the open file descriptor 114.Fa devfd 115and place the result in 116.Fa *valp . 117.It Fn pcidev_conf_write 118Write the value specified by 119.Fa val 120into the PCI configuration register 121.Fa reg 122on the device associated with the open file descriptor 123.Fa devfd . 124.El 125.Sh MISCELLANEOUS FUNCTIONS 126The following miscellaneous functions are available: 127.Bl -tag -width 4n 128.It Fn pci_findvendor 129Return an ASCII description of the PCI vendor in the 130PCI ID register 131.Fa id_reg . 132.It Fn pci_devinfo 133Return an ASCII description of the PCI vendor, PCI product, 134and PCI class specified by the PCI ID register 135.Fa id_reg 136and PCI class ID register 137.Fa class_reg . 138The description is placed into the buffer pointed to by 139.Fa devinfo ; 140the size of that buffer is specified in 141.Fa len . 142If 143.Fa showclass 144is not 0, the class, subclass and interface are added into the buffer. 145.It Fn pci_conf_print 146Print the PCI configuration information for the device located 147at 148.Fa bus , 149.Fa dev , 150.Fa func . 151.Fa pcifd 152must be an open file descriptor to a PCI bus within the target PCI domain. 153.It Fn pci_drvname 154For the PCI bus opened on 155.Fa pcifd , 156return the driver name for 157.Fa dev 158and 159.Fa func 160into 161.Fa drvname 162using 163.Fa len 164as the buffer length. 165.It Fn pci_drvnameonbus 166Just like 167.Fn pci_drvname 168but also allows looking up via PCI bus number. 169.El 170.Sh RETURN VALUES 171The 172.Fn pcibus_conf_read , 173.Fn pcibus_conf_write , 174.Fn pcidev_conf_read , 175.Fn pcidev_conf_write , 176.Fn pci_devinfo , 177and 178.Fn pci_drvname 179functions return 0 on success and \-1 on failure. 180.Pp 181The 182.Fn pci_findvendor 183function returns 184.Dv NULL 185if the PCI vendor description cannot be found. 186.Sh SEE ALSO 187.Xr pci 4 188.Sh HISTORY 189The 190.Fn pcibus_conf_read , 191.Fn pcibus_conf_write , 192.Fn pcidev_conf_read , 193.Fn pcidev_conf_write , 194.Fn pci_findvendor , 195.Fn pci_devinfo , 196and 197.Fn pci_conf_print 198functions first appeared in 199.Nx 1.6 . 200The 201.Fn pci_drvname 202function first appeared in 203.Nx 7.0 . 204