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

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.comSigned-off-by: default avatarUlf Hansson <ulf.hansson@linaro.org>
parent 16ada730
...@@ -73,13 +73,13 @@ struct sdhci_arasan_soc_ctl_field { ...@@ -73,13 +73,13 @@ struct sdhci_arasan_soc_ctl_field {
/** /**
* struct sdhci_arasan_soc_ctl_map - Map in syscon to corecfg registers * 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 * @baseclkfreq: Where to find corecfg_baseclkfreq
* @clockmultiplier: Where to find corecfg_clockmultiplier * @clockmultiplier: Where to find corecfg_clockmultiplier
* @hiword_update: If true, use HIWORD_UPDATE to access the syscon * @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_map {
struct sdhci_arasan_soc_ctl_field baseclkfreq; struct sdhci_arasan_soc_ctl_field baseclkfreq;
...@@ -99,7 +99,8 @@ struct sdhci_arasan_clk_ops { ...@@ -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_hw: Struct for the clock we might provide to a PHY.
* @sdcardclk: Pointer to normal 'struct clock' for sdcardclk_hw. * @sdcardclk: Pointer to normal 'struct clock' for sdcardclk_hw.
* @sampleclk_hw: Struct for the clock we might provide to a PHY. * @sampleclk_hw: Struct for the clock we might provide to a PHY.
...@@ -125,15 +126,18 @@ struct sdhci_arasan_zynqmp_clk_data { ...@@ -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. * @host: Pointer to the main SDHCI host structure.
* @clk_ahb: Pointer to the AHB clock * @clk_ahb: Pointer to the AHB clock
* @phy: Pointer to the generic phy * @phy: Pointer to the generic phy
* @is_phy_on: True if the PHY is on; false if not. * @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_data: Struct for the Arasan Controller Clock Data.
* @clk_ops: Struct for the Arasan Controller Clock Operations. * @clk_ops: Struct for the Arasan Controller Clock Operations.
* @soc_ctl_base: Pointer to regmap for syscon for soc_ctl registers. * @soc_ctl_base: Pointer to regmap for syscon for soc_ctl registers.
* @soc_ctl_map: Map to get offsets into 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_arasan_data {
struct sdhci_host *host; struct sdhci_host *host;
...@@ -147,7 +151,7 @@ struct sdhci_arasan_data { ...@@ -147,7 +151,7 @@ struct sdhci_arasan_data {
struct regmap *soc_ctl_base; struct regmap *soc_ctl_base;
const struct sdhci_arasan_soc_ctl_map *soc_ctl_map; 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 */ /* Controller does not have CD wired and will not function normally without */
#define SDHCI_ARASAN_QUIRK_FORCE_CDTEST BIT(0) #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 = { ...@@ -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 * 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. * 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 * 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 * this function will silently return an error code. It will be noisy
* and print errors for any other (unexpected) errors. * and print errors for any other (unexpected) errors.
* *
* @host: The sdhci_host * Return: 0 on success and error value on error
* @fld: The field to write to
* @val: The value to write
*/ */
static int sdhci_arasan_syscon_write(struct sdhci_host *host, static int sdhci_arasan_syscon_write(struct sdhci_host *host,
const struct sdhci_arasan_soc_ctl_field *fld, const struct sdhci_arasan_soc_ctl_field *fld,
...@@ -420,9 +426,10 @@ static const struct sdhci_pltfm_data sdhci_arasan_cqe_pdata = { ...@@ -420,9 +426,10 @@ static const struct sdhci_pltfm_data sdhci_arasan_cqe_pdata = {
/** /**
* sdhci_arasan_suspend - Suspend method for the driver * sdhci_arasan_suspend - Suspend method for the driver
* @dev: Address of the device structure * @dev: Address of the device structure
* Returns 0 on success and error value on error
* *
* Put the device in a low power state. * 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) static int sdhci_arasan_suspend(struct device *dev)
{ {
...@@ -463,9 +470,10 @@ 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 * sdhci_arasan_resume - Resume method for the driver
* @dev: Address of the device structure * @dev: Address of the device structure
* Returns 0 on success and error value on error
* *
* Resume operation after suspend * Resume operation after suspend
*
* Return: 0 on success and error value on error
*/ */
static int sdhci_arasan_resume(struct device *dev) 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, ...@@ -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 * 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 * Return the current actual rate of the SD card clock. This can be used
* to communicate with out PHY. * to communicate with out PHY.
* *
* @hw: Pointer to the hardware clock structure. * Return: The card clock rate.
* @parent_rate The parent rate (should be rate of clk_xin).
* Returns the card clock rate.
*/ */
static unsigned long sdhci_arasan_sdcardclk_recalc_rate(struct clk_hw *hw, static unsigned long sdhci_arasan_sdcardclk_recalc_rate(struct clk_hw *hw,
unsigned long parent_rate) unsigned long parent_rate)
{ {
struct sdhci_arasan_clk_data *clk_data = struct sdhci_arasan_clk_data *clk_data =
container_of(hw, struct sdhci_arasan_clk_data, sdcardclk_hw); container_of(hw, struct sdhci_arasan_clk_data, sdcardclk_hw);
...@@ -541,16 +549,16 @@ static const struct clk_ops arasan_sdcardclk_ops = { ...@@ -541,16 +549,16 @@ static const struct clk_ops arasan_sdcardclk_ops = {
/** /**
* sdhci_arasan_sampleclk_recalc_rate - Return the sampling clock rate * 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 * Return the current actual rate of the sampling clock. This can be used
* to communicate with out PHY. * to communicate with out PHY.
* *
* @hw: Pointer to the hardware clock structure. * Return: The sample clock rate.
* @parent_rate The parent rate (should be rate of clk_xin).
* Returns the sample clock rate.
*/ */
static unsigned long sdhci_arasan_sampleclk_recalc_rate(struct clk_hw *hw, static unsigned long sdhci_arasan_sampleclk_recalc_rate(struct clk_hw *hw,
unsigned long parent_rate) unsigned long parent_rate)
{ {
struct sdhci_arasan_clk_data *clk_data = struct sdhci_arasan_clk_data *clk_data =
container_of(hw, struct sdhci_arasan_clk_data, sampleclk_hw); container_of(hw, struct sdhci_arasan_clk_data, sampleclk_hw);
...@@ -568,14 +576,14 @@ static const struct clk_ops arasan_sampleclk_ops = { ...@@ -568,14 +576,14 @@ static const struct clk_ops arasan_sampleclk_ops = {
/** /**
* sdhci_zynqmp_sdcardclk_set_phase - Set the SD Output Clock Tap Delays * 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 * 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 * Return: 0 on success and error value on error
*/ */
static int sdhci_zynqmp_sdcardclk_set_phase(struct clk_hw *hw, int degrees) static int sdhci_zynqmp_sdcardclk_set_phase(struct clk_hw *hw, int degrees)
{ {
struct sdhci_arasan_clk_data *clk_data = struct sdhci_arasan_clk_data *clk_data =
container_of(hw, struct sdhci_arasan_clk_data, sdcardclk_hw); container_of(hw, struct sdhci_arasan_clk_data, sdcardclk_hw);
...@@ -640,14 +648,14 @@ static const struct clk_ops zynqmp_sdcardclk_ops = { ...@@ -640,14 +648,14 @@ static const struct clk_ops zynqmp_sdcardclk_ops = {
/** /**
* sdhci_zynqmp_sampleclk_set_phase - Set the SD Input Clock Tap Delays * 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 * 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 * Return: 0 on success and error value on error
*/ */
static int sdhci_zynqmp_sampleclk_set_phase(struct clk_hw *hw, int degrees) static int sdhci_zynqmp_sampleclk_set_phase(struct clk_hw *hw, int degrees)
{ {
struct sdhci_arasan_clk_data *clk_data = struct sdhci_arasan_clk_data *clk_data =
container_of(hw, struct sdhci_arasan_clk_data, sampleclk_hw); container_of(hw, struct sdhci_arasan_clk_data, sampleclk_hw);
...@@ -712,10 +720,11 @@ static const struct clk_ops zynqmp_sampleclk_ops = { ...@@ -712,10 +720,11 @@ static const struct clk_ops zynqmp_sampleclk_ops = {
/** /**
* sdhci_versal_sdcardclk_set_phase - Set the SD Output Clock Tap Delays * 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 * 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 * Return: 0 on success and error value on error
*/ */
static int sdhci_versal_sdcardclk_set_phase(struct clk_hw *hw, int degrees) 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 = { ...@@ -783,10 +792,11 @@ static const struct clk_ops versal_sdcardclk_ops = {
/** /**
* sdhci_versal_sampleclk_set_phase - Set the SD Input Clock Tap Delays * 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 * 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 * Return: 0 on success and error value on error
*/ */
static int sdhci_versal_sampleclk_set_phase(struct clk_hw *hw, int degrees) 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) ...@@ -902,6 +912,9 @@ static int arasan_zynqmp_execute_tuning(struct mmc_host *mmc, u32 opcode)
/** /**
* sdhci_arasan_update_clockmultiplier - Set corecfg_clockmultiplier * 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 * The corecfg_clockmultiplier is supposed to contain clock multiplier
* value of programmable clock generator. * value of programmable clock generator.
* *
...@@ -913,8 +926,6 @@ static int arasan_zynqmp_execute_tuning(struct mmc_host *mmc, u32 opcode) ...@@ -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 * - The value of corecfg_clockmultiplier should sync with that of corresponding
* value reading from sdhci_capability_register. So this function is called * value reading from sdhci_capability_register. So this function is called
* once at probe time and never called again. * once at probe time and never called again.
*
* @host: The sdhci_host
*/ */
static void sdhci_arasan_update_clockmultiplier(struct sdhci_host *host, static void sdhci_arasan_update_clockmultiplier(struct sdhci_host *host,
u32 value) u32 value)
...@@ -941,6 +952,8 @@ static void sdhci_arasan_update_clockmultiplier(struct sdhci_host *host, ...@@ -941,6 +952,8 @@ static void sdhci_arasan_update_clockmultiplier(struct sdhci_host *host,
/** /**
* sdhci_arasan_update_baseclkfreq - Set corecfg_baseclkfreq * sdhci_arasan_update_baseclkfreq - Set corecfg_baseclkfreq
* *
* @host: The sdhci_host
*
* The corecfg_baseclkfreq is supposed to contain the MHz of clk_xin. This * The corecfg_baseclkfreq is supposed to contain the MHz of clk_xin. This
* function can be used to make that happen. * function can be used to make that happen.
* *
...@@ -952,8 +965,6 @@ static void sdhci_arasan_update_clockmultiplier(struct sdhci_host *host, ...@@ -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 * - 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 * to achieve lower clock rates. That means that this function is called once
* at probe time and never called again. * at probe time and never called again.
*
* @host: The sdhci_host
*/ */
static void sdhci_arasan_update_baseclkfreq(struct sdhci_host *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, ...@@ -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 * 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. * @dev: Pointer to our struct device.
* @clk_data: Pointer to the Clock Data structure * @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, static void arasan_dt_parse_clk_phases(struct device *dev,
struct sdhci_arasan_clk_data *clk_data) struct sdhci_arasan_clk_data *clk_data)
...@@ -1191,14 +1202,15 @@ MODULE_DEVICE_TABLE(of, sdhci_arasan_of_match); ...@@ -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_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 * 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 * them to find out, we'll provide a clock through the common clock framework
* for them to query. * for them to query.
* *
* @sdhci_arasan: Our private data structure. * Return: 0 on success and error value on error
* @clk_xin: Pointer to the functional clock
* @dev: Pointer to our struct device.
* Returns 0 on success and error value on error
*/ */
static int static int
sdhci_arasan_register_sdcardclk(struct sdhci_arasan_data *sdhci_arasan, sdhci_arasan_register_sdcardclk(struct sdhci_arasan_data *sdhci_arasan,
...@@ -1240,14 +1252,15 @@ 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_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 * 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 * them to find out, we'll provide a clock through the common clock framework
* for them to query. * for them to query.
* *
* @sdhci_arasan: Our private data structure. * Return: 0 on success and error value on error
* @clk_xin: Pointer to the functional clock
* @dev: Pointer to our struct device.
* Returns 0 on success and error value on error
*/ */
static int static int
sdhci_arasan_register_sampleclk(struct sdhci_arasan_data *sdhci_arasan, sdhci_arasan_register_sampleclk(struct sdhci_arasan_data *sdhci_arasan,
...@@ -1289,10 +1302,10 @@ 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() * 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() * Should be called any time we're exiting and sdhci_arasan_register_sdclk()
* returned success. * returned success.
*
* @dev: Pointer to our struct device.
*/ */
static void sdhci_arasan_unregister_sdclk(struct device *dev) static void sdhci_arasan_unregister_sdclk(struct device *dev)
{ {
...@@ -1307,6 +1320,10 @@ 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_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 * 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 * them to find out, we'll provide a clock through the common clock framework
* for them to query. * for them to query.
...@@ -1319,10 +1336,7 @@ static void sdhci_arasan_unregister_sdclk(struct device *dev) ...@@ -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 * to create nice clean device tree bindings and later (if needed) we can try
* re-architecting SDHCI if we see some benefit to it. * re-architecting SDHCI if we see some benefit to it.
* *
* @sdhci_arasan: Our private data structure. * Return: 0 on success and error value on error
* @clk_xin: Pointer to the functional clock
* @dev: Pointer to our struct device.
* Returns 0 on success and error value on error
*/ */
static int sdhci_arasan_register_sdclk(struct sdhci_arasan_data *sdhci_arasan, static int sdhci_arasan_register_sdclk(struct sdhci_arasan_data *sdhci_arasan,
struct clk *clk_xin, struct clk *clk_xin,
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment