Re: [PATCH] scsi: ufs: docs: Describe how to test with QEMU

[Bean Huo]

Stanley, 

Thanks, this is very useful, a few comments as below:

On Sun, 2026-10-11 at 18:33 +0800, Stanley Jhu wrote:
> QEMU emulates a UFS host controller and logical units, but the kernel
> tree does not mention it, so developers without UFS hardware have no
> documented way to exercise the UFS core.
> 
> Add a short section with the required kernel options, an example QEMU
> command line, and what the emulation does not cover.
> 
> Signed-off-by: Stanley Jhu <stanleyjhu@xxxxxxxxxx>
> ---
>  Documentation/scsi/ufs.rst | 33 +++++++++++++++++++++++++++++++++
>  1 file changed, 33 insertions(+)
> 
> diff --git a/Documentation/scsi/ufs.rst b/Documentation/scsi/ufs.rst
> index a7b2b2ed1c3a..1ff1c8218bf1 100644
> --- a/Documentation/scsi/ufs.rst
> +++ b/Documentation/scsi/ufs.rst
> @@ -19,6 +19,7 @@ Universal Flash Storage
>       3.4 SCSI Error handling
>     4. BSG Support
>     5. UFS Reference Clock Frequency configuration
> +   6. Testing with QEMU
>  
>  
>  1. Overview
> @@ -208,3 +209,35 @@ the UFS specification. UFS subsystem will attempt to read
> the value when
>  executing common controller initialization. If the value is available, UFS
>  subsystem will ensure the bRefClkFreq attribute of the UFS storage device is
>  set accordingly and will modify it if there is a mismatch.
> +
> +6. Testing with QEMU
> +====================
> +
> +QEMU emulates a UFS host controller as a PCI device named "ufs" and
> +logical units named "ufs-lu". This can be used to test changes to the
> +UFS core and to ufshcd-pci without UFS hardware.
> +

should here state the minimum QEMU version for the ufs device, and for mcq=on,
since the older version QEMU may not have them or one of them.

> +Enable the following kernel options on top of the architecture
> +defconfig::
> +
> +       CONFIG_SCSI_UFSHCD=y
> +       CONFIG_SCSI_UFSHCD_PCI=y
> +       CONFIG_BLK_DEV_SD=y
> +
> +Example for an arm64 guest with one 1 GiB logical unit::
> +
> +       qemu-img create -f raw ufs.img 1G
> +       qemu-system-aarch64 -M virt -cpu max -smp 4 -m 2G -nographic \
> +               -kernel arch/arm64/boot/Image -initrd rootfs.cpio.gz \
> +               -append "console=ttyAMA0" \
> +               -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
> +
> +The logical unit appears as a SCSI disk (/dev/sda).

maybe here adds "for example"-> The logical unit appears as a SCSI disk (for
example /dev/sda)

> Drop "mcq=on" to
> +test the single doorbell mode instead of MCQ. The same -device options
> +work with qemu-system-x86_64.
> +
> +The emulation does not model UniPro, M-PHY, power mode changes,

I am cconfused by this statement, since I checked QEMU, the latest QEMU accepts
some UIC commands such as hibern8 enter/exit, if I am correct, here "accepts but
does not model" would be more precise, you can check  hw/ufs/ufs.c:

static void ufs_process_uiccmd(UfsHc *u, uint32_t val)

> +hibernation or clock gating hardware, and vendor host drivers are not
> +exercised. Changes in those areas still need testing on real hardware.


Kind regards,
Bean