UFSHCI(4)

📦
version 15.1 · 2 versions
, in freebsd 15.1, nixpkgs unstable

🎀 NAME 🎀

okay bestie, welcome to UFSHCI(4), straight outta the Kernel Interfaces Manual ✨. This is the page for ufshci — the Universal Flash Storage Host Controller Interface driver. iconic storage energy, no cap.

✨ SYNOPSIS ✨

To compile this driver into the kernel, put this line in the kernel configuration file:

device ufshci

Or, to load the driver as a module at boot, put this line in loader.conf(5):

ufshci_load="YES"

🦋 DESCRIPTION 🦋

Universal Flash Storage (UFS) is a low-power, high-performance storage standard made of a host controller and a single target device. the way it's built different 💅

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) subsystem and its logical unit shows up as the device node /dev/daX. main character device node behavior 😌

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. future-era glow-up in progress 🧚

🌸 HARDWARE 🌸

The ufshci driver supports both host controllers and devices implementing the Universal Flash Storage Host Controller Interface 4.1 and earlier. compatibility slay 🫶

🎀 CONFIGURATION 🎀

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 this tunable value in loader.conf(5):
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 this tunable value in loader.conf(5):
hw.ufshci.min_cpus_per_ioq=X
  • To change the I/O command timeout value (in seconds), set this tunable value in loader.conf(5):
hw.ufshci.timeout_period=X
  • To change the I/O command retry count, set this tunable value in loader.conf(5):
hw.ufshci.retry_count=X
  • To force the driver to use legacy INTx interrupts, set this tunable value in loader.conf(5):
hw.ufshci.force_intx=1
Note: until MCQ support is available the driver always uses legacy INTx, so this value effectively remains 1. iykyk 💀

💅 SYSCTL VARIABLES 💅

The following controller-level sysctl(8) 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.utmrq.num_failures — (R) Number of failed UTP task-management requests.
  • dev.ufshci.0.utmrq.ioq.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 🌈

⭐ HISTORY ⭐

The ufshci driver first appeared in FreeBSD 15.0. era-defining 👑

💜 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>.

that's the whole vibe, bestie 🫶 — source/version says Debian, dated July 17, 2025, and the page is UFSHCI(4). periodt 💅

📦 where this page comes from