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}