[PATCH qemu v1 8/8] cxl: Add documentation for CXL UIO support

[Shrihari E S <shrihari.s@samsung.com>]

Add a section for the UIO related device options, and a
command-line example demonstrating a topology with three CXL Type-3
devices connected via a switch, with Unordered I/O (UIO) enabled on
all ports and endpoints. The example shows the correct usage of
the x-svc, x-256b-flit and x-uio options, including the x-uio option
of the pxb-cxl host bridge, which marks all the root ports within
the host bridge as capable of routing UIO requests.

The x-uio option of the CXL type3 device works together with x-svc
and x-256b-flit: the device carries the UIO capability when all
three are set.

Signed-off-by: Shrihari E S <shrihari.s@samsung.com>
Signed-off-by: Dongjoo Seo <dongjoo.seo1@samsung.com>
---
 docs/system/devices/cxl.rst | 54 ++++++++++++++++++++++++++++++++++---
 1 file changed, 51 insertions(+), 3 deletions(-)

diff --git a/docs/system/devices/cxl.rst b/docs/system/devices/cxl.rst
index 32b1b5d773..e2d66b0e4e 100644
--- a/docs/system/devices/cxl.rst
+++ b/docs/system/devices/cxl.rst
@@ -394,12 +394,12 @@ use HDM-DB for coherence, which requires operating in Flit mode::
   -object memory-backend-ram,id=cxl-mem2,share=on,size=256M \
   -object memory-backend-ram,id=cxl-mem3,share=on,size=256M \
   -device pxb-cxl,bus_nr=12,bus=pcie.0,id=cxl.1 \
-  -device cxl-rp,port=0,bus=cxl.1,id=root_port0,chassis=0,slot=0 \
+  -device cxl-rp,port=0,bus=cxl.1,id=root_port0,chassis=0,slot=0,x-256b-flit=on \
   -device cxl-rp,port=1,bus=cxl.1,id=root_port1,chassis=0,slot=1 \
   -device cxl-upstream,bus=root_port0,id=us0,x-256b-flit=on \
-  -device cxl-downstream,port=0,bus=us0,id=swport0,chassis=0,slot=4 \
+  -device cxl-downstream,port=0,bus=us0,id=swport0,chassis=0,slot=4,x-256b-flit=on \
   -device cxl-type3,bus=swport0,volatile-memdev=cxl-mem0,id=cxl-mem0,sn=0x1,x-256b-flit=on,hdm-db=on \
-  -device cxl-downstream,port=1,bus=us0,id=swport1,chassis=0,slot=5 \
+  -device cxl-downstream,port=1,bus=us0,id=swport1,chassis=0,slot=5,x-256b-flit=on \
   -device cxl-type3,bus=swport1,volatile-memdev=cxl-mem1,id=cxl-mem1,sn=0x2,x-256b-flit=on,hdm-db=on \
   -device cxl-downstream,port=2,bus=us0,id=swport2,chassis=0,slot=6 \
   -device cxl-type3,bus=swport2,volatile-memdev=cxl-mem2,id=cxl-mem2,sn=0x3 \
@@ -407,6 +407,54 @@ use HDM-DB for coherence, which requires operating in Flit mode::
   -device cxl-type3,bus=swport3,volatile-memdev=cxl-mem3,id=cxl-mem3,sn=0x4 \
   -M cxl-fmw.0.targets.0=cxl.1,cxl-fmw.0.size=4G,cxl-fmw.0.interleave-granularity=4k
 
+Unordered I/O (UIO) Support
+---------------------------
+CXL 3.2 and PCIe 6.1 introduce Unordered I/O (UIO), which allows memory
+transactions to bypass strict ordering requirements, potentially improving
+performance for certain workloads. UIO support builds on three
+coordinated features:
+
+1. **256-byte Flit Mode**: Enabled via ``x-256b-flit=on`` on all ports
+   and devices in the UIO path
+2. **Streamlined Virtual Channel (SVC)**: Enabled via ``x-svc`` on all ports
+   and CXL type3 device. SVC is a PCIe extended capability
+   (PCIe 6.4 section 7.9.29) that provides dedicated virtual channels for
+   UIO traffic.
+3. **Device 3 Extended Capability**: Enabled via ``x-uio`` on the CXL type3
+   device. Device 3 is a PCIe extended capability (PCIe 6.4 section 7.7.9)
+   that advertises a device's UIO requester/completer support. ``x-uio``
+   works together with the ``x-svc`` and ``x-256b-flit`` options: the
+   device carries the UIO capability when all three are set.
+
+``x-uio`` is also accepted by the ``pxb-cxl`` host bridge: it sets the
+UIO Capable bit of the host bridge HDM decoder capability. Each root
+port within the host bridge completes the advertisement, reporting the
+UIO Capable bit of its own HDM decoder capability when the host bridge
+carries ``x-uio`` and its own ``x-svc`` and ``x-256b-flit`` options
+are set.
+
+An example of 3 type3 devices with volatile memory below a switch. All the
+devices and ports support the Unordered IO (UIO) feature, which builds on
+the Streamlined Virtual Channel (SVC) capability, the Device 3 capability
+and 256-byte flit mode::
+
+  qemu-system-x86_64 -M q35,cxl=on -m 4G,maxmem=8G,slots=8 -smp 4 \
+  ...
+  -object memory-backend-ram,id=target-mem1,size=512M \
+  -object memory-backend-ram,id=target-mem2,size=512M \
+  -object memory-backend-ram,id=target-mem3,size=512M \
+  -device pxb-cxl,bus_nr=12,bus=pcie.0,id=cxl.1,x-uio=on \
+  -device cxl-rp,port=0,bus=cxl.1,id=rp13,chassis=0,slot=0,x-svc=on,x-256b-flit=on,x-speed=64,x-width=16 \
+  -device cxl-rp,port=1,bus=cxl.1,id=root_port1,chassis=0,slot=1,x-svc=on,x-256b-flit=on,x-speed=64,x-width=16 \
+  -device cxl-upstream,port=2,sn=1234,bus=rp13,id=us0,x-svc=on,x-256b-flit=on,x-speed=64,x-width=16 \
+  -device cxl-downstream,port=0,bus=us0,id=swport0,chassis=0,slot=4,x-svc=on,x-256b-flit=on,x-speed=64,x-width=16 \
+  -device cxl-downstream,port=1,bus=us0,id=swport1,chassis=0,slot=5,x-svc=on,x-256b-flit=on,x-speed=64,x-width=16 \
+  -device cxl-downstream,port=2,bus=us0,id=swport2,chassis=0,slot=6,x-svc=on,x-256b-flit=on,x-speed=64,x-width=16 \
+  -device cxl-type3,id=mem1,bus=swport0,volatile-memdev=target-mem1,x-uio=on,x-svc=on,x-256b-flit=on,sn=1233 \
+  -device cxl-type3,id=mem2,bus=swport1,volatile-memdev=target-mem2,x-uio=on,x-svc=on,x-256b-flit=on,sn=1234 \
+  -device cxl-type3,id=mem3,bus=swport2,volatile-memdev=target-mem3,x-uio=on,x-svc=on,x-256b-flit=on,sn=1235 \
+  -M cxl-fmw.0.targets.0=cxl.1,cxl-fmw.0.size=4G,cxl-fmw.0.interleave-granularity=4k
+
 A simple arm/virt example featuring a single direct connected CXL Type 3
 Volatile Memory device::
 
-- 
2.34.1