1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* 3 * glue.h - DesignWare USB3 DRD glue header 4 */ 5 6 #ifndef __DRIVERS_USB_DWC3_GLUE_H 7 #define __DRIVERS_USB_DWC3_GLUE_H 8 9 #include <linux/types.h> 10 #include "core.h" 11 12 /** 13 * dwc3_properties: DWC3 core properties 14 * @gsbuscfg0_reqinfo: Value to be programmed in the GSBUSCFG0.REQINFO field 15 */ 16 struct dwc3_properties { 17 u32 gsbuscfg0_reqinfo; 18 }; 19 20 #define DWC3_DEFAULT_PROPERTIES ((struct dwc3_properties){ \ 21 .gsbuscfg0_reqinfo = DWC3_GSBUSCFG0_REQINFO_UNSPECIFIED, \ 22 }) 23 24 /** 25 * dwc3_probe_data: Initialization parameters passed to dwc3_core_probe() 26 * @dwc: Reference to dwc3 context structure 27 * @res: resource for the DWC3 core mmio region 28 * @ignore_clocks_and_resets: clocks and resets defined for the device should 29 * be ignored by the DWC3 core, as they are managed by the glue 30 * @skip_core_init_mode: Skip the finial initialization of the target mode, as 31 * it must be managed by the glue 32 * @properties: dwc3 software manage properties 33 */ 34 struct dwc3_probe_data { 35 struct dwc3 *dwc; 36 struct resource *res; 37 bool ignore_clocks_and_resets; 38 bool skip_core_init_mode; 39 struct dwc3_properties properties; 40 }; 41 42 /** 43 * dwc3_core_probe - Initialize the core dwc3 driver 44 * @data: Initialization and configuration parameters for the controller 45 * 46 * Initializes the DesignWare USB3 core driver by setting up resources, 47 * registering interrupts, performing hardware setup, and preparing 48 * the controller for operation in the appropriate mode (host, gadget, 49 * or OTG). This is the main initialization function called by glue 50 * layer drivers to set up the core controller. 51 * 52 * Return: 0 on success, negative error code on failure 53 */ 54 int dwc3_core_probe(const struct dwc3_probe_data *data); 55 56 /** 57 * dwc3_core_remove - Deinitialize and remove the core dwc3 driver 58 * @dwc: Pointer to DWC3 controller context 59 * 60 * Cleans up resources and disables the dwc3 core driver. This should be called 61 * during driver removal or when the glue layer needs to shut down the 62 * controller completely. 63 */ 64 void dwc3_core_remove(struct dwc3 *dwc); 65 66 /* 67 * The following callbacks are provided for glue drivers to call from their 68 * own pm callbacks provided in struct dev_pm_ops. Glue drivers can perform 69 * platform-specific work before or after calling these functions and delegate 70 * the core suspend/resume operations to the core driver. 71 */ 72 int dwc3_runtime_suspend(struct dwc3 *dwc); 73 int dwc3_runtime_resume(struct dwc3 *dwc); 74 int dwc3_runtime_idle(struct dwc3 *dwc); 75 int dwc3_pm_suspend(struct dwc3 *dwc); 76 int dwc3_pm_resume(struct dwc3 *dwc); 77 void dwc3_pm_complete(struct dwc3 *dwc); 78 int dwc3_pm_prepare(struct dwc3 *dwc); 79 80 81 /* All of the following functions must only be used with skip_core_init_mode */ 82 83 /** 84 * dwc3_core_init - Initialize DWC3 core hardware 85 * @dwc: Pointer to DWC3 controller context 86 * 87 * Configures and initializes the core hardware, usually done by dwc3_core_probe. 88 * This function is provided for platforms that use skip_core_init_mode and need 89 * to finalize the core initialization after some platform-specific setup. 90 * It must only be called when using skip_core_init_mode and before 91 * dwc3_host_init or dwc3_gadget_init. 92 * 93 * Return: 0 on success, negative error code on failure 94 */ 95 int dwc3_core_init(struct dwc3 *dwc); 96 97 /** 98 * dwc3_core_exit - Shut down DWC3 core hardware 99 * @dwc: Pointer to DWC3 controller context 100 * 101 * Disables and cleans up the core hardware state. This is usually handled 102 * internally by dwc3 and must only be called when using skip_core_init_mode 103 * and only after dwc3_core_init. Afterwards, dwc3_core_init may be called 104 * again. 105 */ 106 void dwc3_core_exit(struct dwc3 *dwc); 107 108 /** 109 * dwc3_host_init - Initialize host mode operation 110 * @dwc: Pointer to DWC3 controller context 111 * 112 * Initializes the controller for USB host mode operation, usually done by 113 * dwc3_core_probe or from within the dwc3 USB role switch callback. 114 * This function is provided for platforms that use skip_core_init_mode and need 115 * to finalize the host initialization after some platform-specific setup. 116 * It must not be called before dwc3_core_init or when skip_core_init_mode is 117 * not used. It must also not be called when gadget or host mode has already 118 * been initialized. 119 * 120 * Return: 0 on success, negative error code on failure 121 */ 122 int dwc3_host_init(struct dwc3 *dwc); 123 124 /** 125 * dwc3_host_exit - Shut down host mode operation 126 * @dwc: Pointer to DWC3 controller context 127 * 128 * Disables and cleans up host mode resources, usually done by 129 * the dwc3 USB role switch callback before switching controller mode. 130 * It must only be called when skip_core_init_mode is used and only after 131 * dwc3_host_init. 132 */ 133 void dwc3_host_exit(struct dwc3 *dwc); 134 135 /** 136 * dwc3_gadget_init - Initialize gadget mode operation 137 * @dwc: Pointer to DWC3 controller context 138 * 139 * Initializes the controller for USB gadget mode operation, usually done by 140 * dwc3_core_probe or from within the dwc3 USB role switch callback. This 141 * function is provided for platforms that use skip_core_init_mode and need to 142 * finalize the gadget initialization after some platform-specific setup. 143 * It must not be called before dwc3_core_init or when skip_core_init_mode is 144 * not used. It must also not be called when gadget or host mode has already 145 * been initialized. 146 * 147 * Return: 0 on success, negative error code on failure 148 */ 149 int dwc3_gadget_init(struct dwc3 *dwc); 150 151 /** 152 * dwc3_gadget_exit - Shut down gadget mode operation 153 * @dwc: Pointer to DWC3 controller context 154 * 155 * Disables and cleans up gadget mode resources, usually done by 156 * the dwc3 USB role switch callback before switching controller mode. 157 * It must only be called when skip_core_init_mode is used and only after 158 * dwc3_gadget_init. 159 */ 160 void dwc3_gadget_exit(struct dwc3 *dwc); 161 162 /** 163 * dwc3_enable_susphy - Control SUSPHY status for all USB ports 164 * @dwc: Pointer to DWC3 controller context 165 * @enable: True to enable SUSPHY, false to disable 166 * 167 * Enables or disables the USB3 PHY SUSPEND and USB2 PHY SUSPHY feature for 168 * all available ports. 169 * This is usually handled by the dwc3 core code and should only be used 170 * when skip_core_init_mode is used and the glue layer needs to manage SUSPHY 171 * settings itself, e.g., due to platform-specific requirements during mode 172 * switches. 173 */ 174 void dwc3_enable_susphy(struct dwc3 *dwc, bool enable); 175 176 /** 177 * dwc3_set_prtcap - Set the USB controller PRTCAP mode 178 * @dwc: Pointer to DWC3 controller context 179 * @mode: Target mode, must be one of DWC3_GCTL_PRTCAP_{HOST,DEVICE,OTG} 180 * @ignore_susphy: If true, skip disabling the SUSPHY and keep the current state 181 * 182 * Updates PRTCAP of the controller and current_dr_role inside the dwc3 183 * structure. For DRD controllers, this also disables SUSPHY unless explicitly 184 * told to skip via the ignore_susphy parameter. 185 * 186 * This is usually handled by the dwc3 core code and should only be used 187 * when skip_core_init_mode is used and the glue layer needs to manage mode 188 * transitions itself due to platform-specific requirements. It must be called 189 * with the correct mode before calling dwc3_host_init or dwc3_gadget_init. 190 */ 191 void dwc3_set_prtcap(struct dwc3 *dwc, u32 mode, bool ignore_susphy); 192 193 #endif 194