kernel/process_loading.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//! Helper functions and machines for loading process binaries into in-memory
6//! Tock processes.
7//!
8//! Process loaders are responsible for parsing the binary formats of Tock
9//! processes, checking whether they are allowed to be loaded, and if so
10//! initializing a process structure to run it.
11//!
12//! This module provides multiple process loader options depending on which
13//! features a particular board requires.
14
15use core::cell::Cell;
16use core::fmt;
17
18use crate::capabilities::ProcessManagementCapability;
19use crate::config;
20use crate::debug;
21use crate::deferred_call::{DeferredCall, DeferredCallClient};
22use crate::kernel::Kernel;
23use crate::platform::chip::Chip;
24use crate::process::{Process, ShortId};
25use crate::process_binary::{ProcessBinary, ProcessBinaryError};
26use crate::process_checker::AcceptedCredential;
27use crate::process_checker::{AppIdPolicy, ProcessCheckError, ProcessCheckerMachine};
28use crate::process_policies::ProcessFaultPolicy;
29use crate::process_policies::ProcessStandardStoragePermissionsPolicy;
30use crate::process_standard::ProcessStandard;
31use crate::process_standard::{ProcessStandardDebug, ProcessStandardDebugFull};
32use crate::utilities::cells::{MapCell, OptionalCell};
33
34/// Errors that can occur when trying to load and create processes.
35pub enum ProcessLoadError {
36 /// Not enough memory to meet the amount requested by a process. Modify the
37 /// process to request less memory, flash fewer processes, or increase the
38 /// size of the region your board reserves for process memory.
39 NotEnoughMemory,
40
41 /// A process was loaded with a length in flash that the MPU does not
42 /// support. The fix is probably to correct the process size, but this could
43 /// also be caused by a bad MPU implementation.
44 MpuInvalidFlashLength,
45
46 /// The MPU configuration failed for some other, unspecified reason. This
47 /// could be of an internal resource exhaustion, or a mismatch between the
48 /// (current) MPU constraints and process requirements.
49 MpuConfigurationError,
50
51 /// A process specified a fixed memory address that it needs its memory
52 /// range to start at, and the kernel did not or could not give the process
53 /// a memory region starting at that address.
54 MemoryAddressMismatch {
55 actual_address: u32,
56 expected_address: u32,
57 },
58
59 /// There is nowhere in the `PROCESSES` array to store this process.
60 NoProcessSlot,
61
62 /// Process loading failed because parsing the binary failed.
63 BinaryError(ProcessBinaryError),
64
65 /// Process loading failed because checking the process failed.
66 CheckError(ProcessCheckError),
67
68 /// Process loading error due (likely) to a bug in the kernel. If you get
69 /// this error please open a bug report.
70 InternalError,
71}
72
73impl fmt::Debug for ProcessLoadError {
74 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
75 match self {
76 ProcessLoadError::NotEnoughMemory => {
77 write!(f, "Not able to provide RAM requested by app")
78 }
79
80 ProcessLoadError::MpuInvalidFlashLength => {
81 write!(f, "App flash length not supported by MPU")
82 }
83
84 ProcessLoadError::MpuConfigurationError => {
85 write!(f, "Configuring the MPU failed")
86 }
87
88 ProcessLoadError::MemoryAddressMismatch {
89 actual_address,
90 expected_address,
91 } => write!(
92 f,
93 "App memory does not match requested address Actual:{:#x}, Expected:{:#x}",
94 actual_address, expected_address
95 ),
96
97 ProcessLoadError::NoProcessSlot => {
98 write!(f, "Nowhere to store the loaded process")
99 }
100
101 ProcessLoadError::BinaryError(binary_error) => {
102 writeln!(f, "Error parsing process binary")?;
103 write!(f, "{:?}", binary_error)
104 }
105
106 ProcessLoadError::CheckError(check_error) => {
107 writeln!(f, "Error checking process")?;
108 write!(f, "{:?}", check_error)
109 }
110
111 ProcessLoadError::InternalError => write!(f, "Error in kernel. Likely a bug."),
112 }
113 }
114}
115
116////////////////////////////////////////////////////////////////////////////////
117// SYNCHRONOUS PROCESS LOADING
118////////////////////////////////////////////////////////////////////////////////
119
120/// Load processes into runnable process structures.
121///
122/// Load processes (stored as TBF objects in flash) into runnable process
123/// structures stored in the `procs` array and mark all successfully loaded
124/// processes as runnable. This method does not check the cryptographic
125/// credentials of TBF objects. Platforms for which code size is tight and do
126/// not need to check TBF credentials can call this method because it results in
127/// a smaller kernel, as it does not invoke the credential checking state
128/// machine.
129///
130/// This function is made `pub` so that board files can use it, but loading
131/// processes from slices of flash an memory is fundamentally unsafe. Therefore,
132/// we require the `ProcessManagementCapability` to call this function.
133// Mark inline always to reduce code size. Since this is only called in one
134// place (a board's main.rs), by inlining the load_*processes() functions, the
135// compiler can elide many checks which reduces code size appreciably. Note,
136// however, these functions require a rather large stack frame, which may be an
137// issue for boards small kernel stacks.
138#[inline(always)]
139pub fn load_processes<C: Chip>(
140 kernel: &'static Kernel,
141 chip: &'static C,
142 app_flash: &'static [u8],
143 app_memory: &'static mut [u8],
144 fault_policy: &'static dyn ProcessFaultPolicy,
145 _capability_management: &dyn ProcessManagementCapability,
146) -> Result<(), ProcessLoadError> {
147 load_processes_from_flash::<C, ProcessStandardDebugFull>(
148 kernel,
149 chip,
150 app_flash,
151 app_memory,
152 fault_policy,
153 )?;
154
155 if config::CONFIG.debug_process_credentials {
156 debug!("Checking: no checking, load and run all processes");
157 for proc in kernel.get_process_iter() {
158 debug!("Running {}", proc.get_process_name());
159 }
160 }
161 Ok(())
162}
163
164/// Helper function to load processes from flash into an array of active
165/// processes. This is the default template for loading processes, but a board
166/// is able to create its own `load_processes()` function and use that instead.
167///
168/// Processes are found in flash starting from the given address and iterating
169/// through Tock Binary Format (TBF) headers. Processes are given memory out of
170/// the `app_memory` buffer until either the memory is exhausted or the
171/// allocated number of processes are created. This buffer is a non-static slice,
172/// ensuring that this code cannot hold onto the slice past the end of this function
173/// (instead, processes store a pointer and length), which necessary for later
174/// creation of `ProcessBuffer`s in this memory region to be sound.
175/// A reference to each process is stored in the provided `procs` array.
176/// How process faults are handled by the
177/// kernel must be provided and is assigned to every created process.
178///
179/// Returns `Ok(())` if process discovery went as expected. Returns a
180/// `ProcessLoadError` if something goes wrong during TBF parsing or process
181/// creation.
182#[inline(always)]
183fn load_processes_from_flash<C: Chip, D: ProcessStandardDebug + 'static>(
184 kernel: &'static Kernel,
185 chip: &'static C,
186 app_flash: &'static [u8],
187 app_memory: &'static mut [u8],
188 fault_policy: &'static dyn ProcessFaultPolicy,
189) -> Result<(), ProcessLoadError> {
190 if config::CONFIG.debug_load_processes {
191 debug!(
192 "Loading processes from flash={:#010X}-{:#010X} into sram={:#010X}-{:#010X}",
193 app_flash.as_ptr() as usize,
194 app_flash.as_ptr() as usize + app_flash.len() - 1,
195 app_memory.as_ptr() as usize,
196 app_memory.as_ptr() as usize + app_memory.len() - 1
197 );
198 }
199
200 let mut remaining_flash = app_flash;
201 let mut remaining_memory = app_memory;
202
203 loop {
204 match kernel.next_available_process_slot() {
205 Ok((index, slot)) => {
206 let load_binary_result = discover_process_binary(remaining_flash);
207
208 match load_binary_result {
209 Ok((new_flash, process_binary)) => {
210 remaining_flash = new_flash;
211
212 let load_result = load_process::<C, D>(
213 kernel,
214 chip,
215 process_binary,
216 remaining_memory,
217 ShortId::LocallyUnique,
218 index,
219 fault_policy,
220 &(),
221 );
222 match load_result {
223 Ok((new_mem, proc)) => {
224 remaining_memory = new_mem;
225 match proc {
226 Some(p) => {
227 if config::CONFIG.debug_load_processes {
228 debug!("Loaded process {}", p.get_process_name())
229 }
230 slot.set(p);
231 }
232 None => {
233 if config::CONFIG.debug_load_processes {
234 debug!("No process loaded.");
235 }
236 }
237 }
238 }
239 Err((new_mem, err)) => {
240 remaining_memory = new_mem;
241 if config::CONFIG.debug_load_processes {
242 debug!("Processes load error: {:?}.", err);
243 }
244 }
245 }
246 }
247 Err((new_flash, err)) => {
248 remaining_flash = new_flash;
249 match err {
250 ProcessBinaryError::NotEnoughFlash
251 | ProcessBinaryError::TbfHeaderNotFound => {
252 if config::CONFIG.debug_load_processes {
253 debug!("No more processes to load: {:?}.", err);
254 }
255 // No more processes to load.
256 break;
257 }
258
259 ProcessBinaryError::TbfHeaderParseFailure(_)
260 | ProcessBinaryError::IncompatibleKernelVersion { .. }
261 | ProcessBinaryError::IncorrectFlashAddress { .. }
262 | ProcessBinaryError::NotEnabledProcess
263 | ProcessBinaryError::Padding => {
264 if config::CONFIG.debug_load_processes {
265 debug!("Unable to use process binary: {:?}.", err);
266 }
267
268 // Skip this binary and move to the next one.
269 continue;
270 }
271 }
272 }
273 }
274 }
275 Err(()) => {
276 // No slot available.
277 if config::CONFIG.debug_load_processes {
278 debug!("No more process slots to load processes into.");
279 }
280 break;
281 }
282 }
283 }
284 Ok(())
285}
286
287////////////////////////////////////////////////////////////////////////////////
288// HELPER FUNCTIONS
289////////////////////////////////////////////////////////////////////////////////
290
291/// Find a process binary stored at the beginning of `flash` and create a
292/// `ProcessBinary` object if the process is viable to run on this kernel.
293fn discover_process_binary(
294 flash: &'static [u8],
295) -> Result<(&'static [u8], ProcessBinary), (&'static [u8], ProcessBinaryError)> {
296 if config::CONFIG.debug_load_processes {
297 debug!(
298 "Looking for process binary in flash={:#010X}-{:#010X}",
299 flash.as_ptr() as usize,
300 flash.as_ptr() as usize + flash.len() - 1
301 );
302 }
303
304 // If this fails, not enough remaining flash to check for an app.
305 let test_header_slice = flash
306 .get(0..8)
307 .ok_or((flash, ProcessBinaryError::NotEnoughFlash))?;
308
309 // Pass the first eight bytes to tbfheader to parse out the length of
310 // the tbf header and app. We then use those values to see if we have
311 // enough flash remaining to parse the remainder of the header.
312 //
313 // Start by converting [u8] to [u8; 8].
314 let header = test_header_slice
315 .try_into()
316 .or(Err((flash, ProcessBinaryError::NotEnoughFlash)))?;
317
318 let (version, header_length, app_length) =
319 match tock_tbf::parse::parse_tbf_header_lengths(header) {
320 Ok((v, hl, el)) => (v, hl, el),
321 Err(tock_tbf::types::InitialTbfParseError::InvalidHeader(app_length)) => {
322 // If we could not parse the header, then we want to skip over
323 // this app and look for the next one.
324 (0, 0, app_length)
325 }
326 Err(tock_tbf::types::InitialTbfParseError::UnableToParse) => {
327 // Since Tock apps use a linked list, it is very possible the
328 // header we started to parse is intentionally invalid to signal
329 // the end of apps. This is ok and just means we have finished
330 // loading apps.
331 return Err((flash, ProcessBinaryError::TbfHeaderNotFound));
332 }
333 };
334
335 // Now we can get a slice which only encompasses the length of flash
336 // described by this tbf header. We will either parse this as an actual
337 // app, or skip over this region.
338 let app_flash = flash
339 .get(0..app_length as usize)
340 .ok_or((flash, ProcessBinaryError::NotEnoughFlash))?;
341
342 // Advance the flash slice for process discovery beyond this last entry.
343 // This will be the start of where we look for a new process since Tock
344 // processes are allocated back-to-back in flash.
345 let remaining_flash = flash
346 .get(app_flash.len()..)
347 .ok_or((flash, ProcessBinaryError::NotEnoughFlash))?;
348
349 let pb = ProcessBinary::create(app_flash, header_length as usize, version, true)
350 .map_err(|e| (remaining_flash, e))?;
351
352 Ok((remaining_flash, pb))
353}
354
355/// Load a process stored as a TBF process binary with `app_memory` as the RAM
356/// pool that its RAM should be allocated from. Returns `Ok` if the process
357/// object was created, `Err` with a relevant error if the process object could
358/// not be created.
359fn load_process<C: Chip, D: ProcessStandardDebug>(
360 kernel: &'static Kernel,
361 chip: &'static C,
362 process_binary: ProcessBinary,
363 app_memory: &'static mut [u8],
364 app_id: ShortId,
365 index: usize,
366 fault_policy: &'static dyn ProcessFaultPolicy,
367 storage_policy: &'static dyn ProcessStandardStoragePermissionsPolicy<C, D>,
368) -> Result<(&'static mut [u8], Option<&'static dyn Process>), (&'static mut [u8], ProcessLoadError)>
369{
370 if config::CONFIG.debug_load_processes {
371 debug!(
372 "Loading: process flash={:#010X}-{:#010X} ram={:#010X}-{:#010X}",
373 process_binary.flash.as_ptr() as usize,
374 process_binary.flash.as_ptr() as usize + process_binary.flash.len() - 1,
375 app_memory.as_ptr() as usize,
376 app_memory.as_ptr() as usize + app_memory.len() - 1
377 );
378 }
379
380 // Need to reassign remaining_memory in every iteration so the compiler
381 // knows it will not be re-borrowed.
382 // If we found an actual app header, try to create a `Process`
383 // object. We also need to shrink the amount of remaining memory
384 // based on whatever is assigned to the new process if one is
385 // created.
386
387 // Try to create a process object from that app slice. If we don't
388 // get a process and we didn't get a loading error (aka we got to
389 // this point), then the app is a disabled process or just padding.
390 let (process_option, unused_memory) = unsafe {
391 ProcessStandard::<C, D>::create(
392 kernel,
393 chip,
394 process_binary,
395 app_memory,
396 fault_policy,
397 storage_policy,
398 app_id,
399 index,
400 )
401 .map_err(|(e, memory)| (memory, e))?
402 };
403
404 process_option.map(|process| {
405 if config::CONFIG.debug_load_processes {
406 debug!(
407 "Loading: {} [{}] flash={:#010X}-{:#010X} ram={:#010X}-{:#010X}",
408 process.get_process_name(),
409 index,
410 process.get_addresses().flash_start,
411 process.get_addresses().flash_end,
412 process.get_addresses().sram_start,
413 process.get_addresses().sram_end - 1,
414 );
415 }
416 });
417
418 Ok((unused_memory, process_option))
419}
420
421////////////////////////////////////////////////////////////////////////////////
422// ASYNCHRONOUS PROCESS LOADING
423////////////////////////////////////////////////////////////////////////////////
424
425/// Client for asynchronous process loading.
426///
427/// This supports a client that is notified after trying to load each process in
428/// flash. Also there is a callback for after all processes have been
429/// discovered.
430pub trait ProcessLoadingAsyncClient {
431 /// A process was successfully found in flash, checked, and loaded into a
432 /// `ProcessStandard` object.
433 fn process_loaded(&self, result: Result<(), ProcessLoadError>);
434
435 /// There are no more processes in flash to be loaded.
436 fn process_loading_finished(&self);
437}
438
439/// Asynchronous process loading.
440///
441/// Machines which implement this trait perform asynchronous process loading and
442/// signal completion through `ProcessLoadingAsyncClient`.
443///
444/// Various process loaders may exist. This includes a loader from a MCU's
445/// integrated flash, or a loader from an external flash chip.
446pub trait ProcessLoadingAsync<'a> {
447 /// Set the client to receive callbacks about process loading and when
448 /// process loading has finished.
449 fn set_client(&self, client: &'a dyn ProcessLoadingAsyncClient);
450
451 /// Set the credential checking policy for the loader.
452 fn set_policy(&self, policy: &'a dyn AppIdPolicy);
453
454 /// Start the process loading operation.
455 fn start(&self);
456}
457
458/// Operating mode of the loader.
459#[derive(Clone, Copy)]
460enum SequentialProcessLoaderMachineState {
461 /// Phase of discovering `ProcessBinary` objects in flash.
462 DiscoverProcessBinaries,
463 /// Phase of loading `ProcessBinary`s into `Process`es.
464 LoadProcesses,
465}
466
467/// Operating mode of the sequential process loader.
468///
469/// The loader supports loading processes from flash at boot, and loading processes
470/// that were written to flash dynamically at runtime. Most of the internal logic is the
471/// same (and therefore reused), but we need to track which mode of operation the
472/// loader is in.
473#[derive(Clone, Copy)]
474enum SequentialProcessLoaderMachineRunMode {
475 /// The loader was called by a board's main function at boot.
476 BootMode,
477 /// The loader was called by a dynamic process loader at runtime.
478 RuntimeMode,
479}
480
481/// Enum to hold the padding requirements for a new application.
482#[derive(Clone, Copy, PartialEq, Default)]
483pub enum PaddingRequirement {
484 #[default]
485 None,
486 PrePad,
487 PostPad,
488 PreAndPostPad,
489}
490
491/// A machine for loading processes stored sequentially in a region of flash.
492///
493/// Load processes (stored as TBF objects in flash) into runnable process
494/// structures stored in the `procs` array. This machine scans the footers in
495/// the TBF for cryptographic credentials for binary integrity, passing them to
496/// the checker to decide whether the process has sufficient credentials to run.
497pub struct SequentialProcessLoaderMachine<'a, C: Chip + 'static, D: ProcessStandardDebug + 'static>
498{
499 /// Client to notify as processes are loaded and process loading finishes after boot.
500 boot_client: OptionalCell<&'a dyn ProcessLoadingAsyncClient>,
501 /// Client to notify as processes are loaded and process loading finishes during runtime.
502 runtime_client: OptionalCell<&'a dyn ProcessLoadingAsyncClient>,
503 /// Machine to use to check process credentials.
504 checker: &'static ProcessCheckerMachine,
505 /// Array to store `ProcessBinary`s after checking credentials.
506 proc_binaries: MapCell<&'static mut [Option<ProcessBinary>]>,
507 /// Total available flash for process binaries on this board.
508 flash_bank: Cell<&'static [u8]>,
509 /// Flash memory region to load processes from.
510 flash: Cell<&'static [u8]>,
511 /// Memory available to assign to applications.
512 app_memory: Cell<&'static mut [u8]>,
513 /// Mechanism for generating async callbacks.
514 deferred_call: DeferredCall,
515 /// Reference to the kernel object for creating Processes.
516 kernel: &'static Kernel,
517 /// Reference to the Chip object for creating Processes.
518 chip: &'static C,
519 /// The policy to use when determining ShortIds and process uniqueness.
520 policy: OptionalCell<&'a dyn AppIdPolicy>,
521 /// The fault policy to assign to each created Process.
522 fault_policy: &'static dyn ProcessFaultPolicy,
523 /// The storage permissions policy to assign to each created Process.
524 storage_policy: &'static dyn ProcessStandardStoragePermissionsPolicy<C, D>,
525 /// Current mode of the loading machine.
526 state: OptionalCell<SequentialProcessLoaderMachineState>,
527 /// Current operating mode of the loading machine.
528 run_mode: OptionalCell<SequentialProcessLoaderMachineRunMode>,
529}
530
531impl<'a, C: Chip, D: ProcessStandardDebug> SequentialProcessLoaderMachine<'a, C, D> {
532 /// This function is made `pub` so that board files can use it, but loading
533 /// processes from slices of flash an memory is fundamentally unsafe.
534 /// Therefore, we require the `ProcessManagementCapability` to call this
535 /// function.
536 pub fn new(
537 checker: &'static ProcessCheckerMachine,
538 proc_binaries: &'static mut [Option<ProcessBinary>],
539 kernel: &'static Kernel,
540 chip: &'static C,
541 flash: &'static [u8],
542 app_memory: &'static mut [u8],
543 fault_policy: &'static dyn ProcessFaultPolicy,
544 storage_policy: &'static dyn ProcessStandardStoragePermissionsPolicy<C, D>,
545 policy: &'static dyn AppIdPolicy,
546 _capability_management: &dyn ProcessManagementCapability,
547 ) -> Self {
548 Self {
549 deferred_call: DeferredCall::new(),
550 checker,
551 boot_client: OptionalCell::empty(),
552 runtime_client: OptionalCell::empty(),
553 run_mode: OptionalCell::empty(),
554 proc_binaries: MapCell::new(proc_binaries),
555 kernel,
556 chip,
557 flash_bank: Cell::new(flash),
558 flash: Cell::new(flash),
559 app_memory: Cell::new(app_memory),
560 policy: OptionalCell::new(policy),
561 fault_policy,
562 storage_policy,
563 state: OptionalCell::empty(),
564 }
565 }
566
567 /// Set the runtime client to receive callbacks about process loading and when
568 /// process loading has finished.
569 pub fn set_runtime_client(&self, client: &'a dyn ProcessLoadingAsyncClient) {
570 self.runtime_client.set(client);
571 }
572
573 /// Find the current active client based on the operation mode.
574 fn get_current_client(&self) -> Option<&dyn ProcessLoadingAsyncClient> {
575 match self.run_mode.get()? {
576 SequentialProcessLoaderMachineRunMode::BootMode => self.boot_client.get(),
577 SequentialProcessLoaderMachineRunMode::RuntimeMode => self.runtime_client.get(),
578 }
579 }
580
581 /// Find a slot in the `PROCESS_BINARIES` array to store this process.
582 fn find_open_process_binary_slot(&self) -> Option<usize> {
583 self.proc_binaries.map_or(None, |proc_bins| {
584 for (i, p) in proc_bins.iter().enumerate() {
585 if p.is_none() {
586 return Some(i);
587 }
588 }
589 None
590 })
591 }
592
593 fn load_and_check(&self) {
594 let ret = self.discover_process_binary();
595 match ret {
596 Ok(pb) => match self.checker.check(pb) {
597 Ok(()) => {}
598 Err(e) => {
599 self.get_current_client().map(|client| {
600 client.process_loaded(Err(ProcessLoadError::CheckError(e)));
601 });
602 }
603 },
604 Err(ProcessBinaryError::NotEnoughFlash)
605 | Err(ProcessBinaryError::TbfHeaderNotFound) => {
606 // These two errors occur when there are no more app binaries in
607 // flash. Now we can move to actually loading process binaries
608 // into full processes.
609
610 self.state
611 .set(SequentialProcessLoaderMachineState::LoadProcesses);
612 self.deferred_call.set();
613 }
614 Err(e) => {
615 if config::CONFIG.debug_load_processes {
616 debug!("Loading: unable to create ProcessBinary: {:?}", e);
617 }
618
619 // Other process binary errors indicate the process is not
620 // compatible. Signal error and try the next item in flash.
621 self.get_current_client().map(|client| {
622 client.process_loaded(Err(ProcessLoadError::BinaryError(e)));
623 });
624
625 self.deferred_call.set();
626 }
627 }
628 }
629
630 /// Try to parse a process binary from flash.
631 ///
632 /// Returns the process binary object or an error if a valid process
633 /// binary could not be extracted.
634 fn discover_process_binary(&self) -> Result<ProcessBinary, ProcessBinaryError> {
635 let flash = self.flash.get();
636
637 match discover_process_binary(flash) {
638 Ok((remaining_flash, pb)) => {
639 self.flash.set(remaining_flash);
640 Ok(pb)
641 }
642
643 Err((remaining_flash, err)) => {
644 self.flash.set(remaining_flash);
645 Err(err)
646 }
647 }
648 }
649
650 /// Create process objects from the discovered process binaries.
651 ///
652 /// This verifies that the discovered processes are valid to run.
653 fn load_process_objects(&self) -> Result<(), ()> {
654 let proc_binaries = self.proc_binaries.take().ok_or(())?;
655 let proc_binaries_len = proc_binaries.len();
656
657 // Iterate all process binary entries.
658 for i in 0..proc_binaries_len {
659 // We are either going to load this process binary or discard it, so
660 // we can use `take()` here.
661 if let Some(process_binary) = proc_binaries[i].take() {
662 // We assume the process can be loaded. This is not the case
663 // if there is a conflicting process.
664 let mut ok_to_load = true;
665
666 // Start by iterating all other process binaries and seeing
667 // if any are in conflict (same AppID with newer version).
668 for proc_bin in proc_binaries.iter() {
669 if let Some(other_process_binary) = proc_bin {
670 let blocked =
671 self.is_blocked_from_loading_by(&process_binary, other_process_binary);
672
673 if blocked {
674 ok_to_load = false;
675 break;
676 }
677 }
678 }
679
680 // Go to next ProcessBinary if we cannot load this process.
681 if !ok_to_load {
682 continue;
683 }
684
685 // Now scan the already loaded processes and make sure this
686 // doesn't conflict with any of those. Since those processes
687 // are already loaded, we just need to check if this process
688 // binary has the same AppID as an already loaded process.
689 for proc in self.kernel.get_process_iter() {
690 let blocked = self.is_blocked_from_loading_by_process(&process_binary, proc);
691 if blocked {
692 ok_to_load = false;
693 break;
694 }
695 }
696
697 if !ok_to_load {
698 continue;
699 }
700
701 // If we get here it is ok to load the process.
702 match self.kernel.next_available_process_slot() {
703 Ok((index, slot)) => {
704 // Calculate the ShortId for this new process.
705 let short_app_id = self.policy.map_or(ShortId::LocallyUnique, |policy| {
706 policy.to_short_id(&process_binary)
707 });
708
709 // Try to create a `Process` object.
710 let load_result = load_process(
711 self.kernel,
712 self.chip,
713 process_binary,
714 self.app_memory.take(),
715 short_app_id,
716 index,
717 self.fault_policy,
718 self.storage_policy,
719 );
720 match load_result {
721 Ok((new_mem, proc)) => {
722 self.app_memory.set(new_mem);
723 match proc {
724 Some(p) => {
725 if config::CONFIG.debug_load_processes {
726 debug!(
727 "Loading: Loaded process {}",
728 p.get_process_name()
729 )
730 }
731
732 // Store the `ProcessStandard` object in the `PROCESSES`
733 // array.
734 slot.set(p);
735 // Notify the client the process was loaded
736 // successfully.
737 self.get_current_client().map(|client| {
738 client.process_loaded(Ok(()));
739 });
740 }
741 None => {
742 if config::CONFIG.debug_load_processes {
743 debug!("No process loaded.");
744 }
745 }
746 }
747 }
748 Err((new_mem, err)) => {
749 self.app_memory.set(new_mem);
750 if config::CONFIG.debug_load_processes {
751 debug!("Could not load process: {:?}.", err);
752 }
753 self.get_current_client().map(|client| {
754 client.process_loaded(Err(err));
755 });
756 }
757 }
758 }
759 Err(()) => {
760 // Nowhere to store the process.
761 self.get_current_client().map(|client| {
762 client.process_loaded(Err(ProcessLoadError::NoProcessSlot));
763 });
764 }
765 }
766 }
767 }
768 self.proc_binaries.put(proc_binaries);
769
770 // We have iterated all discovered `ProcessBinary`s and loaded what we
771 // could so now we can signal that process loading is finished.
772 self.get_current_client().map(|client| {
773 client.process_loading_finished();
774 });
775
776 self.state.clear();
777 Ok(())
778 }
779
780 /// Check if `pb1` is blocked from running by `pb2`.
781 ///
782 /// `pb2` blocks `pb1` if:
783 ///
784 /// - They both have the same AppID or they both have the same ShortId, and
785 /// - `pb2` has a higher version number.
786 fn is_blocked_from_loading_by(&self, pb1: &ProcessBinary, pb2: &ProcessBinary) -> bool {
787 let same_app_id = self
788 .policy
789 .map_or(false, |policy| !policy.different_identifier(pb1, pb2));
790 let same_short_app_id = self.policy.map_or(false, |policy| {
791 policy.to_short_id(pb1) == policy.to_short_id(pb2)
792 });
793 let other_newer = pb2.header.get_binary_version() > pb1.header.get_binary_version();
794
795 let blocks = (same_app_id || same_short_app_id) && other_newer;
796
797 if config::CONFIG.debug_process_credentials {
798 debug!(
799 "Loading: ProcessBinary {}({:#02x}) does{} block {}({:#02x})",
800 pb2.header.get_package_name().unwrap_or(""),
801 pb2.flash.as_ptr() as usize,
802 if blocks { "" } else { " not" },
803 pb1.header.get_package_name().unwrap_or(""),
804 pb1.flash.as_ptr() as usize,
805 );
806 }
807
808 blocks
809 }
810
811 /// Check if `pb` is blocked from running by `process`.
812 ///
813 /// `process` blocks `pb` if:
814 ///
815 /// - They both have the same AppID, or
816 /// - They both have the same ShortId
817 ///
818 /// Since `process` is already loaded, we only have to enforce the AppID and
819 /// ShortId uniqueness guarantees.
820 fn is_blocked_from_loading_by_process(
821 &self,
822 pb: &ProcessBinary,
823 process: &dyn Process,
824 ) -> bool {
825 let same_app_id = self.policy.map_or(false, |policy| {
826 !policy.different_identifier_process(pb, process)
827 });
828 let same_short_app_id = self.policy.map_or(false, |policy| {
829 policy.to_short_id(pb) == process.short_app_id()
830 });
831
832 let blocks = same_app_id || same_short_app_id;
833
834 if config::CONFIG.debug_process_credentials {
835 debug!(
836 "Loading: Process {}({:#02x}) does{} block {}({:#02x})",
837 process.get_process_name(),
838 process.get_addresses().flash_start,
839 if blocks { "" } else { " not" },
840 pb.header.get_package_name().unwrap_or(""),
841 pb.flash.as_ptr() as usize,
842 );
843 }
844
845 blocks
846 }
847
848 ////////////////////////////////////////////////////////////////////////////////
849 // DYNAMIC PROCESS LOADING HELPERS
850 ////////////////////////////////////////////////////////////////////////////////
851
852 /// Scan the entire flash to populate lists of existing binaries addresses.
853 fn scan_flash_for_process_binaries(
854 &self,
855 flash: &'static [u8],
856 process_binaries_start_addresses: &mut [usize],
857 process_binaries_end_addresses: &mut [usize],
858 ) -> Result<(), ()> {
859 fn inner_function(
860 flash: &'static [u8],
861 process_binaries_start_addresses: &mut [usize],
862 process_binaries_end_addresses: &mut [usize],
863 ) -> Result<(), ProcessBinaryError> {
864 let flash_end = flash.as_ptr() as usize + flash.len() - 1;
865 let mut addresses = flash.as_ptr() as usize;
866 let mut index: usize = 0;
867
868 while addresses < flash_end {
869 let flash_offset = addresses - flash.as_ptr() as usize;
870
871 let test_header_slice = flash
872 .get(flash_offset..flash_offset + 8)
873 .ok_or(ProcessBinaryError::NotEnoughFlash)?;
874
875 let header = test_header_slice
876 .try_into()
877 .or(Err(ProcessBinaryError::NotEnoughFlash))?;
878
879 let (_version, header_length, app_length) =
880 match tock_tbf::parse::parse_tbf_header_lengths(header) {
881 Ok((v, hl, el)) => (v, hl, el),
882 Err(tock_tbf::types::InitialTbfParseError::InvalidHeader(app_length)) => {
883 (0, 0, app_length)
884 }
885 Err(tock_tbf::types::InitialTbfParseError::UnableToParse) => {
886 return Ok(());
887 }
888 };
889
890 let app_flash = flash
891 .get(flash_offset..flash_offset + app_length as usize)
892 .ok_or(ProcessBinaryError::NotEnoughFlash)?;
893
894 let app_header = flash
895 .get(flash_offset..flash_offset + header_length as usize)
896 .ok_or(ProcessBinaryError::NotEnoughFlash)?;
897
898 let remaining_flash = flash
899 .get(flash_offset + app_flash.len()..)
900 .ok_or(ProcessBinaryError::NotEnoughFlash)?;
901
902 // Get the rest of the header. The `remaining_header` variable
903 // will continue to hold the remainder of the header we have
904 // not processed.
905 let remaining_header = app_header
906 .get(16..)
907 .ok_or(ProcessBinaryError::NotEnoughFlash)?;
908
909 if remaining_header.len() == 0 {
910 // This is a padding app.
911 if config::CONFIG.debug_load_processes {
912 debug!("Is padding!");
913 }
914 } else {
915 // This is an app binary, add it to the pb arrays.
916 process_binaries_start_addresses[index] = app_flash.as_ptr() as usize;
917 process_binaries_end_addresses[index] =
918 app_flash.as_ptr() as usize + app_length as usize;
919
920 if config::CONFIG.debug_load_processes {
921 debug!(
922 "[Metadata] Process binary start address at index {}: {:#010x}, with end_address {:#010x}",
923 index,
924 process_binaries_start_addresses[index],
925 process_binaries_end_addresses[index]
926 );
927 }
928 index += 1;
929 if index > process_binaries_start_addresses.len() - 1 {
930 return Err(ProcessBinaryError::NotEnoughFlash);
931 }
932 }
933 addresses = remaining_flash.as_ptr() as usize;
934 }
935
936 Ok(())
937 }
938
939 inner_function(
940 flash,
941 process_binaries_start_addresses,
942 process_binaries_end_addresses,
943 )
944 .or(Err(()))
945 }
946
947 /// Helper function to find the next potential aligned address for the
948 /// new app with size `app_length` assuming Cortex-M alignment rules.
949 fn find_next_cortex_m_aligned_address(&self, address: usize, app_length: usize) -> usize {
950 let remaining = address % app_length;
951 if remaining == 0 {
952 address
953 } else {
954 address + (app_length - remaining)
955 }
956 }
957
958 /// Function to compute the address for a new app with size `app_size`.
959 fn compute_new_process_binary_address(
960 &self,
961 app_size: usize,
962 process_binaries_start_addresses: &mut [usize],
963 process_binaries_end_addresses: &mut [usize],
964 ) -> usize {
965 let mut start_count = 0;
966 let mut end_count = 0;
967
968 // Remove zeros from addresses in place.
969 for i in 0..process_binaries_start_addresses.len() {
970 if process_binaries_start_addresses[i] != 0 {
971 process_binaries_start_addresses[start_count] = process_binaries_start_addresses[i];
972 start_count += 1;
973 }
974 }
975
976 for i in 0..process_binaries_end_addresses.len() {
977 if process_binaries_end_addresses[i] != 0 {
978 process_binaries_end_addresses[end_count] = process_binaries_end_addresses[i];
979 end_count += 1;
980 }
981 }
982
983 // If there is only one application in flash:
984 if start_count == 1 {
985 let potential_address = self
986 .find_next_cortex_m_aligned_address(process_binaries_end_addresses[0], app_size);
987 return potential_address;
988 }
989
990 // Otherwise, iterate through the sorted start and end addresses to find gaps for the new app.
991 for i in 0..start_count - 1 {
992 let gap_start = process_binaries_end_addresses[i];
993 let gap_end = process_binaries_start_addresses[i + 1];
994
995 // Ensure gap_end is valid (skip zeros - these indicate there are no process binaries).
996 if gap_end == 0 {
997 continue;
998 }
999
1000 // If there is a valid gap, i.e., (gap_end > gap_start), check alignment.
1001 if gap_end > gap_start {
1002 let potential_address =
1003 self.find_next_cortex_m_aligned_address(gap_start, app_size);
1004 if potential_address + app_size < gap_end {
1005 return potential_address;
1006 }
1007 }
1008 }
1009 // If no gaps found, check after the last app.
1010 let last_app_end_address = process_binaries_end_addresses[end_count - 1];
1011 self.find_next_cortex_m_aligned_address(last_app_end_address, app_size)
1012 }
1013
1014 /// This function checks if there is a need to pad either before or after
1015 /// the new app to preserve the linked list.
1016 ///
1017 /// When do we pad?
1018 ///
1019 /// 1. When there is a binary located in flash after the new app but
1020 /// not immediately after, we need to add padding between the new
1021 /// app and the existing app.
1022 /// 2. Due to MPU alignment, the new app may be similarly placed not
1023 /// immediately after an existing process, in that case, we need to add
1024 /// padding between the previous app and the new app.
1025 /// 3. If both the above conditions are met, we add both a prepadding and a
1026 /// postpadding.
1027 /// 4. If either of these conditions are not met, we don't pad.
1028 ///
1029 /// Change checks against process binaries instead of processes?
1030 fn compute_padding_requirement_and_neighbors(
1031 &self,
1032 new_app_start_address: usize,
1033 app_length: usize,
1034 process_binaries_start_addresses: &[usize],
1035 process_binaries_end_addresses: &[usize],
1036 ) -> (PaddingRequirement, usize, usize) {
1037 // The end address of our newly loaded application.
1038 let new_app_end_address = new_app_start_address + app_length;
1039 // To store the address until which we need to write the padding app.
1040 let mut next_app_start_addr = 0;
1041 // To store the address from which we need to write the padding app.
1042 let mut previous_app_end_addr = 0;
1043 let mut padding_requirement: PaddingRequirement = PaddingRequirement::None;
1044
1045 // We compute the closest neighbor to our app such that:
1046 //
1047 // 1. If the new app is placed in between two existing binaries, we
1048 // compute the closest located binaries.
1049 // 2. Once we compute these values, we determine if we need to write a
1050 // pre pad header, or a post pad header, or both.
1051 // 3. If there are no apps after ours in the process binary array, we don't
1052 // do anything.
1053
1054 // Postpad requirement.
1055 if let Some(next_closest_neighbor) = process_binaries_start_addresses
1056 .iter()
1057 .filter(|&&x| x > new_app_end_address - 1)
1058 .min()
1059 {
1060 // We found the next closest app in flash.
1061 next_app_start_addr = *next_closest_neighbor;
1062 if next_app_start_addr != 0 {
1063 padding_requirement = PaddingRequirement::PostPad;
1064 }
1065 } else {
1066 if config::CONFIG.debug_load_processes {
1067 debug!("No App Found after the new app so not adding post padding.");
1068 }
1069 }
1070
1071 // Prepad requirement.
1072 if let Some(previous_closest_neighbor) = process_binaries_end_addresses
1073 .iter()
1074 .filter(|&&x| x < new_app_start_address + 1)
1075 .max()
1076 {
1077 // We found the previous closest app in flash.
1078 previous_app_end_addr = *previous_closest_neighbor;
1079 if new_app_start_address - previous_app_end_addr != 0 {
1080 if padding_requirement == PaddingRequirement::PostPad {
1081 padding_requirement = PaddingRequirement::PreAndPostPad;
1082 } else {
1083 padding_requirement = PaddingRequirement::PrePad;
1084 }
1085 }
1086 } else {
1087 if config::CONFIG.debug_load_processes {
1088 debug!("No Previous App Found, so not padding before the new app.");
1089 }
1090 }
1091 (
1092 padding_requirement,
1093 previous_app_end_addr,
1094 next_app_start_addr,
1095 )
1096 }
1097
1098 /// This function scans flash, checks for, and returns an address that follows alignment rules given
1099 /// an app size of `new_app_size`.
1100 fn check_flash_for_valid_address(
1101 &self,
1102 new_app_size: usize,
1103 pb_start_address: &mut [usize],
1104 pb_end_address: &mut [usize],
1105 ) -> Result<usize, ProcessBinaryError> {
1106 let total_flash = self.flash_bank.get();
1107 let total_flash_start = total_flash.as_ptr() as usize;
1108 let total_flash_end = total_flash_start + total_flash.len() - 1;
1109
1110 match self.scan_flash_for_process_binaries(total_flash, pb_start_address, pb_end_address) {
1111 Ok(()) => {
1112 if config::CONFIG.debug_load_processes {
1113 debug!("Successfully scanned flash");
1114 }
1115 let new_app_address = self.compute_new_process_binary_address(
1116 new_app_size,
1117 pb_start_address,
1118 pb_end_address,
1119 );
1120 if new_app_address + new_app_size - 1 > total_flash_end {
1121 Err(ProcessBinaryError::NotEnoughFlash)
1122 } else {
1123 Ok(new_app_address)
1124 }
1125 }
1126 Err(()) => Err(ProcessBinaryError::NotEnoughFlash),
1127 }
1128 }
1129
1130 /// Function to check if the object with address `offset` of size `length` lies
1131 /// within flash bounds.
1132 pub fn check_if_within_flash_bounds(&self, offset: usize, length: usize) -> bool {
1133 let flash = self.flash_bank.get();
1134 let flash_end = flash.as_ptr() as usize + flash.len() - 1;
1135
1136 (flash_end - offset) >= length
1137 }
1138
1139 /// Function to compute an available address for the new application binary.
1140 pub fn check_flash_for_new_address(
1141 &self,
1142 new_app_size: usize,
1143 ) -> Result<(usize, PaddingRequirement, usize, usize), ProcessBinaryError> {
1144 const MAX_PROCS: usize = 10;
1145 let mut pb_start_address: [usize; MAX_PROCS] = [0; MAX_PROCS];
1146 let mut pb_end_address: [usize; MAX_PROCS] = [0; MAX_PROCS];
1147 match self.check_flash_for_valid_address(
1148 new_app_size,
1149 &mut pb_start_address,
1150 &mut pb_end_address,
1151 ) {
1152 Ok(app_address) => {
1153 let (pr, prev_app_addr, next_app_addr) = self
1154 .compute_padding_requirement_and_neighbors(
1155 app_address,
1156 new_app_size,
1157 &pb_start_address,
1158 &pb_end_address,
1159 );
1160 let (padding_requirement, previous_app_end_addr, next_app_start_addr) =
1161 (pr, prev_app_addr, next_app_addr);
1162 Ok((
1163 app_address,
1164 padding_requirement,
1165 previous_app_end_addr,
1166 next_app_start_addr,
1167 ))
1168 }
1169 Err(e) => Err(e),
1170 }
1171 }
1172
1173 /// Function to check if the app binary at address `app_address` is valid.
1174 fn check_new_binary_validity(&self, app_address: usize) -> bool {
1175 let flash = self.flash_bank.get();
1176 // Pass the first eight bytes of the tbfheader to parse out the
1177 // length of the tbf header and app. We then use those values to see
1178 // if we have enough flash remaining to parse the remainder of the
1179 // header.
1180 let binary_header = match flash.get(app_address..app_address + 8) {
1181 Some(slice) if slice.len() == 8 => slice,
1182 _ => return false, // Ensure exactly 8 bytes are available
1183 };
1184
1185 let binary_header_array: &[u8; 8] = match binary_header.try_into() {
1186 Ok(arr) => arr,
1187 Err(_) => return false,
1188 };
1189
1190 match tock_tbf::parse::parse_tbf_header_lengths(binary_header_array) {
1191 Ok((_version, _header_length, _entry_length)) => true,
1192 Err(tock_tbf::types::InitialTbfParseError::InvalidHeader(_entry_length)) => false,
1193 Err(tock_tbf::types::InitialTbfParseError::UnableToParse) => false,
1194 }
1195 }
1196
1197 /// Function to start loading the new application at address `app_address` with size
1198 /// `app_size`.
1199 pub fn load_new_process_binary(
1200 &self,
1201 app_address: usize,
1202 app_size: usize,
1203 ) -> Result<(), ProcessLoadError> {
1204 let flash = self.flash_bank.get();
1205 let process_address = app_address - flash.as_ptr() as usize;
1206 let process_flash = flash.get(process_address..process_address + app_size);
1207 let result = self.check_new_binary_validity(process_address);
1208 match result {
1209 true => {
1210 if let Some(flash) = process_flash {
1211 self.flash.set(flash);
1212 } else {
1213 return Err(ProcessLoadError::BinaryError(
1214 ProcessBinaryError::TbfHeaderNotFound,
1215 ));
1216 }
1217
1218 self.state
1219 .set(SequentialProcessLoaderMachineState::DiscoverProcessBinaries);
1220
1221 self.run_mode
1222 .set(SequentialProcessLoaderMachineRunMode::RuntimeMode);
1223 // Start an asynchronous flow so we can issue a callback on error.
1224 self.deferred_call.set();
1225
1226 Ok(())
1227 }
1228 false => Err(ProcessLoadError::BinaryError(
1229 ProcessBinaryError::TbfHeaderNotFound,
1230 )),
1231 }
1232 }
1233}
1234
1235impl<'a, C: Chip, D: ProcessStandardDebug> ProcessLoadingAsync<'a>
1236 for SequentialProcessLoaderMachine<'a, C, D>
1237{
1238 fn set_client(&self, client: &'a dyn ProcessLoadingAsyncClient) {
1239 self.boot_client.set(client);
1240 }
1241
1242 fn set_policy(&self, policy: &'a dyn AppIdPolicy) {
1243 self.policy.replace(policy);
1244 }
1245
1246 fn start(&self) {
1247 self.state
1248 .set(SequentialProcessLoaderMachineState::DiscoverProcessBinaries);
1249 self.run_mode
1250 .set(SequentialProcessLoaderMachineRunMode::BootMode);
1251 // Start an asynchronous flow so we can issue a callback on error.
1252 self.deferred_call.set();
1253 }
1254}
1255
1256impl<C: Chip, D: ProcessStandardDebug> DeferredCallClient
1257 for SequentialProcessLoaderMachine<'_, C, D>
1258{
1259 fn handle_deferred_call(&self) {
1260 // We use deferred calls to start the operation in the async loop.
1261 match self.state.get() {
1262 Some(SequentialProcessLoaderMachineState::DiscoverProcessBinaries) => {
1263 self.load_and_check();
1264 }
1265 Some(SequentialProcessLoaderMachineState::LoadProcesses) => {
1266 let ret = self.load_process_objects();
1267 match ret {
1268 Ok(()) => {}
1269 Err(()) => {
1270 // If this failed for some reason, we still need to
1271 // signal that process loading has finished.
1272 self.get_current_client().map(|client| {
1273 client.process_loading_finished();
1274 });
1275 }
1276 }
1277 }
1278 None => {}
1279 }
1280 }
1281
1282 fn register(&'static self) {
1283 self.deferred_call.register(self);
1284 }
1285}
1286
1287impl<C: Chip, D: ProcessStandardDebug> crate::process_checker::ProcessCheckerMachineClient
1288 for SequentialProcessLoaderMachine<'_, C, D>
1289{
1290 fn done(
1291 &self,
1292 process_binary: ProcessBinary,
1293 result: Result<Option<AcceptedCredential>, crate::process_checker::ProcessCheckError>,
1294 ) {
1295 // Check if this process was approved by the checker.
1296 match result {
1297 Ok(optional_credential) => {
1298 if config::CONFIG.debug_load_processes {
1299 debug!(
1300 "Loading: Check succeeded for process {}",
1301 process_binary.header.get_package_name().unwrap_or("")
1302 );
1303 }
1304 // Save the checked process binary now that we know it is valid.
1305 match self.find_open_process_binary_slot() {
1306 Some(index) => {
1307 self.proc_binaries.map(|proc_binaries| {
1308 process_binary.credential.insert(optional_credential);
1309 proc_binaries[index] = Some(process_binary);
1310 });
1311 }
1312 None => {
1313 self.get_current_client().map(|client| {
1314 client.process_loaded(Err(ProcessLoadError::NoProcessSlot));
1315 });
1316 }
1317 }
1318 }
1319 Err(e) => {
1320 if config::CONFIG.debug_load_processes {
1321 debug!(
1322 "Loading: Process {} check failed {:?}",
1323 process_binary.header.get_package_name().unwrap_or(""),
1324 e
1325 );
1326 }
1327 // Signal error and call try next
1328 self.get_current_client().map(|client| {
1329 client.process_loaded(Err(ProcessLoadError::CheckError(e)));
1330 });
1331 }
1332 }
1333
1334 // Try to load the next process in flash.
1335 self.deferred_call.set();
1336 }
1337}