2 .\" Copyright (c) 1999 Kenneth D. Merry.
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. The name of the author may not be used to endorse or promote products
11 .\" derived from this software without specific prior written permission.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .Nd generic PCI bus driver
34 To compile the PCI bus driver into the kernel,
35 place the following line in your
36 kernel configuration file:
37 .Bd -ragged -offset indent
41 To compile in support for Single Root I/O Virtualization
43 .Bd -ragged -offset indent
47 To compile in support for native PCI-express HotPlug:
48 .Bd -ragged -offset indent
54 driver provides support for
56 devices in the kernel and limited access to
64 character device that can be used by userland programs to read and write
66 configuration registers.
67 Programs can also use this device to get a list of all
71 devices that match various patterns.
75 driver provides a write interface for
77 configuration registers, system administrators should exercise caution when
78 granting access to the
81 If used improperly, this driver can allow userland applications to
82 crash a machine or cause data loss.
89 It enumerates any devices on the
93 client drivers the chance to attach to them.
94 It assigns resources to children, when the BIOS does not.
95 It takes care of routing interrupts when necessary.
96 It reprobes the unattached
100 client drivers are dynamically
104 driver also includes support for PCI-PCI bridges,
105 various platform-specific Host-PCI bridges,
106 and basic support for
112 calls are supported by the
115 They are defined in the header file
117 .Bl -tag -width 012345678901234
124 It allows the user to retrieve information on all
126 devices in the system, or on
128 devices matching patterns supplied by the user.
131 to any value specified in either
137 structure consists of a number of fields:
138 .Bl -tag -width match_buf_len
140 The length, in bytes, of the buffer filled with user-supplied patterns.
142 The number of user-supplied patterns.
144 Pointer to a buffer filled with user-supplied patterns.
152 structure consists of the following elements:
153 .Bl -tag -width pd_vendor
156 domain, bus, slot and function.
162 device driver unit number.
173 The flags describe which of the fields the kernel should match against.
174 A device must match all specified fields in order to be returned.
175 The match flags are enumerated in the
176 .Va pci_getconf_flags
178 Hopefully the flag values are obvious enough that they do not need to
184 buffer allocated by the user to hold the results of the
188 Number of matches returned by the kernel.
190 Buffer containing matching devices returned by the kernel.
191 The items in this buffer are of type
193 which consists of the following items:
194 .Bl -tag -width pc_subvendor
197 domain, bus, slot and function.
221 device programming interface.
231 The offset is passed in by the user to tell the kernel where it should
232 start traversing the device list.
233 The value passed out by the kernel
234 points to the record immediately after the last one returned.
236 pass the value returned by the kernel in subsequent calls to the
239 If the user does not intend to use the offset, it must be set to zero.
242 configuration generation.
243 This value only needs to be set if the offset is set.
244 The kernel will compare the current generation number of its internal
245 device list to the generation passed in by the user to determine whether
246 its device list has changed since the user last called the
249 If the device list has changed, a status of
250 .Va PCI_GETCONF_LIST_CHANGED
253 The status tells the user the disposition of his request for a device list.
254 The possible status values are:
256 .It PCI_GETCONF_LAST_DEVICE
257 This means that there are no more devices in the PCI device list matching
258 the specified criteria after the
262 .It PCI_GETCONF_LIST_CHANGED
263 This status tells the user that the
265 device list has changed since his last call to the
267 ioctl and he must reset the
271 to zero to start over at the beginning of the list.
272 .It PCI_GETCONF_MORE_DEVS
273 This tells the user that his buffer was not large enough to hold all of the
274 remaining devices in the device list that match his criteria.
275 .It PCI_GETCONF_ERROR
276 This indicates a general error while servicing the user's request.
282 .Fn sizeof "struct pci_match_conf" ,
293 configuration registers specified by the passed-in
298 structure consists of the following fields:
299 .Bl -tag -width pi_width
303 structure which specifies the domain, bus, slot and function the user would
305 If the specific bus is not found, errno will be set to ENODEV and -1 returned
310 configuration register the user would like to access.
312 The width, in bytes, of the data the user would like to read.
314 may be either 1, 2, or 4.
315 3-byte reads and reads larger than 4 bytes are
317 If an invalid width is passed, errno will be set to EINVAL.
319 The data returned by the kernel.
324 allows users to write to the
326 specified in the passed-in
331 structure is described above.
332 The limitations on data width described for
333 reading registers, above, also apply to writing
335 configuration registers.
338 Tunables can be set at the
340 prompt before booting the kernel, or stored in
342 The current value of these tunables can be examined at runtime via
344 nodes of the same name.
345 Unless otherwise specified,
346 each of these tunables is a boolean that can be enabled by setting the
347 tunable to a non-zero value.
348 .Bl -tag -width indent
349 .It Va hw.pci.clear_bars Pq Defaults to 0
350 Ignore any firmware-assigned memory and I/O port resources.
353 bus driver to allocate resource ranges for memory and I/O port resources
355 .It Va hw.pci.clear_buses Pq Defaults to 0
356 Ignore any firmware-assigned bus number registers in PCI-PCI bridges.
359 bus driver and PCI-PCI bridge driver to allocate bus numbers for secondary
360 buses behind PCI-PCI bridges.
361 .It Va hw.pci.clear_pcib Pq Defaults to 0
362 Ignore any firmware-assigned memory and I/O port resource windows in PCI-PCI
364 This forces the PCI-PCI bridge driver to allocate memory and I/O port resources
365 for resource windows from scratch.
367 By default the PCI-PCI bridge driver will allocate windows that
368 contain the firmware-assigned resources devices behind the bridge.
369 In addition, the PCI-PCI bridge driver will suballocate from existing window
370 regions when possible to satisfy a resource request.
373 .Va hw.pci.clear_bars
375 .Va hw.pci.clear_pcib
376 must be enabled to fully ignore firmware-supplied resource assignments.
377 .It Va hw.pci.default_vgapci_unit Pq Defaults to -1
381 VGA adapter encountered by the system is assumed to be the boot display device.
382 This tunable can be set to choose a specific VGA adapter by specifying the
383 unit number of the associated
386 .It Va hw.pci.do_power_nodriver Pq Defaults to 0
387 Place devices into a low power state
389 when a suitable device driver is not found.
390 Can be set to one of the following values:
391 .Bl -tag -width indent
395 devices without a device driver.
397 Powers down most devices without a device driver.
398 PCI devices with the display, memory, and base peripheral device classes
399 are not powered down.
401 Similar to a setting of 2 except that storage controllers are also not
404 All devices are left fully powered.
409 device must support power management to be powered down.
410 Placing a device into a low power state may not reduce power consumption.
411 .It Va hw.pci.do_power_resume Pq Defaults to 1
414 devices into the fully powered state when resuming either the system or an
416 Setting this to zero is discouraged as the system will not attempt to power
417 up non-powered PCI devices after a suspend.
418 .It Va hw.pci.do_power_suspend Pq Defaults to 1
421 devices into a low power state when suspending either the system or individual
423 Normally the D3 state is used as the low power state,
424 but firmware may override the desired power state during a system suspend.
425 .It Va hw.pci.enable_ari Pq Defaults to 1
426 Enable support for PCI-express Alternative RID Interpretation.
427 This is often used in conjunction with SR-IOV.
428 .It Va hw.pci.enable_io_modes Pq Defaults to 1
429 Enable memory or I/O port decoding in a PCI device's command register if it has
430 firmware-assigned memory or I/O port resources.
433 in some systems does not enable memory or I/O port decoding for some devices
434 even when it has assigned resources to the device.
435 This enables decoding for such resources during bus probe.
436 .It Va hw.pci.enable_msi Pq Defaults to 1
437 Enable support for Message Signalled Interrupts
439 MSI interrupts can be disabled by setting this tunable to 0.
440 .It Va hw.pci.enable_msix Pq Defaults to 1
441 Enable support for extended Message Signalled Interrupts
443 MSI-X interrupts can be disabled by setting this tunable to 0.
444 .It Va hw.pci.enable_pcie_hp Pq Defaults to 1
445 Enable support for native PCI-express HotPlug.
446 .It Va hw.pci.honor_msi_blacklist Pq Defaults to 1
447 MSI and MSI-X interrupts are disabled for certain chipsets known to have
448 broken MSI and MSI-X implementations when this tunable is set.
449 It can be set to zero to permit use of MSI and MSI-X interrupts if the
450 chipset match is a false positive.
451 .It Va hw.pci.iov_max_config Pq Defaults to 1MB
452 The maximum amount of memory permitted for the configuration parameters
453 used when creating Virtual Functions via SR-IOV.
454 This tunable can also be changed at runtime via
456 .It Va hw.pci.realloc_bars Pq Defaults to 0
457 Attempt to allocate a new resource range during the initial device scan
458 for any memory or I/O port resources with firmware-assigned ranges that
459 conflict with another active resource.
460 .It Va hw.pci.usb_early_takeover Pq Defaults to 1 on Tn amd64 and Tn i386
461 Disable legacy device emulation of USB devices during the initial device
463 Set this tunable to zero to use USB devices via legacy emulation when
464 using a custom kernel without USB controller drivers.
465 .It Va hw.pci<D>.<B>.<S>.INT<P>.irq
466 These tunables can be used to override the interrupt routing for legacy
468 Unlike other tunables in this list,
469 these do not have corresponding sysctl nodes.
470 The tunable name includes the address of the PCI device as well as the
471 pin of the desired INTx IRQ to override:
472 .Bl -tag -width indent
476 of the PCI device in decimal.
478 The bus address of the PCI device in decimal.
480 The slot of the PCI device in decimal.
482 The interrupt pin of the PCI slot to override.
491 The value of the tunable is the raw IRQ value to use for the INTx interrupt
492 pin identified by the tunable name.
493 Mapping of IRQ values to platform interrupt sources is machine dependent.
496 You can wire the device unit at a given location with device.hints.
498 .Va hints.<name>.<unit>.at="pci<B>:<S>:<F>"
500 .Va hints.<name>.<unit>.at="pci<D>:<B>:<S>:<F>"
501 will force the driver
503 to probe and attach at unit
505 for any PCI device found to match the specification, where:
506 .Bl -tag -width -indent
510 of the PCI device in decimal.
511 Defaults to 0 if unspecified
513 The bus address of the PCI device in decimal.
515 The slot of the PCI device in decimal.
517 The function of the PCI device in decimal.
520 The code to do the matching requires an exact string match.
521 Do not specify the angle brackets
524 Wiring multiple devices to the same
528 produces undefined results.
530 Given the following lines in
531 .Pa /boot/device.hints :
532 .Cd hint.nvme.3.at="pci6:0:0"
533 .Cd hint.igb.8.at="pci14:0:0"
534 If there is a device that supports
536 at PCI bus 14 slot 0 function 0,
537 then it will be assigned igb8 for probe and attach.
538 Likewise, if there is an
540 card at PCI bus 6 slot 0 function 0,
541 then it will be assigned nvme3 for probe and attach.
542 If another type of card is in either of these locations, the name and
543 unit of that card will be the default names and will be unaffected by
545 If other igb or nvme cards are located elsewhere, they will be
546 assigned their unit numbers sequentially, skipping the unit numbers
547 that have 'at' hints.
549 .Bl -tag -width /dev/pci -compact
551 Character device for the
560 driver (not the kernel's
562 support code) first appeared in
564 and was written by Stefan Esser and Garrett Wollman.
565 Support for device listing and matching was re-implemented by
566 Kenneth Merry, and first appeared in
569 .An Kenneth Merry Aq Mt ken@FreeBSD.org
571 It is not possible for users to specify an accurate offset into the device
572 list without calling the
574 at least once, since they have no way of knowing the current generation
576 This probably is not a serious problem, though, since
577 users can easily narrow their search by specifying a pattern or patterns
578 for the kernel to match against.