OMAP clockdomain/powerdomain: improve documentation
This patch only affects documentation; no functional changes are
included.
Clean up comments in the current clockdomain, powerdomain code and
header files. This mostly involves conversion to kerneldoc format,
although some clarifications are also included.
Signed-off-by: Paul Walmsley <paul@pwsan.com>
diff --git a/arch/arm/mach-omap2/clockdomain.c b/arch/arm/mach-omap2/clockdomain.c
index 6eaa931..a38a615 100644
--- a/arch/arm/mach-omap2/clockdomain.c
+++ b/arch/arm/mach-omap2/clockdomain.c
@@ -351,10 +351,10 @@
* @init_autodeps: optional pointer to an array of autodeps to register
*
* Set up internal state. If a pointer to an array of clockdomains
- * was supplied, loop through the list of clockdomains, register all
- * that are available on the current platform. Similarly, if a pointer
- * to an array of clockdomain autodependencies was provided, register
- * those. No return value.
+ * @clkdms was supplied, loop through the list of clockdomains,
+ * register all that are available on the current platform. Similarly,
+ * if a pointer to an array of clockdomain autodependencies
+ * @init_autodeps was provided, register those. No return value.
*/
void clkdm_init(struct clockdomain **clkdms,
struct clkdm_autodep *init_autodeps)
@@ -386,8 +386,8 @@
* clkdm_lookup - look up a clockdomain by name, return a pointer
* @name: name of clockdomain
*
- * Find a registered clockdomain by its name. Returns a pointer to the
- * struct clockdomain if found, or NULL otherwise.
+ * Find a registered clockdomain by its name @name. Returns a pointer
+ * to the struct clockdomain if found, or NULL otherwise.
*/
struct clockdomain *clkdm_lookup(const char *name)
{
@@ -412,8 +412,8 @@
* clkdm_for_each - call function on each registered clockdomain
* @fn: callback function *
*
- * Call the supplied function for each registered clockdomain.
- * The callback function can return anything but 0 to bail
+ * Call the supplied function @fn for each registered clockdomain.
+ * The callback function @fn can return anything but 0 to bail
* out early from the iterator. The callback function is called with
* the clkdm_mutex held, so no clockdomain structure manipulation
* functions should be called from the callback, although hardware
@@ -446,7 +446,7 @@
* @clkdm: struct clockdomain *
*
* Return a pointer to the struct powerdomain that the specified clockdomain
- * 'clkdm' exists in, or returns NULL if clkdm argument is NULL.
+ * @clkdm exists in, or returns NULL if @clkdm is NULL.
*/
struct powerdomain *clkdm_get_pwrdm(struct clockdomain *clkdm)
{
@@ -759,10 +759,10 @@
/**
* omap2_clkdm_clktrctrl_read - read the clkdm's current state transition mode
- * @clk: struct clk * of a clockdomain
+ * @clkdm: struct clkdm * of a clockdomain
*
- * Return the clockdomain's current state transition mode from the
- * corresponding domain OMAP2_CM_CLKSTCTRL register. Returns -EINVAL if clk
+ * Return the clockdomain @clkdm current state transition mode from the
+ * corresponding domain CM_CLKSTCTRL register. Returns -EINVAL if @clkdm
* is NULL or the current mode upon success.
*/
static int omap2_clkdm_clktrctrl_read(struct clockdomain *clkdm)
@@ -784,7 +784,7 @@
* @clkdm: struct clockdomain *
*
* Instruct the CM to force a sleep transition on the specified
- * clockdomain 'clkdm'. Returns -EINVAL if clk is NULL or if
+ * clockdomain @clkdm. Returns -EINVAL if @clkdm is NULL or if
* clockdomain does not support software-initiated sleep; 0 upon
* success.
*/
@@ -828,7 +828,7 @@
* @clkdm: struct clockdomain *
*
* Instruct the CM to force a wakeup transition on the specified
- * clockdomain 'clkdm'. Returns -EINVAL if clkdm is NULL or if the
+ * clockdomain @clkdm. Returns -EINVAL if @clkdm is NULL or if the
* clockdomain does not support software-controlled wakeup; 0 upon
* success.
*/
@@ -871,7 +871,7 @@
* omap2_clkdm_allow_idle - enable hwsup idle transitions for clkdm
* @clkdm: struct clockdomain *
*
- * Allow the hardware to automatically switch the clockdomain into
+ * Allow the hardware to automatically switch the clockdomain @clkdm into
* active or idle states, as needed by downstream clocks. If the
* clockdomain has any downstream clocks enabled in the clock
* framework, wkdep/sleepdep autodependencies are added; this is so
@@ -904,8 +904,8 @@
* @clkdm: struct clockdomain *
*
* Prevent the hardware from automatically switching the clockdomain
- * into inactive or idle states. If the clockdomain has downstream
- * clocks enabled in the clock framework, wkdep/sleepdep
+ * @clkdm into inactive or idle states. If the clockdomain has
+ * downstream clocks enabled in the clock framework, wkdep/sleepdep
* autodependencies are removed. No return value.
*/
void omap2_clkdm_deny_idle(struct clockdomain *clkdm)
@@ -936,14 +936,14 @@
* @clkdm: struct clockdomain *
* @clk: struct clk * of the enabled downstream clock
*
- * Increment the usecount of this clockdomain 'clkdm' and ensure that
- * it is awake. Intended to be called by clk_enable() code. If the
- * clockdomain is in software-supervised idle mode, force the
- * clockdomain to wake. If the clockdomain is in hardware-supervised
- * idle mode, add clkdm-pwrdm autodependencies, to ensure that devices
- * in the clockdomain can be read from/written to by on-chip processors.
- * Returns -EINVAL if passed null pointers; returns 0 upon success or
- * if the clockdomain is in hwsup idle mode.
+ * Increment the usecount of the clockdomain @clkdm and ensure that it
+ * is awake before @clk is enabled. Intended to be called by
+ * clk_enable() code. If the clockdomain is in software-supervised
+ * idle mode, force the clockdomain to wake. If the clockdomain is in
+ * hardware-supervised idle mode, add clkdm-pwrdm autodependencies, to
+ * ensure that devices in the clockdomain can be read from/written to
+ * by on-chip processors. Returns -EINVAL if passed null pointers;
+ * returns 0 upon success or if the clockdomain is in hwsup idle mode.
*/
int omap2_clkdm_clk_enable(struct clockdomain *clkdm, struct clk *clk)
{
@@ -988,13 +988,14 @@
* @clkdm: struct clockdomain *
* @clk: struct clk * of the disabled downstream clock
*
- * Decrement the usecount of this clockdomain 'clkdm'. Intended to be
- * called by clk_disable() code. If the usecount goes to 0, put the
- * clockdomain to sleep (software-supervised mode) or remove the
- * clkdm-pwrdm autodependencies (hardware-supervised mode). Returns
- * -EINVAL if passed null pointers; -ERANGE if the clkdm usecount
- * underflows and debugging is enabled; or returns 0 upon success or
- * if the clockdomain is in hwsup idle mode.
+ * Decrement the usecount of this clockdomain @clkdm when @clk is
+ * disabled. Intended to be called by clk_disable() code. If the
+ * clockdomain usecount goes to 0, put the clockdomain to sleep
+ * (software-supervised mode) or remove the clkdm autodependencies
+ * (hardware-supervised mode). Returns -EINVAL if passed null
+ * pointers; -ERANGE if the @clkdm usecount underflows and debugging
+ * is enabled; or returns 0 upon success or if the clockdomain is in
+ * hwsup idle mode.
*/
int omap2_clkdm_clk_disable(struct clockdomain *clkdm, struct clk *clk)
{