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}