doc(core): introduce the term "boot phase", add a diagram depicting the kernel lifecycle

Author: yvt

src/r3_core/doc/system_lifecycle.rs

@@ -0,0 +1,45 @@
+svgbobdoc::transform! { /**
+```svgbob,[system_lifecycle]
+
+                      Main thread
+                      .-----------------------.
+                      |                       |
+                      |           *           |
+                      |           |           |
+                      |           v           |
+  Boot phase          | Kernel initialization |
+                      |           |           |
+                      |           v           |
+                      |     Startup hooks     |
+                      |      "(user code)"    |
+                      |           |           |
+                      '-----------+-----------'
+                                  |
+  - - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - -
+                                  |
+                                  | For each hardware thread...
+                                  |
+                                  +<------------------------------.
+                                  |                               |
+                                  v                               |
+                      Determine the next thread                   |
+                             to execute                           |
+                                  |                               |
+                                  |                               |
+                                  v                               |
+           .--------------+--------------+--------------+--- ...  |
+           |              |         Int. |         Int. |         |
+    Task 1 |       Task 2 |    handler 1 |    handler 2 |         |
+     .-----+-----.  .-----+-----.  .-----+-----.  .-----+-----.   |
+     |     |     |  |     |     |  |     |     |  |     |     |   |
+     |     v     |  |     v     |  |     v     |  |     v     |   |
+     | User code |  | User code |  | User code |  | User code |   |
+     |     |     |  |     |     |  |     |     |  |     |     |   |
+     |     |     |  |     |     |  |     |     |  |     |     |   |
+     '-----+-----'  '-----+-----'  '-----+-----'  '-----+-----'   |
+           |              |              |              |         |
+           '--------------+--------------+--------------+---------'
+              The thread exiting, preempted, or blocked
+              or an interrupt taken
+```
+*/ }

src/r3_core/src/kernel/hook.rs

@@ -12,9 +12,11 @@ use crate::{
 /// There are no operations defined for startup hooks, so this type
 /// is only used for static configuration.
 ///
-/// Startup hooks execute during the boot process with [CPU Lock] active, after
-/// initializing kernel structures and before scheduling the first task.
+/// Startup hooks execute during [the boot phase][] with [CPU Lock][] active,
+/// after initializing kernel structures and before scheduling the first task.
+/// <!-- [ref:startup_hook_cpu_lock_active] -->
 ///
+/// [the boot phase]: crate#threads
 /// [CPU Lock]: crate#system-states
 ///
 /// <div class="admonition-follows"></div>

src/r3_core/src/lib.md

@@ -256,15 +256,17 @@ Like a lock guard of a mutex, CPU Lock can be thought of as something to be “o
 
 # Threads
 
-An **(execution) thread** is a sequence of instructions executed by a processor. There can be multiple threads existing at the same time and the kernel is responsible for deciding which thread to run at any point on a processor (this process is called scheduling). The location in a program where a thread starts execution is called the thread's **entry point function** for the thread. A thread exits when it returns from its entry point function¹ or calls [`exit_task`](crate::kernel::Kernel::exit_task) (valid only for tasks).
+An **(execution) thread** is a logical sequence of instructions executed by a processor. There can be multiple threads existing at the same time, and the kernel is responsible for deciding which thread to run at any point on a processor (this process is called scheduling)². The location in a program where a thread starts execution is called the thread's **entry point function** for the thread. A thread exits when it returns from its entry point function¹ or calls [`exit_task`](crate::kernel::Kernel::exit_task) (valid only for tasks).
 
- ¹ More precisely, a thread starts execution with a hypothetical function call to the entry point function, and it exits when it returns from this hypothetical function call.
+<small> ¹ More precisely, a thread starts execution with a hypothetical function call to the entry point function, and it exits when it returns from this hypothetical function call.</small>
+
+<small> ² The execution of code responsible for scheduling is not considered pertaining to any threads.</small>
 
 The properties of threads such as how and when they are created and whether they can block or not are specific to each thread type.
 
-The initial thread that starts up the kernel is called the **main thread**. This is where the initialization of kernel structures takes place. Additionally, an application can register one or more [**startup hooks**] to execute user code here. <!-- [tag:startup_hook_cpu_lock_active] --> Startup hooks execute with CPU Lock active and *should never deactivate CPU Lock*. The main thread exits when the kernel dispatches the first task.
+The initial thread that starts up the kernel is called the **main thread**. The part of the kernel's lifecycle where the main thread executes is called the kernel's **boot phase**, and this is where the initialization of kernel structures takes place. An application can register one or more [**startup hooks**] to execute user code here. <!-- [tag:startup_hook_cpu_lock_active] --> Startup hooks execute with CPU Lock active and *should never deactivate CPU Lock*. The main thread exits, i.e., the boot phase completes when the kernel dispatches the first task and starts multi-tasking. The following diagram depicts the kernel lifecycle during and after the boot phase.
 
-<!-- TODO: It's useful to introduce a term "the boot phase". -->
+<span class="center">![system_lifecycle]</span>
 
 [**startup hooks**]: crate::kernel::StartupHook
 

src/r3_core/src/lib.rs

@@ -57,6 +57,7 @@
 )]
 #![doc = include_str!("./lib.md")]
 #![doc = include_str!("./common.md")]
+#![doc = include!("../doc/system_lifecycle.rs")] // `![system_lifecycle]`
 #![doc = include!("../doc/trait_binding.rs")] // `![trait_binding]`
 #![doc = include!("../doc/static_cfg.rs")] // `![static_cfg]`
 #![cfg_attr(