kernel/
scheduler.rs

1// Licensed under the Apache License, Version 2.0 or the MIT License.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3// Copyright Tock Contributors 2022.
4
5//! Interface for Tock kernel schedulers.
6
7use crate::deferred_call::DeferredCall;
8use crate::platform::chip::Chip;
9use crate::process::ProcessId;
10use crate::process::StoppedExecutingReason;
11
12use core::num::NonZeroU32;
13
14/// Trait which any scheduler must implement.
15pub trait Scheduler<C: Chip> {
16    /// Decide which process to run next.
17    ///
18    /// The scheduler must decide whether to run a process, and if so, which
19    /// one. If the scheduler chooses not to run a process, it can request that
20    /// the chip enter sleep mode.
21    ///
22    /// If the scheduler selects a process to run it must provide its `ProcessId`
23    /// and an optional timeslice length in microseconds to provide to that
24    /// process. If the timeslice is `None`, the process will be run
25    /// cooperatively (i.e. without preemption). Otherwise the process will run
26    /// with a timeslice set to the specified length.
27    fn next(&self) -> SchedulingDecision;
28
29    /// Inform the scheduler of why the last process stopped executing, and how
30    /// long it executed for. Notably, `execution_time_us` will be `None`
31    /// if the the scheduler requested this process be run cooperatively.
32    fn result(&self, result: StoppedExecutingReason, execution_time_us: Option<u32>);
33
34    /// Tell the scheduler to execute kernel work such as interrupt bottom
35    /// halves and dynamic deferred calls. Most schedulers will use this default
36    /// implementation, but schedulers which at times wish to defer interrupt
37    /// handling will reimplement it.
38    ///
39    /// Providing this interface allows schedulers to fully manage how the main
40    /// kernel loop executes. For example, a more advanced scheduler that
41    /// attempts to help processes meet their deadlines may need to defer bottom
42    /// half interrupt handling or to selectively service certain interrupts.
43    /// Or, a power aware scheduler may want to selectively choose what work to
44    /// complete at any time to meet power requirements.
45    ///
46    /// Custom implementations of this function must be very careful, however,
47    /// as this function is called in the core kernel loop.
48    unsafe fn execute_kernel_work(&self, chip: &C) {
49        chip.service_pending_interrupts();
50        while DeferredCall::has_tasks() && !chip.has_pending_interrupts() {
51            DeferredCall::service_next_pending();
52        }
53    }
54
55    /// Ask the scheduler whether to take a break from executing userspace
56    /// processes to handle kernel tasks. Most schedulers will use this default
57    /// implementation, which always prioritizes kernel work, but schedulers
58    /// that wish to defer interrupt handling may reimplement it.
59    fn do_kernel_work_now(&self, chip: &C) -> bool {
60        chip.has_pending_interrupts() || DeferredCall::has_tasks()
61    }
62
63    /// Ask the scheduler whether to continue trying to execute a process.
64    ///
65    /// Once a process is scheduled the kernel will try to execute it until it
66    /// has no more work to do or exhausts its timeslice. The kernel will call
67    /// this function before every loop to check with the scheduler if it wants
68    /// to continue trying to execute this process.
69    ///
70    /// Most schedulers will use this default implementation, which causes the
71    /// `do_process()` loop to return if there are interrupts or deferred calls
72    /// that need to be serviced. However, schedulers which wish to defer
73    /// interrupt handling may change this, or priority schedulers which wish to
74    /// check if the execution of the current process has caused a higher
75    /// priority process to become ready (such as in the case of IPC). If this
76    /// returns `false`, then `do_process` will exit with a `KernelPreemption`.
77    ///
78    /// `id` is the identifier of the currently active process.
79    fn continue_process(&self, _id: ProcessId, chip: &C) -> bool {
80        !(chip.has_pending_interrupts() || DeferredCall::has_tasks())
81    }
82}
83
84/// Enum representing the actions the scheduler can request in each call to
85/// `scheduler.next()`.
86#[derive(Copy, Clone)]
87pub enum SchedulingDecision {
88    /// Tell the kernel to run the specified process with the passed timeslice.
89    /// If `None` is passed as a timeslice, the process will be run
90    /// cooperatively.
91    RunProcess((ProcessId, Option<NonZeroU32>)),
92
93    /// Tell the kernel to go to sleep. Notably, if the scheduler asks the
94    /// kernel to sleep when kernel tasks are ready, the kernel will not sleep,
95    /// and will instead restart the main loop and call `next()` again.
96    TrySleep,
97}
kernel/scheduler.rs

kernel/
scheduler.rs
