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>

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

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

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.