blob: 3e2b73cf3fd2a76d4cd543b8a8bd381719365c34 [file] [view]
# 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](#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
```rust
#[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)
```rust
// 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))
}
}
```