Zephyr UFS Driver Support

This page gives an overview of the UFS Zephyr driver which is available as part of the zephyr-amd repo.

HW Features

  • UFS Host Controller

Design Notes

  • N/A

Implementation

Features Supported

  • Basic UFS Host Controller Driver Initialization

  • raw disk mode - read/write support

  • Filesystem - read/write support

  • Support for PWM, HS Gear speed change.

  • Read/write all device configurations, descriptors, flags

Missing Features

  • Task Management

  • Runtime Error Handling

  • Hibernate

  • RPMB

Known Issues

  • N/A

Limitations

  • LUN info needs to known in device tree for disk/filesystem access.

  • Only 4 KB block size is verified on testing

Kernel Configuration

  • CONFIG_DISK_DRIVER_UFS

  • CONFIG_SCSI

  • CONFIG_UFS_STACK

  • CONFIG_UFSHC

CONFIG_DISK_DRIVER_UFS=y
CONFIG_SCSI=y
CONFIG_UFS_STACK=y
CONFIG_UFSHC=y

Device Tree

Ufs Host Controller Node

ufs0: ufs@f10b0000 {
    compatible = "amd,versal2-ufshc";
    status = "disabled";
    reg =   <0xf10b0000 0x10000>,
            <0xf1060000 0x2000>,
            <0xf1250000 0x100>,
            <0xf1260000 0x100>;
    interrupts = <GIC_SPI 234 IRQ_TYPE_LEVEL IRQ_DEFAULT_PRIORITY>;
    clocks = <&ufs_core_clk>;
    clock-names = "core_clk";
};

  • changes with respect to Linux device tree

    • sclr, efuse, CRP(clock reset power) registers are added

    • ufs disk node is added

Ufs Disk Node

ufs_disk0 {
    compatible = "zephyr,ufs-disk";
    disk-name = "UFS";
    status = "okay";
};

Driver Stack Size

  • 19 KB

    • txt - 13.3 KB, data - 1.2 KB, heap - 1.5 KB

      • scsi.c - txt - 1.12 KB, data - 0 KB

      • ufs.c - txt - 5.41 KB, data - 0 KB, heap - 1.5 KB

        • heap for cmd, transfer descriptors

      • ufshc_amd_versal2.c - txt - 2.21 KB, data - 0.8 KB

      • ufsdisk.c - txt - 4.18 KB, data - 0.18 KB, heap - 4.0 KB

        • heap 4 KB for unaligned read/writes

      • ufs_ops.c - txt - 0.33 KB, data - 0 KB

Test Platform

  • QEMU - Versal Gen 2 QEMU (Versal2_RPU)

  • SPP - Versal Gen 2 SPP (R52, A78)

  • HW - Versal Gen 2, VEK385 (RPU)

Test SoC Architecture

  • RPU - R52 Core - Validated

  • APU - A78 Core - Validated

  • SMP - Switch - Not tested

Testing Sequence

  • Build zephyr application for R52 or A78

    • west build -p -b <board> <sample application path>

  • Run zephyr elf on SPP or QEMU or Versal Gen 2 hardware (RPU)

Example Tests

Test Name

Example Source

Description

UFS API

tests/subsys/ufs/

Performs Driver Init and Query Read Attribute, Flags

SCSI API

tests/subsys/scsi/scsi_ufs/

Performs scsi cmds tests like Test Unit Ready

DISK - UFS

tests/drivers/disk/disk_access/

Performs read/write tests using disk layer.

Driver code coverage with example tests - 69.3%

File

Coverage

scsi.c

71.4%

ufs.c

67.8%

ufshc_amd_versal2.c

75.5%

ufsdisk.c

63.7%

ufs_ops.c

72.5%

Expected Output

  • west build -p -b versal2_rpu /tests/subsys/ufs/ -DCONFIG_HEAP_MEMPOOL_SIZE=8092 -G’Unix Makefiles’

WARNING: Image format was not specified for 'ufs-disk.img' and probing guessed raw.
         Automatically detecting the format is dangerous for raw images, write operations on block 0 will be restricted.
         Specify the 'raw' format explicitly to remove the restrictions.
*** Booting Zephyr OS build xilinx_v2024.2-19-gf25100050944 ***
Running TESTSUITE ufs_stack
===================================================================
START - test0_init
 PASS - test0_init in 0.234 seconds
===================================================================
START - test1_ioctl_desc
Lun id:0, lun_enable:1h
 PASS - test1_ioctl_desc in 0.020 seconds
===================================================================
START - test2_ioctl_attr
bootlun_attrval:1h
 PASS - test2_ioctl_attr in 0.017 seconds
===================================================================
START - test3_ioctl_flag
fdeviceinit_flag:0h
 PASS - test3_ioctl_flag in 0.017 seconds
===================================================================
TESTSUITE ufs_stack succeeded
------ TESTSUITE SUMMARY START ------
SUITE PASS - 100.00% [ufs_stack]: pass = 4, fail = 0, skip = 0, total = 4 duration = 0.288 seconds
 - PASS - [ufs_stack.test0_init] duration = 0.234 seconds
 - PASS - [ufs_stack.test1_ioctl_desc] duration = 0.020 seconds
 - PASS - [ufs_stack.test2_ioctl_attr] duration = 0.017 seconds
 - PASS - [ufs_stack.test3_ioctl_flag] duration = 0.017 seconds
------ TESTSUITE SUMMARY END ------
===================================================================
PROJECT EXECUTION SUCCESSFUL

Performance Metric

  • TBA

Mainline Status

Driver Source Path

  • drivers/ufshc/ufshc_amd_versal2.c

Misra C Report

File

Required

Advisory

Kernel Utility Violations

scsi.c

0

0

13

ufs.c

7

1

149

ufshc_amd_versal2.c

0

12

18

ufsdisk.c

1

1

20

ufs_ops.c

0

0

9

Total violations

8

14

209