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

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

[Stanley Jhu]

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@google.com>
---
 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.
+
+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). 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,
+hibernation or clock gating hardware, and vendor host drivers are not
+exercised. Changes in those areas still need testing on real hardware.
-- 
2.56.0.385.gd3acb90ef8-goog

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

[Alim Akhtar]

> -----Original Message-----
> From: Stanley Jhu <stanleyjhu@google.com>
> Sent: Sunday, October 11, 2026 4:03 PM
> To: Martin K. Petersen <mkp@kernel.org>; James E.J. Bottomley
> <James.Bottomley@HansenPartnership.com>; Jonathan Corbet
> <corbet@lwn.net>
> Cc: Bart Van Assche <bvanassche@acm.org>; Alim Akhtar
> <alim.akhtar@samsung.com>; Shuah Khan <skhan@linuxfoundation.org>;
> Randy Dunlap <rdunlap@infradead.org>; Jeuk Kim
> <jeuk20.kim@samsung.com>; Bean Huo <beanhuo@iokpp.de>; linux-
> scsi@vger.kernel.org; linux-doc@vger.kernel.org; linux-
> kernel@vger.kernel.org
> Subject: [PATCH] scsi: ufs: docs: Describe how to test with QEMU
> 
> 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@google.com>
> ---
Thanks Stanley!
This helps

Reviewed-by: Alim Akhtar <alim.akhtar@samsung.com>

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@google.com>
> ---
>  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