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
impl ProcessId
Sourcepub fn new_external(
kernel: &'static Kernel,
identifier: usize,
index: usize,
_capability: &dyn ExternalProcessCapability,
) -> ProcessId
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.
Sourcepub fn id(&self) -> usize
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.
Sourcepub fn short_app_id(&self) -> ShortId
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.
Sourcepub fn get_editable_flash_range(&self) -> (usize, usize)
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.
Sourcepub fn get_storage_permissions(&self) -> Option<StoragePermissions>
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.