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