Skip to main content

kernel/
process_standard.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//! Tock default Process implementation.
6//!
7//! `ProcessStandard` is an implementation for a userspace process running on
8//! the Tock kernel.
9
10use core::cell::Cell;
11use core::cmp;
12use core::fmt::Write;
13use core::mem::MaybeUninit;
14use core::num::NonZeroU32;
15use core::ptr::NonNull;
16use core::{mem, ptr, slice, str};
17
18use crate::collections::queue::Queue;
19use crate::collections::ring_buffer::RingBuffer;
20use crate::config;
21use crate::debug;
22use crate::errorcode::ErrorCode;
23use crate::init_uninit_struct;
24use crate::kernel::Kernel;
25use crate::platform::chip::Chip;
26use crate::platform::mpu::{self, MPU};
27use crate::process::ProcessBinary;
28use crate::process::{BinaryVersion, ReturnArguments};
29use crate::process::{Error, FunctionCall, FunctionCallSource, Process, Task};
30use crate::process::{FaultAction, ProcessCustomGrantIdentifier, ProcessId};
31use crate::process::{ProcessAddresses, ProcessSizes, ShortId};
32use crate::process::{State, StoppedState};
33use crate::process_checker::AcceptedCredential;
34use crate::process_loading::ProcessLoadError;
35use crate::process_policies::ProcessFaultPolicy;
36use crate::process_policies::ProcessStandardStoragePermissionsPolicy;
37use crate::processbuffer::{ReadOnlyProcessBuffer, ReadWriteProcessBuffer};
38use crate::storage_permissions::StoragePermissions;
39use crate::syscall::{self, Syscall, SyscallReturn, UserspaceKernelBoundary};
40use crate::upcall::UpcallId;
41use crate::utilities::capability_ptr::{CapabilityPtr, CapabilityPtrPermissions};
42use crate::utilities::cells::{MapCell, NumericCellExt, OptionalCell};
43
44use tock_tbf::types::CommandPermissions;
45
46/// Gets a mutable (unique) reference to the contained value.
47///
48/// TODO: this is copied from the standard library, where it is available under
49/// the `maybe_uninit_slice` nightly feature. Remove and switch to the core
50/// library variant once that is stable.
51///
52/// # Safety
53///
54/// Calling this when the content is not yet fully initialized causes undefined
55/// behavior: it is up to the caller to guarantee that every `MaybeUninit<T>` in the
56/// slice really is in an initialized state. For instance, `.assume_init_mut()` cannot
57/// be used to initialize a `MaybeUninit` slice.
58#[inline(always)]
59const unsafe fn maybe_uninit_slice_assume_init_mut<T>(src: &mut [MaybeUninit<T>]) -> &mut [T] {
60    // SAFETY: similar to safety notes for `slice_get_ref`, but we have a
61    // mutable reference which is also guaranteed to be valid for writes.
62    #[allow(clippy::ref_as_ptr)]
63    unsafe {
64        &mut *(src as *mut [MaybeUninit<T>] as *mut [T])
65    }
66}
67
68/// Divides one mutable raw slice into two at an index.
69///
70/// This method implementation is copied from the standard library, where it is
71/// available with `raw_slice_split` nightly feature. TODO: switch to the
72/// standard library function once that is stable.
73///
74/// The first will contain all indices from `[0, mid)` (excluding the index
75/// `mid` itself) and the second will contain all indices from `[mid, len)`
76/// (excluding the index `len` itself).
77///
78/// # Panics
79///
80/// Panics if `mid > len`.
81///
82/// # Safety
83///
84/// `mid` must be [in-bounds] of the underlying [allocation].  Which means
85/// `self` must be dereferenceable and span a single allocation that is at least
86/// `mid * size_of::<T>()` bytes long. Not upholding these requirements is
87/// *[undefined behavior]* even if the resulting pointers are not used.
88///
89/// Since `len` being in-bounds is not a safety invariant of `*mut [T]` the
90/// safety requirements of this method are the same as for
91/// [`split_at_mut_unchecked`].  The explicit bounds check is only as useful as
92/// `len` is correct.
93///
94/// [`split_at_mut_unchecked`]: https://doc.rust-lang.org/stable/std/primitive.pointer.html#method.split_at_mut_unchecked
95/// [in-bounds]: https://doc.rust-lang.org/stable/std/primitive.pointer.html#method.add-1
96/// [allocation]: https://doc.rust-lang.org/stable/std/ptr/index.html#allocation
97/// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
98unsafe fn raw_slice_split_at_mut<T>(slice: *mut [T], mid: usize) -> (*mut [T], *mut [T]) {
99    assert!(mid <= slice.len());
100
101    let len = slice.len();
102    let ptr = slice.cast::<T>();
103
104    // SAFETY: Caller must pass a valid pointer and an index that is in-bounds.
105    let tail = unsafe { ptr.add(mid) };
106    (
107        core::ptr::slice_from_raw_parts_mut(ptr, mid),
108        core::ptr::slice_from_raw_parts_mut(tail, len - mid),
109    )
110}
111
112/// Interface supported by [`ProcessStandard`] for recording debug information.
113///
114/// This trait provides flexibility to users of [`ProcessStandard`] to determine
115/// how debugging information should be recorded, or if debugging information
116/// should be recorded at all.
117///
118/// Platforms that want to only maintain certain debugging information can
119/// implement only part of this trait.
120///
121/// Tock provides a default implementation of this trait on the `()` type.
122/// Kernels that wish to use [`ProcessStandard`] but do not need process-level
123/// debugging information can use `()` as the `ProcessStandardDebug` type.
124pub trait ProcessStandardDebug: Default {
125    /// Record the address in flash the process expects to start at.
126    fn set_fixed_address_flash(&self, address: u32);
127    /// Get the address in flash the process expects to start at, if it was
128    /// recorded.
129    fn get_fixed_address_flash(&self) -> Option<u32>;
130    /// Record the address in RAM the process expects to start at.
131    fn set_fixed_address_ram(&self, address: u32);
132    /// Get the address in RAM the process expects to start at, if it was
133    /// recorded.
134    fn get_fixed_address_ram(&self) -> Option<u32>;
135    /// Record the address where the process placed its heap.
136    fn set_app_heap_start_pointer(&self, ptr: *const u8);
137    /// Get the address where the process placed its heap, if it was recorded.
138    fn get_app_heap_start_pointer(&self) -> Option<*const u8>;
139    /// Record the address where the process placed its stack.
140    fn set_app_stack_start_pointer(&self, ptr: *const u8);
141    /// Get the address where the process placed its stack, if it was recorded.
142    fn get_app_stack_start_pointer(&self) -> Option<*const u8>;
143    /// Update the lowest address that the process's stack has reached.
144    fn set_app_stack_min_pointer(&self, ptr: *const u8);
145    /// Get the lowest address of the process's stack , if it was recorded.
146    fn get_app_stack_min_pointer(&self) -> Option<*const u8>;
147    /// Provide the current address of the bottom of the stack and record the
148    /// address if it is the lowest address that the process's stack has
149    /// reached.
150    fn set_new_app_stack_min_pointer(&self, ptr: *const u8);
151
152    /// Record the most recent system call the process called.
153    fn set_last_syscall(&self, syscall: Syscall);
154    /// Get the most recent system call the process called, if it was recorded.
155    fn get_last_syscall(&self) -> Option<Syscall>;
156    /// Clear any record of the most recent system call the process called.
157    fn reset_last_syscall(&self);
158
159    /// Increase the recorded count of the number of system calls the process
160    /// has called.
161    fn increment_syscall_count(&self);
162    /// Get the recorded count of the number of system calls the process has
163    /// called.
164    ///
165    /// This should return 0 if
166    /// [`ProcessStandardDebug::increment_syscall_count()`] is never called.
167    fn get_syscall_count(&self) -> usize;
168    /// Reset the recorded count of the number of system calls called by the app
169    /// to 0.
170    fn reset_syscall_count(&self);
171
172    /// Increase the recorded count of the number of upcalls that have been
173    /// dropped for the process.
174    fn increment_dropped_upcall_count(&self);
175    /// Get the recorded count of the number of upcalls that have been dropped
176    /// for the process.
177    ///
178    /// This should return 0 if
179    /// [`ProcessStandardDebug::increment_dropped_upcall_count()`] is never
180    /// called.
181    fn get_dropped_upcall_count(&self) -> usize;
182    /// Reset the recorded count of the number of upcalls that have been dropped
183    /// for the process to 0.
184    fn reset_dropped_upcall_count(&self);
185
186    /// Increase the recorded count of the number of times the process has
187    /// exceeded its timeslice.
188    fn increment_timeslice_expiration_count(&self);
189    /// Get the recorded count of the number times the process has exceeded its
190    /// timeslice.
191    ///
192    /// This should return 0 if
193    /// [`ProcessStandardDebug::increment_timeslice_expiration_count()`] is
194    /// never called.
195    fn get_timeslice_expiration_count(&self) -> usize;
196    /// Reset the recorded count of the number of the process has exceeded its
197    /// timeslice to 0.
198    fn reset_timeslice_expiration_count(&self);
199}
200
201/// A debugging implementation for [`ProcessStandard`] that records the full
202/// debugging state.
203pub struct ProcessStandardDebugFull {
204    /// Inner field for the debug state that is in a [`MapCell`] to provide
205    /// mutable access.
206    debug: MapCell<ProcessStandardDebugFullInner>,
207}
208
209/// Struct for debugging [`ProcessStandard`] processes that records the full set
210/// of debugging information.
211///
212/// These pointers and counters are not strictly required for kernel operation,
213/// but provide helpful information when an app crashes.
214#[derive(Default)]
215struct ProcessStandardDebugFullInner {
216    /// If this process was compiled for fixed addresses, save the address
217    /// it must be at in flash. This is useful for debugging and saves having
218    /// to re-parse the entire TBF header.
219    fixed_address_flash: Option<u32>,
220
221    /// If this process was compiled for fixed addresses, save the address
222    /// it must be at in RAM. This is useful for debugging and saves having
223    /// to re-parse the entire TBF header.
224    fixed_address_ram: Option<u32>,
225
226    /// Where the process has started its heap in RAM.
227    app_heap_start_pointer: Option<*const u8>,
228
229    /// Where the start of the stack is for the process. If the kernel does the
230    /// PIC setup for this app then we know this, otherwise we need the app to
231    /// tell us where it put its stack.
232    app_stack_start_pointer: Option<*const u8>,
233
234    /// How low have we ever seen the stack pointer.
235    app_stack_min_pointer: Option<*const u8>,
236
237    /// How many syscalls have occurred since the process started.
238    syscall_count: usize,
239
240    /// What was the most recent syscall.
241    last_syscall: Option<Syscall>,
242
243    /// How many upcalls were dropped because the queue was insufficiently
244    /// long.
245    dropped_upcall_count: usize,
246
247    /// How many times this process has been paused because it exceeded its
248    /// timeslice.
249    timeslice_expiration_count: usize,
250}
251
252impl ProcessStandardDebug for ProcessStandardDebugFull {
253    fn set_fixed_address_flash(&self, address: u32) {
254        self.debug.map(|d| d.fixed_address_flash = Some(address));
255    }
256    fn get_fixed_address_flash(&self) -> Option<u32> {
257        self.debug.map_or(None, |d| d.fixed_address_flash)
258    }
259    fn set_fixed_address_ram(&self, address: u32) {
260        self.debug.map(|d| d.fixed_address_ram = Some(address));
261    }
262    fn get_fixed_address_ram(&self) -> Option<u32> {
263        self.debug.map_or(None, |d| d.fixed_address_ram)
264    }
265    fn set_app_heap_start_pointer(&self, ptr: *const u8) {
266        self.debug.map(|d| d.app_heap_start_pointer = Some(ptr));
267    }
268    fn get_app_heap_start_pointer(&self) -> Option<*const u8> {
269        self.debug.map_or(None, |d| d.app_heap_start_pointer)
270    }
271    fn set_app_stack_start_pointer(&self, ptr: *const u8) {
272        self.debug.map(|d| d.app_stack_start_pointer = Some(ptr));
273    }
274    fn get_app_stack_start_pointer(&self) -> Option<*const u8> {
275        self.debug.map_or(None, |d| d.app_stack_start_pointer)
276    }
277    fn set_app_stack_min_pointer(&self, ptr: *const u8) {
278        self.debug.map(|d| d.app_stack_min_pointer = Some(ptr));
279    }
280    fn get_app_stack_min_pointer(&self) -> Option<*const u8> {
281        self.debug.map_or(None, |d| d.app_stack_min_pointer)
282    }
283    fn set_new_app_stack_min_pointer(&self, ptr: *const u8) {
284        self.debug.map(|d| {
285            match d.app_stack_min_pointer {
286                None => d.app_stack_min_pointer = Some(ptr),
287                Some(asmp) => {
288                    // Update max stack depth if needed.
289                    if ptr < asmp {
290                        d.app_stack_min_pointer = Some(ptr);
291                    }
292                }
293            }
294        });
295    }
296
297    fn set_last_syscall(&self, syscall: Syscall) {
298        self.debug.map(|d| d.last_syscall = Some(syscall));
299    }
300    fn get_last_syscall(&self) -> Option<Syscall> {
301        self.debug.map_or(None, |d| d.last_syscall)
302    }
303    fn reset_last_syscall(&self) {
304        self.debug.map(|d| d.last_syscall = None);
305    }
306
307    fn increment_syscall_count(&self) {
308        self.debug.map(|d| d.syscall_count += 1);
309    }
310    fn get_syscall_count(&self) -> usize {
311        self.debug.map_or(0, |d| d.syscall_count)
312    }
313    fn reset_syscall_count(&self) {
314        self.debug.map(|d| d.syscall_count = 0);
315    }
316
317    fn increment_dropped_upcall_count(&self) {
318        self.debug.map(|d| d.dropped_upcall_count += 1);
319    }
320    fn get_dropped_upcall_count(&self) -> usize {
321        self.debug.map_or(0, |d| d.dropped_upcall_count)
322    }
323    fn reset_dropped_upcall_count(&self) {
324        self.debug.map(|d| d.dropped_upcall_count = 0);
325    }
326
327    fn increment_timeslice_expiration_count(&self) {
328        self.debug.map(|d| d.timeslice_expiration_count += 1);
329    }
330    fn get_timeslice_expiration_count(&self) -> usize {
331        self.debug.map_or(0, |d| d.timeslice_expiration_count)
332    }
333    fn reset_timeslice_expiration_count(&self) {
334        self.debug.map(|d| d.timeslice_expiration_count = 0);
335    }
336}
337
338impl Default for ProcessStandardDebugFull {
339    fn default() -> Self {
340        Self {
341            debug: MapCell::new(ProcessStandardDebugFullInner::default()),
342        }
343    }
344}
345
346impl ProcessStandardDebug for () {
347    fn set_fixed_address_flash(&self, _address: u32) {}
348    fn get_fixed_address_flash(&self) -> Option<u32> {
349        None
350    }
351    fn set_fixed_address_ram(&self, _address: u32) {}
352    fn get_fixed_address_ram(&self) -> Option<u32> {
353        None
354    }
355    fn set_app_heap_start_pointer(&self, _ptr: *const u8) {}
356    fn get_app_heap_start_pointer(&self) -> Option<*const u8> {
357        None
358    }
359    fn set_app_stack_start_pointer(&self, _ptr: *const u8) {}
360    fn get_app_stack_start_pointer(&self) -> Option<*const u8> {
361        None
362    }
363    fn set_app_stack_min_pointer(&self, _ptr: *const u8) {}
364    fn get_app_stack_min_pointer(&self) -> Option<*const u8> {
365        None
366    }
367    fn set_new_app_stack_min_pointer(&self, _ptr: *const u8) {}
368
369    fn set_last_syscall(&self, _syscall: Syscall) {}
370    fn get_last_syscall(&self) -> Option<Syscall> {
371        None
372    }
373    fn reset_last_syscall(&self) {}
374
375    fn increment_syscall_count(&self) {}
376    fn get_syscall_count(&self) -> usize {
377        0
378    }
379    fn reset_syscall_count(&self) {}
380    fn increment_dropped_upcall_count(&self) {}
381    fn get_dropped_upcall_count(&self) -> usize {
382        0
383    }
384    fn reset_dropped_upcall_count(&self) {}
385    fn increment_timeslice_expiration_count(&self) {}
386    fn get_timeslice_expiration_count(&self) -> usize {
387        0
388    }
389    fn reset_timeslice_expiration_count(&self) {}
390}
391
392/// Entry that is stored in the grant pointer table at the top of process
393/// memory.
394///
395/// One copy of this entry struct is stored per grant region defined in the
396/// kernel. This type allows the core kernel to lookup a grant based on the
397/// driver_num associated with the grant, and also holds the pointer to the
398/// memory allocated for the particular grant.
399#[repr(C)]
400struct GrantPointerEntry {
401    /// The syscall driver number associated with the allocated grant.
402    ///
403    /// This defaults to 0 if the grant has not been allocated. Note, however,
404    /// that 0 is a valid driver_num, and therefore cannot be used to check if a
405    /// grant is allocated or not.
406    driver_num: usize,
407
408    /// The start of the memory location where the grant has been allocated, or
409    /// null if the grant has not been allocated.
410    grant_ptr: *mut u8,
411}
412
413/// A type for userspace processes in Tock.
414///
415/// As its name implies, this is the standard implementation for Tock processes
416/// that exposes the full support for processes running on embedded hardware.
417///
418/// [`ProcessStandard`] is templated on two parameters:
419///
420/// - `C`: [`Chip`]: The implementation must know the [`Chip`] the kernel is
421///   running on to properly store architecture-specific and MPU state for the
422///   process.
423/// - `D`: [`ProcessStandardDebug`]: This configures the debugging mechanism the
424///   process uses for storing optional debugging data. Kernels that do not wish
425///   to store per-process debugging state can use the `()` type for this
426///   parameter.
427pub struct ProcessStandard<'a, C: 'static + Chip, D: 'static + ProcessStandardDebug + Default> {
428    /// Identifier of this process and the index of the process in the process
429    /// table.
430    process_id: Cell<ProcessId>,
431
432    /// An application ShortId, generated from process loading and
433    /// checking, which denotes the security identity of this process.
434    app_id: ShortId,
435
436    /// Pointer to the main Kernel struct.
437    kernel: &'static Kernel,
438
439    /// Pointer to the struct that defines the actual chip the kernel is running
440    /// on. This is used because processes have subtle hardware-based
441    /// differences. Specifically, the actual syscall interface and how
442    /// processes are switched to is architecture-specific, and how memory must
443    /// be allocated for memory protection units is also hardware-specific.
444    chip: &'static C,
445
446    /// Application memory layout:
447    ///
448    /// ```text
449    ///     ╒════════ ← memory_start + memory_len
450    ///  ╔═ │ Grant Pointers
451    ///  ║  │ ──────
452    ///  ║  │ Upcall Queue
453    ///  ║  │ ──────
454    ///     │ Process Control Block
455    ///  D  │ ──────
456    ///  Y  │ Grant Regions
457    ///  N  │
458    ///  A  │   ↓
459    ///  M  │ ──────  ← kernel_memory_break
460    ///  I  │
461    ///  C  │ ──────  ← app_break               ═╗
462    ///     │                                    ║
463    ///  ║  │   ↑                                  A
464    ///  ║  │  Heap                              P C
465    ///  ╠═ │ ──────  ← app_heap_start           R C
466    ///     │  Data                              O E
467    ///  F  │ ──────  ← data_start_pointer       C S
468    ///  I  │ Stack                              E S
469    ///  X  │   ↓                                S I
470    ///  E  │                                    S B
471    ///  D  │ ──────  ← current_stack_pointer      L
472    ///     │                                    ║ E
473    ///  ╚═ ╘════════ ← memory_start            ═╝
474    /// ```
475    ///
476    /// The start of process memory. We store this as a pointer and length and
477    /// not a slice due to Rust aliasing rules. If we were to store a slice,
478    /// then any time another slice to the same memory or an ProcessBuffer is
479    /// used in the kernel would be undefined behavior.
480    memory_start: *const u8,
481    /// Number of bytes of memory allocated to this process.
482    memory_len: usize,
483
484    /// Reference to the slice of `GrantPointerEntry`s stored in the process's
485    /// memory reserved for the kernel. These driver numbers are zero and
486    /// pointers are null if the grant region has not been allocated. When the
487    /// grant region is allocated these pointers are updated to point to the
488    /// allocated memory and the driver number is set to match the driver that
489    /// owns the grant. No other reference to these pointers exists in the Tock
490    /// kernel.
491    grant_pointers: MapCell<&'static mut [GrantPointerEntry]>,
492
493    /// Pointer to the end of the allocated (and MPU protected) grant region.
494    kernel_memory_break: Cell<*const u8>,
495
496    /// Pointer to the end of process RAM that has been sbrk'd to the process.
497    app_break: Cell<*const u8>,
498
499    /// Pointer to high water mark for process buffers shared through `allow`
500    allow_high_water_mark: Cell<*const u8>,
501
502    /// Process flash segment. This is the region of nonvolatile flash that
503    /// the process occupies.
504    flash: &'static [u8],
505
506    /// The footers of the process binary (may be zero-sized), which are metadata
507    /// about the process not covered by integrity. Used, among other things, to
508    /// store signatures.
509    footers: &'static [u8],
510
511    /// Collection of pointers to the TBF header in flash.
512    header: tock_tbf::types::TbfHeader<'static>,
513
514    /// Credential that was approved for this process, or `None` if the
515    /// credential was permitted to run without an accepted credential.
516    credential: Option<AcceptedCredential>,
517
518    /// State saved on behalf of the process each time the app switches to the
519    /// kernel.
520    stored_state:
521        MapCell<<<C as Chip>::UserspaceKernelBoundary as UserspaceKernelBoundary>::StoredState>,
522
523    /// The current state of the app. The scheduler uses this to determine
524    /// whether it can schedule this app to execute.
525    ///
526    /// The `state` is used both for bookkeeping for the scheduler as well as
527    /// for enabling control by other parts of the system. The scheduler keeps
528    /// track of if a process is ready to run or not by switching between the
529    /// `Running` and `Yielded` states. The system can control the process by
530    /// switching it to a "stopped" state to prevent the scheduler from
531    /// scheduling it.
532    state: Cell<State>,
533
534    /// How to respond if this process faults.
535    fault_policy: &'a dyn ProcessFaultPolicy,
536
537    /// Storage permissions for this process.
538    ///
539    /// This is stored in a `Cell` because we need to create the
540    /// [`ProcessStandard`] first to then later determine the storage
541    /// permissions.
542    storage_permissions: Cell<StoragePermissions>,
543
544    /// Configuration data for the MPU
545    mpu_config: MapCell<<<C as Chip>::MPU as MPU>::MpuConfig>,
546
547    /// MPU regions are saved as a pointer-size pair.
548    mpu_regions: [Cell<Option<mpu::Region>>; 6],
549
550    /// Essentially a list of upcalls that want to call functions in the
551    /// process.
552    tasks: MapCell<RingBuffer<'a, Task>>,
553
554    /// Count of how many times this process has entered the fault condition and
555    /// been restarted. This is used by some `ProcessRestartPolicy`s to
556    /// determine if the process should be restarted or not.
557    restart_count: Cell<usize>,
558
559    /// The completion code set by the process when it last exited, restarted,
560    /// or was terminated. If the process is has never terminated, then the
561    /// `OptionalCell` will be empty (i.e. `None`). If the process has exited,
562    /// restarted, or terminated, the `OptionalCell` will contain an optional 32
563    /// bit value. The option will be `None` if the process crashed or was
564    /// stopped by the kernel and there is no provided completion code. If the
565    /// process called the exit syscall then the provided completion code will
566    /// be stored as `Some(completion code)`.
567    completion_code: OptionalCell<Option<u32>>,
568
569    /// Flag that stores whether this process has a task that is ready when
570    /// the process is in the [`State::YieldedFor`] state.
571    is_yield_wait_for_ready: Cell<bool>,
572
573    /// Values kept so that we can print useful debug messages when apps fault.
574    debug: D,
575}
576
577impl<C: Chip, D: 'static + ProcessStandardDebug> Process for ProcessStandard<'_, C, D> {
578    fn processid(&self) -> ProcessId {
579        self.process_id.get()
580    }
581
582    fn short_app_id(&self) -> ShortId {
583        self.app_id
584    }
585
586    fn binary_version(&self) -> Option<BinaryVersion> {
587        let version = self.header.get_binary_version();
588        match NonZeroU32::new(version) {
589            Some(version_nonzero) => Some(BinaryVersion::new(version_nonzero)),
590            None => None,
591        }
592    }
593
594    fn get_credential(&self) -> Option<AcceptedCredential> {
595        self.credential
596    }
597
598    fn enqueue_task(&self, task: Task) -> Result<(), ErrorCode> {
599        // If this app is in a `Fault` state then we shouldn't schedule
600        // any work for it.
601        if !self.is_running() {
602            return Err(ErrorCode::NODEVICE);
603        }
604
605        let ret = self.tasks.map_or(Err(ErrorCode::FAIL), |tasks| {
606            match tasks.enqueue(task) {
607                true => {
608                    let opt_this_upcall_id = match task {
609                        Task::FunctionCall(FunctionCall {
610                            source: FunctionCallSource::Driver(upcall_id),
611                            ..
612                        }) => Some(upcall_id),
613                        Task::ReturnValue(ReturnArguments { upcall_id, .. }) => Some(upcall_id),
614                        _ => None,
615                    };
616
617                    // If the process is yielded-for this task, set the ready flag.
618                    //
619                    // In case the process is yielding for another upcall, don't
620                    // clear the flag; this would re-introduce the race
621                    // condition of #5195.
622                    if let State::YieldedFor(yielded_upcall_id) = self.state.get()
623                        && let Some(this_upcall_id) = opt_this_upcall_id
624                        && yielded_upcall_id == this_upcall_id
625                    {
626                        self.is_yield_wait_for_ready.set(true);
627                    }
628
629                    // The task has been successfully enqueued.
630                    Ok(())
631                }
632                false => {
633                    // The task could not be enqueued as there is
634                    // insufficient space in the ring buffer.
635                    Err(ErrorCode::NOMEM)
636                }
637            }
638        });
639
640        if ret.is_err() {
641            // On any error we were unable to enqueue the task. Record the
642            // error, but importantly do _not_ increment kernel work.
643            self.debug.increment_dropped_upcall_count();
644        }
645
646        ret
647    }
648
649    fn ready(&self) -> bool {
650        match self.state.get() {
651            State::Running => true,
652            State::YieldedFor(_) => self.is_yield_wait_for_ready.get(),
653            State::Yielded => self.tasks.map_or(false, |ring_buf| ring_buf.has_elements()),
654            _ => false,
655        }
656    }
657
658    fn remove_pending_upcalls(&self, upcall_id: UpcallId) -> usize {
659        self.tasks.map_or(0, |tasks| {
660            let count_before = tasks.len();
661            tasks.retain(|task| match task {
662                // Remove only tasks that are function calls with an id equal
663                // to `upcall_id`.
664                Task::FunctionCall(function_call) => match function_call.source {
665                    FunctionCallSource::Kernel => true,
666                    FunctionCallSource::Driver(id) => id != upcall_id,
667                },
668                _ => true,
669            });
670            let count_after = tasks.len();
671            if config::CONFIG.trace_syscalls {
672                debug!(
673                    "[{:?}] remove_pending_upcalls[{:#x}:{}] = {} upcall(s) removed",
674                    self.processid(),
675                    upcall_id.driver_num,
676                    upcall_id.subscribe_num,
677                    count_before - count_after,
678                );
679            }
680            count_before - count_after
681        })
682    }
683
684    fn is_running(&self) -> bool {
685        match self.state.get() {
686            State::Running | State::Yielded | State::YieldedFor(_) | State::Stopped(_) => true,
687            _ => false,
688        }
689    }
690
691    fn get_state(&self) -> State {
692        self.state.get()
693    }
694
695    fn set_yielded_state(&self) {
696        if self.state.get() == State::Running {
697            self.state.set(State::Yielded);
698        }
699    }
700
701    fn set_yielded_for_state(&self, upcall_id: UpcallId) {
702        if self.state.get() == State::Running
703            || self.state.get() == State::Stopped(StoppedState::YieldedFor(upcall_id))
704        {
705            self.state.set(State::YieldedFor(upcall_id));
706
707            // Verify if the process has a task that this yield waits for
708            self.is_yield_wait_for_ready
709                .set(self.tasks.map_or(false, |tasks| {
710                    tasks
711                        .find_first_matching(|task| match task {
712                            Task::ReturnValue(ReturnArguments { upcall_id: id, .. }) => {
713                                upcall_id == *id
714                            }
715                            Task::FunctionCall(FunctionCall {
716                                source: FunctionCallSource::Driver(id),
717                                ..
718                            }) => upcall_id == *id,
719                            _ => false,
720                        })
721                        .is_some()
722                }));
723        }
724    }
725
726    fn stop(&self) {
727        match self.state.get() {
728            State::Running => self.state.set(State::Stopped(StoppedState::Running)),
729            State::Yielded => self.state.set(State::Stopped(StoppedState::Yielded)),
730            State::YieldedFor(upcall_id) => self
731                .state
732                .set(State::Stopped(StoppedState::YieldedFor(upcall_id))),
733            State::Stopped(_stopped_state) => {
734                // Already stopped, nothing to do.
735            }
736            State::Faulted | State::Terminated => {
737                // Stop has no meaning on a inactive process.
738            }
739        }
740    }
741
742    fn resume(&self) {
743        if let State::Stopped(stopped_state) = self.state.get() {
744            match stopped_state {
745                StoppedState::Running => self.state.set(State::Running),
746                StoppedState::Yielded => self.state.set(State::Yielded),
747                StoppedState::YieldedFor(upcall_id) => self.set_yielded_for_state(upcall_id),
748            }
749        }
750    }
751
752    fn set_fault_state(&self) {
753        // Use the per-process fault policy to determine what action the kernel
754        // should take since the process faulted.
755        let action = self.fault_policy.action(self);
756        match action {
757            FaultAction::Panic => {
758                // process faulted. Panic and print status
759                self.state.set(State::Faulted);
760                panic!("Process {} had a fault", self.get_process_name());
761            }
762            FaultAction::Restart => {
763                self.try_restart(None);
764            }
765            FaultAction::Stop => {
766                // This looks a lot like restart, except we just leave the app
767                // how it faulted and mark it as `Faulted`. By clearing
768                // all of the app's todo work it will not be scheduled, and
769                // clearing all of the grant regions will cause capsules to drop
770                // this app as well.
771                self.terminate(None);
772                self.state.set(State::Faulted);
773            }
774        }
775    }
776
777    fn start(&self, _cap: &dyn crate::capabilities::ProcessStartCapability) {
778        // `start()` can only be called on a terminated process.
779        if self.get_state() != State::Terminated {
780            return;
781        }
782
783        // Reset to start the process.
784        if let Ok(()) = self.reset() {
785            self.state.set(State::Yielded);
786        }
787    }
788
789    fn try_restart(&self, completion_code: Option<u32>) {
790        // `try_restart()` cannot be called if the process is terminated. Only
791        // `start()` can start a terminated process.
792        if self.get_state() == State::Terminated {
793            return;
794        }
795
796        // Terminate the process, freeing its state and removing any
797        // pending tasks from the scheduler's queue.
798        self.terminate(completion_code);
799
800        // If there is a kernel policy that controls restarts, it should be
801        // implemented here. For now, always restart.
802        if let Ok(()) = self.reset() {
803            self.state.set(State::Yielded);
804        }
805
806        // Decide what to do with res later. E.g., if we can't restart
807        // want to reclaim the process resources.
808    }
809
810    fn terminate(&self, completion_code: Option<u32>) {
811        // A process can be terminated if it is running or in the `Faulted`
812        // state. Otherwise, you cannot terminate it and this method return
813        // early.
814        //
815        // The kernel can terminate in the `Faulted` state to return the process
816        // to a state in which it can run again (e.g., reset it).
817        if !self.is_running() && self.get_state() != State::Faulted {
818            return;
819        }
820
821        // And remove those tasks
822        self.tasks.map(|tasks| {
823            tasks.empty();
824        });
825
826        // Clear any grant regions this app has setup with any capsules by
827        // setting all `grant_ptr`s to NULL.
828        self.grant_pointers.map(|grant_pointers| {
829            for grant_entry in grant_pointers.iter_mut() {
830                grant_entry.driver_num = 0;
831                grant_entry.grant_ptr = ptr::null_mut();
832            }
833        });
834
835        // Save the completion code.
836        self.completion_code.set(completion_code);
837
838        // Mark the app as stopped so the scheduler won't try to run it.
839        self.state.set(State::Terminated);
840    }
841
842    fn get_restart_count(&self) -> usize {
843        self.restart_count.get()
844    }
845
846    fn has_tasks(&self) -> bool {
847        self.tasks.map_or(false, |tasks| tasks.has_elements())
848    }
849
850    fn dequeue_task(&self) -> Option<Task> {
851        self.tasks.map_or(None, |tasks| tasks.dequeue())
852    }
853
854    fn remove_upcall(&self, upcall_id: UpcallId) -> Option<Task> {
855        self.tasks.map_or(None, |tasks| {
856            tasks.remove_first_matching(|task| match task {
857                Task::FunctionCall(fc) => match fc.source {
858                    FunctionCallSource::Driver(upid) => upid == upcall_id,
859                    _ => false,
860                },
861                Task::ReturnValue(rv) => rv.upcall_id == upcall_id,
862                Task::IPC(_) => false,
863            })
864        })
865    }
866
867    fn pending_tasks(&self) -> usize {
868        self.tasks.map_or(0, |tasks| tasks.len())
869    }
870
871    fn get_command_permissions(&self, driver_num: usize, offset: usize) -> CommandPermissions {
872        self.header.get_command_permissions(driver_num, offset)
873    }
874
875    fn get_storage_permissions(&self) -> StoragePermissions {
876        self.storage_permissions.get()
877    }
878
879    fn number_writeable_flash_regions(&self) -> usize {
880        self.header.number_writeable_flash_regions()
881    }
882
883    fn get_writeable_flash_region(&self, region_index: usize) -> (usize, usize) {
884        self.header.get_writeable_flash_region(region_index)
885    }
886
887    fn update_stack_start_pointer(&self, stack_pointer: *const u8) {
888        if stack_pointer >= self.mem_start() && stack_pointer < self.mem_end() {
889            self.debug.set_app_stack_start_pointer(stack_pointer);
890            // We also reset the minimum stack pointer because whatever
891            // value we had could be entirely wrong by now.
892            self.debug.set_app_stack_min_pointer(stack_pointer);
893        }
894    }
895
896    fn update_heap_start_pointer(&self, heap_pointer: *const u8) {
897        if heap_pointer >= self.mem_start() && heap_pointer < self.mem_end() {
898            self.debug.set_app_heap_start_pointer(heap_pointer);
899        }
900    }
901
902    fn setup_mpu(&self) {
903        self.mpu_config.map(|config| {
904            // SAFETY: `configure_mpu` is unsafe, as invoking it with an incorrect
905            // configuration can allow an untrusted application to access
906            // kernel-private memory.
907            //
908            // This call is safe given we trust that the implementation of
909            // `ProcessStandard` correctly provisions a set of MPU regions that
910            // does not grant access to any kernel-private memory, and
911            // `ProcessStandard` does not provide safe, publicly accessible
912            // APIs to add other arbitrary MPU regions to this configuration.
913            unsafe {
914                self.chip.mpu().configure_mpu(config);
915            }
916        });
917    }
918
919    fn add_mpu_region(
920        &self,
921        unallocated_memory_start: *const u8,
922        unallocated_memory_size: usize,
923        min_region_size: usize,
924    ) -> Option<mpu::Region> {
925        self.mpu_config.and_then(|config| {
926            let new_region = self.chip.mpu().allocate_region(
927                unallocated_memory_start,
928                unallocated_memory_size,
929                min_region_size,
930                mpu::Permissions::ReadWriteOnly,
931                config,
932            )?;
933
934            for region in self.mpu_regions.iter() {
935                if region.get().is_none() {
936                    region.set(Some(new_region));
937                    return Some(new_region);
938                }
939            }
940
941            // if we get here, the region was set in the `mpu_config`, but there was
942            // no free region left in `mpu_regions`
943            let _ = self.chip.mpu().remove_memory_region(new_region, config);
944
945            // Not enough room in Process struct to store the MPU region.
946            None
947        })
948    }
949
950    fn remove_mpu_region(&self, region: mpu::Region) -> Result<(), ErrorCode> {
951        self.mpu_config.map_or(Err(ErrorCode::INVAL), |config| {
952            // Find the existing mpu region that we are removing; it needs to match exactly.
953            if let Some(internal_region) = self.mpu_regions.iter().find(|r| r.get() == Some(region))
954            {
955                self.chip
956                    .mpu()
957                    .remove_memory_region(region, config)
958                    .or(Err(ErrorCode::FAIL))?;
959
960                // Remove this region from the tracking cache of mpu_regions
961                internal_region.set(None);
962                Ok(())
963            } else {
964                Err(ErrorCode::INVAL)
965            }
966        })
967    }
968
969    fn sbrk(&self, increment: isize) -> Result<CapabilityPtr, Error> {
970        // Do not modify an inactive process.
971        if !self.is_running() {
972            return Err(Error::InactiveApp);
973        }
974
975        let new_break = self.app_break.get().wrapping_offset(increment);
976        self.brk(new_break)
977    }
978
979    fn brk(&self, new_break: *const u8) -> Result<CapabilityPtr, Error> {
980        // Do not modify an inactive process.
981        if !self.is_running() {
982            return Err(Error::InactiveApp);
983        }
984
985        self.mpu_config.map_or(Err(Error::KernelError), |config| {
986            if new_break < self.allow_high_water_mark.get() || new_break >= self.mem_end() {
987                Err(Error::AddressOutOfBounds)
988            } else if new_break > self.kernel_memory_break.get() {
989                Err(Error::OutOfMemory)
990            } else if let Err(()) = self.chip.mpu().update_app_memory_region(
991                new_break,
992                self.kernel_memory_break.get(),
993                mpu::Permissions::ReadWriteOnly,
994                config,
995            ) {
996                Err(Error::OutOfMemory)
997            } else {
998                let old_break: *const u8 = self.app_break.get();
999                self.app_break.set(new_break);
1000
1001                // SAFETY: `configure_mpu` is unsafe, as invoking it with an incorrect
1002                // configuration can allow an untrusted application to access
1003                // kernel-private memory.
1004                //
1005                // This call is safe given we trust that the implementation of
1006                // `ProcessStandard` correctly provisions a set of MPU regions
1007                // that does not grant access to any kernel-private memory, and
1008                // `ProcessStandard` does not provide safe, publicly
1009                // accessible APIs to add other arbitrary MPU regions to this
1010                // configuration.
1011                unsafe {
1012                    self.chip.mpu().configure_mpu(config);
1013                }
1014
1015                if new_break > old_break {
1016                    // We need to initialize (zero) the newly accessible memory
1017                    // region at `[old_break; new_break)`. This serves two
1018                    // purposes:
1019                    //
1020                    // 1. It prevents a process from accessing any information
1021                    //    still contained in this memory from prior kernel
1022                    //    instances or processes.
1023                    //
1024                    // 2. It satisfies Rust's requirements that all
1025                    //    dereferencable memory be properly initialized. This is
1026                    //    important, as we'll be creating references into this
1027                    //    process-accessible memory region through the process
1028                    //    buffer infrastructure.
1029                    let old_break_mut_ptr: *mut u8 = old_break.cast_mut();
1030                    // SAFETY: We know this will write to only process-accessible memory
1031                    // that has never been used to create any kernel data structures
1032                    // because of the checks at the beginning of this function. We also
1033                    // know this is valid memory to write to because we checked the
1034                    // new_break is within process memory. Because we are using `u8`, we
1035                    // know `old_break_mut_ptr` is aligned. Since the process will have
1036                    // access to this memory we know the kernel will not try to use it
1037                    // for any data structures, avoiding any potential future memory
1038                    // initialization error.
1039                    unsafe {
1040                        core::ptr::write_bytes(
1041                            old_break_mut_ptr,
1042                            // Set the newly app-accessible memory to `0`:
1043                            0_u8,
1044                            new_break.addr() - old_break.addr(),
1045                        );
1046                    }
1047                }
1048
1049                let base = self.mem_start() as usize;
1050                let old_break_unit_ptr: *const () = old_break.cast();
1051                // SAFETY: It must be safe for this process to access the
1052                // bounds+permission expressed here while assuming no other
1053                // protection mechanism is active.
1054                //  - A process should have Read+Write access to its memory.
1055                //  - The function has established [base, new_break) as the
1056                //    (new) valid bounds for process memory.
1057                //  - We grant only Read+Write permissions.
1058                //  - We only pass this pointer to this process.
1059                let break_result = unsafe {
1060                    CapabilityPtr::new_with_authority(
1061                        old_break_unit_ptr,
1062                        base,
1063                        (new_break as usize) - base,
1064                        CapabilityPtrPermissions::ReadWrite,
1065                    )
1066                };
1067
1068                Ok(break_result)
1069            }
1070        })
1071    }
1072
1073    #[allow(clippy::not_unsafe_ptr_arg_deref)]
1074    fn build_readwrite_process_buffer(
1075        &self,
1076        buf_start_addr: *mut u8,
1077        size: usize,
1078    ) -> Result<ReadWriteProcessBuffer, ErrorCode> {
1079        if !self.is_running() {
1080            // Do not operate on an inactive process
1081            return Err(ErrorCode::FAIL);
1082        }
1083
1084        // A process is allowed to pass any pointer if the buffer length is 0,
1085        // as to revoke kernel access to a memory region without granting access
1086        // to another one
1087        if size == 0 {
1088            // Clippy complains that we're dereferencing a pointer in a public
1089            // and safe function here. While we are not dereferencing the
1090            // pointer here, we pass it along to an unsafe function, which is as
1091            // dangerous (as it is likely to be dereferenced down the line).
1092            //
1093            // Relevant discussion:
1094            // https://github.com/rust-lang/rust-clippy/issues/3045
1095            //
1096            // It should be fine to ignore the lint here, as a buffer of length
1097            // 0 will never allow dereferencing any memory in a safe manner.
1098            //
1099            // SAFETY: We specify a zero-length buffer, so the implementation of
1100            // `ReadWriteProcessBuffer` will handle any safety issues.
1101            // Therefore, we can encapsulate the unsafe.
1102            Ok(unsafe { ReadWriteProcessBuffer::new(buf_start_addr, 0, self.processid()) })
1103        } else if self.in_app_owned_memory(buf_start_addr, size) {
1104            // TODO: Check for buffer aliasing here
1105
1106            // Valid buffer, we need to adjust the app's watermark
1107            // note: `in_app_owned_memory` ensures this offset does not wrap
1108            let buf_end_addr = buf_start_addr.wrapping_add(size);
1109            let new_water_mark = cmp::max(self.allow_high_water_mark.get(), buf_end_addr);
1110            self.allow_high_water_mark.set(new_water_mark);
1111
1112            // Clippy complains that we're dereferencing a pointer in a public
1113            // and safe function here. While we are not dereferencing the
1114            // pointer here, we pass it along to an unsafe function, which is as
1115            // dangerous (as it is likely to be dereferenced down the line).
1116            //
1117            // Relevant discussion:
1118            // https://github.com/rust-lang/rust-clippy/issues/3045
1119            //
1120            // It should be fine to ignore the lint here, as long as we make
1121            // sure that we're pointing towards userspace memory (verified using
1122            // `in_app_owned_memory`) and respect alignment and other
1123            // constraints of the Rust references created by
1124            // `ReadWriteProcessBuffer`.
1125            //
1126            // SAFETY: We encapsulate the unsafe here on the condition in the TODO
1127            // above, as we must ensure that this `ReadWriteProcessBuffer` will
1128            // be the only reference to this memory.
1129            Ok(unsafe { ReadWriteProcessBuffer::new(buf_start_addr, size, self.processid()) })
1130        } else {
1131            Err(ErrorCode::INVAL)
1132        }
1133    }
1134
1135    #[allow(clippy::not_unsafe_ptr_arg_deref)]
1136    fn build_readonly_process_buffer(
1137        &self,
1138        buf_start_addr: *const u8,
1139        size: usize,
1140    ) -> Result<ReadOnlyProcessBuffer, ErrorCode> {
1141        if !self.is_running() {
1142            // Do not operate on an inactive process
1143            return Err(ErrorCode::FAIL);
1144        }
1145
1146        // A process is allowed to pass any pointer if the buffer length is 0,
1147        // as to revoke kernel access to a memory region without granting access
1148        // to another one
1149        if size == 0 {
1150            // Clippy complains that we're dereferencing a pointer in a public
1151            // and safe function here. While we are not dereferencing the
1152            // pointer here, we pass it along to an unsafe function, which is as
1153            // dangerous (as it is likely to be dereferenced down the line).
1154            //
1155            // Relevant discussion:
1156            // https://github.com/rust-lang/rust-clippy/issues/3045
1157            //
1158            // It should be fine to ignore the lint here, as a buffer of length
1159            // 0 will never allow dereferencing any memory in a safe manner.
1160            //
1161            // SAFETY: We specify a zero-length buffer, so the implementation of
1162            // `ReadOnlyProcessBuffer` will handle any safety issues. Therefore,
1163            // we can encapsulate the unsafe.
1164            Ok(unsafe { ReadOnlyProcessBuffer::new(buf_start_addr, 0, self.processid()) })
1165        } else if self.in_app_owned_memory(buf_start_addr, size)
1166            || self.in_app_flash_memory(buf_start_addr, size)
1167        {
1168            // TODO: Check for buffer aliasing here
1169
1170            if self.in_app_owned_memory(buf_start_addr, size) {
1171                // Valid buffer, and since this is in read-write memory (i.e.
1172                // not flash), we need to adjust the process's watermark. Note:
1173                // `in_app_owned_memory()` ensures this offset does not wrap.
1174                let buf_end_addr = buf_start_addr.wrapping_add(size);
1175                let new_water_mark = cmp::max(self.allow_high_water_mark.get(), buf_end_addr);
1176                self.allow_high_water_mark.set(new_water_mark);
1177            }
1178
1179            // Clippy complains that we're dereferencing a pointer in a public
1180            // and safe function here. While we are not dereferencing the
1181            // pointer here, we pass it along to an unsafe function, which is as
1182            // dangerous (as it is likely to be dereferenced down the line).
1183            //
1184            // Relevant discussion:
1185            // https://github.com/rust-lang/rust-clippy/issues/3045
1186            //
1187            // It should be fine to ignore the lint here, as long as we make
1188            // sure that we're pointing towards userspace memory (verified using
1189            // `in_app_owned_memory` or `in_app_flash_memory`) and respect
1190            // alignment and other constraints of the Rust references created by
1191            // `ReadWriteProcessBuffer`.
1192            //
1193            // SAFETY: We encapsulate the unsafe here on the condition in the TODO
1194            // above, as we must ensure that this `ReadOnlyProcessBuffer` will
1195            // be the only reference to this memory.
1196            Ok(unsafe { ReadOnlyProcessBuffer::new(buf_start_addr, size, self.processid()) })
1197        } else {
1198            Err(ErrorCode::INVAL)
1199        }
1200    }
1201
1202    unsafe fn set_byte(&self, addr: *mut u8, value: u8) -> bool {
1203        if self.in_app_owned_memory(addr, 1) {
1204            // SAFETY: We verify that this will only write process-accessible memory,
1205            // but this can still be undefined behavior if something else holds
1206            // a reference to this memory. The caller must ensure nothing else
1207            // holds a reference to this memory.
1208            unsafe {
1209                *addr = value;
1210            }
1211            true
1212        } else {
1213            false
1214        }
1215    }
1216
1217    fn grant_is_allocated(&self, grant_num: usize) -> Option<bool> {
1218        // Do not modify an inactive process.
1219        if !self.is_running() {
1220            return None;
1221        }
1222
1223        // Update the grant pointer to the address of the new allocation.
1224        self.grant_pointers.map_or(None, |grant_pointers| {
1225            // Implement `grant_pointers[grant_num]` without a chance of a
1226            // panic.
1227            grant_pointers
1228                .get(grant_num)
1229                .map(|grant_entry| !grant_entry.grant_ptr.is_null())
1230        })
1231    }
1232
1233    fn allocate_grant(
1234        &self,
1235        grant_num: usize,
1236        driver_num: usize,
1237        size: usize,
1238        align: usize,
1239    ) -> Result<(), ()> {
1240        // Do not modify an inactive process.
1241        if !self.is_running() {
1242            return Err(());
1243        }
1244
1245        // Verify the grant_num is valid.
1246        if grant_num >= self.kernel.get_grant_count_and_finalize() {
1247            return Err(());
1248        }
1249
1250        // Verify that the grant is not already allocated. If the pointer is not
1251        // null then the grant is already allocated.
1252        if let Some(is_allocated) = self.grant_is_allocated(grant_num) {
1253            if is_allocated {
1254                return Err(());
1255            }
1256        }
1257
1258        // Verify that there is not already a grant allocated with the same
1259        // `driver_num`.
1260        let exists = self.grant_pointers.map_or(false, |grant_pointers| {
1261            // Check our list of grant pointers if the driver number is used.
1262            grant_pointers.iter().any(|grant_entry| {
1263                // Check if the grant is both allocated (its grant pointer is
1264                // non null) and the driver number matches.
1265                (!grant_entry.grant_ptr.is_null()) && grant_entry.driver_num == driver_num
1266            })
1267        });
1268        // If we find a match, then the `driver_num` must already be used and
1269        // the grant allocation fails.
1270        if exists {
1271            return Err(());
1272        }
1273
1274        // Use the shared grant allocator function to actually allocate memory.
1275        // Returns `None` if the allocation cannot be created.
1276        if let Some(grant_ptr) = self.allocate_in_grant_region_internal(size, align) {
1277            // Update the grant pointer to the address of the new allocation.
1278            self.grant_pointers.map_or(Err(()), |grant_pointers| {
1279                // Implement `grant_pointers[grant_num] = grant_ptr` without a
1280                // chance of a panic.
1281                grant_pointers
1282                    .get_mut(grant_num)
1283                    .map_or(Err(()), |grant_entry| {
1284                        // Actually set the driver num and grant pointer.
1285                        grant_entry.driver_num = driver_num;
1286                        grant_entry.grant_ptr = grant_ptr.as_ptr();
1287
1288                        // If all of this worked, return true.
1289                        Ok(())
1290                    })
1291            })
1292        } else {
1293            // Could not allocate the memory for the grant region.
1294            Err(())
1295        }
1296    }
1297
1298    fn allocate_custom_grant(
1299        &self,
1300        size: usize,
1301        align: usize,
1302    ) -> Result<(ProcessCustomGrantIdentifier, NonNull<u8>), ()> {
1303        // Do not modify an inactive process.
1304        if !self.is_running() {
1305            return Err(());
1306        }
1307
1308        // Use the shared grant allocator function to actually allocate memory.
1309        // Returns `None` if the allocation cannot be created.
1310        if let Some(ptr) = self.allocate_in_grant_region_internal(size, align) {
1311            // Create the identifier that the caller will use to get access to
1312            // this custom grant in the future.
1313            let identifier = self.create_custom_grant_identifier(ptr);
1314
1315            Ok((identifier, ptr))
1316        } else {
1317            // Could not allocate memory for the custom grant.
1318            Err(())
1319        }
1320    }
1321
1322    fn enter_grant(&self, grant_num: usize) -> Result<NonNull<u8>, Error> {
1323        // Do not try to access the grant region of an inactive process.
1324        if !self.is_running() {
1325            return Err(Error::InactiveApp);
1326        }
1327
1328        // Retrieve the grant pointer from the `grant_pointers` slice. We use
1329        // `[slice].get()` so that if the grant number is invalid this will
1330        // return `Err` and not panic.
1331        self.grant_pointers
1332            .map_or(Err(Error::KernelError), |grant_pointers| {
1333                // Implement `grant_pointers[grant_num]` without a chance of a
1334                // panic.
1335                match grant_pointers.get_mut(grant_num) {
1336                    Some(grant_entry) => {
1337                        // Check if this is entering a valid grant that has been created and
1338                        // initialized. If the grant is not valid then the `grant_ptr` will
1339                        // be null.
1340                        if let Some(grant_ptr_nonnull) = NonNull::new(grant_entry.grant_ptr) {
1341                            // Check if the grant pointer is marked that the grant has already
1342                            // been entered. If so, return an error.
1343                            if (usize::from(grant_ptr_nonnull.addr())) & 0x1 == 0x1 {
1344                                // Lowest bit is one, meaning this grant has been entered.
1345                                Err(Error::AlreadyInUse)
1346                            } else {
1347                                // Now, to mark that the grant has been entered, we set the lowest
1348                                // bit to one and save this as the grant pointer.
1349                                grant_entry.grant_ptr =
1350                                    grant_ptr_nonnull.map_addr(|a| a | 0x1).as_ptr();
1351
1352                                // And we return the grant pointer to the entered grant.
1353                                Ok(grant_ptr_nonnull)
1354                            }
1355                        } else {
1356                            // The grant has not been created and is not valid to enter.
1357                            Err(Error::OutOfMemory)
1358                        }
1359                    }
1360                    None => Err(Error::AddressOutOfBounds),
1361                }
1362            })
1363    }
1364
1365    fn enter_custom_grant(
1366        &self,
1367        identifier: ProcessCustomGrantIdentifier,
1368    ) -> Result<*mut u8, Error> {
1369        // Do not try to access the grant region of an inactive process.
1370        if !self.is_running() {
1371            return Err(Error::InactiveApp);
1372        }
1373
1374        // Get the address of the custom grant based on the identifier.
1375        let address = self.get_custom_grant_address(identifier);
1376
1377        // We never deallocate custom grants and only we can change the
1378        // `identifier` so we know this is a valid address for the custom grant.
1379        // kernel_memory_break seems like the most reasonable pointer to get the
1380        // provenance from.
1381        Ok(self.kernel_memory_break().with_addr(address).cast_mut())
1382    }
1383
1384    unsafe fn leave_grant(&self, grant_num: usize) {
1385        // Do not modify an inactive process.
1386        if !self.is_running() {
1387            return;
1388        }
1389
1390        self.grant_pointers.map(|grant_pointers| {
1391            // Implement `grant_pointers[grant_num]` without a chance of a
1392            // panic.
1393            if let Some(grant_entry) = grant_pointers.get_mut(grant_num) {
1394                // Get a copy of the actual grant pointer.
1395                let grant_ptr = grant_entry.grant_ptr;
1396
1397                // Now, to mark that the grant has been released, we set the
1398                // lowest bit back to zero and save this as the grant
1399                // pointer.
1400                grant_entry.grant_ptr = grant_ptr.map_addr(|a| a & !0x1);
1401            }
1402        });
1403    }
1404
1405    fn grant_allocated_count(&self) -> Option<usize> {
1406        // Do not modify an inactive process.
1407        if !self.is_running() {
1408            return None;
1409        }
1410
1411        self.grant_pointers.map(|grant_pointers| {
1412            // Filter our list of grant pointers into just the non-null ones,
1413            // and count those. A grant is allocated if its grant pointer is
1414            // non-null.
1415            grant_pointers
1416                .iter()
1417                .filter(|grant_entry| !grant_entry.grant_ptr.is_null())
1418                .count()
1419        })
1420    }
1421
1422    fn lookup_grant_from_driver_num(&self, driver_num: usize) -> Result<usize, Error> {
1423        self.grant_pointers
1424            .map_or(Err(Error::KernelError), |grant_pointers| {
1425                // Filter our list of grant pointers into just the non null
1426                // ones, and count those. A grant is allocated if its grant
1427                // pointer is non-null.
1428                match grant_pointers.iter().position(|grant_entry| {
1429                    // Only consider allocated grants.
1430                    (!grant_entry.grant_ptr.is_null()) && grant_entry.driver_num == driver_num
1431                }) {
1432                    Some(idx) => Ok(idx),
1433                    None => Err(Error::OutOfMemory),
1434                }
1435            })
1436    }
1437
1438    fn is_valid_upcall_function_pointer(&self, upcall_fn: *const ()) -> bool {
1439        let ptr: *const u8 = upcall_fn.cast();
1440        let size = mem::size_of::<*const u8>();
1441
1442        // It is okay if this function is in memory or flash.
1443        self.in_app_flash_memory(ptr, size) || self.in_app_owned_memory(ptr, size)
1444    }
1445
1446    fn get_process_name(&self) -> &'static str {
1447        self.header.get_package_name().unwrap_or("")
1448    }
1449
1450    fn get_completion_code(&self) -> Option<Option<u32>> {
1451        self.completion_code.get()
1452    }
1453
1454    fn set_syscall_return_value(&self, return_value: SyscallReturn) {
1455        match self.stored_state.map(|stored_state| {
1456            // Actually set the return value for a particular process.
1457            //
1458            // SAFETY: The UKB implementation uses the bounds of
1459            // process-accessible memory to verify that any memory changes are
1460            // valid. Here, the unsafe promise we are making is that the bounds
1461            // passed to the UKB are correct. Because we use the start of the
1462            // process's memory, and the current `app_break`, we know that the
1463            // memory in that range is accessible to the process.
1464            unsafe {
1465                self.chip
1466                    .userspace_kernel_boundary()
1467                    .set_syscall_return_value(
1468                        self.mem_start(),
1469                        self.app_break.get(),
1470                        stored_state,
1471                        return_value,
1472                    )
1473            }
1474        }) {
1475            Some(Ok(())) => {
1476                // If we get an `Ok` we are all set.
1477
1478                // The process is either already in the running state (having
1479                // just called a nonblocking syscall like command) or needs to
1480                // be moved to the running state having called Yield-WaitFor and
1481                // now needing to be resumed. Either way we can set the state to
1482                // running.
1483                self.state.set(State::Running);
1484                // The task is running, if it was yielded-for an upcall,
1485                // the upcall must have been scheduled, unset
1486                // the ready flag.
1487                self.is_yield_wait_for_ready.set(false);
1488            }
1489
1490            Some(Err(())) => {
1491                // If we get an `Err`, then the UKB implementation could not set
1492                // the return value, likely because the process's stack is no
1493                // longer accessible to it. All we can do is fault.
1494                self.set_fault_state();
1495            }
1496
1497            None => {
1498                // We should never be here since `stored_state` should always be
1499                // occupied.
1500                self.set_fault_state();
1501            }
1502        }
1503    }
1504
1505    fn set_process_function(&self, callback: FunctionCall) {
1506        // See if we can actually enqueue this function for this process.
1507        // Architecture-specific code handles actually doing this since the
1508        // exact method is both architecture- and implementation-specific.
1509        //
1510        // This can fail, for example if the process does not have enough memory
1511        // remaining.
1512        match self.stored_state.map(|stored_state| {
1513            // Let the UKB implementation handle setting the process's PC so
1514            // that the process executes the upcall function.
1515            //
1516            // SAFETY: We encapsulate unsafe here because we are guaranteeing
1517            // that the memory bounds passed to `set_process_function` are
1518            // correct. We know this because we use the start of process memory
1519            // and the current `app_break`, and that range is accessible to the
1520            // process.
1521            unsafe {
1522                self.chip.userspace_kernel_boundary().set_process_function(
1523                    self.mem_start(),
1524                    self.app_break.get(),
1525                    stored_state,
1526                    callback,
1527                )
1528            }
1529        }) {
1530            Some(Ok(())) => {
1531                // If we got an `Ok` we are all set and should mark that this
1532                // process is ready to be scheduled.
1533
1534                // Move this process to the "running" state so the scheduler
1535                // will schedule it.
1536                self.state.set(State::Running);
1537            }
1538
1539            Some(Err(())) => {
1540                // If we got an Error, then there was likely not enough room on
1541                // the stack to allow the process to execute this function given
1542                // the details of the particular architecture this is running
1543                // on. This process has essentially faulted, so we mark it as
1544                // such.
1545                self.set_fault_state();
1546            }
1547
1548            None => {
1549                // We should never be here since `stored_state` should always be
1550                // occupied.
1551                self.set_fault_state();
1552            }
1553        }
1554    }
1555
1556    unsafe fn switch_to(&self) -> Option<syscall::ContextSwitchReason> {
1557        // Cannot switch to an invalid process
1558        if !self.is_running() {
1559            return None;
1560        }
1561
1562        let (switch_reason, stack_pointer) =
1563            self.stored_state.map_or((None, None), |stored_state| {
1564                // Switch to the process.
1565                //
1566                // SAFETY: We guarantee that the memory pointers we pass are valid,
1567                // ensuring this context switch is safe. We know this because we use
1568                // the start of process memory and the current `app_break`, and that
1569                // range is accessible to the process. Therefore we encapsulate the
1570                // `unsafe`. Also, the safety requirements for `switch_to` ensure
1571                // the MPU is correctly configured.
1572                unsafe {
1573                    let (switch_reason, optional_stack_pointer) = self
1574                        .chip
1575                        .userspace_kernel_boundary()
1576                        .switch_to_process(self.mem_start(), self.app_break.get(), stored_state);
1577                    (Some(switch_reason), optional_stack_pointer)
1578                }
1579            });
1580
1581        // If the UKB implementation passed us a stack pointer, update our
1582        // debugging state. This is completely optional.
1583        if let Some(sp) = stack_pointer {
1584            self.debug.set_new_app_stack_min_pointer(sp);
1585        }
1586
1587        switch_reason
1588    }
1589
1590    fn debug_syscall_count(&self) -> usize {
1591        self.debug.get_syscall_count()
1592    }
1593
1594    fn debug_dropped_upcall_count(&self) -> usize {
1595        self.debug.get_dropped_upcall_count()
1596    }
1597
1598    fn debug_timeslice_expiration_count(&self) -> usize {
1599        self.debug.get_timeslice_expiration_count()
1600    }
1601
1602    fn debug_timeslice_expired(&self) {
1603        self.debug.increment_timeslice_expiration_count();
1604    }
1605
1606    fn debug_syscall_called(&self, last_syscall: Syscall) {
1607        self.debug.increment_syscall_count();
1608        self.debug.set_last_syscall(last_syscall);
1609    }
1610
1611    fn debug_syscall_last(&self) -> Option<Syscall> {
1612        self.debug.get_last_syscall()
1613    }
1614
1615    fn get_addresses(&self) -> ProcessAddresses {
1616        ProcessAddresses {
1617            flash_start: self.flash_start() as usize,
1618            flash_non_protected_start: self.flash_non_protected_start(),
1619            flash_integrity_end: self
1620                .flash
1621                .as_ptr()
1622                .wrapping_add(self.header.get_binary_end() as usize),
1623            flash_end: self.flash_end(),
1624            sram_start: self.mem_start() as usize,
1625            sram_app_brk: self.app_memory_break() as usize,
1626            sram_grant_start: self.kernel_memory_break() as usize,
1627            sram_end: self.mem_end() as usize,
1628            sram_heap_start: self.debug.get_app_heap_start_pointer().map(|p| p as usize),
1629            sram_stack_top: self.debug.get_app_stack_start_pointer().map(|p| p as usize),
1630            sram_stack_bottom: self.debug.get_app_stack_min_pointer().map(|p| p as usize),
1631        }
1632    }
1633
1634    fn get_sizes(&self) -> ProcessSizes {
1635        ProcessSizes {
1636            grant_pointers: mem::size_of::<GrantPointerEntry>()
1637                * self.kernel.get_grant_count_and_finalize(),
1638            upcall_list: Self::CALLBACKS_SIZE,
1639            process_control_block: Self::PROCESS_STRUCT_SIZE,
1640        }
1641    }
1642
1643    fn print_full_process(&self, writer: &mut dyn Write) {
1644        if !config::CONFIG.debug_panics {
1645            return;
1646        }
1647
1648        self.stored_state.map(|stored_state| {
1649            // SAFETY: We guarantee the memory bounds pointers provided to the
1650            // UKB are correct. We know this because we use the start of process
1651            // memory and the current `app_break`, and that range is accessible
1652            // to the process.
1653            unsafe {
1654                self.chip.userspace_kernel_boundary().print_context(
1655                    self.mem_start(),
1656                    self.app_break.get(),
1657                    stored_state,
1658                    writer,
1659                );
1660            }
1661        });
1662
1663        // Display grant information.
1664        let number_grants = self.kernel.get_grant_count_and_finalize();
1665        let _ = writer.write_fmt(format_args!(
1666            "\
1667            \r\n Total number of grant regions defined: {}\r\n",
1668            self.kernel.get_grant_count_and_finalize()
1669        ));
1670        let rows = number_grants.div_ceil(3);
1671
1672        // Access our array of grant pointers.
1673        self.grant_pointers.map(|grant_pointers| {
1674            // Iterate each grant and show its address.
1675            for i in 0..rows {
1676                for j in 0..3 {
1677                    let index = i + (rows * j);
1678                    if index >= number_grants {
1679                        break;
1680                    }
1681
1682                    // Implement `grant_pointers[grant_num]` without a chance of
1683                    // a panic.
1684                    grant_pointers.get(index).map(|grant_entry| {
1685                        if grant_entry.grant_ptr.is_null() {
1686                            let _ =
1687                                writer.write_fmt(format_args!("  Grant {:>2} : --        ", index));
1688                        } else {
1689                            let _ = writer.write_fmt(format_args!(
1690                                "  Grant {:>2} {:#x}: {:p}",
1691                                index, grant_entry.driver_num, grant_entry.grant_ptr
1692                            ));
1693                        }
1694                    });
1695                }
1696                let _ = writer.write_fmt(format_args!("\r\n"));
1697            }
1698        });
1699
1700        // Display the current state of the MPU for this process.
1701        self.mpu_config.map(|config| {
1702            let _ = writer.write_fmt(format_args!("{}", config));
1703        });
1704
1705        // Print a helpful message on how to re-compile a process to view the
1706        // listing file. If a process is PIC, then we also need to print the
1707        // actual addresses the process executed at so that the .lst file can be
1708        // generated for those addresses. If the process was already compiled
1709        // for a fixed address, then just generating a .lst file is fine.
1710
1711        if self.debug.get_fixed_address_flash().is_some() {
1712            // Fixed addresses, can just run `make lst`.
1713            let _ = writer.write_fmt(format_args!(
1714                "\
1715                    \r\nTo debug libtock-c apps, run `make lst` in the app's\
1716                    \r\nfolder and open the arch.{:#x}.{:#x}.lst file.\r\n\r\n",
1717                self.debug.get_fixed_address_flash().unwrap_or(0),
1718                self.debug.get_fixed_address_ram().unwrap_or(0)
1719            ));
1720        } else {
1721            // PIC, need to specify the addresses.
1722            let sram_start = self.mem_start() as usize;
1723            let flash_start = self.flash.as_ptr() as usize;
1724            let flash_init_fn = flash_start + self.header.get_init_function_offset() as usize;
1725
1726            let _ = writer.write_fmt(format_args!(
1727                "\
1728                    \r\nTo debug libtock-c apps, run\
1729                    \r\n`make debug RAM_START={:#x} FLASH_INIT={:#x}`\
1730                    \r\nin the app's folder and open the .lst file.\r\n\r\n",
1731                sram_start, flash_init_fn
1732            ));
1733        }
1734    }
1735
1736    fn get_stored_state(&self, out: &mut [u8]) -> Result<usize, ErrorCode> {
1737        self.stored_state
1738            .map(|stored_state| {
1739                self.chip
1740                    .userspace_kernel_boundary()
1741                    .store_context(stored_state, out)
1742            })
1743            .unwrap_or(Err(ErrorCode::FAIL))
1744    }
1745}
1746
1747impl<C: 'static + Chip, D: 'static + ProcessStandardDebug> ProcessStandard<'_, C, D> {
1748    /// Alignment requirement for each `GrantPointerEntry` in the grant pointers
1749    /// slice.
1750    const GRANT_POINTERS_ALIGNMENT: usize = mem::align_of::<GrantPointerEntry>();
1751
1752    /// Number of upcalls stored in the upcall ring buffer (10 element length).
1753    const CALLBACK_LEN: usize = 10;
1754    /// Size of the upcall storage buffer.
1755    ///
1756    /// As of June 2026, we cannot do
1757    ///
1758    /// ```ignore
1759    /// const CALLBACKS_SIZE usize = mem::size_of::<MaybeUninit<[Task; Self::CALLBACK_LEN]>>();
1760    /// ```
1761    ///
1762    /// because of the error:
1763    ///
1764    /// ```text
1765    /// error: generic `Self` types are currently not permitted in anonymous constants
1766    ///     --> kernel/src/process_standard.rs:1712:70
1767    ///      |
1768    /// 1712 |     const CALLBACKS_SIZE: usize = mem::size_of::<MaybeUninit<[Task; Self::CALLBACK_LEN]>>();
1769    ///      |                                                                      ^^^^
1770    ///      |
1771    /// ```
1772    const CALLBACKS_SIZE: usize = mem::size_of::<Task>() * Self::CALLBACK_LEN;
1773    /// Alignment requirement of the upcall storage buffer.
1774    const CALLBACKS_ALIGNMENT: usize = mem::align_of::<Task>();
1775
1776    // Memory offset to make room for this process's control block.
1777    const PROCESS_STRUCT_SIZE: usize = mem::size_of::<ProcessStandard<C, D>>();
1778    /// Alignment requirement for `ProcessStandard`.
1779    const PROCESS_STRUCT_ALIGNMENT: usize = mem::align_of::<ProcessStandard<C, D>>();
1780
1781    /// Create a `ProcessStandard` object based on the found `ProcessBinary`.
1782    ///
1783    /// # Safety
1784    ///
1785    /// This function allocates memory from `remaining_memory` for use by the
1786    /// process. There must not be any references to or other uses of
1787    /// `remaining_memory` when calling this function.
1788    pub(crate) unsafe fn create(
1789        kernel: &'static Kernel,
1790        chip: &'static C,
1791        pb: ProcessBinary,
1792        remaining_memory: *mut [u8],
1793        fault_policy: &'static dyn ProcessFaultPolicy,
1794        storage_permissions_policy: &'static dyn ProcessStandardStoragePermissionsPolicy<C, D>,
1795        app_id: ShortId,
1796        index: usize,
1797    ) -> Result<(Option<&'static dyn Process>, *mut [u8]), (ProcessLoadError, *mut [u8])> {
1798        let process_name = pb.header.get_package_name();
1799        let process_ram_requested_size = pb.header.get_minimum_app_ram_size() as usize;
1800
1801        // Initialize MPU region configuration.
1802        let mut mpu_config = match chip.mpu().new_config() {
1803            Some(mpu_config) => mpu_config,
1804            None => return Err((ProcessLoadError::MpuConfigurationError, remaining_memory)),
1805        };
1806
1807        // Allocate MPU region for flash.
1808        if chip
1809            .mpu()
1810            .allocate_region(
1811                pb.flash.as_ptr(),
1812                pb.flash.len(),
1813                pb.flash.len(),
1814                mpu::Permissions::ReadExecuteOnly,
1815                &mut mpu_config,
1816            )
1817            .is_none()
1818        {
1819            if config::CONFIG.debug_load_processes {
1820                debug!(
1821                    "[!] flash={:#010X}-{:#010X} process={:?} - couldn't allocate MPU region for flash",
1822                    pb.flash.as_ptr() as usize,
1823                    pb.flash.as_ptr() as usize + pb.flash.len() - 1,
1824                    process_name
1825                );
1826            }
1827            return Err((ProcessLoadError::MpuInvalidFlashLength, remaining_memory));
1828        }
1829
1830        // Determine how much space we need in the application's memory space
1831        // just for kernel and grant state. We need to make sure we allocate
1832        // enough memory just for that.
1833
1834        // Calculate how many bytes we need for grant pointers.
1835        let grant_ptr_size = mem::size_of::<GrantPointerEntry>();
1836        let grant_ptrs_num = kernel.get_grant_count_and_finalize();
1837        let grant_ptrs_size = grant_ptrs_num * grant_ptr_size;
1838
1839        // Initial size of the kernel-owned part of process memory can be
1840        // calculated directly based on the initial size of all kernel-owned
1841        // data structures.
1842        //
1843        // Add the alignment size of each data structure to handle the case
1844        // where the memory region starts at the worst possible address and we
1845        // need to add padding. Note: the maximum shift will only ever be one
1846        // less than the alignment size, but to avoid unusual addresses we just
1847        // use the full alignment.
1848        let initial_kernel_memory_size = grant_ptrs_size
1849            + Self::GRANT_POINTERS_ALIGNMENT
1850            + Self::CALLBACKS_SIZE
1851            + Self::CALLBACKS_ALIGNMENT
1852            + Self::PROCESS_STRUCT_SIZE
1853            + Self::PROCESS_STRUCT_ALIGNMENT;
1854
1855        // By default we start with the initial size of process-accessible
1856        // memory set to 0. This maximizes the flexibility that processes have
1857        // to allocate their memory as they see fit. If a process needs more
1858        // accessible memory it must use the `brk` memop syscalls to request
1859        // more memory.
1860        //
1861        // We must take into account any process-accessible memory required by
1862        // the context switching implementation and allocate at least that much
1863        // memory so that we can successfully switch to the process. This is
1864        // architecture and implementation specific, so we query that now.
1865        let min_process_memory_size = chip
1866            .userspace_kernel_boundary()
1867            .initial_process_app_brk_size();
1868
1869        // We have to ensure that we at least ask the MPU for
1870        // `min_process_memory_size` so that we can be sure that `app_brk` is
1871        // not set inside the kernel-owned memory region. Now, in practice,
1872        // processes should not request 0 (or very few) bytes of memory in their
1873        // TBF header (i.e. `process_ram_requested_size` will almost always be
1874        // much larger than `min_process_memory_size`), as they are unlikely to
1875        // work with essentially no available memory. But, we still must protect
1876        // for that case.
1877        let min_process_ram_size = cmp::max(process_ram_requested_size, min_process_memory_size);
1878
1879        // Minimum memory size for the process.
1880        let min_total_memory_size = min_process_ram_size + initial_kernel_memory_size;
1881
1882        // Check if this process requires a fixed memory start address. If so,
1883        // try to adjust the memory region to work for this process.
1884        //
1885        // Right now, we only support skipping some RAM and leaving a chunk
1886        // unused so that the memory region starts where the process needs it
1887        // to.
1888        let remaining_memory = if let Some(fixed_memory_start) = pb
1889            .header
1890            .get_fixed_address_ram()
1891            .map(|addr: u32| remaining_memory.cast::<u8>().with_addr(addr as usize))
1892        {
1893            // The process does have a fixed address.
1894            if fixed_memory_start == remaining_memory.cast() {
1895                // Address already matches.
1896                remaining_memory
1897            } else if fixed_memory_start > remaining_memory.cast() {
1898                // Process wants a memory address farther in memory. Try to
1899                // advance the memory region to make the address match.
1900                let diff = fixed_memory_start.addr() - remaining_memory.addr();
1901                if diff > remaining_memory.len() {
1902                    // We ran out of memory.
1903                    let actual_address = (remaining_memory.cast::<u8>())
1904                        .wrapping_byte_add(remaining_memory.len())
1905                        .wrapping_byte_sub(1);
1906                    let expected_address = fixed_memory_start;
1907                    return Err((
1908                        ProcessLoadError::MemoryAddressMismatch {
1909                            actual_address,
1910                            expected_address,
1911                        },
1912                        remaining_memory,
1913                    ));
1914                } else {
1915                    // Change the memory range to start where the process requested it.
1916                    // Because of the if statement above we know this should work. Doing
1917                    // it more cleanly would be good but was a bit beyond my borrow ken;
1918                    // calling get_mut has a mutable borrow.-pal
1919                    //
1920                    // SAFETY: `diff` must be within the `remaining_memory` slice. Because we
1921                    // check that `diff` is less than the length of `remaining_memory`
1922                    // we know diff will be within  `remaining_memory`.
1923                    let (_, sliced) = unsafe { raw_slice_split_at_mut(remaining_memory, diff) };
1924                    sliced
1925                }
1926            } else {
1927                // Address is earlier in memory, nothing we can do.
1928                let actual_address = remaining_memory.cast();
1929                let expected_address = fixed_memory_start;
1930                return Err((
1931                    ProcessLoadError::MemoryAddressMismatch {
1932                        actual_address,
1933                        expected_address,
1934                    },
1935                    remaining_memory,
1936                ));
1937            }
1938        } else {
1939            remaining_memory
1940        };
1941
1942        // Determine where process memory will go and allocate an MPU region.
1943        //
1944        // `[allocation_start, allocation_size)` will cover both
1945        //
1946        // - the app-owned `min_process_memory_size`-long part of memory (at
1947        //   some offset within `remaining_memory`), as well as
1948        //
1949        // - the kernel-owned allocation growing downward starting at the end
1950        //   of this allocation, `initial_kernel_memory_size` bytes long.
1951        //
1952        let (allocation_start, allocation_size) = match chip.mpu().allocate_app_memory_region(
1953            remaining_memory.cast(),
1954            remaining_memory.len(),
1955            min_total_memory_size,
1956            min_process_memory_size,
1957            initial_kernel_memory_size,
1958            mpu::Permissions::ReadWriteOnly,
1959            &mut mpu_config,
1960        ) {
1961            Some((memory_start, memory_size)) => (memory_start, memory_size),
1962            None => {
1963                // Failed to load process. Insufficient memory.
1964                if config::CONFIG.debug_load_processes {
1965                    debug!(
1966                        "[!] flash={:#010X}-{:#010X} process={:?} - couldn't allocate memory region of size >= {:#X}",
1967                        pb.flash.as_ptr() as usize,
1968                        pb.flash.as_ptr() as usize + pb.flash.len() - 1,
1969                        process_name,
1970                        min_total_memory_size
1971                    );
1972                }
1973                return Err((ProcessLoadError::NotEnoughMemory, remaining_memory));
1974            }
1975        };
1976
1977        // Determine the offset of the app-owned part of the above memory
1978        // allocation. An MPU may not place it at the very start of
1979        // `remaining_memory` for internal alignment constraints. This can only
1980        // overflow if the MPU implementation is incorrect; a compliant
1981        // implementation must return a memory allocation within the
1982        // `remaining_memory` slice.
1983        let app_memory_start_offset = allocation_start.addr() - remaining_memory.addr();
1984
1985        // Check if the memory region is valid for the process. If a process
1986        // included a fixed address for the start of RAM in its TBF header (this
1987        // field is optional, processes that are position independent do not
1988        // need a fixed address) then we check that we used the same address
1989        // when we allocated it in RAM.
1990        if let Some(fixed_memory_start) = pb
1991            .header
1992            .get_fixed_address_ram()
1993            .map(|addr: u32| remaining_memory.cast::<u8>().with_addr(addr as usize))
1994        {
1995            let actual_address = remaining_memory
1996                .cast::<u8>()
1997                .wrapping_byte_add(app_memory_start_offset);
1998            let expected_address = fixed_memory_start;
1999            if actual_address != expected_address {
2000                return Err((
2001                    ProcessLoadError::MemoryAddressMismatch {
2002                        actual_address,
2003                        expected_address,
2004                    },
2005                    remaining_memory,
2006                ));
2007            }
2008        }
2009
2010        // With our MPU allocation, we can begin to divide up the
2011        // `remaining_memory` slice into individual regions for the process and
2012        // kernel, as follows:
2013        //
2014        //
2015        //  ┌───────────────────────────────────────────────────────────────────────────────────────
2016        //  │ remaining_memory
2017        //  └───────────────────────────────────────────────────────────────────────────────────────
2018        //  ┆                                                                        ┆
2019        //  ┌────────────────────────────────────────────────────────────────────────┬──────────────
2020        //  │ allocated_padded_memory                                                │ unused_memory
2021        //  └────────────────────────────────────────────────────────────────────────┴──────────────
2022        //      ┆                                                                    ┆
2023        //      ┌────────────────────────────────────────────────────────────────────┐
2024        //  ┆←─→│ allocated_memory                                                   │
2025        //    ↑ └────────────────────────────────────────────────────────────────────┘
2026        //    └┄┄┄app_memory_start_offset                                            ┆
2027        //      ┌─────────────────────────┬──────────────────────────────────────────┐
2028        //      │ app_accessible_memory   │ allocated_kernel_memory                  │
2029        //      └─────────────────────────┴──────────────────────────────────────────┘
2030        //      ┆←min_process_memory_size→┆←────→┆←────initial_kernel_memory_size───→┆
2031        //                                ↑  ↑   ┆                                   ┆
2032        //              initial_app_brk┄┄┄┘  ┆   ┆ ┌┄┄┄kernel_memory_break           ┆
2033        //           initially unallocated┄┄┄┘   ┆ ↓                                 ┆
2034        //                                       ┆ ┌───────┬──────────┬──────────────┐
2035        //                                       ┆↔│process│upcall_buf│grant_pointers│
2036        //                                       ┆ └───────┴──────────┴──────────────┘
2037        //                                        ↑       ↑          ↑              ↑
2038        //             possible alignment padding┄┴┄┄┄┄┄┄┄┴┄┄┄┄┄┄┄┄┄┄┴┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘
2039        //
2040        //
2041        // First split the `remaining_memory` into two slices:
2042        //
2043        // 1. `allocated_padded_memory`: the allocated memory region, containing:
2044        //
2045        //    1. optional padding at the start of the memory region of
2046        //       `app_memory_start_offset` bytes,
2047        //    2. the app accessible memory region of `min_process_memory_size`,
2048        //    3. optional unallocated memory, and
2049        //    4. kernel-reserved memory, growing downward starting at the end of
2050        //       `allocated_memory`.
2051        //
2052        // 2. `unused_memory`: the rest of the `remaining_memory`, not assigned
2053        //    to this app.
2054        //
2055        // SAFETY: `app_memory_start_offset + allocation_size` must be within `remaining_memory`.
2056        let (allocated_padded_memory, unused_memory) = unsafe {
2057            raw_slice_split_at_mut(remaining_memory, app_memory_start_offset + allocation_size)
2058        };
2059
2060        // Now, slice off the (optional) padding at the start:
2061        //
2062        // SAFETY: `app_memory_start_offset` must be within `allocated_padded_memory`.
2063        let (_padding, allocated_memory) =
2064            unsafe { raw_slice_split_at_mut(allocated_padded_memory, app_memory_start_offset) };
2065
2066        // We continue to sub-slice the `allocated_memory` into
2067        // process-accessible and kernel-owned memory. Prior to that, store the
2068        // start and length ofthe overall allocation:
2069        let allocated_memory_start = allocated_memory.cast();
2070        let allocated_memory_len = allocated_memory.len();
2071
2072        // Slice off the process-accessible memory:
2073        //
2074        // SAFETY: `min_process_memory_size` must be within `allocated_memory`.
2075        let (app_accessible_memory, allocated_kernel_memory) =
2076            unsafe { raw_slice_split_at_mut(allocated_memory, min_process_memory_size) };
2077
2078        // Initialize (zero) the initial process-accessible memory region. This
2079        // serves two purposes:
2080        //
2081        // 1. It prevents a process from accessing any information still
2082        //    contained in this memory from prior kernel instances or processes.
2083        //
2084        // 2. It satisfies Rust's requirements that all dereferencable memory be
2085        //    properly initialized. This is important, as we'll be creating
2086        //    references into this process-accessible memory region through the
2087        //    process buffer infrastructure.
2088        let app_accessible_memory_bytes: *mut u8 = app_accessible_memory.cast();
2089        // SAFETY: `app_accessible_memory_bytes` is from a slice, and we use that
2090        // slice's length, so we know that there is enough memory and that the
2091        // pointer is aligned.
2092        unsafe {
2093            core::ptr::write_bytes(
2094                app_accessible_memory_bytes,
2095                // Set the entire app-accessible memory region to `0`:
2096                0_u8,
2097                app_accessible_memory.len(),
2098            );
2099        }
2100
2101        // Set the initial process-accessible memory.
2102        //
2103        // SAFETY: By using the slice `app_accessible_memory` and getting a pointer to
2104        // the byte after the slice, we are ensured that the memory between the
2105        // start of the allocation and the new pointer (at the end of the slice)
2106        // is valid because of the existing slice.
2107        let initial_app_brk = unsafe {
2108            app_accessible_memory
2109                .cast::<u8>()
2110                .add(app_accessible_memory.len())
2111        };
2112
2113        // Set the initial allow high water mark to the start of process memory
2114        // since no `allow` calls have been made yet.
2115        let initial_allow_high_water_mark = app_accessible_memory.cast();
2116
2117        // Set up initial grant region.
2118        //
2119        // `kernel_memory_break` is set to the end of kernel-accessible memory
2120        // and grows downward.
2121        let mut kernel_memory_break: *mut u8 = allocated_kernel_memory
2122            .cast::<u8>()
2123            .wrapping_add(allocated_kernel_memory.len());
2124
2125        ////////////////////////
2126        // Grant Region Pointers
2127        ////////////////////////
2128
2129        // Now that we know we have the space we can setup the grant pointers.
2130        //
2131        // First, move `kernel_memory_break` up to make room for the grant pointers.
2132        kernel_memory_break = kernel_memory_break.wrapping_sub(grant_ptrs_size);
2133        // Next, use the extra alignment padding we factored in to the total
2134        // calculation of `initial_kernel_memory_size` to ensure that
2135        // `kernel_memory_break` is aligned to a `GrantPointerEntry`.
2136        kernel_memory_break = kernel_memory_break
2137            .wrapping_sub(kernel_memory_break as usize % Self::GRANT_POINTERS_ALIGNMENT);
2138
2139        // Create the `GrantPointerEntry`s in the kernel region, then initialize
2140        // them.
2141        //
2142        // Where we calculated the updated kernel_memory_break is where the
2143        // `GrantPointerEntry`s start.
2144        let grant_pointers_memory_location: *mut MaybeUninit<GrantPointerEntry> =
2145            kernel_memory_break.cast();
2146        // Get a reference to the slice of `GrantPointerEntry`s.
2147        //
2148        // SAFETY: This is safe, as `grant_pointers_memory_location` is aligned to a
2149        // `GrantPointerEntry`, and we ensured there is space for
2150        // `grant_ptrs_num` of `GrantPointerEntry`s allocated.
2151        let grant_pointers_uninit: &mut [MaybeUninit<GrantPointerEntry>] =
2152            unsafe { slice::from_raw_parts_mut(grant_pointers_memory_location, grant_ptrs_num) };
2153        // Set all grant pointers to null.
2154        for grant_entry in grant_pointers_uninit.iter_mut() {
2155            grant_entry.write(GrantPointerEntry {
2156                driver_num: 0,
2157                grant_ptr: core::ptr::null_mut(),
2158            });
2159        }
2160        // SAFETY: All values in this slice have been properly initialized.
2161        let grant_pointers = unsafe { maybe_uninit_slice_assume_init_mut(grant_pointers_uninit) };
2162
2163        ////////////////////////
2164        // Upcall Queue
2165        ////////////////////////
2166
2167        // Now that we know we have the space we can setup the memory for the
2168        // upcalls.
2169        //
2170        // Move our `kernel_memory_break` up the size of the callback slice.
2171        kernel_memory_break = kernel_memory_break.wrapping_sub(Self::CALLBACKS_SIZE);
2172        // Use the space we allocated for alignment in case the pointer is not aligned.
2173        kernel_memory_break = kernel_memory_break
2174            .wrapping_sub(kernel_memory_break as usize % Self::CALLBACKS_ALIGNMENT);
2175
2176        // Set up ring buffer for upcalls to the process. The memory is uninitialized here,
2177        // so we cast to MaybeUninit<Task> which accurately represents that state.
2178        let upcall_buf: *mut core::mem::MaybeUninit<Task> = kernel_memory_break.cast();
2179
2180        // Get a reference `&mut [Task; Self:CALLBACK_LEN]`
2181        //
2182        // SAFETY: This needs to be aligned and have allocated space for
2183        // `Self::CALLBACK_LEN` instances of `Task`. We ensured there is enough
2184        // space when we allocated `allocated_kernel_memory` and we moved
2185        // kernel_memory_break up to fit the callbacks. We ensured this is
2186        // aligned by moving `kernel_memory_break` up if needed, and we
2187        // accounted for that potential increase in size when we allocated
2188        // `allocated_kernel_memory`.
2189        let upcall_buf = unsafe { slice::from_raw_parts_mut(upcall_buf, Self::CALLBACK_LEN) };
2190        // Actually setup the ring buffer.
2191        let tasks = RingBuffer::new(upcall_buf);
2192
2193        ////////////////////////
2194        // ProcessStandard
2195        ////////////////////////
2196
2197        // Last thing in the kernel region of process RAM is the process struct.
2198        //
2199        // Move `kernel_memory_break` to make room for the `ProcessStandard` struct.
2200        kernel_memory_break = kernel_memory_break.wrapping_sub(Self::PROCESS_STRUCT_SIZE);
2201        // Use the space we allocated for alignment in case the pointer is not aligned.
2202        kernel_memory_break = kernel_memory_break
2203            .wrapping_sub(kernel_memory_break as usize % Self::PROCESS_STRUCT_ALIGNMENT);
2204
2205        // Create a pointer to where the `ProcessStandard` struct will go in the
2206        // app grant region.
2207        let process_struct_memory_location: *mut MaybeUninit<ProcessStandard<'static, C, D>> =
2208            kernel_memory_break.cast();
2209        // Get a reference to the uninitialized `ProcessStandard` object.
2210        //
2211        // Note, this requires every field be explicitly initialized, as we are
2212        // just transforming a pointer into a structure. Because the
2213        // `ProcessStandard` is not initialized we mark it with `MaybeUninit`.
2214        //
2215        // SAFETY: This must have sufficient allocated space and proper alignment. When
2216        // we sized `allocated_kernel_memory` we ensured there was room for the
2217        // entire `ProcessStandard` struct. We also allocated space for
2218        // potential alignment issues, and ensured `kernel_memory_break` was
2219        // properly aligned for `ProcessStandard`.
2220        let process_uninit: &mut MaybeUninit<ProcessStandard<C, D>> =
2221            unsafe { &mut *process_struct_memory_location };
2222
2223        // Initialize ALL fields of `ProcessStandard`.
2224        //
2225        // SAFETY: These need to be valid and aligned writes. When we create the `MaybeUnint`
2226        // ProcessStandard struct we ensure there is valid memory for the object and
2227        // that it is aligned.
2228        unsafe {
2229            init_uninit_struct!(process_uninit => ProcessStandard<C, D> {
2230                process_id: Cell::new(ProcessId::new(
2231                    kernel,
2232                    kernel.create_process_identifier(),
2233                    index,
2234                )),
2235                app_id: app_id,
2236                kernel: kernel,
2237                chip: chip,
2238                allow_high_water_mark: Cell::new(initial_allow_high_water_mark),
2239                memory_start: allocated_memory_start,
2240                memory_len: allocated_memory_len,
2241                header: pb.header,
2242                kernel_memory_break: Cell::new(kernel_memory_break),
2243                app_break: Cell::new(initial_app_brk),
2244                grant_pointers: MapCell::new(grant_pointers),
2245
2246                credential: pb.credential.get(),
2247                footers: pb.footers,
2248                flash: pb.flash,
2249
2250                stored_state: MapCell::new(Default::default()),
2251                state: Cell::new(State::Yielded),
2252                fault_policy: fault_policy,
2253                restart_count: Cell::new(0),
2254                completion_code: OptionalCell::empty(),
2255
2256                storage_permissions: Cell::new(StoragePermissions::new_null()),
2257
2258                mpu_config: MapCell::new(mpu_config),
2259                mpu_regions: [
2260                    Cell::new(None),
2261                    Cell::new(None),
2262                    Cell::new(None),
2263                    Cell::new(None),
2264                    Cell::new(None),
2265                    Cell::new(None),
2266                ],
2267                tasks: MapCell::new(tasks),
2268                is_yield_wait_for_ready: Cell::new(false),
2269
2270                debug: D::default(),
2271            });
2272        }
2273
2274        // Convert the originally uninitialized `ProcessStandard` to a proper
2275        // `ProcessStandard` struct reference.
2276        //
2277        // SAFETY: All fields in `ProcessStandard` must be initialized. We guaranteed
2278        // this by using the `init_uninit_struct!()` macro, which causes a
2279        // compiler error if there is a missing field.
2280        let process = unsafe { process_uninit.assume_init_mut() };
2281
2282        // Save copies of these in case the app was compiled for fixed addresses
2283        // for later debugging.
2284        let fixed_address_flash = process.header.get_fixed_address_flash();
2285        let fixed_address_ram = process.header.get_fixed_address_ram();
2286        if let Some(fix_addr_flash) = fixed_address_flash {
2287            process.debug.set_fixed_address_flash(fix_addr_flash);
2288        }
2289        if let Some(fix_addr_ram) = fixed_address_ram {
2290            process.debug.set_fixed_address_ram(fix_addr_ram);
2291        }
2292
2293        // Handle any architecture-specific requirements for a new process.
2294        match process.stored_state.map(|stored_state| {
2295            // SAFETY: NOTE! We have to ensure that the start of process-accessible memory
2296            // (`app_memory_start`) is word-aligned. Since we currently start
2297            // process-accessible memory at the beginning of the allocated memory
2298            // region, we trust the MPU to give us a word-aligned starting address.
2299            //
2300            // TODO: https://github.com/tock/tock/issues/1739
2301            unsafe {
2302                chip.userspace_kernel_boundary().initialize_process(
2303                    app_accessible_memory.cast(),
2304                    initial_app_brk,
2305                    stored_state,
2306                )
2307            }
2308        }) {
2309            Some(Ok(())) => {}
2310            _ => {
2311                if config::CONFIG.debug_load_processes {
2312                    debug!(
2313                        "[!] flash={:#010X}-{:#010X} process={:?} - couldn't initialize process",
2314                        pb.flash.as_ptr() as usize,
2315                        pb.flash.as_ptr() as usize + pb.flash.len() - 1,
2316                        process_name
2317                    );
2318                }
2319                // Note that since remaining_memory was split by split_at_mut into
2320                // application memory and unused_memory, a failure here will leak
2321                // the application memory. Not leaking it requires being able to
2322                // reconstitute the original memory slice.
2323                return Err((ProcessLoadError::InternalError, unused_memory));
2324            }
2325        }
2326
2327        let flash_start: *const u8 = process.flash.as_ptr();
2328        let app_start =
2329            flash_start.wrapping_add(process.header.get_app_start_offset() as usize) as usize;
2330        let init_addr: *const () = flash_start
2331            .wrapping_add(process.header.get_init_function_offset() as usize)
2332            .cast();
2333        let fn_base = flash_start as usize;
2334        let fn_len = process.flash.len();
2335
2336        // We need to construct a capability with sufficient authority to cover
2337        // all of a user's code, with permissions to execute it. The entirety
2338        // of this process's flash is sufficient.
2339        //
2340        // SAFETY: It must be safe for this process to access the
2341        // bounds+permission expressed here while assuming no other protection
2342        // mechanism is active.
2343        //  - It is valid under Tock's threat model for a process to try to
2344        //  execute anything within process-owned flash.
2345        //  - `process.flash` which we use to derive the bounds is defined as
2346        //  process-owned flash for a well-formed process, which we trust is
2347        //  the case here.
2348        //  - We grant only execute permission.
2349        //  - We only pass this pointer to this process.
2350        let init_fn = unsafe {
2351            CapabilityPtr::new_with_authority(
2352                init_addr,
2353                fn_base,
2354                fn_len,
2355                CapabilityPtrPermissions::Execute,
2356            )
2357        };
2358
2359        process.tasks.map(|tasks| {
2360            tasks.enqueue(Task::FunctionCall(FunctionCall {
2361                source: FunctionCallSource::Kernel,
2362                pc: init_fn,
2363                argument0: app_start,
2364                argument1: process.memory_start as usize,
2365                argument2: process.memory_len,
2366                argument3: (process.app_break.get() as usize).into(),
2367            }));
2368        });
2369
2370        // Set storage permissions. Put this at the end so that `process` is
2371        // completely formed before using it to determine the storage
2372        // permissions.
2373        process
2374            .storage_permissions
2375            .set(storage_permissions_policy.get_permissions(process));
2376
2377        // Return the process object and a remaining memory for processes slice.
2378        Ok((Some(process), unused_memory))
2379    }
2380
2381    /// Reset the process, resetting all of its state and re-initializing it so
2382    /// it can start running. Assumes the process is not running but is still in
2383    /// flash and still has its memory region allocated to it.
2384    fn reset(&self) -> Result<(), ErrorCode> {
2385        // We need a new process identifier for this process since the restarted
2386        // version is in effect a new process. This is also necessary to
2387        // invalidate any stored `ProcessId`s that point to the old version of
2388        // the process. However, the process has not moved locations in the
2389        // processes array, so we copy the existing index.
2390        let old_index = self.process_id.get().index;
2391        let new_identifier = self.kernel.create_process_identifier();
2392        self.process_id
2393            .set(ProcessId::new(self.kernel, new_identifier, old_index));
2394
2395        // Reset debug information that is per-execution and not per-process.
2396        self.debug.reset_last_syscall();
2397        self.debug.reset_syscall_count();
2398        self.debug.reset_dropped_upcall_count();
2399        self.debug.reset_timeslice_expiration_count();
2400
2401        // Reset MPU region configuration.
2402        //
2403        // TODO: ideally, this would be moved into a helper function used by
2404        // both create() and reset(), but process load debugging complicates
2405        // this. We just want to create new config with only flash and memory
2406        // regions.
2407        //
2408        // We must have a previous MPU configuration stored, fault the
2409        // process if this invariant is violated. We avoid allocating
2410        // a new MPU configuration, as this may eventually exhaust the
2411        // number of available MPU configurations.
2412        let mut mpu_config = self.mpu_config.take().ok_or(ErrorCode::FAIL)?;
2413        self.chip.mpu().reset_config(&mut mpu_config);
2414
2415        for region in self.mpu_regions.iter() {
2416            region.take();
2417        }
2418
2419        // Allocate MPU region for flash.
2420        let app_mpu_flash = self.chip.mpu().allocate_region(
2421            self.flash.as_ptr(),
2422            self.flash.len(),
2423            self.flash.len(),
2424            mpu::Permissions::ReadExecuteOnly,
2425            &mut mpu_config,
2426        );
2427        if app_mpu_flash.is_none() {
2428            // We were unable to allocate an MPU region for flash. This is very
2429            // unexpected since we previously ran this process. However, we
2430            // return now and leave the process faulted and it will not be
2431            // scheduled.
2432            return Err(ErrorCode::FAIL);
2433        }
2434
2435        // RAM
2436
2437        // Re-determine the minimum amount of RAM the kernel must allocate to
2438        // the process based on the specific requirements of the syscall
2439        // implementation.
2440        let min_process_memory_size = self
2441            .chip
2442            .userspace_kernel_boundary()
2443            .initial_process_app_brk_size();
2444
2445        // Recalculate initial_kernel_memory_size as was done in create()
2446        let grant_ptr_size = mem::size_of::<GrantPointerEntry>();
2447        let grant_ptrs_num = self.kernel.get_grant_count_and_finalize();
2448        let grant_ptrs_size = grant_ptrs_num * grant_ptr_size;
2449
2450        let initial_kernel_memory_size = grant_ptrs_size
2451            + Self::GRANT_POINTERS_ALIGNMENT
2452            + Self::CALLBACKS_SIZE
2453            + Self::CALLBACKS_ALIGNMENT
2454            + Self::PROCESS_STRUCT_SIZE
2455            + Self::PROCESS_STRUCT_ALIGNMENT;
2456
2457        let app_mpu_mem = self.chip.mpu().allocate_app_memory_region(
2458            self.mem_start(),
2459            self.memory_len,
2460            self.memory_len, //we want exactly as much as we had before restart
2461            min_process_memory_size,
2462            initial_kernel_memory_size,
2463            mpu::Permissions::ReadWriteOnly,
2464            &mut mpu_config,
2465        );
2466        let (app_mpu_mem_start, app_mpu_mem_len) = match app_mpu_mem {
2467            Some((start, len)) => (start, len),
2468            None => {
2469                // We couldn't configure the MPU for the process. This shouldn't
2470                // happen since we were able to start the process before, but at
2471                // this point it is better to leave the app faulted and not
2472                // schedule it.
2473                return Err(ErrorCode::NOMEM);
2474            }
2475        };
2476
2477        // Reset memory pointers now that we know the layout of the process
2478        // memory and know that we can configure the MPU.
2479
2480        // app_brk is set based on minimum syscall size above the start of
2481        // memory.
2482        let app_brk = app_mpu_mem_start.wrapping_add(min_process_memory_size);
2483        self.app_break.set(app_brk);
2484        // kernel_brk is calculated backwards from the end of memory the size of
2485        // the initial kernel data structures.
2486        let kernel_brk = app_mpu_mem_start
2487            .wrapping_add(app_mpu_mem_len)
2488            .wrapping_sub(initial_kernel_memory_size);
2489        self.kernel_memory_break.set(kernel_brk);
2490        // High water mark for `allow`ed memory is reset to the start of the
2491        // process's memory region.
2492        self.allow_high_water_mark.set(app_mpu_mem_start);
2493
2494        // Store the adjusted MPU configuration:
2495        self.mpu_config.replace(mpu_config);
2496
2497        // Handle any architecture-specific requirements for a process when it
2498        // first starts (as it would when it is new).
2499        let ukb_init_process = self.stored_state.map_or(Err(()), |stored_state| {
2500            // SAFETY: The memory bounds must be valid for this process. We know
2501            // this is true here because we use the start of process memory and
2502            // the current `app_brk`, and that range is accessible to the
2503            // process.
2504            unsafe {
2505                self.chip.userspace_kernel_boundary().initialize_process(
2506                    app_mpu_mem_start,
2507                    app_brk,
2508                    stored_state,
2509                )
2510            }
2511        });
2512        match ukb_init_process {
2513            Ok(()) => {}
2514            Err(()) => {
2515                // We couldn't initialize the architecture-specific state for
2516                // this process. This shouldn't happen since the app was able to
2517                // be started before, but at this point the app is no longer
2518                // valid. The best thing we can do now is leave the app as still
2519                // faulted and not schedule it.
2520                return Err(ErrorCode::RESERVE);
2521            }
2522        }
2523
2524        self.restart_count.increment();
2525
2526        // Mark the state as `Yielded` for the scheduler.
2527        self.state.set(State::Yielded);
2528
2529        // And queue up this app to be restarted.
2530        let flash_start: *const u8 = self.flash_start();
2531        let app_start =
2532            flash_start.wrapping_add(self.header.get_app_start_offset() as usize) as usize;
2533        let init_addr: *const () = flash_start
2534            .wrapping_add(self.header.get_init_function_offset() as usize)
2535            .cast();
2536
2537        // We need to construct a capability with sufficient authority to cover
2538        // all of a user's code, with permissions to execute it. The entirety
2539        // of this process's flash is sufficient.
2540        //
2541        // SAFETY: It must be safe for this process to access the
2542        // bounds+permission expressed here while assuming no other protection
2543        // mechanism is active.
2544        //  - It is valid under Tock's threat model for a process to try to
2545        //  execute anything within process-owned flash.
2546        //  - `self.flash` which we use to derive the bounds is defined as
2547        //  process-owned flash for a well-formed process, which we trust is
2548        //  the case here.
2549        //  - We grant only execute permission.
2550        //  - We only pass this pointer to this process.
2551        let init_fn = unsafe {
2552            CapabilityPtr::new_with_authority(
2553                init_addr,
2554                flash_start as usize,
2555                self.flash_end() - (flash_start as usize),
2556                CapabilityPtrPermissions::Execute,
2557            )
2558        };
2559
2560        self.enqueue_task(Task::FunctionCall(FunctionCall {
2561            source: FunctionCallSource::Kernel,
2562            pc: init_fn,
2563            argument0: app_start,
2564            argument1: self.memory_start as usize,
2565            argument2: self.memory_len,
2566            argument3: (self.app_break.get() as usize).into(),
2567        }))
2568    }
2569
2570    /// Checks if the buffer represented by the passed in base pointer and size
2571    /// is within the RAM bounds currently exposed to the processes (i.e. ending
2572    /// at `app_break`). If this method returns `true`, the buffer is guaranteed
2573    /// to be accessible to the process and to not overlap with the grant
2574    /// region.
2575    fn in_app_owned_memory(&self, buf_start_addr: *const u8, size: usize) -> bool {
2576        // TODO: On some platforms, CapabilityPtr has sufficient authority that we
2577        // could skip this check.
2578        // CapabilityPtr needs to make it slightly further, and we need to add
2579        // interfaces that tell us how much assurance it gives on the current
2580        // platform.
2581        let buf_end_addr = buf_start_addr.wrapping_add(size);
2582
2583        buf_end_addr >= buf_start_addr
2584            && buf_start_addr >= self.mem_start()
2585            && buf_end_addr <= self.app_break.get()
2586    }
2587
2588    /// Checks if the buffer represented by the passed in base pointer and size
2589    /// are within the readable region of an application's flash memory.  If
2590    /// this method returns true, the buffer is guaranteed to be readable to the
2591    /// process.
2592    fn in_app_flash_memory(&self, buf_start_addr: *const u8, size: usize) -> bool {
2593        #![allow(
2594            clippy::suspicious_operation_groupings,
2595            reason = "false positive on flash_non_protected_start"
2596        )]
2597
2598        // TODO: On some platforms, CapabilityPtr has sufficient authority that we
2599        // could skip this check.
2600        // CapabilityPtr needs to make it slightly further, and we need to add
2601        // interfaces that tell us how much assurance it gives on the current
2602        // platform.
2603        let buf_end_addr = buf_start_addr.wrapping_add(size);
2604
2605        buf_end_addr >= buf_start_addr
2606            && buf_start_addr.addr() >= self.flash_non_protected_start()
2607            && buf_end_addr.addr() <= self.flash_end()
2608    }
2609
2610    /// Allocate memory in a process's grant region.
2611    ///
2612    /// Ensures that the allocation is of `size` bytes and aligned to `align`
2613    /// bytes.
2614    ///
2615    /// If there is not enough memory, or the MPU cannot isolate the process
2616    /// accessible region from the new kernel memory break after doing the
2617    /// allocation, then this will return `None`.
2618    fn allocate_in_grant_region_internal(&self, size: usize, align: usize) -> Option<NonNull<u8>> {
2619        self.mpu_config.and_then(|config| {
2620            // First, compute the candidate new pointer. Note that at this point
2621            // we have not yet checked whether there is space for this
2622            // allocation or that it meets alignment requirements.
2623            let new_break_unaligned = self.kernel_memory_break.get().wrapping_sub(size);
2624
2625            // Our minimum alignment requirement is two bytes, so that the
2626            // lowest bit of the address will always be zero and we can use it
2627            // as a flag. It doesn't hurt to increase the alignment (except for
2628            // potentially a wasted byte) so we make sure `align` is at least
2629            // two.
2630            let align = cmp::max(align, 2);
2631
2632            // The alignment must be a power of two, 2^a. The expression
2633            // `!(align - 1)` then returns a mask with leading ones, followed by
2634            // `a` trailing zeros.
2635            let alignment_mask = !(align - 1);
2636            let new_break = new_break_unaligned.map_addr(|a| a & alignment_mask);
2637
2638            // Verify there is space for this allocation
2639            if new_break < self.app_break.get() {
2640                None
2641                // Verify it didn't wrap around
2642            } else if new_break > self.kernel_memory_break.get() {
2643                None
2644                // Verify this is compatible with the MPU.
2645            } else if let Err(()) = self.chip.mpu().update_app_memory_region(
2646                self.app_break.get(),
2647                new_break,
2648                mpu::Permissions::ReadWriteOnly,
2649                config,
2650            ) {
2651                None
2652            } else {
2653                // Allocation is valid.
2654
2655                // We always allocate down, so we must lower the
2656                // kernel_memory_break.
2657                self.kernel_memory_break.set(new_break);
2658
2659                // We need `grant_ptr` as a mutable pointer.
2660                let grant_ptr: *mut u8 = new_break.cast_mut();
2661
2662                // SAFETY: Here we are guaranteeing that `grant_ptr` is not null. We can
2663                // ensure this because we just created `grant_ptr` based on the
2664                // process's allocated memory, and we know it cannot be null.
2665                unsafe { Some(NonNull::new_unchecked(grant_ptr)) }
2666            }
2667        })
2668    }
2669
2670    /// Create the identifier for a custom grant that grant.rs uses to access
2671    /// the custom grant.
2672    ///
2673    /// We create this identifier by calculating the number of bytes between
2674    /// where the custom grant starts and the end of the process memory.
2675    fn create_custom_grant_identifier(&self, ptr: NonNull<u8>) -> ProcessCustomGrantIdentifier {
2676        let custom_grant_address = ptr.as_ptr() as usize;
2677        let process_memory_end = self.mem_end() as usize;
2678
2679        ProcessCustomGrantIdentifier {
2680            offset: process_memory_end - custom_grant_address,
2681        }
2682    }
2683
2684    /// Use a `ProcessCustomGrantIdentifier` to find the address of the
2685    /// custom grant.
2686    ///
2687    /// This reverses `create_custom_grant_identifier()`.
2688    fn get_custom_grant_address(&self, identifier: ProcessCustomGrantIdentifier) -> usize {
2689        let process_memory_end = self.mem_end() as usize;
2690
2691        // Subtract the offset in the identifier from the end of the process
2692        // memory to get the address of the custom grant.
2693        process_memory_end - identifier.offset
2694    }
2695
2696    /// Return the app's read and modify storage permissions from the TBF header
2697    /// if it exists.
2698    ///
2699    /// If the header does not exist then return `None`. If the header does
2700    /// exist, this returns a 5-tuple with:
2701    ///
2702    /// - `write_allowed`: bool. If this process should have write permissions.
2703    /// - `read_count`: usize. How many read IDs are valid.
2704    /// - `read_ids`: [u32]. The read IDs.
2705    /// - `modify_count`: usze. How many modify IDs are valid.
2706    /// - `modify_ids`: [u32]. The modify IDs.
2707    pub fn get_tbf_storage_permissions(&self) -> Option<(bool, usize, [u32; 8], usize, [u32; 8])> {
2708        let read_perms = self.header.get_storage_read_ids();
2709        let modify_perms = self.header.get_storage_modify_ids();
2710
2711        match (read_perms, modify_perms) {
2712            (Some((read_count, read_ids)), Some((modify_count, modify_ids))) => Some((
2713                self.header.get_storage_write_id().is_some(),
2714                read_count,
2715                read_ids,
2716                modify_count,
2717                modify_ids,
2718            )),
2719            _ => None,
2720        }
2721    }
2722
2723    /// The start address of allocated RAM for this process.
2724    fn mem_start(&self) -> *const u8 {
2725        self.memory_start
2726    }
2727
2728    /// The first address after the end of the allocated RAM for this process.
2729    fn mem_end(&self) -> *const u8 {
2730        self.memory_start.wrapping_add(self.memory_len)
2731    }
2732
2733    /// The start address of the flash region allocated for this process.
2734    fn flash_start(&self) -> *const u8 {
2735        self.flash.as_ptr()
2736    }
2737
2738    /// Get the first address of process's flash that isn't protected by the
2739    /// kernel. The protected range of flash contains the TBF header and
2740    /// potentially other state the kernel is storing on behalf of the process,
2741    /// and cannot be edited by the process.
2742    fn flash_non_protected_start(&self) -> usize {
2743        (self.flash.as_ptr() as usize) + self.header.get_protected_size() as usize
2744    }
2745
2746    /// The first address after the end of the flash region allocated for this
2747    /// process.
2748    fn flash_end(&self) -> usize {
2749        self.flash.as_ptr().addr().wrapping_add(self.flash.len())
2750    }
2751
2752    /// The lowest address of the grant region for the process.
2753    fn kernel_memory_break(&self) -> *const u8 {
2754        self.kernel_memory_break.get()
2755    }
2756
2757    /// Return the highest address the process has access to, or the current
2758    /// process memory brk.
2759    fn app_memory_break(&self) -> *const u8 {
2760        self.app_break.get()
2761    }
2762}