LCOV - code coverage report
Current view: top level - kernel/include - ksched.h (source / functions) Hit Total Coverage
Test: coverage.info Lines: 31 55 56.4 %
Date: 2022-08-18 11:36:24 Functions: 11 21 52.4 %
Legend: Lines: hit not hit | Branches: + taken - not taken # not executed Branches: 4 10 40.0 %

           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_ */

Generated by: LCOV version 1.14