ARM: keystone2: psc: redo doc in kernel-doc format
u-boot coding style guidance in
http://www.denx.de/wiki/U-Boot/CodingStyle clearly mentions that the
kernel doc style shall be followed for documentation in u-boot.
Current PSC documentation standard does not, so fix that.
Signed-off-by: Nishanth Menon <nm@ti.com>
Reviewed-by: Tom Rini <trini@konsulko.com>
diff --git a/arch/arm/mach-keystone/psc.c b/arch/arm/mach-keystone/psc.c
index 237e776..8991e23 100644
--- a/arch/arm/mach-keystone/psc.c
+++ b/arch/arm/mach-keystone/psc.c
@@ -13,24 +13,27 @@
#include <asm/processor.h>
#include <asm/arch/psc_defs.h>
+/**
+ * psc_delay() - delay for psc
+ *
+ * Return: 10
+ */
int psc_delay(void)
{
udelay(10);
return 10;
}
-/*
- * FUNCTION PURPOSE: Wait for end of transitional state
+/**
+ * psc_wait() - Wait for end of transitional state
+ * @domain_num: GPSC domain number
*
- * DESCRIPTION: Polls pstat for the selected domain and waits for transitions
- * to be complete.
+ * Polls pstat for the selected domain and waits for transitions to be complete.
+ * Since this is boot loader code it is *ASSUMED* that interrupts are disabled
+ * and no other core is mucking around with the psc at the same time.
*
- * Since this is boot loader code it is *ASSUMED* that interrupts
- * are disabled and no other core is mucking around with the psc
- * at the same time.
- *
- * Returns 0 when the domain is free. Returns -1 if a timeout
- * occurred waiting for the completion.
+ * Return: 0 when the domain is free. Returns -1 if a timeout occurred waiting
+ * for the completion.
*/
int psc_wait(u32 domain_num)
{
@@ -59,6 +62,10 @@
return 0;
}
+/**
+ * psc_get_domain_num() - Get the domain number
+ * @mod_num: LPSC module number
+ */
u32 psc_get_domain_num(u32 mod_num)
{
u32 domain_num;
@@ -70,20 +77,19 @@
return domain_num;
}
-/*
- * FUNCTION PURPOSE: Power up/down a module
+/**
+ * psc_set_state() - powers up/down a module
+ * @mod_num: LPSC module number
+ * @state: 1 to enable, 0 to disable.
*
- * DESCRIPTION: Powers up/down the requested module and the associated power
- * domain if required. No action is taken it the module is
- * already powered up/down.
+ * Powers up/down the requested module and the associated power domain if
+ * required. No action is taken it the module is already powered up/down.
+ * This only controls modules. The domain in which the module resides will
+ * be left in the power on state. Multiple modules can exist in a power
+ * domain, so powering down the domain based on a single module is not done.
*
- * This only controls modules. The domain in which the module
- * resides will be left in the power on state. Multiple modules
- * can exist in a power domain, so powering down the domain based
- * on a single module is not done.
- *
- * Returns 0 on success, -1 if the module can't be powered up, or
- * if there is a timeout waiting for the transition.
+ * Return: 0 on success, -1 if the module can't be powered up, or if there is a
+ * timeout waiting for the transition.
*/
int psc_set_state(u32 mod_num, u32 state)
{
@@ -136,15 +142,16 @@
return psc_wait(domain_num);
}
-/*
- * FUNCTION PURPOSE: Power up a module
+/**
+ * psc_enable_module() - power up a module
+ * @mod_num: LPSC module number
*
- * DESCRIPTION: Powers up the requested module and the associated power domain
- * if required. No action is taken it the module is already
- * powered up.
+ * Powers up the requested module and the associated power domain
+ * if required. No action is taken it the module is already powered up.
*
- * Returns 0 on success, -1 if the module can't be powered up, or
- * if there is a timeout waiting for the transition.
+ * Return: 0 on success, -1 if the module can't be powered up, or
+ * if there is a timeout waiting for the transition.
+ *
*/
int psc_enable_module(u32 mod_num)
{
@@ -158,12 +165,11 @@
return psc_set_state(mod_num, PSC_REG_VAL_MDCTL_NEXT_ON);
}
-/*
- * FUNCTION PURPOSE: Power down a module
+/**
+ * psc_disable_module() - Power down a module
+ * @mod_num: LPSC module number
*
- * DESCRIPTION: Powers down the requested module.
- *
- * Returns 0 on success, -1 on failure or timeout.
+ * Return: 0 on success, -1 on failure or timeout.
*/
int psc_disable_module(u32 mod_num)
{
@@ -179,13 +185,16 @@
return psc_set_state(mod_num, PSC_REG_VAL_MDCTL_NEXT_SWRSTDISABLE);
}
-/*
- * FUNCTION PURPOSE: Set the reset isolation bit in mdctl
+/**
+ * psc_set_reset_iso() - Set the reset isolation bit in mdctl
+ * @mod_num: LPSC module number
*
- * DESCRIPTION: The reset isolation enable bit is set. The state of the module
- * is not changed. Returns 0 if the module config showed that
- * reset isolation is supported. Returns 1 otherwise. This is not
- * an error, but setting the bit in mdctl has no effect.
+ * The reset isolation enable bit is set. The state of the module is not
+ * changed.
+ *
+ * Return: 0 if the module config showed that reset isolation is supported.
+ * Returns 1 otherwise. This is not an error, but setting the bit in mdctl
+ * has no effect.
*/
int psc_set_reset_iso(u32 mod_num)
{
@@ -204,10 +213,9 @@
return 1;
}
-/*
- * FUNCTION PURPOSE: Disable a power domain
- *
- * DESCRIPTION: The power domain is disabled
+/**
+ * psc_disable_domain() - Disable a power domain
+ * @domain_num: GPSC domain number
*/
int psc_disable_domain(u32 domain_num)
{