STRUCT UFS_HBA(9)

✨ NAME ✨

okay so welcome to struct ufs_hba(9) from the Kernel API Manual, bestie 💖 this is the per adapter private structure — and yes, she is large. Like, main-character-energy large. Not me already being obsessed with how much private state one adapter can hold 🫶.

🌸 SYNOPSIS 🌸

here's the struct in all its exact, character-for-character glory — code is the one thing we do not remix, periodt:

struct ufs_hba {
    void __iomem *mmio_base;
    struct utp_transfer_cmd_desc *ucdl_base_addr;
    struct utp_transfer_req_desc *utrdl_base_addr;
    struct utp_task_req_desc *utmrdl_base_addr;
    struct utp_devman_cmd_desc *devman_ucd_base_addr;
    dma_addr_t ucdl_dma_addr;
    dma_addr_t utrdl_dma_addr;
    dma_addr_t utmrdl_dma_addr;
    dma_addr_t devman_ucd_dma_addr;
    struct Scsi_Host *host;
    struct device *dev;
    struct scsi_device *ufs_device_wlun;
    struct scsi_device *ufs_rpmb_wlun;
  #ifdef CONFIG_SCSI_UFS_HWMON;
    struct device *hwmon_device;
  #endif;
    enum ufs_dev_pwr_mode curr_dev_pwr_mode;
    enum uic_link_state uic_link_state;
    enum ufs_pm_level rpm_lvl;
    enum ufs_pm_level spm_lvl;
    enum ufs_pm_level pm_lvl_min;
    int pm_op_in_progress;
    u32 ahit;
    unsigned long outstanding_tasks;
    spinlock_t outstanding_lock;
    unsigned long outstanding_reqs;
    u32 capabilities;
    int nutrs;
    int nortt;
    u32 mcq_capabilities;
    int nutmrs;
    u32 ufs_version;
    const struct ufs_hba_variant_ops *vops;
    struct ufs_hba_variant_params *vps;
    void *priv;
  #ifdef CONFIG_SCSI_UFS_VARIABLE_SG_ENTRY_SIZE;
    size_t sg_entry_size;
  #endif;
    unsigned int irq;
    bool is_irq_enabled;
    enum ufs_ref_clk_freq dev_ref_clk_freq;
    unsigned int quirks;
    unsigned int dev_quirks;
    struct blk_mq_tag_set tmf_tag_set;
    struct request_queue *tmf_queue;
    struct request **tmf_rqs;
    struct uic_command *active_uic_cmd;
    struct mutex uic_cmd_mutex;
    struct completion *uic_async_done;
    enum ufshcd_state ufshcd_state;
    u32 eh_flags;
    u32 intr_mask;
    u16 ee_ctrl_mask;
    u16 ee_drv_mask;
    u16 ee_usr_mask;
    struct mutex ee_ctrl_mutex;
    bool is_powered;
    bool shutting_down;
    struct semaphore host_sem;
    struct workqueue_struct *eh_wq;
    struct work_struct eh_work;
    struct work_struct eeh_work;
    u32 errors;
    u32 uic_error;
    u32 saved_err;
    u32 saved_uic_err;
    struct ufs_stats ufs_stats;
    bool force_reset;
    bool silence_err_logs;
    struct ufs_dev_cmd dev_cmd;
    ktime_t last_dme_cmd_tstamp;
    int nop_out_timeout;
    struct ufs_dev_info dev_info;
    bool auto_bkops_enabled;
    struct ufs_vreg_info vreg_info;
    struct list_head clk_list_head;
    bool use_pm_opp;
    int req_abort_count;
    u32 lanes_per_direction;
    struct ufs_pa_layer_attr pwr_info;
    struct ufs_pwr_mode_info max_pwr_info;
    struct ufs_clk_gating clk_gating;
    u32 caps;
    struct devfreq *devfreq;
    struct ufs_clk_scaling clk_scaling;
    bool is_sys_suspended;
    enum bkops_status urgent_bkops_lvl;
    bool is_urgent_bkops_lvl_checked;
    struct mutex wb_mutex;
    struct rw_semaphore clk_scaling_lock;
    struct device           bsg_dev;
    struct request_queue    *bsg_queue;
    struct delayed_work rpm_dev_flush_recheck_work;
    struct ufs_hba_monitor  monitor;
  #ifdef CONFIG_SCSI_UFS_CRYPTO;
    union ufs_crypto_capabilities crypto_capabilities;
    union ufs_crypto_cap_entry *crypto_cap_array;
    u32 crypto_cfg_register;
    struct blk_crypto_profile crypto_profile;
  #endif;
  #ifdef CONFIG_DEBUG_FS;
    struct dentry *debugfs_root;
    struct delayed_work debugfs_ee_work;
    u32 debugfs_ee_rate_limit_ms;
  #endif;
  #ifdef CONFIG_SCSI_UFS_FAULT_INJECTION;
    struct fault_attr trigger_eh_attr;
    struct fault_attr timeout_attr;
  #endif;
    u32 luns_avail;
    unsigned int nr_hw_queues;
    unsigned int nr_queues[HCTX_MAX_TYPES];
    bool complete_put;
    bool scsi_host_added;
    bool mcq_sup;
    bool lsdb_sup;
    bool mcq_enabled;
    bool mcq_esi_enabled;
    void __iomem *mcq_base;
    struct ufs_hw_queue *uhq;
    struct ufshcd_mcq_opr_info_t mcq_opr[OPR_MAX];
    struct delayed_work ufs_rtc_update_work;
    struct pm_qos_request pm_qos_req;
    bool pm_qos_enabled;
    struct mutex pm_qos_mutex;
    int critical_health_count;
    atomic_t dev_lvl_exception_count;
    u64 dev_lvl_exception_id;
    atomic_t dme_qos_notification;
    struct kernfs_node *dme_qos_sysfs_handle;
    u32 vcc_off_delay_us;
    struct list_head rpmbs;
    u8 host_preshoot_cap;
    u8 host_deemphasis_cap;
    u8 device_preshoot_cap;
    u8 device_deemphasis_cap;
    struct ufshcd_tx_eq_params tx_eq_params[UFS_HS_GEAR_MAX];
};

✨ Members ✨

okay bestie, deep breath — this is the big one. every single field of struct ufs_hba, in order, no skips, no shortcuts. it's a lot but you're gonna eat 💅

• mmio_base — UFSHCI base register address. the front door of the whole controller 🏠
• ucdl_base_addr — UFS Command Descriptor base address
• utrdl_base_addr — UTP Transfer Request Descriptor base address
• utmrdl_base_addr — UTP Task Management Descriptor base address
• devman_ucd_base_addr — UFS Command Descriptor base address for the reserved device management tag (has a larger response area) 👀
• ucdl_dma_addr — UFS Command Descriptor DMA address
• utrdl_dma_addr — UTRDL DMA address
• utmrdl_dma_addr — UTMRDL DMA address
• devman_ucd_dma_addr — UFS Command Descriptor DMA address for the reserved device management tag
• host — Scsi_Host instance of the driver
• dev — device handle
• ufs_device_wlun — WLUN that controls the entire UFS device. main character WLUN ngl 👑
• ufs_rpmb_wlun — RPMB WLUN SCSI device
• hwmon_device — device instance registered with the hwmon core.
• curr_dev_pwr_mode — active UFS device power mode.
• uic_link_state — active state of the link to the UFS device.
• rpm_lvl — desired UFS power management level during runtime PM.
• spm_lvl — desired UFS power management level during system PM.
• pm_lvl_min — minimum supported power management level.
• pm_op_in_progress — whether or not a PM operation is in progress.
• ahit — value of Auto-Hibernate Idle Timer register.
• outstanding_tasks — Bits representing outstanding task requests
• outstanding_lock — Protects outstanding_reqs.
• outstanding_reqs — Bits representing outstanding transfer requests
• capabilities — UFS Controller Capabilities
• nutrs — Transfer Request Queue depth supported by controller
• nortt — Max outstanding RTTs supported by controller
• mcq_capabilities — UFS Multi Circular Queue capabilities
• nutmrs — Task Management Queue depth supported by controller
• ufs_version — UFS Version to which controller complies
• vops — pointer to variant specific operations
• vps — pointer to variant specific parameters
• priv — pointer to variant specific private data
• sg_entry_size — size of struct ufshcd_sg_entry (may include variant fields)
• irq — Irq number of the controller
• is_irq_enabled — whether or not the UFS controller interrupt is enabled.
• dev_ref_clk_freq — reference clock frequency
• quirks — bitmask with information about deviations from the UFSHCI standard.
• dev_quirks — bitmask with information about deviations from the UFS standard.
• tmf_tag_set — TMF tag set.
• tmf_queue — Used to allocate TMF tags.
• tmf_rqs — array with pointers to TMF requests while these are in progress.
• active_uic_cmd — pointer to active UIC command.
• uic_cmd_mutex — mutex used for serializing UIC command processing.
• uic_async_done — completion used to wait for power mode or hibernation state changes.
• ufshcd_state — UFSHCD state
• eh_flags — Error handling flags
• intr_mask — Interrupt Mask Bits
• ee_ctrl_mask — Exception event control mask
• ee_drv_mask — Exception event mask for driver
• ee_usr_mask — Exception event mask for user (set via debugfs)
• ee_ctrl_mutex — Used to serialize exception event information.
• is_powered — flag to check if HBA is powered
• shutting_down — flag to check if shutdown has been invoked
• host_sem — semaphore used to serialize concurrent contexts
• eh_wq — Workqueue that eh_work works on
• eh_work — Worker to handle UFS errors that require s/w attention
• eeh_work — Worker to handle exception events
• errors — HBA errors
• uic_error — UFS interconnect layer error status
• saved_err — sticky error mask
• saved_uic_err — sticky UIC error mask
• ufs_stats — various error counters
• force_reset — flag to force eh_work perform a full reset
• silence_err_logs — flag to silence error logs 🤫
• dev_cmd — ufs device management command information
• last_dme_cmd_tstamp — time stamp of the last completed DME command
• nop_out_timeout — NOP OUT timeout value
• dev_info — information about the UFS device
• auto_bkops_enabled — to track whether bkops is enabled in device
• vreg_info — UFS device voltage regulator information
• clk_list_head — UFS host controller clocks list node head
• use_pm_opp — Indicates whether OPP based scaling is used or not
• req_abort_count — number of times ufshcd_abort has been called
• lanes_per_direction — number of lanes per data direction between the UFS controller and the UFS device.
• pwr_info — holds current power mode
• max_pwr_info — keeps the device max valid pwm
• clk_gating — information related to clock gating
• caps — bitmask with information about UFS controller capabilities
• devfreq — frequency scaling information owned by the devfreq core
• clk_scaling — frequency scaling information owned by the UFS driver
• is_sys_suspended — UFS device has been suspended because of system suspend
• urgent_bkops_lvl — keeps track of urgent bkops level for device
• is_urgent_bkops_lvl_checked — keeps track if the urgent bkops level for device is known or not.
• wb_mutex — used to serialize devfreq and sysfs write booster toggling
• clk_scaling_lock — used to serialize device commands and clock scaling
• bsg_dev — struct device associated with the BSG queue
• bsg_queue — BSG queue associated with the UFS controller
• rpm_dev_flush_recheck_work — used to suspend from RPM (runtime power management) after the UFS device has finished a WriteBooster buffer flush or auto BKOP.
• monitor — statistics about UFS commands
• crypto_capabilities — Content of crypto capabilities register (0x100)
• crypto_cap_array — Array of crypto capabilities
• crypto_cfg_register — Start of the crypto cfg array
• crypto_profile — the crypto profile of this hba (if applicable)
• debugfs_root — UFS controller debugfs root directory
• debugfs_ee_work — used to restore ee_ctrl_mask after a delay
• debugfs_ee_rate_limit_ms — user configurable delay after which to restore ee_ctrl_mask
• trigger_eh_attr — fault attributes for the fault injection trigger EH
• timeout_attr — fault attributes for the timeout fault injection trigger
• luns_avail — number of regular and well known LUNs supported by the UFS device
• nr_hw_queues — number of hardware queues configured
• nr_queues — number of Queues of different queue types
• complete_put — whether or not to call ufshcd_rpm_put from inside ufshcd_resume_complete
• scsi_host_added — indicates that scsi_add_host has been called
• mcq_sup — is mcq supported by UFSHC
• lsdb_sup — LSDBS capability
• mcq_enabled — is mcq ready to accept requests
• mcq_esi_enabled — is mcq ESI configured
• mcq_base — Multi circular queue registers base address
• uhq — array of supported hardware queues
• mcq_opr — MCQ operation and runtime registers
• ufs_rtc_update_work — A work for UFS RTC periodic update
• pm_qos_req — PM QoS request handle
• pm_qos_enabled — flag to check if pm qos is enabled
• pm_qos_mutex — synchronizes PM QoS request and status updates
• critical_health_count — count of critical health exceptions
• dev_lvl_exception_count — count of device level exceptions since last reset
• dev_lvl_exception_id — vendor specific information about the device level exception event.
• dme_qos_notification — Bitfield of pending DME Quality of Service (QoS) events. Bits[3:1] reflect the corresponding bits of UIC DME Error Code field within the Host Controller's UECDME register. Bit[0] is a flag indicating that the DME QoS Monitor has been reset by the host.
• dme_qos_sysfs_handle — handle for 'dme_qos_notification' sysfs entry
• vcc_off_delay_us — length of delay after VCC is powered off
• rpmbs — list of OP-TEE RPMB devices (one per RPMB region)
• host_preshoot_cap — a bitfield to indicate supported PreShoot dBs of host's TX lanes, cache of host M-PHY TX_HS_PreShoot_Setting_Capability Attribute (ID 0x15)
• host_deemphasis_cap — a bitfield to indicate supported DeEmphasis dBs of host's TX lanes, cache of host M-PHY TX_HS_DeEmphasis_Setting_Capability Attribute (ID 0x12)
• device_preshoot_cap — a bitfield to indicate supported PreShoot dBs of device's TX lanes, cache of device M-PHY TX_HS_PreShoot_Setting_Capability Attribute (ID 0x15)
• device_deemphasis_cap — a bitfield to indicate supported DeEmphasis dBs of device's TX lanes, cache of device M-PHY TX_HS_DeEmphasis_Setting_Capability Attribute (ID 0x12)
• tx_eq_params — TX Equalization settings

and that's the whole roster, bestie. every field accounted for, not a single one left on read 🫶

🌈 SEE ALSO 🌈

the whole friend group, all in Kernel file ./include/ufs/ufshcd.h:

struct uic_command(9), struct ufshcd_lrb(9), struct ufs_query_req(9), struct ufs_query_res(9), struct ufs_query(9), struct ufs_dev_cmd(9), struct ufs_clk_info(9), struct tx_eqtr_iter(9), struct ufshcd_tx_eq_settings(9), struct ufshcd_tx_eqtr_data(9), struct ufshcd_tx_eqtr_record(9), struct ufshcd_tx_eq_params(9), struct ufs_hba_variant_ops(9), struct ufs_clk_gating(9), struct ufs_clk_scaling(9), struct ufs_event_hist(9), struct ufs_stats(9), enum ufshcd_state(9), enum ufshcd_pmc_policy(9), struct ufshcd_mcq_opr_info_t(9), struct ufs_hw_queue(9), ufshcd_rmwl(9), ufshcd_set_variant(9), ufshcd_get_variant(9)

that's the page, babes ✨ it lives in ./include/ufs, it's the October 2026 edition of struct ufs_hba(9) — go forth and slay your UFS driver debugging 💖