zephyr/sys/
sync.rs

1// Copyright (c) 2024 Linaro LTD
2// SPDX-License-Identifier: Apache-2.0
3
4//! # Zephyr low-level synchronization primities.
5//!
6//! The `zephyr-sys` crate contains direct calls into the Zephyr C API.  This interface, however,
7//! cannot be used from safe Rust.  This crate attempts to be as direct an interface to some of
8//! these synchronization mechanisms, but without the need for unsafe.  The other module
9//! `crate::sync` provides higher level interfaces that help manage synchronization in coordination
10//! with Rust's borrowing and sharing rules, and will generally provide much more usable
11//! interfaces.
12//!
13//! # Kernel objects
14//!
15//! Zephyr's primitives work with the concept of a kernel object.  These are the data structures
16//! that are used by the Zephyr kernel to coordinate the operation of the primitives.  In addition,
17//! they are where the protection barrier provided by `CONFIG_USERSPACE` is implemented.  In order
18//! to use these primitives from a userspace thread two things must happen:
19//!
20//! - The kernel objects must be specially declared.  All kernel objects in Zephyr will be built,
21//!   at compile time, into a perfect hash table that is used to validate them.  The special
22//!   declaration will take care of this.
23//! - The objects must be granted permission to be used by the userspace thread.  This can be
24//!   managed either by specifically granting permission, or by using inheritance when creating the
25//!   thread.
26//!
27//! At this time, only the first mechanism is implemented, and all kernel objects should be
28//! declared using the `crate::kobj_define!` macro.  These then must be initialized, and then the
29//! special method `.get()` called, to retrieve the Rust-style value that is used to manage them.
30//! Later, there will be a pool mechanism to allow these kernel objects to be allocated and freed
31//! from a pool, although the objects will still be statically allocated.
32
33pub mod mutex;
34pub mod semaphore;
35
36pub use mutex::{Condvar, Mutex, StaticCondvar, StaticMutex};
37pub use semaphore::Semaphore;