STRUCT DWC3(9)

💅 struct dwc3(9) 💅

okay so this page is from the Kernel API Manual, and it is literally all about struct dwc3 — representation of our controller. bestie, she is iconic and extremely detailed, so hydrate before we dive in. 🎀✨

✨ NAME ✨

struct dwc3 — representation of our controller. periodt. 💖

🦋 SYNOPSIS 🦋

okay so the synopsis is literally the whole struct dwc3 definition. no notes, just fields, vibes, and a whole lot of #defines:

struct dwc3 {
    struct work_struct      drd_work;
    struct work_struct      err_recovery_work;
    struct dwc3_trb         *ep0_trb;
    void *bounce;
    u8 *setup_buf;
    dma_addr_t ep0_trb_addr;
    dma_addr_t bounce_addr;
    struct dwc3_request     ep0_usb_req;
    struct completion       ep0_in_setup;
    spinlock_t lock;
    struct mutex            mutex;
    struct mutex            connect_mutex;
    struct device           *dev;
    struct device           *sysdev;
    struct platform_device  *xhci;
    struct resource         xhci_resources[DWC3_XHCI_RESOURCES_NUM];
    struct dwc3_event_buffer *ev_buf;
    struct dwc3_ep          *eps[DWC3_ENDPOINTS_NUM];
    struct usb_gadget       *gadget;
    struct usb_gadget_driver *gadget_driver;
    const struct dwc3_glue_ops      *glue_ops;
    struct clk              *bus_clk;
    struct clk              *ref_clk;
    struct clk              *susp_clk;
    struct clk              *utmi_clk;
    struct clk              *pipe_clk;
    struct reset_control    *reset;
    struct usb_phy          *usb2_phy;
    struct usb_phy          *usb3_phy;
    struct phy              *usb2_generic_phy[DWC3_USB2_MAX_PORTS];
    struct phy              *usb3_generic_phy[DWC3_USB3_MAX_PORTS];
    u8 num_usb2_ports;
    u8 num_usb3_ports;
    bool phys_ready;
    struct ulpi             *ulpi;
    bool ulpi_ready;
    void __iomem            *regs;
    size_t regs_size;
    enum usb_dr_mode        dr_mode;
    u32 current_dr_role;
    u32 desired_dr_role;
    struct extcon_dev       *edev;
    struct notifier_block   edev_nb;
    enum usb_phy_interface  hsphy_mode;
    struct usb_role_switch  *role_sw;
    enum usb_dr_mode        role_switch_default_mode;
    struct power_supply     *usb_psy;
    const char              *usb_psy_name;
    struct notifier_block   psy_nb;
    struct work_struct      vbus_draw_work;
    unsigned int            current_limit;
  #define DWC3_CURRENT_UNSPECIFIED        UINT_MAX;
    u32 fladj;
    u32 ref_clk_per;
    u32 irq_gadget;
    u32 otg_irq;
    u32 current_otg_role;
    u32 desired_otg_role;
    bool otg_restart_host;
    u32 u1u2;
    u32 maximum_speed;
    u32 gadget_max_speed;
    enum usb_ssp_rate       max_ssp_rate;
    enum usb_ssp_rate       gadget_ssp_rate;
    u32 ip;
  #define DWC3_IP                 0x5533;
  #define DWC31_IP                0x3331;
  #define DWC32_IP                0x3332;
  #define DWC4_IP                 0x3430;
    u32 revision;
  #define DWC3_REVISION_ANY       0x0;
  #define DWC3_REVISION_173A      0x5533173a;
  #define DWC3_REVISION_175A      0x5533175a;
  #define DWC3_REVISION_180A      0x5533180a;
  #define DWC3_REVISION_183A      0x5533183a;
  #define DWC3_REVISION_185A      0x5533185a;
  #define DWC3_REVISION_187A      0x5533187a;
  #define DWC3_REVISION_188A      0x5533188a;
  #define DWC3_REVISION_190A      0x5533190a;
  #define DWC3_REVISION_194A      0x5533194a;
  #define DWC3_REVISION_200A      0x5533200a;
  #define DWC3_REVISION_202A      0x5533202a;
  #define DWC3_REVISION_210A      0x5533210a;
  #define DWC3_REVISION_220A      0x5533220a;
  #define DWC3_REVISION_230A      0x5533230a;
  #define DWC3_REVISION_240A      0x5533240a;
  #define DWC3_REVISION_250A      0x5533250a;
  #define DWC3_REVISION_260A      0x5533260a;
  #define DWC3_REVISION_270A      0x5533270a;
  #define DWC3_REVISION_280A      0x5533280a;
  #define DWC3_REVISION_290A      0x5533290a;
  #define DWC3_REVISION_300A      0x5533300a;
  #define DWC3_REVISION_310A      0x5533310a;
  #define DWC3_REVISION_320A      0x5533320a;
  #define DWC3_REVISION_330A      0x5533330a;
  #define DWC31_REVISION_ANY      0x0;
  #define DWC31_REVISION_110A     0x3131302a;
  #define DWC31_REVISION_120A     0x3132302a;
  #define DWC31_REVISION_160A     0x3136302a;
  #define DWC31_REVISION_170A     0x3137302a;
  #define DWC31_REVISION_180A     0x3138302a;
  #define DWC31_REVISION_190A     0x3139302a;
  #define DWC31_REVISION_200A     0x3230302a;
  #define DWC32_REVISION_ANY      0x0;
  #define DWC32_REVISION_100A     0x3130302a;
    u32 version_type;
  #define DWC31_VERSIONTYPE_ANY           0x0;
  #define DWC31_VERSIONTYPE_EA01          0x65613031;
  #define DWC31_VERSIONTYPE_EA02          0x65613032;
  #define DWC31_VERSIONTYPE_EA03          0x65613033;
  #define DWC31_VERSIONTYPE_EA04          0x65613034;
  #define DWC31_VERSIONTYPE_EA05          0x65613035;
  #define DWC31_VERSIONTYPE_EA06          0x65613036;
    enum dwc3_ep0_next      ep0_next_event;
    enum dwc3_ep0_state     ep0state;
    enum dwc3_link_state    link_state;
    enum dwc3_err_state     err_state;
    u32 err_recovery_count;
    u16 u2sel;
    u16 u2pel;
    u8 u1sel;
    u8 u1pel;
    u8 speed;
    u8 num_eps;
    struct dwc3_hwparams    hwparams;
    struct debugfs_regset32 *regset;
    u32 dbg_lsp_select;
    u8 test_mode;
    u8 test_mode_nr;
    u8 lpm_nyet_threshold;
    u8 hird_threshold;
    u8 rx_thr_num_pkt;
    u8 rx_max_burst;
    u8 tx_thr_num_pkt;
    u8 tx_max_burst;
    u8 rx_thr_num_pkt_prd;
    u8 rx_max_burst_prd;
    u8 tx_thr_num_pkt_prd;
    u8 tx_max_burst_prd;
    u8 tx_fifo_resize_max_num;
    u8 clear_stall_protocol;
    u16 num_hc_interrupters;
    const char              *hsphy_interface;
    unsigned connected:1;
    unsigned softconnect:1;
    unsigned delayed_status:1;
    unsigned ep0_bounced:1;
    unsigned ep0_expect_in:1;
    unsigned sysdev_is_parent:1;
    unsigned has_lpm_erratum:1;
    unsigned is_utmi_l1_suspend:1;
    unsigned is_fpga:1;
    unsigned pending_events:1;
    unsigned do_fifo_resize:1;
    unsigned pullups_connected:1;
    unsigned setup_packet_pending:1;
    unsigned three_stage_setup:1;
    unsigned dis_start_transfer_quirk:1;
    unsigned usb3_lpm_capable:1;
    unsigned usb2_lpm_disable:1;
    unsigned usb2_gadget_lpm_disable:1;
    unsigned needs_full_reinit:1;
    unsigned disable_scramble_quirk:1;
    unsigned u2exit_lfps_quirk:1;
    unsigned u2ss_inp3_quirk:1;
    unsigned req_p1p2p3_quirk:1;
    unsigned del_p1p2p3_quirk:1;
    unsigned del_phy_power_chg_quirk:1;
    unsigned lfps_filter_quirk:1;
    unsigned rx_detect_poll_quirk:1;
    unsigned dis_u3_susphy_quirk:1;
    unsigned dis_u2_susphy_quirk:1;
    unsigned dis_enblslpm_quirk:1;
    unsigned dis_u1_entry_quirk:1;
    unsigned dis_u2_entry_quirk:1;
    unsigned dis_rxdet_inp3_quirk:1;
    unsigned dis_u2_freeclk_exists_quirk:1;
    unsigned dis_del_phy_power_chg_quirk:1;
    unsigned dis_tx_ipgap_linecheck_quirk:1;
    unsigned resume_hs_terminations:1;
    unsigned ulpi_ext_vbus_drv:1;
    unsigned parkmode_disable_ss_quirk:1;
    unsigned parkmode_disable_hs_quirk:1;
    unsigned gfladj_refclk_lpm_sel:1;
    unsigned tx_de_emphasis_quirk:1;
    unsigned tx_de_emphasis:2;
    unsigned dis_metastability_quirk:1;
    unsigned dis_split_quirk:1;
    unsigned enable_usb2_transceiver_delay:1;
    unsigned async_callbacks:1;
    unsigned sys_wakeup:1;
    unsigned wakeup_configured:1;
    unsigned suspended:1;
    unsigned susphy_state:1;
    u16 imod_interval;
    int max_cfg_eps;
    int last_fifo_depth;
    int num_ep_resized;
    struct dentry           *debug_root;
    u32 gsbuscfg0_reqinfo;
    u32 wakeup_pending_funcs;
};

🎀 MEMBERS 🎀

here is the member-by-member breakdown, bestie. every single one is here — no skips, no cap. 💖

• drd_work — the workqueue used for role swapping. she is literally the one switching things up. 🔥
• err_recovery_work — the workqueue used for controller error recovery. cleanup main character energy, fr fr.
• ep0_trb — the TRB which is used for the ctrl_req. iconic little control-request TRB.
• bounce — address of the bounce buffer.
• setup_buf — used while processing STD USB requests. bestie, this is the setup buffer.
• ep0_trb_addr — DMA address of ep0_trb.
• bounce_addr — DMA address of bounce.
• ep0_usb_req — dummy req used while handling STD USB requests.
• ep0_in_setup — one control transfer is completed and enter setup phase.
• lock — for synchronizing. keep it locked, bestie. 🔒
• mutex — for mode switching.
• connect_mutex — for the pull-up and err_recovery_work.
• dev — pointer to our struct device.
• sysdev — pointer to the DMA-capable device.
• xhci — pointer to our xHCI child.
• xhci_resources — struct resources for our xhci child.
• ev_buf — struct dwc3_event_buffer pointer.
• eps — endpoint array. the whole lineup, periodt.
• gadget — device side representation of the peripheral controller.
• gadget_driver — pointer to the gadget driver.
• glue_ops — Vendor callbacks for flattened device implementations.
• bus_clk — clock for accessing the registers.
• ref_clk — reference clock.
• susp_clk — clock used when the SS phy is in low power (S3) state.
• utmi_clk — clock used for USB2 PHY communication.
• pipe_clk — clock used for USB3 PHY communication.
• reset — reset control.
• usb2_phy — pointer to USB2 PHY.
• usb3_phy — pointer to USB3 PHY.
• usb2_generic_phy — pointer to array of USB2 PHYs.
• usb3_generic_phy — pointer to array of USB3 PHYs.
• num_usb2_ports — number of USB2 ports.
• num_usb3_ports — number of USB3 ports.
• phys_ready — flag to indicate that PHYs are ready.
• ulpi — pointer to ulpi interface.
• ulpi_ready — flag to indicate that ULPI is initialized.
• regs — base address for our registers.
• regs_size — address space size.
• dr_mode — requested mode of operation.
• current_dr_role — current role of operation when in dual-role mode.
• desired_dr_role — desired role of operation when in dual-role mode.
• edev — extcon handle.
• edev_nb — extcon notifier.
• hsphy_mode — UTMI phy mode, one of following:
  • USBPHY_INTERFACE_MODE_UTMI
  • USBPHY_INTERFACE_MODE_UTMIW
• role_sw — usb_role_switch handle.
• role_switch_default_mode — default operation mode of controller while usb role is USB_ROLE_NONE.
• usb_psy — pointer to power supply interface.
• usb_psy_name — name of the USB power supply.
• psy_nb — power supply notifier block.
• vbus_draw_work — Work to set the vbus drawing limit.
• current_limit — How much current to draw from vbus, in milliAmperes.
• fladj — frame length adjustment. That’s the whole vibe 💅
• ref_clk_per — reference clock period configuration. clock girlies rise 🕰️
• irq_gadget — the peripheral controller’s IRQ number, periodt.
• otg_irq — IRQ number for OTG IRQs. yes, OTG has its own IRQ era ✨
• current_otg_role — the current role of operation while using the OTG block.
• desired_otg_role — the desired role of operation while using the OTG block.
• otg_restart_host — flag that says the OTG controller needs to restart the host.
• u1u2 — only used on revisions <1.83a for a workaround. no cap, that’s the rule.
• maximum_speed — maximum speed requested, mainly for testing purposes.
• gadget_max_speed — maximum gadget speed requested.
• max_ssp_rate — SuperSpeed Plus maximum signaling rate and lane count.
• gadget_ssp_rate — Gadget driver’s maximum supported SuperSpeed Plus signaling rate and lane count.
• ip — controller’s ID.
• revision — controller’s version of an IP.
• version_type — VERSIONTYPE register contents, a sub release of a revision.
• ep0_next_event — holds the next expected event.
• ep0state — state of endpoint zero.
• link_state — link state.
• err_state — current error recovery state.
• err_recovery_count — number of consecutive error recovery attempts until confirmed healthy and reset to 0 on reset event.
• u2sel — parameter from the Set SEL request.
• u2pel — parameter from the Set SEL request.
• u1sel — parameter from the Set SEL request.
• u1pel — parameter from the Set SEL request.
• speed — device speed (super, high, full, low).
• num_eps — number of endpoints.
• hwparams — copy of hwparams registers.
• regset — debugfs pointer to regdump file.
• dbg_lsp_select — current debug lsp mux register selection.
• test_mode — true when we’re entering a USB test mode.
• test_mode_nr — test feature selector.
• lpm_nyet_threshold — LPM NYET response threshold.
• hird_threshold — HIRD threshold.
• rx_thr_num_pkt — USB receive packet count.
• rx_max_burst — max USB receive burst size.
• tx_thr_num_pkt — USB transmit packet count.
• tx_max_burst — max USB transmit burst size.
• rx_thr_num_pkt_prd — periodic ESS receive packet count.
• rx_max_burst_prd — max periodic ESS receive burst size.
• tx_thr_num_pkt_prd — periodic ESS transmit packet count.
• tx_max_burst_prd — max periodic ESS transmit burst size.
• tx_fifo_resize_max_num — max number of fifos allocated during txfifo resize.
• clear_stall_protocol — endpoint number that requires a delayed status phase.
• num_hc_interrupters — number of host controller interrupters.
• hsphy_interface — "utmi" or "ulpi". pick your PHY bestie 💅
• connected — true when we’re connected to a host, false otherwise.
• softconnect — true when gadget connect is called, false when disconnect runs.
• delayed_status — true when gadget driver asks for delayed status.
• ep0_bounced — true when we used bounce buffer.
• ep0_expect_in — true when we expect a DATA IN transfer.
• sysdev_is_parent — true when dwc3 device has a parent driver.
• has_lpm_erratum — true when core was configured with LPM Erratum. note: there’s no way for software to detect this at runtime. important caveat, bestie 😭
• is_utmi_l1_suspend — the core asserts output signal: 0 → utmi_sleep_n, 1 → utmi_l1_suspend_n.
• is_fpga — true when we are using the FPGA board.
• pending_events — true when we have pending IRQs to be handled.
• do_fifo_resize — true when txfifo resizing is enabled for dwc3 endpoints.
• pullups_connected — true when Run/Stop bit is set.
• setup_packet_pending — true when there’s a Setup Packet in FIFO. Workaround.
• three_stage_setup — set if we perform a three phase setup.
• dis_start_transfer_quirk — set if start_transfer failure SW workaround is not needed for DWC_usb31 version 1.70a-ea06 and below.
• usb3_lpm_capable — set if hardware supports Link Power Management.
• usb2_lpm_disable — set to disable usb2 lpm for host.
• usb2_gadget_lpm_disable — set to disable usb2 lpm for gadget.
• needs_full_reinit — set to indicate the core may lose power and need full initialization during system pm.
• disable_scramble_quirk — set if we enable the disable scramble quirk.
• u2exit_lfps_quirk — set if we enable u2exit lfps quirk.
• u2ss_inp3_quirk — set if we enable P3 OK for U2/SS Inactive quirk.
• req_p1p2p3_quirk — set if we enable request p1p2p3 quirk.
• del_p1p2p3_quirk — set if we enable delay p1p2p3 quirk.
• del_phy_power_chg_quirk — set if we enable delay phy power change quirk.
• lfps_filter_quirk — set if we enable LFPS filter quirk.
• rx_detect_poll_quirk — set if we enable rx_detect to polling lfps quirk.
• dis_u3_susphy_quirk — set if we disable usb3 suspend phy.
• dis_u2_susphy_quirk — set if we disable usb2 suspend phy.
• dis_enblslpm_quirk — set if we clear enblslpm in GUSB2PHYCFG, disabling the suspend signal to the PHY.
• dis_u1_entry_quirk — set if link entering into U1 state needs to be disabled.
• dis_u2_entry_quirk — set if link entering into U2 state needs to be disabled.
• dis_rxdet_inp3_quirk — set if we disable Rx.Detect in P3.
• dis_u2_freeclk_exists_quirk — set if we clear u2_freeclk_exists in GUSB2PHYCFG, specify that USB2 PHY doesn’t provide a free-running PHY clock.
• dis_del_phy_power_chg_quirk — set if we disable delay phy power change quirk.
• dis_tx_ipgap_linecheck_quirk — set if we disable u2mac linestate check during HS transmit.
• resume_hs_terminations — set if we enable quirk for fixing improper crc generation after resume from suspend.
• ulpi_ext_vbus_drv — set to configure the upli chip to drives CPEN pin VBUS with an external supply.
• parkmode_disable_ss_quirk — set if we need to disable all SuperSpeed instances in park mode.
• parkmode_disable_hs_quirk — set if we need to disable all HighSpeed instances in park mode.
• gfladj_refclk_lpm_sel — set if we need to enable SOF/ITP counter running based on ref_clk.
• tx_de_emphasis_quirk — set if we enable Tx de-emphasis quirk.
• tx_de_emphasis — Tx de-emphasis value: 0 → -6dB de-emphasis, 1 → -3.5dB de-emphasis, 2 → No de-emphasis, 3 → Reserved. slay those levels 💅
• dis_metastability_quirk — set to disable metastability quirk.
• dis_split_quirk — set to disable split boundary.
• enable_usb2_transceiver_delay — set to insert a delay before the assertion of the TxValid signal during a HS Chirp.
• async_callbacks — if set, indicate that async callbacks will be used.
• sys_wakeup — set if the device may do system wakeup.
• wakeup_configured — set if the device is configured for remote wakeup.
• suspended — set to track suspend event due to U3/L2.
• susphy_state — state of DWC3_GUSB2PHYCFG_SUSPHY + DWC3_GUSB3PIPECTL_SUSPHY before PM suspend.
• imod_interval — set the interrupt moderation interval in 250ns increments or 0 to disable. zero means off, bestie ✨
• max_cfg_eps — current max number of IN eps used across all USB configs.
• last_fifo_depth — last fifo depth used to determine next fifo ram start address.
• num_ep_resized — carries the current number endpoints which have had its tx fifo resized.
• debug_root — root debugfs directory for this device to put its files in.
• gsbuscfg0_reqinfo — store GSBUSCFG0.DATRDREQINFO, DESRDREQINFO, DATWRREQINFO, and DESWRREQINFO value passed from glue driver.
• wakeup_pending_funcs — indicates whether any interface has requested for function wakeup in bitmap format where bit position represents interface_id.

👀 SEE ALSO 👀

The kernel file to check is ./drivers/usb/dwc3/core.h — yes, that exact path, bestie. source-of-truth energy fr fr 🫶

• struct dwc3_event_buffer(9)
• struct dwc3_ep(9)
• struct dwc3_trb(9)
• struct dwc3_hwparams(9)
• struct dwc3_request(9)
• struct dwc3_glue_ops(9)
• struct dwc3_event_depevt(9)
• struct dwc3_event_devt(9)
• struct dwc3_event_gevt(9)
• union dwc3_event(9)
• struct dwc3_gadget_ep_cmd_params(9)
• dwc3_mdwidth(9)

source: ./drivers/usb/dwc3 · version/page: struct dwc3(9) · date: October 2026 — okay that’s the whole page, bestie, go flex those struct fields 💖✨