pw_kernel/kernel/scheduler/process.rs - pigweed/sandbox - Git at Google

 // Copyright 2026 The Pigweed Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License"); you may not
 // use this file except in compliance with the License. You may obtain a copy of
 // the License at
 //
 //     https://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 // License for the specific language governing permissions and limitations under
 // the License.

 use core::mem::ManuallyDrop;
 use core::ops::Range;
 use core::ptr::NonNull;
 use core::sync::atomic::Ordering;

 use exit_status::ExitStatus;
 #[cfg(not(feature = "user_space"))]
 use foreign_box::ForeignBox;
 #[cfg(feature = "user_space")]
 use foreign_box::{ForeignBox, ForeignRc};
 use list::*;
 use memory_config::{MemoryConfig as _, MemoryRegionType};
 use pw_atomic::{AtomicAdd, AtomicSub, AtomicZero};
 use pw_log::info;
 use pw_status::Result;
 use pw_time_core::Instant;

 use crate::Kernel;
 #[cfg(feature = "user_space")]
 use crate::object::{KernelObject, ObjectTable};
 use crate::scheduler::SchedulerState;
 use crate::scheduler::thread::{Thread, ThreadHandle, ThreadState};
 use crate::sync::event::{Event, EventConfig, EventSignaler};
 use crate::sync::spinlock::SpinLockGuard;

 /// Runtime state of a Process.
 #[derive(Copy, Clone, PartialEq)]
 pub enum ProcessState {
     /// Process is registered with the scheduled because it is either new or has been joined.
     Inactive,

     /// Process is registered with the scheduler and participates in execution.
     Active,

     /// Process termination has been requested; threads are being terminated.
     Terminating,

     /// Process has no active threads and is terminated, waiting to be joined.
     Terminated,
 }

 pub(super) fn process_state_to_string(s: ProcessState) -> &'static str {
     match s {
         ProcessState::Inactive => "Inactive",
         ProcessState::Active => "Active",
         ProcessState::Terminating => "Terminating",
         ProcessState::Terminated => "Terminated",
     }
 }

 pub struct Process<K: Kernel> {
     // List of the processes in the system
     pub link: Link,

     // TODO - konkers: allow this to be tokenized.
     pub name: &'static str,

     pub(crate) memory_config: <K::ThreadState as ThreadState>::MemoryConfig,

     #[cfg(feature = "user_space")]
     object_table: ForeignBox<dyn ObjectTable<K>>,

     #[cfg(feature = "user_space")]
     pub object: Option<foreign_box::ForeignRc<K::AtomicUsize, crate::object::ProcessObject<K>>>,

     pub(super) thread_list: UnsafeList<Thread<K>, ProcessThreadListAdapter<K>>,

     pub(super) ref_count: K::AtomicUsize,
     pub(super) state: ProcessState,
     pub(super) join_event: Option<EventSignaler<K>>,
     pub(super) exit_status: Option<ExitStatus>,
 }

 // Safety: Process internal state is protected by the scheduler lock or atomic operations.
 unsafe impl<K: Kernel> Send for Process<K> {}
 unsafe impl<K: Kernel> Sync for Process<K> {}

 list::define_adapter!(pub ProcessListAdapter<K: Kernel> => Process<K>::link);
 list::define_adapter!(pub ProcessThreadListAdapter<K: Kernel> => Thread<K>::process_link);

 impl<K: Kernel> Process<K> {
     /// Creates a new, empty, unregistered process.
     #[must_use]
     pub const fn new(
         name: &'static str,
         memory_config: <K::ThreadState as ThreadState>::MemoryConfig,
         #[cfg(feature = "user_space")] object_table: ForeignBox<dyn ObjectTable<K>>,
     ) -> Self {
         Self {
             link: Link::new(),
             name,
             memory_config,
             #[cfg(feature = "user_space")]
             object_table,
             #[cfg(feature = "user_space")]
             object: None,
             thread_list: UnsafeList::new(),
             ref_count: K::AtomicUsize::ZERO,
             state: ProcessState::Inactive,
             join_event: None,
             exit_status: None,
         }
     }

     /// Manually increment the processes refcount
     ///
     /// SAFETY: This should only be done by the scheduler to maintain a
     /// virtual, reference on the kernel process during initialization.
     pub(super) unsafe fn manually_increment_ref_count(&mut self) {
         self.ref_count.fetch_add(1, Ordering::Acquire);
     }

     #[cfg(feature = "user_space")]
     pub fn get_object(
         &self,
         kernel: K,
         handle: u32,
     ) -> Option<ForeignRc<K::AtomicUsize, dyn KernelObject<K>>> {
         self.object_table.get_object(kernel, handle)
     }

     #[cfg(feature = "user_space")]
     pub fn reset_objects(&self, kernel: K) -> Result<()> {
         self.object_table.reset_all(kernel)
     }

     /// # Safety
     /// Caller must ensure exclusive access to the process and `thread` and all
     /// threads in the process' thread list.  This can be accomplished by holding
     /// the scheduler lock.
     pub unsafe fn add_to_thread_list(&mut self, thread: &mut Thread<K>) {
         // SAFETY: Caller guarantees exclusive access to the process and `thread`
         // and all threads in the process' thread list.
         unsafe {
             let thread = NonNull::from(thread);
             pw_assert::assert!(!self.thread_list.is_element_linked(thread));
             self.thread_list.push_front_unchecked(thread);
         }
     }

     pub fn range_has_access(&self, access_type: MemoryRegionType, range: Range<usize>) -> bool {
         self.memory_config
             .range_has_access(access_type, range.start, range.end)
     }

     /// A simple ID for debugging purposes, currently the pointer to the thread
     /// structure itself.
     ///
     /// # Safety
     ///
     /// The returned value should not be relied upon as being a valid pointer.
     /// Even in the current implementation, `id` does not expose the pointer's
     /// provenance.
     #[must_use]
     pub fn id(&self) -> usize {
         // Note: any changes to this also need to be reflected in
         // `const_id_from_process_address`.
         core::ptr::from_ref(self).addr()
     }

     /// Computes the ID of a process from its address.
     ///
     /// # Safety
     ///
     /// This exists to allow process annotations to be generated at compile time
     /// for static processes that are initialized at runtime. This should not be
     /// called in any other circumstance.
     #[must_use]
     pub const unsafe fn const_id_from_process_address(addr: *const ()) -> *const () {
         addr
     }

     pub fn dump(&self, kernel: K) {
         info!(
             "Process '{}' ({:#010x}) state: {}",
             self.name as &str,
             self.id() as usize,
             process_state_to_string(self.state) as &str
         );
         #[cfg(feature = "user_space")]
         {
             self.object_table.dump(kernel);
         }
         #[cfg(not(feature = "user_space"))]
         {
             // Suppress unused warning when user_space not enabled.
             let _ = kernel;
         }
         unsafe {
             let _ = self
                 .thread_list
                 .for_each(|thread| -> core::result::Result<(), ()> {
                     thread.dump();
                     Ok(())
                 });
         }
     }
 }

 pub struct ProcessHandle<K: Kernel> {
     pub(crate) process: NonNull<Process<K>>,
     kernel: K,
 }

 // Safety: ProcessHandle is a handle to a reference counted process.  All operations
 // on the process are protected by the scheduler lock or atomic operations.
 unsafe impl<K: Kernel> Send for ProcessHandle<K> {}
 unsafe impl<K: Kernel> Sync for ProcessHandle<K> {}

 impl<K: Kernel> ProcessHandle<K> {
     // `ProcessHandle`s should only be created when adding a process to the
     // scheduler.
     pub(super) fn new(process: NonNull<Process<K>>, kernel: K) -> Self {
         unsafe {
             process.as_ref().ref_count.fetch_add(1, Ordering::Acquire);
         }
         Self { process, kernel }
     }

     /// Request termination of the process.
     ///
     /// Sets the process state to Terminating and requests termination for all
     /// threads in the process.
     ///
     /// This is an ASYNCHRONOUS operation.
     pub fn terminate(&self, kernel: K, status: ExitStatus) {
         kernel
             .get_scheduler()
             .lock(kernel)
             .process_terminate(kernel, self, status);
     }

     /// Returns the current state of the process.
     #[must_use]
     pub fn get_state_locked(
         &self,
         _sched: &SpinLockGuard<'_, K, SchedulerState<K>>,
     ) -> ProcessState {
         // SAFETY: `self.process` is guaranteed to be valid because it is reference
         // counted.  The state is guaranteed to be coherent because the sched lock
         // is taken.
         unsafe { self.process.as_ref().state }
     }

     pub fn join(self, kernel: K) -> Result<(ForeignBox<Process<K>>, ExitStatus)> {
         match self.join_until(kernel, Instant::<K::Clock>::MAX) {
             crate::scheduler::ProcessJoinResult::Joined(process, status) => {
                 #[cfg(feature = "user_space")]
                 process.reset_objects(kernel)?;
                 Ok((process, status))
             }
             crate::scheduler::ProcessJoinResult::Err { error, .. } => Err(error),
         }
     }

     /// Attempts to join the referenced process.
     ///
     /// If `ProcessTryJoinResult::Joined` is returned, the caller is responsible
     /// for resetting the process's objects using `process.reset_objects(kernel)`.
     pub fn try_join(self, kernel: K) -> crate::scheduler::ProcessTryJoinResult<K> {
         let (_, res) = kernel
             .get_scheduler()
             .lock(kernel)
             .process_try_join(kernel, self, None);
         res
     }

     /// Join the referenced process with a deadline
     ///
     /// Waits until the all other references to the process are dropped and the
     /// process terminates.
     pub fn join_until(
         mut self,
         kernel: K,
         deadline: Instant<K::Clock>,
     ) -> crate::scheduler::ProcessJoinResult<K> {
         let join_event = Event::new(kernel, EventConfig::ManualReset);
         loop {
             let (_, res) = kernel.get_scheduler().lock(kernel).process_try_join(
                 kernel,
                 self,
                 Some(join_event.get_signaler()),
             );
             match res {
                 crate::scheduler::ProcessTryJoinResult::Err {
                     error: e,
                     process: process_handle,
                 } => {
                     return crate::scheduler::ProcessJoinResult::Err {
                         error: e,
                         process: process_handle,
                     };
                 }
                 crate::scheduler::ProcessTryJoinResult::Joined(process_box, status) => {
                     return crate::scheduler::ProcessJoinResult::Joined(process_box, status);
                 }
                 crate::scheduler::ProcessTryJoinResult::Wait(process_handle) => {
                     self = process_handle
                 }
             };

             if let Err(e) = join_event.wait_until(deadline) {
                 kernel
                     .get_scheduler()
                     .lock(kernel)
                     .process_cancel_try_join(&mut self);

                 return crate::scheduler::ProcessJoinResult::Err {
                     error: e,
                     process: self,
                 };
             }
         }
     }

     /// Drop the `ProcessHandle` while the scheduler lock is held.
     ///
     /// This is an internal version for use by the scheduler while it is holding
     /// the scheduler lock.
     pub(super) fn drop_locked(
         mut self,
         kernel: K,
         mut sched: SpinLockGuard<'_, K, SchedulerState<K>>,
     ) -> SpinLockGuard<'_, K, SchedulerState<K>> {
         unsafe {
             let prev_value = self
                 .process
                 .as_ref()
                 .ref_count
                 .fetch_sub(1, Ordering::Release);

             // If this ref was one of two outstanding references to the process,
             // the other reference may be attempting to join.  Let the scheduler
             // notify the join request if it is outstanding.
             if prev_value == 2 {
                 sched = sched.process_signal_join(kernel, &mut self);
             }
         }

         // Ensure that the trait version of drop is not run.
         let _ = ManuallyDrop::new(self);
         sched
     }

     pub fn add_thread(&mut self, kernel: K, thread_handle: &mut ThreadHandle<K>) -> Result<()> {
         kernel
             .get_scheduler()
             .lock(kernel)
             .process_add_thread(self, thread_handle)
     }

     pub fn range_has_access_locked(
         &self,
         _sched: &SpinLockGuard<'_, K, SchedulerState<K>>,
         region_type: MemoryRegionType,
         range: Range<usize>,
     ) -> bool {
         // SAFETY: `self.process` is valid because `ProcessHandle` guarantees the
         // lifetime of the pointed-to `Process`.
         unsafe { self.process.as_ref().range_has_access(region_type, range) }
     }
 }

 impl<K: Kernel> Clone for ProcessHandle<K> {
     fn clone(&self) -> Self {
         unsafe {
             self.process
                 .as_ref()
                 .ref_count
                 .fetch_add(1, Ordering::Acquire);
         }

         Self {
             process: self.process,
             kernel: self.kernel,
         }
     }
 }

 impl<K: Kernel> Drop for ProcessHandle<K> {
     fn drop(&mut self) {
         unsafe {
             let prev_value = self
                 .process
                 .as_ref()
                 .ref_count
                 .fetch_sub(1, Ordering::Release);

             // If this ref was one of two outstanding references to the process,
             // the other reference may be attempting to join.  Let the scheduler
             // notify the join request if it is outstanding.
             if prev_value == 2 {
                 let _ = self
                     .kernel
                     .get_scheduler()
                     .lock(self.kernel)
                     .process_signal_join(self.kernel, self);
             }
         }
     }
 }

 /// Add debug annotations for a static process
 ///
 /// This macro is called by `init_non_priv_process` and should not be called
 /// directly.
 #[macro_export]
 macro_rules! annotate_process_from_address {
     ($name:expr, $arch:ty, $process_address:expr) => {{
         #[repr(C, packed(1))]
         struct ProcessAnnotation {
             name: &'static str,
             id: *const (),
         }
         unsafe impl Sync for ProcessAnnotation {};

         #[unsafe(link_section = ".pw_kernel.annotations.process")]
         #[used]
         static _PROCESS_ANNOTATION: ProcessAnnotation = ProcessAnnotation {
             name: $name,
             id: unsafe {
                 $crate::Process::<$arch>::const_id_from_process_address(
                     $process_address as *const (),
                 )
             },
         };
     }};
 }

 /// Declare static storage for a non-privileged process.
 ///
 /// Creates a static in named `storage_ident` in the calling scope which holds
 /// the storage for a static process.
 #[cfg(feature = "user_space")]
 #[macro_export]
 macro_rules! declare_non_priv_process_storage {
     ($storage_ident:ident) => {
         static $storage_ident: $crate::__private::foreign_box::StaticStorage<
             $crate::scheduler::Process<arch::Arch>,
         > = $crate::__private::foreign_box::StaticStorage::new();
     };
 }

 /// Get the constant process ID of a non-privileged process.
 #[cfg(feature = "user_space")]
 #[macro_export]
 macro_rules! non_priv_process_id {
     ($storage:expr) => {{
         use $crate::scheduler::Process;
         unsafe {
             Process::<arch::Arch>::const_id_from_process_address(unsafe { $storage.address() })
         }
     }};
 }

 /// Declares a new [`Process`] in a previously declared static process storage.
 ///
 /// # Safety
 ///
 /// Each invocation of `declare_non_priv_process!` must be executed at most once at
 /// run time.
 #[cfg(feature = "user_space")]
 #[macro_export]
 macro_rules! declare_non_priv_process {
     ($storage:expr, $name:literal, $memory_config:expr, $object_table:expr $(,)?) => {{
         use $crate::__private::foreign_box::StaticStorage;
         use $crate::Kernel;
         use $crate::object::ObjectTable;
         use $crate::scheduler::Process;

         /// SAFETY: This must be executed at most once at run time.  See
         /// StaticStorage::init() for more details.
         #[allow(clippy::mut_from_ref)]
         unsafe fn __declare_non_priv_process(
             storage: &'static StaticStorage<Process<arch::Arch>>,
             object_table: ForeignBox<dyn ObjectTable<arch::Arch>>,
         ) -> ForeignBox<Process<arch::Arch>> {
             use pw_log::info;
             use $crate::__private::foreign_box::ForeignBox;
             info!(
                 "Allocating non-privileged process '{}'",
                 $name as &'static str
             );

             // SAFETY: The caller promises that this function will be executed
             // at most once.
             let proc = unsafe { storage.init(Process::new($name, $memory_config, object_table)) };
             ForeignBox::from(proc)
         }

         $crate::annotate_process_from_address!($name, arch::Arch, unsafe { $storage.address() });
         __declare_non_priv_process(&$storage, $object_table)
     }};
 }
	// Copyright 2026 The Pigweed Authors
	//
	// Licensed under the Apache License, Version 2.0 (the "License"); you may not
	// use this file except in compliance with the License. You may obtain a copy of
	// the License at
	//
	// https://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
	// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
	// License for the specific language governing permissions and limitations under
	// the License.

	use core::mem::ManuallyDrop;
	use core::ops::Range;
	use core::ptr::NonNull;
	use core::sync::atomic::Ordering;

	use exit_status::ExitStatus;
	#[cfg(not(feature = "user_space"))]
	use foreign_box::ForeignBox;
	#[cfg(feature = "user_space")]
	use foreign_box::{ForeignBox, ForeignRc};
	use list::*;
	use memory_config::{MemoryConfig as _, MemoryRegionType};
	use pw_atomic::{AtomicAdd, AtomicSub, AtomicZero};
	use pw_log::info;
	use pw_status::Result;
	use pw_time_core::Instant;

	use crate::Kernel;
	#[cfg(feature = "user_space")]
	use crate::object::{KernelObject, ObjectTable};
	use crate::scheduler::SchedulerState;
	use crate::scheduler::thread::{Thread, ThreadHandle, ThreadState};
	use crate::sync::event::{Event, EventConfig, EventSignaler};
	use crate::sync::spinlock::SpinLockGuard;

	/// Runtime state of a Process.
	#[derive(Copy, Clone, PartialEq)]
	pub enum ProcessState {
	/// Process is registered with the scheduled because it is either new or has been joined.
	Inactive,

	/// Process is registered with the scheduler and participates in execution.
	Active,

	/// Process termination has been requested; threads are being terminated.
	Terminating,

	/// Process has no active threads and is terminated, waiting to be joined.
	Terminated,
	}

	pub(super) fn process_state_to_string(s: ProcessState) -> &'static str {
	match s {
	ProcessState::Inactive => "Inactive",
	ProcessState::Active => "Active",
	ProcessState::Terminating => "Terminating",
	ProcessState::Terminated => "Terminated",
	}
	}

	pub struct Process<K: Kernel> {
	// List of the processes in the system
	pub link: Link,

	// TODO - konkers: allow this to be tokenized.
	pub name: &'static str,

	pub(crate) memory_config: <K::ThreadState as ThreadState>::MemoryConfig,

	#[cfg(feature = "user_space")]
	object_table: ForeignBox<dyn ObjectTable<K>>,

	#[cfg(feature = "user_space")]
	pub object: Option<foreign_box::ForeignRc<K::AtomicUsize, crate::object::ProcessObject<K>>>,

	pub(super) thread_list: UnsafeList<Thread<K>, ProcessThreadListAdapter<K>>,

	pub(super) ref_count: K::AtomicUsize,
	pub(super) state: ProcessState,
	pub(super) join_event: Option<EventSignaler<K>>,
	pub(super) exit_status: Option<ExitStatus>,
	}

	// Safety: Process internal state is protected by the scheduler lock or atomic operations.
	unsafe impl<K: Kernel> Send for Process<K> {}
	unsafe impl<K: Kernel> Sync for Process<K> {}

	list::define_adapter!(pub ProcessListAdapter<K: Kernel> => Process<K>::link);
	list::define_adapter!(pub ProcessThreadListAdapter<K: Kernel> => Thread<K>::process_link);

	impl<K: Kernel> Process<K> {
	/// Creates a new, empty, unregistered process.
	#[must_use]
	pub const fn new(
	name: &'static str,
	memory_config: <K::ThreadState as ThreadState>::MemoryConfig,
	#[cfg(feature = "user_space")] object_table: ForeignBox<dyn ObjectTable<K>>,
	) -> Self {
	Self {
	link: Link::new(),
	name,
	memory_config,
	#[cfg(feature = "user_space")]
	object_table,
	#[cfg(feature = "user_space")]
	object: None,
	thread_list: UnsafeList::new(),
	ref_count: K::AtomicUsize::ZERO,
	state: ProcessState::Inactive,
	join_event: None,
	exit_status: None,
	}
	}

	/// Manually increment the processes refcount
	///
	/// SAFETY: This should only be done by the scheduler to maintain a
	/// virtual, reference on the kernel process during initialization.
	pub(super) unsafe fn manually_increment_ref_count(&mut self) {
	self.ref_count.fetch_add(1, Ordering::Acquire);
	}

	#[cfg(feature = "user_space")]
	pub fn get_object(
	&self,
	kernel: K,
	handle: u32,
	) -> Option<ForeignRc<K::AtomicUsize, dyn KernelObject<K>>> {
	self.object_table.get_object(kernel, handle)
	}

	#[cfg(feature = "user_space")]
	pub fn reset_objects(&self, kernel: K) -> Result<()> {
	self.object_table.reset_all(kernel)
	}

	/// # Safety
	/// Caller must ensure exclusive access to the process and `thread` and all
	/// threads in the process' thread list. This can be accomplished by holding
	/// the scheduler lock.
	pub unsafe fn add_to_thread_list(&mut self, thread: &mut Thread<K>) {
	// SAFETY: Caller guarantees exclusive access to the process and `thread`
	// and all threads in the process' thread list.
	unsafe {
	let thread = NonNull::from(thread);
	pw_assert::assert!(!self.thread_list.is_element_linked(thread));
	self.thread_list.push_front_unchecked(thread);
	}
	}

	pub fn range_has_access(&self, access_type: MemoryRegionType, range: Range<usize>) -> bool {
	self.memory_config
	.range_has_access(access_type, range.start, range.end)
	}

	/// A simple ID for debugging purposes, currently the pointer to the thread
	/// structure itself.
	///
	/// # Safety
	///
	/// The returned value should not be relied upon as being a valid pointer.
	/// Even in the current implementation, `id` does not expose the pointer's
	/// provenance.
	#[must_use]
	pub fn id(&self) -> usize {
	// Note: any changes to this also need to be reflected in
	// `const_id_from_process_address`.
	core::ptr::from_ref(self).addr()
	}

	/// Computes the ID of a process from its address.
	///
	/// # Safety
	///
	/// This exists to allow process annotations to be generated at compile time
	/// for static processes that are initialized at runtime. This should not be
	/// called in any other circumstance.
	#[must_use]
	pub const unsafe fn const_id_from_process_address(addr: const ()) -> const () {
	addr
	}

	pub fn dump(&self, kernel: K) {
	info!(
	"Process '{}' ({:#010x}) state: {}",
	self.name as &str,
	self.id() as usize,
	process_state_to_string(self.state) as &str
	);
	#[cfg(feature = "user_space")]
	{
	self.object_table.dump(kernel);
	}
	#[cfg(not(feature = "user_space"))]
	{
	// Suppress unused warning when user_space not enabled.
	let _ = kernel;
	}
	unsafe {
	let _ = self
	.thread_list
	.for_each(\|thread\| -> core::result::Result<(), ()> {
	thread.dump();
	Ok(())
	});
	}
	}
	}

	pub struct ProcessHandle<K: Kernel> {
	pub(crate) process: NonNull<Process<K>>,
	kernel: K,
	}

	// Safety: ProcessHandle is a handle to a reference counted process. All operations
	// on the process are protected by the scheduler lock or atomic operations.
	unsafe impl<K: Kernel> Send for ProcessHandle<K> {}
	unsafe impl<K: Kernel> Sync for ProcessHandle<K> {}

	impl<K: Kernel> ProcessHandle<K> {
	// `ProcessHandle`s should only be created when adding a process to the
	// scheduler.
	pub(super) fn new(process: NonNull<Process<K>>, kernel: K) -> Self {
	unsafe {
	process.as_ref().ref_count.fetch_add(1, Ordering::Acquire);
	}
	Self { process, kernel }
	}

	/// Request termination of the process.
	///
	/// Sets the process state to Terminating and requests termination for all
	/// threads in the process.
	///
	/// This is an ASYNCHRONOUS operation.
	pub fn terminate(&self, kernel: K, status: ExitStatus) {
	kernel
	.get_scheduler()
	.lock(kernel)
	.process_terminate(kernel, self, status);
	}

	/// Returns the current state of the process.
	#[must_use]
	pub fn get_state_locked(
	&self,
	_sched: &SpinLockGuard<'_, K, SchedulerState<K>>,
	) -> ProcessState {
	// SAFETY: `self.process` is guaranteed to be valid because it is reference
	// counted. The state is guaranteed to be coherent because the sched lock
	// is taken.
	unsafe { self.process.as_ref().state }
	}

	pub fn join(self, kernel: K) -> Result<(ForeignBox<Process<K>>, ExitStatus)> {
	match self.join_until(kernel, Instant::<K::Clock>::MAX) {
	crate::scheduler::ProcessJoinResult::Joined(process, status) => {
	#[cfg(feature = "user_space")]
	process.reset_objects(kernel)?;
	Ok((process, status))
	}
	crate::scheduler::ProcessJoinResult::Err { error, .. } => Err(error),
	}
	}

	/// Attempts to join the referenced process.
	///
	/// If `ProcessTryJoinResult::Joined` is returned, the caller is responsible
	/// for resetting the process's objects using `process.reset_objects(kernel)`.
	pub fn try_join(self, kernel: K) -> crate::scheduler::ProcessTryJoinResult<K> {
	let (_, res) = kernel
	.get_scheduler()
	.lock(kernel)
	.process_try_join(kernel, self, None);
	res
	}

	/// Join the referenced process with a deadline
	///
	/// Waits until the all other references to the process are dropped and the
	/// process terminates.
	pub fn join_until(
	mut self,
	kernel: K,
	deadline: Instant<K::Clock>,
	) -> crate::scheduler::ProcessJoinResult<K> {
	let join_event = Event::new(kernel, EventConfig::ManualReset);
	loop {
	let (_, res) = kernel.get_scheduler().lock(kernel).process_try_join(
	kernel,
	self,
	Some(join_event.get_signaler()),
	);
	match res {
	crate::scheduler::ProcessTryJoinResult::Err {
	error: e,
	process: process_handle,
	} => {
	return crate::scheduler::ProcessJoinResult::Err {
	error: e,
	process: process_handle,
	};
	}
	crate::scheduler::ProcessTryJoinResult::Joined(process_box, status) => {
	return crate::scheduler::ProcessJoinResult::Joined(process_box, status);
	}
	crate::scheduler::ProcessTryJoinResult::Wait(process_handle) => {
	self = process_handle
	}
	};

	if let Err(e) = join_event.wait_until(deadline) {
	kernel
	.get_scheduler()
	.lock(kernel)
	.process_cancel_try_join(&mut self);

	return crate::scheduler::ProcessJoinResult::Err {
	error: e,
	process: self,
	};
	}
	}
	}

	/// Drop the `ProcessHandle` while the scheduler lock is held.
	///
	/// This is an internal version for use by the scheduler while it is holding
	/// the scheduler lock.
	pub(super) fn drop_locked(
	mut self,
	kernel: K,
	mut sched: SpinLockGuard<'_, K, SchedulerState<K>>,
	) -> SpinLockGuard<'_, K, SchedulerState<K>> {
	unsafe {
	let prev_value = self
	.process
	.as_ref()
	.ref_count
	.fetch_sub(1, Ordering::Release);

	// If this ref was one of two outstanding references to the process,
	// the other reference may be attempting to join. Let the scheduler
	// notify the join request if it is outstanding.
	if prev_value == 2 {
	sched = sched.process_signal_join(kernel, &mut self);
	}
	}

	// Ensure that the trait version of drop is not run.
	let _ = ManuallyDrop::new(self);
	sched
	}

	pub fn add_thread(&mut self, kernel: K, thread_handle: &mut ThreadHandle<K>) -> Result<()> {
	kernel
	.get_scheduler()
	.lock(kernel)
	.process_add_thread(self, thread_handle)
	}

	pub fn range_has_access_locked(
	&self,
	_sched: &SpinLockGuard<'_, K, SchedulerState<K>>,
	region_type: MemoryRegionType,
	range: Range<usize>,
	) -> bool {
	// SAFETY: `self.process` is valid because `ProcessHandle` guarantees the
	// lifetime of the pointed-to `Process`.
	unsafe { self.process.as_ref().range_has_access(region_type, range) }
	}
	}

	impl<K: Kernel> Clone for ProcessHandle<K> {
	fn clone(&self) -> Self {
	unsafe {
	self.process
	.as_ref()
	.ref_count
	.fetch_add(1, Ordering::Acquire);
	}

	Self {
	process: self.process,
	kernel: self.kernel,
	}
	}
	}

	impl<K: Kernel> Drop for ProcessHandle<K> {
	fn drop(&mut self) {
	unsafe {
	let prev_value = self
	.process
	.as_ref()
	.ref_count
	.fetch_sub(1, Ordering::Release);

	// If this ref was one of two outstanding references to the process,
	// the other reference may be attempting to join. Let the scheduler
	// notify the join request if it is outstanding.
	if prev_value == 2 {
	let _ = self
	.kernel
	.get_scheduler()
	.lock(self.kernel)
	.process_signal_join(self.kernel, self);
	}
	}
	}
	}

	/// Add debug annotations for a static process
	///
	/// This macro is called by `init_non_priv_process` and should not be called
	/// directly.
	#[macro_export]
	macro_rules! annotate_process_from_address {
	($name:expr, $arch:ty, $process_address:expr) => {{
	#[repr(C, packed(1))]
	struct ProcessAnnotation {
	name: &'static str,
	id: *const (),
	}
	unsafe impl Sync for ProcessAnnotation {};

	#[unsafe(link_section = ".pw_kernel.annotations.process")]
	#[used]
	static _PROCESS_ANNOTATION: ProcessAnnotation = ProcessAnnotation {
	name: $name,
	id: unsafe {
	$crate::Process::<$arch>::const_id_from_process_address(
	$process_address as *const (),
	)
	},
	};
	}};
	}

	/// Declare static storage for a non-privileged process.
	///
	/// Creates a static in named `storage_ident` in the calling scope which holds
	/// the storage for a static process.
	#[cfg(feature = "user_space")]
	#[macro_export]
	macro_rules! declare_non_priv_process_storage {
	($storage_ident:ident) => {
	static $storage_ident: $crate::__private::foreign_box::StaticStorage<
	$crate::scheduler::Process<arch::Arch>,
	> = $crate::__private::foreign_box::StaticStorage::new();
	};
	}

	/// Get the constant process ID of a non-privileged process.
	#[cfg(feature = "user_space")]
	#[macro_export]
	macro_rules! non_priv_process_id {
	($storage:expr) => {{
	use $crate::scheduler::Process;
	unsafe {
	Process::<arch::Arch>::const_id_from_process_address(unsafe { $storage.address() })
	}
	}};
	}

	/// Declares a new [`Process`] in a previously declared static process storage.
	///
	/// # Safety
	///
	/// Each invocation of `declare_non_priv_process!` must be executed at most once at
	/// run time.
	#[cfg(feature = "user_space")]
	#[macro_export]
	macro_rules! declare_non_priv_process {
	($storage:expr, $name:literal, $memory_config:expr, $object_table:expr $(,)?) => {{
	use $crate::__private::foreign_box::StaticStorage;
	use $crate::Kernel;
	use $crate::object::ObjectTable;
	use $crate::scheduler::Process;

	/// SAFETY: This must be executed at most once at run time. See
	/// StaticStorage::init() for more details.
	#[allow(clippy::mut_from_ref)]
	unsafe fn __declare_non_priv_process(
	storage: &'static StaticStorage<Process<arch::Arch>>,
	object_table: ForeignBox<dyn ObjectTable<arch::Arch>>,
	) -> ForeignBox<Process<arch::Arch>> {
	use pw_log::info;
	use $crate::__private::foreign_box::ForeignBox;
	info!(
	"Allocating non-privileged process '{}'",
	$name as &'static str
	);

	// SAFETY: The caller promises that this function will be executed
	// at most once.
	let proc = unsafe { storage.init(Process::new($name, $memory_config, object_table)) };
	ForeignBox::from(proc)
	}

	$crate::annotate_process_from_address!($name, arch::Arch, unsafe { $storage.address() });
	__declare_non_priv_process(&$storage, $object_table)
	}};
	}