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>
---
 MAINTAINERS                      |  1 +
 docs/system/device-emulation.rst |  1 +
 docs/system/devices/ufs.rst      | 88 ++++++++++++++++++++++++++++++++
 3 files changed, 90 insertions(+)
 create mode 100644 docs/system/devices/ufs.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index 1312bbd1b..c7f65a5a7 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 40054bb7d..a7d247a27 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 000000000..d3482e929
--- /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.
-- 
2.56.0.385.gd3acb90ef8-goog

> 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>
> ---
>  MAINTAINERS                      |  1 +
>  docs/system/device-emulation.rst |  1 +
>  docs/system/devices/ufs.rst      | 88 ++++++++++++++++++++++++++++++++
>  3 files changed, 90 insertions(+)
>  create mode 100644 docs/system/devices/ufs.rst
>
> 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.

Thank you for writing this UFS guide.

Reviewed-by: Jeuk Kim <jeuk20.kim@samsung.com>

-- 
Jeuk Kim <jeuk20.kim@samsung.com>