glue.h

  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 */
 16struct 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 */
 34struct 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 */
 54int 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 */
 64void 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 */
 72int dwc3_runtime_suspend(struct dwc3 *dwc);
 73int dwc3_runtime_resume(struct dwc3 *dwc);
 74int dwc3_runtime_idle(struct dwc3 *dwc);
 75int dwc3_pm_suspend(struct dwc3 *dwc);
 76int dwc3_pm_resume(struct dwc3 *dwc);
 77void dwc3_pm_complete(struct dwc3 *dwc);
 78int 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 */
 95int 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 */
106void 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 */
122int 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 */
133void 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 */
149int 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 */
160void 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 */
174void 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 */
191void dwc3_set_prtcap(struct dwc3 *dwc, u32 mode, bool ignore_susphy);
192
193#endif