From: Stanley Jhu <[email protected]> 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 <[email protected]> Reviewed-by: Jeuk Kim <[email protected]> Signed-off-by: Jeuk Kim <[email protected]> --- 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 1312bbd1bd8..c7f65a5a779 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: [email protected] diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst index 40054bb7dfc..a7d247a270e 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 00000000000..d3482e92992 --- /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.43.0
