repository·main·Indexed 20 days ago
https://github.com/hawkw/myceliumAn experimental microkernel-based operating system written in Rust using WebAssembly and WASI. The project includes several supporting libraries: mycelium-bitfield for structured bitfields and integer range packing; Cordyceps for intrusive data structures like doubly-linked lists and lock-free MPSC queues; and maitake-sync, a collection of asynchronous synchronization primitives (Mutex, RwLock, Semaphore) designed for #![no_std] environments.
maitake-sync is a collection of asynchronous synchronization primitives for Rust, built on core::task and core::future. It is designed primarily for #![no_std] environments, such as bare-metal operating systems, embedded systems, and OS components. It provides tools to coordinate tasks by allowing them to yield to a runtime scheduler while waiting for resources.mycelium-util is a "standard library" crate containing general-purpose utility types and traits designed specifically for the Mycelium operating system and its related libraries.
Note for non-Mycelium users: This crate is primarily intended for use within the Mycelium ecosystem. It may contain Mycelium-specific design decisions or quirks. Because it is tightly coupled to the OS development, breaking changes may occur frequently, and older major versions are generally not supported.
maitake is a modular async runtime construction kit for Rust, specifically designed for #![no_std] and bare-metal projects (like operating systems or embedded systems).
Unlike complete runtimes such as tokio or async-std, maitake does not provide a single, monolithic runtime. Instead, it offers reusable, low-level components that you can combine to build a custom, application-specific async runtime. This allows for direct control over implementation details, such as how tasks are stored in memory.
mycelium-bitfield is a library for defining structured bitfields in Rust. It provides two main ways to work with bitfields:
bitfield! macro: A declarative macro that automatically generates bitfield types.pack module: A set of low-level packing spec types used to define ranges that can be packed and unpacked from an integer value. This allows you to hand-write bitfield logic if the macro-generated code does not meet your needs.The library is modular; the bitfield! macro is built using the components found in the pack module.
mycelium-pci is an abstraction layer designed for interacting with devices on PCI and PCI Express buses. It is specifically implemented for the [Mycelium] operating system and provides a cross-platform (ish) interface for bus interaction.Cordyceps currently provides two primary intrusive data structures:
List implementation.The maitake library is organized into several major functional modules:
maitake::task: The task system. Provides Task (an async task/future), TaskRef (a reference-counted, type-erased pointer to a task), JoinHandle (to await task output), and task::Builder (for task configuration).maitake::scheduler: Task execution. Provides Scheduler and StaticScheduler types to drive tasks forward.maitake::time: Time management. Provides Sleep (wait for duration) and Timeout (wrap a future with a deadline) futures. It uses a hierarchical Timer wheel that must be driven by a hardware time source (e.g., interrupts or timestamp counters).maitake::sync: Asynchronous synchronization. Provides Mutex, RwLock, and Semaphore, along with lower-level primitives for custom strategies.maitake::future: General-purpose utility Future types that work without the Rust standard library.liballoc or a heap allocator is unavailable, maitake allows you to avoid dynamic allocation by overriding the memory container where tasks are stored. You can use the Storage trait to define how tasks are allocated, enabling you to create and schedule a fixed set of tasks stored in 'static memory (compile-time allocation).Many async primitives in maitake-sync (like Mutex, RwLock, Semaphore, and WaitQueue) internally use maitake_sync::blocking::Mutex for wait-list synchronization. By default, this uses blocking::DefaultMutex.
If you need to provide a custom mutex implementation (e.g., a spinlock or a hardware-specific mutex), maitake_sync::blocking::Mutex and the async primitives are generic over a Lock type parameter. You can implement the RawMutex or ScopedRawMutex traits from the mutex-traits crate to allow your custom implementation to be used throughout the library. This also enables compatibility with lock_api and critical-section adapters via the mutex crate.
When choosing a bitfield library, consider these differences:
bitflags: Best for simple, single-bit boolean flags. It cannot define multi-bit structured ranges.mycelium-bitfield: Supports both single-bit flags and multi-bit structured ranges. It can perform most tasks bitflags can do, but with more advanced range capabilities.modular-bitfield uses a procedural macro attribute, whereas mycelium-bitfield uses a declarative macro. Choose mycelium-bitfield if you need to avoid procedural macros.mycelium-bitfield provides the pack module, allowing you to build bitfield types manually. modular-bitfield only provides the procedural macro.modular-bitfield provides compile-time validation to ensure typed values fit within their bitfield ranges. mycelium-bitfield relies on the correctness of the FromBits trait implementation for user-provided types.Cordyceps provides node-based data structures where the node data (pointers to other nodes and associated metadata) is stored within the values themselves, rather than the collection owning the values.
statics or pages in a page allocator), they can be added without any allocation at all.struct must be aware of the collection. It must include a Links struct as a field and implement the Linked trait.Linked type cannot be added to multiple intrusive data structures of the same type simultaneously (though it can be part of multiple structures of different types).Linked is unsafe. Members of intrusive collections must be pinned in memory; they cannot move or be dropped while they are linked into a collection.