1.\" 2.\" Copyright (c) 2025, Samsung Electronics Co., Ltd. 3.\" 4.\" SPDX-License-Identifier: BSD-2-Clause 5.\" 6.\" ufshci driver man page. 7.\" 8.\" Author: Jaeyoon Choi <j_yoon.choi@samsung.com> 9.\" 10.Dd July 17, 2025 11.Dt UFSHCI 4 12.Os 13.Sh NAME 14.Nm ufshci 15.Nd Universal Flash Storage Host Controller Interface driver 16.Sh SYNOPSIS 17To compile this driver into the kernel, 18place the following line in the kernel configuration file: 19.Bd -ragged -offset indent 20.Cd "device ufshci" 21.Ed 22.Pp 23Or, to load the driver as a module at boot, place the following line in 24.Xr loader.conf 5 : 25.Bd -literal -offset indent 26ufshci_load="YES" 27.Ed 28.Sh DESCRIPTION 29Universal Flash Storage (UFS) is a low-power, high-performance storage 30standard composed of a host controller and a single target device. 31.Pp 32The driver currently provides: 33.Bl -bullet 34.It 35Initialization of the host controller and the target device 36.It 37Handling of UFS Interconnect (UIC) commands 38.It 39Support for UTP Transfer Requests (UTR) and UTP Task Management Requests (UTMR) 40.It 41Support for the SCSI command set 42.It 43Operation in the legacy single-doorbell queue mode 44.It 45Support for the PCI Express bus 46.El 47.Pp 48After initialization, the controller is registered with the 49.Xr cam 4 50subsystem and its logical unit appears as the device node 51.Pa /dev/daX . 52.Pp 53The driver is under active development; upcoming work includes full 54UFS 4.1 feature coverage, additional power-management modes, and 55ACPI/FDT-based attach support. 56.Sh HARDWARE 57The 58.Nm 59driver supports both host controllers and devices implementing the 60Universal Flash Storage Host Controller Interface 4.1 and earlier. 61.Sh CONFIGURATION 62The 63.Nm 64driver currently operates with a single doorbell (one I/O-queue), so any 65tunables that change the queue count are ignored. 66When Multi-Circular Queue (MCQ) support is added and multiple queues 67become available, the following queue count tunable values will take effect: 68.Pp 69To force a single I/O queue pair shared by all CPUs, set the following 70tunable value in loader.conf(5): 71.Bd -literal -offset indent 72hw.ufshci.per_cpu_io_queues=0 73.Ed 74.Pp 75To assign more than one CPU per I/O queue pair, thereby reducing the 76number of MSI-X vectors consumed by the device, set the following tunable 77value in loader.conf(5): 78.Bd -literal -offset indent 79hw.ufshci.min_cpus_per_ioq=X 80.Ed 81.Pp 82To change the I/O command timeout value (in seconds), set the following tunable 83value in loader.conf(5): 84.Bd -literal -offset indent 85hw.ufshci.timeout_period=X 86.Ed 87.Pp 88To change the I/O command retry count, set the following tunable value in 89loader.conf(5): 90.Bd -literal -offset indent 91hw.ufshci.retry_count=X 92.Ed 93.Pp 94To force the driver to use legacy INTx interrupts, set the following tunable 95value in loader.conf(5): 96.br 97(Note: until MCQ support is available the driver always uses legacy INTx, so 98this value effectively remains 1) 99.Bd -literal -offset indent 100hw.ufshci.force_intx=1 101.Ed 102.Sh SYSCTL VARIABLES 103The following controller-level 104.Xr sysctl 8 105nodes are currently implemented: 106.Bl -tag -width indent 107.It Va dev.ufshci.0.num_failures 108(R) Number of command failures for the entire controller. 109.It Va dev.ufshci.0.num_retries 110(R) Number of command retries for the entire controller. 111.It Va dev.ufshci.0.num_intr_handler_calls 112(R) Number of times the interrupt handler has been called. 113.It Va dev.ufshci.0.num_cmds 114(R) Total number of commands issued by the controller. 115.It Va dev.ufshci.0.timeout_period 116(RW) Configured timeout period (in seconds). 117.It Va dev.ufshci.0.cap 118(R) Host controller capabilities register value. 119.It Va dev.ufshci.0.num_io_queues 120(R) Number of I/O-queue pairs. 121.It Va dev.ufshci.0.io_queue_mode 122(R) Indicates single doorbell mode or multi circular queue mode. 123.It Va dev.ufshci.0.minor_version 124(R) Host controller minor version. 125.It Va dev.ufshci.0.major_version 126(R) Host controller major version. 127.It Va dev.ufshci.0.utmrq.num_failures 128(R) Number of failed UTP task-management requests. 129.It Va dev.ufshci.0.utmrq.ioq.num_retries 130(R) Number of retried UTP task-management requests. 131.It Va dev.ufshci.0.utmrq.num_intr_handler_calls 132(R) Number of interrupt handler calls caused by UTP task-management requests. 133.It Va dev.ufshci.0.utmrq.num_cmds 134(R) Number of UTP task-management requests issued. 135.It Va dev.ufshci.0.utmrq.cq_head 136(R) Current location of the UTP task-management completion queue head. 137.It Va dev.ufshci.0.utmrq.sq_tail 138(R) Current location of the UTP task-management submission queue tail. 139.It Va dev.ufshci.0.utmrq.sq_head 140(R) Current location of the UTP task-management submission queue head. 141.It Va dev.ufshci.0.utmrq.num_trackers 142(R) Number of trackers in the UTP task-management queue. 143.It Va dev.ufshci.0.utmrq.num_entries 144(R) Number of entries in the UTP task-management queue. 145.It Va dev.ufshci.0.ioq.0.num_failures 146(R) Number of failed UTP transfer requests. 147.It Va dev.ufshci.0.ioq.0.num_retries 148(R) Number of retried UTP transfer requests. 149.It Va dev.ufshci.0.ioq.0.num_intr_handler_calls 150(R) Number of interrupt-handler calls caused by UTP transfer requests. 151.It Va dev.ufshci.0.ioq.0.num_cmds 152(R) Number of UTP transfer requests issued. 153.It Va dev.ufshci.0.ioq.0.cq_head 154(R) Current location of the UTP transfer completion queue head. 155.It Va dev.ufshci.0.ioq.0.sq_tail 156(R) Current location of the UTP transfer submission queue tail. 157.It Va dev.ufshci.0.ioq.0.sq_head 158(R) Current location of the UTP transfer submission queue head. 159.It Va dev.ufshci.0.ioq.0.num_trackers 160(R) Number of trackers in the UTP transfer queue. 161.It Va dev.ufshci.0.ioq.0.num_entries 162(R) Number of entries in the UTP transfer queue. 163.El 164.Sh SEE ALSO 165.Xr cam 4 , 166.Xr pci 4 , 167.Xr disk 9 168.Sh HISTORY 169The 170.Nm 171driver first appeared in 172.Fx 15.0 . 173.Sh AUTHORS 174.An -nosplit 175The 176.Nm 177driver was developed by Samsung Electronics and originally written by 178.An Jaeyoon Choi Aq Mt j_yoon.choi@samsung.com . 179.Pp 180This manual page was written by 181.An Jaeyoon Choi Aq Mt j_yoon.choi@samsung.com . 182