path: root/static/freebsd/man4/pci.4 3.html

<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> &#x2014; <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">&lt;<a class="In">sys/pciio.h</a>&gt;</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&lt;D&gt;.&lt;B&gt;.&lt;S&gt;.INT&lt;P&gt;.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>&lt;D&gt;</dt>
      <dd>The domain (or segment) of the PCI device in decimal.</dd>
      <dt>&lt;B&gt;</dt>
      <dd>The bus address of the PCI device in decimal.</dd>
      <dt>&lt;S&gt;</dt>
      <dd>The slot of the PCI device in decimal.</dd>
      <dt>&lt;P&gt;</dt>
      <dd>The interrupt pin of the PCI slot to override. One of
          &#x2018;<code class="Li">A</code>&#x2019;,
          &#x2018;<code class="Li">B</code>&#x2019;,
          &#x2018;<code class="Li">C</code>&#x2019;, or
          &#x2018;<code class="Li">D</code>&#x2019;.</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.&lt;name&gt;.&lt;unit&gt;.at=&quot;pci&lt;B&gt;:&lt;S&gt;:&lt;F&gt;&quot;</var>
    or
    <var class="Va">hints.&lt;name&gt;.&lt;unit&gt;.at=&quot;pci&lt;D&gt;:&lt;B&gt;:&lt;S&gt;:&lt;F&gt;&quot;</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>&lt;D&gt;</dt>
  <dd>The domain (or segment) of the PCI device in decimal. Defaults to 0 if
      unspecified.</dd>
  <dt>&lt;B&gt;</dt>
  <dd>The bus address of the PCI device in decimal.</dd>
  <dt>&lt;S&gt;</dt>
  <dd>The slot of the PCI device in decimal.</dd>
  <dt>&lt;F&gt;</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 (&lt; &gt;) 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=&quot;pci6:0:0&quot;
hint.igb.8.at=&quot;pci14:0:0&quot;</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> &#x2018;<code class="Cm">getpath</code>&#x2019;
    command with a &#x2018;<var class="Ar">UEFI</var>&#x2019; locator. The above
    example could also be expressed as</p>
<div class="Bd Pp Li">
<pre>hint.nvme.3.at=&quot;PciRoot(0x2)/Pci(0x1,0x3)/Pci(0x0,0x0)/Pci(0x0,0x0)/Pci(0x0,0x0)&quot;
hint.nvme.8.at=&quot;PciRoot(0x1)/Pci(0x2,0x2)/Pci(0x0,0x0)/Pci(0x0,0x0)&quot;</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>
    &lt;<a class="Mt" href="mailto:ken@FreeBSD.org">ken@FreeBSD.org</a>&gt;</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>