Branch data Line data Source code
1 : : /*
2 : : * Copyright (c) 2016-2017 Wind River Systems, Inc.
3 : : *
4 : : * SPDX-License-Identifier: Apache-2.0
5 : : */
6 : :
7 : : #ifndef ZEPHYR_KERNEL_INCLUDE_KSCHED_H_
8 : : #define ZEPHYR_KERNEL_INCLUDE_KSCHED_H_
9 : :
10 : : #include <kernel_structs.h>
11 : : #include <kernel_internal.h>
12 : : #include <timeout_q.h>
13 : : #include <tracing/tracing.h>
14 : : #include <stdbool.h>
15 : :
16 : : BUILD_ASSERT(K_LOWEST_APPLICATION_THREAD_PRIO
17 : : >= K_HIGHEST_APPLICATION_THREAD_PRIO);
18 : :
19 : : #ifdef CONFIG_MULTITHREADING
20 : : #define Z_VALID_PRIO(prio, entry_point) \
21 : : (((prio) == K_IDLE_PRIO && z_is_idle_thread_entry(entry_point)) || \
22 : : ((K_LOWEST_APPLICATION_THREAD_PRIO \
23 : : >= K_HIGHEST_APPLICATION_THREAD_PRIO) \
24 : : && (prio) >= K_HIGHEST_APPLICATION_THREAD_PRIO \
25 : : && (prio) <= K_LOWEST_APPLICATION_THREAD_PRIO))
26 : :
27 : : #define Z_ASSERT_VALID_PRIO(prio, entry_point) do { \
28 : : __ASSERT(Z_VALID_PRIO((prio), (entry_point)), \
29 : : "invalid priority (%d); allowed range: %d to %d", \
30 : : (prio), \
31 : : K_LOWEST_APPLICATION_THREAD_PRIO, \
32 : : K_HIGHEST_APPLICATION_THREAD_PRIO); \
33 : : } while (false)
34 : : #else
35 : : #define Z_VALID_PRIO(prio, entry_point) ((prio) == -1)
36 : : #define Z_ASSERT_VALID_PRIO(prio, entry_point) __ASSERT((prio) == -1, "")
37 : : #endif
38 : :
39 : : void z_sched_init(void);
40 : : void z_move_thread_to_end_of_prio_q(struct k_thread *thread);
41 : : int z_is_thread_time_slicing(struct k_thread *thread);
42 : : void z_unpend_thread_no_timeout(struct k_thread *thread);
43 : : struct k_thread *z_unpend1_no_timeout(_wait_q_t *wait_q);
44 : : int z_pend_curr(struct k_spinlock *lock, k_spinlock_key_t key,
45 : : _wait_q_t *wait_q, k_timeout_t timeout);
46 : : int z_pend_curr_irqlock(uint32_t key, _wait_q_t *wait_q, k_timeout_t timeout);
47 : : void z_pend_thread(struct k_thread *thread, _wait_q_t *wait_q,
48 : : k_timeout_t timeout);
49 : : void z_reschedule(struct k_spinlock *lock, k_spinlock_key_t key);
50 : : void z_reschedule_irqlock(uint32_t key);
51 : : struct k_thread *z_unpend_first_thread(_wait_q_t *wait_q);
52 : : void z_unpend_thread(struct k_thread *thread);
53 : : int z_unpend_all(_wait_q_t *wait_q);
54 : : void z_thread_priority_set(struct k_thread *thread, int prio);
55 : : bool z_set_prio(struct k_thread *thread, int prio);
56 : : void *z_get_next_switch_handle(void *interrupted);
57 : : void idle(void *unused1, void *unused2, void *unused3);
58 : : void z_time_slice(int ticks);
59 : : void z_reset_time_slice(struct k_thread *curr);
60 : : void z_sched_abort(struct k_thread *thread);
61 : : void z_sched_ipi(void);
62 : : void z_sched_start(struct k_thread *thread);
63 : : void z_ready_thread(struct k_thread *thread);
64 : : void z_requeue_current(struct k_thread *curr);
65 : : struct k_thread *z_swap_next_thread(void);
66 : : void z_thread_abort(struct k_thread *thread);
67 : :
68 : : static inline void z_pend_curr_unlocked(_wait_q_t *wait_q, k_timeout_t timeout)
69 : : {
70 : : (void) z_pend_curr_irqlock(arch_irq_lock(), wait_q, timeout);
71 : : }
72 : :
73 : 1 : static inline void z_reschedule_unlocked(void)
74 : : {
75 : 1 : (void) z_reschedule_irqlock(arch_irq_lock());
76 : 1 : }
77 : :
78 : 1 : static inline bool z_is_idle_thread_entry(void *entry_point)
79 : : {
80 : 1 : return entry_point == idle;
81 : : }
82 : :
83 : 3 : static inline bool z_is_idle_thread_object(struct k_thread *thread)
84 : : {
85 : : #ifdef CONFIG_MULTITHREADING
86 : : #ifdef CONFIG_SMP
87 : : return thread->base.is_idle;
88 : : #else
89 : 3 : return thread == &z_idle_threads[0];
90 : : #endif
91 : : #else
92 : : return false;
93 : : #endif /* CONFIG_MULTITHREADING */
94 : : }
95 : :
96 : 0 : static inline bool z_is_thread_suspended(struct k_thread *thread)
97 : : {
98 : 0 : return (thread->base.thread_state & _THREAD_SUSPENDED) != 0U;
99 : : }
100 : :
101 : 0 : static inline bool z_is_thread_pending(struct k_thread *thread)
102 : : {
103 : 0 : return (thread->base.thread_state & _THREAD_PENDING) != 0U;
104 : : }
105 : :
106 : 5 : static inline bool z_is_thread_prevented_from_running(struct k_thread *thread)
107 : : {
108 : 5 : uint8_t state = thread->base.thread_state;
109 : :
110 : 5 : return (state & (_THREAD_PENDING | _THREAD_PRESTART | _THREAD_DEAD |
111 : 5 : _THREAD_DUMMY | _THREAD_SUSPENDED)) != 0U;
112 : :
113 : : }
114 : :
115 : 4 : static inline bool z_is_thread_timeout_active(struct k_thread *thread)
116 : : {
117 : 4 : return !z_is_inactive_timeout(&thread->base.timeout);
118 : : }
119 : :
120 : 2 : static inline bool z_is_thread_ready(struct k_thread *thread)
121 : : {
122 [ + - + - ]: 4 : return !((z_is_thread_prevented_from_running(thread)) != 0U ||
123 : 2 : z_is_thread_timeout_active(thread));
124 : : }
125 : :
126 : 1 : static inline bool z_has_thread_started(struct k_thread *thread)
127 : : {
128 : 1 : return (thread->base.thread_state & _THREAD_PRESTART) == 0U;
129 : : }
130 : :
131 : 3 : static inline bool z_is_thread_state_set(struct k_thread *thread, uint32_t state)
132 : : {
133 : 3 : return (thread->base.thread_state & state) != 0U;
134 : : }
135 : :
136 : 3 : static inline bool z_is_thread_queued(struct k_thread *thread)
137 : : {
138 : 3 : return z_is_thread_state_set(thread, _THREAD_QUEUED);
139 : : }
140 : :
141 : 0 : static inline void z_mark_thread_as_suspended(struct k_thread *thread)
142 : : {
143 : 0 : thread->base.thread_state |= _THREAD_SUSPENDED;
144 : :
145 : : SYS_PORT_TRACING_FUNC(k_thread, sched_suspend, thread);
146 : 0 : }
147 : :
148 : 0 : static inline void z_mark_thread_as_not_suspended(struct k_thread *thread)
149 : : {
150 : 0 : thread->base.thread_state &= ~_THREAD_SUSPENDED;
151 : :
152 : : SYS_PORT_TRACING_FUNC(k_thread, sched_resume, thread);
153 : 0 : }
154 : :
155 : 3 : static inline void z_mark_thread_as_started(struct k_thread *thread)
156 : : {
157 : 3 : thread->base.thread_state &= ~_THREAD_PRESTART;
158 : 3 : }
159 : :
160 : 0 : static inline void z_mark_thread_as_pending(struct k_thread *thread)
161 : : {
162 : 0 : thread->base.thread_state |= _THREAD_PENDING;
163 : 0 : }
164 : :
165 : 0 : static inline void z_mark_thread_as_not_pending(struct k_thread *thread)
166 : : {
167 : 0 : thread->base.thread_state &= ~_THREAD_PENDING;
168 : 0 : }
169 : :
170 : : static inline void z_set_thread_states(struct k_thread *thread, uint32_t states)
171 : : {
172 : : thread->base.thread_state |= states;
173 : : }
174 : :
175 : : static inline void z_reset_thread_states(struct k_thread *thread,
176 : : uint32_t states)
177 : : {
178 : : thread->base.thread_state &= ~states;
179 : : }
180 : :
181 : 0 : static inline bool z_is_under_prio_ceiling(int prio)
182 : : {
183 : 0 : return prio >= CONFIG_PRIORITY_CEILING;
184 : : }
185 : :
186 : 0 : static inline int z_get_new_prio_with_ceiling(int prio)
187 : : {
188 [ # # ]: 0 : return z_is_under_prio_ceiling(prio) ? prio : CONFIG_PRIORITY_CEILING;
189 : : }
190 : :
191 : : static inline bool z_is_prio1_higher_than_or_equal_to_prio2(int prio1, int prio2)
192 : : {
193 : : return prio1 <= prio2;
194 : : }
195 : :
196 : : static inline bool z_is_prio_higher_or_equal(int prio1, int prio2)
197 : : {
198 : : return z_is_prio1_higher_than_or_equal_to_prio2(prio1, prio2);
199 : : }
200 : :
201 : : static inline bool z_is_prio1_lower_than_or_equal_to_prio2(int prio1, int prio2)
202 : : {
203 : : return prio1 >= prio2;
204 : : }
205 : :
206 : 0 : static inline bool z_is_prio1_higher_than_prio2(int prio1, int prio2)
207 : : {
208 : 0 : return prio1 < prio2;
209 : : }
210 : :
211 : 0 : static inline bool z_is_prio_higher(int prio, int test_prio)
212 : : {
213 : 0 : return z_is_prio1_higher_than_prio2(prio, test_prio);
214 : : }
215 : :
216 : : static inline bool z_is_prio_lower_or_equal(int prio1, int prio2)
217 : : {
218 : : return z_is_prio1_lower_than_or_equal_to_prio2(prio1, prio2);
219 : : }
220 : :
221 : : int32_t z_sched_prio_cmp(struct k_thread *thread_1, struct k_thread *thread_2);
222 : :
223 : : static inline bool _is_valid_prio(int prio, void *entry_point)
224 : : {
225 : : if (prio == K_IDLE_PRIO && z_is_idle_thread_entry(entry_point)) {
226 : : return true;
227 : : }
228 : :
229 : : if (!z_is_prio_higher_or_equal(prio,
230 : : K_LOWEST_APPLICATION_THREAD_PRIO)) {
231 : : return false;
232 : : }
233 : :
234 : : if (!z_is_prio_lower_or_equal(prio,
235 : : K_HIGHEST_APPLICATION_THREAD_PRIO)) {
236 : : return false;
237 : : }
238 : :
239 : : return true;
240 : : }
241 : :
242 : : static inline void _ready_one_thread(_wait_q_t *wq)
243 : : {
244 : : struct k_thread *thread = z_unpend_first_thread(wq);
245 : :
246 : : if (thread != NULL) {
247 : : z_ready_thread(thread);
248 : : }
249 : : }
250 : :
251 : 2 : static inline void z_sched_lock(void)
252 : : {
253 [ - + ]: 2 : __ASSERT(!arch_is_in_isr(), "");
254 [ - + ]: 2 : __ASSERT(_current->base.sched_locked != 1U, "");
255 : :
256 : 2 : --_current->base.sched_locked;
257 : :
258 : 2 : compiler_barrier();
259 : 2 : }
260 : :
261 : : static ALWAYS_INLINE void z_sched_unlock_no_reschedule(void)
262 : : {
263 : : __ASSERT(!arch_is_in_isr(), "");
264 : : __ASSERT(_current->base.sched_locked != 0U, "");
265 : :
266 : : compiler_barrier();
267 : :
268 : : ++_current->base.sched_locked;
269 : : }
270 : :
271 : : static ALWAYS_INLINE bool z_is_thread_timeout_expired(struct k_thread *thread)
272 : : {
273 : : #ifdef CONFIG_SYS_CLOCK_EXISTS
274 : : return thread->base.timeout.dticks == _EXPIRED;
275 : : #else
276 : : return 0;
277 : : #endif
278 : : }
279 : :
280 : : /*
281 : : * APIs for working with the Zephyr kernel scheduler. Intended for use in
282 : : * management of IPC objects, either in the core kernel or other IPC
283 : : * implemented by OS compatibility layers, providing basic wait/wake operations
284 : : * with spinlocks used for synchronization.
285 : : *
286 : : * These APIs are public and will be treated as contract, even if the
287 : : * underlying scheduler implementation changes.
288 : : */
289 : :
290 : : /**
291 : : * Wake up a thread pending on the provided wait queue
292 : : *
293 : : * Given a wait_q, wake up the highest priority thread on the queue. If the
294 : : * queue was empty just return false.
295 : : *
296 : : * Otherwise, do the following, in order, holding sched_spinlock the entire
297 : : * time so that the thread state is guaranteed not to change:
298 : : * - Set the thread's swap return values to swap_retval and swap_data
299 : : * - un-pend and ready the thread, but do not invoke the scheduler.
300 : : *
301 : : * Repeated calls to this function until it returns false is a suitable
302 : : * way to wake all threads on the queue.
303 : : *
304 : : * It is up to the caller to implement locking such that the return value of
305 : : * this function (whether a thread was woken up or not) does not immediately
306 : : * become stale. Calls to wait and wake on the same wait_q object must have
307 : : * synchronization. Calling this without holding any spinlock is a sign that
308 : : * this API is not being used properly.
309 : : *
310 : : * @param wait_q Wait queue to wake up the highest prio thread
311 : : * @param swap_retval Swap return value for woken thread
312 : : * @param swap_data Data return value to supplement swap_retval. May be NULL.
313 : : * @retval true If a thread was woken up
314 : : * @retval false If the wait_q was empty
315 : : */
316 : : bool z_sched_wake(_wait_q_t *wait_q, int swap_retval, void *swap_data);
317 : :
318 : : /**
319 : : * Wake up all threads pending on the provided wait queue
320 : : *
321 : : * Convenience function to invoke z_sched_wake() on all threads in the queue
322 : : * until there are no more to wake up.
323 : : *
324 : : * @param wait_q Wait queue to wake up the highest prio thread
325 : : * @param swap_retval Swap return value for woken thread
326 : : * @param swap_data Data return value to supplement swap_retval. May be NULL.
327 : : * @retval true If any threads were woken up
328 : : * @retval false If the wait_q was empty
329 : : */
330 : : static inline bool z_sched_wake_all(_wait_q_t *wait_q, int swap_retval,
331 : : void *swap_data)
332 : : {
333 : : bool woken = false;
334 : :
335 : : while (z_sched_wake(wait_q, swap_retval, swap_data)) {
336 : : woken = true;
337 : : }
338 : :
339 : : /* True if we woke at least one thread up */
340 : : return woken;
341 : : }
342 : :
343 : : /**
344 : : * Atomically put the current thread to sleep on a wait queue, with timeout
345 : : *
346 : : * The thread will be added to the provided waitqueue. The lock, which should
347 : : * be held by the caller with the provided key, will be released once this is
348 : : * completely done and we have swapped out.
349 : : *
350 : : * The return value and data pointer is set by whoever woke us up via
351 : : * z_sched_wake.
352 : : *
353 : : * @param lock Address of spinlock to release when we swap out
354 : : * @param key Key to the provided spinlock when it was locked
355 : : * @param wait_q Wait queue to go to sleep on
356 : : * @param timeout Waiting period to be woken up, or K_FOREVER to wait
357 : : * indefinitely.
358 : : * @param data Storage location for data pointer set when thread was woken up.
359 : : * May be NULL if not used.
360 : : * @retval Return value set by whatever woke us up, or -EAGAIN if the timeout
361 : : * expired without being woken up.
362 : : */
363 : : int z_sched_wait(struct k_spinlock *lock, k_spinlock_key_t key,
364 : : _wait_q_t *wait_q, k_timeout_t timeout, void **data);
365 : :
366 : :
367 : : /** @brief Halt thread cycle usage accounting.
368 : : *
369 : : * Halts the accumulation of thread cycle usage and adds the current
370 : : * total to the thread's counter. Called on context switch.
371 : : *
372 : : * Note that this function is idempotent. The core kernel code calls
373 : : * it at the end of interrupt handlers (because that is where we have
374 : : * a portable hook) where we are context switching, which will include
375 : : * any cycles spent in the ISR in the per-thread accounting. But
376 : : * architecture code can also call it earlier out of interrupt entry
377 : : * to improve measurement fidelity.
378 : : *
379 : : * This function assumes local interrupts are masked (so that the
380 : : * current CPU pointer and current thread are safe to modify), but
381 : : * requires no other synchronizaton. Architecture layers don't need
382 : : * to do anything more.
383 : : */
384 : : void z_sched_usage_stop(void);
385 : :
386 : : void z_sched_usage_start(struct k_thread *thread);
387 : :
388 : : /**
389 : : * @brief Retrieves CPU cycle usage data for specified core
390 : : */
391 : : void z_sched_cpu_usage(uint8_t core_id, struct k_thread_runtime_stats *stats);
392 : :
393 : : /**
394 : : * @brief Retrieves thread cycle usage data for specified thread
395 : : */
396 : : void z_sched_thread_usage(struct k_thread *thread,
397 : : struct k_thread_runtime_stats *stats);
398 : :
399 : : static inline void z_sched_usage_switch(struct k_thread *thread)
400 : : {
401 : : ARG_UNUSED(thread);
402 : : #ifdef CONFIG_SCHED_THREAD_USAGE
403 : : z_sched_usage_stop();
404 : : z_sched_usage_start(thread);
405 : : #endif
406 : : }
407 : :
408 : : #endif /* ZEPHYR_KERNEL_INCLUDE_KSCHED_H_ */
|