diff options
Diffstat (limited to 'static/freebsd/man4/pci.4 3.html')
| -rw-r--r-- | static/freebsd/man4/pci.4 3.html | 580 |
1 files changed, 0 insertions, 580 deletions
diff --git a/static/freebsd/man4/pci.4 3.html b/static/freebsd/man4/pci.4 3.html deleted file mode 100644 index a892e232..00000000 --- a/static/freebsd/man4/pci.4 3.html +++ /dev/null @@ -1,580 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">PCI(4)</td> - <td class="head-vol">Device Drivers Manual</td> - <td class="head-rtitle">PCI(4)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">pci</code> — <span class="Nd">generic - PCI/PCIe bus driver</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp">To compile the PCI bus driver into the kernel, place the following - line in your kernel configuration file:</p> -<div class="Bd Pp Bd-indent"><code class="Cd">device pci</code></div> -<p class="Pp">To compile in support for Single Root I/O Virtualization - (SR-IOV):</p> -<div class="Bd Pp Bd-indent"><code class="Cd">options PCI_IOV</code></div> -<p class="Pp">To compile in support for native PCI-express HotPlug:</p> -<div class="Bd Pp Bd-indent"><code class="Cd">options PCI_HP</code></div> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">pci</code> driver provides support for PCI - and PCIe devices in the kernel and limited access to PCI devices for - userland.</p> -<p class="Pp">The <code class="Nm">pci</code> driver provides a - <span class="Pa">/dev/pci</span> character device that can be used by - userland programs to read and write PCI configuration registers. Programs - can also use this device to get a list of all PCI devices, or all PCI - devices that match various patterns.</p> -<p class="Pp">Since the <code class="Nm">pci</code> driver provides a write - interface for PCI configuration registers, system administrators should - exercise caution when granting access to the <code class="Nm">pci</code> - device. If used improperly, this driver can allow userland applications to - crash a machine or cause data loss. In particular, driver only allows - operations on the opened <span class="Pa">/dev/pci</span> to modify system - state if the file descriptor was opened for writing. For instance, the - <code class="Dv">PCIOCREAD</code> and <code class="Dv">PCIOCBARMMAP</code> - operations require a writeable descriptor, because reading a config register - or a BAR read access could have function-specific side-effects.</p> -<p class="Pp">The <code class="Nm">pci</code> driver implements the PCI bus in - the kernel. It enumerates any devices on the PCI bus and gives PCI client - drivers the chance to attach to them. It assigns resources to children, when - the BIOS does not. It takes care of routing interrupts when necessary. It - reprobes the unattached PCI children when PCI client drivers are dynamically - loaded at runtime. The <code class="Nm">pci</code> driver also includes - support for PCI-PCI bridges, various platform-specific Host-PCI bridges, and - basic support for PCI VGA adapters.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="IOCTLS"><a class="permalink" href="#IOCTLS">IOCTLS</a></h1> -<p class="Pp">The following <a class="Xr">ioctl(2)</a> calls are supported by - the <code class="Nm">pci</code> driver. They are defined in the header file - <code class="In"><<a class="In">sys/pciio.h</a>></code>.</p> -<dl class="Bl-tag"> - <dt>PCIOCGETCONF</dt> - <dd>This <a class="Xr">ioctl(2)</a> takes a <var class="Va">pci_conf_io</var> - structure. It allows the user to retrieve information on all PCI devices - in the system, or on PCI devices matching patterns supplied by the user. - The call may set <var class="Va">errno</var> to any value specified in - either <a class="Xr">copyin(9)</a> or <a class="Xr">copyout(9)</a>. The - <var class="Va">pci_conf_io</var> structure consists of a number of - fields: - <dl class="Bl-tag"> - <dt>pat_buf_len</dt> - <dd>The length, in bytes, of the buffer filled with user-supplied - patterns.</dd> - <dt>num_patterns</dt> - <dd>The number of user-supplied patterns.</dd> - <dt>patterns</dt> - <dd>Pointer to a buffer filled with user-supplied patterns. - <var class="Va">patterns</var> is a pointer to - <var class="Va">num_patterns</var> - <var class="Va">pci_match_conf</var> structures. The - <var class="Va">pci_match_conf</var> structure consists of the - following elements: - <dl class="Bl-tag"> - <dt>pc_sel</dt> - <dd>PCI domain, bus, slot and function.</dd> - <dt>pd_name</dt> - <dd>PCI device driver name.</dd> - <dt>pd_unit</dt> - <dd>PCI device driver unit number.</dd> - <dt>pc_vendor</dt> - <dd>PCI vendor ID.</dd> - <dt>pc_device</dt> - <dd>PCI device ID.</dd> - <dt>pc_class</dt> - <dd>PCI device class.</dd> - <dt>flags</dt> - <dd>The flags describe which of the fields the kernel should match - against. A device must match all specified fields in order to be - returned. The match flags are enumerated in the - <var class="Va">pci_getconf_flags</var> structure. Hopefully the - flag values are obvious enough that they do not need to described - in detail.</dd> - </dl> - </dd> - <dt>match_buf_len</dt> - <dd>Length of the <var class="Va">matches</var> buffer allocated by the - user to hold the results of the <code class="Dv">PCIOCGETCONF</code> - query.</dd> - <dt>num_matches</dt> - <dd>Number of matches returned by the kernel.</dd> - <dt>matches</dt> - <dd>Buffer containing matching devices returned by the kernel. The items - in this buffer are of type <var class="Va">pci_conf</var>, which - consists of the following items: - <dl class="Bl-tag"> - <dt>pc_sel</dt> - <dd>PCI domain, bus, slot and function.</dd> - <dt>pc_hdr</dt> - <dd>PCI header type.</dd> - <dt>pc_subvendor</dt> - <dd>PCI subvendor ID.</dd> - <dt>pc_subdevice</dt> - <dd>PCI subdevice ID.</dd> - <dt>pc_vendor</dt> - <dd>PCI vendor ID.</dd> - <dt>pc_device</dt> - <dd>PCI device ID.</dd> - <dt>pc_class</dt> - <dd>PCI device class.</dd> - <dt>pc_subclass</dt> - <dd>PCI device subclass.</dd> - <dt>pc_progif</dt> - <dd>PCI device programming interface.</dd> - <dt>pc_revid</dt> - <dd>PCI revision ID.</dd> - <dt>pd_name</dt> - <dd>Driver name.</dd> - <dt>pd_unit</dt> - <dd>Driver unit number.</dd> - <dt>pd_numa_domain</dt> - <dd>Device NUMA domain.</dd> - <dt>pc_reported_len</dt> - <dd>Length of the valid portion of the encompassing - <var class="Vt">pci_conf</var> structure. This should always be - equivalent to the offset of the <var class="Va">pc_spare</var> - member.</dd> - <dt>pc_secbus</dt> - <dd>Secondary PCI bus number. (Only valid for bridge devices)</dd> - <dt>pc_subbus</dt> - <dd>Subordinate PCI bus number. (Only valid for bridge devices)</dd> - <dt>pc_spare</dt> - <dd>Reserved for future use.</dd> - </dl> - </dd> - <dt>offset</dt> - <dd>The offset is passed in by the user to tell the kernel where it should - start traversing the device list. The value passed out by the kernel - points to the record immediately after the last one returned. The user - may pass the value returned by the kernel in subsequent calls to the - <code class="Dv">PCIOCGETCONF</code> ioctl. If the user does not - intend to use the offset, it must be set to zero.</dd> - <dt>generation</dt> - <dd>PCI configuration generation. This value only needs to be set if the - offset is set. The kernel will compare the current generation number - of its internal device list to the generation passed in by the user to - determine whether its device list has changed since the user last - called the <code class="Dv">PCIOCGETCONF</code> ioctl. If the device - list has changed, a status of - <var class="Va">PCI_GETCONF_LIST_CHANGED</var> will be passed - back.</dd> - <dt>status</dt> - <dd>The status tells the user the disposition of his request for a device - list. The possible status values are: - <dl class="Bl-ohang"> - <dt>PCI_GETCONF_LAST_DEVICE</dt> - <dd>This means that there are no more devices in the PCI device list - matching the specified criteria after the ones returned in the - <var class="Va">matches</var> buffer.</dd> - <dt>PCI_GETCONF_LIST_CHANGED</dt> - <dd>This status tells the user that the PCI device list has changed - since his last call to the <code class="Dv">PCIOCGETCONF</code> - ioctl and he must reset the <var class="Va">offset</var> and - <var class="Va">generation</var> to zero to start over at the - beginning of the list.</dd> - <dt>PCI_GETCONF_MORE_DEVS</dt> - <dd>This tells the user that his buffer was not large enough to hold - all of the remaining devices in the device list that match his - criteria.</dd> - <dt id="sizeof">PCI_GETCONF_ERROR</dt> - <dd>This indicates a general error while servicing the user's request. - If the <var class="Va">pat_buf_len</var> is not equal to - <var class="Va">num_patterns</var> times - <a class="permalink" href="#sizeof"><code class="Fn">sizeof</code></a>(<var class="Fa">struct - pci_match_conf</var>), <var class="Va">errno</var> will be set to - <code class="Er">EINVAL</code>.</dd> - </dl> - </dd> - </dl> - </dd> - <dt>PCIOCREAD</dt> - <dd>This <a class="Xr">ioctl(2)</a> reads the PCI configuration registers - specified by the passed-in <var class="Va">pci_io</var> structure. The - <var class="Va">pci_io</var> structure consists of the following fields: - <dl class="Bl-tag"> - <dt>pi_sel</dt> - <dd>A <var class="Va">pcisel</var> structure which specifies the domain, - bus, slot and function the user would like to query. If the specific - bus is not found, errno will be set to ENODEV and -1 returned from the - ioctl.</dd> - <dt>pi_reg</dt> - <dd>The PCI configuration registers the user would like to access.</dd> - <dt>pi_width</dt> - <dd>The width, in bytes, of the data the user would like to read. This - value may be either 1, 2, or 4. 3-byte reads and reads larger than 4 - bytes are not supported. If an invalid width is passed, errno will be - set to EINVAL.</dd> - <dt>pi_data</dt> - <dd>The data returned by the kernel.</dd> - </dl> - </dd> - <dt>PCIOCWRITE</dt> - <dd>This <a class="Xr">ioctl(2)</a> allows users to write to the PCI - configuration registers specified in the passed-in - <var class="Va">pci_io</var> structure. The <var class="Va">pci_io</var> - structure is described above. The limitations on data width described for - reading registers, above, also apply to writing PCI configuration - registers.</dd> - <dt>PCIOCATTACHED</dt> - <dd>This <a class="Xr">ioctl(2)</a> allows users to query if a driver is - attached to the PCI device specified in the passed-in - <var class="Va">pci_io</var> structure. The <var class="Va">pci_io</var> - structure is described above, however, the <var class="Va">pi_reg</var> - and <var class="Va">pi_width</var> fields are not used. The status of the - device is stored in the <var class="Va">pi_data</var> field. A value of 0 - indicates no driver is attached, while a value larger than 0 indicates - that a driver is attached.</dd> - <dt>PCIOCBARMMAP</dt> - <dd>This <a class="Xr">ioctl(2)</a> command allows userspace processes to - <a class="Xr">mmap(2)</a> the memory-mapped PCI BAR into its address - space. The input parameters and results are passed in the - <var class="Va">pci_bar_mmap</var> structure, which has the following - fields: - <dl class="Bl-tag"> - <dt><var class="Vt">void *pbm_map_base</var></dt> - <dd>Reports the established mapping base to the caller. If - <var class="Va">PCIIO_BAR_MMAP_FIXED</var> flag was specified, then - this field must be filled before the call with the desired address for - the mapping.</dd> - <dt><var class="Vt">size_t pbm_map_length</var></dt> - <dd>Reports the mapped length of the BAR, in bytes. Its - <var class="Vt">size_t</var> value is always multiple of machine - pages.</dd> - <dt><var class="Vt">uint64_t pbm_bar_length</var></dt> - <dd>Reports length of the bar as exposed by the device.</dd> - <dt><var class="Vt">int pbm_bar_off</var></dt> - <dd>Reports offset from the mapped base to the start of the first register - in the bar.</dd> - <dt><var class="Vt">struct pcisel pbm_sel</var></dt> - <dd>Should be filled before the call. Describes the device to operate - on.</dd> - <dt><var class="Vt">int pbm_reg</var></dt> - <dd>The BAR index to mmap.</dd> - <dt><var class="Vt">int pbm_flags</var></dt> - <dd>Flags which augments the operation. See below.</dd> - <dt><var class="Vt">int pbm_memattr</var></dt> - <dd>The caching attribute for the mapping. Typical values are - <code class="Dv">VM_MEMATTR_UNCACHEABLE</code> for control registers - BARs, and <code class="Dv">VM_MEMATTR_WRITE_COMBINING</code> for frame - buffers. Regular memory-like BAR should be mapped with - <code class="Dv">VM_MEMATTR_DEFAULT</code> attribute.</dd> - </dl> - <p class="Pp">Currently defined flags are:</p> - <dl class="Bl-tag"> - <dt>PCIIO_BAR_MMAP_FIXED</dt> - <dd>The resulted mappings should be established at the address specified - by the <var class="Va">pbm_map_base</var> member, otherwise fail.</dd> - <dt>PCIIO_BAR_MMAP_EXCL</dt> - <dd>Must be used together with - <code class="Dv">PCIIO_BAR_MMAP_FIXED</code> If the specified base - contains already established mappings, the operation fails instead of - implicitly unmapping them.</dd> - <dt>PCIIO_BAR_MMAP_RW</dt> - <dd>The requested mapping allows both reading and writing. Without the - flag, read-only mapping is established. Note that it is common for the - device registers to have side-effects even on reads.</dd> - <dt>PCIIO_BAR_MMAP_ACTIVATE</dt> - <dd>(Unimplemented) If the BAR is not activated, activate it in the course - of mapping. Currently attempt to mmap an inactive BAR results in - error.</dd> - </dl> - </dd> - <dt>PCIOCBARIO</dt> - <dd>This <a class="Xr">ioctl(2)</a> command allows users to read from and - write to BARs. The I/O request parameters are passed in a - <var class="Va">struct pci_bar_ioreq</var> structure, which has the - following fields: - <dl class="Bl-tag"> - <dt><var class="Vt">struct pcisel pbi_sel</var></dt> - <dd>Describes the device to operate on.</dd> - <dt><var class="Vt">int pbi_op</var></dt> - <dd>The operation to perform. Currently supported values are - <code class="Dv">PCIBARIO_READ</code> and - <code class="Dv">PCIBARIO_WRITE</code>.</dd> - <dt><var class="Vt">uint32_t pbi_bar</var></dt> - <dd>The index of the BAR on which to operate.</dd> - <dt><var class="Vt">uint32_t pbi_offset</var></dt> - <dd>The offset into the BAR at which to operate.</dd> - <dt><var class="Vt">uint32_t pbi_width</var></dt> - <dd>The size, in bytes, of the I/O operation. 1-byte, 2-byte, 4-byte and - 8-byte perations are supported.</dd> - <dt><var class="Vt">uint32_t pbi_value</var></dt> - <dd>For reads, the value is returned in this field. For writes, the caller - specifies the value to be written in this field. - <p class="Pp">Note that this operation maps and unmaps the corresponding - resource and so is relatively expensive for memory BARs. The - <var class="Va">PCIOCBARMMAP</var> <a class="Xr">ioctl(2)</a> can be - used to create a persistent userspace mapping for such BARs - instead.</p> - </dd> - </dl> - </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="LOADER_TUNABLES"><a class="permalink" href="#LOADER_TUNABLES">LOADER - TUNABLES</a></h1> -<p class="Pp">Tunables can be set at the <a class="Xr">loader(8)</a> prompt - before booting the kernel, or stored in <a class="Xr">loader.conf(5)</a>. - The current value of these tunables can be examined at runtime via - <a class="Xr">sysctl(8)</a> nodes of the same name. Unless otherwise - specified, each of these tunables is a boolean that can be enabled by - setting the tunable to a non-zero value.</p> -<dl class="Bl-tag"> - <dt id="hw.pci.clear_bars"><var class="Va">hw.pci.clear_bars</var> (Defaults - to 0)</dt> - <dd>Ignore any firmware-assigned memory and I/O port resources. This forces - the PCI bus driver to allocate resource ranges for memory and I/O port - resources from scratch.</dd> - <dt id="hw.pci.clear_buses"><var class="Va">hw.pci.clear_buses</var> (Defaults - to 0)</dt> - <dd>Ignore any firmware-assigned bus number registers in PCI-PCI bridges. This - forces the PCI bus driver and PCI-PCI bridge driver to allocate bus - numbers for secondary buses behind PCI-PCI bridges.</dd> - <dt id="hw.pci.clear_pcib"><var class="Va">hw.pci.clear_pcib</var> (Defaults - to 0)</dt> - <dd>Ignore any firmware-assigned memory and I/O port resource windows in - PCI-PCI bridges. This forces the PCI-PCI bridge driver to allocate memory - and I/O port resources for resource windows from scratch. - <p class="Pp">By default the PCI-PCI bridge driver will allocate windows - that contain the firmware-assigned resources devices behind the bridge. - In addition, the PCI-PCI bridge driver will suballocate from existing - window regions when possible to satisfy a resource request. As a result, - both <var class="Va">hw.pci.clear_bars</var> and - <var class="Va">hw.pci.clear_pcib</var> must be enabled to fully ignore - firmware-supplied resource assignments.</p> - </dd> - <dt id="hw.pci.default_vgapci_unit"><var class="Va">hw.pci.default_vgapci_unit</var> - (Defaults to -1)</dt> - <dd>By default, the first PCI VGA adapter encountered by the system is assumed - to be the boot display device. This tunable can be set to choose a - specific VGA adapter by specifying the unit number of the associated - <var class="Va">vgapci</var><var class="Ar">X</var> device.</dd> - <dt id="hw.pci.do_power_nodriver"><var class="Va">hw.pci.do_power_nodriver</var> - (Defaults to 0)</dt> - <dd>Place devices into a low power state (D3) when a suitable device driver is - not found. Can be set to one of the following values: - <dl class="Bl-tag"> - <dt>3</dt> - <dd>Powers down all PCI devices without a device driver.</dd> - <dt>2</dt> - <dd>Powers down most devices without a device driver. PCI devices with the - display, memory, and base peripheral device classes are not powered - down.</dd> - <dt>1</dt> - <dd>Similar to a setting of 2 except that storage controllers are also not - powered down.</dd> - <dt>0</dt> - <dd>All devices are left fully powered.</dd> - </dl> - <p class="Pp">A PCI device must support power management to be powered down. - Placing a device into a low power state may not reduce power - consumption.</p> - </dd> - <dt id="hw.pci.do_power_resume"><var class="Va">hw.pci.do_power_resume</var> - (Defaults to 1)</dt> - <dd>Place PCI devices into the fully powered state when resuming either the - system or an individual device. Setting this to zero is discouraged as the - system will not attempt to power up non-powered PCI devices after a - suspend.</dd> - <dt id="hw.pci.do_power_suspend"><var class="Va">hw.pci.do_power_suspend</var> - (Defaults to 1)</dt> - <dd>Place PCI devices into a low power state when suspending either the system - or individual devices. Normally the D3 state is used as the low power - state, but firmware may override the desired power state during a system - suspend.</dd> - <dt id="hw.pci.enable_ari"><var class="Va">hw.pci.enable_ari</var> (Defaults - to 1)</dt> - <dd>Enable support for PCI-express Alternative RID Interpretation. This is - often used in conjunction with SR-IOV.</dd> - <dt id="hw.pci.enable_io_modes"><var class="Va">hw.pci.enable_io_modes</var> - (Defaults to 1)</dt> - <dd>Enable memory or I/O port decoding in a PCI device's command register if - it has firmware-assigned memory or I/O port resources. The firmware (BIOS) - in some systems does not enable memory or I/O port decoding for some - devices even when it has assigned resources to the device. This enables - decoding for such resources during bus probe.</dd> - <dt id="hw.pci.enable_msi"><var class="Va">hw.pci.enable_msi</var> (Defaults - to 1)</dt> - <dd>Enable support for Message Signalled Interrupts (MSI). MSI interrupts can - be disabled by setting this tunable to 0.</dd> - <dt id="hw.pci.enable_msix"><var class="Va">hw.pci.enable_msix</var> (Defaults - to 1)</dt> - <dd>Enable support for extended Message Signalled Interrupts (MSI-X). MSI-X - interrupts can be disabled by setting this tunable to 0.</dd> - <dt id="hw.pci.enable_pcie_ei"><var class="Va">hw.pci.enable_pcie_ei</var> - (Defaults to 0)</dt> - <dd>Enable support for PCI-express Electromechanical Interlock.</dd> - <dt id="hw.pci.enable_pcie_hp"><var class="Va">hw.pci.enable_pcie_hp</var> - (Defaults to 1)</dt> - <dd>Enable support for native PCI-express HotPlug.</dd> - <dt id="hw.pci.honor_msi_blacklist"><var class="Va">hw.pci.honor_msi_blacklist</var> - (Defaults to 1)</dt> - <dd>MSI and MSI-X interrupts are disabled for certain chipsets known to have - broken MSI and MSI-X implementations when this tunable is set. It can be - set to zero to permit use of MSI and MSI-X interrupts if the chipset match - is a false positive.</dd> - <dt id="hw.pci.iov_max_config"><var class="Va">hw.pci.iov_max_config</var> - (Defaults to 1MB)</dt> - <dd>The maximum amount of memory permitted for the configuration parameters - used when creating Virtual Functions via SR-IOV. This tunable can also be - changed at runtime via <a class="Xr">sysctl(8)</a>.</dd> - <dt id="hw.pci.realloc_bars"><var class="Va">hw.pci.realloc_bars</var> - (Defaults to 0)</dt> - <dd>Attempt to allocate a new resource range during the initial device scan - for any memory or I/O port resources with firmware-assigned ranges that - conflict with another active resource.</dd> - <dt id="hw.pci.usb_early_takeover"><var class="Va">hw.pci.usb_early_takeover</var> - (Defaults to 1 on amd64 and i386)</dt> - <dd>Disable legacy device emulation of USB devices during the initial device - scan. Set this tunable to zero to use USB devices via legacy emulation - when using a custom kernel without USB controller drivers.</dd> - <dt id="hw.pci_D_._B_._S_.INT_P_.irq"><var class="Va">hw.pci<D>.<B>.<S>.INT<P>.irq</var></dt> - <dd>These tunables can be used to override the interrupt routing for legacy - PCI INTx interrupts. Unlike other tunables in this list, these do not have - corresponding sysctl nodes. The tunable name includes the address of the - PCI device as well as the pin of the desired INTx IRQ to override: - <dl class="Bl-tag"> - <dt><D></dt> - <dd>The domain (or segment) of the PCI device in decimal.</dd> - <dt><B></dt> - <dd>The bus address of the PCI device in decimal.</dd> - <dt><S></dt> - <dd>The slot of the PCI device in decimal.</dd> - <dt><P></dt> - <dd>The interrupt pin of the PCI slot to override. One of - ‘<code class="Li">A</code>’, - ‘<code class="Li">B</code>’, - ‘<code class="Li">C</code>’, or - ‘<code class="Li">D</code>’.</dd> - </dl> - <p class="Pp">The value of the tunable is the raw IRQ value to use for the - INTx interrupt pin identified by the tunable name. Mapping of IRQ values - to platform interrupt sources is machine dependent.</p> - </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="DEVICE_WIRING"><a class="permalink" href="#DEVICE_WIRING">DEVICE - WIRING</a></h1> -<p class="Pp">You can wire the device unit at a given location with - <a class="Xr">device.hints(5)</a>.</p> -<section class="Ss"> -<h2 class="Ss" id="BSF_Based_Wiring"><a class="permalink" href="#BSF_Based_Wiring">BSF - Based Wiring</a></h2> -<p class="Pp">Devices may be wired to a Bus / Slot / Function (BSF) address. - This is the form reported by <a class="Xr">pciconf(8)</a> Entries of the - form - <var class="Va">hints.<name>.<unit>.at="pci<B>:<S>:<F>"</var> - or - <var class="Va">hints.<name>.<unit>.at="pci<D>:<B>:<S>:<F>"</var> - will force the driver <var class="Va">name</var> to probe and attach at unit - <var class="Va">unit</var> for any PCI device found to match the - specification, where:</p> -<dl class="Bl-tag"> - <dt><D></dt> - <dd>The domain (or segment) of the PCI device in decimal. Defaults to 0 if - unspecified.</dd> - <dt><B></dt> - <dd>The bus address of the PCI device in decimal.</dd> - <dt><S></dt> - <dd>The slot of the PCI device in decimal.</dd> - <dt><F></dt> - <dd>The function of the PCI device in decimal.</dd> -</dl> -<p class="Pp">The code to do the matching requires an exact string match. Do not - specify the angle brackets (< >) in the hints file. Wiring multiple - devices to the same <var class="Va">name</var> and - <var class="Va">unit</var> produces undefined results.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Examples"><a class="permalink" href="#Examples">Examples</a></h2> -<p class="Pp">Given the following lines in - <span class="Pa">/boot/device.hints</span>:</p> -<div class="Bd Pp Li"> -<pre>hint.nvme.3.at="pci6:0:0" -hint.igb.8.at="pci14:0:0"</pre> -</div> -<p class="Pp">If there is a device that supports <a class="Xr">igb(4)</a> at PCI - bus 14 slot 0 function 0, then it will be assigned igb8 for probe and - attach. Likewise, if there is an <a class="Xr">nvme(4)</a> device at PCI bus - 6 slot 0 function 0, then it will be assigned nvme3 for probe and attach. If - another type of card is in either of these locations, the name and unit of - that card will be the default names and will be unaffected by these hints. - If other igb or nvme cards are located elsewhere, they will be assigned - their unit numbers sequentially, skipping the unit numbers that have 'at' - hints.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Location_Based_Wiring"><a class="permalink" href="#Location_Based_Wiring">Location - Based Wiring</a></h2> -<p class="Pp">While simple to locate where to place a device for BSF wiring, the - bus number of that is not invariant. Any number of changes to the devices - within the system can cause this value to vary from boot to boot. The UEFI - Standard defines a device path that's based only on the invariant parts of - the address: The root complex (domain), the slot number and the function. - These paths are hard to construct by hand, please see - <a class="Xr">devctl(8)</a> ‘<code class="Cm">getpath</code>’ - command with a ‘<var class="Ar">UEFI</var>’ locator. The above - example could also be expressed as</p> -<div class="Bd Pp Li"> -<pre>hint.nvme.3.at="PciRoot(0x2)/Pci(0x1,0x3)/Pci(0x0,0x0)/Pci(0x0,0x0)/Pci(0x0,0x0)" -hint.nvme.8.at="PciRoot(0x1)/Pci(0x2,0x2)/Pci(0x0,0x0)/Pci(0x0,0x0)"</pre> -</div> -<p class="Pp">The advantage of this notation is that you can specify the exact - location a device will be at. For deployments of multiple systems with the - same configuration, this can be helpful in managing the devices. However, - even slight variation in motherboards can cause the path to change - substantially. It is also less natural to think of the UEFI Device Paths - since little else will report it.</p> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> -<dl class="Bl-tag Bl-compact"> - <dt><span class="Pa">/dev/pci</span></dt> - <dd>Character device for the <code class="Nm">pci</code> driver.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">device.hints(5)</a> <a class="Xr">pciconf(8)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The <code class="Nm">pci</code> driver (not the kernel's PCI - support code) first appeared in <span class="Ux">FreeBSD 2.2</span>, and was - written by Stefan Esser and Garrett Wollman. Support for device listing and - matching was re-implemented by Kenneth Merry, and first appeared in - <span class="Ux">FreeBSD 3.0</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp"><span class="An">Kenneth Merry</span> - <<a class="Mt" href="mailto:ken@FreeBSD.org">ken@FreeBSD.org</a>></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> -<p class="Pp">It is not possible for users to specify an accurate offset into - the device list without calling the <code class="Dv">PCIOCGETCONF</code> at - least once, since they have no way of knowing the current generation number - otherwise. This probably is not a serious problem, though, since users can - easily narrow their search by specifying a pattern or patterns for the - kernel to match against.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">March 10, 2026</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |