Date: Sun, 2 Mar 2025 05:19:26 GMT From: Warner Losh <imp@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org Subject: git: 23da585dd465 - main - pci(4): Give UEFI wiring example Message-ID: <202503020519.5225JQYl091653@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=23da585dd4650bd17d605049779baceb466cf59b commit 23da585dd4650bd17d605049779baceb466cf59b Author: Warner Losh <imp@FreeBSD.org> AuthorDate: 2025-03-02 05:19:11 +0000 Commit: Warner Losh <imp@FreeBSD.org> CommitDate: 2025-03-02 05:19:11 +0000 pci(4): Give UEFI wiring example Sponsored by: Netflix Reviewed by: ziaee Differential Revision: https://reviews.freebsd.org/D49195 --- share/man/man4/pci.4 | 48 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 42 insertions(+), 6 deletions(-) diff --git a/share/man/man4/pci.4 b/share/man/man4/pci.4 index e9b587dac12c..8623eaf3c3b5 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 March 1, 2025 .Dt PCI 4 .Os .Sh NAME @@ -624,7 +624,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 +644,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 +665,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 +684,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 +719,7 @@ Character device for the driver. .El .Sh SEE ALSO +.Xr device.hints 5 .Xr pciconf 8 .Sh HISTORY The
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202503020519.5225JQYl091653>