KSync: Technical Design Document

This document covers the technical architecture, safety invariants, and macro code generation details of the ksync crate.

1. Technical Architecture

ksync implements a token-based synchronization pattern (also known as the “Ghost Token” pattern). Instead of encapsulating the protected data inside the mutex or reader-writer lock struct itself (like std::sync::Mutex<T>), it separates the lock state (KMutex, BrwLockPi) from the actual data storage (KCell).

+-------------------------------------------------------------+
|                        Parent Struct                        |
|                                                             |
|   +-------------------+        +------------------------+   |
|   | KMutex/BrwLockPi  |        |  KCell<T, Class>       |   |
|   |  (Raw Lock State) |        |  (UnsafeCell wrapper)  |   |
|   +--------+----------+        +-----------+------------+   |
+------------|-------------------------------|----------------+
             | lock() / read_lock()          | get(token)
             v                               v
    +--------+------------+         +--------+-------+
    |  Lock Guard         |         |  &T / &mut T   |
    |                     |-------->|  (Safe Access) |
    |  - LockToken        |         +----------------+
    +---------------------+

The Core Types

  1. LockToken<'a, Class>: A zero-sized type (ZST) that serves as compile-time proof that the lock for Class is currently held by the current thread. It has a lifetime 'a bound to the active lock guard.
  2. KMutex<Class, M>: The mutual exclusion lock state representation, wrapping a raw lock M: RawLock. Locking it acquires the raw lock and returns a KMutexGuard holding the LockToken. There is no default M: the kernel's TrackedMutex is not part of this crate (see Raw lock implementations).
  3. BrwLockPi<Class, L>: The priority-inheriting reader-writer lock state representation, wrapping a raw reader-writer lock L: RawSharedLock (again with no default). Locking it returns a BrwLockPiReadGuard or BrwLockPiWriteGuard holding the LockToken.
  4. KCell<T, Class>: A wrapper around core::cell::UnsafeCell<T>. It provides token-gated accessors (get(&self, token) and get_mut(&self, token)).

Guard Types & The Instance-Bound Soundness Model

While the LockToken and KCell share a compile-time Class type parameter to prevent mixing locks of different types, this type-level association is insufficient to guarantee memory safety.

To provide safety, the macro generates custom guard structures (e.g. MyStructMuGuard, MyStructLockReadGuard, MyStructLockWriteGuard) that wrap standard lock guards and hold a reference to the parent structure instance. These custom guards expose safe, compiler-checked projection accessors (such as .field() or .fields_mut()). This guarantees safe access to guarded fields without requiring any unsafe block or risking cross-instance token mixing.

Raw Lock Implementations

ksync is split into two parts:

  • The ksync crate (//src/lib/ksync:ksync) holds the lock traits (RawLock, RawSharedLock, LockPolicy, ...), the generic lock types (KMutex, BrwLockPi, KCell, ...), the macros, and the userspace raw locks used for host builds and tests.
  • The kernel's raw locks (TrackedMutex, TrackedCriticalMutex, TrackedSpinlock, TrackedMonitoredSpinlock, TrackedBrwLockPi, TrackedBrwLockNoPi), their policies, the KSpinlock / KMonitoredSpinlock aliases, and the declare_singleton_mutex!, declare_singleton_critical_mutex!, declare_singleton_spinlock! and declare_singleton_monitored_spinlock! macros live in //zircon/kernel/lib/ksync. This is a kernel_rust_mod that is compiled directly into the kernel crate and mounted at crate::ksync_kernel. The mutexes are implemented directly on the Rust kernel Mutex in //zircon/kernel/kernel/mutex.rs, the spinlocks on the Rust kernel SpinLock and MonitoredSpinLock in //zircon/kernel/kernel/spinlock.rs, and the reader-writer locks on the Rust kernel BrwLockPi and BrwLockNoPi in //zircon/kernel/kernel/brwlock.rs, and re-exported from crate::ksync_kernel.

As a result, neither the ksync crate nor any other non-kernel crate (such as fbl or region_alloc) can name the kernel's raw locks. Generic code is instead parameterized over its raw lock type (M: RawLock), and the final usage site in the kernel crate supplies the concrete raw lock (e.g. crate::ksync_kernel::TrackedMutex). For the same reason there is no default raw lock type: KMutex and BrwLockPi fields in a #[guarded] struct (e.g. KMutex<TrackedSpinlock> or BrwLockPi<TrackedBrwLockPi>) and declare_singleton_lock! must always name their raw lock type explicitly.

2. Safe Exclusive Access

If a thread has unique exclusive access to the KCell container itself (either by holding ownership self or an exclusive borrow &mut self), it doesn't need a runtime lock token to access the data safely. The Rust borrow checker already guarantees compile-time thread exclusivity:

  • get_inner_mut(&mut self) -> &mut T: Accesses the inner value mutably via UnsafeCell::get_mut(). This is safe because the &mut self borrow ensures no other borrows of the cell are active.
  • into_inner(self) -> T: Consumes the KCell container and returns the inner value T safely via UnsafeCell::into_inner().

3. Macro Code Generation

The #[guarded] attribute proc-macro parses a struct definition, rewrites its fields, and generates the lock acquisition methods.

3.1 Input Struct

#[guarded]
pub struct MyStruct {
    #[mutex]
    pub mu: KMutex<TrackedMutex>,

    #[brwlock]
    pub lock: BrwLockPi<TrackedBrwLockPi>,

    #[guarded_by(mu)]
    pub data1: u32,

    #[guarded_by(lock)]
    pub data2: i32,
}

3.2 Expanded Code Output (Simplified)

// 1. Unique Lock Class marker structs generated automatically
pub struct MyStructMuClass;
pub struct MyStructLockClass;

// 2. Struct fields rewritten to KMutex/BrwLockPi and KCell
pub struct MyStruct {
    pub mu: ::ksync::KMutex<MyStructMuClass, TrackedMutex>,
    pub lock: ::ksync::BrwLockPi<MyStructLockClass, TrackedBrwLockPi>,
    pub data1: ::ksync::KCell<u32, MyStructMuClass>,
    pub data2: ::ksync::KCell<i32, MyStructLockClass>,
}

// 3. Custom projection guard structures (stack-pinned)
pub struct MyStructMuGuard<'a> {
    parent: &'a MyStruct,
    inner: ::ksync::KMutexGuard<'a, MyStructMuClass, TrackedMutex>,
    _pin: ::core::marker::PhantomPinned,
}

pub struct MyStructLockReadGuard<'a> {
    parent: &'a MyStruct,
    inner: ::ksync::BrwLockPiReadGuard<'a, MyStructLockClass, TrackedBrwLockPi>,
    _pin: ::core::marker::PhantomPinned,
}

pub struct MyStructLockWriteGuard<'a> {
    parent: &'a MyStruct,
    inner: ::ksync::BrwLockPiWriteGuard<'a, MyStructLockClass, TrackedBrwLockPi>,
    _pin: ::core::marker::PhantomPinned,
}

// 4. Safe projection accessors and field projection structs
pub struct MyStructLockReadFields<'b> {
    pub data2: &'b i32,
    _marker: ::core::marker::PhantomData<&'b ()>,
}

pub struct MyStructLockWriteFields<'b> {
    pub data2: &'b mut i32,
    _marker: ::core::marker::PhantomData<&'b ()>,
}

impl<'a> MyStructMuGuard<'a> {
    pub fn data1(&self) -> &u32 {
        unsafe { self.parent.data1.get(self.inner.token()) }
    }
    pub fn data1_mut(self: Pin<&mut Self>) -> &mut u32 { ... }
    pub fn fields<'b>(&'b self) -> MyStructMuFields<'b> { ... }
    pub fn fields_mut<'b>(self: Pin<&'b mut Self>) -> MyStructMuFieldsMut<'b> { ... }
}

impl<'a> MyStructLockReadGuard<'a> {
    pub fn data2(&self) -> &i32 {
        unsafe { self.parent.data2.get(self.inner.token()) }
    }
    pub fn fields<'b>(&'b self) -> MyStructLockReadFields<'b> { ... }
}

impl<'a> MyStructLockWriteGuard<'a> {
    pub fn data2(&self) -> &i32 {
        unsafe { self.parent.data2.get(self.inner.token()) }
    }
    pub fn data2_mut(self: Pin<&mut Self>) -> &mut i32 { ... }
    pub fn fields<'b>(&'b self) -> MyStructLockReadFields<'b> { ... }
    pub fn fields_mut<'b>(self: Pin<&'b mut Self>) -> MyStructLockWriteFields<'b> { ... }
}

// 5. Lock methods implemented on the parent struct returning PinInit blocks
impl MyStruct {
    #[inline(always)]
    pub fn lock_mu(&self) -> impl pin_init::PinInit<MyStructMuGuard<'_>, ::core::convert::Infallible> {
        MyStructMuGuard::__new(self, ::ksync::KMutexGuard::new(&self.mu))
    }

    #[inline(always)]
    pub fn read_lock(&self) -> impl pin_init::PinInit<MyStructLockReadGuard<'_>, ::core::convert::Infallible> {
        MyStructLockReadGuard::__new(self, ::ksync::BrwLockPiReadGuard::new(&self.lock))
    }

    #[inline(always)]
    pub fn write_lock(&self) -> impl pin_init::PinInit<MyStructLockWriteGuard<'_>, ::core::convert::Infallible> {
        MyStructLockWriteGuard::__new(self, ::ksync::BrwLockPiWriteGuard::new(&self.lock))
    }
}