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, 580 insertions, 0 deletions
diff --git a/static/freebsd/man4/pci.4 3.html b/static/freebsd/man4/pci.4 3.html new file mode 100644 index 00000000..a892e232 --- /dev/null +++ b/static/freebsd/man4/pci.4 3.html @@ -0,0 +1,580 @@ +<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> |