From 4908460ef16e1a5b7597c2a9871661e827ef8ee7 Mon Sep 17 00:00:00 2001 From: Manish Narani Date: Mon, 6 Apr 2020 23:13:35 +0530 Subject: [PATCH] mmc: sdhci-of-arasan: Fix kernel-doc warnings Modify code to fix the warnings reported by kernel-doc for better documentation. Signed-off-by: Manish Narani Link: https://lore.kernel.org/r/1586195015-128992-7-git-send-email-manish.narani@xilinx.com Signed-off-by: Ulf Hansson --- drivers/mmc/host/sdhci-of-arasan.c | 114 ++++++++++++++++------------- 1 file changed, 64 insertions(+), 50 deletions(-) diff --git a/drivers/mmc/host/sdhci-of-arasan.c b/drivers/mmc/host/sdhci-of-arasan.c index a9a6346d46dd..16e26c217a77 100644 --- a/drivers/mmc/host/sdhci-of-arasan.c +++ b/drivers/mmc/host/sdhci-of-arasan.c @@ -73,13 +73,13 @@ struct sdhci_arasan_soc_ctl_field { /** * struct sdhci_arasan_soc_ctl_map - Map in syscon to corecfg registers * - * It's up to the licensee of the Arsan IP block to make these available - * somewhere if needed. Presumably these will be scattered somewhere that's - * accessible via the syscon API. - * * @baseclkfreq: Where to find corecfg_baseclkfreq * @clockmultiplier: Where to find corecfg_clockmultiplier * @hiword_update: If true, use HIWORD_UPDATE to access the syscon + * + * It's up to the licensee of the Arsan IP block to make these available + * somewhere if needed. Presumably these will be scattered somewhere that's + * accessible via the syscon API. */ struct sdhci_arasan_soc_ctl_map { struct sdhci_arasan_soc_ctl_field baseclkfreq; @@ -99,7 +99,8 @@ struct sdhci_arasan_clk_ops { }; /** - * struct sdhci_arasan_clk_data + * struct sdhci_arasan_clk_data - Arasan Controller Clock Data. + * * @sdcardclk_hw: Struct for the clock we might provide to a PHY. * @sdcardclk: Pointer to normal 'struct clock' for sdcardclk_hw. * @sampleclk_hw: Struct for the clock we might provide to a PHY. @@ -125,15 +126,18 @@ struct sdhci_arasan_zynqmp_clk_data { }; /** - * struct sdhci_arasan_data + * struct sdhci_arasan_data - Arasan Controller Data + * * @host: Pointer to the main SDHCI host structure. * @clk_ahb: Pointer to the AHB clock * @phy: Pointer to the generic phy * @is_phy_on: True if the PHY is on; false if not. + * @has_cqe: True if controller has command queuing engine. * @clk_data: Struct for the Arasan Controller Clock Data. * @clk_ops: Struct for the Arasan Controller Clock Operations. * @soc_ctl_base: Pointer to regmap for syscon for soc_ctl registers. * @soc_ctl_map: Map to get offsets into soc_ctl registers. + * @quirks: Arasan deviations from spec. */ struct sdhci_arasan_data { struct sdhci_host *host; @@ -147,7 +151,7 @@ struct sdhci_arasan_data { struct regmap *soc_ctl_base; const struct sdhci_arasan_soc_ctl_map *soc_ctl_map; - unsigned int quirks; /* Arasan deviations from spec */ + unsigned int quirks; /* Controller does not have CD wired and will not function normally without */ #define SDHCI_ARASAN_QUIRK_FORCE_CDTEST BIT(0) @@ -183,14 +187,16 @@ static const struct sdhci_arasan_soc_ctl_map intel_lgm_sdxc_soc_ctl_map = { /** * sdhci_arasan_syscon_write - Write to a field in soc_ctl registers * + * @host: The sdhci_host + * @fld: The field to write to + * @val: The value to write + * * This function allows writing to fields in sdhci_arasan_soc_ctl_map. * Note that if a field is specified as not available (shift < 0) then * this function will silently return an error code. It will be noisy * and print errors for any other (unexpected) errors. * - * @host: The sdhci_host - * @fld: The field to write to - * @val: The value to write + * Return: 0 on success and error value on error */ static int sdhci_arasan_syscon_write(struct sdhci_host *host, const struct sdhci_arasan_soc_ctl_field *fld, @@ -420,9 +426,10 @@ static const struct sdhci_pltfm_data sdhci_arasan_cqe_pdata = { /** * sdhci_arasan_suspend - Suspend method for the driver * @dev: Address of the device structure - * Returns 0 on success and error value on error * * Put the device in a low power state. + * + * Return: 0 on success and error value on error */ static int sdhci_arasan_suspend(struct device *dev) { @@ -463,9 +470,10 @@ static int sdhci_arasan_suspend(struct device *dev) /** * sdhci_arasan_resume - Resume method for the driver * @dev: Address of the device structure - * Returns 0 on success and error value on error * * Resume operation after suspend + * + * Return: 0 on success and error value on error */ static int sdhci_arasan_resume(struct device *dev) { @@ -514,16 +522,16 @@ static SIMPLE_DEV_PM_OPS(sdhci_arasan_dev_pm_ops, sdhci_arasan_suspend, /** * sdhci_arasan_sdcardclk_recalc_rate - Return the card clock rate * + * @hw: Pointer to the hardware clock structure. + * @parent_rate: The parent rate (should be rate of clk_xin). + * * Return the current actual rate of the SD card clock. This can be used * to communicate with out PHY. * - * @hw: Pointer to the hardware clock structure. - * @parent_rate The parent rate (should be rate of clk_xin). - * Returns the card clock rate. + * Return: The card clock rate. */ static unsigned long sdhci_arasan_sdcardclk_recalc_rate(struct clk_hw *hw, unsigned long parent_rate) - { struct sdhci_arasan_clk_data *clk_data = container_of(hw, struct sdhci_arasan_clk_data, sdcardclk_hw); @@ -541,16 +549,16 @@ static const struct clk_ops arasan_sdcardclk_ops = { /** * sdhci_arasan_sampleclk_recalc_rate - Return the sampling clock rate * + * @hw: Pointer to the hardware clock structure. + * @parent_rate: The parent rate (should be rate of clk_xin). + * * Return the current actual rate of the sampling clock. This can be used * to communicate with out PHY. * - * @hw: Pointer to the hardware clock structure. - * @parent_rate The parent rate (should be rate of clk_xin). - * Returns the sample clock rate. + * Return: The sample clock rate. */ static unsigned long sdhci_arasan_sampleclk_recalc_rate(struct clk_hw *hw, unsigned long parent_rate) - { struct sdhci_arasan_clk_data *clk_data = container_of(hw, struct sdhci_arasan_clk_data, sampleclk_hw); @@ -568,14 +576,14 @@ static const struct clk_ops arasan_sampleclk_ops = { /** * sdhci_zynqmp_sdcardclk_set_phase - Set the SD Output Clock Tap Delays * + * @hw: Pointer to the hardware clock structure. + * @degrees: The clock phase shift between 0 - 359. + * * Set the SD Output Clock Tap Delays for Output path * - * @hw: Pointer to the hardware clock structure. - * @degrees The clock phase shift between 0 - 359. * Return: 0 on success and error value on error */ static int sdhci_zynqmp_sdcardclk_set_phase(struct clk_hw *hw, int degrees) - { struct sdhci_arasan_clk_data *clk_data = container_of(hw, struct sdhci_arasan_clk_data, sdcardclk_hw); @@ -640,14 +648,14 @@ static const struct clk_ops zynqmp_sdcardclk_ops = { /** * sdhci_zynqmp_sampleclk_set_phase - Set the SD Input Clock Tap Delays * + * @hw: Pointer to the hardware clock structure. + * @degrees: The clock phase shift between 0 - 359. + * * Set the SD Input Clock Tap Delays for Input path * - * @hw: Pointer to the hardware clock structure. - * @degrees The clock phase shift between 0 - 359. * Return: 0 on success and error value on error */ static int sdhci_zynqmp_sampleclk_set_phase(struct clk_hw *hw, int degrees) - { struct sdhci_arasan_clk_data *clk_data = container_of(hw, struct sdhci_arasan_clk_data, sampleclk_hw); @@ -712,10 +720,11 @@ static const struct clk_ops zynqmp_sampleclk_ops = { /** * sdhci_versal_sdcardclk_set_phase - Set the SD Output Clock Tap Delays * + * @hw: Pointer to the hardware clock structure. + * @degrees: The clock phase shift between 0 - 359. + * * Set the SD Output Clock Tap Delays for Output path * - * @hw: Pointer to the hardware clock structure. - * @degrees The clock phase shift between 0 - 359. * Return: 0 on success and error value on error */ static int sdhci_versal_sdcardclk_set_phase(struct clk_hw *hw, int degrees) @@ -783,10 +792,11 @@ static const struct clk_ops versal_sdcardclk_ops = { /** * sdhci_versal_sampleclk_set_phase - Set the SD Input Clock Tap Delays * + * @hw: Pointer to the hardware clock structure. + * @degrees: The clock phase shift between 0 - 359. + * * Set the SD Input Clock Tap Delays for Input path * - * @hw: Pointer to the hardware clock structure. - * @degrees The clock phase shift between 0 - 359. * Return: 0 on success and error value on error */ static int sdhci_versal_sampleclk_set_phase(struct clk_hw *hw, int degrees) @@ -902,6 +912,9 @@ static int arasan_zynqmp_execute_tuning(struct mmc_host *mmc, u32 opcode) /** * sdhci_arasan_update_clockmultiplier - Set corecfg_clockmultiplier * + * @host: The sdhci_host + * @value: The value to write + * * The corecfg_clockmultiplier is supposed to contain clock multiplier * value of programmable clock generator. * @@ -913,8 +926,6 @@ static int arasan_zynqmp_execute_tuning(struct mmc_host *mmc, u32 opcode) * - The value of corecfg_clockmultiplier should sync with that of corresponding * value reading from sdhci_capability_register. So this function is called * once at probe time and never called again. - * - * @host: The sdhci_host */ static void sdhci_arasan_update_clockmultiplier(struct sdhci_host *host, u32 value) @@ -941,6 +952,8 @@ static void sdhci_arasan_update_clockmultiplier(struct sdhci_host *host, /** * sdhci_arasan_update_baseclkfreq - Set corecfg_baseclkfreq * + * @host: The sdhci_host + * * The corecfg_baseclkfreq is supposed to contain the MHz of clk_xin. This * function can be used to make that happen. * @@ -952,8 +965,6 @@ static void sdhci_arasan_update_clockmultiplier(struct sdhci_host *host, * - It's assumed that clk_xin is not dynamic and that we use the SDHCI divider * to achieve lower clock rates. That means that this function is called once * at probe time and never called again. - * - * @host: The sdhci_host */ static void sdhci_arasan_update_baseclkfreq(struct sdhci_host *host) { @@ -1017,10 +1028,10 @@ static void arasan_dt_read_clk_phase(struct device *dev, /** * arasan_dt_parse_clk_phases - Read Clock Delay values from DT * - * Called at initialization to parse the values of Clock Delays. - * * @dev: Pointer to our struct device. * @clk_data: Pointer to the Clock Data structure + * + * Called at initialization to parse the values of Clock Delays. */ static void arasan_dt_parse_clk_phases(struct device *dev, struct sdhci_arasan_clk_data *clk_data) @@ -1191,14 +1202,15 @@ MODULE_DEVICE_TABLE(of, sdhci_arasan_of_match); /** * sdhci_arasan_register_sdcardclk - Register the sdcardclk for a PHY to use * + * @sdhci_arasan: Our private data structure. + * @clk_xin: Pointer to the functional clock + * @dev: Pointer to our struct device. + * * Some PHY devices need to know what the actual card clock is. In order for * them to find out, we'll provide a clock through the common clock framework * for them to query. * - * @sdhci_arasan: Our private data structure. - * @clk_xin: Pointer to the functional clock - * @dev: Pointer to our struct device. - * Returns 0 on success and error value on error + * Return: 0 on success and error value on error */ static int sdhci_arasan_register_sdcardclk(struct sdhci_arasan_data *sdhci_arasan, @@ -1240,14 +1252,15 @@ sdhci_arasan_register_sdcardclk(struct sdhci_arasan_data *sdhci_arasan, /** * sdhci_arasan_register_sampleclk - Register the sampleclk for a PHY to use * + * @sdhci_arasan: Our private data structure. + * @clk_xin: Pointer to the functional clock + * @dev: Pointer to our struct device. + * * Some PHY devices need to know what the actual card clock is. In order for * them to find out, we'll provide a clock through the common clock framework * for them to query. * - * @sdhci_arasan: Our private data structure. - * @clk_xin: Pointer to the functional clock - * @dev: Pointer to our struct device. - * Returns 0 on success and error value on error + * Return: 0 on success and error value on error */ static int sdhci_arasan_register_sampleclk(struct sdhci_arasan_data *sdhci_arasan, @@ -1289,10 +1302,10 @@ sdhci_arasan_register_sampleclk(struct sdhci_arasan_data *sdhci_arasan, /** * sdhci_arasan_unregister_sdclk - Undoes sdhci_arasan_register_sdclk() * + * @dev: Pointer to our struct device. + * * Should be called any time we're exiting and sdhci_arasan_register_sdclk() * returned success. - * - * @dev: Pointer to our struct device. */ static void sdhci_arasan_unregister_sdclk(struct device *dev) { @@ -1307,6 +1320,10 @@ static void sdhci_arasan_unregister_sdclk(struct device *dev) /** * sdhci_arasan_register_sdclk - Register the sdcardclk for a PHY to use * + * @sdhci_arasan: Our private data structure. + * @clk_xin: Pointer to the functional clock + * @dev: Pointer to our struct device. + * * Some PHY devices need to know what the actual card clock is. In order for * them to find out, we'll provide a clock through the common clock framework * for them to query. @@ -1319,10 +1336,7 @@ static void sdhci_arasan_unregister_sdclk(struct device *dev) * to create nice clean device tree bindings and later (if needed) we can try * re-architecting SDHCI if we see some benefit to it. * - * @sdhci_arasan: Our private data structure. - * @clk_xin: Pointer to the functional clock - * @dev: Pointer to our struct device. - * Returns 0 on success and error value on error + * Return: 0 on success and error value on error */ static int sdhci_arasan_register_sdclk(struct sdhci_arasan_data *sdhci_arasan, struct clk *clk_xin, -- GitLab