diff mbox

[v3] usb: dwc2: Fix kernel doc's warnings.

Message ID 6bb13b8b1ce03b99e7b7246a4d3fa8110aca972e.1526457822.git.tovmasya@synopsys.com (mailing list archive)
State New, archived
Headers show

Commit Message

Grigor Tovmasyan May 16, 2018, 8:04 a.m. UTC
Added descriptions for all not described parameters.
Fix all kernel doc's warnings.

Signed-off-by: Grigor Tovmasyan <tovmasya@synopsys.com>
---
 drivers/usb/dwc2/core.c      |   7 ++
 drivers/usb/dwc2/core.h      | 170 ++++++++++++++++++++++++++++++++++---------
 drivers/usb/dwc2/debug.h     |   2 +-
 drivers/usb/dwc2/debugfs.c   |  19 ++---
 drivers/usb/dwc2/gadget.c    |  29 +++++---
 drivers/usb/dwc2/hcd.c       |   3 +-
 drivers/usb/dwc2/hcd.h       |  14 ++--
 drivers/usb/dwc2/hcd_ddma.c  |   1 +
 drivers/usb/dwc2/hcd_intr.c  |  12 +++
 drivers/usb/dwc2/hcd_queue.c |   5 +-
 drivers/usb/dwc2/params.c    |   8 ++
 drivers/usb/dwc2/pci.c       |   6 ++
 12 files changed, 215 insertions(+), 61 deletions(-)

Comments

Grigor Tovmasyan May 16, 2018, 8:07 a.m. UTC | #1
Hi Felipe,

I rebase this patch to your current testing/next (3196f73ff844)

BR,
Grigor.

On 5/16/2018 12:04 PM, Grigor Tovmasyan wrote:
> Added descriptions for all not described parameters.
> Fix all kernel doc's warnings.
> 
> Signed-off-by: Grigor Tovmasyan <tovmasya@synopsys.com>
> ---
>   drivers/usb/dwc2/core.c      |   7 ++
>   drivers/usb/dwc2/core.h      | 170 ++++++++++++++++++++++++++++++++++---------
>   drivers/usb/dwc2/debug.h     |   2 +-
>   drivers/usb/dwc2/debugfs.c   |  19 ++---
>   drivers/usb/dwc2/gadget.c    |  29 +++++---
>   drivers/usb/dwc2/hcd.c       |   3 +-
>   drivers/usb/dwc2/hcd.h       |  14 ++--
>   drivers/usb/dwc2/hcd_ddma.c  |   1 +
>   drivers/usb/dwc2/hcd_intr.c  |  12 +++
>   drivers/usb/dwc2/hcd_queue.c |   5 +-
>   drivers/usb/dwc2/params.c    |   8 ++
>   drivers/usb/dwc2/pci.c       |   6 ++
>   12 files changed, 215 insertions(+), 61 deletions(-)
> 
> diff --git a/drivers/usb/dwc2/core.c b/drivers/usb/dwc2/core.c
> index 18a0a1771289..1c36a6a9dd63 100644
> --- a/drivers/usb/dwc2/core.c
> +++ b/drivers/usb/dwc2/core.c
> @@ -419,6 +419,8 @@ static void dwc2_wait_for_mode(struct dwc2_hsotg *hsotg,
>   /**
>    * dwc2_iddig_filter_enabled() - Returns true if the IDDIG debounce
>    * filter is enabled.
> + *
> + * @hsotg: Programming view of DWC_otg controller
>    */
>   static bool dwc2_iddig_filter_enabled(struct dwc2_hsotg *hsotg)
>   {
> @@ -564,6 +566,9 @@ int dwc2_core_reset(struct dwc2_hsotg *hsotg, bool skip_wait)
>    * If a force is done, it requires a IDDIG debounce filter delay if
>    * the filter is configured and enabled. We poll the current mode of
>    * the controller to account for this delay.
> + *
> + * @hsotg: Programming view of DWC_otg controller
> + * @host: Host mode flag
>    */
>   void dwc2_force_mode(struct dwc2_hsotg *hsotg, bool host)
>   {
> @@ -610,6 +615,8 @@ void dwc2_force_mode(struct dwc2_hsotg *hsotg, bool host)
>    * or not because the value of the connector ID status is affected by
>    * the force mode. We only need to call this once during probe if
>    * dr_mode == OTG.
> + *
> + * @hsotg: Programming view of DWC_otg controller
>    */
>   static void dwc2_clear_force_mode(struct dwc2_hsotg *hsotg)
>   {
> diff --git a/drivers/usb/dwc2/core.h b/drivers/usb/dwc2/core.h
> index 2438480e4496..6d304e91c20e 100644
> --- a/drivers/usb/dwc2/core.h
> +++ b/drivers/usb/dwc2/core.h
> @@ -164,12 +164,11 @@ struct dwc2_hsotg_req;
>    *       and has yet to be completed (maybe due to data move, or simply
>    *       awaiting an ack from the core all the data has been completed).
>    * @debugfs: File entry for debugfs file for this endpoint.
> - * @lock: State lock to protect contents of endpoint.
>    * @dir_in: Set to true if this endpoint is of the IN direction, which
>    *          means that it is sending data to the Host.
>    * @index: The index for the endpoint registers.
>    * @mc: Multi Count - number of transactions per microframe
> - * @interval - Interval for periodic endpoints, in frames or microframes.
> + * @interval: Interval for periodic endpoints, in frames or microframes.
>    * @name: The name array passed to the USB core.
>    * @halted: Set if the endpoint has been halted.
>    * @periodic: Set if this is a periodic ep, such as Interrupt
> @@ -182,6 +181,7 @@ struct dwc2_hsotg_req;
>    * @compl_desc: index of next descriptor to be completed by xFerComplete
>    * @total_data: The total number of data bytes done.
>    * @fifo_size: The size of the FIFO (for periodic IN endpoints)
> + * @fifo_index: For Dedicated FIFO operation, only FIFO0 can be used for EP0.
>    * @fifo_load: The amount of data loaded into the FIFO (periodic IN)
>    * @last_load: The offset of data for the last start of request.
>    * @size_loaded: The last loaded size for DxEPTSIZE for periodic IN
> @@ -380,9 +380,12 @@ enum dwc2_ep0_state {
>    *                      is FS.
>    *                       0 - No (default)
>    *                       1 - Yes
> - * @ipg_isoc_en         Indicates the IPG supports is enabled or disabled.
> + * @ipg_isoc_en:        Indicates the IPG supports is enabled or disabled.
>    *                       0 - Disable (default)
>    *                       1 - Enable
> + * @acg_enable:		For enabling Active Clock Gating in the controller
> + *                       0 - No
> + *                       1 - Yes
>    * @ulpi_fs_ls:         Make ULPI phy operate in FS/LS mode only
>    *                       0 - No (default)
>    *                       1 - Yes
> @@ -552,7 +555,7 @@ struct dwc2_core_params {
>    *
>    * The values that are not in dwc2_core_params are documented below.
>    *
> - * @op_mode             Mode of Operation
> + * @op_mode:             Mode of Operation
>    *                       0 - HNP- and SRP-Capable OTG (Host & Device)
>    *                       1 - SRP-Capable OTG (Host & Device)
>    *                       2 - Non-HNP and Non-SRP Capable OTG (Host & Device)
> @@ -560,49 +563,102 @@ struct dwc2_core_params {
>    *                       4 - Non-OTG Device
>    *                       5 - SRP-Capable Host
>    *                       6 - Non-OTG Host
> - * @arch                Architecture
> + * @arch:                Architecture
>    *                       0 - Slave only
>    *                       1 - External DMA
>    *                       2 - Internal DMA
> - * @ipg_isoc_en         This feature indicates that the controller supports
> + * @ipg_isoc_en:        This feature indicates that the controller supports
>    *                      the worst-case scenario of Rx followed by Rx
>    *                      Interpacket Gap (IPG) (32 bitTimes) as per the utmi
>    *                      specification for any token following ISOC OUT token.
>    *                       0 - Don't support
>    *                       1 - Support
> - * @power_optimized     Are power optimizations enabled?
> - * @num_dev_ep          Number of device endpoints available
> - * @num_dev_in_eps      Number of device IN endpoints available
> - * @num_dev_perio_in_ep Number of device periodic IN endpoints
> - *                      available
> - * @dev_token_q_depth   Device Mode IN Token Sequence Learning Queue
> + * @power_optimized:    Are power optimizations enabled?
> + * @num_dev_ep:         Number of device endpoints available
> + * @num_dev_in_eps:     Number of device IN endpoints available
> + * @num_dev_perio_in_ep: Number of device periodic IN endpoints
> + *                       available
> + * @dev_token_q_depth:  Device Mode IN Token Sequence Learning Queue
>    *                      Depth
>    *                       0 to 30
> - * @host_perio_tx_q_depth
> + * @host_perio_tx_q_depth:
>    *                      Host Mode Periodic Request Queue Depth
>    *                       2, 4 or 8
> - * @nperio_tx_q_depth
> + * @nperio_tx_q_depth:
>    *                      Non-Periodic Request Queue Depth
>    *                       2, 4 or 8
> - * @hs_phy_type         High-speed PHY interface type
> + * @hs_phy_type:         High-speed PHY interface type
>    *                       0 - High-speed interface not supported
>    *                       1 - UTMI+
>    *                       2 - ULPI
>    *                       3 - UTMI+ and ULPI
> - * @fs_phy_type         Full-speed PHY interface type
> + * @fs_phy_type:         Full-speed PHY interface type
>    *                       0 - Full speed interface not supported
>    *                       1 - Dedicated full speed interface
>    *                       2 - FS pins shared with UTMI+ pins
>    *                       3 - FS pins shared with ULPI pins
>    * @total_fifo_size:    Total internal RAM for FIFOs (bytes)
> - * @hibernation		Is hibernation enabled?
> - * @utmi_phy_data_width UTMI+ PHY data width
> + * @hibernation:	Is hibernation enabled?
> + * @utmi_phy_data_width: UTMI+ PHY data width
>    *                       0 - 8 bits
>    *                       1 - 16 bits
>    *                       2 - 8 or 16 bits
>    * @snpsid:             Value from SNPSID register
>    * @dev_ep_dirs:        Direction of device endpoints (GHWCFG1)
> - * @g_tx_fifo_size[]	Power-on values of TxFIFO sizes
> + * @g_tx_fifo_size:	Power-on values of TxFIFO sizes
> + * @dma_desc_enable:    When DMA mode is enabled, specifies whether to use
> + *                      address DMA mode or descriptor DMA mode for accessing
> + *                      the data FIFOs. The driver will automatically detect the
> + *                      value for this if none is specified.
> + *                       0 - Address DMA
> + *                       1 - Descriptor DMA (default, if available)
> + * @enable_dynamic_fifo: 0 - Use coreConsultant-specified FIFO size parameters
> + *                       1 - Allow dynamic FIFO sizing (default, if available)
> + * @en_multiple_tx_fifo: Specifies whether dedicated per-endpoint transmit FIFOs
> + *                      are enabled for non-periodic IN endpoints in device
> + *                      mode.
> + * @host_nperio_tx_fifo_size: Number of 4-byte words in the non-periodic Tx FIFO
> + *                      in host mode when dynamic FIFO sizing is enabled
> + *                       16 to 32768
> + *                      Actual maximum value is autodetected and also
> + *                      the default.
> + * @host_perio_tx_fifo_size: Number of 4-byte words in the periodic Tx FIFO in
> + *                      host mode when dynamic FIFO sizing is enabled
> + *                       16 to 32768
> + *                      Actual maximum value is autodetected and also
> + *                      the default.
> + * @max_transfer_size:  The maximum transfer size supported, in bytes
> + *                       2047 to 65,535
> + *                      Actual maximum value is autodetected and also
> + *                      the default.
> + * @max_packet_count:   The maximum number of packets in a transfer
> + *                       15 to 511
> + *                      Actual maximum value is autodetected and also
> + *                      the default.
> + * @host_channels:      The number of host channel registers to use
> + *                       1 to 16
> + *                      Actual maximum value is autodetected and also
> + *                      the default.
> + * @dev_nperio_tx_fifo_size: Number of 4-byte words in the non-periodic Tx FIFO
> + *			     in device mode when dynamic FIFO sizing is enabled
> + *			     16 to 32768
> + *			     Actual maximum value is autodetected and also
> + *			     the default.
> + * @i2c_enable:         Specifies whether to use the I2Cinterface for a full
> + *                      speed PHY. This parameter is only applicable if phy_type
> + *                      is FS.
> + *                       0 - No (default)
> + *                       1 - Yes
> + * @acg_enable:		For enabling Active Clock Gating in the controller
> + *                       0 - Disable
> + *                       1 - Enable
> + * @lpm_mode:		For enabling Link Power Management in the controller
> + *                       0 - Disable
> + *                       1 - Enable
> + * @rx_fifo_size:	Number of 4-byte words in the  Rx FIFO when dynamic
> + *			FIFO sizing is enabled 16 to 32768
> + *			Actual maximum value is autodetected and also
> + *			the default.
>    */
>   struct dwc2_hw_params {
>   	unsigned op_mode:3;
> @@ -653,7 +709,11 @@ struct dwc2_hw_params {
>    * @gi2cctl:		Backup of GI2CCTL register
>    * @glpmcfg:		Backup of GLPMCFG register
>    * @gdfifocfg:		Backup of GDFIFOCFG register
> + * @pcgcctl:		Backup of PCGCCTL register
> + * @pcgcctl1:		Backup of PCGCCTL1 register
> + * @dtxfsiz:		Backup of DTXFSIZ registers for each endpoint
>    * @gpwrdn:		Backup of GPWRDN register
> + * @valid:		True if registers values backuped.
>    */
>   struct dwc2_gregs_backup {
>   	u32 gotgctl;
> @@ -686,6 +746,7 @@ struct dwc2_gregs_backup {
>    * @doeptsiz:		Backup of DOEPTSIZ register
>    * @doepdma:		Backup of DOEPDMA register
>    * @dtxfsiz:		Backup of DTXFSIZ registers for each endpoint
> + * @valid:      True if registers values backuped.
>    */
>   struct dwc2_dregs_backup {
>   	u32 dcfg;
> @@ -709,9 +770,10 @@ struct dwc2_dregs_backup {
>    * @hcfg:		Backup of HCFG register
>    * @haintmsk:		Backup of HAINTMSK register
>    * @hcintmsk:		Backup of HCINTMSK register
> - * @hptr0:		Backup of HPTR0 register
> + * @hprt0:		Backup of HPTR0 register
>    * @hfir:		Backup of HFIR register
>    * @hptxfsiz:		Backup of HPTXFSIZ register
> + * @valid:      True if registers values backuped.
>    */
>   struct dwc2_hregs_backup {
>   	u32 hcfg;
> @@ -811,7 +873,7 @@ struct dwc2_hregs_backup {
>    * @regs:		Pointer to controller regs
>    * @hw_params:          Parameters that were autodetected from the
>    *                      hardware registers
> - * @core_params:	Parameters that define how the core should be configured
> + * @params:	Parameters that define how the core should be configured
>    * @op_state:           The operational State, during transitions (a_host=>
>    *                      a_peripheral and b_device=>b_host) this may not match
>    *                      the core, but allows the software to determine
> @@ -820,9 +882,9 @@ struct dwc2_hregs_backup {
>    *                      - USB_DR_MODE_PERIPHERAL
>    *                      - USB_DR_MODE_HOST
>    *                      - USB_DR_MODE_OTG
> - * @hcd_enabled		Host mode sub-driver initialization indicator.
> - * @gadget_enabled	Peripheral mode sub-driver initialization indicator.
> - * @ll_hw_enabled	Status of low-level hardware resources.
> + * @hcd_enabled:	Host mode sub-driver initialization indicator.
> + * @gadget_enabled:	Peripheral mode sub-driver initialization indicator.
> + * @ll_hw_enabled:	Status of low-level hardware resources.
>    * @hibernated:		True if core is hibernated
>    * @frame_number:       Frame number read from the core. For both device
>    *			and host modes. The value ranges are from 0
> @@ -846,13 +908,25 @@ struct dwc2_hregs_backup {
>    *                      interrupt
>    * @wkp_timer:          Timer object for handling Wakeup Detected interrupt
>    * @lx_state:           Lx state of connected device
> - * @gregs_backup: Backup of global registers during suspend
> - * @dregs_backup: Backup of device registers during suspend
> - * @hregs_backup: Backup of host registers during suspend
> + * @gr_backup: Backup of global registers during suspend
> + * @dr_backup: Backup of device registers during suspend
> + * @hr_backup: Backup of host registers during suspend
>    *
>    * These are for host mode:
>    *
>    * @flags:              Flags for handling root port state changes
> + * @flags.d32:          Contain all root port flags
> + * @flags.b:            Separate root port flags from each other
> + * @flags.b.port_connect_status_change: True if root port connect status
> + *                      changed
> + * @flags.b.port_connect_status: True if device connected to root port
> + * @flags.b.port_reset_change: True if root port reset status changed
> + * @flags.b.port_enable_change: True if root port enable status changed
> + * @flags.b.port_suspend_change: True if root port suspend status changed
> + * @flags.b.port_over_current_change: True if root port over current state
> + *                       changed.
> + * @flags.b.port_l1_change: True if root port l1 status changed
> + * @flags.b.reserved:   Reserved bits of root port register
>    * @non_periodic_sched_inactive: Inactive QHs in the non-periodic schedule.
>    *                      Transfers associated with these QHs are not currently
>    *                      assigned to a host channel.
> @@ -861,6 +935,9 @@ struct dwc2_hregs_backup {
>    *                      assigned to a host channel.
>    * @non_periodic_qh_ptr: Pointer to next QH to process in the active
>    *                      non-periodic schedule
> + * @non_periodic_sched_waiting: Waiting QHs in the non-periodic schedule.
> + *                      Transfers associated with these QHs are not currently
> + *                      assigned to a host channel.
>    * @periodic_sched_inactive: Inactive QHs in the periodic schedule. This is a
>    *                      list of QHs for periodic transfers that are _not_
>    *                      scheduled for the next frame. Each QH in the list has an
> @@ -910,8 +987,8 @@ struct dwc2_hregs_backup {
>    *                      host channel is available for non-periodic transactions.
>    * @non_periodic_channels: Number of host channels assigned to non-periodic
>    *                      transfers
> - * @available_host_channels Number of host channels available for the microframe
> - *                      scheduler to use
> + * @available_host_channels: Number of host channels available for the
> + *			     microframe scheduler to use
>    * @hc_ptr_array:       Array of pointers to the host channel descriptors.
>    *                      Allows accessing a host channel descriptor given the
>    *                      host channel number. This is useful in interrupt
> @@ -934,9 +1011,6 @@ struct dwc2_hregs_backup {
>    * @dedicated_fifos:    Set if the hardware has dedicated IN-EP fifos.
>    * @num_of_eps:         Number of available EPs (excluding EP0)
>    * @debug_root:         Root directrory for debugfs.
> - * @debug_file:         Main status file for debugfs.
> - * @debug_testmode:     Testmode status file for debugfs.
> - * @debug_fifo:         FIFO status file for debugfs.
>    * @ep0_reply:          Request used for ep0 reply.
>    * @ep0_buff:           Buffer for EP0 reply data, if needed.
>    * @ctrl_buff:          Buffer for EP0 control requests.
> @@ -951,7 +1025,37 @@ struct dwc2_hregs_backup {
>    * @ctrl_in_desc:	EP0 IN data phase desc chain pointer
>    * @ctrl_out_desc_dma:	EP0 OUT data phase desc chain DMA address
>    * @ctrl_out_desc:	EP0 OUT data phase desc chain pointer
> - * @eps:                The endpoints being supplied to the gadget framework
> + * @irq:		Interrupt request line number
> + * @clk:		Pointer to otg clock
> + * @reset:		Pointer to dwc2 reset controller
> + * @reset_ecc:          Pointer to dwc2 optional reset controller in Stratix10.
> + * @regset:		A pointer to a struct debugfs_regset32, which contains
> + *			a pointer to an array of register definitions, the
> + *			array size and the base address where the register bank
> + *			is to be found.
> + * @bus_suspended:	True if bus is suspended
> + * @last_frame_num:	Number of last frame. Range from 0 to  32768
> + * @frame_num_array:    Used only  if CONFIG_USB_DWC2_TRACK_MISSED_SOFS is
> + *			defined, for missed SOFs tracking. Array holds that
> + *			frame numbers, which not equal to last_frame_num +1
> + * @last_frame_num_array:   Used only  if CONFIG_USB_DWC2_TRACK_MISSED_SOFS is
> + *			    defined, for missed SOFs tracking.
> + *			    If current_frame_number != last_frame_num+1
> + *			    then last_frame_num added to this array
> + * @frame_num_idx:	Actual size of frame_num_array and last_frame_num_array
> + * @dumped_frame_num_array:	1 - if missed SOFs frame numbers dumbed
> + *				0 - if missed SOFs frame numbers not dumbed
> + * @fifo_mem:			Total internal RAM for FIFOs (bytes)
> + * @fifo_map:		Each bit intend for concrete fifo. If that bit is set,
> + *			then that fifo is used
> + * @gadget:		Represents a usb slave device
> + * @connected:		Used in slave mode. True if device connected with host
> + * @eps_in:		The IN endpoints being supplied to the gadget framework
> + * @eps_out:		The OUT endpoints being supplied to the gadget framework
> + * @new_connection:	Used in host mode. True if there are new connected
> + *			device
> + * @enabled:		Indicates the enabling state of controller
> + *
>    */
>   struct dwc2_hsotg {
>   	struct device *dev;
> diff --git a/drivers/usb/dwc2/debug.h b/drivers/usb/dwc2/debug.h
> index 6f23219c13cb..a8c565b6bc34 100644
> --- a/drivers/usb/dwc2/debug.h
> +++ b/drivers/usb/dwc2/debug.h
> @@ -1,5 +1,5 @@
>   // SPDX-License-Identifier: GPL-2.0
> -/**
> +/*
>    * debug.h - Designware USB2 DRD controller debug header
>    *
>    * Copyright (C) 2015 Intel Corporation
> diff --git a/drivers/usb/dwc2/debugfs.c b/drivers/usb/dwc2/debugfs.c
> index a21f89354434..7e6618ad9f21 100644
> --- a/drivers/usb/dwc2/debugfs.c
> +++ b/drivers/usb/dwc2/debugfs.c
> @@ -1,5 +1,5 @@
>   // SPDX-License-Identifier: GPL-2.0
> -/**
> +/*
>    * debugfs.c - Designware USB2 DRD controller debugfs
>    *
>    * Copyright (C) 2015 Intel Corporation
> @@ -16,12 +16,13 @@
>   
>   #if IS_ENABLED(CONFIG_USB_DWC2_PERIPHERAL) || \
>   	IS_ENABLED(CONFIG_USB_DWC2_DUAL_ROLE)
> +
>   /**
> - * testmode_write - debugfs: change usb test mode
> - * @seq: The seq file to write to.
> - * @v: Unused parameter.
> - *
> - * This debugfs entry modify the current usb test mode.
> + * testmode_write() - change usb test mode state.
> + * @file: The  file to write to.
> + * @ubuf: The buffer where user wrote.
> + * @count: The ubuf size.
> + * @ppos: Unused parameter.
>    */
>   static ssize_t testmode_write(struct file *file, const char __user *ubuf, size_t
>   		count, loff_t *ppos)
> @@ -55,9 +56,9 @@ static ssize_t testmode_write(struct file *file, const char __user *ubuf, size_t
>   }
>   
>   /**
> - * testmode_show - debugfs: show usb test mode state
> - * @seq: The seq file to write to.
> - * @v: Unused parameter.
> + * testmode_show() - debugfs: show usb test mode state
> + * @s: The seq file to write to.
> + * @unused: Unused parameter.
>    *
>    * This debugfs entry shows which usb test mode is currently enabled.
>    */
> diff --git a/drivers/usb/dwc2/gadget.c b/drivers/usb/dwc2/gadget.c
> index d0f2993125aa..93e59e4e5d9e 100644
> --- a/drivers/usb/dwc2/gadget.c
> +++ b/drivers/usb/dwc2/gadget.c
> @@ -1,5 +1,5 @@
>   // SPDX-License-Identifier: GPL-2.0
> -/**
> +/*
>    * Copyright (c) 2011 Samsung Electronics Co., Ltd.
>    *		http://www.samsung.com
>    *
> @@ -107,7 +107,6 @@ static inline bool using_desc_dma(struct dwc2_hsotg *hsotg)
>   /**
>    * dwc2_gadget_incr_frame_num - Increments the targeted frame number.
>    * @hs_ep: The endpoint
> - * @increment: The value to increment by
>    *
>    * This function will also check if the frame number overruns DSTS_SOFFN_LIMIT.
>    * If an overrun occurs it will wrap the value and set the frame_overrun flag.
> @@ -190,6 +189,8 @@ static void dwc2_hsotg_ctrl_epint(struct dwc2_hsotg *hsotg,
>   
>   /**
>    * dwc2_hsotg_tx_fifo_count - return count of TX FIFOs in device mode
> + *
> + * @hsotg: Programming view of the DWC_otg controller
>    */
>   int dwc2_hsotg_tx_fifo_count(struct dwc2_hsotg *hsotg)
>   {
> @@ -204,6 +205,8 @@ int dwc2_hsotg_tx_fifo_count(struct dwc2_hsotg *hsotg)
>   /**
>    * dwc2_hsotg_tx_fifo_total_depth - return total FIFO depth available for
>    * device mode TX FIFOs
> + *
> + * @hsotg: Programming view of the DWC_otg controller
>    */
>   int dwc2_hsotg_tx_fifo_total_depth(struct dwc2_hsotg *hsotg)
>   {
> @@ -227,6 +230,8 @@ int dwc2_hsotg_tx_fifo_total_depth(struct dwc2_hsotg *hsotg)
>   /**
>    * dwc2_hsotg_tx_fifo_average_depth - returns average depth of device mode
>    * TX FIFOs
> + *
> + * @hsotg: Programming view of the DWC_otg controller
>    */
>   int dwc2_hsotg_tx_fifo_average_depth(struct dwc2_hsotg *hsotg)
>   {
> @@ -327,6 +332,7 @@ static void dwc2_hsotg_init_fifo(struct dwc2_hsotg *hsotg)
>   }
>   
>   /**
> + * dwc2_hsotg_ep_alloc_request - allocate USB rerequest structure
>    * @ep: USB endpoint to allocate request for.
>    * @flags: Allocation flags
>    *
> @@ -2424,6 +2430,7 @@ static u32 dwc2_hsotg_ep0_mps(unsigned int mps)
>    * @ep: The index number of the endpoint
>    * @mps: The maximum packet size in bytes
>    * @mc: The multicount value
> + * @dir_in: True if direction is in.
>    *
>    * Configure the maximum packet size for the given endpoint, updating
>    * the hardware control registers to reflect this.
> @@ -2723,7 +2730,7 @@ static void dwc2_gadget_handle_ep_disabled(struct dwc2_hsotg_ep *hs_ep)
>   
>   /**
>    * dwc2_gadget_handle_out_token_ep_disabled - handle DXEPINT_OUTTKNEPDIS
> - * @hs_ep: The endpoint on which interrupt is asserted.
> + * @ep: The endpoint on which interrupt is asserted.
>    *
>    * This is starting point for ISOC-OUT transfer, synchronization done with
>    * first out token received from host while corresponding EP is disabled.
> @@ -3183,6 +3190,7 @@ static void dwc2_hsotg_irq_fifoempty(struct dwc2_hsotg *hsotg, bool periodic)
>   /**
>    * dwc2_hsotg_core_init - issue softreset to the core
>    * @hsotg: The device state
> + * @is_usb_reset: Usb resetting flag
>    *
>    * Issue a soft reset to the core, and await the core finishing it.
>    */
> @@ -4289,7 +4297,6 @@ static int dwc2_hsotg_udc_start(struct usb_gadget *gadget,
>   /**
>    * dwc2_hsotg_udc_stop - stop the udc
>    * @gadget: The usb gadget state
> - * @driver: The usb gadget driver
>    *
>    * Stop udc hw block and stay tunned for future transmissions
>    */
> @@ -4441,6 +4448,7 @@ static const struct usb_gadget_ops dwc2_hsotg_gadget_ops = {
>    * @hsotg: The device state.
>    * @hs_ep: The endpoint to be initialised.
>    * @epnum: The endpoint number
> + * @dir_in: True if direction is in.
>    *
>    * Initialise the given endpoint (as part of the probe and device state
>    * creation) to give to the gadget driver. Setup the endpoint name, any
> @@ -4514,7 +4522,7 @@ static void dwc2_hsotg_initep(struct dwc2_hsotg *hsotg,
>   
>   /**
>    * dwc2_hsotg_hw_cfg - read HW configuration registers
> - * @param: The device state
> + * @hsotg: Programming view of the DWC_otg controller
>    *
>    * Read the USB core HW configuration registers
>    */
> @@ -4570,7 +4578,8 @@ static int dwc2_hsotg_hw_cfg(struct dwc2_hsotg *hsotg)
>   
>   /**
>    * dwc2_hsotg_dump - dump state of the udc
> - * @param: The device state
> + * @hsotg: Programming view of the DWC_otg controller
> + *
>    */
>   static void dwc2_hsotg_dump(struct dwc2_hsotg *hsotg)
>   {
> @@ -4621,7 +4630,8 @@ static void dwc2_hsotg_dump(struct dwc2_hsotg *hsotg)
>   
>   /**
>    * dwc2_gadget_init - init function for gadget
> - * @dwc2: The data structure for the DWC2 driver.
> + * @hsotg: Programming view of the DWC_otg controller
> + *
>    */
>   int dwc2_gadget_init(struct dwc2_hsotg *hsotg)
>   {
> @@ -4718,7 +4728,8 @@ int dwc2_gadget_init(struct dwc2_hsotg *hsotg)
>   
>   /**
>    * dwc2_hsotg_remove - remove function for hsotg driver
> - * @pdev: The platform information for the driver
> + * @hsotg: Programming view of the DWC_otg controller
> + *
>    */
>   int dwc2_hsotg_remove(struct dwc2_hsotg *hsotg)
>   {
> @@ -4999,7 +5010,7 @@ int dwc2_gadget_enter_hibernation(struct dwc2_hsotg *hsotg)
>    *
>    * @hsotg: Programming view of the DWC_otg controller
>    * @rem_wakeup: indicates whether resume is initiated by Device or Host.
> - * @param reset: indicates whether resume is initiated by Reset.
> + * @reset: indicates whether resume is initiated by Reset.
>    *
>    * Return non-zero if failed to exit from hibernation.
>    */
> diff --git a/drivers/usb/dwc2/hcd.c b/drivers/usb/dwc2/hcd.c
> index 190f95964000..0ccd4b21f973 100644
> --- a/drivers/usb/dwc2/hcd.c
> +++ b/drivers/usb/dwc2/hcd.c
> @@ -592,7 +592,7 @@ u32 dwc2_calc_frame_interval(struct dwc2_hsotg *hsotg)
>    * dwc2_read_packet() - Reads a packet from the Rx FIFO into the destination
>    * buffer
>    *
> - * @core_if: Programming view of DWC_otg controller
> + * @hsotg: Programming view of DWC_otg controller
>    * @dest:    Destination buffer for the packet
>    * @bytes:   Number of bytes to copy to the destination
>    */
> @@ -4082,7 +4082,6 @@ static struct dwc2_hsotg *dwc2_hcd_to_hsotg(struct usb_hcd *hcd)
>    * then the refcount for the structure will go to 0 and we'll free it.
>    *
>    * @hsotg:     The HCD state structure for the DWC OTG controller.
> - * @qh:        The QH structure.
>    * @context:   The priv pointer from a struct dwc2_hcd_urb.
>    * @mem_flags: Flags for allocating memory.
>    * @ttport:    We'll return this device's port number here.  That's used to
> diff --git a/drivers/usb/dwc2/hcd.h b/drivers/usb/dwc2/hcd.h
> index 96a9da5fb202..7db1ee7e7a77 100644
> --- a/drivers/usb/dwc2/hcd.h
> +++ b/drivers/usb/dwc2/hcd.h
> @@ -80,7 +80,7 @@ struct dwc2_qh;
>    * @xfer_count:         Number of bytes transferred so far
>    * @start_pkt_count:    Packet count at start of transfer
>    * @xfer_started:       True if the transfer has been started
> - * @ping:               True if a PING request should be issued on this channel
> + * @do_ping:            True if a PING request should be issued on this channel
>    * @error_state:        True if the error count for this transaction is non-zero
>    * @halt_on_queue:      True if this channel should be halted the next time a
>    *                      request is queued for the channel. This is necessary in
> @@ -102,7 +102,7 @@ struct dwc2_qh;
>    * @schinfo:            Scheduling micro-frame bitmap
>    * @ntd:                Number of transfer descriptors for the transfer
>    * @halt_status:        Reason for halting the host channel
> - * @hcint               Contents of the HCINT register when the interrupt came
> + * @hcint:               Contents of the HCINT register when the interrupt came
>    * @qh:                 QH for the transfer being processed by this channel
>    * @hc_list_entry:      For linking to list of host channels
>    * @desc_list_addr:     Current QH's descriptor list DMA address
> @@ -237,7 +237,7 @@ struct dwc2_tt {
>   /**
>    * struct dwc2_hs_transfer_time - Info about a transfer on the high speed bus.
>    *
> - * @start_schedule_usecs:  The start time on the main bus schedule.  Note that
> + * @start_schedule_us:  The start time on the main bus schedule.  Note that
>    *                         the main bus schedule is tightly packed and this
>    *			   time should be interpreted as tightly packed (so
>    *			   uFrame 0 starts at 0 us, uFrame 1 starts at 100 us
> @@ -301,7 +301,6 @@ struct dwc2_hs_transfer_time {
>    *                           "struct dwc2_tt".  Not used if this device is high
>    *                           speed.  Note that this is in "schedule slice" which
>    *                           is tightly packed.
> - * @ls_duration_us:     Duration on the low speed bus schedule.
>    * @ntd:                Actual number of transfer descriptors in a list
>    * @qtd_list:           List of QTDs for this QH
>    * @channel:            Host channel currently processing transfers for this QH
> @@ -315,7 +314,7 @@ struct dwc2_hs_transfer_time {
>    *                      descriptor
>    * @unreserve_timer:    Timer for releasing periodic reservation.
>    * @wait_timer:         Timer used to wait before re-queuing.
> - * @dwc2_tt:            Pointer to our tt info (or NULL if no tt).
> + * @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
>    * @unreserve_pending:  True if we planned to unreserve but haven't yet.
> @@ -325,6 +324,7 @@ struct dwc2_hs_transfer_time {
>    *                      periodic transfers and is ignored for periodic ones.
>    * @wait_timer_cancel:  Set to true to cancel the wait_timer.
>    *
> + * @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.
> @@ -400,6 +400,10 @@ struct dwc2_qh {
>    * @urb:                URB for this transfer
>    * @qh:                 Queue head for this QTD
>    * @qtd_list_entry:     For linking to the QH's list of QTDs
> + * @isoc_td_first:	Index of first activated isochronous transfer
> + *			descriptor in Descriptor DMA mode
> + * @isoc_td_last:	Index of last activated isochronous transfer
> + *			descriptor in Descriptor DMA mode
>    *
>    * A Queue Transfer Descriptor (QTD) holds the state of a bulk, control,
>    * interrupt, or isochronous transfer. A single QTD is created for each URB
> diff --git a/drivers/usb/dwc2/hcd_ddma.c b/drivers/usb/dwc2/hcd_ddma.c
> index 28c8898b3b66..74f11c823f79 100644
> --- a/drivers/usb/dwc2/hcd_ddma.c
> +++ b/drivers/usb/dwc2/hcd_ddma.c
> @@ -332,6 +332,7 @@ static void dwc2_release_channel_ddma(struct dwc2_hsotg *hsotg,
>    *
>    * @hsotg: The HCD state structure for the DWC OTG controller
>    * @qh:    The QH to init
> + * @mem_flags: Indicates the type of memory allocation
>    *
>    * Return: 0 if successful, negative error code otherwise
>    *
> diff --git a/drivers/usb/dwc2/hcd_intr.c b/drivers/usb/dwc2/hcd_intr.c
> index a5dfd9d8bd9a..fbea5e3fb947 100644
> --- a/drivers/usb/dwc2/hcd_intr.c
> +++ b/drivers/usb/dwc2/hcd_intr.c
> @@ -478,6 +478,12 @@ static u32 dwc2_get_actual_xfer_length(struct dwc2_hsotg *hsotg,
>    * of the URB based on the number of bytes transferred via the host channel.
>    * Sets the URB status if the data transfer is finished.
>    *
> + * @hsotg: Programming view of the DWC_otg controller
> + * @chan: Programming view of host channel
> + * @chnum: Channel number
> + * @urb: Processing URB
> + * @qtd: Queue transfer descriptor
> + *
>    * Return: 1 if the data transfer specified by the URB is completely finished,
>    * 0 otherwise
>    */
> @@ -566,6 +572,12 @@ void dwc2_hcd_save_data_toggle(struct dwc2_hsotg *hsotg,
>    * halt_status. Completes the Isochronous URB if all the URB frames have been
>    * completed.
>    *
> + * @hsotg: Programming view of the DWC_otg controller
> + * @chan: Programming view of host channel
> + * @chnum: Channel number
> + * @halt_status: Reason for halting a host channel
> + * @qtd: Queue transfer descriptor
> + *
>    * Return: DWC2_HC_XFER_COMPLETE if there are more frames remaining to be
>    * transferred in the URB. Otherwise return DWC2_HC_XFER_URB_COMPLETE.
>    */
> diff --git a/drivers/usb/dwc2/hcd_queue.c b/drivers/usb/dwc2/hcd_queue.c
> index e34ad5e65350..d7c3d6c776d8 100644
> --- a/drivers/usb/dwc2/hcd_queue.c
> +++ b/drivers/usb/dwc2/hcd_queue.c
> @@ -679,6 +679,7 @@ static int dwc2_hs_pmap_schedule(struct dwc2_hsotg *hsotg, struct dwc2_qh *qh,
>    *
>    * @hsotg:       The HCD state structure for the DWC OTG controller.
>    * @qh:          QH for the periodic transfer.
> + * @index:       Transfer index
>    */
>   static void dwc2_hs_pmap_unschedule(struct dwc2_hsotg *hsotg,
>   				    struct dwc2_qh *qh, int index)
> @@ -1276,7 +1277,7 @@ static void dwc2_do_unreserve(struct dwc2_hsotg *hsotg, struct dwc2_qh *qh)
>    * release the reservation.  This worker is called after the appropriate
>    * delay.
>    *
> - * @work: Pointer to a qh unreserve_work.
> + * @t: Address to a qh unreserve_work.
>    */
>   static void dwc2_unreserve_timer_fn(struct timer_list *t)
>   {
> @@ -1631,7 +1632,7 @@ static void dwc2_qh_init(struct dwc2_hsotg *hsotg, struct dwc2_qh *qh,
>    * @hsotg:        The HCD state structure for the DWC OTG controller
>    * @urb:          Holds the information about the device/endpoint needed
>    *                to initialize the QH
> - * @atomic_alloc: Flag to do atomic allocation if needed
> + * @mem_flags:   Flags for allocating memory.
>    *
>    * Return: Pointer to the newly allocated QH, or NULL on error
>    */
> diff --git a/drivers/usb/dwc2/params.c b/drivers/usb/dwc2/params.c
> index 2700f5279285..b43d8c6a749d 100644
> --- a/drivers/usb/dwc2/params.c
> +++ b/drivers/usb/dwc2/params.c
> @@ -269,6 +269,9 @@ static void dwc2_set_param_power_down(struct dwc2_hsotg *hsotg)
>   /**
>    * dwc2_set_default_params() - Set all core parameters to their
>    * auto-detected default values.
> + *
> + * @hsotg: Programming view of the DWC_otg controller
> + *
>    */
>   static void dwc2_set_default_params(struct dwc2_hsotg *hsotg)
>   {
> @@ -339,6 +342,8 @@ static void dwc2_set_default_params(struct dwc2_hsotg *hsotg)
>   /**
>    * dwc2_get_device_properties() - Read in device properties.
>    *
> + * @hsotg: Programming view of the DWC_otg controller
> + *
>    * Read in the device properties and adjust core parameters if needed.
>    */
>   static void dwc2_get_device_properties(struct dwc2_hsotg *hsotg)
> @@ -690,6 +695,9 @@ static void dwc2_get_dev_hwparams(struct dwc2_hsotg *hsotg)
>   /**
>    * During device initialization, read various hardware configuration
>    * registers and interpret the contents.
> + *
> + * @hsotg: Programming view of the DWC_otg controller
> + *
>    */
>   int dwc2_get_hwparams(struct dwc2_hsotg *hsotg)
>   {
> diff --git a/drivers/usb/dwc2/pci.c b/drivers/usb/dwc2/pci.c
> index 7f21747007f1..e9e26f021a89 100644
> --- a/drivers/usb/dwc2/pci.c
> +++ b/drivers/usb/dwc2/pci.c
> @@ -77,6 +77,12 @@ static int dwc2_pci_quirks(struct pci_dev *pdev, struct platform_device *dwc2)
>   	return 0;
>   }
>   
> +/**
> + * dwc2_pci_probe() - Provides the cleanup entry points for the DWC_otg PCI
> + * driver
> + *
> + * @pci: The programming view of DWC_otg PCI
> + */
>   static void dwc2_pci_remove(struct pci_dev *pci)
>   {
>   	struct dwc2_pci_glue *glue = pci_get_drvdata(pci);
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Minas Harutyunyan May 17, 2018, 5:34 a.m. UTC | #2
On 5/16/2018 12:04 PM, Grigor Tovmasyan wrote:
> Added descriptions for all not described parameters.
> Fix all kernel doc's warnings.
> 
> Signed-off-by: Grigor Tovmasyan <tovmasya@synopsys.com>
> ---

Acked-by: Minas Harutyunyan <hminas@synopsys.com>

>   drivers/usb/dwc2/core.c      |   7 ++
>   drivers/usb/dwc2/core.h      | 170 ++++++++++++++++++++++++++++++++++---------
>   drivers/usb/dwc2/debug.h     |   2 +-
>   drivers/usb/dwc2/debugfs.c   |  19 ++---
>   drivers/usb/dwc2/gadget.c    |  29 +++++---
>   drivers/usb/dwc2/hcd.c       |   3 +-
>   drivers/usb/dwc2/hcd.h       |  14 ++--
>   drivers/usb/dwc2/hcd_ddma.c  |   1 +
>   drivers/usb/dwc2/hcd_intr.c  |  12 +++
>   drivers/usb/dwc2/hcd_queue.c |   5 +-
>   drivers/usb/dwc2/params.c    |   8 ++
>   drivers/usb/dwc2/pci.c       |   6 ++
>   12 files changed, 215 insertions(+), 61 deletions(-)
> 
> diff --git a/drivers/usb/dwc2/core.c b/drivers/usb/dwc2/core.c
> index 18a0a1771289..1c36a6a9dd63 100644
> --- a/drivers/usb/dwc2/core.c
> +++ b/drivers/usb/dwc2/core.c
> @@ -419,6 +419,8 @@ static void dwc2_wait_for_mode(struct dwc2_hsotg *hsotg,
>   /**
>    * dwc2_iddig_filter_enabled() - Returns true if the IDDIG debounce
>    * filter is enabled.
> + *
> + * @hsotg: Programming view of DWC_otg controller
>    */
>   static bool dwc2_iddig_filter_enabled(struct dwc2_hsotg *hsotg)
>   {
> @@ -564,6 +566,9 @@ int dwc2_core_reset(struct dwc2_hsotg *hsotg, bool skip_wait)
>    * If a force is done, it requires a IDDIG debounce filter delay if
>    * the filter is configured and enabled. We poll the current mode of
>    * the controller to account for this delay.
> + *
> + * @hsotg: Programming view of DWC_otg controller
> + * @host: Host mode flag
>    */
>   void dwc2_force_mode(struct dwc2_hsotg *hsotg, bool host)
>   {
> @@ -610,6 +615,8 @@ void dwc2_force_mode(struct dwc2_hsotg *hsotg, bool host)
>    * or not because the value of the connector ID status is affected by
>    * the force mode. We only need to call this once during probe if
>    * dr_mode == OTG.
> + *
> + * @hsotg: Programming view of DWC_otg controller
>    */
>   static void dwc2_clear_force_mode(struct dwc2_hsotg *hsotg)
>   {
> diff --git a/drivers/usb/dwc2/core.h b/drivers/usb/dwc2/core.h
> index 2438480e4496..6d304e91c20e 100644
> --- a/drivers/usb/dwc2/core.h
> +++ b/drivers/usb/dwc2/core.h
> @@ -164,12 +164,11 @@ struct dwc2_hsotg_req;
>    *       and has yet to be completed (maybe due to data move, or simply
>    *       awaiting an ack from the core all the data has been completed).
>    * @debugfs: File entry for debugfs file for this endpoint.
> - * @lock: State lock to protect contents of endpoint.
>    * @dir_in: Set to true if this endpoint is of the IN direction, which
>    *          means that it is sending data to the Host.
>    * @index: The index for the endpoint registers.
>    * @mc: Multi Count - number of transactions per microframe
> - * @interval - Interval for periodic endpoints, in frames or microframes.
> + * @interval: Interval for periodic endpoints, in frames or microframes.
>    * @name: The name array passed to the USB core.
>    * @halted: Set if the endpoint has been halted.
>    * @periodic: Set if this is a periodic ep, such as Interrupt
> @@ -182,6 +181,7 @@ struct dwc2_hsotg_req;
>    * @compl_desc: index of next descriptor to be completed by xFerComplete
>    * @total_data: The total number of data bytes done.
>    * @fifo_size: The size of the FIFO (for periodic IN endpoints)
> + * @fifo_index: For Dedicated FIFO operation, only FIFO0 can be used for EP0.
>    * @fifo_load: The amount of data loaded into the FIFO (periodic IN)
>    * @last_load: The offset of data for the last start of request.
>    * @size_loaded: The last loaded size for DxEPTSIZE for periodic IN
> @@ -380,9 +380,12 @@ enum dwc2_ep0_state {
>    *                      is FS.
>    *                       0 - No (default)
>    *                       1 - Yes
> - * @ipg_isoc_en         Indicates the IPG supports is enabled or disabled.
> + * @ipg_isoc_en:        Indicates the IPG supports is enabled or disabled.
>    *                       0 - Disable (default)
>    *                       1 - Enable
> + * @acg_enable:		For enabling Active Clock Gating in the controller
> + *                       0 - No
> + *                       1 - Yes
>    * @ulpi_fs_ls:         Make ULPI phy operate in FS/LS mode only
>    *                       0 - No (default)
>    *                       1 - Yes
> @@ -552,7 +555,7 @@ struct dwc2_core_params {
>    *
>    * The values that are not in dwc2_core_params are documented below.
>    *
> - * @op_mode             Mode of Operation
> + * @op_mode:             Mode of Operation
>    *                       0 - HNP- and SRP-Capable OTG (Host & Device)
>    *                       1 - SRP-Capable OTG (Host & Device)
>    *                       2 - Non-HNP and Non-SRP Capable OTG (Host & Device)
> @@ -560,49 +563,102 @@ struct dwc2_core_params {
>    *                       4 - Non-OTG Device
>    *                       5 - SRP-Capable Host
>    *                       6 - Non-OTG Host
> - * @arch                Architecture
> + * @arch:                Architecture
>    *                       0 - Slave only
>    *                       1 - External DMA
>    *                       2 - Internal DMA
> - * @ipg_isoc_en         This feature indicates that the controller supports
> + * @ipg_isoc_en:        This feature indicates that the controller supports
>    *                      the worst-case scenario of Rx followed by Rx
>    *                      Interpacket Gap (IPG) (32 bitTimes) as per the utmi
>    *                      specification for any token following ISOC OUT token.
>    *                       0 - Don't support
>    *                       1 - Support
> - * @power_optimized     Are power optimizations enabled?
> - * @num_dev_ep          Number of device endpoints available
> - * @num_dev_in_eps      Number of device IN endpoints available
> - * @num_dev_perio_in_ep Number of device periodic IN endpoints
> - *                      available
> - * @dev_token_q_depth   Device Mode IN Token Sequence Learning Queue
> + * @power_optimized:    Are power optimizations enabled?
> + * @num_dev_ep:         Number of device endpoints available
> + * @num_dev_in_eps:     Number of device IN endpoints available
> + * @num_dev_perio_in_ep: Number of device periodic IN endpoints
> + *                       available
> + * @dev_token_q_depth:  Device Mode IN Token Sequence Learning Queue
>    *                      Depth
>    *                       0 to 30
> - * @host_perio_tx_q_depth
> + * @host_perio_tx_q_depth:
>    *                      Host Mode Periodic Request Queue Depth
>    *                       2, 4 or 8
> - * @nperio_tx_q_depth
> + * @nperio_tx_q_depth:
>    *                      Non-Periodic Request Queue Depth
>    *                       2, 4 or 8
> - * @hs_phy_type         High-speed PHY interface type
> + * @hs_phy_type:         High-speed PHY interface type
>    *                       0 - High-speed interface not supported
>    *                       1 - UTMI+
>    *                       2 - ULPI
>    *                       3 - UTMI+ and ULPI
> - * @fs_phy_type         Full-speed PHY interface type
> + * @fs_phy_type:         Full-speed PHY interface type
>    *                       0 - Full speed interface not supported
>    *                       1 - Dedicated full speed interface
>    *                       2 - FS pins shared with UTMI+ pins
>    *                       3 - FS pins shared with ULPI pins
>    * @total_fifo_size:    Total internal RAM for FIFOs (bytes)
> - * @hibernation		Is hibernation enabled?
> - * @utmi_phy_data_width UTMI+ PHY data width
> + * @hibernation:	Is hibernation enabled?
> + * @utmi_phy_data_width: UTMI+ PHY data width
>    *                       0 - 8 bits
>    *                       1 - 16 bits
>    *                       2 - 8 or 16 bits
>    * @snpsid:             Value from SNPSID register
>    * @dev_ep_dirs:        Direction of device endpoints (GHWCFG1)
> - * @g_tx_fifo_size[]	Power-on values of TxFIFO sizes
> + * @g_tx_fifo_size:	Power-on values of TxFIFO sizes
> + * @dma_desc_enable:    When DMA mode is enabled, specifies whether to use
> + *                      address DMA mode or descriptor DMA mode for accessing
> + *                      the data FIFOs. The driver will automatically detect the
> + *                      value for this if none is specified.
> + *                       0 - Address DMA
> + *                       1 - Descriptor DMA (default, if available)
> + * @enable_dynamic_fifo: 0 - Use coreConsultant-specified FIFO size parameters
> + *                       1 - Allow dynamic FIFO sizing (default, if available)
> + * @en_multiple_tx_fifo: Specifies whether dedicated per-endpoint transmit FIFOs
> + *                      are enabled for non-periodic IN endpoints in device
> + *                      mode.
> + * @host_nperio_tx_fifo_size: Number of 4-byte words in the non-periodic Tx FIFO
> + *                      in host mode when dynamic FIFO sizing is enabled
> + *                       16 to 32768
> + *                      Actual maximum value is autodetected and also
> + *                      the default.
> + * @host_perio_tx_fifo_size: Number of 4-byte words in the periodic Tx FIFO in
> + *                      host mode when dynamic FIFO sizing is enabled
> + *                       16 to 32768
> + *                      Actual maximum value is autodetected and also
> + *                      the default.
> + * @max_transfer_size:  The maximum transfer size supported, in bytes
> + *                       2047 to 65,535
> + *                      Actual maximum value is autodetected and also
> + *                      the default.
> + * @max_packet_count:   The maximum number of packets in a transfer
> + *                       15 to 511
> + *                      Actual maximum value is autodetected and also
> + *                      the default.
> + * @host_channels:      The number of host channel registers to use
> + *                       1 to 16
> + *                      Actual maximum value is autodetected and also
> + *                      the default.
> + * @dev_nperio_tx_fifo_size: Number of 4-byte words in the non-periodic Tx FIFO
> + *			     in device mode when dynamic FIFO sizing is enabled
> + *			     16 to 32768
> + *			     Actual maximum value is autodetected and also
> + *			     the default.
> + * @i2c_enable:         Specifies whether to use the I2Cinterface for a full
> + *                      speed PHY. This parameter is only applicable if phy_type
> + *                      is FS.
> + *                       0 - No (default)
> + *                       1 - Yes
> + * @acg_enable:		For enabling Active Clock Gating in the controller
> + *                       0 - Disable
> + *                       1 - Enable
> + * @lpm_mode:		For enabling Link Power Management in the controller
> + *                       0 - Disable
> + *                       1 - Enable
> + * @rx_fifo_size:	Number of 4-byte words in the  Rx FIFO when dynamic
> + *			FIFO sizing is enabled 16 to 32768
> + *			Actual maximum value is autodetected and also
> + *			the default.
>    */
>   struct dwc2_hw_params {
>   	unsigned op_mode:3;
> @@ -653,7 +709,11 @@ struct dwc2_hw_params {
>    * @gi2cctl:		Backup of GI2CCTL register
>    * @glpmcfg:		Backup of GLPMCFG register
>    * @gdfifocfg:		Backup of GDFIFOCFG register
> + * @pcgcctl:		Backup of PCGCCTL register
> + * @pcgcctl1:		Backup of PCGCCTL1 register
> + * @dtxfsiz:		Backup of DTXFSIZ registers for each endpoint
>    * @gpwrdn:		Backup of GPWRDN register
> + * @valid:		True if registers values backuped.
>    */
>   struct dwc2_gregs_backup {
>   	u32 gotgctl;
> @@ -686,6 +746,7 @@ struct dwc2_gregs_backup {
>    * @doeptsiz:		Backup of DOEPTSIZ register
>    * @doepdma:		Backup of DOEPDMA register
>    * @dtxfsiz:		Backup of DTXFSIZ registers for each endpoint
> + * @valid:      True if registers values backuped.
>    */
>   struct dwc2_dregs_backup {
>   	u32 dcfg;
> @@ -709,9 +770,10 @@ struct dwc2_dregs_backup {
>    * @hcfg:		Backup of HCFG register
>    * @haintmsk:		Backup of HAINTMSK register
>    * @hcintmsk:		Backup of HCINTMSK register
> - * @hptr0:		Backup of HPTR0 register
> + * @hprt0:		Backup of HPTR0 register
>    * @hfir:		Backup of HFIR register
>    * @hptxfsiz:		Backup of HPTXFSIZ register
> + * @valid:      True if registers values backuped.
>    */
>   struct dwc2_hregs_backup {
>   	u32 hcfg;
> @@ -811,7 +873,7 @@ struct dwc2_hregs_backup {
>    * @regs:		Pointer to controller regs
>    * @hw_params:          Parameters that were autodetected from the
>    *                      hardware registers
> - * @core_params:	Parameters that define how the core should be configured
> + * @params:	Parameters that define how the core should be configured
>    * @op_state:           The operational State, during transitions (a_host=>
>    *                      a_peripheral and b_device=>b_host) this may not match
>    *                      the core, but allows the software to determine
> @@ -820,9 +882,9 @@ struct dwc2_hregs_backup {
>    *                      - USB_DR_MODE_PERIPHERAL
>    *                      - USB_DR_MODE_HOST
>    *                      - USB_DR_MODE_OTG
> - * @hcd_enabled		Host mode sub-driver initialization indicator.
> - * @gadget_enabled	Peripheral mode sub-driver initialization indicator.
> - * @ll_hw_enabled	Status of low-level hardware resources.
> + * @hcd_enabled:	Host mode sub-driver initialization indicator.
> + * @gadget_enabled:	Peripheral mode sub-driver initialization indicator.
> + * @ll_hw_enabled:	Status of low-level hardware resources.
>    * @hibernated:		True if core is hibernated
>    * @frame_number:       Frame number read from the core. For both device
>    *			and host modes. The value ranges are from 0
> @@ -846,13 +908,25 @@ struct dwc2_hregs_backup {
>    *                      interrupt
>    * @wkp_timer:          Timer object for handling Wakeup Detected interrupt
>    * @lx_state:           Lx state of connected device
> - * @gregs_backup: Backup of global registers during suspend
> - * @dregs_backup: Backup of device registers during suspend
> - * @hregs_backup: Backup of host registers during suspend
> + * @gr_backup: Backup of global registers during suspend
> + * @dr_backup: Backup of device registers during suspend
> + * @hr_backup: Backup of host registers during suspend
>    *
>    * These are for host mode:
>    *
>    * @flags:              Flags for handling root port state changes
> + * @flags.d32:          Contain all root port flags
> + * @flags.b:            Separate root port flags from each other
> + * @flags.b.port_connect_status_change: True if root port connect status
> + *                      changed
> + * @flags.b.port_connect_status: True if device connected to root port
> + * @flags.b.port_reset_change: True if root port reset status changed
> + * @flags.b.port_enable_change: True if root port enable status changed
> + * @flags.b.port_suspend_change: True if root port suspend status changed
> + * @flags.b.port_over_current_change: True if root port over current state
> + *                       changed.
> + * @flags.b.port_l1_change: True if root port l1 status changed
> + * @flags.b.reserved:   Reserved bits of root port register
>    * @non_periodic_sched_inactive: Inactive QHs in the non-periodic schedule.
>    *                      Transfers associated with these QHs are not currently
>    *                      assigned to a host channel.
> @@ -861,6 +935,9 @@ struct dwc2_hregs_backup {
>    *                      assigned to a host channel.
>    * @non_periodic_qh_ptr: Pointer to next QH to process in the active
>    *                      non-periodic schedule
> + * @non_periodic_sched_waiting: Waiting QHs in the non-periodic schedule.
> + *                      Transfers associated with these QHs are not currently
> + *                      assigned to a host channel.
>    * @periodic_sched_inactive: Inactive QHs in the periodic schedule. This is a
>    *                      list of QHs for periodic transfers that are _not_
>    *                      scheduled for the next frame. Each QH in the list has an
> @@ -910,8 +987,8 @@ struct dwc2_hregs_backup {
>    *                      host channel is available for non-periodic transactions.
>    * @non_periodic_channels: Number of host channels assigned to non-periodic
>    *                      transfers
> - * @available_host_channels Number of host channels available for the microframe
> - *                      scheduler to use
> + * @available_host_channels: Number of host channels available for the
> + *			     microframe scheduler to use
>    * @hc_ptr_array:       Array of pointers to the host channel descriptors.
>    *                      Allows accessing a host channel descriptor given the
>    *                      host channel number. This is useful in interrupt
> @@ -934,9 +1011,6 @@ struct dwc2_hregs_backup {
>    * @dedicated_fifos:    Set if the hardware has dedicated IN-EP fifos.
>    * @num_of_eps:         Number of available EPs (excluding EP0)
>    * @debug_root:         Root directrory for debugfs.
> - * @debug_file:         Main status file for debugfs.
> - * @debug_testmode:     Testmode status file for debugfs.
> - * @debug_fifo:         FIFO status file for debugfs.
>    * @ep0_reply:          Request used for ep0 reply.
>    * @ep0_buff:           Buffer for EP0 reply data, if needed.
>    * @ctrl_buff:          Buffer for EP0 control requests.
> @@ -951,7 +1025,37 @@ struct dwc2_hregs_backup {
>    * @ctrl_in_desc:	EP0 IN data phase desc chain pointer
>    * @ctrl_out_desc_dma:	EP0 OUT data phase desc chain DMA address
>    * @ctrl_out_desc:	EP0 OUT data phase desc chain pointer
> - * @eps:                The endpoints being supplied to the gadget framework
> + * @irq:		Interrupt request line number
> + * @clk:		Pointer to otg clock
> + * @reset:		Pointer to dwc2 reset controller
> + * @reset_ecc:          Pointer to dwc2 optional reset controller in Stratix10.
> + * @regset:		A pointer to a struct debugfs_regset32, which contains
> + *			a pointer to an array of register definitions, the
> + *			array size and the base address where the register bank
> + *			is to be found.
> + * @bus_suspended:	True if bus is suspended
> + * @last_frame_num:	Number of last frame. Range from 0 to  32768
> + * @frame_num_array:    Used only  if CONFIG_USB_DWC2_TRACK_MISSED_SOFS is
> + *			defined, for missed SOFs tracking. Array holds that
> + *			frame numbers, which not equal to last_frame_num +1
> + * @last_frame_num_array:   Used only  if CONFIG_USB_DWC2_TRACK_MISSED_SOFS is
> + *			    defined, for missed SOFs tracking.
> + *			    If current_frame_number != last_frame_num+1
> + *			    then last_frame_num added to this array
> + * @frame_num_idx:	Actual size of frame_num_array and last_frame_num_array
> + * @dumped_frame_num_array:	1 - if missed SOFs frame numbers dumbed
> + *				0 - if missed SOFs frame numbers not dumbed
> + * @fifo_mem:			Total internal RAM for FIFOs (bytes)
> + * @fifo_map:		Each bit intend for concrete fifo. If that bit is set,
> + *			then that fifo is used
> + * @gadget:		Represents a usb slave device
> + * @connected:		Used in slave mode. True if device connected with host
> + * @eps_in:		The IN endpoints being supplied to the gadget framework
> + * @eps_out:		The OUT endpoints being supplied to the gadget framework
> + * @new_connection:	Used in host mode. True if there are new connected
> + *			device
> + * @enabled:		Indicates the enabling state of controller
> + *
>    */
>   struct dwc2_hsotg {
>   	struct device *dev;
> diff --git a/drivers/usb/dwc2/debug.h b/drivers/usb/dwc2/debug.h
> index 6f23219c13cb..a8c565b6bc34 100644
> --- a/drivers/usb/dwc2/debug.h
> +++ b/drivers/usb/dwc2/debug.h
> @@ -1,5 +1,5 @@
>   // SPDX-License-Identifier: GPL-2.0
> -/**
> +/*
>    * debug.h - Designware USB2 DRD controller debug header
>    *
>    * Copyright (C) 2015 Intel Corporation
> diff --git a/drivers/usb/dwc2/debugfs.c b/drivers/usb/dwc2/debugfs.c
> index a21f89354434..7e6618ad9f21 100644
> --- a/drivers/usb/dwc2/debugfs.c
> +++ b/drivers/usb/dwc2/debugfs.c
> @@ -1,5 +1,5 @@
>   // SPDX-License-Identifier: GPL-2.0
> -/**
> +/*
>    * debugfs.c - Designware USB2 DRD controller debugfs
>    *
>    * Copyright (C) 2015 Intel Corporation
> @@ -16,12 +16,13 @@
>   
>   #if IS_ENABLED(CONFIG_USB_DWC2_PERIPHERAL) || \
>   	IS_ENABLED(CONFIG_USB_DWC2_DUAL_ROLE)
> +
>   /**
> - * testmode_write - debugfs: change usb test mode
> - * @seq: The seq file to write to.
> - * @v: Unused parameter.
> - *
> - * This debugfs entry modify the current usb test mode.
> + * testmode_write() - change usb test mode state.
> + * @file: The  file to write to.
> + * @ubuf: The buffer where user wrote.
> + * @count: The ubuf size.
> + * @ppos: Unused parameter.
>    */
>   static ssize_t testmode_write(struct file *file, const char __user *ubuf, size_t
>   		count, loff_t *ppos)
> @@ -55,9 +56,9 @@ static ssize_t testmode_write(struct file *file, const char __user *ubuf, size_t
>   }
>   
>   /**
> - * testmode_show - debugfs: show usb test mode state
> - * @seq: The seq file to write to.
> - * @v: Unused parameter.
> + * testmode_show() - debugfs: show usb test mode state
> + * @s: The seq file to write to.
> + * @unused: Unused parameter.
>    *
>    * This debugfs entry shows which usb test mode is currently enabled.
>    */
> diff --git a/drivers/usb/dwc2/gadget.c b/drivers/usb/dwc2/gadget.c
> index d0f2993125aa..93e59e4e5d9e 100644
> --- a/drivers/usb/dwc2/gadget.c
> +++ b/drivers/usb/dwc2/gadget.c
> @@ -1,5 +1,5 @@
>   // SPDX-License-Identifier: GPL-2.0
> -/**
> +/*
>    * Copyright (c) 2011 Samsung Electronics Co., Ltd.
>    *		http://www.samsung.com
>    *
> @@ -107,7 +107,6 @@ static inline bool using_desc_dma(struct dwc2_hsotg *hsotg)
>   /**
>    * dwc2_gadget_incr_frame_num - Increments the targeted frame number.
>    * @hs_ep: The endpoint
> - * @increment: The value to increment by
>    *
>    * This function will also check if the frame number overruns DSTS_SOFFN_LIMIT.
>    * If an overrun occurs it will wrap the value and set the frame_overrun flag.
> @@ -190,6 +189,8 @@ static void dwc2_hsotg_ctrl_epint(struct dwc2_hsotg *hsotg,
>   
>   /**
>    * dwc2_hsotg_tx_fifo_count - return count of TX FIFOs in device mode
> + *
> + * @hsotg: Programming view of the DWC_otg controller
>    */
>   int dwc2_hsotg_tx_fifo_count(struct dwc2_hsotg *hsotg)
>   {
> @@ -204,6 +205,8 @@ int dwc2_hsotg_tx_fifo_count(struct dwc2_hsotg *hsotg)
>   /**
>    * dwc2_hsotg_tx_fifo_total_depth - return total FIFO depth available for
>    * device mode TX FIFOs
> + *
> + * @hsotg: Programming view of the DWC_otg controller
>    */
>   int dwc2_hsotg_tx_fifo_total_depth(struct dwc2_hsotg *hsotg)
>   {
> @@ -227,6 +230,8 @@ int dwc2_hsotg_tx_fifo_total_depth(struct dwc2_hsotg *hsotg)
>   /**
>    * dwc2_hsotg_tx_fifo_average_depth - returns average depth of device mode
>    * TX FIFOs
> + *
> + * @hsotg: Programming view of the DWC_otg controller
>    */
>   int dwc2_hsotg_tx_fifo_average_depth(struct dwc2_hsotg *hsotg)
>   {
> @@ -327,6 +332,7 @@ static void dwc2_hsotg_init_fifo(struct dwc2_hsotg *hsotg)
>   }
>   
>   /**
> + * dwc2_hsotg_ep_alloc_request - allocate USB rerequest structure
>    * @ep: USB endpoint to allocate request for.
>    * @flags: Allocation flags
>    *
> @@ -2424,6 +2430,7 @@ static u32 dwc2_hsotg_ep0_mps(unsigned int mps)
>    * @ep: The index number of the endpoint
>    * @mps: The maximum packet size in bytes
>    * @mc: The multicount value
> + * @dir_in: True if direction is in.
>    *
>    * Configure the maximum packet size for the given endpoint, updating
>    * the hardware control registers to reflect this.
> @@ -2723,7 +2730,7 @@ static void dwc2_gadget_handle_ep_disabled(struct dwc2_hsotg_ep *hs_ep)
>   
>   /**
>    * dwc2_gadget_handle_out_token_ep_disabled - handle DXEPINT_OUTTKNEPDIS
> - * @hs_ep: The endpoint on which interrupt is asserted.
> + * @ep: The endpoint on which interrupt is asserted.
>    *
>    * This is starting point for ISOC-OUT transfer, synchronization done with
>    * first out token received from host while corresponding EP is disabled.
> @@ -3183,6 +3190,7 @@ static void dwc2_hsotg_irq_fifoempty(struct dwc2_hsotg *hsotg, bool periodic)
>   /**
>    * dwc2_hsotg_core_init - issue softreset to the core
>    * @hsotg: The device state
> + * @is_usb_reset: Usb resetting flag
>    *
>    * Issue a soft reset to the core, and await the core finishing it.
>    */
> @@ -4289,7 +4297,6 @@ static int dwc2_hsotg_udc_start(struct usb_gadget *gadget,
>   /**
>    * dwc2_hsotg_udc_stop - stop the udc
>    * @gadget: The usb gadget state
> - * @driver: The usb gadget driver
>    *
>    * Stop udc hw block and stay tunned for future transmissions
>    */
> @@ -4441,6 +4448,7 @@ static const struct usb_gadget_ops dwc2_hsotg_gadget_ops = {
>    * @hsotg: The device state.
>    * @hs_ep: The endpoint to be initialised.
>    * @epnum: The endpoint number
> + * @dir_in: True if direction is in.
>    *
>    * Initialise the given endpoint (as part of the probe and device state
>    * creation) to give to the gadget driver. Setup the endpoint name, any
> @@ -4514,7 +4522,7 @@ static void dwc2_hsotg_initep(struct dwc2_hsotg *hsotg,
>   
>   /**
>    * dwc2_hsotg_hw_cfg - read HW configuration registers
> - * @param: The device state
> + * @hsotg: Programming view of the DWC_otg controller
>    *
>    * Read the USB core HW configuration registers
>    */
> @@ -4570,7 +4578,8 @@ static int dwc2_hsotg_hw_cfg(struct dwc2_hsotg *hsotg)
>   
>   /**
>    * dwc2_hsotg_dump - dump state of the udc
> - * @param: The device state
> + * @hsotg: Programming view of the DWC_otg controller
> + *
>    */
>   static void dwc2_hsotg_dump(struct dwc2_hsotg *hsotg)
>   {
> @@ -4621,7 +4630,8 @@ static void dwc2_hsotg_dump(struct dwc2_hsotg *hsotg)
>   
>   /**
>    * dwc2_gadget_init - init function for gadget
> - * @dwc2: The data structure for the DWC2 driver.
> + * @hsotg: Programming view of the DWC_otg controller
> + *
>    */
>   int dwc2_gadget_init(struct dwc2_hsotg *hsotg)
>   {
> @@ -4718,7 +4728,8 @@ int dwc2_gadget_init(struct dwc2_hsotg *hsotg)
>   
>   /**
>    * dwc2_hsotg_remove - remove function for hsotg driver
> - * @pdev: The platform information for the driver
> + * @hsotg: Programming view of the DWC_otg controller
> + *
>    */
>   int dwc2_hsotg_remove(struct dwc2_hsotg *hsotg)
>   {
> @@ -4999,7 +5010,7 @@ int dwc2_gadget_enter_hibernation(struct dwc2_hsotg *hsotg)
>    *
>    * @hsotg: Programming view of the DWC_otg controller
>    * @rem_wakeup: indicates whether resume is initiated by Device or Host.
> - * @param reset: indicates whether resume is initiated by Reset.
> + * @reset: indicates whether resume is initiated by Reset.
>    *
>    * Return non-zero if failed to exit from hibernation.
>    */
> diff --git a/drivers/usb/dwc2/hcd.c b/drivers/usb/dwc2/hcd.c
> index 190f95964000..0ccd4b21f973 100644
> --- a/drivers/usb/dwc2/hcd.c
> +++ b/drivers/usb/dwc2/hcd.c
> @@ -592,7 +592,7 @@ u32 dwc2_calc_frame_interval(struct dwc2_hsotg *hsotg)
>    * dwc2_read_packet() - Reads a packet from the Rx FIFO into the destination
>    * buffer
>    *
> - * @core_if: Programming view of DWC_otg controller
> + * @hsotg: Programming view of DWC_otg controller
>    * @dest:    Destination buffer for the packet
>    * @bytes:   Number of bytes to copy to the destination
>    */
> @@ -4082,7 +4082,6 @@ static struct dwc2_hsotg *dwc2_hcd_to_hsotg(struct usb_hcd *hcd)
>    * then the refcount for the structure will go to 0 and we'll free it.
>    *
>    * @hsotg:     The HCD state structure for the DWC OTG controller.
> - * @qh:        The QH structure.
>    * @context:   The priv pointer from a struct dwc2_hcd_urb.
>    * @mem_flags: Flags for allocating memory.
>    * @ttport:    We'll return this device's port number here.  That's used to
> diff --git a/drivers/usb/dwc2/hcd.h b/drivers/usb/dwc2/hcd.h
> index 96a9da5fb202..7db1ee7e7a77 100644
> --- a/drivers/usb/dwc2/hcd.h
> +++ b/drivers/usb/dwc2/hcd.h
> @@ -80,7 +80,7 @@ struct dwc2_qh;
>    * @xfer_count:         Number of bytes transferred so far
>    * @start_pkt_count:    Packet count at start of transfer
>    * @xfer_started:       True if the transfer has been started
> - * @ping:               True if a PING request should be issued on this channel
> + * @do_ping:            True if a PING request should be issued on this channel
>    * @error_state:        True if the error count for this transaction is non-zero
>    * @halt_on_queue:      True if this channel should be halted the next time a
>    *                      request is queued for the channel. This is necessary in
> @@ -102,7 +102,7 @@ struct dwc2_qh;
>    * @schinfo:            Scheduling micro-frame bitmap
>    * @ntd:                Number of transfer descriptors for the transfer
>    * @halt_status:        Reason for halting the host channel
> - * @hcint               Contents of the HCINT register when the interrupt came
> + * @hcint:               Contents of the HCINT register when the interrupt came
>    * @qh:                 QH for the transfer being processed by this channel
>    * @hc_list_entry:      For linking to list of host channels
>    * @desc_list_addr:     Current QH's descriptor list DMA address
> @@ -237,7 +237,7 @@ struct dwc2_tt {
>   /**
>    * struct dwc2_hs_transfer_time - Info about a transfer on the high speed bus.
>    *
> - * @start_schedule_usecs:  The start time on the main bus schedule.  Note that
> + * @start_schedule_us:  The start time on the main bus schedule.  Note that
>    *                         the main bus schedule is tightly packed and this
>    *			   time should be interpreted as tightly packed (so
>    *			   uFrame 0 starts at 0 us, uFrame 1 starts at 100 us
> @@ -301,7 +301,6 @@ struct dwc2_hs_transfer_time {
>    *                           "struct dwc2_tt".  Not used if this device is high
>    *                           speed.  Note that this is in "schedule slice" which
>    *                           is tightly packed.
> - * @ls_duration_us:     Duration on the low speed bus schedule.
>    * @ntd:                Actual number of transfer descriptors in a list
>    * @qtd_list:           List of QTDs for this QH
>    * @channel:            Host channel currently processing transfers for this QH
> @@ -315,7 +314,7 @@ struct dwc2_hs_transfer_time {
>    *                      descriptor
>    * @unreserve_timer:    Timer for releasing periodic reservation.
>    * @wait_timer:         Timer used to wait before re-queuing.
> - * @dwc2_tt:            Pointer to our tt info (or NULL if no tt).
> + * @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
>    * @unreserve_pending:  True if we planned to unreserve but haven't yet.
> @@ -325,6 +324,7 @@ struct dwc2_hs_transfer_time {
>    *                      periodic transfers and is ignored for periodic ones.
>    * @wait_timer_cancel:  Set to true to cancel the wait_timer.
>    *
> + * @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.
> @@ -400,6 +400,10 @@ struct dwc2_qh {
>    * @urb:                URB for this transfer
>    * @qh:                 Queue head for this QTD
>    * @qtd_list_entry:     For linking to the QH's list of QTDs
> + * @isoc_td_first:	Index of first activated isochronous transfer
> + *			descriptor in Descriptor DMA mode
> + * @isoc_td_last:	Index of last activated isochronous transfer
> + *			descriptor in Descriptor DMA mode
>    *
>    * A Queue Transfer Descriptor (QTD) holds the state of a bulk, control,
>    * interrupt, or isochronous transfer. A single QTD is created for each URB
> diff --git a/drivers/usb/dwc2/hcd_ddma.c b/drivers/usb/dwc2/hcd_ddma.c
> index 28c8898b3b66..74f11c823f79 100644
> --- a/drivers/usb/dwc2/hcd_ddma.c
> +++ b/drivers/usb/dwc2/hcd_ddma.c
> @@ -332,6 +332,7 @@ static void dwc2_release_channel_ddma(struct dwc2_hsotg *hsotg,
>    *
>    * @hsotg: The HCD state structure for the DWC OTG controller
>    * @qh:    The QH to init
> + * @mem_flags: Indicates the type of memory allocation
>    *
>    * Return: 0 if successful, negative error code otherwise
>    *
> diff --git a/drivers/usb/dwc2/hcd_intr.c b/drivers/usb/dwc2/hcd_intr.c
> index a5dfd9d8bd9a..fbea5e3fb947 100644
> --- a/drivers/usb/dwc2/hcd_intr.c
> +++ b/drivers/usb/dwc2/hcd_intr.c
> @@ -478,6 +478,12 @@ static u32 dwc2_get_actual_xfer_length(struct dwc2_hsotg *hsotg,
>    * of the URB based on the number of bytes transferred via the host channel.
>    * Sets the URB status if the data transfer is finished.
>    *
> + * @hsotg: Programming view of the DWC_otg controller
> + * @chan: Programming view of host channel
> + * @chnum: Channel number
> + * @urb: Processing URB
> + * @qtd: Queue transfer descriptor
> + *
>    * Return: 1 if the data transfer specified by the URB is completely finished,
>    * 0 otherwise
>    */
> @@ -566,6 +572,12 @@ void dwc2_hcd_save_data_toggle(struct dwc2_hsotg *hsotg,
>    * halt_status. Completes the Isochronous URB if all the URB frames have been
>    * completed.
>    *
> + * @hsotg: Programming view of the DWC_otg controller
> + * @chan: Programming view of host channel
> + * @chnum: Channel number
> + * @halt_status: Reason for halting a host channel
> + * @qtd: Queue transfer descriptor
> + *
>    * Return: DWC2_HC_XFER_COMPLETE if there are more frames remaining to be
>    * transferred in the URB. Otherwise return DWC2_HC_XFER_URB_COMPLETE.
>    */
> diff --git a/drivers/usb/dwc2/hcd_queue.c b/drivers/usb/dwc2/hcd_queue.c
> index e34ad5e65350..d7c3d6c776d8 100644
> --- a/drivers/usb/dwc2/hcd_queue.c
> +++ b/drivers/usb/dwc2/hcd_queue.c
> @@ -679,6 +679,7 @@ static int dwc2_hs_pmap_schedule(struct dwc2_hsotg *hsotg, struct dwc2_qh *qh,
>    *
>    * @hsotg:       The HCD state structure for the DWC OTG controller.
>    * @qh:          QH for the periodic transfer.
> + * @index:       Transfer index
>    */
>   static void dwc2_hs_pmap_unschedule(struct dwc2_hsotg *hsotg,
>   				    struct dwc2_qh *qh, int index)
> @@ -1276,7 +1277,7 @@ static void dwc2_do_unreserve(struct dwc2_hsotg *hsotg, struct dwc2_qh *qh)
>    * release the reservation.  This worker is called after the appropriate
>    * delay.
>    *
> - * @work: Pointer to a qh unreserve_work.
> + * @t: Address to a qh unreserve_work.
>    */
>   static void dwc2_unreserve_timer_fn(struct timer_list *t)
>   {
> @@ -1631,7 +1632,7 @@ static void dwc2_qh_init(struct dwc2_hsotg *hsotg, struct dwc2_qh *qh,
>    * @hsotg:        The HCD state structure for the DWC OTG controller
>    * @urb:          Holds the information about the device/endpoint needed
>    *                to initialize the QH
> - * @atomic_alloc: Flag to do atomic allocation if needed
> + * @mem_flags:   Flags for allocating memory.
>    *
>    * Return: Pointer to the newly allocated QH, or NULL on error
>    */
> diff --git a/drivers/usb/dwc2/params.c b/drivers/usb/dwc2/params.c
> index 2700f5279285..b43d8c6a749d 100644
> --- a/drivers/usb/dwc2/params.c
> +++ b/drivers/usb/dwc2/params.c
> @@ -269,6 +269,9 @@ static void dwc2_set_param_power_down(struct dwc2_hsotg *hsotg)
>   /**
>    * dwc2_set_default_params() - Set all core parameters to their
>    * auto-detected default values.
> + *
> + * @hsotg: Programming view of the DWC_otg controller
> + *
>    */
>   static void dwc2_set_default_params(struct dwc2_hsotg *hsotg)
>   {
> @@ -339,6 +342,8 @@ static void dwc2_set_default_params(struct dwc2_hsotg *hsotg)
>   /**
>    * dwc2_get_device_properties() - Read in device properties.
>    *
> + * @hsotg: Programming view of the DWC_otg controller
> + *
>    * Read in the device properties and adjust core parameters if needed.
>    */
>   static void dwc2_get_device_properties(struct dwc2_hsotg *hsotg)
> @@ -690,6 +695,9 @@ static void dwc2_get_dev_hwparams(struct dwc2_hsotg *hsotg)
>   /**
>    * During device initialization, read various hardware configuration
>    * registers and interpret the contents.
> + *
> + * @hsotg: Programming view of the DWC_otg controller
> + *
>    */
>   int dwc2_get_hwparams(struct dwc2_hsotg *hsotg)
>   {
> diff --git a/drivers/usb/dwc2/pci.c b/drivers/usb/dwc2/pci.c
> index 7f21747007f1..e9e26f021a89 100644
> --- a/drivers/usb/dwc2/pci.c
> +++ b/drivers/usb/dwc2/pci.c
> @@ -77,6 +77,12 @@ static int dwc2_pci_quirks(struct pci_dev *pdev, struct platform_device *dwc2)
>   	return 0;
>   }
>   
> +/**
> + * dwc2_pci_probe() - Provides the cleanup entry points for the DWC_otg PCI
> + * driver
> + *
> + * @pci: The programming view of DWC_otg PCI
> + */
>   static void dwc2_pci_remove(struct pci_dev *pci)
>   {
>   	struct dwc2_pci_glue *glue = pci_get_drvdata(pci);
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
diff mbox

Patch

diff --git a/drivers/usb/dwc2/core.c b/drivers/usb/dwc2/core.c
index 18a0a1771289..1c36a6a9dd63 100644
--- a/drivers/usb/dwc2/core.c
+++ b/drivers/usb/dwc2/core.c
@@ -419,6 +419,8 @@  static void dwc2_wait_for_mode(struct dwc2_hsotg *hsotg,
 /**
  * dwc2_iddig_filter_enabled() - Returns true if the IDDIG debounce
  * filter is enabled.
+ *
+ * @hsotg: Programming view of DWC_otg controller
  */
 static bool dwc2_iddig_filter_enabled(struct dwc2_hsotg *hsotg)
 {
@@ -564,6 +566,9 @@  int dwc2_core_reset(struct dwc2_hsotg *hsotg, bool skip_wait)
  * If a force is done, it requires a IDDIG debounce filter delay if
  * the filter is configured and enabled. We poll the current mode of
  * the controller to account for this delay.
+ *
+ * @hsotg: Programming view of DWC_otg controller
+ * @host: Host mode flag
  */
 void dwc2_force_mode(struct dwc2_hsotg *hsotg, bool host)
 {
@@ -610,6 +615,8 @@  void dwc2_force_mode(struct dwc2_hsotg *hsotg, bool host)
  * or not because the value of the connector ID status is affected by
  * the force mode. We only need to call this once during probe if
  * dr_mode == OTG.
+ *
+ * @hsotg: Programming view of DWC_otg controller
  */
 static void dwc2_clear_force_mode(struct dwc2_hsotg *hsotg)
 {
diff --git a/drivers/usb/dwc2/core.h b/drivers/usb/dwc2/core.h
index 2438480e4496..6d304e91c20e 100644
--- a/drivers/usb/dwc2/core.h
+++ b/drivers/usb/dwc2/core.h
@@ -164,12 +164,11 @@  struct dwc2_hsotg_req;
  *       and has yet to be completed (maybe due to data move, or simply
  *       awaiting an ack from the core all the data has been completed).
  * @debugfs: File entry for debugfs file for this endpoint.
- * @lock: State lock to protect contents of endpoint.
  * @dir_in: Set to true if this endpoint is of the IN direction, which
  *          means that it is sending data to the Host.
  * @index: The index for the endpoint registers.
  * @mc: Multi Count - number of transactions per microframe
- * @interval - Interval for periodic endpoints, in frames or microframes.
+ * @interval: Interval for periodic endpoints, in frames or microframes.
  * @name: The name array passed to the USB core.
  * @halted: Set if the endpoint has been halted.
  * @periodic: Set if this is a periodic ep, such as Interrupt
@@ -182,6 +181,7 @@  struct dwc2_hsotg_req;
  * @compl_desc: index of next descriptor to be completed by xFerComplete
  * @total_data: The total number of data bytes done.
  * @fifo_size: The size of the FIFO (for periodic IN endpoints)
+ * @fifo_index: For Dedicated FIFO operation, only FIFO0 can be used for EP0.
  * @fifo_load: The amount of data loaded into the FIFO (periodic IN)
  * @last_load: The offset of data for the last start of request.
  * @size_loaded: The last loaded size for DxEPTSIZE for periodic IN
@@ -380,9 +380,12 @@  enum dwc2_ep0_state {
  *                      is FS.
  *                       0 - No (default)
  *                       1 - Yes
- * @ipg_isoc_en         Indicates the IPG supports is enabled or disabled.
+ * @ipg_isoc_en:        Indicates the IPG supports is enabled or disabled.
  *                       0 - Disable (default)
  *                       1 - Enable
+ * @acg_enable:		For enabling Active Clock Gating in the controller
+ *                       0 - No
+ *                       1 - Yes
  * @ulpi_fs_ls:         Make ULPI phy operate in FS/LS mode only
  *                       0 - No (default)
  *                       1 - Yes
@@ -552,7 +555,7 @@  struct dwc2_core_params {
  *
  * The values that are not in dwc2_core_params are documented below.
  *
- * @op_mode             Mode of Operation
+ * @op_mode:             Mode of Operation
  *                       0 - HNP- and SRP-Capable OTG (Host & Device)
  *                       1 - SRP-Capable OTG (Host & Device)
  *                       2 - Non-HNP and Non-SRP Capable OTG (Host & Device)
@@ -560,49 +563,102 @@  struct dwc2_core_params {
  *                       4 - Non-OTG Device
  *                       5 - SRP-Capable Host
  *                       6 - Non-OTG Host
- * @arch                Architecture
+ * @arch:                Architecture
  *                       0 - Slave only
  *                       1 - External DMA
  *                       2 - Internal DMA
- * @ipg_isoc_en         This feature indicates that the controller supports
+ * @ipg_isoc_en:        This feature indicates that the controller supports
  *                      the worst-case scenario of Rx followed by Rx
  *                      Interpacket Gap (IPG) (32 bitTimes) as per the utmi
  *                      specification for any token following ISOC OUT token.
  *                       0 - Don't support
  *                       1 - Support
- * @power_optimized     Are power optimizations enabled?
- * @num_dev_ep          Number of device endpoints available
- * @num_dev_in_eps      Number of device IN endpoints available
- * @num_dev_perio_in_ep Number of device periodic IN endpoints
- *                      available
- * @dev_token_q_depth   Device Mode IN Token Sequence Learning Queue
+ * @power_optimized:    Are power optimizations enabled?
+ * @num_dev_ep:         Number of device endpoints available
+ * @num_dev_in_eps:     Number of device IN endpoints available
+ * @num_dev_perio_in_ep: Number of device periodic IN endpoints
+ *                       available
+ * @dev_token_q_depth:  Device Mode IN Token Sequence Learning Queue
  *                      Depth
  *                       0 to 30
- * @host_perio_tx_q_depth
+ * @host_perio_tx_q_depth:
  *                      Host Mode Periodic Request Queue Depth
  *                       2, 4 or 8
- * @nperio_tx_q_depth
+ * @nperio_tx_q_depth:
  *                      Non-Periodic Request Queue Depth
  *                       2, 4 or 8
- * @hs_phy_type         High-speed PHY interface type
+ * @hs_phy_type:         High-speed PHY interface type
  *                       0 - High-speed interface not supported
  *                       1 - UTMI+
  *                       2 - ULPI
  *                       3 - UTMI+ and ULPI
- * @fs_phy_type         Full-speed PHY interface type
+ * @fs_phy_type:         Full-speed PHY interface type
  *                       0 - Full speed interface not supported
  *                       1 - Dedicated full speed interface
  *                       2 - FS pins shared with UTMI+ pins
  *                       3 - FS pins shared with ULPI pins
  * @total_fifo_size:    Total internal RAM for FIFOs (bytes)
- * @hibernation		Is hibernation enabled?
- * @utmi_phy_data_width UTMI+ PHY data width
+ * @hibernation:	Is hibernation enabled?
+ * @utmi_phy_data_width: UTMI+ PHY data width
  *                       0 - 8 bits
  *                       1 - 16 bits
  *                       2 - 8 or 16 bits
  * @snpsid:             Value from SNPSID register
  * @dev_ep_dirs:        Direction of device endpoints (GHWCFG1)
- * @g_tx_fifo_size[]	Power-on values of TxFIFO sizes
+ * @g_tx_fifo_size:	Power-on values of TxFIFO sizes
+ * @dma_desc_enable:    When DMA mode is enabled, specifies whether to use
+ *                      address DMA mode or descriptor DMA mode for accessing
+ *                      the data FIFOs. The driver will automatically detect the
+ *                      value for this if none is specified.
+ *                       0 - Address DMA
+ *                       1 - Descriptor DMA (default, if available)
+ * @enable_dynamic_fifo: 0 - Use coreConsultant-specified FIFO size parameters
+ *                       1 - Allow dynamic FIFO sizing (default, if available)
+ * @en_multiple_tx_fifo: Specifies whether dedicated per-endpoint transmit FIFOs
+ *                      are enabled for non-periodic IN endpoints in device
+ *                      mode.
+ * @host_nperio_tx_fifo_size: Number of 4-byte words in the non-periodic Tx FIFO
+ *                      in host mode when dynamic FIFO sizing is enabled
+ *                       16 to 32768
+ *                      Actual maximum value is autodetected and also
+ *                      the default.
+ * @host_perio_tx_fifo_size: Number of 4-byte words in the periodic Tx FIFO in
+ *                      host mode when dynamic FIFO sizing is enabled
+ *                       16 to 32768
+ *                      Actual maximum value is autodetected and also
+ *                      the default.
+ * @max_transfer_size:  The maximum transfer size supported, in bytes
+ *                       2047 to 65,535
+ *                      Actual maximum value is autodetected and also
+ *                      the default.
+ * @max_packet_count:   The maximum number of packets in a transfer
+ *                       15 to 511
+ *                      Actual maximum value is autodetected and also
+ *                      the default.
+ * @host_channels:      The number of host channel registers to use
+ *                       1 to 16
+ *                      Actual maximum value is autodetected and also
+ *                      the default.
+ * @dev_nperio_tx_fifo_size: Number of 4-byte words in the non-periodic Tx FIFO
+ *			     in device mode when dynamic FIFO sizing is enabled
+ *			     16 to 32768
+ *			     Actual maximum value is autodetected and also
+ *			     the default.
+ * @i2c_enable:         Specifies whether to use the I2Cinterface for a full
+ *                      speed PHY. This parameter is only applicable if phy_type
+ *                      is FS.
+ *                       0 - No (default)
+ *                       1 - Yes
+ * @acg_enable:		For enabling Active Clock Gating in the controller
+ *                       0 - Disable
+ *                       1 - Enable
+ * @lpm_mode:		For enabling Link Power Management in the controller
+ *                       0 - Disable
+ *                       1 - Enable
+ * @rx_fifo_size:	Number of 4-byte words in the  Rx FIFO when dynamic
+ *			FIFO sizing is enabled 16 to 32768
+ *			Actual maximum value is autodetected and also
+ *			the default.
  */
 struct dwc2_hw_params {
 	unsigned op_mode:3;
@@ -653,7 +709,11 @@  struct dwc2_hw_params {
  * @gi2cctl:		Backup of GI2CCTL register
  * @glpmcfg:		Backup of GLPMCFG register
  * @gdfifocfg:		Backup of GDFIFOCFG register
+ * @pcgcctl:		Backup of PCGCCTL register
+ * @pcgcctl1:		Backup of PCGCCTL1 register
+ * @dtxfsiz:		Backup of DTXFSIZ registers for each endpoint
  * @gpwrdn:		Backup of GPWRDN register
+ * @valid:		True if registers values backuped.
  */
 struct dwc2_gregs_backup {
 	u32 gotgctl;
@@ -686,6 +746,7 @@  struct dwc2_gregs_backup {
  * @doeptsiz:		Backup of DOEPTSIZ register
  * @doepdma:		Backup of DOEPDMA register
  * @dtxfsiz:		Backup of DTXFSIZ registers for each endpoint
+ * @valid:      True if registers values backuped.
  */
 struct dwc2_dregs_backup {
 	u32 dcfg;
@@ -709,9 +770,10 @@  struct dwc2_dregs_backup {
  * @hcfg:		Backup of HCFG register
  * @haintmsk:		Backup of HAINTMSK register
  * @hcintmsk:		Backup of HCINTMSK register
- * @hptr0:		Backup of HPTR0 register
+ * @hprt0:		Backup of HPTR0 register
  * @hfir:		Backup of HFIR register
  * @hptxfsiz:		Backup of HPTXFSIZ register
+ * @valid:      True if registers values backuped.
  */
 struct dwc2_hregs_backup {
 	u32 hcfg;
@@ -811,7 +873,7 @@  struct dwc2_hregs_backup {
  * @regs:		Pointer to controller regs
  * @hw_params:          Parameters that were autodetected from the
  *                      hardware registers
- * @core_params:	Parameters that define how the core should be configured
+ * @params:	Parameters that define how the core should be configured
  * @op_state:           The operational State, during transitions (a_host=>
  *                      a_peripheral and b_device=>b_host) this may not match
  *                      the core, but allows the software to determine
@@ -820,9 +882,9 @@  struct dwc2_hregs_backup {
  *                      - USB_DR_MODE_PERIPHERAL
  *                      - USB_DR_MODE_HOST
  *                      - USB_DR_MODE_OTG
- * @hcd_enabled		Host mode sub-driver initialization indicator.
- * @gadget_enabled	Peripheral mode sub-driver initialization indicator.
- * @ll_hw_enabled	Status of low-level hardware resources.
+ * @hcd_enabled:	Host mode sub-driver initialization indicator.
+ * @gadget_enabled:	Peripheral mode sub-driver initialization indicator.
+ * @ll_hw_enabled:	Status of low-level hardware resources.
  * @hibernated:		True if core is hibernated
  * @frame_number:       Frame number read from the core. For both device
  *			and host modes. The value ranges are from 0
@@ -846,13 +908,25 @@  struct dwc2_hregs_backup {
  *                      interrupt
  * @wkp_timer:          Timer object for handling Wakeup Detected interrupt
  * @lx_state:           Lx state of connected device
- * @gregs_backup: Backup of global registers during suspend
- * @dregs_backup: Backup of device registers during suspend
- * @hregs_backup: Backup of host registers during suspend
+ * @gr_backup: Backup of global registers during suspend
+ * @dr_backup: Backup of device registers during suspend
+ * @hr_backup: Backup of host registers during suspend
  *
  * These are for host mode:
  *
  * @flags:              Flags for handling root port state changes
+ * @flags.d32:          Contain all root port flags
+ * @flags.b:            Separate root port flags from each other
+ * @flags.b.port_connect_status_change: True if root port connect status
+ *                      changed
+ * @flags.b.port_connect_status: True if device connected to root port
+ * @flags.b.port_reset_change: True if root port reset status changed
+ * @flags.b.port_enable_change: True if root port enable status changed
+ * @flags.b.port_suspend_change: True if root port suspend status changed
+ * @flags.b.port_over_current_change: True if root port over current state
+ *                       changed.
+ * @flags.b.port_l1_change: True if root port l1 status changed
+ * @flags.b.reserved:   Reserved bits of root port register
  * @non_periodic_sched_inactive: Inactive QHs in the non-periodic schedule.
  *                      Transfers associated with these QHs are not currently
  *                      assigned to a host channel.
@@ -861,6 +935,9 @@  struct dwc2_hregs_backup {
  *                      assigned to a host channel.
  * @non_periodic_qh_ptr: Pointer to next QH to process in the active
  *                      non-periodic schedule
+ * @non_periodic_sched_waiting: Waiting QHs in the non-periodic schedule.
+ *                      Transfers associated with these QHs are not currently
+ *                      assigned to a host channel.
  * @periodic_sched_inactive: Inactive QHs in the periodic schedule. This is a
  *                      list of QHs for periodic transfers that are _not_
  *                      scheduled for the next frame. Each QH in the list has an
@@ -910,8 +987,8 @@  struct dwc2_hregs_backup {
  *                      host channel is available for non-periodic transactions.
  * @non_periodic_channels: Number of host channels assigned to non-periodic
  *                      transfers
- * @available_host_channels Number of host channels available for the microframe
- *                      scheduler to use
+ * @available_host_channels: Number of host channels available for the
+ *			     microframe scheduler to use
  * @hc_ptr_array:       Array of pointers to the host channel descriptors.
  *                      Allows accessing a host channel descriptor given the
  *                      host channel number. This is useful in interrupt
@@ -934,9 +1011,6 @@  struct dwc2_hregs_backup {
  * @dedicated_fifos:    Set if the hardware has dedicated IN-EP fifos.
  * @num_of_eps:         Number of available EPs (excluding EP0)
  * @debug_root:         Root directrory for debugfs.
- * @debug_file:         Main status file for debugfs.
- * @debug_testmode:     Testmode status file for debugfs.
- * @debug_fifo:         FIFO status file for debugfs.
  * @ep0_reply:          Request used for ep0 reply.
  * @ep0_buff:           Buffer for EP0 reply data, if needed.
  * @ctrl_buff:          Buffer for EP0 control requests.
@@ -951,7 +1025,37 @@  struct dwc2_hregs_backup {
  * @ctrl_in_desc:	EP0 IN data phase desc chain pointer
  * @ctrl_out_desc_dma:	EP0 OUT data phase desc chain DMA address
  * @ctrl_out_desc:	EP0 OUT data phase desc chain pointer
- * @eps:                The endpoints being supplied to the gadget framework
+ * @irq:		Interrupt request line number
+ * @clk:		Pointer to otg clock
+ * @reset:		Pointer to dwc2 reset controller
+ * @reset_ecc:          Pointer to dwc2 optional reset controller in Stratix10.
+ * @regset:		A pointer to a struct debugfs_regset32, which contains
+ *			a pointer to an array of register definitions, the
+ *			array size and the base address where the register bank
+ *			is to be found.
+ * @bus_suspended:	True if bus is suspended
+ * @last_frame_num:	Number of last frame. Range from 0 to  32768
+ * @frame_num_array:    Used only  if CONFIG_USB_DWC2_TRACK_MISSED_SOFS is
+ *			defined, for missed SOFs tracking. Array holds that
+ *			frame numbers, which not equal to last_frame_num +1
+ * @last_frame_num_array:   Used only  if CONFIG_USB_DWC2_TRACK_MISSED_SOFS is
+ *			    defined, for missed SOFs tracking.
+ *			    If current_frame_number != last_frame_num+1
+ *			    then last_frame_num added to this array
+ * @frame_num_idx:	Actual size of frame_num_array and last_frame_num_array
+ * @dumped_frame_num_array:	1 - if missed SOFs frame numbers dumbed
+ *				0 - if missed SOFs frame numbers not dumbed
+ * @fifo_mem:			Total internal RAM for FIFOs (bytes)
+ * @fifo_map:		Each bit intend for concrete fifo. If that bit is set,
+ *			then that fifo is used
+ * @gadget:		Represents a usb slave device
+ * @connected:		Used in slave mode. True if device connected with host
+ * @eps_in:		The IN endpoints being supplied to the gadget framework
+ * @eps_out:		The OUT endpoints being supplied to the gadget framework
+ * @new_connection:	Used in host mode. True if there are new connected
+ *			device
+ * @enabled:		Indicates the enabling state of controller
+ *
  */
 struct dwc2_hsotg {
 	struct device *dev;
diff --git a/drivers/usb/dwc2/debug.h b/drivers/usb/dwc2/debug.h
index 6f23219c13cb..a8c565b6bc34 100644
--- a/drivers/usb/dwc2/debug.h
+++ b/drivers/usb/dwc2/debug.h
@@ -1,5 +1,5 @@ 
 // SPDX-License-Identifier: GPL-2.0
-/**
+/*
  * debug.h - Designware USB2 DRD controller debug header
  *
  * Copyright (C) 2015 Intel Corporation
diff --git a/drivers/usb/dwc2/debugfs.c b/drivers/usb/dwc2/debugfs.c
index a21f89354434..7e6618ad9f21 100644
--- a/drivers/usb/dwc2/debugfs.c
+++ b/drivers/usb/dwc2/debugfs.c
@@ -1,5 +1,5 @@ 
 // SPDX-License-Identifier: GPL-2.0
-/**
+/*
  * debugfs.c - Designware USB2 DRD controller debugfs
  *
  * Copyright (C) 2015 Intel Corporation
@@ -16,12 +16,13 @@ 
 
 #if IS_ENABLED(CONFIG_USB_DWC2_PERIPHERAL) || \
 	IS_ENABLED(CONFIG_USB_DWC2_DUAL_ROLE)
+
 /**
- * testmode_write - debugfs: change usb test mode
- * @seq: The seq file to write to.
- * @v: Unused parameter.
- *
- * This debugfs entry modify the current usb test mode.
+ * testmode_write() - change usb test mode state.
+ * @file: The  file to write to.
+ * @ubuf: The buffer where user wrote.
+ * @count: The ubuf size.
+ * @ppos: Unused parameter.
  */
 static ssize_t testmode_write(struct file *file, const char __user *ubuf, size_t
 		count, loff_t *ppos)
@@ -55,9 +56,9 @@  static ssize_t testmode_write(struct file *file, const char __user *ubuf, size_t
 }
 
 /**
- * testmode_show - debugfs: show usb test mode state
- * @seq: The seq file to write to.
- * @v: Unused parameter.
+ * testmode_show() - debugfs: show usb test mode state
+ * @s: The seq file to write to.
+ * @unused: Unused parameter.
  *
  * This debugfs entry shows which usb test mode is currently enabled.
  */
diff --git a/drivers/usb/dwc2/gadget.c b/drivers/usb/dwc2/gadget.c
index d0f2993125aa..93e59e4e5d9e 100644
--- a/drivers/usb/dwc2/gadget.c
+++ b/drivers/usb/dwc2/gadget.c
@@ -1,5 +1,5 @@ 
 // SPDX-License-Identifier: GPL-2.0
-/**
+/*
  * Copyright (c) 2011 Samsung Electronics Co., Ltd.
  *		http://www.samsung.com
  *
@@ -107,7 +107,6 @@  static inline bool using_desc_dma(struct dwc2_hsotg *hsotg)
 /**
  * dwc2_gadget_incr_frame_num - Increments the targeted frame number.
  * @hs_ep: The endpoint
- * @increment: The value to increment by
  *
  * This function will also check if the frame number overruns DSTS_SOFFN_LIMIT.
  * If an overrun occurs it will wrap the value and set the frame_overrun flag.
@@ -190,6 +189,8 @@  static void dwc2_hsotg_ctrl_epint(struct dwc2_hsotg *hsotg,
 
 /**
  * dwc2_hsotg_tx_fifo_count - return count of TX FIFOs in device mode
+ *
+ * @hsotg: Programming view of the DWC_otg controller
  */
 int dwc2_hsotg_tx_fifo_count(struct dwc2_hsotg *hsotg)
 {
@@ -204,6 +205,8 @@  int dwc2_hsotg_tx_fifo_count(struct dwc2_hsotg *hsotg)
 /**
  * dwc2_hsotg_tx_fifo_total_depth - return total FIFO depth available for
  * device mode TX FIFOs
+ *
+ * @hsotg: Programming view of the DWC_otg controller
  */
 int dwc2_hsotg_tx_fifo_total_depth(struct dwc2_hsotg *hsotg)
 {
@@ -227,6 +230,8 @@  int dwc2_hsotg_tx_fifo_total_depth(struct dwc2_hsotg *hsotg)
 /**
  * dwc2_hsotg_tx_fifo_average_depth - returns average depth of device mode
  * TX FIFOs
+ *
+ * @hsotg: Programming view of the DWC_otg controller
  */
 int dwc2_hsotg_tx_fifo_average_depth(struct dwc2_hsotg *hsotg)
 {
@@ -327,6 +332,7 @@  static void dwc2_hsotg_init_fifo(struct dwc2_hsotg *hsotg)
 }
 
 /**
+ * dwc2_hsotg_ep_alloc_request - allocate USB rerequest structure
  * @ep: USB endpoint to allocate request for.
  * @flags: Allocation flags
  *
@@ -2424,6 +2430,7 @@  static u32 dwc2_hsotg_ep0_mps(unsigned int mps)
  * @ep: The index number of the endpoint
  * @mps: The maximum packet size in bytes
  * @mc: The multicount value
+ * @dir_in: True if direction is in.
  *
  * Configure the maximum packet size for the given endpoint, updating
  * the hardware control registers to reflect this.
@@ -2723,7 +2730,7 @@  static void dwc2_gadget_handle_ep_disabled(struct dwc2_hsotg_ep *hs_ep)
 
 /**
  * dwc2_gadget_handle_out_token_ep_disabled - handle DXEPINT_OUTTKNEPDIS
- * @hs_ep: The endpoint on which interrupt is asserted.
+ * @ep: The endpoint on which interrupt is asserted.
  *
  * This is starting point for ISOC-OUT transfer, synchronization done with
  * first out token received from host while corresponding EP is disabled.
@@ -3183,6 +3190,7 @@  static void dwc2_hsotg_irq_fifoempty(struct dwc2_hsotg *hsotg, bool periodic)
 /**
  * dwc2_hsotg_core_init - issue softreset to the core
  * @hsotg: The device state
+ * @is_usb_reset: Usb resetting flag
  *
  * Issue a soft reset to the core, and await the core finishing it.
  */
@@ -4289,7 +4297,6 @@  static int dwc2_hsotg_udc_start(struct usb_gadget *gadget,
 /**
  * dwc2_hsotg_udc_stop - stop the udc
  * @gadget: The usb gadget state
- * @driver: The usb gadget driver
  *
  * Stop udc hw block and stay tunned for future transmissions
  */
@@ -4441,6 +4448,7 @@  static const struct usb_gadget_ops dwc2_hsotg_gadget_ops = {
  * @hsotg: The device state.
  * @hs_ep: The endpoint to be initialised.
  * @epnum: The endpoint number
+ * @dir_in: True if direction is in.
  *
  * Initialise the given endpoint (as part of the probe and device state
  * creation) to give to the gadget driver. Setup the endpoint name, any
@@ -4514,7 +4522,7 @@  static void dwc2_hsotg_initep(struct dwc2_hsotg *hsotg,
 
 /**
  * dwc2_hsotg_hw_cfg - read HW configuration registers
- * @param: The device state
+ * @hsotg: Programming view of the DWC_otg controller
  *
  * Read the USB core HW configuration registers
  */
@@ -4570,7 +4578,8 @@  static int dwc2_hsotg_hw_cfg(struct dwc2_hsotg *hsotg)
 
 /**
  * dwc2_hsotg_dump - dump state of the udc
- * @param: The device state
+ * @hsotg: Programming view of the DWC_otg controller
+ *
  */
 static void dwc2_hsotg_dump(struct dwc2_hsotg *hsotg)
 {
@@ -4621,7 +4630,8 @@  static void dwc2_hsotg_dump(struct dwc2_hsotg *hsotg)
 
 /**
  * dwc2_gadget_init - init function for gadget
- * @dwc2: The data structure for the DWC2 driver.
+ * @hsotg: Programming view of the DWC_otg controller
+ *
  */
 int dwc2_gadget_init(struct dwc2_hsotg *hsotg)
 {
@@ -4718,7 +4728,8 @@  int dwc2_gadget_init(struct dwc2_hsotg *hsotg)
 
 /**
  * dwc2_hsotg_remove - remove function for hsotg driver
- * @pdev: The platform information for the driver
+ * @hsotg: Programming view of the DWC_otg controller
+ *
  */
 int dwc2_hsotg_remove(struct dwc2_hsotg *hsotg)
 {
@@ -4999,7 +5010,7 @@  int dwc2_gadget_enter_hibernation(struct dwc2_hsotg *hsotg)
  *
  * @hsotg: Programming view of the DWC_otg controller
  * @rem_wakeup: indicates whether resume is initiated by Device or Host.
- * @param reset: indicates whether resume is initiated by Reset.
+ * @reset: indicates whether resume is initiated by Reset.
  *
  * Return non-zero if failed to exit from hibernation.
  */
diff --git a/drivers/usb/dwc2/hcd.c b/drivers/usb/dwc2/hcd.c
index 190f95964000..0ccd4b21f973 100644
--- a/drivers/usb/dwc2/hcd.c
+++ b/drivers/usb/dwc2/hcd.c
@@ -592,7 +592,7 @@  u32 dwc2_calc_frame_interval(struct dwc2_hsotg *hsotg)
  * dwc2_read_packet() - Reads a packet from the Rx FIFO into the destination
  * buffer
  *
- * @core_if: Programming view of DWC_otg controller
+ * @hsotg: Programming view of DWC_otg controller
  * @dest:    Destination buffer for the packet
  * @bytes:   Number of bytes to copy to the destination
  */
@@ -4082,7 +4082,6 @@  static struct dwc2_hsotg *dwc2_hcd_to_hsotg(struct usb_hcd *hcd)
  * then the refcount for the structure will go to 0 and we'll free it.
  *
  * @hsotg:     The HCD state structure for the DWC OTG controller.
- * @qh:        The QH structure.
  * @context:   The priv pointer from a struct dwc2_hcd_urb.
  * @mem_flags: Flags for allocating memory.
  * @ttport:    We'll return this device's port number here.  That's used to
diff --git a/drivers/usb/dwc2/hcd.h b/drivers/usb/dwc2/hcd.h
index 96a9da5fb202..7db1ee7e7a77 100644
--- a/drivers/usb/dwc2/hcd.h
+++ b/drivers/usb/dwc2/hcd.h
@@ -80,7 +80,7 @@  struct dwc2_qh;
  * @xfer_count:         Number of bytes transferred so far
  * @start_pkt_count:    Packet count at start of transfer
  * @xfer_started:       True if the transfer has been started
- * @ping:               True if a PING request should be issued on this channel
+ * @do_ping:            True if a PING request should be issued on this channel
  * @error_state:        True if the error count for this transaction is non-zero
  * @halt_on_queue:      True if this channel should be halted the next time a
  *                      request is queued for the channel. This is necessary in
@@ -102,7 +102,7 @@  struct dwc2_qh;
  * @schinfo:            Scheduling micro-frame bitmap
  * @ntd:                Number of transfer descriptors for the transfer
  * @halt_status:        Reason for halting the host channel
- * @hcint               Contents of the HCINT register when the interrupt came
+ * @hcint:               Contents of the HCINT register when the interrupt came
  * @qh:                 QH for the transfer being processed by this channel
  * @hc_list_entry:      For linking to list of host channels
  * @desc_list_addr:     Current QH's descriptor list DMA address
@@ -237,7 +237,7 @@  struct dwc2_tt {
 /**
  * struct dwc2_hs_transfer_time - Info about a transfer on the high speed bus.
  *
- * @start_schedule_usecs:  The start time on the main bus schedule.  Note that
+ * @start_schedule_us:  The start time on the main bus schedule.  Note that
  *                         the main bus schedule is tightly packed and this
  *			   time should be interpreted as tightly packed (so
  *			   uFrame 0 starts at 0 us, uFrame 1 starts at 100 us
@@ -301,7 +301,6 @@  struct dwc2_hs_transfer_time {
  *                           "struct dwc2_tt".  Not used if this device is high
  *                           speed.  Note that this is in "schedule slice" which
  *                           is tightly packed.
- * @ls_duration_us:     Duration on the low speed bus schedule.
  * @ntd:                Actual number of transfer descriptors in a list
  * @qtd_list:           List of QTDs for this QH
  * @channel:            Host channel currently processing transfers for this QH
@@ -315,7 +314,7 @@  struct dwc2_hs_transfer_time {
  *                      descriptor
  * @unreserve_timer:    Timer for releasing periodic reservation.
  * @wait_timer:         Timer used to wait before re-queuing.
- * @dwc2_tt:            Pointer to our tt info (or NULL if no tt).
+ * @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
  * @unreserve_pending:  True if we planned to unreserve but haven't yet.
@@ -325,6 +324,7 @@  struct dwc2_hs_transfer_time {
  *                      periodic transfers and is ignored for periodic ones.
  * @wait_timer_cancel:  Set to true to cancel the wait_timer.
  *
+ * @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.
@@ -400,6 +400,10 @@  struct dwc2_qh {
  * @urb:                URB for this transfer
  * @qh:                 Queue head for this QTD
  * @qtd_list_entry:     For linking to the QH's list of QTDs
+ * @isoc_td_first:	Index of first activated isochronous transfer
+ *			descriptor in Descriptor DMA mode
+ * @isoc_td_last:	Index of last activated isochronous transfer
+ *			descriptor in Descriptor DMA mode
  *
  * A Queue Transfer Descriptor (QTD) holds the state of a bulk, control,
  * interrupt, or isochronous transfer. A single QTD is created for each URB
diff --git a/drivers/usb/dwc2/hcd_ddma.c b/drivers/usb/dwc2/hcd_ddma.c
index 28c8898b3b66..74f11c823f79 100644
--- a/drivers/usb/dwc2/hcd_ddma.c
+++ b/drivers/usb/dwc2/hcd_ddma.c
@@ -332,6 +332,7 @@  static void dwc2_release_channel_ddma(struct dwc2_hsotg *hsotg,
  *
  * @hsotg: The HCD state structure for the DWC OTG controller
  * @qh:    The QH to init
+ * @mem_flags: Indicates the type of memory allocation
  *
  * Return: 0 if successful, negative error code otherwise
  *
diff --git a/drivers/usb/dwc2/hcd_intr.c b/drivers/usb/dwc2/hcd_intr.c
index a5dfd9d8bd9a..fbea5e3fb947 100644
--- a/drivers/usb/dwc2/hcd_intr.c
+++ b/drivers/usb/dwc2/hcd_intr.c
@@ -478,6 +478,12 @@  static u32 dwc2_get_actual_xfer_length(struct dwc2_hsotg *hsotg,
  * of the URB based on the number of bytes transferred via the host channel.
  * Sets the URB status if the data transfer is finished.
  *
+ * @hsotg: Programming view of the DWC_otg controller
+ * @chan: Programming view of host channel
+ * @chnum: Channel number
+ * @urb: Processing URB
+ * @qtd: Queue transfer descriptor
+ *
  * Return: 1 if the data transfer specified by the URB is completely finished,
  * 0 otherwise
  */
@@ -566,6 +572,12 @@  void dwc2_hcd_save_data_toggle(struct dwc2_hsotg *hsotg,
  * halt_status. Completes the Isochronous URB if all the URB frames have been
  * completed.
  *
+ * @hsotg: Programming view of the DWC_otg controller
+ * @chan: Programming view of host channel
+ * @chnum: Channel number
+ * @halt_status: Reason for halting a host channel
+ * @qtd: Queue transfer descriptor
+ *
  * Return: DWC2_HC_XFER_COMPLETE if there are more frames remaining to be
  * transferred in the URB. Otherwise return DWC2_HC_XFER_URB_COMPLETE.
  */
diff --git a/drivers/usb/dwc2/hcd_queue.c b/drivers/usb/dwc2/hcd_queue.c
index e34ad5e65350..d7c3d6c776d8 100644
--- a/drivers/usb/dwc2/hcd_queue.c
+++ b/drivers/usb/dwc2/hcd_queue.c
@@ -679,6 +679,7 @@  static int dwc2_hs_pmap_schedule(struct dwc2_hsotg *hsotg, struct dwc2_qh *qh,
  *
  * @hsotg:       The HCD state structure for the DWC OTG controller.
  * @qh:          QH for the periodic transfer.
+ * @index:       Transfer index
  */
 static void dwc2_hs_pmap_unschedule(struct dwc2_hsotg *hsotg,
 				    struct dwc2_qh *qh, int index)
@@ -1276,7 +1277,7 @@  static void dwc2_do_unreserve(struct dwc2_hsotg *hsotg, struct dwc2_qh *qh)
  * release the reservation.  This worker is called after the appropriate
  * delay.
  *
- * @work: Pointer to a qh unreserve_work.
+ * @t: Address to a qh unreserve_work.
  */
 static void dwc2_unreserve_timer_fn(struct timer_list *t)
 {
@@ -1631,7 +1632,7 @@  static void dwc2_qh_init(struct dwc2_hsotg *hsotg, struct dwc2_qh *qh,
  * @hsotg:        The HCD state structure for the DWC OTG controller
  * @urb:          Holds the information about the device/endpoint needed
  *                to initialize the QH
- * @atomic_alloc: Flag to do atomic allocation if needed
+ * @mem_flags:   Flags for allocating memory.
  *
  * Return: Pointer to the newly allocated QH, or NULL on error
  */
diff --git a/drivers/usb/dwc2/params.c b/drivers/usb/dwc2/params.c
index 2700f5279285..b43d8c6a749d 100644
--- a/drivers/usb/dwc2/params.c
+++ b/drivers/usb/dwc2/params.c
@@ -269,6 +269,9 @@  static void dwc2_set_param_power_down(struct dwc2_hsotg *hsotg)
 /**
  * dwc2_set_default_params() - Set all core parameters to their
  * auto-detected default values.
+ *
+ * @hsotg: Programming view of the DWC_otg controller
+ *
  */
 static void dwc2_set_default_params(struct dwc2_hsotg *hsotg)
 {
@@ -339,6 +342,8 @@  static void dwc2_set_default_params(struct dwc2_hsotg *hsotg)
 /**
  * dwc2_get_device_properties() - Read in device properties.
  *
+ * @hsotg: Programming view of the DWC_otg controller
+ *
  * Read in the device properties and adjust core parameters if needed.
  */
 static void dwc2_get_device_properties(struct dwc2_hsotg *hsotg)
@@ -690,6 +695,9 @@  static void dwc2_get_dev_hwparams(struct dwc2_hsotg *hsotg)
 /**
  * During device initialization, read various hardware configuration
  * registers and interpret the contents.
+ *
+ * @hsotg: Programming view of the DWC_otg controller
+ *
  */
 int dwc2_get_hwparams(struct dwc2_hsotg *hsotg)
 {
diff --git a/drivers/usb/dwc2/pci.c b/drivers/usb/dwc2/pci.c
index 7f21747007f1..e9e26f021a89 100644
--- a/drivers/usb/dwc2/pci.c
+++ b/drivers/usb/dwc2/pci.c
@@ -77,6 +77,12 @@  static int dwc2_pci_quirks(struct pci_dev *pdev, struct platform_device *dwc2)
 	return 0;
 }
 
+/**
+ * dwc2_pci_probe() - Provides the cleanup entry points for the DWC_otg PCI
+ * driver
+ *
+ * @pci: The programming view of DWC_otg PCI
+ */
 static void dwc2_pci_remove(struct pci_dev *pci)
 {
 	struct dwc2_pci_glue *glue = pci_get_drvdata(pci);