libkernel: add documentation and cargo metadata

Fix up missing documentaiton and add metadata to the cargo definition.

libkernel/src/sync/condvar.rs

@@ -1,3 +1,5 @@
+//! Async-aware condition variable.
+
 use super::spinlock::SpinLockIrq;
 use super::waker_set::WakerSet;
 use crate::CpuOps;
@@ -5,8 +7,11 @@ use alloc::sync::Arc;
 
 /// The type of wakeup that should occur after a state update.
 pub enum WakeupType {
+    /// Do not wake any waiting task.
     None,
+    /// Wake exactly one waiting task.
     One,
+    /// Wake all waiting tasks.
     All,
 }
 

libkernel/src/sync/mod.rs

@@ -1,3 +1,8 @@
+//! Synchronisation primitives for `no_std` kernel environments.
+//!
+//! All primitives are generic over [`CpuOps`](crate::CpuOps) so they can
+//! disable/restore interrupts on the local core.
+
 pub mod condvar;
 pub mod mpsc;
 pub mod mutex;

libkernel/src/sync/mutex.rs

@@ -1,3 +1,5 @@
+//! Async-aware mutual-exclusion lock.
+
 use alloc::collections::VecDeque;
 use core::cell::UnsafeCell;
 use core::future::Future;

libkernel/src/sync/once_lock.rs

@@ -1,3 +1,5 @@
+//! A thread-safe cell that is initialized exactly once.
+
 use core::fmt;
 
 use crate::CpuOps;

libkernel/src/sync/per_cpu.rs

@@ -65,6 +65,7 @@ where
     }
 }
 
+/// A mutable borrow of per-CPU data that restores interrupts on drop.
 pub struct IrqSafeRefMut<'a, T, CPU: CpuOps> {
     borrow: ManuallyDrop<RefMut<'a, T>>,
     flags: usize,
@@ -198,6 +199,7 @@ impl<T: Send, CPU: CpuOps> PerCpu<RefCell<T>, CPU> {
         }
     }
 
+    /// Attempts to mutably borrow the per-CPU data, returning `None` if already borrowed.
     #[track_caller]
     pub fn try_borrow_mut(&self) -> Option<IrqGuard<RefMut<'_, T>, CPU>> {
         let flags = CPU::disable_interrupts();
@@ -225,6 +227,7 @@ impl<T: Send, CPU: CpuOps> PerCpu<RefCell<T>, CPU> {
 }
 
 impl<T: Send + Sync, CPU: CpuOps> PerCpu<T, CPU> {
+    /// Returns a reference to the data for the given CPU.
     pub fn get_by_cpu(&self, cpu_id: usize) -> &T {
         unsafe { self.get_for_cpu(cpu_id) }
     }

libkernel/src/sync/rwlock.rs

@@ -1,3 +1,5 @@
+//! Async-aware readers–writer lock.
+
 use super::spinlock::SpinLockIrq;
 use crate::CpuOps;
 use crate::sync::mutex::Mutex;

libkernel/src/sync/spinlock.rs

@@ -1,3 +1,5 @@
+//! Low-level spin lock primitives.
+
 use core::cell::UnsafeCell;
 use core::hint::spin_loop;
 use core::marker::PhantomData;

libkernel/src/sync/waker_set.rs

@@ -1,3 +1,5 @@
+//! Waker registration and notification set.
+
 use alloc::collections::BTreeMap;
 use alloc::sync::Arc;
 use core::{
@@ -9,6 +11,7 @@ use crate::CpuOps;
 
 use super::spinlock::SpinLockIrq;
 
+/// A set of registered [`Waker`]s that can be selectively or collectively woken.
 pub struct WakerSet<T = ()> {
     waiters: BTreeMap<u64, (Waker, T)>,
     next_id: u64,
@@ -21,6 +24,7 @@ impl Default for WakerSet {
 }
 
 impl<T> WakerSet<T> {
+    /// Creates a new, empty waker set.
     pub fn new() -> Self {
         Self {
             waiters: BTreeMap::new(),
@@ -38,6 +42,7 @@ impl<T> WakerSet<T> {
         id
     }
 
+    /// Returns `true` if the given token is still registered in the set.
     pub fn contains_token(&self, token: u64) -> bool {
         self.waiters.contains_key(&token)
     }
@@ -84,6 +89,7 @@ impl<T> WakerSet<T> {
         }
     }
 
+    /// Registers a waker together with associated data, returning its token.
     pub fn register_with_data(&mut self, waker: &Waker, data: T) -> u64 {
         let id = self.allocate_id();