* [v2] usb: dwc2: Fix kernel doc's warnings.
@ 2018-05-16 5:59 Felipe Balbi
0 siblings, 0 replies; 4+ messages in thread
From: Felipe Balbi @ 2018-05-16 5:59 UTC (permalink / raw)
To: Minas Harutyunyan
Minas Harutyunyan <Minas.Harutyunyan@synopsys.com> writes:
> Hi Filipe,
>
> Please pickup this patch to your testing/next.
wish I could:
checking file drivers/usb/dwc2/core.c
checking file drivers/usb/dwc2/core.h
Hunk #2 succeeded at 181 with fuzz 1.
Hunk #3 FAILED at 380.
Hunk #4 succeeded at 552 (offset 4 lines).
Hunk #5 FAILED at 556.
Hunk #6 succeeded at 653 (offset 11 lines).
Hunk #7 succeeded at 690 (offset 11 lines).
Hunk #8 succeeded at 714 (offset 11 lines).
Hunk #9 succeeded at 817 (offset 11 lines).
Hunk #10 succeeded at 826 with fuzz 2 (offset 11 lines).
Hunk #11 succeeded at 852 (offset 14 lines).
Hunk #12 succeeded at 879 (offset 14 lines).
Hunk #13 succeeded at 931 (offset 12 lines).
Hunk #14 succeeded at 955 (offset 12 lines).
Hunk #15 succeeded at 969 (offset 12 lines).
2 out of 15 hunks FAILED
checking file drivers/usb/dwc2/debug.h
checking file drivers/usb/dwc2/debugfs.c
checking file drivers/usb/dwc2/gadget.c
Hunk #7 succeeded at 2430 (offset -17 lines).
Hunk #8 succeeded at 2730 (offset -15 lines).
Hunk #9 succeeded at 3190 (offset -14 lines).
Hunk #10 succeeded at 4297 (offset 9 lines).
Hunk #11 succeeded at 4448 (offset 9 lines).
Hunk #12 succeeded at 4522 (offset 9 lines).
Hunk #13 succeeded at 4578 (offset 9 lines).
Hunk #14 succeeded at 4630 (offset 9 lines).
Hunk #15 succeeded at 4728 (offset 9 lines).
Hunk #16 succeeded at 5010 (offset 9 lines).
checking file drivers/usb/dwc2/hcd.c
checking file drivers/usb/dwc2/hcd.h
checking file drivers/usb/dwc2/hcd_ddma.c
checking file drivers/usb/dwc2/hcd_intr.c
checking file drivers/usb/dwc2/hcd_queue.c
checking file drivers/usb/dwc2/params.c
Hunk #2 succeeded at 342 (offset 1 line).
Hunk #3 succeeded at 695 (offset 2 lines).
checking file drivers/usb/dwc2/pci.c
^ permalink raw reply [flat|nested] 4+ messages in thread
* [v2] usb: dwc2: Fix kernel doc's warnings.
@ 2018-05-15 10:15 Minas Harutyunyan
0 siblings, 0 replies; 4+ messages in thread
From: Minas Harutyunyan @ 2018-05-15 10:15 UTC (permalink / raw)
To: Minas Harutyunyan, Grigor Tovmasyan, John Youn, Felipe Balbi,
Greg Kroah-Hartman, linux-usb
Hi Filipe,
Please pickup this patch to your testing/next.
Thanks,
Minas
On 4/10/2018 9:59 AM, Minas Harutyunyan wrote:
> Hi,
>
> On 4/3/2018 5:15 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>
>> ---
>> Changes from version 1:
>>
>> Fix minor kernel-doc style issue.
>>
>> Changes from version 0:
>>
>> Rebased to balbi/next.
>> Fixed new kernel-doc warnings which cames from new patches.
>> ---
>> drivers/usb/dwc2/core.c | 7 ++
>> drivers/usb/dwc2/core.h | 166 +++++++++++++++++++++++++++++++++++--------
>> 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, 213 insertions(+), 59 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 d83be5651f87..c2c08cbbc19b 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;
>> * @next_desc: index of next free descriptor in the ISOC chain under SW control.
>> * @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,6 +380,9 @@ enum dwc2_ep0_state {
>> * is FS.
>> * 0 - No (default)
>> * 1 - Yes
>> + * @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
>> @@ -548,7 +551,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)
>> @@ -556,43 +559,96 @@ 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
>> - * @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;
>> @@ -642,7 +698,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;
>> @@ -675,6 +735,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;
>> @@ -698,9 +759,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;
>> @@ -800,7 +862,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
>> @@ -809,9 +871,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
>> * @phy: The otg phy transceiver structure for phy control.
>> * @uphy: The otg phy transceiver structure for old USB phy
>> @@ -832,13 +894,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.
>> @@ -847,6 +921,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
>> @@ -898,8 +975,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
>> @@ -922,9 +999,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.
>> @@ -939,7 +1013,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 58c691f882a8..ffe950b02ce0 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 6c32bf26e48e..6ec40a4e8c4a 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.
>> * https://urldefense.proofpoint.com/v2/url?u=http-3A__www.samsung.com&d=DwIBAg&c=DPL6_X_6JkXFx7AXWqB0tg&r=6z9Al9FrHR_ZqbbtSAsD16pvOL2S3XHxQnSzq8kusyI&m=XqBlpu7ZTIrJGFW1zgodFcBuu-4kslWr7JAQRZ317_o&s=RrzhmAWPUuVVTaQqGLv9eXtcQBQ_qkMQu5lxbby8CUE&e=
>> *
>> @@ -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
>> *
>> @@ -2441,6 +2447,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.
>> @@ -2738,7 +2745,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.
>> @@ -3197,6 +3204,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.
>> */
>> @@ -4280,7 +4288,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
>> */
>> @@ -4432,6 +4439,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
>> @@ -4505,7 +4513,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
>> */
>> @@ -4561,7 +4569,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)
>> {
>> @@ -4612,7 +4621,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)
>> {
>> @@ -4709,7 +4719,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)
>> {
>> @@ -4990,7 +5001,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 dcfda5eb4cac..8f855c6fdb30 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 b3871fcafe1e..4766c3d4dcbd 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)
>> {
>> @@ -338,6 +341,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)
>> @@ -688,6 +693,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);
>>
>
> Acked-by: Minas Harutyunyan <hminas@synopsys.com>
> --
> 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 https://urldefense.proofpoint.com/v2/url?u=http-3A__vger.kernel.org_majordomo-2Dinfo.html&d=DwIDAg&c=DPL6_X_6JkXFx7AXWqB0tg&r=6z9Al9FrHR_ZqbbtSAsD16pvOL2S3XHxQnSzq8kusyI&m=XeEMBsfWnOoSzyUg4axwaqqPMNgDwjNAt2xycplDtEA&s=u0W1Il9YOy5BmjELWJOu33nbe4Iatqq7zbezeZPdyzM&e=
>
---
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* [v2] usb: dwc2: Fix kernel doc's warnings.
@ 2018-04-10 5:59 Minas Harutyunyan
0 siblings, 0 replies; 4+ messages in thread
From: Minas Harutyunyan @ 2018-04-10 5:59 UTC (permalink / raw)
To: Grigor Tovmasyan, John Youn, Felipe Balbi, Greg Kroah-Hartman, linux-usb
Hi,
On 4/3/2018 5:15 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>
> ---
> Changes from version 1:
>
> Fix minor kernel-doc style issue.
>
> Changes from version 0:
>
> Rebased to balbi/next.
> Fixed new kernel-doc warnings which cames from new patches.
> ---
> drivers/usb/dwc2/core.c | 7 ++
> drivers/usb/dwc2/core.h | 166 +++++++++++++++++++++++++++++++++++--------
> 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, 213 insertions(+), 59 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 d83be5651f87..c2c08cbbc19b 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;
> * @next_desc: index of next free descriptor in the ISOC chain under SW control.
> * @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,6 +380,9 @@ enum dwc2_ep0_state {
> * is FS.
> * 0 - No (default)
> * 1 - Yes
> + * @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
> @@ -548,7 +551,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)
> @@ -556,43 +559,96 @@ 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
> - * @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;
> @@ -642,7 +698,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;
> @@ -675,6 +735,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;
> @@ -698,9 +759,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;
> @@ -800,7 +862,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
> @@ -809,9 +871,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
> * @phy: The otg phy transceiver structure for phy control.
> * @uphy: The otg phy transceiver structure for old USB phy
> @@ -832,13 +894,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.
> @@ -847,6 +921,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
> @@ -898,8 +975,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
> @@ -922,9 +999,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.
> @@ -939,7 +1013,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 58c691f882a8..ffe950b02ce0 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 6c32bf26e48e..6ec40a4e8c4a 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.
> * https://urldefense.proofpoint.com/v2/url?u=http-3A__www.samsung.com&d=DwIBAg&c=DPL6_X_6JkXFx7AXWqB0tg&r=6z9Al9FrHR_ZqbbtSAsD16pvOL2S3XHxQnSzq8kusyI&m=XqBlpu7ZTIrJGFW1zgodFcBuu-4kslWr7JAQRZ317_o&s=RrzhmAWPUuVVTaQqGLv9eXtcQBQ_qkMQu5lxbby8CUE&e=
> *
> @@ -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
> *
> @@ -2441,6 +2447,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.
> @@ -2738,7 +2745,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.
> @@ -3197,6 +3204,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.
> */
> @@ -4280,7 +4288,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
> */
> @@ -4432,6 +4439,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
> @@ -4505,7 +4513,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
> */
> @@ -4561,7 +4569,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)
> {
> @@ -4612,7 +4621,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)
> {
> @@ -4709,7 +4719,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)
> {
> @@ -4990,7 +5001,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 dcfda5eb4cac..8f855c6fdb30 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 b3871fcafe1e..4766c3d4dcbd 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)
> {
> @@ -338,6 +341,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)
> @@ -688,6 +693,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);
>
Acked-by: Minas Harutyunyan <hminas@synopsys.com>
---
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
^ permalink raw reply [flat|nested] 4+ messages in thread
* [v2] usb: dwc2: Fix kernel doc's warnings.
@ 2018-04-03 13:15 Grigor Tovmasyan
0 siblings, 0 replies; 4+ messages in thread
From: Grigor Tovmasyan @ 2018-04-03 13:15 UTC (permalink / raw)
To: John Youn, Felipe Balbi, Greg Kroah-Hartman, linux-usb; +Cc: Grigor Tovmasyan
Added descriptions for all not described parameters.
Fix all kernel doc's warnings.
Signed-off-by: Grigor Tovmasyan <tovmasya@synopsys.com>
---
Changes from version 1:
Fix minor kernel-doc style issue.
Changes from version 0:
Rebased to balbi/next.
Fixed new kernel-doc warnings which cames from new patches.
---
drivers/usb/dwc2/core.c | 7 ++
drivers/usb/dwc2/core.h | 166 +++++++++++++++++++++++++++++++++++--------
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, 213 insertions(+), 59 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 d83be5651f87..c2c08cbbc19b 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;
* @next_desc: index of next free descriptor in the ISOC chain under SW control.
* @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,6 +380,9 @@ enum dwc2_ep0_state {
* is FS.
* 0 - No (default)
* 1 - Yes
+ * @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
@@ -548,7 +551,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)
@@ -556,43 +559,96 @@ 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
- * @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;
@@ -642,7 +698,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;
@@ -675,6 +735,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;
@@ -698,9 +759,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;
@@ -800,7 +862,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
@@ -809,9 +871,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
* @phy: The otg phy transceiver structure for phy control.
* @uphy: The otg phy transceiver structure for old USB phy
@@ -832,13 +894,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.
@@ -847,6 +921,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
@@ -898,8 +975,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
@@ -922,9 +999,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.
@@ -939,7 +1013,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 58c691f882a8..ffe950b02ce0 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 6c32bf26e48e..6ec40a4e8c4a 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
*
@@ -2441,6 +2447,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.
@@ -2738,7 +2745,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.
@@ -3197,6 +3204,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.
*/
@@ -4280,7 +4288,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
*/
@@ -4432,6 +4439,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
@@ -4505,7 +4513,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
*/
@@ -4561,7 +4569,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)
{
@@ -4612,7 +4621,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)
{
@@ -4709,7 +4719,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)
{
@@ -4990,7 +5001,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 dcfda5eb4cac..8f855c6fdb30 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 b3871fcafe1e..4766c3d4dcbd 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)
{
@@ -338,6 +341,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)
@@ -688,6 +693,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);
^ permalink raw reply related [flat|nested] 4+ messages in thread
end of thread, other threads:[~2018-05-16 5:59 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-05-16 5:59 [v2] usb: dwc2: Fix kernel doc's warnings Felipe Balbi
-- strict thread matches above, loose matches on Subject: below --
2018-05-15 10:15 Minas Harutyunyan
2018-04-10 5:59 Minas Harutyunyan
2018-04-03 13:15 Grigor Tovmasyan
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.