time: fix various kernel-doc problems
Commit Message
Clean up kernel-doc complaints about function names and non-kernel-doc
comments in kernel/time/. Fixes these warnings:
kernel/time/time.c:479: warning: expecting prototype for set_normalized_timespec(). Prototype was for set_normalized_timespec64() instead
kernel/time/time.c:553: warning: expecting prototype for msecs_to_jiffies(). Prototype was for __msecs_to_jiffies() instead
kernel/time/timekeeping.c:1595: warning: contents before sections
kernel/time/timekeeping.c:1705: warning: This comment starts with '/**', but isn't a kernel-doc comment.
* We have three kinds of time sources to use for sleep time
kernel/time/timekeeping.c:1726: warning: This comment starts with '/**', but isn't a kernel-doc comment.
* 1) can be determined whether to use or not only when doing
kernel/time/tick-oneshot.c:21: warning: missing initial short description on line:
* tick_program_event
kernel/time/tick-oneshot.c:107: warning: expecting prototype for tick_check_oneshot_mode(). Prototype was for tick_oneshot_mode_active() instead
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: John Stultz <jstultz@google.com>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Stephen Boyd <sboyd@kernel.org>
Cc: Frederic Weisbecker <fweisbec@gmail.com>
Cc: Ingo Molnar <mingo@kernel.org>
---
kernel/time/tick-oneshot.c | 4 ++--
kernel/time/time.c | 8 ++++----
kernel/time/timekeeping.c | 8 ++++----
3 files changed, 10 insertions(+), 10 deletions(-)
Comments
Hi Randy,
Thank you for the patch! Perhaps something to improve:
[auto build test WARNING on tip/timers/core]
[also build test WARNING on tip/timers/nohz linus/master v6.2-rc2 next-20221226]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]
url: https://github.com/intel-lab-lkp/linux/commits/Randy-Dunlap/time-fix-various-kernel-doc-problems/20230103-113048
patch link: https://lore.kernel.org/r/20230103032849.12723-1-rdunlap%40infradead.org
patch subject: [PATCH] time: fix various kernel-doc problems
config: x86_64-rhel-8.3-rust
compiler: clang version 14.0.6 (https://github.com/llvm/llvm-project f28c006a5895fc0e329fe15fead81e37457cb1d1)
reproduce (this is a W=1 build):
wget https://raw.githubusercontent.com/intel/lkp-tests/master/sbin/make.cross -O ~/bin/make.cross
chmod +x ~/bin/make.cross
# https://github.com/intel-lab-lkp/linux/commit/856bf2d268b0558b5f99d7d077f2ab593b068899
git remote add linux-review https://github.com/intel-lab-lkp/linux
git fetch --no-tags linux-review Randy-Dunlap/time-fix-various-kernel-doc-problems/20230103-113048
git checkout 856bf2d268b0558b5f99d7d077f2ab593b068899
# save the config file
mkdir build_dir && cp config build_dir/.config
COMPILER_INSTALL_PATH=$HOME/0day COMPILER=clang make.cross W=1 O=build_dir ARCH=x86_64 olddefconfig
COMPILER_INSTALL_PATH=$HOME/0day COMPILER=clang make.cross W=1 O=build_dir ARCH=x86_64 SHELL=/bin/bash kernel/time/
If you fix the issue, kindly add following tag where applicable
| Reported-by: kernel test robot <lkp@intel.com>
All warnings (new ones prefixed by >>):
>> kernel/time/tick-oneshot.c:106:5: warning: no previous prototype for function 'tick_check_oneshot_mode' [-Wmissing-prototypes]
int tick_check_oneshot_mode(void)
^
kernel/time/tick-oneshot.c:106:1: note: declare 'static' if the function is not intended to be used outside of this translation unit
int tick_check_oneshot_mode(void)
^
static
1 warning generated.
vim +/tick_check_oneshot_mode +106 kernel/time/tick-oneshot.c
100
101 /**
102 * tick_check_oneshot_mode - check whether the system is in oneshot mode
103 *
104 * returns 1 when either nohz or highres are enabled. otherwise 0.
105 */
> 106 int tick_check_oneshot_mode(void)
107 {
108 unsigned long flags;
109 int ret;
110
111 local_irq_save(flags);
112 ret = __this_cpu_read(tick_cpu_device.mode) == TICKDEV_MODE_ONESHOT;
113 local_irq_restore(flags);
114
115 return ret;
116 }
117
Hi Randy,
Thank you for the patch! Perhaps something to improve:
[auto build test WARNING on tip/timers/core]
[also build test WARNING on tip/timers/nohz linus/master v6.2-rc2 next-20221226]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]
url: https://github.com/intel-lab-lkp/linux/commits/Randy-Dunlap/time-fix-various-kernel-doc-problems/20230103-113048
patch link: https://lore.kernel.org/r/20230103032849.12723-1-rdunlap%40infradead.org
patch subject: [PATCH] time: fix various kernel-doc problems
config: mips-allmodconfig
compiler: mips-linux-gcc (GCC) 12.1.0
reproduce (this is a W=1 build):
wget https://raw.githubusercontent.com/intel/lkp-tests/master/sbin/make.cross -O ~/bin/make.cross
chmod +x ~/bin/make.cross
# https://github.com/intel-lab-lkp/linux/commit/856bf2d268b0558b5f99d7d077f2ab593b068899
git remote add linux-review https://github.com/intel-lab-lkp/linux
git fetch --no-tags linux-review Randy-Dunlap/time-fix-various-kernel-doc-problems/20230103-113048
git checkout 856bf2d268b0558b5f99d7d077f2ab593b068899
# save the config file
mkdir build_dir && cp config build_dir/.config
COMPILER_INSTALL_PATH=$HOME/0day COMPILER=gcc-12.1.0 make.cross W=1 O=build_dir ARCH=mips olddefconfig
COMPILER_INSTALL_PATH=$HOME/0day COMPILER=gcc-12.1.0 make.cross W=1 O=build_dir ARCH=mips SHELL=/bin/bash kernel/
If you fix the issue, kindly add following tag where applicable
| Reported-by: kernel test robot <lkp@intel.com>
All warnings (new ones prefixed by >>):
>> kernel/time/tick-oneshot.c:106:5: warning: no previous prototype for 'tick_check_oneshot_mode' [-Wmissing-prototypes]
106 | int tick_check_oneshot_mode(void)
| ^~~~~~~~~~~~~~~~~~~~~~~
vim +/tick_check_oneshot_mode +106 kernel/time/tick-oneshot.c
100
101 /**
102 * tick_check_oneshot_mode - check whether the system is in oneshot mode
103 *
104 * returns 1 when either nohz or highres are enabled. otherwise 0.
105 */
> 106 int tick_check_oneshot_mode(void)
107 {
108 unsigned long flags;
109 int ret;
110
111 local_irq_save(flags);
112 ret = __this_cpu_read(tick_cpu_device.mode) == TICKDEV_MODE_ONESHOT;
113 local_irq_restore(flags);
114
115 return ret;
116 }
117
Hi Randy,
Thank you for the patch! Yet something to improve:
[auto build test ERROR on tip/timers/core]
[also build test ERROR on tip/timers/nohz linus/master v6.2-rc2 next-20221226]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]
url: https://github.com/intel-lab-lkp/linux/commits/Randy-Dunlap/time-fix-various-kernel-doc-problems/20230103-113048
patch link: https://lore.kernel.org/r/20230103032849.12723-1-rdunlap%40infradead.org
patch subject: [PATCH] time: fix various kernel-doc problems
config: x86_64-defconfig
compiler: gcc-11 (Debian 11.3.0-8) 11.3.0
reproduce (this is a W=1 build):
# https://github.com/intel-lab-lkp/linux/commit/856bf2d268b0558b5f99d7d077f2ab593b068899
git remote add linux-review https://github.com/intel-lab-lkp/linux
git fetch --no-tags linux-review Randy-Dunlap/time-fix-various-kernel-doc-problems/20230103-113048
git checkout 856bf2d268b0558b5f99d7d077f2ab593b068899
# save the config file
mkdir build_dir && cp config build_dir/.config
make W=1 O=build_dir ARCH=x86_64 olddefconfig
make W=1 O=build_dir ARCH=x86_64 SHELL=/bin/bash
If you fix the issue, kindly add following tag where applicable
| Reported-by: kernel test robot <lkp@intel.com>
All errors (new ones prefixed by >>):
ld: kernel/time/clocksource.o: in function `__clocksource_select':
clocksource.c:(.text+0xad): undefined reference to `tick_oneshot_mode_active'
ld: kernel/time/clocksource.o: in function `available_clocksource_show':
clocksource.c:(.text+0x395): undefined reference to `tick_oneshot_mode_active'
ld: kernel/time/tick-common.o: in function `tick_check_replacement':
tick-common.c:(.text+0x413): undefined reference to `tick_oneshot_mode_active'
>> ld: tick-common.c:(.text+0x472): undefined reference to `tick_oneshot_mode_active'
* Randy Dunlap <rdunlap@infradead.org> wrote:
> kernel/time/tick-oneshot.c:107: warning: expecting prototype for tick_check_oneshot_mode(). Prototype was for tick_oneshot_mode_active() instead
> --- a/kernel/time/tick-oneshot.c
> +++ b/kernel/time/tick-oneshot.c
> @@ -103,7 +103,7 @@ int tick_switch_to_oneshot(void (*handle
> *
> * returns 1 when either nohz or highres are enabled. otherwise 0.
> */
> -int tick_oneshot_mode_active(void)
> +int tick_check_oneshot_mode(void)
> {
> unsigned long flags;
> int ret;
This one looks wrong - did you change the name on the wrong line?
I've applied your patch, but fixed the above hunk to be:
@@ -99,7 +99,7 @@ int tick_switch_to_oneshot(void (*handle
}
/**
- * tick_check_oneshot_mode - check whether the system is in oneshot mode
+ * tick_oneshot_mode_active - check whether the system is in oneshot mode
*
* returns 1 when either nohz or highres are enabled. otherwise 0.
*/
Thanks,
Ingo
Hi Ingo,
On 1/3/23 02:06, Ingo Molnar wrote:
>
> * Randy Dunlap <rdunlap@infradead.org> wrote:
>
>> kernel/time/tick-oneshot.c:107: warning: expecting prototype for tick_check_oneshot_mode(). Prototype was for tick_oneshot_mode_active() instead
>
>> --- a/kernel/time/tick-oneshot.c
>> +++ b/kernel/time/tick-oneshot.c
>
>> @@ -103,7 +103,7 @@ int tick_switch_to_oneshot(void (*handle
>> *
>> * returns 1 when either nohz or highres are enabled. otherwise 0.
>> */
>> -int tick_oneshot_mode_active(void)
>> +int tick_check_oneshot_mode(void)
>> {
>> unsigned long flags;
>> int ret;
>
> This one looks wrong - did you change the name on the wrong line?
Yes, sorry about that.
> I've applied your patch, but fixed the above hunk to be:
>
> @@ -99,7 +99,7 @@ int tick_switch_to_oneshot(void (*handle
> }
>
> /**
> - * tick_check_oneshot_mode - check whether the system is in oneshot mode
> + * tick_oneshot_mode_active - check whether the system is in oneshot mode
> *
> * returns 1 when either nohz or highres are enabled. otherwise 0.
> */
>
> Thanks,
Thank you also.
@@ -462,7 +462,7 @@ struct __kernel_old_timeval ns_to_kernel
EXPORT_SYMBOL(ns_to_kernel_old_timeval);
/**
- * set_normalized_timespec - set timespec sec and nsec parts and normalize
+ * set_normalized_timespec64 - set timespec sec and nsec parts and normalize
*
* @ts: pointer to timespec variable to be set
* @sec: seconds to set
@@ -526,7 +526,7 @@ struct timespec64 ns_to_timespec64(s64 n
EXPORT_SYMBOL(ns_to_timespec64);
/**
- * msecs_to_jiffies: - convert milliseconds to jiffies
+ * __msecs_to_jiffies: - convert milliseconds to jiffies
* @m: time in milliseconds
*
* conversion is done as follows:
@@ -541,12 +541,12 @@ EXPORT_SYMBOL(ns_to_timespec64);
* handling any 32-bit overflows.
* for the details see __msecs_to_jiffies()
*
- * msecs_to_jiffies() checks for the passed in value being a constant
+ * __msecs_to_jiffies() checks for the passed in value being a constant
* via __builtin_constant_p() allowing gcc to eliminate most of the
* code, __msecs_to_jiffies() is called if the value passed does not
* allow constant folding and the actual conversion must be done at
* runtime.
- * the _msecs_to_jiffies helpers are the HZ dependent conversion
+ * The _msecs_to_jiffies helpers are the HZ dependent conversion
* routines found in include/linux/jiffies.h
*/
unsigned long __msecs_to_jiffies(const unsigned int m)
@@ -1590,10 +1590,10 @@ void __weak read_persistent_clock64(stru
/**
* read_persistent_wall_and_boot_offset - Read persistent clock, and also offset
* from the boot.
+ * @wall_time: current time as returned by persistent clock
+ * @boot_offset: offset that is defined as wall_time - boot_time
*
* Weak dummy function for arches that do not yet support it.
- * @wall_time: - current time as returned by persistent clock
- * @boot_offset: - offset that is defined as wall_time - boot_time
*
* The default function calculates offset based on the current value of
* local_clock(). This way architectures that support sched_clock() but don't
@@ -1701,7 +1701,7 @@ static void __timekeeping_inject_sleepti
}
#if defined(CONFIG_PM_SLEEP) && defined(CONFIG_RTC_HCTOSYS_DEVICE)
-/**
+/*
* We have three kinds of time sources to use for sleep time
* injection, the preference order is:
* 1) non-stop clocksource
@@ -1722,7 +1722,7 @@ bool timekeeping_rtc_skipresume(void)
return !suspend_timing_needed;
}
-/**
+/*
* 1) can be determined whether to use or not only when doing
* timekeeping_resume() which is invoked after rtc_suspend(),
* so we can't skip rtc_suspend() surely if system has 1).
@@ -18,7 +18,7 @@
#include "tick-internal.h"
/**
- * tick_program_event
+ * tick_program_event - program the CPU local timer device for the next event
*/
int tick_program_event(ktime_t expires, int force)
{
@@ -103,7 +103,7 @@ int tick_switch_to_oneshot(void (*handle
*
* returns 1 when either nohz or highres are enabled. otherwise 0.
*/
-int tick_oneshot_mode_active(void)
+int tick_check_oneshot_mode(void)
{
unsigned long flags;
int ret;