[][src]Trait kernel::syscall::UserspaceKernelBoundary

pub trait UserspaceKernelBoundary {
    type StoredState: Default + Copy;
    unsafe fn initialize_new_process(
        &self,
        stack_pointer: *const usize,
        stack_size: usize,
        state: &mut Self::StoredState
    ) -> Result<*const usize, ()>;
unsafe fn set_syscall_return_value(
        &self,
        stack_pointer: *const usize,
        state: &mut Self::StoredState,
        return_value: isize
    );
unsafe fn set_process_function(
        &self,
        stack_pointer: *const usize,
        remaining_stack_memory: usize,
        state: &mut Self::StoredState,
        callback: FunctionCall
    ) -> Result<*mut usize, *mut usize>;
unsafe fn switch_to_process(
        &self,
        stack_pointer: *const usize,
        state: &mut Self::StoredState
    ) -> (*mut usize, ContextSwitchReason);
unsafe fn fault_fmt(&self, writer: &mut dyn Write);
unsafe fn process_detail_fmt(
        &self,
        stack_pointer: *const usize,
        state: &Self::StoredState,
        writer: &mut dyn Write
    ); }

This trait must be implemented by the architecture of the chip Tock is running on. It allows the kernel to manage switching to and from processes in an architecture-agnostic manner.

Associated Types

type StoredState: Default + Copy

Some architecture-specific struct containing per-process state that must be kept while the process is not running. For example, for keeping CPU registers that aren't stored on the stack.

Loading content...

Required methods

unsafe fn initialize_new_process(
    &self,
    stack_pointer: *const usize,
    stack_size: usize,
    state: &mut Self::StoredState
) -> Result<*const usize, ()>

Called by the kernel after a new process has been created by before it is allowed to begin executing. Allows for architecture-specific process setup, e.g. allocating a syscall stack frame.

unsafe fn set_syscall_return_value(
    &self,
    stack_pointer: *const usize,
    state: &mut Self::StoredState,
    return_value: isize
)

Set the return value the process should see when it begins executing again after the syscall. This will only be called after a process has called a syscall.

To help implementations, both the current stack pointer of the process and the saved state for the process are provided. The return_value is the value that should be passed to the process so that when it resumes executing it knows the return value of the syscall it called.

unsafe fn set_process_function(
    &self,
    stack_pointer: *const usize,
    remaining_stack_memory: usize,
    state: &mut Self::StoredState,
    callback: FunctionCall
) -> Result<*mut usize, *mut usize>

Set the function that the process should execute when it is resumed. This has two major uses: 1) sets up the initial function call to _start when the process is started for the very first time; 2) tells the process to execute a callback function after calling yield().

Note: This method cannot be called in conjunction with set_syscall_return_value, as the injected function will clobber the return value.

Arguments

  • stack_pointer is the address of the stack pointer for the current app.
  • remaining_stack_memory is the number of bytes below the stack_pointer that is allocated for the process. This value is checked by the implementer to ensure that there is room for this stack frame without overflowing the stack.
  • state is the stored state for this process.
  • callback is the function that should be executed when the process resumes.

Return

Returns Ok or Err with the current address of the stack pointer for the process. One reason for returning Err is that adding the function call requires adding to the stack, and there is insufficient room on the stack to add the function call.

unsafe fn switch_to_process(
    &self,
    stack_pointer: *const usize,
    state: &mut Self::StoredState
) -> (*mut usize, ContextSwitchReason)

Context switch to a specific process.

This returns a tuple:

  • The new stack pointer address of the process.
  • Why the process stopped executing and switched back to the kernel.

unsafe fn fault_fmt(&self, writer: &mut dyn Write)

Display any general information about the fault.

unsafe fn process_detail_fmt(
    &self,
    stack_pointer: *const usize,
    state: &Self::StoredState,
    writer: &mut dyn Write
)

Display architecture specific (e.g. CPU registers or status flags) data for a process identified by its stack pointer.

Loading content...

Implementors

Loading content...