Struct kernel::process::ProcessId

source ·
pub struct ProcessId { /* private fields */ }
Expand description

Userspace process identifier.

This is an opaque type that can be used to represent a running process on the board without requiring an actual reference to a Process object. Having this ProcessId reference type is useful for managing ownership and type issues in Rust, but more importantly ProcessId serves as a tool for capsules to hold pointers to applications.

Since ProcessId implements Copy, having an ProcessId does not ensure that the process the ProcessId refers to is still valid. The process may have been removed, terminated, or restarted as a new process. Therefore, all uses of ProcessId in the kernel must check that the ProcessId is still valid. This check happens automatically when .index() is called, as noted by the return type: Option<usize>. .index() will return the index of the process in the processes array, but if the process no longer exists then None is returned.

Outside of the kernel crate, holders of an ProcessId may want to use .id() to retrieve a simple identifier for the process that can be communicated over a UART bus or syscall interface. This call is guaranteed to return a suitable identifier for the ProcessId, but does not check that the corresponding application still exists.

This type also provides capsules an interface for interacting with processes since they otherwise would have no reference to a Process. Very limited operations are available through this interface since capsules should not need to know the details of any given process. However, certain information makes certain capsules possible to implement. For example, capsules can use the get_editable_flash_range() function so they can safely allow an app to modify its own flash.

Implementations§

source§

impl ProcessId

source

pub fn new_external( kernel: &'static Kernel, identifier: usize, index: usize, _capability: &dyn ExternalProcessCapability ) -> ProcessId

Create a new ProcessId object based on the app identifier and its index in the processes array.

This constructor is public but protected with a capability so that external implementations of Process can use it.

source

pub fn id(&self) -> usize

Get a usize unique identifier for the app this ProcessId refers to.

This function should not generally be used, instead code should just use the ProcessId object itself to refer to various apps on the system. However, getting just a usize identifier is particularly useful when referring to a specific app with things outside of the kernel, say for userspace (e.g. IPC) or tockloader (e.g. for debugging) where a concrete number is required.

Note, this will always return the saved unique identifier for the app originally referred to, even if that app no longer exists. For example, the app may have restarted, or may have been ended or removed by the kernel. Therefore, calling id() is not a valid way to check that an application still exists.

source

pub fn short_app_id(&self) -> ShortId

Get the ShortId for this application this process is an execution of.

The ShortId is an identifier for the application, not the particular execution (i.e. the currently running process). This makes ShortId distinct from ProcessId.

This function is a helper function as capsules typically use ProcessId as a handle to the running process and corresponding app.

source

pub fn get_editable_flash_range(&self) -> (usize, usize)

Returns the full address of the start and end of the flash region that the app owns and can write to. This includes the app’s code and data and any padding at the end of the app. It does not include the TBF header, or any space that the kernel is using for any potential bookkeeping.

source

pub fn get_storage_permissions(&self) -> Option<StoragePermissions>

Get the storage permissions for the process. These permissions indicate what the process is allowed to read and write. Returns None if the process has no storage permissions.

Trait Implementations§

source§

impl Clone for ProcessId

source§

fn clone(&self) -> ProcessId

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for ProcessId

source§

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl Eq for ProcessId

source§

impl PartialEq for ProcessId

source§

fn eq(&self, other: &ProcessId) -> bool

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Copy for ProcessId

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> SizedTypeProperties for T

source§

const IS_ZST: bool = _

🔬This is a nightly-only experimental API. (sized_type_properties)
true if this type requires no storage. false if its size is greater than zero. Read more
source§

impl<T> SpecOptionPartialEq for T
where T: PartialEq,

source§

default fn eq(l: &Option<T>, r: &Option<T>) -> bool

🔬This is a nightly-only experimental API. (spec_option_partial_eq)
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> Printable for T
where T: Copy + Debug,