[RFC QEMU PATCH 01/10] docs: Add documentation for cxl-vcs-switch

[Joshua Lant <joshualant@gmail.com>]

Signed-off-by: Joshua Lant <joshualant@gmail.com>
---
 docs/system/devices/cxl.rst | 90 ++++++++++++++++++++++++++++++++++---
 1 file changed, 85 insertions(+), 5 deletions(-)

diff --git a/docs/system/devices/cxl.rst b/docs/system/devices/cxl.rst
index 32b1b5d773..9e8452e576 100644
--- a/docs/system/devices/cxl.rst
+++ b/docs/system/devices/cxl.rst
@@ -119,11 +119,11 @@ and associated component register access via PCI bars.
 CXL Switch
 ~~~~~~~~~~
 Here we consider a simple CXL switch with only a single
-virtual hierarchy. Whilst more complex devices exist, their
-visibility to a particular host is generally the same as for
-a simple switch design. Hosts often have no awareness
-of complex rerouting and device pooling, they simply see
-devices being hot added or hot removed.
+virtual hierarchy. Whilst more complex devices exist (see VCS
+Switching below), their visibility to a particular host is
+generally the same as for a simple switch design. Hosts often
+have no awareness of complex rerouting and device pooling,
+they simply see devices being hot added or hot removed.
 
 A CXL switch has a similar architecture to those in PCIe,
 with a single upstream port, internal PCI bus and multiple
@@ -467,6 +467,86 @@ Example configuration:
 Guest OS communication with the MCTP CCI can then be established using standard
 MCTP configuration tools.
 
+CXL Multi-VCS Switching
+-----------------------
+
+The cxl-vcs-switch object allows for a Fabric Manager to dynamically reconfigure
+the switching within a multi-upstream port CXL/PCIe topology, This moves beyond
+the static switching configuration described above. The use of vcs=X on an
+endpoint device indicates that it should be hidden from guests at boot. Each
+upstream port with vcs=X set will conceptually become an upstream PPB. Any
+downstream port that is connected to an upstream port with vcs=X set will
+automatically become a vPPB for that VCS. The overall cxl-virtual-switch has a
+single CCI mailbox used for config/status of all ports within the switch.
+Setting local-fm=true indicates that this QEMU instance has the CCI mailbox
+attached. Setting it false will create listeners for commands from a remote
+QEMU process (yet to be implemented).
+
+An example of how the topology is described on the CLI is shown below:
+
+  -object cxl-vcs-switch,id=vcs0,usp-ppbs=2,dsp-ppbs=4,local-fm=true \
+  -device pxb-cxl,bus_nr=12,bus=pcie.0,id=cxl.0,hdm_for_passthrough=true \
+  -device cxl-rp,port=0,bus=cxl.0,id=root_port1,chassis=0,slot=1 \
+  -device pxb-cxl,bus_nr=22,bus=pcie.0,id=cxl.1,hdm_for_passthrough=true \
+  -device cxl-rp,port=0,bus=cxl.1,id=root_port2,chassis=1,slot=1 \
+  -device cxl-upstream,port=0,sn=1234,bus=root_port1,id=us0,addr=0.0,multifunction=on,vcs=vcs0,usppb=0 \
+  -device cxl-upstream,port=0,sn=5678,bus=root_port2,id=us1,addr=0.0,multifunction=on,vcs=vcs0,usppb=1 \
+  -device cxl-switch-mailbox-cci,bus=root_port1,addr=0.3,target=vcs0 \
+  -device usb-cxl-mctp,bus=ehci.0,id=usb0,target=vcs0 \
+  -device cxl-downstream,port=0,bus=us0,id=dsp0,slot=3 \
+  -device cxl-downstream,port=1,bus=us0,id=dsp1,slot=4 \
+  -device cxl-downstream,port=0,bus=us1,id=dsp2,slot=7 \
+  -device cxl-downstream,port=1,bus=us1,id=dsp3,slot=8 \
+  -device cxl-type3,persistent-memdev=cxl-mem1,id=cxl-ep1,lsa=cxl-lsa1,sn=99,vcs=vcs0,dsppb=0 \
+  -device cxl-type3,persistent-memdev=cxl-mem2,id=cxl-ep2,lsa=cxl-lsa2,sn=100,vcs=vcs0,dsppb=1 \
+  -device cxl-type3,persistent-memdev=cxl-mem3,id=cxl-ep3,lsa=cxl-lsa3,sn=101,vcs=vcs0,dsppb=2 \
+  -device cxl-type3,persistent-memdev=cxl-mem4,id=cxl-ep4,lsa=cxl-lsa4,sn=102,vcs=vcs0,dsppb=3 \
+  -machine cxl-fmw.0.targets.0=cxl.0,cxl-fmw.0.size=8G,cxl-fmw.1.targets.0=cxl.1,cxl-fmw.1.size=8G
+
+Example topology involving VCS switching::
+
+               +--------------------+  +--------------------+
+               |   Host Bridge 0    |  |   Host Bridge 1    |
+               +----------+---------+  +----------+---------+
+    +-------+             |                       |
+    | MCTP  |             |                       |
+    | USB/  |  +----------+---------+  +----------+---------+
+    | I2C   |  |    Root Port 0     |  |    Root Port 1     |
+    +-----+-+  +----------+---------+  +----------+---------+
+          |               |                       |
+          |               |                       |
+   +------|---------------+-----------------------+-----------------------+
+   |    +-+--------+      |  cxl-vcs-switch (vcs0)|                       |
+   | +--| CCI MBOX |---*  |                       |                       |
+   | |  +----------+      |                       |                       |
+   | |  +-----------------+--------+      +-------+------------------+    |
+   | +--+                 |   VCS0 |  *---+       |             VCS1 |    |
+   |    | +---------------+------+ |      | +-----+----------------+ |    |
+   |    | |                      | |      | |                      | |    |
+   |    | |        USP 0         | |      | |        USP 1         | |    |
+   |    | |                      | |      | |                      | |    |
+   |    | +----+------------+----+ |      | +----+------------+----+ |    |
+   |    |      |            |      |      |      |            |      |    |
+   |    | +----+----+  +----+----+ |      | +----+----+  +----+----+ |    |
+   |    | |  DSP 0  |  |  DSP 1  | |      | |  DSP 2  |  |  DSP 3  | |    |
+   |    | |(vPPB 0) |  |(vPPB 1) | |      | |(vPPB 0) |  |(vPPB 1) | |    |
+   |    | |         |  |         | |      | |         |  |         | |    |
+   |    | +---------+  +---------+ |      | +---------+  +----+----+ |    |
+   |    +--------------------------+      +-------------------+------+    |
+   |                                                          |           |
+   |           +----------------------------------------------+           |
+   |           |                                                          |
+   |           |            -                    -            -           |
+   +-----------|------------|--------------------|------------|-----------+
+               |            |                    |            |
+          +---------+  +---------+          +---------+  +---------+
+          |CXL/PCIe |  |CXL/PCIe |          |CXL/PCIe |  |CXL/PCIe |
+          |  EP 0   |  |  EP 1   |          |  EP 2   |  |  EP 3   |
+          | (PPB0)  |  | (PPB1)  |          | (PPB2)  |  | (PPB3)  |
+          +---------+  +---------+          +---------+  +---------+
+                 PPB0 Bound to VCS1, vPPB1. Others unbound...
+
+
 References
 ----------
 
-- 
2.47.3