Struct ProcessStandard

pub struct ProcessStandard<'a, C: 'static + Chip, D: 'static + ProcessStandardDebug + Default> { /* private fields */ }

A type for userspace processes in Tock.

As its name implies, this is the standard implementation for Tock processes that exposes the full support for processes running on embedded hardware.

ProcessStandard is templated on two parameters:

• C: Chip: The implementation must know the Chip the kernel is running on to properly store architecture-specific and MPU state for the process.
• D: ProcessStandardDebug: This configures the debugging mechanism the process uses for storing optional debugging data. Kernels that do not wish to store per-process debugging state can use the () type for this parameter.

Implementations

impl<C: 'static + Chip, D: 'static + ProcessStandardDebug> ProcessStandard<'_, C, D>

pub fn get_tbf_storage_permissions( &self, ) -> Option<(bool, usize, [u32; 8], usize, [u32; 8])>

Return the app’s read and modify storage permissions from the TBF header if it exists.

If the header does not exist then return None. If the header does exist, this returns a 5-tuple with:

• write_allowed: bool. If this process should have write permissions.
• read_count: usize. How many read IDs are valid.
• read_ids: u32. The read IDs.
• modify_count: usze. How many modify IDs are valid.
• modify_ids: u32. The modify IDs.

Trait Implementations

impl<C: Chip, D: 'static + ProcessStandardDebug> Process for ProcessStandard<'_, C, D>

fn processid(&self) -> ProcessId

Returns the process’s identifier.

fn short_app_id(&self) -> ShortId

Returns the ShortId generated by the application binary checker at loading.

fn binary_version(&self) -> Option<BinaryVersion>

Returns the version number of the binary in this process, as specified in a TBF Program Header. If the binary has no version assigned this returns None.

fn get_credential(&self) -> Option<AcceptedCredential>

Return the credential which the credential checker approved if the credential checker approved a credential. If the process was allowed to run without credentials, return None.

fn enqueue_task(&self, task: Task) -> Result<(), ErrorCode>

Queue a Task for the process. This will be added to a per-process buffer and executed by the scheduler. Tasks are some function the process should run, for example a upcall or an IPC call.

fn ready(&self) -> bool

Returns whether this process is ready to execute.

fn remove_pending_upcalls(&self, upcall_id: UpcallId) -> usize

Remove all scheduled upcalls with the given upcall_id from the task queue.

fn is_running(&self) -> bool

Returns whether the process is running or not.

fn get_state(&self) -> State

Returns the current state the process is in.

fn set_yielded_state(&self)

Move this process from the running state to the yielded state.

fn set_yielded_for_state(&self, upcall_id: UpcallId)

Move this process from the running state to the yielded-for state.

fn stop(&self)

Move this process from running or yielded state into the stopped state.

fn resume(&self)

Move this stopped process back into its original state.

fn set_fault_state(&self)

Put this process in the fault state.

fn start(&self, _cap: &dyn ProcessStartCapability)

Start a terminated process. This function can only be called on a terminated process.

fn try_restart(&self, completion_code: Option<u32>)

Terminates and attempts to restart the process. The process and current application always terminate. The kernel may, based on its own policy, restart the application using the same process, reuse the process for another application, or simply terminate the process and application.

fn terminate(&self, completion_code: Option<u32>)

Stop and clear a process’s state and put it into the Terminated state.

fn get_restart_count(&self) -> usize

Returns how many times this process has been restarted.

fn has_tasks(&self) -> bool

Return if there are any Tasks (upcalls/IPC requests) enqueued for the process.

fn dequeue_task(&self) -> Option<Task>

Remove the scheduled operation from the front of the queue and return it to be handled by the scheduler.

fn remove_upcall(&self, upcall_id: UpcallId) -> Option<Task>

Search the work queue for the first pending operation with the given upcall_id and if one exists remove it from the queue.process

fn pending_tasks(&self) -> usize

Returns the number of pending tasks. If 0 then dequeue_task() will return None when called.

fn get_command_permissions( &self, driver_num: usize, offset: usize, ) -> CommandPermissions

Return the permissions for this process for a given driver_num.

fn get_storage_permissions(&self) -> StoragePermissions

Get the storage permissions for the process.

fn number_writeable_flash_regions(&self) -> usize

How many writeable flash regions defined in the TBF header for this process.

fn get_writeable_flash_region(&self, region_index: usize) -> (usize, usize)

Get the offset from the beginning of flash and the size of the defined writeable flash region.

fn update_stack_start_pointer(&self, stack_pointer: *const u8)

Debug function to update the kernel on where the stack starts for this process. Processes are not required to call this through the memop system call, but it aids in debugging the process.

fn update_heap_start_pointer(&self, heap_pointer: *const u8)

Debug function to update the kernel on where the process heap starts. Also optional.

fn setup_mpu(&self)

Configure the MPU to use the process’s allocated regions.

fn add_mpu_region( &self, unallocated_memory_start: *const u8, unallocated_memory_size: usize, min_region_size: usize, ) -> Option<Region>

Allocate a new MPU region for the process that is at least min_region_size bytes and lies within the specified stretch of unallocated memory.

fn remove_mpu_region(&self, region: Region) -> Result<(), ErrorCode>

Removes an MPU region from the process that has been previously added with add_mpu_region.

fn sbrk(&self, increment: isize) -> Result<CapabilityPtr, Error>

Change the location of the program break by increment bytes, reallocate the MPU region covering program memory, and return the previous break address.

fn brk(&self, new_break: *const u8) -> Result<CapabilityPtr, Error>

Change the location of the program break to new_break and reallocate the MPU region covering program memory.

fn build_readwrite_process_buffer( &self, buf_start_addr: *mut u8, size: usize, ) -> Result<ReadWriteProcessBuffer, ErrorCode>

Creates a ReadWriteProcessBuffer from the given offset and size in process memory.

fn build_readonly_process_buffer( &self, buf_start_addr: *const u8, size: usize, ) -> Result<ReadOnlyProcessBuffer, ErrorCode>

Creates a ReadOnlyProcessBuffer from the given offset and size in process memory.

unsafe fn set_byte(&self, addr: *mut u8, value: u8) -> bool

Set a single byte within the process address space at addr to value. Return true if addr is within the RAM bounds currently exposed to the process (thereby writable by the process itself) and the value was set, false otherwise.

fn grant_is_allocated(&self, grant_num: usize) -> Option<bool>

Check if a given grant for this process has been allocated.

fn allocate_grant( &self, grant_num: usize, driver_num: usize, size: usize, align: usize, ) -> Result<(), ()>

Allocate memory from the grant region and store the reference in the proper grant pointer index.

fn allocate_custom_grant( &self, size: usize, align: usize, ) -> Result<(ProcessCustomGrantIdentifier, NonNull<u8>), ()>

Allocate memory from the grant region that is size bytes long and aligned to align bytes. This is used for creating custom grants which are not recorded in the grant pointer array, but are useful for capsules which need additional process-specific dynamically allocated memory.

fn enter_grant(&self, grant_num: usize) -> Result<NonNull<u8>, Error>

Enter the grant based on grant_num for this process.

fn enter_custom_grant( &self, identifier: ProcessCustomGrantIdentifier, ) -> Result<*mut u8, Error>

Enter a custom grant based on the identifier.

unsafe fn leave_grant(&self, grant_num: usize)

Opposite of enter_grant(). Used to signal that the grant is no longer entered.

fn grant_allocated_count(&self) -> Option<usize>

Return the count of the number of allocated grant pointers if the process is active. This does not count custom grants. This is used to determine if a new grant has been allocated after a call to SyscallDriver::allocate_grant().

fn lookup_grant_from_driver_num( &self, driver_num: usize, ) -> Result<usize, Error>

Get the grant number (grant_num) associated with a given driver number if there is a grant associated with that driver_num.

fn is_valid_upcall_function_pointer(&self, upcall_fn: *const ()) -> bool

Verify that an upcall function pointer is within process-accessible memory.

fn get_process_name(&self) -> &'static str

Get the name of the process. Used for IPC.

fn get_completion_code(&self) -> Option<Option<u32>>

Get the completion code if the process has previously terminated.

fn set_syscall_return_value(&self, return_value: SyscallReturn)

Set the return value the process should see when it begins executing again after the syscall.

fn set_process_function(&self, callback: FunctionCall)

Set the function that is to be executed when the process is resumed.

fn switch_to(&self) -> Option<ContextSwitchReason>

Context switch to a specific process.

fn debug_syscall_count(&self) -> usize

Returns how many syscalls this app has called.

fn debug_dropped_upcall_count(&self) -> usize

Returns how many upcalls for this process have been dropped.

fn debug_timeslice_expiration_count(&self) -> usize

Returns how many times this process has exceeded its timeslice.

fn debug_timeslice_expired(&self)

Increment the number of times the process has exceeded its timeslice.

fn debug_syscall_called(&self, last_syscall: Syscall)

Increment the number of times the process called a syscall and record the last syscall that was called.

fn debug_syscall_last(&self) -> Option<Syscall>

Return the last syscall the process called. Returns None if the process has not called any syscalls or the information is unknown.

fn get_addresses(&self) -> ProcessAddresses

Return process state information related to the location in memory of various process data structures.

fn get_sizes(&self) -> ProcessSizes

Return process state information related to the size in memory of various process data structures.

fn print_full_process(&self, writer: &mut dyn Write)

Print out the full state of the process: its memory map, its context, and the state of the memory protection unit (MPU).

fn get_stored_state(&self, out: &mut [u8]) -> Result<usize, ErrorCode>

Write stored state as a binary blob into the out slice. Returns the number of bytes written to out on success.