mmc: dw_mmc: Fix kernel-doc comments in dwmmc.h

Rework kernel-doc comments in dwmmc.h header so it's actually possible
to generate a proper documentation from it usin scripts/kernel-doc
script, with no errors.

No functional change.

Signed-off-by: Sam Protsenko <semen.protsenko@linaro.org>
Signed-off-by: Minkyu Kang <mk7.kang@samsung.com>

diff --git a/include/dwmmc.h b/include/dwmmc.h
index 7bb456e792b451457b1902b68ac802ff0f3e32c7..77c8989148a1ee990f5044ffdf89a771bc55d7fb 100644 (file)
--- a/include/dwmmc.h
+++ b/include/dwmmc.h
@@ -182,6 +182,7 @@ struct dwmci_idmac_regs {
  * @ioaddr:    Base I/O address of controller
  * @quirks:    Quick flags - see DWMCI_QUIRK_...
  * @caps:      Capabilities - see MMC_MODE_...
+ * @clock:     Current clock frequency (after internal divider), Hz
  * @bus_hz:    Bus speed in Hz, if @get_mmc_clk() is NULL
  * @div:       Arbitrary clock divider value for use by controller
  * @dev_index: Arbitrary device index for use by controller
@@ -190,6 +191,10 @@ struct dwmci_idmac_regs {
  * @fifo_depth:        Depth of FIFO, bytes (or 0 for automatic detection)
  * @mmc:       Pointer to generic MMC structure for this device
  * @priv:      Private pointer for use by controller
+ * @clksel:    (Optional) Platform function to run when speed/width is changed
+ * @board_init:        (Optional) Platform function to run on init
+ * @cfg:       Internal MMC configuration, for !CONFIG_BLK cases
+ * @fifo_mode: Use FIFO mode (not DMA) to read and write data
  * @dma_64bit_address: Whether DMA supports 64-bit address mode or not
  * @regs:      Registers that can vary for different DW MMC block versions
  */
@@ -210,9 +215,12 @@ struct dwmci_host {
 
        int (*clksel)(struct dwmci_host *host);
        void (*board_init)(struct dwmci_host *host);
-
        /**
-        * Get / set a particular MMC clock frequency
+        * @get_mmc_clk: (Optional) Platform function to get/set a particular
+        * MMC clock frequency
+        *
+        * @host:       DWMMC host
+        * @freq:       Frequency the host is trying to achieve
         *
         * This is used to request the current clock frequency of the clock
         * that drives the DWMMC peripheral. The caller will then use this
@@ -220,16 +228,12 @@ struct dwmci_host {
         * required MMC bus clock frequency. If you want to handle the
         * clock external to DWMMC, use @freq to select the frequency and
         * return that value too. Then DWMMC will put itself in bypass mode.
-        *
-        * @host:       DWMMC host
-        * @freq:       Frequency the host is trying to achieve
         */
        unsigned int (*get_mmc_clk)(struct dwmci_host *host, uint freq);
 #ifndef CONFIG_BLK
        struct mmc_config cfg;
 #endif
 
-       /* use fifo mode to read and write data */
        bool fifo_mode;
        bool dma_64bit_address;
        const struct dwmci_idmac_regs *regs;
@@ -267,6 +271,10 @@ static inline u8 dwmci_readb(struct dwmci_host *host, int reg)
 #ifdef CONFIG_BLK
 /**
  * dwmci_setup_cfg() - Set up the configuration for DWMMC
+ * @cfg:       Configuration structure to fill in (generally &plat->mmc)
+ * @host:      DWMMC host
+ * @max_clk:   Maximum supported clock speed in Hz (e.g. 150000000)
+ * @min_clk:   Minimum supported clock speed in Hz (e.g. 400000)
  *
  * This is used to set up a DWMMC device when you are using CONFIG_BLK.
  *
@@ -291,28 +299,23 @@ static inline u8 dwmci_readb(struct dwmci_host *host, int reg)
  *     struct rockchip_mmc_plat *plat = dev_get_plat(dev);
  *
  * See rockchip_dw_mmc.c for an example.
- *
- * @cfg:       Configuration structure to fill in (generally &plat->mmc)
- * @host:      DWMMC host
- * @max_clk:   Maximum supported clock speed in HZ (e.g. 150000000)
- * @min_clk:   Minimum supported clock speed in HZ (e.g. 400000)
  */
 void dwmci_setup_cfg(struct mmc_config *cfg, struct dwmci_host *host,
                u32 max_clk, u32 min_clk);
 
 /**
  * dwmci_bind() - Set up a new MMC block device
+ * @dev:       Device to set up
+ * @mmc:       Pointer to mmc structure (normally &plat->mmc)
+ * @cfg:       Empty configuration structure (generally &plat->cfg). This is
+ *             normally all zeroes at this point. The only purpose of passing
+ *             this in is to set mmc->cfg to it.
  *
  * This is used to set up a DWMMC block device when you are using CONFIG_BLK.
  * It should be called from your driver's bind() method.
  *
  * See rockchip_dw_mmc.c for an example.
  *
- * @dev:       Device to set up
- * @mmc:       Pointer to mmc structure (normally &plat->mmc)
- * @cfg:       Empty configuration structure (generally &plat->cfg). This is
- *             normally all zeroes at this point. The only purpose of passing
- *             this in is to set mmc->cfg to it.
  * Return: 0 if OK, -ve if the block device could not be created
  */
 int dwmci_bind(struct udevice *dev, struct mmc *mmc, struct mmc_config *cfg);
@@ -320,12 +323,12 @@ int dwmci_bind(struct udevice *dev, struct mmc *mmc, struct mmc_config *cfg);
 #else
 /**
  * add_dwmci() - Add a new DWMMC interface
+ * @host:      DWMMC host structure
+ * @max_clk:   Maximum supported clock speed in Hz (e.g. 150000000)
+ * @min_clk:   Minimum supported clock speed in Hz (e.g. 400000)
  *
  * This is used when you are not using CONFIG_BLK. Convert your driver over!
  *
- * @host:      DWMMC host structure
- * @max_clk:   Maximum supported clock speed in HZ (e.g. 150000000)
- * @min_clk:   Minimum supported clock speed in HZ (e.g. 400000)
  * Return: 0 if OK, -ve on error
  */
 int add_dwmci(struct dwmci_host *host, u32 max_clk, u32 min_clk);