STRUCT BLK_MQ_HW_CTX(9)

💅 struct blk_mq_hw_ctx(9) — the Kernel API Manual, bestie edition

okay so picture this: it's struct blk_mq_hw_ctx(9), from the Kernel API Manual, and it's literally the state for a hardware queue facing the hardware block device. like, the whole vibe of one hardware queue, tracked in one struct. iconic behavior honestly 🎀

---

✨ SYNOPSIS ✨

struct blk_mq_hw_ctx {
    struct {
      spinlock_t lock;
      struct list_head        dispatch;
      unsigned long           state;
    };
    struct delayed_work     run_work;
    cpumask_var_t cpumask;
    int next_cpu;
    int next_cpu_batch;
    unsigned long           flags;
    void *sched_data;
    struct request_queue    *queue;
    struct blk_flush_queue  *fq;
    void *driver_data;
    struct sbitmap          ctx_map;
    struct blk_mq_ctx       *dispatch_from;
    unsigned int            dispatch_busy;
    unsigned short          type;
    unsigned short          nr_ctx;
    struct blk_mq_ctx       **ctxs;
    spinlock_t dispatch_wait_lock;
    wait_queue_entry_t dispatch_wait;
    atomic_t wait_index;
    struct blk_mq_tags      *tags;
    struct blk_mq_tags      *sched_tags;
    int numa_node;
    unsigned int            queue_num;
    atomic_t nr_active;
    struct hlist_node       cpuhp_online;
    struct hlist_node       cpuhp_dead;
    struct kobject          kobj;
  #ifdef CONFIG_BLK_DEBUG_FS;
    struct dentry           *debugfs_dir;
    struct dentry           *sched_debugfs_dir;
  #endif;
    struct list_head        hctx_list;
 };

---

🌸 Members 🌸

okay this is the part where we go field by field, no skipping, no cap 💖

• {unnamed_struct} — anonymous. yeah she's just... there. mysterious. we don't ask questions 🫶

🦋 the dispatch trio (the anonymous struct crew)

• lock — protects the dispatch list. that's it, that's her job. bodyguard energy.
• dispatch — for requests that are ready to be dispatched to the hardware but for some reason (e.g. lack of resources) could not be sent to the hardware. and the moment the driver can send new requests, requests at this list get sent first, for a fairer dispatch. so it's like the VIP holding area but make it fair ⭐
• state — BLK_MQ_S_* flags. defines the state of the hw queue (active, scheduled to restart, stopped). it's giving status update.

🌈 scheduling & CPU stuff

• run_work — used for scheduling a hardware queue run at a later time. procrastination, but make it kernel-legal.
• cpumask — map of available CPUs where this hctx can run.
• next_cpu — used by blk_mq_hctx_next_cpu for round-robin CPU selection from cpumask. taking turns, as one does 💅
• next_cpu_batch — counter of how many works left in the batch before changing to the next CPU. the countdown, basically.
• flags — BLK_MQ_F_* flags. defines the behaviour of the queue. her personality traits.

🎀 pointers & ownership

• sched_data — pointer owned by the IO scheduler attached to a request queue. it's up to the IO scheduler how to use this pointer. not our business, not our problem 🙈
• queue — pointer to the request queue that owns this hardware context. the parent, the main character.
• fq — queue of requests that need to perform a flush operation.
• driver_data — pointer to data owned by the block driver that created this hctx. lowkey the driver's little stash.
• ctx_map — bitmap for each software queue. if bit is on, there is a pending request in that software queue. bit = on, request = pending, iykyk.
• dispatch_from — software queue to be used when no scheduler was selected. the fallback queen 👑
• dispatch_busy — number used by blk_mq_update_dispatch_busy to decide if the hw_queue is busy using Exponential Weighted Moving Average algorithm. she's doing math, she's doing the most.

🧚 types, counts & arrays

• type — HCTX_TYPE_* flags. type of hardware queue.
• nr_ctx — number of software queues.
• ctxs — array of software queues.

💜 the waiting room

• dispatch_wait_lock — lock for the dispatch_wait queue.
• dispatch_wait — waitqueue to put requests when there is no tag available at the moment, to wait for another try in the future. literally "no tag rn, come back later" energy.
• wait_index — index of next available dispatch_wait queue to insert requests. the ticket number, fr fr.

🔥 tags

• tags — tags owned by the block driver. a tag at this set is only assigned when a request is dispatched from a hardware queue.
• sched_tags — tags owned by I/O scheduler. if there is an I/O scheduler associated with a request queue, a tag is assigned when that request is allocated. else, this member is not used. conditional icon ✨

🌸 node & index & count

• numa_node — NUMA node the storage adapter has been connected to.
• queue_num — index of this hardware queue.
• nr_active — number of active requests. only used when a tag set is shared across request queues. exclusive little field, only sometimes relevant 💅

🫶 CPU hotplug lists

• cpuhp_online — list to store request if CPU is going to die. dramatic but accurate 😭
• cpuhp_dead — list to store request if some CPU die. also dramatic, also accurate.

🎀 sysfs & debugfs

• kobj — kernel object for sysfs.
• debugfs_dir — debugfs directory for this hardware queue. named as cpu<cpu_number>.
• sched_debugfs_dir — debugfs directory for the scheduler.

⭐ the last one

• hctx_list — if this hctx is not in use, this is an entry in q->unused_hctx_list. benched but still on the roster.

---

🔍 SEE ALSO 🔍

kernel file ./include/linux/blk-mq.h, plus the whole friend group: enum blk_eh_timer_return(9), struct blk_mq_queue_map(9), enum hctx_type(9), struct blk_mq_tag_set(9), struct blk_mq_queue_data(9), struct blk_mq_ops(9), blk_mq_rq_state(9), blk_mq_add_to_batch(9), blk_mq_rq_from_pdu(9), blk_mq_rq_to_pdu(9), blk_rq_nr_bvec(9), blk_rq_passthrough_stats(9). go read them, they're all slay, no notes 🌈

---

ok that's the whole struct, every single field, nothing skipped. go forth and dispatch responsibly 💖

and that's a wrap, bestie — brought to you by ./include/linux, dated October 2026, filed under struct blk_mq_hw_ctx(9). mwah 💋✨