1 files changed, 59 insertions, 26 deletions

diff --git a/drivers/staging/dwc2/core.h b/drivers/staging/dwc2/core.h
index ecfcad83f767..9102f66d0111 100644
--- a/drivers/staging/dwc2/core.h
+++ b/drivers/staging/dwc2/core.h
@@ -68,19 +68,18 @@ enum dwc2_lx_state {
 /**
  * struct dwc2_core_params - Parameters for configuring the core
  *
- * @otg_cap:            Specifies the OTG capabilities. The driver will
- *                      automatically detect the value for this parameter if
- *                      none is specified.
- *                       0 - HNP and SRP capable (default)
+ * @otg_cap:            Specifies the OTG capabilities.
+ *                       0 - HNP and SRP capable
  *                       1 - SRP Only capable
- *                       2 - No HNP/SRP capable
+ *                       2 - No HNP/SRP capable (always available)
+ *                      Defaults to best available option (0, 1, then 2)
  * @otg_ver:            OTG version supported
- *                       0 - 1.3
+ *                       0 - 1.3 (default)
  *                       1 - 2.0
  * @dma_enable:         Specifies whether to use slave or DMA mode for accessing
  *                      the data FIFOs. The driver will automatically detect the
  *                      value for this parameter if none is specified.
- *                       0 - Slave
+ *                       0 - Slave (always available)
  *                       1 - DMA (default, if available)
  * @dma_desc_enable:    When DMA mode is enabled, specifies whether to use
  *                      address DMA mode or descriptor DMA mode for accessing
@@ -91,29 +90,47 @@ enum dwc2_lx_state {
  * @speed:              Specifies the maximum speed of operation in host and
  *                      device mode. The actual speed depends on the speed of
  *                      the attached device and the value of phy_type.
- *                       0 - High Speed (default)
+ *                       0 - High Speed
+ *                           (default when phy_type is UTMI+ or ULPI)
  *                       1 - Full Speed
+ *                           (default when phy_type is Full Speed)
  * @enable_dynamic_fifo: 0 - Use coreConsultant-specified FIFO size parameters
- *                       1 - Allow dynamic FIFO sizing (default)
+ *                       1 - Allow dynamic FIFO sizing (default, if available)
  * @en_multiple_tx_fifo: Specifies whether dedicated per-endpoint transmit FIFOs
  *                      are enabled
  * @host_rx_fifo_size:  Number of 4-byte words in the Rx FIFO in host mode when
  *                      dynamic FIFO sizing is enabled
- *                       16 to 32768 (default 1024)
+ *                       16 to 32768
+ *                      Actual maximum value is autodetected and also
+ *                      the default.
  * @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 (default 1024)
+ *                       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 (default 1024)
+ *                       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 (default 65,535)
+ *                       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 (default 511)
+ *                       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 (default 12)
+ *                       1 to 16
+ *                      Actual maximum value is autodetected and also
+ *                      the default.
  * @phy_type:           Specifies the type of PHY interface to use. By default,
  *                      the driver will automatically detect the phy_type.
+ *                       0 - Full Speed Phy
+ *                       1 - UTMI+ Phy
+ *                       2 - ULPI Phy
+ *                      Defaults to best available option (2, 1, then 0)
  * @phy_utmi_width:     Specifies the UTMI+ Data Width (in bits). This parameter
  *                      is applicable for a phy_type of UTMI+ or ULPI. (For a
  *                      ULPI phy_type, this parameter indicates the data width
@@ -122,7 +139,7 @@ enum dwc2_lx_state {
  *                      parameter was set to "8 and 16 bits", meaning that the
  *                      core has been configured to work at either data path
  *                      width.
- *                       8 or 16 (default 16)
+ *                       8 or 16 (default 16 if available)
  * @phy_ulpi_ddr:       Specifies whether the ULPI operates at double or single
  *                      data rate. This parameter is only applicable if phy_type
  *                      is ULPI.
@@ -132,35 +149,51 @@ enum dwc2_lx_state {
  *                           data bus
  * @phy_ulpi_ext_vbus:  For a ULPI phy, specifies whether to use the internal or
  *                      external supply to drive the VBus
+ *                       0 - Internal supply (default)
+ *                       1 - External supply
  * @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
- * @ulpi_fs_ls:         True to make ULPI phy operate in FS/LS mode only
+ * @ulpi_fs_ls:         Make ULPI phy operate in FS/LS mode only
+ *                       0 - No (default)
+ *                       1 - Yes
  * @host_support_fs_ls_low_power: Specifies whether low power mode is supported
  *                      when attached to a Full Speed or Low Speed device in
  *                      host mode.
  *                       0 - Don't support low power mode (default)
  *                       1 - Support low power mode
  * @host_ls_low_power_phy_clk: Specifies the PHY clock rate in low power mode
- *                      when connected to a Low Speed device in host mode. This
- *                      parameter is applicable only if
- *                      host_support_fs_ls_low_power is enabled. If phy_type is
- *                      set to FS then defaults to 6 MHZ otherwise 48 MHZ.
+ *                      when connected to a Low Speed device in host
+ *                      mode. This parameter is applicable only if
+ *                      host_support_fs_ls_low_power is enabled.
  *                       0 - 48 MHz
+ *                           (default when phy_type is UTMI+ or ULPI)
  *                       1 - 6 MHz
- * @ts_dline:           True to enable Term Select Dline pulsing
- * @reload_ctl:         True to allow dynamic reloading of HFIR register during
- *                      runtime
+ *                           (default when phy_type is Full Speed)
+ * @ts_dline:           Enable Term Select Dline pulsing
+ *                       0 - No (default)
+ *                       1 - Yes
+ * @reload_ctl:         Allow dynamic reloading of HFIR register during runtime
+ *                       0 - No (default for core < 2.92a)
+ *                       1 - Yes (default for core >= 2.92a)
  * @ahbcfg:             This field allows the default value of the GAHBCFG
  *                      register to be overridden
- *                       -1         - GAHBCFG value will not be overridden
+ *                       -1         - GAHBCFG value will be set to 0x06
+ *                                    (INCR4, default)
  *                       all others - GAHBCFG value will be overridden with
  *                                    this value
+ *                      Not all bits can be controlled like this, the
+ *                      bits defined by GAHBCFG_CTRL_MASK are controlled
+ *                      by the driver and are ignored in this
+ *                      configuration value.
  *
  * The following parameters may be specified when starting the module. These
- * parameters define how the DWC_otg controller should be configured.
+ * parameters define how the DWC_otg controller should be configured. A
+ * value of -1 (or any other out of range value) for any parameter means
+ * to read the value from hardware (if possible) or use the builtin
+ * default described above.
  */
 struct dwc2_core_params {
         /*