* [PATCH 1/6] time: fix kernel-doc markup
@ 2020-11-13 7:24 Alex Shi
2020-11-13 7:24 ` [PATCH 2/6] timekeeping: add missed kernel-doc marks for 'tkf' Alex Shi
` (6 more replies)
0 siblings, 7 replies; 18+ messages in thread
From: Alex Shi @ 2020-11-13 7:24 UTC (permalink / raw)
To: john.stultz; +Cc: Thomas Gleixner, Stephen Boyd, linux-kernel
The kernel-doc interface error cause some warning:
kernel/time/timeconv.c:79: warning: Function parameter or member
'totalsecs' not described in 'time64_to_tm'
kernel/time/timeconv.c:79: warning: Function parameter or member
'offset' not described in 'time64_to_tm'
kernel/time/timeconv.c:79: warning: Function parameter or member
'result' not described in 'time64_to_tm'
Fix them.
Signed-off-by: Alex Shi <alex.shi@linux.alibaba.com>
Cc: John Stultz <john.stultz@linaro.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Stephen Boyd <sboyd@kernel.org>
Cc: linux-kernel@vger.kernel.org
---
kernel/time/timeconv.c | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/kernel/time/timeconv.c b/kernel/time/timeconv.c
index 589e0a552129..62e3b46717a6 100644
--- a/kernel/time/timeconv.c
+++ b/kernel/time/timeconv.c
@@ -70,10 +70,10 @@ static const unsigned short __mon_yday[2][13] = {
/**
* time64_to_tm - converts the calendar time to local broken-down time
*
- * @totalsecs the number of seconds elapsed since 00:00:00 on January 1, 1970,
+ * @totalsecs: the number of seconds elapsed since 00:00:00 on January 1, 1970,
* Coordinated Universal Time (UTC).
- * @offset offset seconds adding to totalsecs.
- * @result pointer to struct tm variable to receive broken-down time
+ * @offset: offset seconds adding to totalsecs.
+ * @result: pointer to struct tm variable to receive broken-down time
*/
void time64_to_tm(time64_t totalsecs, int offset, struct tm *result)
{
--
2.29.GIT
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 2/6] timekeeping: add missed kernel-doc marks for 'tkf'
2020-11-13 7:24 [PATCH 1/6] time: fix kernel-doc markup Alex Shi
@ 2020-11-13 7:24 ` Alex Shi
2020-11-15 20:08 ` Thomas Gleixner
2020-11-15 22:51 ` [tip: timers/core] timekeeping: Add missing parameter documentation for update_fast_timekeeper() tip-bot2 for Alex Shi
2020-11-13 7:24 ` [PATCH 3/6] timekeeping: add kernel-doc markup for pvclock notifier Alex Shi
` (5 subsequent siblings)
6 siblings, 2 replies; 18+ messages in thread
From: Alex Shi @ 2020-11-13 7:24 UTC (permalink / raw)
To: john.stultz; +Cc: Thomas Gleixner, Stephen Boyd, linux-kernel
Fix the kernel-doc markup and remove the following warning:
kernel/time/timekeeping.c:415: warning: Function parameter or member
'tkf' not described in 'update_fast_timekeeper'
kernel/time/timekeeping.c:464: warning: Function parameter or member
'tkf' not described in '__ktime_get_fast_ns'
Signed-off-by: Alex Shi <alex.shi@linux.alibaba.com>
Cc: John Stultz <john.stultz@linaro.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Stephen Boyd <sboyd@kernel.org>
Cc: linux-kernel@vger.kernel.org
---
kernel/time/timekeeping.c | 2 ++
1 file changed, 2 insertions(+)
diff --git a/kernel/time/timekeeping.c b/kernel/time/timekeeping.c
index daa0ff017819..d0f7cd1b8823 100644
--- a/kernel/time/timekeeping.c
+++ b/kernel/time/timekeeping.c
@@ -399,6 +399,7 @@ static inline u64 timekeeping_cycles_to_ns(const struct tk_read_base *tkr, u64 c
/**
* update_fast_timekeeper - Update the fast and NMI safe monotonic timekeeper.
* @tkr: Timekeeping readout base from which we take the update
+ * @tkf: NMI safe timekeeper
*
* We want to use this from any context including NMI and tracing /
* instrumenting the timekeeping code itself.
@@ -430,6 +431,7 @@ static void update_fast_timekeeper(const struct tk_read_base *tkr,
/**
* ktime_get_mono_fast_ns - Fast NMI safe access to clock monotonic
+ * @tkf: NMI safe timekeeper
*
* This timestamp is not guaranteed to be monotonic across an update.
* The timestamp is calculated by:
--
2.29.GIT
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 3/6] timekeeping: add kernel-doc markup for pvclock notifier
2020-11-13 7:24 [PATCH 1/6] time: fix kernel-doc markup Alex Shi
2020-11-13 7:24 ` [PATCH 2/6] timekeeping: add missed kernel-doc marks for 'tkf' Alex Shi
@ 2020-11-13 7:24 ` Alex Shi
2020-11-15 22:28 ` Thomas Gleixner
2020-11-15 22:51 ` [tip: timers/core] timekeeping: Add missing parameter docs for pvclock_gtod_[un]register_notifier() tip-bot2 for Alex Shi
2020-11-13 7:24 ` [PATCH 4/6] timekeeping: remove static functions from kernel-doc markup Alex Shi
` (4 subsequent siblings)
6 siblings, 2 replies; 18+ messages in thread
From: Alex Shi @ 2020-11-13 7:24 UTC (permalink / raw)
To: john.stultz; +Cc: Thomas Gleixner, Stephen Boyd, linux-kernel
Add the missed parameter explaination for kernel-doc markup to remove
warning:
kernel/time/timekeeping.c:651: warning: Function parameter or member
'nb' not described in 'pvclock_gtod_register_notifier'
kernel/time/timekeeping.c:670: warning: Function parameter or member
'nb' not described in 'pvclock_gtod_unregister_notifier'
Signed-off-by: Alex Shi <alex.shi@linux.alibaba.com>
Cc: John Stultz <john.stultz@linaro.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Stephen Boyd <sboyd@kernel.org>
Cc: linux-kernel@vger.kernel.org
---
kernel/time/timekeeping.c | 2 ++
1 file changed, 2 insertions(+)
diff --git a/kernel/time/timekeeping.c b/kernel/time/timekeeping.c
index d0f7cd1b8823..9db6aee48c52 100644
--- a/kernel/time/timekeeping.c
+++ b/kernel/time/timekeeping.c
@@ -648,6 +648,7 @@ static void update_pvclock_gtod(struct timekeeper *tk, bool was_set)
/**
* pvclock_gtod_register_notifier - register a pvclock timedata update listener
+ * @nb: a notifier entry which register on pvclock_gtod_chain.
*/
int pvclock_gtod_register_notifier(struct notifier_block *nb)
{
@@ -667,6 +668,7 @@ EXPORT_SYMBOL_GPL(pvclock_gtod_register_notifier);
/**
* pvclock_gtod_unregister_notifier - unregister a pvclock
* timedata update listener
+ * @nb: a notifier entry which unregister on pvclock_gtod_chain.
*/
int pvclock_gtod_unregister_notifier(struct notifier_block *nb)
{
--
2.29.GIT
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 4/6] timekeeping: remove static functions from kernel-doc markup
2020-11-13 7:24 [PATCH 1/6] time: fix kernel-doc markup Alex Shi
2020-11-13 7:24 ` [PATCH 2/6] timekeeping: add missed kernel-doc marks for 'tkf' Alex Shi
2020-11-13 7:24 ` [PATCH 3/6] timekeeping: add kernel-doc markup for pvclock notifier Alex Shi
@ 2020-11-13 7:24 ` Alex Shi
2020-11-15 22:51 ` [tip: timers/core] timekeeping: Remove " tip-bot2 for Alex Shi
2020-11-13 7:24 ` [PATCH 5/6] timekeeping: add ts/tk explaination for kernel-doc Alex Shi
` (3 subsequent siblings)
6 siblings, 1 reply; 18+ messages in thread
From: Alex Shi @ 2020-11-13 7:24 UTC (permalink / raw)
To: john.stultz; +Cc: Thomas Gleixner, Stephen Boyd, linux-kernel
There are couple of functions are 'static' without correct kernel-doc
marks. Since they are not likely be used by others, moving them out of
kernel-doc is better.
Signed-off-by: Alex Shi <alex.shi@linux.alibaba.com>
Cc: John Stultz <john.stultz@linaro.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Stephen Boyd <sboyd@kernel.org>
Cc: linux-kernel@vger.kernel.org
---
kernel/time/timekeeping.c | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/kernel/time/timekeeping.c b/kernel/time/timekeeping.c
index 9db6aee48c52..9bee13d94d70 100644
--- a/kernel/time/timekeeping.c
+++ b/kernel/time/timekeeping.c
@@ -1403,7 +1403,7 @@ void timekeeping_warp_clock(void)
}
}
-/**
+/*
* __timekeeping_set_tai_offset - Sets the TAI offset from UTC and monotonic
*
*/
@@ -1413,7 +1413,7 @@ static void __timekeeping_set_tai_offset(struct timekeeper *tk, s32 tai_offset)
tk->offs_tai = ktime_add(tk->offs_real, ktime_set(tai_offset, 0));
}
-/**
+/*
* change_clocksource - Swaps clocksources if a new one is available
*
* Accumulates current time interval and initializes new clocksource
@@ -2011,7 +2011,7 @@ static void timekeeping_adjust(struct timekeeper *tk, s64 offset)
}
}
-/**
+/*
* accumulate_nsecs_to_secs - Accumulates nsecs into secs
*
* Helper function that accumulates the nsecs greater than a second
@@ -2059,7 +2059,7 @@ static inline unsigned int accumulate_nsecs_to_secs(struct timekeeper *tk)
return clock_set;
}
-/**
+/*
* logarithmic_accumulation - shifted accumulation of cycles
*
* This functions accumulates a shifted interval of cycles into
@@ -2295,7 +2295,7 @@ ktime_t ktime_get_update_offsets_now(unsigned int *cwsseq, ktime_t *offs_real,
return base;
}
-/**
+/*
* timekeeping_validate_timex - Ensures the timex is ok for use in do_adjtimex
*/
static int timekeeping_validate_timex(const struct __kernel_timex *txc)
--
2.29.GIT
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 5/6] timekeeping: add ts/tk explaination for kernel-doc
2020-11-13 7:24 [PATCH 1/6] time: fix kernel-doc markup Alex Shi
` (2 preceding siblings ...)
2020-11-13 7:24 ` [PATCH 4/6] timekeeping: remove static functions from kernel-doc markup Alex Shi
@ 2020-11-13 7:24 ` Alex Shi
2020-11-15 22:19 ` Thomas Gleixner
2020-11-15 22:51 ` [tip: timers/core] timekeeping: Address parameter documentation issues for various functions tip-bot2 for Alex Shi
2020-11-13 7:24 ` [PATCH 6/6] timekeeping: fix kernel-doc mark issue on read_persistent_clock64 Alex Shi
` (2 subsequent siblings)
6 siblings, 2 replies; 18+ messages in thread
From: Alex Shi @ 2020-11-13 7:24 UTC (permalink / raw)
To: john.stultz; +Cc: Thomas Gleixner, Stephen Boyd, linux-kernel
this patch fixed kernel-doc mark incorrection:
kernel/time/timekeeping.c:1543: warning: Function parameter or member
'ts' not described in 'read_persistent_clock64'
kernel/time/timekeeping.c:764: warning: Function parameter or member
'tk' not described in 'timekeeping_forward_now'
kernel/time/timekeeping.c:1331: warning: Function parameter or member
'ts' not described in 'timekeeping_inject_offset'
kernel/time/timekeeping.c:1331: warning: Excess function parameter 'tv'
description in 'timekeeping_inject_offset'
Signed-off-by: Alex Shi <alex.shi@linux.alibaba.com>
Cc: John Stultz <john.stultz@linaro.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Stephen Boyd <sboyd@kernel.org>
Cc: linux-kernel@vger.kernel.org
---
kernel/time/timekeeping.c | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/kernel/time/timekeeping.c b/kernel/time/timekeeping.c
index 9bee13d94d70..08ab749a76fc 100644
--- a/kernel/time/timekeeping.c
+++ b/kernel/time/timekeeping.c
@@ -759,6 +759,7 @@ static void timekeeping_update(struct timekeeper *tk, unsigned int action)
/**
* timekeeping_forward_now - update clock to the current time
+ * @tk: pointer to time clock which will be correct.
*
* Forward the current clock to update its state since the last call to
* update_wall_time(). This is useful before significant clock changes,
@@ -1327,7 +1328,7 @@ EXPORT_SYMBOL(do_settimeofday64);
/**
* timekeeping_inject_offset - Adds or subtracts from the current time.
- * @tv: pointer to the timespec variable containing the offset
+ * @ts: pointer to the timespec variable containing the offset
*
* Adds or subtracts an offset value from the current time.
*/
@@ -1536,6 +1537,7 @@ u64 timekeeping_max_deferment(void)
/**
* read_persistent_clock64 - Return time from the persistent clock.
+ * @ts: pointer to timespec to initialize.
*
* Weak dummy function for arches that do not yet support it.
* Reads the time from the battery backed persistent clock.
@@ -1640,6 +1642,7 @@ static struct timespec64 timekeeping_suspend_time;
/**
* __timekeeping_inject_sleeptime - Internal function to add sleep interval
+ * @tk: pointer to a timekeeper to be updated
* @delta: pointer to a timespec delta value
*
* Takes a timespec offset measuring a suspend interval and properly
--
2.29.GIT
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 6/6] timekeeping: fix kernel-doc mark issue on read_persistent_clock64
2020-11-13 7:24 [PATCH 1/6] time: fix kernel-doc markup Alex Shi
` (3 preceding siblings ...)
2020-11-13 7:24 ` [PATCH 5/6] timekeeping: add ts/tk explaination for kernel-doc Alex Shi
@ 2020-11-13 7:24 ` Alex Shi
2020-11-15 22:15 ` Thomas Gleixner
2020-11-15 22:51 ` [tip: timers/core] timekeeping: Fix parameter docs of read_persistent_wall_and_boot_offset() tip-bot2 for Alex Shi
2020-11-15 22:48 ` [PATCH 1/6] time: fix kernel-doc markup Thomas Gleixner
2020-11-15 22:51 ` [tip: timers/core] time: Add missing colons for parameter documentation of time64_to_tm() tip-bot2 for Alex Shi
6 siblings, 2 replies; 18+ messages in thread
From: Alex Shi @ 2020-11-13 7:24 UTC (permalink / raw)
To: john.stultz; +Cc: Thomas Gleixner, Stephen Boyd, linux-kernel
Fix the kernel-doc markup:
kernel/time/timekeeping.c:1563: warning: Function parameter or member
'wall_time' not described in 'read_persistent_wall_and_boot_offset'
kernel/time/timekeeping.c:1563: warning: Function parameter or member
'boot_offset' not described in 'read_persistent_wall_and_boot_offset'
Signed-off-by: Alex Shi <alex.shi@linux.alibaba.com>
Cc: John Stultz <john.stultz@linaro.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Stephen Boyd <sboyd@kernel.org>
Cc: linux-kernel@vger.kernel.org
---
kernel/time/timekeeping.c | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/kernel/time/timekeeping.c b/kernel/time/timekeeping.c
index 08ab749a76fc..665e820bb883 100644
--- a/kernel/time/timekeeping.c
+++ b/kernel/time/timekeeping.c
@@ -1556,8 +1556,9 @@ void __weak read_persistent_clock64(struct timespec64 *ts)
* from the boot.
*
* 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
+ * @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
* support dedicated boot time clock will provide the best estimate of the
--
2.29.GIT
^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: [PATCH 2/6] timekeeping: add missed kernel-doc marks for 'tkf'
2020-11-13 7:24 ` [PATCH 2/6] timekeeping: add missed kernel-doc marks for 'tkf' Alex Shi
@ 2020-11-15 20:08 ` Thomas Gleixner
2020-11-15 22:51 ` [tip: timers/core] timekeeping: Add missing parameter documentation for update_fast_timekeeper() tip-bot2 for Alex Shi
1 sibling, 0 replies; 18+ messages in thread
From: Thomas Gleixner @ 2020-11-15 20:08 UTC (permalink / raw)
To: Alex Shi, john.stultz; +Cc: Stephen Boyd, linux-kernel
On Fri, Nov 13 2020 at 15:24, Alex Shi wrote:
> Fix the kernel-doc markup and remove the following warning:
> kernel/time/timekeeping.c:415: warning: Function parameter or member
> 'tkf' not described in 'update_fast_timekeeper'
> kernel/time/timekeeping.c:464: warning: Function parameter or member
> 'tkf' not described in '__ktime_get_fast_ns'
>
> diff --git a/kernel/time/timekeeping.c b/kernel/time/timekeeping.c
> index daa0ff017819..d0f7cd1b8823 100644
> --- a/kernel/time/timekeeping.c
> +++ b/kernel/time/timekeeping.c
> @@ -399,6 +399,7 @@ static inline u64 timekeeping_cycles_to_ns(const struct tk_read_base *tkr, u64 c
> /**
> * update_fast_timekeeper - Update the fast and NMI safe monotonic timekeeper.
> * @tkr: Timekeeping readout base from which we take the update
> + * @tkf: NMI safe timekeeper
> *
> * We want to use this from any context including NMI and tracing /
> * instrumenting the timekeeping code itself.
> @@ -430,6 +431,7 @@ static void update_fast_timekeeper(const struct tk_read_base *tkr,
>
> /**
> * ktime_get_mono_fast_ns - Fast NMI safe access to clock monotonic
> + * @tkf: NMI safe timekeeper
> *
> * This timestamp is not guaranteed to be monotonic across an update.
> * The timestamp is calculated by:
That's wrong. The documentation is for ktime_get_mono_fast_ns() which
does not have an argument, but due to an oversight the documentation is
now above __ktime_get_mono_fast_ns() which takes an argument.
I'm fixing it up.
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 6/6] timekeeping: fix kernel-doc mark issue on read_persistent_clock64
2020-11-13 7:24 ` [PATCH 6/6] timekeeping: fix kernel-doc mark issue on read_persistent_clock64 Alex Shi
@ 2020-11-15 22:15 ` Thomas Gleixner
2020-11-15 22:51 ` [tip: timers/core] timekeeping: Fix parameter docs of read_persistent_wall_and_boot_offset() tip-bot2 for Alex Shi
1 sibling, 0 replies; 18+ messages in thread
From: Thomas Gleixner @ 2020-11-15 22:15 UTC (permalink / raw)
To: Alex Shi, john.stultz; +Cc: Stephen Boyd, linux-kernel
On Fri, Nov 13 2020 at 15:24, Alex Shi wrote:
> Fix the kernel-doc markup:
> kernel/time/timekeeping.c:1563: warning: Function parameter or member
> 'wall_time' not described in 'read_persistent_wall_and_boot_offset'
> kernel/time/timekeeping.c:1563: warning: Function parameter or member
> 'boot_offset' not described in 'read_persistent_wall_and_boot_offset'
How is the subject related to the actual problem ?
Thanks,
tglx
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 5/6] timekeeping: add ts/tk explaination for kernel-doc
2020-11-13 7:24 ` [PATCH 5/6] timekeeping: add ts/tk explaination for kernel-doc Alex Shi
@ 2020-11-15 22:19 ` Thomas Gleixner
2020-11-15 22:51 ` [tip: timers/core] timekeeping: Address parameter documentation issues for various functions tip-bot2 for Alex Shi
1 sibling, 0 replies; 18+ messages in thread
From: Thomas Gleixner @ 2020-11-15 22:19 UTC (permalink / raw)
To: Alex Shi, john.stultz; +Cc: Stephen Boyd, linux-kernel
On Fri, Nov 13 2020 at 15:24, Alex Shi wrote:
Subject: timekeeping: add ts/tk explaination for kernel-doc
Sentence after the colon starts with an uppercase letter.
s/explaination/explanation/ Please use a spell checker.
Also what is ts/tk? The short log sentence has to be concise and easy to
understand and decribe what the patch does.
> this patch fixed kernel-doc mark incorrection:
'This patch fixed' ?
First of all, sentences start with an uppercase letter, but also please
do:
# git grep 'This patch' Documentation/process/
and read the paragraph which matches.
> /**
> * timekeeping_inject_offset - Adds or subtracts from the current time.
> - * @tv: pointer to the timespec variable containing the offset
> + * @ts: pointer to the timespec variable containing the offset
This is _not_ adding documention, it's fixing the wrongly named
parameter.
Thanks,
tglx
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 3/6] timekeeping: add kernel-doc markup for pvclock notifier
2020-11-13 7:24 ` [PATCH 3/6] timekeeping: add kernel-doc markup for pvclock notifier Alex Shi
@ 2020-11-15 22:28 ` Thomas Gleixner
2020-11-15 22:51 ` [tip: timers/core] timekeeping: Add missing parameter docs for pvclock_gtod_[un]register_notifier() tip-bot2 for Alex Shi
1 sibling, 0 replies; 18+ messages in thread
From: Thomas Gleixner @ 2020-11-15 22:28 UTC (permalink / raw)
To: Alex Shi, john.stultz; +Cc: Stephen Boyd, linux-kernel
On Fri, Nov 13 2020 at 15:24, Alex Shi wrote:
> /**
> * pvclock_gtod_register_notifier - register a pvclock timedata update listener
> + * @nb: a notifier entry which register on pvclock_gtod_chain.
What is a notifier entry? The struct is named notifier_block and the
argument is a pointer to a notifier block. So why making things up?
Also it's completely irrelevant for the reader to know about the name of
the notifier chain. The function documentation says:
register a pvclock timedata update listener
which precisely describes what the function does. pvclock_gtod_chain is
an internal implementation detail and nothing external can depend on it.
It could be renamed to 'foo_bar' and the function would still do the
same thing.
* @nb: Notifier block to register
is precise and good enough, isn't it?
Thanks,
tglx
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/6] time: fix kernel-doc markup
2020-11-13 7:24 [PATCH 1/6] time: fix kernel-doc markup Alex Shi
` (4 preceding siblings ...)
2020-11-13 7:24 ` [PATCH 6/6] timekeeping: fix kernel-doc mark issue on read_persistent_clock64 Alex Shi
@ 2020-11-15 22:48 ` Thomas Gleixner
2020-11-16 2:44 ` Alex Shi
2020-11-15 22:51 ` [tip: timers/core] time: Add missing colons for parameter documentation of time64_to_tm() tip-bot2 for Alex Shi
6 siblings, 1 reply; 18+ messages in thread
From: Thomas Gleixner @ 2020-11-15 22:48 UTC (permalink / raw)
To: Alex Shi, john.stultz; +Cc: Stephen Boyd, linux-kernel
On Fri, Nov 13 2020 at 15:24, Alex Shi wrote:
> The kernel-doc interface error cause some warning:
I fixes the lot up and applied it. Please look at the changes I did and
be more careful next time.
Thanks,
tglx
^ permalink raw reply [flat|nested] 18+ messages in thread
* [tip: timers/core] timekeeping: Address parameter documentation issues for various functions
2020-11-13 7:24 ` [PATCH 5/6] timekeeping: add ts/tk explaination for kernel-doc Alex Shi
2020-11-15 22:19 ` Thomas Gleixner
@ 2020-11-15 22:51 ` tip-bot2 for Alex Shi
1 sibling, 0 replies; 18+ messages in thread
From: tip-bot2 for Alex Shi @ 2020-11-15 22:51 UTC (permalink / raw)
To: linux-tip-commits; +Cc: Alex Shi, Thomas Gleixner, x86, linux-kernel
The following commit has been merged into the timers/core branch of tip:
Commit-ID: 6e5a91901c2dff3a0f2eb9f10e427dce2b0488fc
Gitweb: https://git.kernel.org/tip/6e5a91901c2dff3a0f2eb9f10e427dce2b0488fc
Author: Alex Shi <alex.shi@linux.alibaba.com>
AuthorDate: Fri, 13 Nov 2020 15:24:34 +08:00
Committer: Thomas Gleixner <tglx@linutronix.de>
CommitterDate: Sun, 15 Nov 2020 23:47:24 +01:00
timekeeping: Address parameter documentation issues for various functions
The kernel-doc parser complains:
kernel/time/timekeeping.c:1543: warning: Function parameter or member
'ts' not described in 'read_persistent_clock64'
kernel/time/timekeeping.c:764: warning: Function parameter or member
'tk' not described in 'timekeeping_forward_now'
kernel/time/timekeeping.c:1331: warning: Function parameter or member
'ts' not described in 'timekeeping_inject_offset'
kernel/time/timekeeping.c:1331: warning: Excess function parameter 'tv'
description in 'timekeeping_inject_offset'
Add the missing parameter documentations and rename the 'tv' parameter of
timekeeping_inject_offset() to 'ts' so it matches the implemention.
[ tglx: Reworded a few docs and massaged changelog ]
Signed-off-by: Alex Shi <alex.shi@linux.alibaba.com>
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Link: https://lore.kernel.org/r/1605252275-63652-5-git-send-email-alex.shi@linux.alibaba.com
---
kernel/time/timekeeping.c | 7 +++++--
1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/kernel/time/timekeeping.c b/kernel/time/timekeeping.c
index 75cba95..74503c0 100644
--- a/kernel/time/timekeeping.c
+++ b/kernel/time/timekeeping.c
@@ -774,6 +774,7 @@ static void timekeeping_update(struct timekeeper *tk, unsigned int action)
/**
* timekeeping_forward_now - update clock to the current time
+ * @tk: Pointer to the timekeeper to update
*
* Forward the current clock to update its state since the last call to
* update_wall_time(). This is useful before significant clock changes,
@@ -1350,7 +1351,7 @@ EXPORT_SYMBOL(do_settimeofday64);
/**
* timekeeping_inject_offset - Adds or subtracts from the current time.
- * @tv: pointer to the timespec variable containing the offset
+ * @ts: Pointer to the timespec variable containing the offset
*
* Adds or subtracts an offset value from the current time.
*/
@@ -1558,6 +1559,7 @@ u64 timekeeping_max_deferment(void)
/**
* read_persistent_clock64 - Return time from the persistent clock.
+ * @ts: Pointer to the storage for the readout value
*
* Weak dummy function for arches that do not yet support it.
* Reads the time from the battery backed persistent clock.
@@ -1663,7 +1665,8 @@ static struct timespec64 timekeeping_suspend_time;
/**
* __timekeeping_inject_sleeptime - Internal function to add sleep interval
- * @delta: pointer to a timespec delta value
+ * @tk: Pointer to the timekeeper to be updated
+ * @delta: Pointer to the delta value in timespec64 format
*
* Takes a timespec offset measuring a suspend interval and properly
* adds the sleep offset to the timekeeping variables.
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [tip: timers/core] timekeeping: Fix parameter docs of read_persistent_wall_and_boot_offset()
2020-11-13 7:24 ` [PATCH 6/6] timekeeping: fix kernel-doc mark issue on read_persistent_clock64 Alex Shi
2020-11-15 22:15 ` Thomas Gleixner
@ 2020-11-15 22:51 ` tip-bot2 for Alex Shi
1 sibling, 0 replies; 18+ messages in thread
From: tip-bot2 for Alex Shi @ 2020-11-15 22:51 UTC (permalink / raw)
To: linux-tip-commits; +Cc: Alex Shi, Thomas Gleixner, x86, linux-kernel
The following commit has been merged into the timers/core branch of tip:
Commit-ID: 29efc4612ac1b888e65da408b41dafa4dd00842f
Gitweb: https://git.kernel.org/tip/29efc4612ac1b888e65da408b41dafa4dd00842f
Author: Alex Shi <alex.shi@linux.alibaba.com>
AuthorDate: Fri, 13 Nov 2020 15:24:35 +08:00
Committer: Thomas Gleixner <tglx@linutronix.de>
CommitterDate: Sun, 15 Nov 2020 23:47:24 +01:00
timekeeping: Fix parameter docs of read_persistent_wall_and_boot_offset()
Address the following kernel-doc markup warnings:
kernel/time/timekeeping.c:1563: warning: Function parameter or member
'wall_time' not described in 'read_persistent_wall_and_boot_offset'
kernel/time/timekeeping.c:1563: warning: Function parameter or member
'boot_offset' not described in 'read_persistent_wall_and_boot_offset'
The parameters are described but miss the leading '@' and the colon after
the parameter names.
[ tglx: Massaged changelog ]
Signed-off-by: Alex Shi <alex.shi@linux.alibaba.com>
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Link: https://lore.kernel.org/r/1605252275-63652-6-git-send-email-alex.shi@linux.alibaba.com
---
kernel/time/timekeeping.c | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/kernel/time/timekeeping.c b/kernel/time/timekeeping.c
index 9c93923..75cba95 100644
--- a/kernel/time/timekeeping.c
+++ b/kernel/time/timekeeping.c
@@ -1576,8 +1576,9 @@ void __weak read_persistent_clock64(struct timespec64 *ts)
* from the boot.
*
* 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
+ * @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
* support dedicated boot time clock will provide the best estimate of the
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [tip: timers/core] timekeeping: Add missing parameter docs for pvclock_gtod_[un]register_notifier()
2020-11-13 7:24 ` [PATCH 3/6] timekeeping: add kernel-doc markup for pvclock notifier Alex Shi
2020-11-15 22:28 ` Thomas Gleixner
@ 2020-11-15 22:51 ` tip-bot2 for Alex Shi
1 sibling, 0 replies; 18+ messages in thread
From: tip-bot2 for Alex Shi @ 2020-11-15 22:51 UTC (permalink / raw)
To: linux-tip-commits; +Cc: Alex Shi, Thomas Gleixner, x86, linux-kernel
The following commit has been merged into the timers/core branch of tip:
Commit-ID: f27f7c3f100e74a7f451a63a15788f50c52f7cce
Gitweb: https://git.kernel.org/tip/f27f7c3f100e74a7f451a63a15788f50c52f7cce
Author: Alex Shi <alex.shi@linux.alibaba.com>
AuthorDate: Fri, 13 Nov 2020 15:24:32 +08:00
Committer: Thomas Gleixner <tglx@linutronix.de>
CommitterDate: Sun, 15 Nov 2020 23:47:24 +01:00
timekeeping: Add missing parameter docs for pvclock_gtod_[un]register_notifier()
The kernel-doc parser complains about:
kernel/time/timekeeping.c:651: warning: Function parameter or member
'nb' not described in 'pvclock_gtod_register_notifier'
kernel/time/timekeeping.c:670: warning: Function parameter or member
'nb' not described in 'pvclock_gtod_unregister_notifier'
Add the missing parameter explanations.
[ tglx: Massaged changelog ]
Signed-off-by: Alex Shi <alex.shi@linux.alibaba.com>
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Link: https://lore.kernel.org/r/1605252275-63652-3-git-send-email-alex.shi@linux.alibaba.com
---
kernel/time/timekeeping.c | 2 ++
1 file changed, 2 insertions(+)
diff --git a/kernel/time/timekeeping.c b/kernel/time/timekeeping.c
index ab4b831..9c93923 100644
--- a/kernel/time/timekeeping.c
+++ b/kernel/time/timekeeping.c
@@ -663,6 +663,7 @@ static void update_pvclock_gtod(struct timekeeper *tk, bool was_set)
/**
* pvclock_gtod_register_notifier - register a pvclock timedata update listener
+ * @nb: Pointer to the notifier block to register
*/
int pvclock_gtod_register_notifier(struct notifier_block *nb)
{
@@ -682,6 +683,7 @@ EXPORT_SYMBOL_GPL(pvclock_gtod_register_notifier);
/**
* pvclock_gtod_unregister_notifier - unregister a pvclock
* timedata update listener
+ * @nb: Pointer to the notifier block to unregister
*/
int pvclock_gtod_unregister_notifier(struct notifier_block *nb)
{
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [tip: timers/core] timekeeping: Add missing parameter documentation for update_fast_timekeeper()
2020-11-13 7:24 ` [PATCH 2/6] timekeeping: add missed kernel-doc marks for 'tkf' Alex Shi
2020-11-15 20:08 ` Thomas Gleixner
@ 2020-11-15 22:51 ` tip-bot2 for Alex Shi
1 sibling, 0 replies; 18+ messages in thread
From: tip-bot2 for Alex Shi @ 2020-11-15 22:51 UTC (permalink / raw)
To: linux-tip-commits; +Cc: Alex Shi, Thomas Gleixner, x86, linux-kernel
The following commit has been merged into the timers/core branch of tip:
Commit-ID: e025b03113d27139ce2b28b82599018e4d8fa5f6
Gitweb: https://git.kernel.org/tip/e025b03113d27139ce2b28b82599018e4d8fa5f6
Author: Alex Shi <alex.shi@linux.alibaba.com>
AuthorDate: Fri, 13 Nov 2020 15:24:31 +08:00
Committer: Thomas Gleixner <tglx@linutronix.de>
CommitterDate: Sun, 15 Nov 2020 23:47:24 +01:00
timekeeping: Add missing parameter documentation for update_fast_timekeeper()
Address the following warning:
kernel/time/timekeeping.c:415: warning: Function parameter or member
'tkf' not described in 'update_fast_timekeeper'
[ tglx: Remove the bogus ktime_get_mono_fast_ns() part ]
Signed-off-by: Alex Shi <alex.shi@linux.alibaba.com>
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Link: https://lore.kernel.org/r/1605252275-63652-2-git-send-email-alex.shi@linux.alibaba.com
---
kernel/time/timekeeping.c | 1 +
1 file changed, 1 insertion(+)
diff --git a/kernel/time/timekeeping.c b/kernel/time/timekeeping.c
index 570fc50..a823703 100644
--- a/kernel/time/timekeeping.c
+++ b/kernel/time/timekeeping.c
@@ -407,6 +407,7 @@ static inline u64 timekeeping_cycles_to_ns(const struct tk_read_base *tkr, u64 c
/**
* update_fast_timekeeper - Update the fast and NMI safe monotonic timekeeper.
* @tkr: Timekeeping readout base from which we take the update
+ * @tkf: Pointer to NMI safe timekeeper
*
* We want to use this from any context including NMI and tracing /
* instrumenting the timekeeping code itself.
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [tip: timers/core] time: Add missing colons for parameter documentation of time64_to_tm()
2020-11-13 7:24 [PATCH 1/6] time: fix kernel-doc markup Alex Shi
` (5 preceding siblings ...)
2020-11-15 22:48 ` [PATCH 1/6] time: fix kernel-doc markup Thomas Gleixner
@ 2020-11-15 22:51 ` tip-bot2 for Alex Shi
6 siblings, 0 replies; 18+ messages in thread
From: tip-bot2 for Alex Shi @ 2020-11-15 22:51 UTC (permalink / raw)
To: linux-tip-commits; +Cc: Alex Shi, Thomas Gleixner, x86, linux-kernel
The following commit has been merged into the timers/core branch of tip:
Commit-ID: a0f5a65fa5faeef708d022698d5fcba290a35856
Gitweb: https://git.kernel.org/tip/a0f5a65fa5faeef708d022698d5fcba290a35856
Author: Alex Shi <alex.shi@linux.alibaba.com>
AuthorDate: Fri, 13 Nov 2020 15:24:30 +08:00
Committer: Thomas Gleixner <tglx@linutronix.de>
CommitterDate: Sun, 15 Nov 2020 23:47:23 +01:00
time: Add missing colons for parameter documentation of time64_to_tm()
Address these kernel-doc warnings:
kernel/time/timeconv.c:79: warning: Function parameter or member
'totalsecs' not described in 'time64_to_tm'
kernel/time/timeconv.c:79: warning: Function parameter or member
'offset' not described in 'time64_to_tm'
kernel/time/timeconv.c:79: warning: Function parameter or member
'result' not described in 'time64_to_tm'
The parameters are described but lack colons after the parameter name.
[ tglx: Massaged changelog ]
Signed-off-by: Alex Shi <alex.shi@linux.alibaba.com>
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Link: https://lore.kernel.org/r/1605252275-63652-1-git-send-email-alex.shi@linux.alibaba.com
---
kernel/time/timeconv.c | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/kernel/time/timeconv.c b/kernel/time/timeconv.c
index 589e0a5..62e3b46 100644
--- a/kernel/time/timeconv.c
+++ b/kernel/time/timeconv.c
@@ -70,10 +70,10 @@ static const unsigned short __mon_yday[2][13] = {
/**
* time64_to_tm - converts the calendar time to local broken-down time
*
- * @totalsecs the number of seconds elapsed since 00:00:00 on January 1, 1970,
+ * @totalsecs: the number of seconds elapsed since 00:00:00 on January 1, 1970,
* Coordinated Universal Time (UTC).
- * @offset offset seconds adding to totalsecs.
- * @result pointer to struct tm variable to receive broken-down time
+ * @offset: offset seconds adding to totalsecs.
+ * @result: pointer to struct tm variable to receive broken-down time
*/
void time64_to_tm(time64_t totalsecs, int offset, struct tm *result)
{
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [tip: timers/core] timekeeping: Remove static functions from kernel-doc markup
2020-11-13 7:24 ` [PATCH 4/6] timekeeping: remove static functions from kernel-doc markup Alex Shi
@ 2020-11-15 22:51 ` tip-bot2 for Alex Shi
0 siblings, 0 replies; 18+ messages in thread
From: tip-bot2 for Alex Shi @ 2020-11-15 22:51 UTC (permalink / raw)
To: linux-tip-commits; +Cc: Alex Shi, Thomas Gleixner, x86, linux-kernel
The following commit has been merged into the timers/core branch of tip:
Commit-ID: 199d280c884de44c3b0daeb77438db43f6db01a2
Gitweb: https://git.kernel.org/tip/199d280c884de44c3b0daeb77438db43f6db01a2
Author: Alex Shi <alex.shi@linux.alibaba.com>
AuthorDate: Fri, 13 Nov 2020 15:24:33 +08:00
Committer: Thomas Gleixner <tglx@linutronix.de>
CommitterDate: Sun, 15 Nov 2020 23:47:23 +01:00
timekeeping: Remove static functions from kernel-doc markup
Various static functions in the timekeeping code have function comments
which pretend to be kernel-doc, but are incomplete and trigger parser
warnings.
As these functions are local to the timekeeping core code there is no need
to expose them via kernel-doc.
Remove the double star kernel-doc marker and remove excess newlines.
[ tglx: Massaged changelog and removed excess newlines ]
Signed-off-by: Alex Shi <alex.shi@linux.alibaba.com>
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Link: https://lore.kernel.org/r/1605252275-63652-4-git-send-email-alex.shi@linux.alibaba.com
---
kernel/time/timekeeping.c | 12 +++++-------
1 file changed, 5 insertions(+), 7 deletions(-)
diff --git a/kernel/time/timekeeping.c b/kernel/time/timekeeping.c
index 6858a31..570fc50 100644
--- a/kernel/time/timekeeping.c
+++ b/kernel/time/timekeeping.c
@@ -1415,9 +1415,8 @@ void timekeeping_warp_clock(void)
}
}
-/**
+/*
* __timekeeping_set_tai_offset - Sets the TAI offset from UTC and monotonic
- *
*/
static void __timekeeping_set_tai_offset(struct timekeeper *tk, s32 tai_offset)
{
@@ -1425,7 +1424,7 @@ static void __timekeeping_set_tai_offset(struct timekeeper *tk, s32 tai_offset)
tk->offs_tai = ktime_add(tk->offs_real, ktime_set(tai_offset, 0));
}
-/**
+/*
* change_clocksource - Swaps clocksources if a new one is available
*
* Accumulates current time interval and initializes new clocksource
@@ -2023,13 +2022,12 @@ static void timekeeping_adjust(struct timekeeper *tk, s64 offset)
}
}
-/**
+/*
* accumulate_nsecs_to_secs - Accumulates nsecs into secs
*
* Helper function that accumulates the nsecs greater than a second
* from the xtime_nsec field to the xtime_secs field.
* It also calls into the NTP code to handle leapsecond processing.
- *
*/
static inline unsigned int accumulate_nsecs_to_secs(struct timekeeper *tk)
{
@@ -2071,7 +2069,7 @@ static inline unsigned int accumulate_nsecs_to_secs(struct timekeeper *tk)
return clock_set;
}
-/**
+/*
* logarithmic_accumulation - shifted accumulation of cycles
*
* This functions accumulates a shifted interval of cycles into
@@ -2314,7 +2312,7 @@ ktime_t ktime_get_update_offsets_now(unsigned int *cwsseq, ktime_t *offs_real,
return base;
}
-/**
+/*
* timekeeping_validate_timex - Ensures the timex is ok for use in do_adjtimex
*/
static int timekeeping_validate_timex(const struct __kernel_timex *txc)
^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: [PATCH 1/6] time: fix kernel-doc markup
2020-11-15 22:48 ` [PATCH 1/6] time: fix kernel-doc markup Thomas Gleixner
@ 2020-11-16 2:44 ` Alex Shi
0 siblings, 0 replies; 18+ messages in thread
From: Alex Shi @ 2020-11-16 2:44 UTC (permalink / raw)
To: Thomas Gleixner, john.stultz; +Cc: Stephen Boyd, linux-kernel
在 2020/11/16 上午6:48, Thomas Gleixner 写道:
> On Fri, Nov 13 2020 at 15:24, Alex Shi wrote:
>
>> The kernel-doc interface error cause some warning:
>
> I fixes the lot up and applied it. Please look at the changes I did and
> be more careful next time.
>
Hi Thomas,
Thanks a lot for all fix and kindly coaching! I have learned a lot here.
Thanks
Alex
^ permalink raw reply [flat|nested] 18+ messages in thread
end of thread, other threads:[~2020-11-16 2:46 UTC | newest]
Thread overview: 18+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-11-13 7:24 [PATCH 1/6] time: fix kernel-doc markup Alex Shi
2020-11-13 7:24 ` [PATCH 2/6] timekeeping: add missed kernel-doc marks for 'tkf' Alex Shi
2020-11-15 20:08 ` Thomas Gleixner
2020-11-15 22:51 ` [tip: timers/core] timekeeping: Add missing parameter documentation for update_fast_timekeeper() tip-bot2 for Alex Shi
2020-11-13 7:24 ` [PATCH 3/6] timekeeping: add kernel-doc markup for pvclock notifier Alex Shi
2020-11-15 22:28 ` Thomas Gleixner
2020-11-15 22:51 ` [tip: timers/core] timekeeping: Add missing parameter docs for pvclock_gtod_[un]register_notifier() tip-bot2 for Alex Shi
2020-11-13 7:24 ` [PATCH 4/6] timekeeping: remove static functions from kernel-doc markup Alex Shi
2020-11-15 22:51 ` [tip: timers/core] timekeeping: Remove " tip-bot2 for Alex Shi
2020-11-13 7:24 ` [PATCH 5/6] timekeeping: add ts/tk explaination for kernel-doc Alex Shi
2020-11-15 22:19 ` Thomas Gleixner
2020-11-15 22:51 ` [tip: timers/core] timekeeping: Address parameter documentation issues for various functions tip-bot2 for Alex Shi
2020-11-13 7:24 ` [PATCH 6/6] timekeeping: fix kernel-doc mark issue on read_persistent_clock64 Alex Shi
2020-11-15 22:15 ` Thomas Gleixner
2020-11-15 22:51 ` [tip: timers/core] timekeeping: Fix parameter docs of read_persistent_wall_and_boot_offset() tip-bot2 for Alex Shi
2020-11-15 22:48 ` [PATCH 1/6] time: fix kernel-doc markup Thomas Gleixner
2020-11-16 2:44 ` Alex Shi
2020-11-15 22:51 ` [tip: timers/core] time: Add missing colons for parameter documentation of time64_to_tm() tip-bot2 for Alex Shi
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).