Commit c44c626e28 for qemu.org

commit c44c626e28f1c87e89decaa73756d081f069b9d3
Author: Stanley Jhu <stanleyjhu@google.com>
Date:   Sun Oct 11 20:20:53 2026 +0800

    docs/system: Add UFS emulation page

    The UFS host controller and logical unit devices have no user
    documentation. Their properties and the way the two devices fit
    together can only be found by reading hw/ufs/.

    Add docs/system/devices/ufs.rst with an example command line, the
    device properties, and current limitations, and list it under the UFS
    entry in MAINTAINERS.

    Signed-off-by: Stanley Jhu <stanleyjhu@google.com>
    Reviewed-by: Jeuk Kim <jeuk20.kim@samsung.com>
    Signed-off-by: Jeuk Kim <jeuk20.kim@samsung.com>

diff --git a/MAINTAINERS b/MAINTAINERS
index 1312bbd1bd..c7f65a5a77 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2758,6 +2758,7 @@ S: Supported
 F: hw/ufs/*
 F: include/block/ufs.h
 F: tests/qtest/ufs-test.c
+F: docs/system/devices/ufs.rst

 megasas
 L: qemu-block@nongnu.org
diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst
index 40054bb7df..a7d247a270 100644
--- a/docs/system/device-emulation.rst
+++ b/docs/system/device-emulation.rst
@@ -96,6 +96,7 @@ Emulated Devices
    devices/net.rst
    devices/nvme.rst
    devices/scsi/index.rst
+   devices/ufs.rst
    devices/usb-u2f.rst
    devices/usb.rst
    devices/vfio-user.rst
diff --git a/docs/system/devices/ufs.rst b/docs/system/devices/ufs.rst
new file mode 100644
index 0000000000..d3482e9299
--- /dev/null
+++ b/docs/system/devices/ufs.rst
@@ -0,0 +1,88 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+=============
+UFS Emulation
+=============
+
+QEMU emulates a Universal Flash Storage (UFS) host controller and the
+logical units behind it. The host controller follows the UFSHCI
+register interface and reports UFS version 4.1 to the guest.
+
+Two devices are involved:
+
+``ufs``
+  The host controller on the PCI bus. A ``sysbus-ufs`` variant exists
+  for boards that place the controller on the system bus; it cannot be
+  created with ``-device``.
+
+``ufs-lu``
+  A logical unit attached to a host controller through ``bus=``. Each
+  logical unit is backed by a block device.
+
+The well-known logical units (REPORT LUNS, UFS Device, Boot and RPMB)
+are created by the host controller and need no configuration.
+
+Adding a UFS Device
+===================
+
+The following adds a host controller with MCQ enabled and one logical
+unit backed by ``ufs.img``:
+
+.. code-block:: console
+
+    -drive file=ufs.img,if=none,id=lu0,format=raw \
+    -device ufs,id=ufs0,serial=0001,mcq=on \
+    -device ufs-lu,drive=lu0,bus=ufs0,lun=0
+
+Add more ``ufs-lu`` devices with different ``lun`` values to create
+more logical units. On top of the architecture defconfig, a Linux
+guest needs ``CONFIG_SCSI_UFSHCD``, ``CONFIG_SCSI_UFSHCD_PCI`` and
+``CONFIG_BLK_DEV_SD``; each logical unit then appears as a SCSI disk.
+
+Host Controller Properties
+==========================
+
+``serial``
+  Serial number string. It is accepted but not reported to the guest
+  yet; the serial number string descriptor reads back empty.
+
+``nutrs`` (default 32, maximum 32)
+  Number of UTP transfer request slots.
+
+``nutmrs`` (default 8, maximum 8)
+  Number of UTP task management request slots advertised to the guest.
+  Task management requests are not processed yet (see Limitations).
+
+``mcq`` (default off)
+  Advertise Multi-Circular Queue (MCQ) support. When off, the guest
+  uses the single doorbell transfer request list.
+
+``mcq-maxq`` (default 2, maximum 31)
+  Number of MCQ submission and completion queue pairs.
+
+``wb-max-size``, ``wb-min-size`` (default 0x400 and 0x100)
+  Maximum and minimum WriteBooster buffer size, in allocation units.
+  ``wb-min-size`` must not exceed ``wb-max-size``.
+
+Logical Unit Properties
+=======================
+
+``drive``
+  Backing block device.
+
+``lun`` (default 0)
+  Logical unit number, 0 to 31. A host controller accepts up to 32
+  logical units.
+
+Limitations
+===========
+
+* UniPro and M-PHY are not modelled. Only the UIC commands needed for
+  link startup, DME attribute access and hibernation are handled; DME
+  reads return fixed values, and DME writes, power mode changes and
+  hibernation do not change any link state.
+* UTP task management requests are not processed, so a guest that
+  tries to abort a command or reset a logical unit gets no completion.
+* The Boot and RPMB well-known logical units only answer basic SCSI
+  commands such as INQUIRY; boot and RPMB data access are not emulated.
+* The device cannot be migrated.