doc(core): document r3::kernel::raw_cfg

Author: yvt

src/r3_core/src/kernel/raw_cfg.rs

@@ -3,15 +3,20 @@
 //!
 //! # General Structure
 //!
-//! TODO
+//! This module includes the traits for a kernel-specific low-level configurator
+//! type, which is used by [the kernel static configuration process][1] to
+//! receive the specificiations of defined kernel objects and assign their IDs.
+//! [`CfgBase`][] is the supertrait of all these traits and must be implemented
+//! by the configurator type. It can optionally can implement other traits as
+//! well if they can be supported.
 //!
-//! The `Cfg${TY}` traits extend [`CfgBase`] by providing a
-//! method to define a kernel object of the corresponding type (`${TY}`). The
-//! method takes two parameters: `${TY}Descriptor` containing mandatory
-//! properties and `impl `[`Bag`] containing additional, implementation-specific
-//! properties.
+//! The `Cfg${Ty}` traits extend [`CfgBase`] by providing a
+//! method named `${ty}_define` to define a kernel object of the corresponding
+//! type (`${Ty}`). The method takes two parameters: `${Ty}Descriptor`
+//! containing mandatory properties and `impl `[`Bag`] containing additional,
+//! implementation-specific properties.
 //!
-//! The `${TY}Descriptor` types contain mandatory (both for the consumers and
+//! The `${Ty}Descriptor` types contain mandatory (both for the consumers and
 //! the implementors) properties of a kernel object to be created. They all
 //! contain a `phantom: `[`PhantomInvariant`]`<System>` field to ensure they are
 //! always parameterized and invariant over `System`.
@@ -21,8 +26,33 @@
 //! Most traits in this method are `unsafe trait` because they have to be
 //! trustworthy to be able to build sound memory-safe abstractions on top of
 //! them.
+//!
+//! # Stability
+//!
+//! This module is covered by the kernel-side API stability guarantee.
+//!
+//! The trait paths in this module are covered by the application-side API
+//! stability guarantee. Application code should only use these traits in trait
+//! bounds and, to access the provided functionalities, should use the the
+//! stable wrapper [outside this module](../index.html) instead.
+//!
+//! [1]: crate::kernel::cfg::KernelStatic
 use crate::{bag::Bag, closure::Closure, kernel::raw, time::Duration, utils::PhantomInvariant};
 
+/// The trait for all kernel-specific low-level configurator types, used by
+/// [the kernel static configuration process][2].
+///
+/// # Safety
+///
+/// See [the module documentation][4].
+///
+/// # Stability
+///
+/// See [the module documentation][3].
+///
+/// [2]: crate::kernel::cfg::KernelStatic
+/// [3]: self#stability
+/// [4]: self#safety
 pub unsafe trait CfgBase {
     type System: raw::KernelBase;
     fn num_task_priority_levels(&mut self, new_value: usize);
@@ -35,6 +65,21 @@ pub unsafe trait CfgBase {
     fn startup_hook_define(&mut self, func: fn());
 }
 
+/// A low-level configurator trait providing a method to define a
+/// [task][1] in [the kernel static configuration process][2].
+///
+/// # Safety
+///
+/// See [the module documentation][4].
+///
+/// # Stability
+///
+/// See [the module documentation][3].
+///
+/// [1]: crate::kernel::StaticTask
+/// [2]: crate::kernel::cfg::KernelStatic
+/// [3]: self#stability
+/// [4]: self#safety
 // The supertrait can't be `~const` due to [ref:const_supertraits]
 pub unsafe trait CfgTask: CfgBase {
     fn task_define<Properties: ~const Bag>(
@@ -54,6 +99,21 @@ pub struct TaskDescriptor<System> {
     pub stack_size: Option<usize>,
 }
 
+/// A low-level configurator trait providing a method to define an
+/// [event group][2] in [the kernel static configuration process][1].
+///
+/// # Safety
+///
+/// See [the module documentation][4].
+///
+/// # Stability
+///
+/// See [the module documentation][3].
+///
+/// [1]: crate::kernel::StaticEventGroup
+/// [2]: crate::kernel::cfg::KernelStatic
+/// [3]: self#stability
+/// [4]: self#safety
 // The supertrait can't be `~const` due to [ref:const_supertraits]
 pub unsafe trait CfgEventGroup: CfgBase
 where
@@ -74,6 +134,21 @@ pub struct EventGroupDescriptor<System> {
     pub queue_order: raw::QueueOrder,
 }
 
+/// A low-level configurator trait providing a method to define a
+/// [mutex][2] in [the kernel static configuration process][1].
+///
+/// # Safety
+///
+/// See [the module documentation][4].
+///
+/// # Stability
+///
+/// See [the module documentation][3].
+///
+/// [1]: crate::kernel::StaticMutex
+/// [2]: crate::kernel::cfg::KernelStatic
+/// [3]: self#stability
+/// [4]: self#safety
 // The supertrait can't be `~const` due to [ref:const_supertraits]
 pub unsafe trait CfgMutex: CfgBase
 where
@@ -93,6 +168,21 @@ pub struct MutexDescriptor<System> {
     pub protocol: raw::MutexProtocol,
 }
 
+/// A low-level configurator trait providing a method to define a
+/// [semaphore][2] in [the kernel static configuration process][1].
+///
+/// # Safety
+///
+/// See [the module documentation][4].
+///
+/// # Stability
+///
+/// See [the module documentation][3].
+///
+/// [1]: crate::kernel::StaticSemaphore
+/// [2]: crate::kernel::cfg::KernelStatic
+/// [3]: self#stability
+/// [4]: self#safety
 // The supertrait can't be `~const` due to [ref:const_supertraits]
 pub unsafe trait CfgSemaphore: CfgBase
 where
@@ -114,6 +204,21 @@ pub struct SemaphoreDescriptor<System> {
     pub queue_order: raw::QueueOrder,
 }
 
+/// A low-level configurator trait providing a method to define a
+/// [timwer][2] in [the kernel static configuration process][1].
+///
+/// # Safety
+///
+/// See [the module documentation][4].
+///
+/// # Stability
+///
+/// See [the module documentation][3].
+///
+/// [1]: crate::kernel::StaticTimer
+/// [2]: crate::kernel::cfg::KernelStatic
+/// [3]: self#stability
+/// [4]: self#safety
 // The supertrait can't be `~const` due to [ref:const_supertraits]
 pub unsafe trait CfgTimer: CfgBase
 where
@@ -136,6 +241,21 @@ pub struct TimerDescriptor<System> {
     pub period: Option<Duration>,
 }
 
+/// A low-level configurator trait providing a method to define an
+/// [interrupt line][2] in [the kernel static configuration process][1].
+///
+/// # Safety
+///
+/// See [the module documentation][4].
+///
+/// # Stability
+///
+/// See [the module documentation][3].
+///
+/// [1]: crate::kernel::InterruptLine
+/// [2]: crate::kernel::cfg::KernelStatic
+/// [3]: self#stability
+/// [4]: self#safety
 // The supertrait can't be `~const` due to [ref:const_supertraits]
 pub unsafe trait CfgInterruptLine: CfgBase
 where