--- name: "ufshci" section: "4" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd", "openbsd"] url: "https://new.carta.tech/ufshci" --- # ufshci(4) Universal Flash Storage Host Controller Interface driver ## NAME **ufshci** – Universal Flash Storage Host Controller Interface driver ## SYNOPSIS **device** **ufshci** In [loader.conf(5)](/loader.conf/5.md): **ufshci\_load="YES"** ## DESCRIPTION Universal Flash Storage (UFS) is a low-power, high-performance storage standard composed of a host controller and a single target device. The driver currently provides: - Initialization of the host controller and the target device - Handling of UFS Interconnect (UIC) commands - Support for UTP Transfer Requests (UTR) and UTP Task Management Requests (UTMR) - Support for the SCSI command set - Operation in the legacy single-doorbell queue mode - Support for the PCI Express bus After initialization, the controller is registered with the [cam(4)](/cam/4.md) subsystem and its logical unit appears as the device node */dev/daX*. The driver is under active development; upcoming work includes full UFS 4.1 feature coverage, additional power-management modes, and ACPI/FDT-based attach support. ## HARDWARE The **ufshci** driver supports both host controllers and devices implementing the Universal Flash Storage Host Controller Interface 4.1 and earlier. ## LOADER TUNABLES The **ufshci** driver currently operates with a single doorbell (one I/O-queue), so any tunables that change the queue count are ignored. When Multi-Circular Queue (MCQ) support is added and multiple queues become available, the following queue count tunable values will take effect: To force a single I/O queue pair shared by all CPUs, set the following tunable value in [loader.conf(5)](/loader.conf/5.md): ``` hw.ufshci.per_cpu_io_queues=0 ``` To assign more than one CPU per I/O queue pair, thereby reducing the number of MSI-X vectors consumed by the device, set the following tunable value in [loader.conf(5)](/loader.conf/5.md): ``` hw.ufshci.min_cpus_per_ioq=X ``` To change the I/O command timeout value (in seconds), set the following tunable value in [loader.conf(5)](/loader.conf/5.md): ``` hw.ufshci.timeout_period=X ``` To change the I/O command retry count, set the following tunable value in [loader.conf(5)](/loader.conf/5.md): ``` hw.ufshci.retry_count=X ``` To force the driver to use legacy INTx interrupts, set the following tunable value in [loader.conf(5)](/loader.conf/5.md): ``` hw.ufshci.force_intx=1 ``` **Note:** until MCQ support is available the driver always uses legacy INTx, so this value effectively remains 1. ## SYSCTL VARIABLES The following controller-level [sysctl(8)](/sysctl/8.md) nodes are currently implemented: - *dev.ufshci.0.num\_failures* (R) Number of command failures for the entire controller. - *dev.ufshci.0.num\_retries* (R) Number of command retries for the entire controller. - *dev.ufshci.0.num\_intr\_handler\_calls* (R) Number of times the interrupt handler has been called. - *dev.ufshci.0.num\_cmds* (R) Total number of commands issued by the controller. - *dev.ufshci.0.timeout\_period* (RW) Configured timeout period (in seconds). - *dev.ufshci.0.cap* (R) Host controller capabilities register value. - *dev.ufshci.0.num\_io\_queues* (R) Number of I/O-queue pairs. - *dev.ufshci.0.io\_queue\_mode* (R) Indicates single doorbell mode or multi circular queue mode. - *dev.ufshci.0.minor\_version* (R) Host controller minor version. - *dev.ufshci.0.major\_version* (R) Host controller major version. - *dev.ufshci.0.wb\_enabled* (R) WriteBooster enable/disable. - *dev.ufshci.0.wb\_flush\_enabled* (R) WriteBooster flush enable/disable. - *dev.ufshci.0.wb\_buffer\_type* (R) WriteBooster type. - *dev.ufshci.0.wb\_buffer\_size\_mb* (R) WriteBooster buffer size in MB. - *dev.ufshci.0.wb\_user\_space\_config\_option* (R) WriteBooster preserve user space mode. - *dev.ufshci.0.auto\_hibernation\_supported* (R) Device auto hibernation support. - *dev.ufshci.0.auto\_hibernate\_idle\_timer\_value* (R) Auto-Hibernate Idle Timer Value (in microseconds). - *dev.ufshci.0.power\_mode\_supported* (R) Device power mode support. - *dev.ufshci.0.power\_mode* (R) Current device power mode. - *dev.ufshci.0.tx\_rx\_power\_mode* (R) Current TX/RX PA\_PWRMode value. - *dev.ufshci.0.max\_tx\_lanes* (R) Maximum available TX data lanes. - *dev.ufshci.0.max\_rx\_lanes* (R) Maximum available RX data lanes. - *dev.ufshci.0.tx\_lanes* (R) Active TX data lanes. - *dev.ufshci.0.rx\_lanes* (R) Active RX data lanes. - *dev.ufshci.0.max\_rx\_hs\_gear* (R) Maximum available RX HS gear. - *dev.ufshci.0.hs\_gear* (R) Active HS gear. - *dev.ufshci.0.utmrq.num\_failures* (R) Number of failed UTP task-management requests. - *dev.ufshci.0.utmrq.num\_retries* (R) Number of retried UTP task-management requests. - *dev.ufshci.0.utmrq.num\_intr\_handler\_calls* (R) Number of interrupt handler calls caused by UTP task-management requests. - *dev.ufshci.0.utmrq.num\_cmds* (R) Number of UTP task-management requests issued. - *dev.ufshci.0.utmrq.cq\_head* (R) Current location of the UTP task-management completion queue head. - *dev.ufshci.0.utmrq.sq\_tail* (R) Current location of the UTP task-management submission queue tail. - *dev.ufshci.0.utmrq.sq\_head* (R) Current location of the UTP task-management submission queue head. - *dev.ufshci.0.utmrq.num\_trackers* (R) Number of trackers in the UTP task-management queue. - *dev.ufshci.0.utmrq.num\_entries* (R) Number of entries in the UTP task-management queue. - *dev.ufshci.0.ioq.0.num\_failures* (R) Number of failed UTP transfer requests. - *dev.ufshci.0.ioq.0.num\_retries* (R) Number of retried UTP transfer requests. - *dev.ufshci.0.ioq.0.num\_intr\_handler\_calls* (R) Number of interrupt-handler calls caused by UTP transfer requests. - *dev.ufshci.0.ioq.0.num\_cmds* (R) Number of UTP transfer requests issued. - *dev.ufshci.0.ioq.0.cq\_head* (R) Current location of the UTP transfer completion queue head. - *dev.ufshci.0.ioq.0.sq\_tail* (R) Current location of the UTP transfer submission queue tail. - *dev.ufshci.0.ioq.0.sq\_head* (R) Current location of the UTP transfer submission queue head. - *dev.ufshci.0.ioq.0.num\_trackers* (R) Number of trackers in the UTP transfer queue. - *dev.ufshci.0.ioq.0.num\_entries* (R) Number of entries in the UTP transfer queue. ## SEE ALSO [cam(4)](/cam/4.md), [pci(4)](/pci/4.md), [disk(9)](/disk/9.md) ## HISTORY The **ufshci** driver first appeared in FreeBSD 15.0. ## AUTHORS The **ufshci** driver was developed by Samsung Electronics and originally written by Jaeyoon Choi ⟨*j\_yoon.choi@samsung.com*⟩. This manual page was written by Jaeyoon Choi ⟨*j\_yoon.choi@samsung.com*⟩.