From: Paul M Stillwell Jr <paul.m.stillwell.jr@intel.com>
To: linux-pci@vger.kernel.org
Cc: Paul M Stillwell Jr <paul.m.stillwell.jr@intel.com>
Subject: [PATCH v2] Documentation: PCI: add vmd documentation
Date: Tue, 30 Apr 2024 13:30:07 -0700 [thread overview]
Message-ID: <20240430203007.113-1-paul.m.stillwell.jr@intel.com> (raw)
Adding documentation for the Intel VMD driver and updating the index
file to include it.
Signed-off-by: Paul M Stillwell Jr <paul.m.stillwell.jr@intel.com>
---
v1->v2:
- updated documentation to add commit message from initial patch
submission
- small changes based on community feedback
---
Documentation/PCI/controller/vmd.rst | 74 ++++++++++++++++++++++++++++
Documentation/PCI/index.rst | 1 +
2 files changed, 75 insertions(+)
create mode 100644 Documentation/PCI/controller/vmd.rst
diff --git a/Documentation/PCI/controller/vmd.rst b/Documentation/PCI/controller/vmd.rst
new file mode 100644
index 000000000000..ff4851f9a62d
--- /dev/null
+++ b/Documentation/PCI/controller/vmd.rst
@@ -0,0 +1,74 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+=================================================================
+Linux Base Driver for the Intel(R) Volume Management Device (VMD)
+=================================================================
+
+Intel vmd Linux driver.
+
+Contents
+========
+
+The Intel Volume Management Device (VMD) is a Root Complex Integrated
+Endpoint that acts as a host bridge to a secondary PCIe domain. The BIOS
+can enable or disable VMD. Additioanlly the BIOS can reassign one or more
+Root Ports to appear within a VMD domain instead of the primary domain.
+The immediate benefit is that additional PCIe domains allow more than 256
+buses in a system by letting bus numbers be reused across different domains.
+
+VMD domains do not define ACPI _SEG, so to avoid domain clashing with host
+bridges defining this segment, VMD domains start at 0x10000, which is
+greater than the highest possible 16-bit ACPI defined _SEG.
+
+This driver enumerates and enables the domain using the root bus
+configuration interface provided by the PCI subsystem. The driver provides
+configuration space accessor functions (pci_ops), bus and memory resources,
+an MSI IRQ domain with irq_chip implementation, and DMA operations
+necessary to use devices through the VMD endpoint's interface.
+
+VMD routes I/O as follows:
+
+ 1) Configuration Space: BAR 0 ("CFGBAR") of VMD provides the base
+ address and size for configuration space register access to VMD-owned
+ root ports. It works similarly to MMCONFIG for extended configuration
+ space. Bus numbering is independent and does not conflict with the
+ primary domain.
+
+ 2) MMIO Space: BARs 2 and 4 ("MEMBAR1" and "MEMBAR2") of VMD provide the
+ base address, size, and type for MMIO register access. These addresses
+ are not translated by VMD hardware; they are simply reservations to be
+ distributed to root ports' memory base/limit registers and subdivided
+ among devices downstream.
+
+ 3) DMA: To interact appropriately with an IOMMU, the source ID DMA read
+ and write requests are translated to the bus-device-function of the VMD
+ endpoint. Otherwise, DMA operates normally without VMD-specific address
+ translation.
+
+ 4) Interrupts: Part of VMD's BAR 4 is reserved for VMD's MSI-X Table and
+ PBA. MSIs from VMD domain devices and ports are remapped to appear as
+ if they were issued using one of VMD's MSI-X table entries. Each MSI
+ and MSI-X address of VMD-owned devices and ports has a special format
+ where the address refers to specific entries in the VMD's MSI-X table.
+ As with DMA, the interrupt source ID is translated to VMD's
+ bus-device-function.
+
+ The driver provides its own MSI and MSI-X configuration functions
+ specific to how MSI messages are used within the VMD domain, and
+ provides an irq_chip for independent IRQ allocation to relay interrupts
+ from VMD's interrupt handler to the appropriate device driver's handler.
+
+ 5) Errors: PCIe error message are intercepted by the root ports normally
+ (e.g., AER), except with VMD, system errors (i.e. firmware first) are
+ disabled by default. AER and hotplug interrupts are translated in the
+ same way as endpoint interrupts.
+
+ 6) VMD does not support INTx interrupts or IO ports. Devices or drivers
+ requiring these features should either not be placed below VMD-owned
+ root ports, or VMD should be disabled by BIOS for such endpoints.
+
+The driver can run on both a host and a guest. The BIOS provides a mechanism
+to specify which VMD devices should be passed through to a guest and the
+hypervisor can select that device by specifying the bus-device-function. The
+device that is passed through to a guest is not seen by the driver on the
+host.
\ No newline at end of file
diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
index e73f84aebde3..6558adc703f9 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -18,3 +18,4 @@ PCI Bus Subsystem
pcieaer-howto
endpoint/index
boot-interrupts
+ controller/vmd
--
2.39.1
reply other threads:[~2024-04-30 20:30 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240430203007.113-1-paul.m.stillwell.jr@intel.com \
--to=paul.m.stillwell.jr@intel.com \
--cc=linux-pci@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).