diff options
Diffstat (limited to 'share/man/man4/pci.4')
| -rw-r--r-- | share/man/man4/pci.4 | 58 |
1 files changed, 48 insertions, 10 deletions
diff --git a/share/man/man4/pci.4 b/share/man/man4/pci.4 index e9b587dac12c..91fbb557f644 100644 --- a/share/man/man4/pci.4 +++ b/share/man/man4/pci.4 @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd October 4, 2022 +.Dd April 2, 2025 .Dt PCI 4 .Os .Sh NAME @@ -372,16 +372,18 @@ The input parameters and results are passed in the .Va pci_bar_mmap structure, which has the following fields: .Bl -tag -width Vt struct pcise pbm_sel -.It Vt uint64_t pbm_map_base +.It Vt void *pbm_map_base Reports the established mapping base to the caller. If .Va PCIIO_BAR_MMAP_FIXED flag was specified, then this field must be filled before the call with the desired address for the mapping. -.It Vt uint64_t pbm_map_length +.It Vt size_t pbm_map_length Reports the mapped length of the BAR, in bytes. -Its .Vt uint64_t value is always multiple of machine pages. -.It Vt int64_t pbm_bar_length +Its +.Vt size_t +value is always multiple of machine pages. +.It Vt uint64_t pbm_bar_length Reports length of the bar as exposed by the device. .It Vt int pbm_bar_off Reports offset from the mapped base to the start of the @@ -624,7 +626,12 @@ pin identified by the tunable name. Mapping of IRQ values to platform interrupt sources is machine dependent. .El .Sh DEVICE WIRING -You can wire the device unit at a given location with device.hints. +You can wire the device unit at a given location with +.Xr device.hints 5 . +.Ss BSF Based Wiring +Devices may be wired to a Bus / Slot / Function (BSF) address. +This is the form reported by +.Xr pciconf 8 Entries of the form .Va hints.<name>.<unit>.at="pci<B>:<S>:<F>" or @@ -639,7 +646,7 @@ for any PCI device found to match the specification, where: The domain .Pq or segment of the PCI device in decimal. -Defaults to 0 if unspecified +Defaults to 0 if unspecified. .It <B> The bus address of the PCI device in decimal. .It <S> @@ -660,15 +667,18 @@ produces undefined results. .Ss Examples Given the following lines in .Pa /boot/device.hints : -.Cd hint.nvme.3.at="pci6:0:0" -.Cd hint.igb.8.at="pci14:0:0" +.Bd -literal +hint.nvme.3.at="pci6:0:0" +hint.igb.8.at="pci14:0:0" +.Ed +.Pp If there is a device that supports .Xr igb 4 at PCI bus 14 slot 0 function 0, then it will be assigned igb8 for probe and attach. Likewise, if there is an .Xr nvme 4 -card at PCI bus 6 slot 0 function 0, +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 @@ -676,6 +686,33 @@ 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. +.Ss Location Based Wiring +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 +.Xr devctl 8 +.Sq Cm getpath +command with a +.Sq Ar UEFI +locator. +The above example could also be expressed as +.Bd -literal +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)" +.Ed +.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. .Sh FILES .Bl -tag -width /dev/pci -compact .It Pa /dev/pci @@ -684,6 +721,7 @@ Character device for the driver. .El .Sh SEE ALSO +.Xr device.hints 5 .Xr pciconf 8 .Sh HISTORY The |