STRUCT DWC2_QH(9)

💖 struct dwc2_qh(9) — Software queue head structure 💖

Okay bestie, welcome to the Kernel API Manual page for struct dwc2_qh, aka the software queue head structure. It’s giving iconic kernel-struct energy, and we’re going through every field together — no skips, no cap. 🫶

✨ NAME ✨

struct dwc2_qh — Software queue head structure. Literally that. 💅

🌸 SYNOPSIS 🌸

struct dwc2_qh {
    struct dwc2_hsotg *hsotg;
    u8 ep_type;
    u8 ep_is_in;
    u16 maxp;
    u16 maxp_mult;
    u8 dev_speed;
    u8 data_toggle;
    u8 ping_state;
    u8 do_split;
    u8 td_first;
    u8 td_last;
    u16 host_us;
    u16 device_us;
    u16 host_interval;
    u16 device_interval;
    u16 next_active_frame;
    u16 start_active_frame;
    s16 num_hs_transfers;
    struct dwc2_hs_transfer_time hs_transfers[DWC2_HS_SCHEDULE_UFRAMES];
    u32 ls_start_schedule_slice;
    u16 ntd;
    u8 *dw_align_buf;
    dma_addr_t dw_align_buf_dma;
    struct list_head qtd_list;
    struct dwc2_host_chan *channel;
    struct list_head qh_list_entry;
    struct dwc2_dma_desc *desc_list;
    dma_addr_t desc_list_dma;
    u32 desc_list_sz;
    u32 *n_bytes;
    struct timer_list unreserve_timer;
    struct hrtimer wait_timer;
    struct dwc2_tt *dwc_tt;
    int ttport;
    unsigned tt_buffer_dirty:1;
    unsigned unreserve_pending:1;
    unsigned schedule_low_speed:1;
    unsigned want_wait:1;
    unsigned wait_timer_cancel:1;
};

🦋 Members 🦋

• hsotg — The HCD state structure for the DWC OTG controller. That’s the big-picture controller state, bestie. 🎀
• ep_type — Endpoint type. One of the following values:
  • USB_ENDPOINT_XFER_CONTROL
  • USB_ENDPOINT_XFER_BULK
  • USB_ENDPOINT_XFER_INT
  • USB_ENDPOINT_XFER_ISOC
• ep_is_in — Endpoint direction. Which way the data vibes are flowing. 💫
• maxp — Value from wMaxPacketSize field of Endpoint Descriptor. The packet-size lore, straight from the descriptor.
• maxp_mult — Multiplier for maxp. It’s giving “packet size but make it multiplied.” ✨
• dev_speed — Device speed. One of the following values:
  • USB_SPEED_LOW
  • USB_SPEED_FULL
  • USB_SPEED_HIGH
• data_toggle — Determines the PID of the next data packet for non-control transfers. Ignored for control transfers. One of the following values:
  • DWC2_HC_PID_DATA0
  • DWC2_HC_PID_DATA1
• ping_state — Ping state. That’s the whole note. Ping. State. 🛎️
• do_split — Full/low speed endpoint on high-speed hub requires split. A whole little “yes bestie, split needed” flag.
• td_first — Index of first activated isochronous transfer descriptor.
• td_last — Index of last activated isochronous transfer descriptor.
• host_us — Bandwidth in microseconds per transfer as seen by host.
• device_us — Bandwidth in microseconds per transfer as seen by device.
• host_interval — Interval between transfers as seen by the host. If the host is high speed and the device is low speed this will be 8 times device interval.
• device_interval — Interval between transfers as seen by the device. interval.
• next_active_frame — (Micro)frame before we next need to put something on the bus. We’ll move the qh to active here. If the host is in high speed mode this will be a uframe. If the host is in low speed mode this will be a full frame. 🕰️
• start_active_frame — If we are partway through a split transfer, this will be what next_active_frame was when we started. Otherwise it should always be the same as next_active_frame.
• num_hs_transfers — Number of transfers in hs_transfers. Normally this is 1 but can be more than one for splits. Always >= 1 unless the host is in low/full speed mode.
• hs_transfers — Transfers that are scheduled as seen by the high speed bus. Not used if host is in low or full speed mode (but note that it IS USED if the device is low or full speed as long as the HOST is in high speed mode). 🔥
• ls_start_schedule_slice — Start time (in slices) on the low speed bus schedule that’s being used by this device. This will be on the periodic_bitmap in a struct dwc2_tt. Not used if this device is high speed. Note that this is in schedule slice which is tightly packed.
• ntd — Actual number of transfer descriptors in a list.
• dw_align_buf — Used instead of original buffer if its physical address is not dword-aligned.
• dw_align_buf_dma — DMA address for dw_align_buf.
• qtd_list — List of QTDs for this QH.
• channel — Host channel currently processing transfers for this QH.
• qh_list_entry — Entry for QH in either the periodic or non-periodic schedule.
• desc_list — List of transfer descriptors.
• desc_list_dma — Physical address of desc_list.
• desc_list_sz — Size of descriptors list.
• n_bytes — Xfer Bytes array. Each element corresponds to a transfer descriptor and indicates original XferSize value for the descriptor.
• unreserve_timer — Timer for releasing periodic reservation.
• wait_timer — Timer used to wait before re-queuing.
• dwc_tt — Pointer to our tt info (or NULL if no tt).
• ttport — Port number within our tt. (tt_buffer_dirty — True if clear_tt_buffer_complete is pending.)
• tt_buffer_dirty — True if EP’s TT buffer is not clean. A Queue Head (QH) holds the static characteristics of an endpoint and maintains a list of transfers (QTDs) for that endpoint. A QH structure may be entered in either the non-periodic or periodic schedule.
• unreserve_pending — True if we planned to unreserve but haven’t yet.
• schedule_low_speed — True if we have a low/full speed component (either the host is in low/full speed mode or do_split).
• want_wait — We should wait before re-queuing; only matters for non-periodic transfers and is ignored for periodic ones.
• wait_timer_cancel — Set to true to cancel the wait_timer.

🌈 SEE ALSO 🌈

Kernel file ./drivers/usb/dwc2/hcd.h:

• struct dwc2_host_chan(9)
• struct dwc2_tt(9)
• struct dwc2_hs_transfer_time(9)
• struct dwc2_qtd(9)
• dwc2_handle_hcd_intr(9)
• dwc2_hcd_stop(9)
• dwc2_hcd_is_b_host(9)
• dwc2_hcd_dump_state(9)

That’s the whole page, bestie 🫶. Cute sign-off time: source/version is ./drivers/usb/dwc2, the date is October 2026, and this iconic little page is struct dwc2_qh(9). Periodt. 💅✨