From 82ff21bd6f1c50c4e062a0c178583fb79494e113 Mon Sep 17 00:00:00 2001 From: Nishanth Menon Date: Thu, 25 Feb 2016 12:53:42 -0600 Subject: 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 Reviewed-by: Tom Rini --- arch/arm/mach-keystone/psc.c | 96 ++++++++++++++++++++++++-------------------- 1 file changed, 52 insertions(+), 44 deletions(-) (limited to 'arch') diff --git a/arch/arm/mach-keystone/psc.c b/arch/arm/mach-keystone/psc.c index 237e776e87..8991e23773 100644 --- a/arch/arm/mach-keystone/psc.c +++ b/arch/arm/mach-keystone/psc.c @@ -13,24 +13,27 @@ #include #include +/** + * psc_delay() - delay for psc + * + * Return: 10 + */ int psc_delay(void) { udelay(10); return 10; } -/* - * FUNCTION PURPOSE: Wait for end of transitional state - * - * DESCRIPTION: Polls pstat for the selected domain and waits for transitions - * to be complete. +/** + * psc_wait() - Wait for end of transitional state + * @domain_num: GPSC domain number * - * 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. + * 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. * - * 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 @@ int psc_wait(u32 domain_num) 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 @@ u32 psc_get_domain_num(u32 mod_num) 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 @@ int psc_set_state(u32 mod_num, u32 state) 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. + * + * Return: 0 on success, -1 if the module can't be powered up, or + * if there is a timeout waiting for the transition. * - * Returns 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 @@ int psc_enable_module(u32 mod_num) 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 @@ int psc_disable_module(u32 mod_num) 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 @@ int psc_set_reset_iso(u32 mod_num) 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) { -- cgit v1.2.1