]>
Commit | Line | Data |
---|---|---|
b7ca0ba0 SL |
1 | From 1d7953a6a1ee7206baf560ff83ab36a839ac7d49 Mon Sep 17 00:00:00 2001 |
2 | From: Sasha Levin <sashal@kernel.org> | |
3 | Date: Wed, 23 Nov 2022 21:18:40 +0100 | |
4 | Subject: timers: Update kernel-doc for various functions | |
5 | ||
6 | From: Thomas Gleixner <tglx@linutronix.de> | |
7 | ||
8 | [ Upstream commit 14f043f1340bf30bc60af127bff39f55889fef26 ] | |
9 | ||
10 | The kernel-doc of timer related functions is partially uncomprehensible | |
11 | word salad. Rewrite it to make it useful. | |
12 | ||
13 | Signed-off-by: Thomas Gleixner <tglx@linutronix.de> | |
14 | Tested-by: Guenter Roeck <linux@roeck-us.net> | |
15 | Reviewed-by: Jacob Keller <jacob.e.keller@intel.com> | |
16 | Reviewed-by: Anna-Maria Behnsen <anna-maria@linutronix.de> | |
17 | Link: https://lore.kernel.org/r/20221123201624.828703870@linutronix.de | |
18 | Stable-dep-of: 0f7352557a35 ("wifi: brcmfmac: Fix use-after-free bug in brcmf_cfg80211_detach") | |
19 | Signed-off-by: Sasha Levin <sashal@kernel.org> | |
20 | --- | |
21 | kernel/time/timer.c | 148 +++++++++++++++++++++++++++----------------- | |
22 | 1 file changed, 90 insertions(+), 58 deletions(-) | |
23 | ||
24 | diff --git a/kernel/time/timer.c b/kernel/time/timer.c | |
25 | index e87e638c31bdf..3157a6434a615 100644 | |
26 | --- a/kernel/time/timer.c | |
27 | +++ b/kernel/time/timer.c | |
28 | @@ -1068,14 +1068,16 @@ __mod_timer(struct timer_list *timer, unsigned long expires, unsigned int option | |
29 | } | |
30 | ||
31 | /** | |
32 | - * mod_timer_pending - modify a pending timer's timeout | |
33 | - * @timer: the pending timer to be modified | |
34 | - * @expires: new timeout in jiffies | |
35 | + * mod_timer_pending - Modify a pending timer's timeout | |
36 | + * @timer: The pending timer to be modified | |
37 | + * @expires: New absolute timeout in jiffies | |
38 | * | |
39 | - * mod_timer_pending() is the same for pending timers as mod_timer(), | |
40 | - * but will not re-activate and modify already deleted timers. | |
41 | + * mod_timer_pending() is the same for pending timers as mod_timer(), but | |
42 | + * will not activate inactive timers. | |
43 | * | |
44 | - * It is useful for unserialized use of timers. | |
45 | + * Return: | |
46 | + * * %0 - The timer was inactive and not modified | |
47 | + * * %1 - The timer was active and requeued to expire at @expires | |
48 | */ | |
49 | int mod_timer_pending(struct timer_list *timer, unsigned long expires) | |
50 | { | |
51 | @@ -1084,24 +1086,27 @@ int mod_timer_pending(struct timer_list *timer, unsigned long expires) | |
52 | EXPORT_SYMBOL(mod_timer_pending); | |
53 | ||
54 | /** | |
55 | - * mod_timer - modify a timer's timeout | |
56 | - * @timer: the timer to be modified | |
57 | - * @expires: new timeout in jiffies | |
58 | - * | |
59 | - * mod_timer() is a more efficient way to update the expire field of an | |
60 | - * active timer (if the timer is inactive it will be activated) | |
61 | + * mod_timer - Modify a timer's timeout | |
62 | + * @timer: The timer to be modified | |
63 | + * @expires: New absolute timeout in jiffies | |
64 | * | |
65 | * mod_timer(timer, expires) is equivalent to: | |
66 | * | |
67 | * del_timer(timer); timer->expires = expires; add_timer(timer); | |
68 | * | |
69 | + * mod_timer() is more efficient than the above open coded sequence. In | |
70 | + * case that the timer is inactive, the del_timer() part is a NOP. The | |
71 | + * timer is in any case activated with the new expiry time @expires. | |
72 | + * | |
73 | * Note that if there are multiple unserialized concurrent users of the | |
74 | * same timer, then mod_timer() is the only safe way to modify the timeout, | |
75 | * since add_timer() cannot modify an already running timer. | |
76 | * | |
77 | - * The function returns whether it has modified a pending timer or not. | |
78 | - * (ie. mod_timer() of an inactive timer returns 0, mod_timer() of an | |
79 | - * active timer returns 1.) | |
80 | + * Return: | |
81 | + * * %0 - The timer was inactive and started | |
82 | + * * %1 - The timer was active and requeued to expire at @expires or | |
83 | + * the timer was active and not modified because @expires did | |
84 | + * not change the effective expiry time | |
85 | */ | |
86 | int mod_timer(struct timer_list *timer, unsigned long expires) | |
87 | { | |
88 | @@ -1112,11 +1117,18 @@ EXPORT_SYMBOL(mod_timer); | |
89 | /** | |
90 | * timer_reduce - Modify a timer's timeout if it would reduce the timeout | |
91 | * @timer: The timer to be modified | |
92 | - * @expires: New timeout in jiffies | |
93 | + * @expires: New absolute timeout in jiffies | |
94 | * | |
95 | * timer_reduce() is very similar to mod_timer(), except that it will only | |
96 | - * modify a running timer if that would reduce the expiration time (it will | |
97 | - * start a timer that isn't running). | |
98 | + * modify an enqueued timer if that would reduce the expiration time. If | |
99 | + * @timer is not enqueued it starts the timer. | |
100 | + * | |
101 | + * Return: | |
102 | + * * %0 - The timer was inactive and started | |
103 | + * * %1 - The timer was active and requeued to expire at @expires or | |
104 | + * the timer was active and not modified because @expires | |
105 | + * did not change the effective expiry time such that the | |
106 | + * timer would expire earlier than already scheduled | |
107 | */ | |
108 | int timer_reduce(struct timer_list *timer, unsigned long expires) | |
109 | { | |
110 | @@ -1125,18 +1137,21 @@ int timer_reduce(struct timer_list *timer, unsigned long expires) | |
111 | EXPORT_SYMBOL(timer_reduce); | |
112 | ||
113 | /** | |
114 | - * add_timer - start a timer | |
115 | - * @timer: the timer to be added | |
116 | + * add_timer - Start a timer | |
117 | + * @timer: The timer to be started | |
118 | * | |
119 | - * The kernel will do a ->function(@timer) callback from the | |
120 | - * timer interrupt at the ->expires point in the future. The | |
121 | - * current time is 'jiffies'. | |
122 | + * Start @timer to expire at @timer->expires in the future. @timer->expires | |
123 | + * is the absolute expiry time measured in 'jiffies'. When the timer expires | |
124 | + * timer->function(timer) will be invoked from soft interrupt context. | |
125 | * | |
126 | - * The timer's ->expires, ->function fields must be set prior calling this | |
127 | - * function. | |
128 | + * The @timer->expires and @timer->function fields must be set prior | |
129 | + * to calling this function. | |
130 | + * | |
131 | + * If @timer->expires is already in the past @timer will be queued to | |
132 | + * expire at the next timer tick. | |
133 | * | |
134 | - * Timers with an ->expires field in the past will be executed in the next | |
135 | - * timer tick. | |
136 | + * This can only operate on an inactive timer. Attempts to invoke this on | |
137 | + * an active timer are rejected with a warning. | |
138 | */ | |
139 | void add_timer(struct timer_list *timer) | |
140 | { | |
141 | @@ -1146,11 +1161,13 @@ void add_timer(struct timer_list *timer) | |
142 | EXPORT_SYMBOL(add_timer); | |
143 | ||
144 | /** | |
145 | - * add_timer_on - start a timer on a particular CPU | |
146 | - * @timer: the timer to be added | |
147 | - * @cpu: the CPU to start it on | |
148 | + * add_timer_on - Start a timer on a particular CPU | |
149 | + * @timer: The timer to be started | |
150 | + * @cpu: The CPU to start it on | |
151 | + * | |
152 | + * Same as add_timer() except that it starts the timer on the given CPU. | |
153 | * | |
154 | - * This is not very scalable on SMP. Double adds are not possible. | |
155 | + * See add_timer() for further details. | |
156 | */ | |
157 | void add_timer_on(struct timer_list *timer, int cpu) | |
158 | { | |
159 | @@ -1185,15 +1202,18 @@ void add_timer_on(struct timer_list *timer, int cpu) | |
160 | EXPORT_SYMBOL_GPL(add_timer_on); | |
161 | ||
162 | /** | |
163 | - * del_timer - deactivate a timer. | |
164 | - * @timer: the timer to be deactivated | |
165 | - * | |
166 | - * del_timer() deactivates a timer - this works on both active and inactive | |
167 | - * timers. | |
168 | - * | |
169 | - * The function returns whether it has deactivated a pending timer or not. | |
170 | - * (ie. del_timer() of an inactive timer returns 0, del_timer() of an | |
171 | - * active timer returns 1.) | |
172 | + * del_timer - Deactivate a timer. | |
173 | + * @timer: The timer to be deactivated | |
174 | + * | |
175 | + * The function only deactivates a pending timer, but contrary to | |
176 | + * del_timer_sync() it does not take into account whether the timer's | |
177 | + * callback function is concurrently executed on a different CPU or not. | |
178 | + * It neither prevents rearming of the timer. If @timer can be rearmed | |
179 | + * concurrently then the return value of this function is meaningless. | |
180 | + * | |
181 | + * Return: | |
182 | + * * %0 - The timer was not pending | |
183 | + * * %1 - The timer was pending and deactivated | |
184 | */ | |
185 | int del_timer(struct timer_list *timer) | |
186 | { | |
187 | @@ -1215,10 +1235,19 @@ EXPORT_SYMBOL(del_timer); | |
188 | ||
189 | /** | |
190 | * try_to_del_timer_sync - Try to deactivate a timer | |
191 | - * @timer: timer to delete | |
192 | + * @timer: Timer to deactivate | |
193 | + * | |
194 | + * This function tries to deactivate a timer. On success the timer is not | |
195 | + * queued and the timer callback function is not running on any CPU. | |
196 | * | |
197 | - * This function tries to deactivate a timer. Upon successful (ret >= 0) | |
198 | - * exit the timer is not queued and the handler is not running on any CPU. | |
199 | + * This function does not guarantee that the timer cannot be rearmed right | |
200 | + * after dropping the base lock. That needs to be prevented by the calling | |
201 | + * code if necessary. | |
202 | + * | |
203 | + * Return: | |
204 | + * * %0 - The timer was not pending | |
205 | + * * %1 - The timer was pending and deactivated | |
206 | + * * %-1 - The timer callback function is running on a different CPU | |
207 | */ | |
208 | int try_to_del_timer_sync(struct timer_list *timer) | |
209 | { | |
210 | @@ -1314,23 +1343,19 @@ static inline void del_timer_wait_running(struct timer_list *timer) { } | |
211 | ||
212 | #if defined(CONFIG_SMP) || defined(CONFIG_PREEMPT_RT) | |
213 | /** | |
214 | - * del_timer_sync - deactivate a timer and wait for the handler to finish. | |
215 | - * @timer: the timer to be deactivated | |
216 | - * | |
217 | - * This function only differs from del_timer() on SMP: besides deactivating | |
218 | - * the timer it also makes sure the handler has finished executing on other | |
219 | - * CPUs. | |
220 | + * del_timer_sync - Deactivate a timer and wait for the handler to finish. | |
221 | + * @timer: The timer to be deactivated | |
222 | * | |
223 | * Synchronization rules: Callers must prevent restarting of the timer, | |
224 | * otherwise this function is meaningless. It must not be called from | |
225 | * interrupt contexts unless the timer is an irqsafe one. The caller must | |
226 | - * not hold locks which would prevent completion of the timer's | |
227 | - * handler. The timer's handler must not call add_timer_on(). Upon exit the | |
228 | - * timer is not queued and the handler is not running on any CPU. | |
229 | + * not hold locks which would prevent completion of the timer's callback | |
230 | + * function. The timer's handler must not call add_timer_on(). Upon exit | |
231 | + * the timer is not queued and the handler is not running on any CPU. | |
232 | * | |
233 | - * Note: For !irqsafe timers, you must not hold locks that are held in | |
234 | - * interrupt context while calling this function. Even if the lock has | |
235 | - * nothing to do with the timer in question. Here's why:: | |
236 | + * For !irqsafe timers, the caller must not hold locks that are held in | |
237 | + * interrupt context. Even if the lock has nothing to do with the timer in | |
238 | + * question. Here's why:: | |
239 | * | |
240 | * CPU0 CPU1 | |
241 | * ---- ---- | |
242 | @@ -1344,10 +1369,17 @@ static inline void del_timer_wait_running(struct timer_list *timer) { } | |
243 | * while (base->running_timer == mytimer); | |
244 | * | |
245 | * Now del_timer_sync() will never return and never release somelock. | |
246 | - * The interrupt on the other CPU is waiting to grab somelock but | |
247 | - * it has interrupted the softirq that CPU0 is waiting to finish. | |
248 | + * The interrupt on the other CPU is waiting to grab somelock but it has | |
249 | + * interrupted the softirq that CPU0 is waiting to finish. | |
250 | + * | |
251 | + * This function cannot guarantee that the timer is not rearmed again by | |
252 | + * some concurrent or preempting code, right after it dropped the base | |
253 | + * lock. If there is the possibility of a concurrent rearm then the return | |
254 | + * value of the function is meaningless. | |
255 | * | |
256 | - * The function returns whether it has deactivated a pending timer or not. | |
257 | + * Return: | |
258 | + * * %0 - The timer was not pending | |
259 | + * * %1 - The timer was pending and deactivated | |
260 | */ | |
261 | int del_timer_sync(struct timer_list *timer) | |
262 | { | |
263 | -- | |
264 | 2.43.0 | |
265 |