From nobody Sun Mar 2 05:19:26 2025 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4Z59H33XWPz5hsRH; Sun, 02 Mar 2025 05:19:27 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R10" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Z59H32R2nz46RR; Sun, 02 Mar 2025 05:19:27 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1740892767; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=d/ztPTBCAIdWKiqb+rD+s6UFAZndYSBETYtW62u5pFU=; b=KpjXPCEg2ZrgBOXOe+YxFEC0jyukzk7h8FBsEBe/vgIAf1fR+zg5dh+b652cBs+aI0JDEN +QFj9VycsRk37/En2t8QGtXxxDFPdKIN75X8cl6qsGxSG7PFBao0IEOoie07nL1LoRqvCF f1zdHmv18Nu9ZedjybpVa6BJeNcRKfP7G2KMqvihs+YE2+zF40PZ9Jc2fnoYp1Q4aFsbCE d/LzNvnygoiww2R0ZsX2jBS9O8PLEaaYAlEXMrJubS3hBdREfe0rwe9vxCaazDVVY/f3Wi wq5G3eJxYacilsbLtPGR1NgjVGhk7e5fWsnIssezf0aAQZXXu3Tgz4VI+UtU9w== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1740892767; a=rsa-sha256; cv=none; b=NbnwPp571vTkwiPtanHqj5/vjMvYOhlp7iRUwwUSAHosountkty25vqZDHxIqpjepGqQmV vCODI/VOetFJLhHLq4NHODt/mtJNr5fUg3nhRftT+Fgy+U2lCOZJR7Sw+w7EmTCmb2VTJR hxY3l/vDBWUCVgbLEG8ZauP8i7iJ8sMXVzGKcC+PxtsK2y17gC8xMqNixNzxGodqJg34zG FmSV5eIvqwRy8V3Gcd4ZZS6wSlVtq+OJiTqOJcKU8svNgh1WKtf5MOGsqEAH4aUGOGn+3H P+mjI7Fx0qyZ2GFTunQjTIajqRsTsjy+5zWhm7L0NjeksIs1mREFOXtaQHeGxA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1740892767; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=d/ztPTBCAIdWKiqb+rD+s6UFAZndYSBETYtW62u5pFU=; b=UFuRLT4VGwMWkpXT0tKmGwgzwnasXbOk5VptMXG/L3XhdgW4cz4QmJvwJzYGfT1AiCm0tE bsz3oxa54yNan+xQi31Zk7rJuQo0SkV/qb7LRN2qYgjvk8shOLmJQEatkaR+SgVraGwx94 VKxV3bOFTvtFD9PYjrfzRXq1L+QzBZkqR0H7UsqhhtHKTo/8i6xDV6UJ5x6Se8pjoC5M1C 2KehQCTsg/12w8mxjA6/hLSPClVnL9PzEKAnMzUsYBQ10oXhmzrePVvoc0YaDBh8aKu2h1 oZ8IiAzpgIS5JAviv/UcWm2l15v9dcZzCOZ+yQQ1GyLvwoKBSHyYXVP2Y9U+bQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4Z59H31Nk6zngc; Sun, 02 Mar 2025 05:19:27 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 5225JQgr091656; Sun, 2 Mar 2025 05:19:26 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 5225JQYl091653; Sun, 2 Mar 2025 05:19:26 GMT (envelope-from git) Date: Sun, 2 Mar 2025 05:19:26 GMT Message-Id: <202503020519.5225JQYl091653@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Warner Losh Subject: git: 23da585dd465 - main - pci(4): Give UEFI wiring example List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: imp X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 23da585dd4650bd17d605049779baceb466cf59b Auto-Submitted: auto-generated The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=23da585dd4650bd17d605049779baceb466cf59b commit 23da585dd4650bd17d605049779baceb466cf59b Author: Warner Losh AuthorDate: 2025-03-02 05:19:11 +0000 Commit: Warner Losh 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...at="pci::" 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 The bus address of the PCI device in decimal. .It @@ -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