Commit 4908460e authored by Manish Narani's avatar Manish Narani Committed by Ulf Hansson
Browse files

mmc: sdhci-of-arasan: Fix kernel-doc warnings 



Modify code to fix the warnings reported by kernel-doc for better
documentation.

Signed-off-by: default avatarManish Narani <manish.narani@xilinx.com>
Link: https://lore.kernel.org/r/1586195015-128992-7-git-send-email-manish.narani@xilinx.com


Signed-off-by: default avatarUlf Hansson <ulf.hansson@linaro.org>
parent 16ada730

drivers/mmc/host/sdhci-of-arasan.c

+64 −50
Original line number Diff line number Diff line
@@ -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,