Overview

Relevant source files

• Cargo.toml
• README.md
• src/lib.rs

Purpose and Scope

This document provides an introduction to the cap_access library, a capability-based access control system designed for ArceOS and embedded environments. This overview covers the library's fundamental purpose, core components, and architectural design. For detailed implementation specifics of the capability system, see Capability System. For practical usage examples and integration patterns, see Usage Guide. For information about ArceOS-specific integration details, see ArceOS Integration.

What is cap_access

The cap_access library implements a capability-based access control mechanism that provides unforgeable access tokens for protected objects. It serves as a foundational security primitive within the ArceOS operating system ecosystem, enabling fine-grained permission management in resource-constrained environments.

The library centers around two primary components defined in src/lib.rs(L4 - L15) :

• Cap bitflags representing access permissions (READ, WRITE, EXECUTE)
• WithCap<T> wrapper struct that associates objects with their required capabilities

Unlike traditional access control lists or ownership models, capability-based security provides direct, unforgeable references to objects along with the permissions needed to access them. This approach eliminates ambient authority and reduces the attack surface in system security.

Sources: Cargo.toml(L1 - L16)  src/lib.rs(L1 - L21)  README.md(L7 - L12) 

Core Components Overview

The cap_access library consists of three fundamental layers that work together to provide secure object access:

The system leverages the bitflags crate v2.6 for efficient permission operations, enabling combinations like Cap::READ | Cap::WRITE while maintaining no_std compatibility for embedded environments.

Sources: src/lib.rs(L4 - L15)  src/lib.rs(L17 - L21)  Cargo.toml(L14 - L15) 

System Architecture

flowchart TD
subgraph ExternalDeps["External Dependencies"]
    BitflagsLib["bitflags crate v2.6Efficient flag operations"]
end
subgraph CreationAPI["Object Creation"]
    NewMethod["WithCap::new(inner: T, cap: Cap)→ WithCap<T>"]
    CapGetter["cap() → Cap"]
end
subgraph AccessMethods["Access Control Methods"]
    CanAccess["can_access(cap: Cap)→ bool"]
    Access["access(cap: Cap)→ Option<&T>"]
    AccessOrErr["access_or_err(cap: Cap, err: E)→ Result<&T, E>"]
    AccessUnchecked["access_unchecked()→ &T (unsafe)"]
end
subgraph CoreTypes["Core Type System"]
    CapBitflags["Cap bitflagsREAD | WRITE | EXECUTE"]
    WithCapStruct["WithCap<T>inner: T, cap: Cap"]
end

CanAccess --> Access
CanAccess --> AccessOrErr
CapBitflags --> BitflagsLib
CapBitflags --> WithCapStruct
CapGetter --> CapBitflags
NewMethod --> WithCapStruct
WithCapStruct --> CanAccess

This architecture diagram shows the relationship between the core types and the methods that operate on them. The Cap bitflags provide the foundation for permission representation, while WithCap<T> wraps arbitrary objects with capability requirements. Access control methods then enforce these requirements through various safe and unsafe interfaces.

Sources: src/lib.rs(L4 - L15)  src/lib.rs(L17 - L27)  src/lib.rs(L46 - L99)  Cargo.toml(L14 - L15) 

Access Control Flow

This sequence diagram illustrates the different access patterns available in the cap_access system. The can_access() method serves as the core validation function used by all safe access methods, while access_unchecked() bypasses capability validation entirely for performance-critical scenarios.

Sources: src/lib.rs(L46 - L48)  src/lib.rs(L72 - L78)  src/lib.rs(L93 - L99)  src/lib.rs(L55 - L57) 

Target Environments and Use Cases

The cap_access library is specifically designed for system-level programming environments where security and resource constraints are primary concerns:

no_std Compatibility

The library operates in no_std environments as specified in src/lib.rs(L1)  making it suitable for:

• Embedded systems with limited memory
• Kernel modules without standard library access
• Bare-metal applications on microcontrollers

ArceOS Integration

As indicated by the package metadata in Cargo.toml(L8 - L11)  cap_access serves as a foundational component within the ArceOS operating system, providing:

• Memory region access control
• File system permission enforcement
• Device driver capability management
• Process isolation mechanisms

Multi-Architecture Support

The library supports multiple target architectures through its build system, including x86_64, RISC-V, and ARM64 platforms in both hosted and bare-metal configurations.

Sources: src/lib.rs(L1)  Cargo.toml(L8 - L12)  README.md(L7 - L8) 

Key Design Principles

The cap_access library embodies several important design principles that distinguish it from traditional access control mechanisms:

1. Unforgeable Capabilities: The Cap bitflags cannot be arbitrarily created or modified, ensuring that only authorized code can grant permissions
2. Zero-Cost Abstractions: Capability checks compile to efficient bitwise operations with minimal runtime overhead
3. Type Safety: The WithCap<T> wrapper preserves the original type while adding capability enforcement
4. Flexible Access Patterns: Multiple access methods (access(), access_or_err(), access_unchecked()) accommodate different error handling strategies and performance requirements

This capability-based approach provides stronger security guarantees than discretionary access control while maintaining the performance characteristics required for systems programming.

Sources: src/lib.rs(L4 - L15)  src/lib.rs(L46 - L99)  README.md(L9 - L12) 

Core Architecture

Relevant source files

• src/lib.rs

Purpose and Scope

This document provides a comprehensive overview of the fundamental architecture underlying the cap_access capability-based access control system. It covers the core components that enable secure object protection through unforgeable capability tokens and controlled access patterns.

For specific implementation details of the capability flags system, see Capability System. For in-depth coverage of the object wrapper mechanics, see Object Protection with WithCap. For detailed access method implementations, see Access Control Methods.

System Overview

The cap_access library implements a capability-based access control model built around two primary components: capability tokens (Cap) and protected object wrappers (WithCap<T>). The architecture enforces access control at compile time and runtime through a combination of type safety and capability checking.

Core Architecture Diagram

flowchart TD
subgraph subGraph3["Access Methods"]
    CanAccess["can_access()"]
    Access["access()"]
    AccessOrErr["access_or_err()"]
    AccessUnchecked["access_unchecked()"]
end
subgraph subGraph2["WithCap Fields"]
    Inner["inner: T"]
    CapField["cap: Cap"]
end
subgraph subGraph1["Cap Implementation Details"]
    READ["Cap::READ (1 << 0)"]
    WRITE["Cap::WRITE (1 << 1)"]
    EXECUTE["Cap::EXECUTE (1 << 2)"]
    Contains["Cap::contains()"]
end
subgraph subGraph0["cap_access Core Components"]
    Cap["Cap bitflags struct"]
    WithCap["WithCap<T> wrapper struct"]
    Methods["Access control methods"]
end

CanAccess --> Contains
Cap --> Contains
Cap --> EXECUTE
Cap --> READ
Cap --> WRITE
CapField --> Contains
Methods --> Access
Methods --> AccessOrErr
Methods --> AccessUnchecked
Methods --> CanAccess
WithCap --> CapField
WithCap --> Inner
WithCap --> Methods

Sources: src/lib.rs(L4 - L15)  src/lib.rs(L17 - L21)  src/lib.rs(L23 - L100) 

Core Components

Capability Token System

The Cap struct serves as the foundational security primitive, implemented using the bitflags crate to provide efficient bitwise operations on capability flags. The three basic capabilities can be combined using bitwise OR operations to create compound permissions.

Protected Object Wrapper

The WithCap<T> generic struct encapsulates any type T along with its associated capabilities. This wrapper ensures that access to the inner object is mediated through capability checks, preventing unauthorized operations.

flowchart TD
subgraph subGraph2["Capability Query"]
    GetCap["cap() -> Cap"]
    CanAccess["can_access(cap: Cap) -> bool"]
end
subgraph Constructor["Constructor"]
    New["WithCap::new(inner: T, cap: Cap)"]
end
subgraph subGraph0["WithCap<T> Structure"]
    InnerField["inner: T"]
    CapacityField["cap: Cap"]
end

CapacityField --> CanAccess
CapacityField --> GetCap
New --> CapacityField
New --> InnerField

Sources: src/lib.rs(L17 - L21)  src/lib.rs(L24 - L27)  src/lib.rs(L29 - L32)  src/lib.rs(L34 - L48) 

Access Control Implementation

Capability Checking Logic

The core access control mechanism centers on the can_access method, which uses the Cap::contains operation to verify that the wrapper's capability set includes all bits required by the requested capability.

flowchart TD
Request["Access Request with Cap"]
Check["can_access(requested_cap)"]
Contains["self.cap.contains(requested_cap)"]
Allow["Grant Access"]
Deny["Deny Access"]

Check --> Contains
Contains --> Allow
Contains --> Deny
Request --> Check

Sources: src/lib.rs(L46 - L48) 

Access Pattern Variants

The architecture provides three distinct access patterns, each with different safety and error handling characteristics:

Access Method Flow

flowchart TD
AccessCall["Access Method Called"]
SafeCheck["Safe or Unsafe?"]
CapCheck["Capability Check"]
OptionReturn["Return Option<&T>"]
ResultReturn["Return Result<&T, E>"]
UnsafeReturn["Return &T directly"]

AccessCall --> SafeCheck
CapCheck --> OptionReturn
CapCheck --> ResultReturn
SafeCheck --> CapCheck
SafeCheck --> UnsafeReturn

Sources: src/lib.rs(L50 - L57)  src/lib.rs(L59 - L78)  src/lib.rs(L80 - L99) 

Type Safety and Memory Safety

The architecture leverages Rust's type system to enforce capability-based access control at compile time while providing runtime capability validation. The WithCap<T> wrapper prevents direct access to the inner object, forcing all access through the controlled interface methods.

The unsafe access_unchecked method provides an escape hatch for performance-critical scenarios where the caller can guarantee capability validity, while maintaining clear documentation of the safety requirements.

Sources: src/lib.rs(L1 - L101) 

Capability System

Relevant source files

• src/lib.rs

Purpose and Scope

The Capability System forms the foundation of access control in the cap_access library. This document covers the Cap bitflags structure, the three fundamental capability types (READ, WRITE, EXECUTE), and the mechanisms for combining and checking capabilities. For information about how capabilities are used with protected objects, see Object Protection with WithCap. For details on access control methods that utilize these capabilities, see Access Control Methods.

Cap Bitflags Structure

The capability system is implemented using the bitflags crate to provide efficient bit-level operations for permission management. The Cap structure represents unforgeable access tokens that can be combined using bitwise operations.

flowchart TD
subgraph subGraph2["Bitwise Operations"]
    UNION["Union (|)"]
    INTERSECTION["Intersection (&)"]
    CONTAINS["contains()"]
end
subgraph subGraph1["Bitflags Traits"]
    DEFAULT["Default"]
    DEBUG["Debug"]
    CLONE["Clone"]
    COPY["Copy"]
end
subgraph subGraph0["Cap Structure [lines 4-15]"]
    CAP["Cap: u32"]
    READ["READ = 1 << 0"]
    WRITE["WRITE = 1 << 1"]
    EXECUTE["EXECUTE = 1 << 2"]
end

CAP --> CLONE
CAP --> COPY
CAP --> DEBUG
CAP --> DEFAULT
CAP --> EXECUTE
CAP --> READ
CAP --> WRITE
EXECUTE --> UNION
INTERSECTION --> CONTAINS
READ --> UNION
UNION --> CONTAINS
WRITE --> UNION

Cap Bitflags Architecture

The Cap struct is defined as a bitflags structure that wraps a u32 value, providing type-safe capability manipulation with automatic trait derivations for common operations.

Sources: src/lib.rs(L4 - L15) 

Basic Capability Types

The capability system defines three fundamental access rights that correspond to common operating system permissions:

flowchart TD
subgraph subGraph1["Capability Constants"]
    READ_CONST["Cap::READ = 0x01"]
    WRITE_CONST["Cap::WRITE = 0x02"]
    EXECUTE_CONST["Cap::EXECUTE = 0x04"]
end
subgraph subGraph0["Bit Layout [u32]"]
    BIT2["Bit 2: EXECUTE"]
    BIT1["Bit 1: WRITE"]
    BIT0["Bit 0: READ"]
    UNUSED["Bits 3-31: Reserved"]
end

BIT0 --> READ_CONST
BIT1 --> WRITE_CONST
BIT2 --> EXECUTE_CONST

Capability Bit Layout

Each capability type occupies a specific bit position, allowing for efficient combination and checking operations using bitwise arithmetic.

Sources: src/lib.rs(L8 - L14) 

Capability Combinations

Capabilities can be combined using bitwise OR operations to create composite permissions. The bitflags implementation provides natural syntax for capability composition:

flowchart TD
subgraph subGraph2["Use Cases"]
    READONLY["Read-only files"]
    READWRITE["Mutable data"]
    EXECUTABLE["Program files"]
    FULLACCESS["Administrative access"]
end
subgraph subGraph1["Common Combinations"]
    RW["Cap::READ | Cap::WRITE"]
    RX["Cap::READ | Cap::EXECUTE"]
    WX["Cap::WRITE | Cap::EXECUTE"]
    RWX["Cap::READ | Cap::WRITE | Cap::EXECUTE"]
end
subgraph subGraph0["Single Capabilities"]
    R["Cap::READ"]
    W["Cap::WRITE"]
    X["Cap::EXECUTE"]
end

R --> READONLY
R --> RW
R --> RWX
R --> RX
RW --> READWRITE
RWX --> FULLACCESS
RX --> EXECUTABLE
W --> RW
W --> RWX
W --> WX
X --> RWX
X --> RX
X --> WX

Capability Combination Patterns

The bitflags design enables natural combination of capabilities to express complex permission requirements.

Sources: src/lib.rs(L4 - L15) 

Capability Checking Logic

The capability system provides the contains method for checking whether a set of capabilities includes required permissions. This forms the foundation for all access control decisions in the system.

flowchart TD
subgraph subGraph0["contains() Logic"]
    BITWISE["(self.bits & other.bits) == other.bits"]
    SUBSET["Check if 'other' is subset of 'self'"]
end
subgraph subGraph1["Example Scenarios"]
    SCENARIO1["Object has READ|WRITERequest: READ → true"]
    SCENARIO2["Object has READRequest: WRITE → false"]
    SCENARIO3["Object has READ|WRITERequest: READ|WRITE → true"]
end
START["can_access(cap: Cap)"]
CHECK["self.cap.contains(cap)"]
TRUE["Return true"]
FALSE["Return false"]

BITWISE --> SUBSET
CHECK --> BITWISE
START --> CHECK
SUBSET --> FALSE
SUBSET --> TRUE

Capability Checking Flow

The can_access method uses bitwise operations to determine if the requested capabilities are a subset of the available capabilities.

Sources: src/lib.rs(L46 - L48) 

Implementation Details

The Cap structure leverages several key design patterns for efficient and safe capability management:

Bitflags Integration

The implementation uses the bitflags! macro to generate a complete capability management API, including:

• Automatic implementation of bitwise operations (|, &, ^, !)
• Type-safe flag manipulation methods
• Built-in contains() method for subset checking
• Standard trait implementations (Debug, Clone, Copy, Default)

Memory Efficiency

The Cap structure occupies only 4 bytes (u32) regardless of capability combinations, making it suitable for embedded environments where memory usage is critical.

Constant Evaluation

The can_access method is marked as const fn, enabling compile-time capability checking when capability values are known at compile time.

Sources: src/lib.rs(L4 - L15)  src/lib.rs(L46 - L48) 

Object Protection with WithCap

Relevant source files

• src/lib.rs

Purpose and Scope

This document covers the WithCap<T> wrapper struct, which serves as the core object protection mechanism in the cap_access library. The WithCap<T> struct associates any object of type T with a specific capability (Cap), providing controlled access to the wrapped object through capability checking.

For details about the underlying capability system and Cap bitflags, see Capability System. For comprehensive coverage of the access control methods provided by WithCap<T>, see Access Control Methods.

WithCap Structure Overview

The WithCap<T> struct provides a simple but powerful abstraction for capability-based object protection. It wraps any object with an associated capability, ensuring that access to the object is mediated through capability checks.

Core Architecture

flowchart TD
subgraph AccessMethods["Access Methods"]
    new["new(inner, cap)"]
    can_access["can_access(cap)"]
    access["access(cap)"]
    access_or_err["access_or_err(cap, err)"]
    access_unchecked["access_unchecked()"]
    cap_getter["cap()"]
end
subgraph CapSystem["Capability System"]
    READ["Cap::READ"]
    WRITE["Cap::WRITE"]
    EXECUTE["Cap::EXECUTE"]
    COMBINED["Combined Capabilities"]
end
subgraph WithCap["WithCap<T> Structure"]
    inner["inner: T"]
    cap["cap: Cap"]
end

COMBINED --> cap
EXECUTE --> cap
READ --> cap
WRITE --> cap

Sources: src/lib.rs(L18 - L21)  src/lib.rs(L23 - L100) 

Struct Definition

The WithCap<T> struct contains exactly two fields that work together to provide controlled access:

The struct is generic over type T, allowing any object to be protected with capabilities.

Sources: src/lib.rs(L18 - L21) 

Object Wrapping Process

Creating Protected Objects

The WithCap::new() constructor associates an object with specific capabilities, creating an immutable binding between the object and its access permissions.

flowchart TD
subgraph Examples["Example Objects"]
    FileData["File Data"]
    MemoryRegion["Memory Region"]
    DeviceHandle["Device Handle"]
end
subgraph Creation["Object Protection Process"]
    UnprotectedObj["Unprotected Object"]
    Capability["Cap Permissions"]
    Constructor["WithCap::new()"]
    ProtectedObj["WithCap<T>"]
end

Capability --> Constructor
Constructor --> ProtectedObj
DeviceHandle --> UnprotectedObj
FileData --> UnprotectedObj
MemoryRegion --> UnprotectedObj
UnprotectedObj --> Constructor

Sources: src/lib.rs(L24 - L27) 

Capability Association

The new() method permanently associates the provided capability with the object. Once created, the capability cannot be modified, ensuring the integrity of the access control policy.

The constructor signature demonstrates this immutable binding:

• pub fn new(inner: T, cap: Cap) -> Self

Sources: src/lib.rs(L24 - L27) 

Access Control Implementation

Capability Checking Logic

The core access control mechanism relies on the can_access() method, which performs bitwise capability checking using the underlying Cap::contains() operation.

flowchart TD
subgraph AccessMethods["Access Method Types"]
    SafeAccess["access() → Option<&T>"]
    ErrorAccess["access_or_err() → Result<&T, E>"]
    UnsafeAccess["access_unchecked() → &T"]
end
subgraph AccessFlow["Access Control Flow"]
    Request["Access Request with Cap"]
    Check["can_access(cap)"]
    Contains["cap.contains(requested_cap)"]
    Allow["Grant Access"]
    Deny["Deny Access"]
end

Allow --> ErrorAccess
Allow --> SafeAccess
Check --> Contains
Contains --> Allow
Contains --> Deny
Deny --> ErrorAccess
Deny --> SafeAccess
Request --> Check
UnsafeAccess --> Check

Sources: src/lib.rs(L46 - L48)  src/lib.rs(L72 - L78)  src/lib.rs(L93 - L99)  src/lib.rs(L55 - L57) 

Method Categories

The WithCap<T> struct provides three categories of access methods:

Sources: src/lib.rs(L72 - L78)  src/lib.rs(L93 - L99)  src/lib.rs(L55 - L57) 

Internal Architecture Details

Capability Storage

The WithCap<T> struct stores capabilities as Cap bitflags, enabling efficient bitwise operations for permission checking. The cap() getter method provides read-only access to the stored capability.

Memory Layout Considerations

The struct maintains a simple memory layout with the protected object and capability stored adjacently. This design minimizes overhead while maintaining clear separation between the object and its access permissions.

flowchart TD
subgraph CapabilityBits["Cap Bitfield Structure"]
    Bit0["Bit 0: READ"]
    Bit1["Bit 1: WRITE"]
    Bit2["Bit 2: EXECUTE"]
    Reserved["Bits 3-31: Reserved"]
end
subgraph MemoryLayout["WithCap<T> Memory Layout"]
    InnerData["inner: T(Protected Object)"]
    CapData["cap: Cap(u32 bitflags)"]
end
WithCap["WithCap"]

CapData --> Bit0
CapData --> Bit1
CapData --> Bit2
CapData --> Reserved
CapData --> WithCap
InnerData --> WithCap

Sources: src/lib.rs(L18 - L21)  src/lib.rs(L29 - L32) 

Const Methods

Several methods are declared as const fn, enabling compile-time evaluation when possible:

• cap() - capability getter
• can_access() - capability checking
• access() - checked access

This design supports zero-cost abstractions in performance-critical embedded environments.

Sources: src/lib.rs(L30)  src/lib.rs(L46)  src/lib.rs(L72) 

Access Control Methods

Relevant source files

• src/lib.rs

Purpose and Scope

This document covers the access control methods provided by the WithCap<T> wrapper for accessing protected objects. It explains the different access patterns available, their safety guarantees, and appropriate usage scenarios. For information about the capability system and permission flags, see Capability System. For details about the WithCap<T> wrapper structure itself, see Object Protection with WithCap.

The access control methods implement a capability-based security model where objects can only be accessed when the caller presents the required capabilities. The system provides multiple access patterns to accommodate different error handling strategies and performance requirements.

Access Control Flow

The access control system follows a consistent pattern where capability validation determines whether access is granted to the protected object.

flowchart TD
CALLER["Caller Code"]
METHOD["Access Method Call"]
CHECK["can_access(cap)"]
VALIDATE["CapabilityValidation"]
GRANT["Access Granted"]
DENY["Access Denied"]
RETURN_REF["Return &T"]
ERROR_HANDLING["Error Handling"]
OPTION["Option::None"]
RESULT["Result::Err(E)"]
UNSAFE["Undefined Behavior"]
SAFE_ACCESS["access(cap)"]
RESULT_ACCESS["access_or_err(cap, err)"]
UNSAFE_ACCESS["access_unchecked()"]

CALLER --> METHOD
CHECK --> VALIDATE
DENY --> ERROR_HANDLING
ERROR_HANDLING --> OPTION
ERROR_HANDLING --> RESULT
ERROR_HANDLING --> UNSAFE
GRANT --> RETURN_REF
METHOD --> CHECK
METHOD --> RESULT_ACCESS
METHOD --> SAFE_ACCESS
METHOD --> UNSAFE_ACCESS
RESULT_ACCESS --> CHECK
SAFE_ACCESS --> CHECK
UNSAFE_ACCESS --> RETURN_REF
VALIDATE --> DENY
VALIDATE --> GRANT

Sources: src/lib.rs(L46 - L99) 

Capability Validation

All safe access methods rely on the can_access method for capability validation. This method performs a bitwise containment check to determine if the required capabilities are present.

can_accessMethod

The can_access method provides the fundamental capability checking logic used by all safe access patterns.

Implementation Details:

• Uses self.cap.contains(cap) for bitwise capability checking
• Declared as const fn for compile-time evaluation
• Returns true if all requested capability bits are present
• Returns false if any requested capability bits are missing

Sources: src/lib.rs(L46 - L48) 

Safe Access Methods

The library provides two safe access methods that perform capability validation before granting access to the protected object.

Option-Based Access

The access method provides safe access with Option<&T> return semantics for cases where capability failure should be handled gracefully.

flowchart TD
INPUT["access(cap: Cap)"]
CHECK["can_access(cap)"]
SOME["Some(&self.inner)"]
NONE["None"]
CLIENT_OK["Client handles success"]
CLIENT_ERR["Client handles None"]

CHECK --> NONE
CHECK --> SOME
INPUT --> CHECK
NONE --> CLIENT_ERR
SOME --> CLIENT_OK

Method Characteristics:

• Signature: access(&self, cap: Cap) -> Option<&T>
• Safety: Memory safe with compile-time guarantees
• Performance: Minimal overhead with const fn optimization
• Error Handling: Returns None on capability mismatch

Usage Pattern:

if let Some(data) = protected_obj.access(Cap::READ) {
    // Use data safely
} else {
    // Handle access denial
}

Sources: src/lib.rs(L72 - L78) 

Result-Based Access

The access_or_err method provides safe access with Result<&T, E> return semantics, allowing custom error types and error propagation patterns.

flowchart TD
INPUT["access_or_err(cap: Cap, err: E)"]
CHECK["can_access(cap)"]
OK["Ok(&self.inner)"]
ERR["Err(err)"]
CLIENT_OK["Client handles success"]
CLIENT_ERR["Client handles custom error"]
PROPAGATE["Error propagation with ?"]

CHECK --> ERR
CHECK --> OK
ERR --> CLIENT_ERR
ERR --> PROPAGATE
INPUT --> CHECK
OK --> CLIENT_OK

Method Characteristics:

• Signature: access_or_err<E>(&self, cap: Cap, err: E) -> Result<&T, E>
• Safety: Memory safe with compile-time guarantees
• Error Handling: Returns custom error type on capability mismatch
• Integration: Compatible with ? operator for error propagation

Usage Pattern:

let data = protected_obj.access_or_err(Cap::WRITE, "Write access denied")?;
// Use data safely, or propagate error

Sources: src/lib.rs(L93 - L99) 

Unsafe Access Methods

The library provides an unsafe access method for performance-critical scenarios where capability checking overhead must be eliminated.

Unchecked Access

The access_unchecked method bypasses all capability validation and directly returns a reference to the protected object.

flowchart TD
INPUT["access_unchecked()"]
DIRECT["&self.inner"]
WARNING["⚠️ UNSAFE:No capability validation"]
CALLER["Caller Responsibility"]
BYPASS["Bypasses can_access()"]
PERFORMANCE["Zero-overhead access"]

BYPASS --> PERFORMANCE
DIRECT --> WARNING
INPUT --> BYPASS
INPUT --> DIRECT
WARNING --> CALLER

Method Characteristics:

• Signature: unsafe fn access_unchecked(&self) -> &T
• Safety: UNSAFE - No capability validation performed
• Performance: Zero overhead - direct memory access
• Responsibility: Caller must ensure capability compliance

Safety Requirements: The caller must guarantee that they have the appropriate capabilities for the intended use of the object. Violating this contract may lead to:

• Security vulnerabilities
• Privilege escalation
• Undefined behavior in security-critical contexts

Sources: src/lib.rs(L55 - L57) 

Access Method Comparison

Implementation Architecture

The access control methods are implemented as part of the WithCap<T> struct and follow a layered architecture:

flowchart TD
subgraph subGraph2["Memory Access"]
    INNER_REF["&self.inner"]
end
subgraph subGraph1["Core Validation"]
    CONTAINS["self.cap.contains(cap)"]
    BITFLAGS["bitflags operations"]
end
subgraph subGraph0["WithCap Access Methods"]
    CAN_ACCESS["can_access(cap: Cap)→ bool"]
    ACCESS["access(cap: Cap)→ Option<&T>"]
    ACCESS_ERR["access_or_err(cap: Cap, err: E)→ Result<&T, E>"]
    ACCESS_UNSAFE["access_unchecked()→ &T"]
end

ACCESS --> CAN_ACCESS
ACCESS --> INNER_REF
ACCESS_ERR --> CAN_ACCESS
ACCESS_ERR --> INNER_REF
ACCESS_UNSAFE --> INNER_REF
CAN_ACCESS --> CONTAINS
CONTAINS --> BITFLAGS

Architecture Characteristics:

• Layered Design: Safe methods build upon capability validation
• Shared Validation: All safe methods use can_access for consistency
• Zero-Cost Abstractions: const fn declarations enable compile-time optimization
• Type Safety: Generic design works with any wrapped type T

Sources: src/lib.rs(L23 - L100) 

Usage Guide

Relevant source files

• README.md
• src/lib.rs

This guide provides practical examples and patterns for using the cap_access library in real applications. It covers the essential usage patterns, access methods, and best practices for implementing capability-based access control in your code.

For architectural details about the underlying capability system, see Core Architecture. For information about integrating with ArceOS, see ArceOS Integration.

Basic Usage Patterns

The fundamental workflow with cap_access involves creating protected objects with WithCap::new() and accessing them through capability-checked methods.

Creating Protected Objects

flowchart TD
subgraph subGraph0["Cap Constants"]
    READ["Cap::READ"]
    WRITE["Cap::WRITE"]
    EXECUTE["Cap::EXECUTE"]
end
Object["Raw Object(T)"]
WithCap_new["WithCap::new()"]
Capability["Cap Permission(READ | WRITE | EXECUTE)"]
Protected["WithCap<T>Protected Object"]

Capability --> WithCap_new
EXECUTE --> Capability
Object --> WithCap_new
READ --> Capability
WRITE --> Capability
WithCap_new --> Protected

The most common pattern is to wrap objects at creation time with appropriate capabilities:

Sources: src/lib.rs(L4 - L15)  src/lib.rs(L23 - L27) 

Capability Composition

Capabilities can be combined using bitwise operations to create complex permission sets:

flowchart TD
subgraph subGraph1["Combined Capabilities"]
    RW["Cap::READ | Cap::WRITERead-Write Access"]
    RX["Cap::READ | Cap::EXECUTERead-Execute Access"]
    RWX["Cap::READ | Cap::WRITE | Cap::EXECUTEFull Access"]
end
subgraph subGraph0["Individual Capabilities"]
    READ_CAP["Cap::READ(1 << 0)"]
    WRITE_CAP["Cap::WRITE(1 << 1)"]
    EXEC_CAP["Cap::EXECUTE(1 << 2)"]
end

EXEC_CAP --> RWX
EXEC_CAP --> RX
READ_CAP --> RW
READ_CAP --> RWX
READ_CAP --> RX
WRITE_CAP --> RW
WRITE_CAP --> RWX

Sources: src/lib.rs(L4 - L15)  README.md(L16 - L29) 

Access Method Comparison

The WithCap<T> struct provides three distinct access patterns, each with different safety and error handling characteristics:

flowchart TD
subgraph subGraph1["Return Types"]
    Bool["Boolean CheckValidation only"]
    Option["Option PatternNone on failure"]
    Result["Result PatternCustom error on failure"]
    Direct["Direct ReferenceNo safety checks"]
end
subgraph subGraph0["Access Methods"]
    can_access["can_access(cap)→ bool"]
    access["access(cap)→ Option<&T>"]
    access_or_err["access_or_err(cap, err)→ Result<&T, E>"]
    access_unchecked["access_unchecked()→ &T (UNSAFE)"]
end
WithCap["WithCap<T>Protected Object"]

WithCap --> access
WithCap --> access_or_err
WithCap --> access_unchecked
WithCap --> can_access
access --> Option
access_or_err --> Result
access_unchecked --> Direct
can_access --> Bool

Method Selection Guidelines

Sources: src/lib.rs(L34 - L48)  src/lib.rs(L59 - L78)  src/lib.rs(L80 - L99)  src/lib.rs(L50 - L57) 

Practical Access Patterns

Safe Access with Option Handling

The access() method returns Option<&T> and is ideal for scenarios where access failure is expected and should be handled gracefully:

sequenceDiagram
    participant Client as Client
    participant WithCapaccess as "WithCap::access()"
    participant WithCapcan_access as "WithCap::can_access()"
    participant innerT as "inner: T"

    Client ->> WithCapaccess: access(requested_cap)
    WithCapaccess ->> WithCapcan_access: self.cap.contains(requested_cap)
    alt Capability Match
        WithCapcan_access -->> WithCapaccess: true
        WithCapaccess ->> innerT: &self.inner
        innerT -->> WithCapaccess: &T
        WithCapaccess -->> Client: Some(&T)
    else Capability Mismatch
        WithCapcan_access -->> WithCapaccess: false
        WithCapaccess -->> Client: None
    end

This pattern is demonstrated in the README examples where checking for Cap::EXECUTE on a read-write object returns None.

Sources: src/lib.rs(L72 - L78)  README.md(L22 - L28) 

Error-Based Access with Context

The access_or_err() method provides custom error messages for better debugging and user feedback:

flowchart TD
subgraph Output["Output"]
    Result_Ok["Result::Ok(&T)"]
    Result_Err["Result::Err(E)"]
end
subgraph subGraph1["access_or_err Process"]
    Check["can_access(cap)"]
    Success["Ok(&inner)"]
    Failure["Err(custom_error)"]
end
subgraph Input["Input"]
    Cap_Request["Requested Capability"]
    Error_Value["Custom Error Value"]
end

Cap_Request --> Check
Check --> Failure
Check --> Success
Error_Value --> Check
Failure --> Result_Err
Success --> Result_Ok

This method is particularly useful in system programming contexts where specific error codes or messages are required for debugging.

Sources: src/lib.rs(L93 - L99) 

Unsafe High-Performance Access

The access_unchecked() method bypasses capability validation for performance-critical code paths:

Safety Requirements:

• Caller must manually verify capability compliance
• Should only be used in trusted, performance-critical contexts
• Requires unsafe block, making the safety contract explicit

Sources: src/lib.rs(L55 - L57) 

Best Practices

Capability Design Patterns

1. Principle of Least Privilege: Grant minimal necessary capabilities
2. Capability Composition: Use bitwise OR to combine permissions
3. Validation at Boundaries: Check capabilities at system boundaries
4. Consistent Error Handling: Choose one access method per subsystem

Integration Patterns

flowchart TD
subgraph subGraph2["Protected Resources"]
    FileSystem["File System Objects"]
    Memory["Memory Regions"]
    DeviceDrivers["Device Drivers"]
end
subgraph subGraph1["cap_access Integration"]
    WithCap_Factory["WithCap CreationWithCap::new(obj, cap)"]
    Access_Layer["Access Controlaccess() / access_or_err()"]
    Validation["Capability Validationcan_access()"]
end
subgraph subGraph0["Application Layer"]
    UserCode["User Application Code"]
    ServiceLayer["Service Layer"]
end

Access_Layer --> Validation
ServiceLayer --> Access_Layer
ServiceLayer --> WithCap_Factory
UserCode --> Access_Layer
UserCode --> WithCap_Factory
WithCap_Factory --> DeviceDrivers
WithCap_Factory --> FileSystem
WithCap_Factory --> Memory

Common Usage Scenarios

Sources: src/lib.rs(L23 - L27)  README.md(L19 - L24) 

Advanced Usage Patterns

Dynamic Capability Checking

The can_access() method enables sophisticated access control logic:

This pattern is essential for security-sensitive applications that need comprehensive access logging and audit trails.

Sources: src/lib.rs(L46 - L48) 

Multi-Level Access Control

Complex systems often require nested capability checks across multiple abstraction layers:

flowchart TD
subgraph subGraph1["WithCap Instances"]
    AppData["WithCap<UserData>"]
    KernelData["WithCap<SystemCall>"]
    HWData["WithCap<Device>"]
end
subgraph subGraph0["System Architecture"]
    App["Application LayerCap::READ | Cap::WRITE"]
    Kernel["Kernel LayerCap::EXECUTE"]
    Hardware["Hardware LayerCap::READ | Cap::WRITE | Cap::EXECUTE"]
end
UserAccess["User Read Access"]
SyscallAccess["System Call Execution"]
DirectHW["Direct Hardware Access"]

App --> AppData
AppData --> UserAccess
HWData --> DirectHW
Hardware --> HWData
Kernel --> KernelData
KernelData --> SyscallAccess

This layered approach ensures that capability validation occurs at appropriate system boundaries while maintaining performance where needed.

Sources: src/lib.rs(L1 - L101) 

ArceOS Integration

Relevant source files

• Cargo.toml
• src/lib.rs

Purpose and Scope

This document explains how the cap_access library integrates into the ArceOS operating system ecosystem, serving as a foundational security primitive for capability-based access control. It covers the library's role in kernel security, no_std compatibility requirements, and integration patterns across ArceOS components.

For detailed information about the core capability system and access control methods, see Core Architecture. For practical usage examples, see Usage Guide.

ArceOS Ecosystem Integration

The cap_access library serves as a core security infrastructure component within the ArceOS operating system, providing capability-based access control primitives that are used throughout the kernel and user-space applications.

Integration Architecture

flowchart TD
subgraph subGraph3["User Applications"]
    SystemServices["System Services"]
    UserApps["User Applications"]
    RuntimeLibs["Runtime Libraries"]
end
subgraph subGraph2["Protected Resources"]
    MemoryRegions["Memory Regions"]
    FileObjects["File Objects"]
    DeviceResources["Device Resources"]
    ProcessData["Process Data"]
end
subgraph subGraph1["cap_access Security Layer"]
    CapStruct["Cap bitflags"]
    WithCapStruct["WithCap"]
    AccessMethods["Access Methods"]
end
subgraph subGraph0["ArceOS Kernel Layer"]
    KernelCore["Kernel Core"]
    MemoryMgr["Memory Manager"]
    FileSystem["File System"]
    DeviceDrivers["Device Drivers"]
end

AccessMethods --> CapStruct
AccessMethods --> WithCapStruct
DeviceDrivers --> WithCapStruct
FileSystem --> WithCapStruct
KernelCore --> CapStruct
MemoryMgr --> WithCapStruct
RuntimeLibs --> AccessMethods
SystemServices --> AccessMethods
UserApps --> AccessMethods
WithCapStruct --> DeviceResources
WithCapStruct --> FileObjects
WithCapStruct --> MemoryRegions
WithCapStruct --> ProcessData

Sources: Cargo.toml(L8 - L12)  src/lib.rs(L17 - L21) 

Package Configuration for ArceOS

The library is specifically configured for integration with ArceOS through its package metadata:

Sources: Cargo.toml(L8 - L12) 

Kernel Security Layer

The cap_access library provides unforgeable security tokens through its capability-based access control system, enabling fine-grained permission management within ArceOS kernel components.

Security Primitive Integration

flowchart TD
subgraph subGraph3["Kernel Usage"]
    KernelCheck["Kernel Permission Check"]
    ResourceAccess["Resource Access"]
    ErrorHandling["Error Handling"]
end
subgraph subGraph2["Access Control"]
    CanAccess["can_access()"]
    Access["access()"]
    AccessOrErr["access_or_err()"]
    AccessUnchecked["access_unchecked()"]
end
subgraph subGraph1["Object Protection"]
    WithCapNew["WithCap::new()"]
    WithCapStruct["WithCap"]
    InnerData["inner: T"]
    CapField["cap: Cap"]
end
subgraph subGraph0["Capability Definition"]
    CapRead["Cap::READ"]
    CapWrite["Cap::WRITE"]
    CapExecute["Cap::EXECUTE"]
end

Access --> CanAccess
Access --> KernelCheck
AccessOrErr --> CanAccess
AccessOrErr --> ErrorHandling
AccessUnchecked --> ResourceAccess
CanAccess --> CapField
CapExecute --> WithCapNew
CapRead --> WithCapNew
CapWrite --> WithCapNew
KernelCheck --> ResourceAccess
WithCapNew --> WithCapStruct
WithCapStruct --> CapField
WithCapStruct --> InnerData

Sources: src/lib.rs(L4 - L15)  src/lib.rs(L46 - L48)  src/lib.rs(L72 - L78) 

Security Guarantees

The capability system provides several security guarantees essential for kernel operation:

• Unforgeable Tokens: Cap bitflags cannot be arbitrarily created, only through controlled initialization
• Compile-time Safety: The type system prevents capability escalation through WithCap<T> wrapper
• Runtime Validation: Methods like can_access() and access() provide runtime permission checking
• Controlled Unsafe Access: access_unchecked() provides escape hatch for performance-critical kernel code

Sources: src/lib.rs(L46 - L48)  src/lib.rs(L72 - L78)  src/lib.rs(L55 - L57) 

no_std Compatibility

The cap_access library is designed for no_std environments, making it suitable for embedded systems and kernel contexts where the standard library is not available.

no_std Configuration

The library uses conditional compilation to support both std and no_std environments:

#![cfg_attr(not(test), no_std)]

This configuration enables:

• Kernel Integration: Direct usage within ArceOS kernel without standard library dependencies
• Embedded Support: Deployment on resource-constrained embedded systems
• Bare Metal: Operation on bare metal platforms without operating system support

Sources: src/lib.rs(L1) 

Dependencies

The library maintains minimal dependencies to support no_std compatibility:

Sources: Cargo.toml(L14 - L15) 

Multi-Platform Support

ArceOS targets multiple hardware architectures, and cap_access provides consistent capability-based access control across all supported platforms.

Supported Architectures

Based on the CI configuration and ArceOS requirements, cap_access supports:

• x86_64: Standard desktop and server platforms (x86_64-unknown-linux-gnu, x86_64-unknown-none)
• RISC-V: Embedded and specialized systems (riscv64gc-unknown-none-elf)
• ARM64: Mobile and embedded platforms (aarch64-unknown-none-softfloat)

Platform-Agnostic Design

The capability system is designed to be platform-agnostic through:

• Pure Rust Implementation: No platform-specific assembly or system calls
• Bitflag Operations: Efficient bitwise operations supported on all target architectures
• Const Functions: Compile-time evaluation where possible for performance

Sources: src/lib.rs(L30 - L32)  src/lib.rs(L46 - L48)  src/lib.rs(L72 - L78) 

Integration Patterns

Typical ArceOS Usage Patterns

Within ArceOS, cap_access follows several common integration patterns:

1. Kernel Resource Protection: Wrapping kernel data structures with WithCap<T> to control access
2. System Call Interface: Using capability checking in system call implementations
3. Driver Security: Protecting device driver resources with capability-based access
4. Memory Management: Controlling access to memory regions through capability tokens

Example Integration Flow

sequenceDiagram
    participant Application as "Application"
    participant ArceOSKernel as "ArceOS Kernel"
    participant cap_access as "cap_access"
    participant ProtectedResource as "Protected Resource"

    Application ->> ArceOSKernel: "System call with capability"
    ArceOSKernel ->> cap_access: "WithCap::new(resource, cap)"
    cap_access ->> ProtectedResource: "Wrap with capability"
    ProtectedResource -->> cap_access: "WithCap<Resource>"
    cap_access -->> ArceOSKernel: "Protected object"
    Application ->> ArceOSKernel: "Access request"
    ArceOSKernel ->> cap_access: "access(required_cap)"
    cap_access ->> cap_access: "can_access() check"
    alt "Capability sufficient"
        cap_access -->> ArceOSKernel: "Some(&resource)"
        ArceOSKernel -->> Application: "Access granted"
    else "Capability insufficient"
        cap_access -->> ArceOSKernel: "None"
        ArceOSKernel -->> Application: "Access denied"
    end

Sources: src/lib.rs(L24 - L27)  src/lib.rs(L72 - L78)  src/lib.rs(L46 - L48) 

This integration pattern ensures that ArceOS maintains strong security guarantees while providing the performance characteristics required for operating system operations across diverse hardware platforms.

Development Guide

Relevant source files

• .github/workflows/ci.yml
• .gitignore
• Cargo.toml

This document provides guidance for developers contributing to the cap_access library. It covers the project structure, development environment setup, testing procedures, and contribution workflow. For detailed information about the build system and CI pipeline, see Build System and CI. For platform-specific development considerations, see Multi-Platform Support.

Project Structure

The cap_access project follows a standard Rust library structure with emphasis on embedded and no_std compatibility. The codebase is designed as a foundational security primitive for the ArceOS operating system ecosystem.

Repository Organization

flowchart TD
subgraph subGraph2["Generated Artifacts"]
    TARGET["target/Build outputs"]
    DOCS["target/doc/Generated documentation"]
    LOCK["Cargo.lockDependency lock file"]
end
subgraph subGraph1["GitHub Workflows"]
    CI[".github/workflows/ci.ymlContinuous integration"]
end
subgraph subGraph0["Repository Root"]
    CARGO["Cargo.tomlPackage metadata"]
    GITIGNORE[".gitignoreVCS exclusions"]
    SRC["src/Source code"]
end

CARGO --> TARGET
CI --> DOCS
CI --> TARGET
GITIGNORE --> LOCK
GITIGNORE --> TARGET
SRC --> TARGET

Sources: Cargo.toml(L1 - L16)  .gitignore(L1 - L5)  .github/workflows/ci.yml(L1 - L56) 

Package Configuration

The project is configured as a multi-licensed Rust library with specific focus on operating systems and embedded development:

Sources: Cargo.toml(L1 - L12) 

Development Environment

Required Tools

The development environment requires the Rust nightly toolchain with specific components for cross-compilation and code quality:

flowchart TD
subgraph subGraph1["Target Platforms"]
    LINUX["x86_64-unknown-linux-gnuStandard Linux"]
    BAREMETAL["x86_64-unknown-noneBare metal x86_64"]
    RISCV["riscv64gc-unknown-none-elfRISC-V embedded"]
    ARM["aarch64-unknown-none-softfloatARM64 embedded"]
end
subgraph subGraph0["Rust Toolchain"]
    NIGHTLY["rustc nightlyCompiler toolchain"]
    RUSTFMT["rustfmtCode formatter"]
    CLIPPY["clippyLinter"]
    RUSTSRC["rust-srcSource code component"]
end

CLIPPY --> NIGHTLY
NIGHTLY --> ARM
NIGHTLY --> BAREMETAL
NIGHTLY --> LINUX
NIGHTLY --> RISCV
RUSTFMT --> NIGHTLY
RUSTSRC --> NIGHTLY

Sources: .github/workflows/ci.yml(L15 - L19)  .github/workflows/ci.yml(L11 - L12) 

Dependencies

The project maintains minimal dependencies to ensure compatibility with embedded environments:

• bitflags 2.6: Provides efficient bit flag operations for the Cap permission system

Sources: Cargo.toml(L14 - L15) 

Quality Assurance Pipeline

Automated Checks

The CI pipeline enforces code quality through multiple automated checks:

flowchart TD
subgraph subGraph1["Target Matrix"]
    T1["x86_64-unknown-linux-gnu"]
    T2["x86_64-unknown-none"]
    T3["riscv64gc-unknown-none-elf"]
    T4["aarch64-unknown-none-softfloat"]
end
subgraph subGraph0["Code Quality Gates"]
    FORMAT["cargo fmt --all --checkCode formatting validation"]
    LINT["cargo clippy --target TARGET --all-featuresLinting analysis"]
    BUILD["cargo build --target TARGET --all-featuresCompilation verification"]
    TEST["cargo test --target x86_64-unknown-linux-gnuUnit test execution"]
end

BUILD --> T1
BUILD --> T2
BUILD --> T3
BUILD --> T4
BUILD --> TEST
FORMAT --> LINT
LINT --> BUILD
LINT --> T1
LINT --> T2
LINT --> T3
LINT --> T4
TEST --> T1

Sources: .github/workflows/ci.yml(L22 - L30) 

Clippy Configuration

The linting process uses Clippy with specific allowances for the project's design patterns:

• Allows clippy::new_without_default due to the WithCap::new design requiring explicit capability parameters

Sources: .github/workflows/ci.yml(L25) 

Documentation System

Documentation Generation

The project uses a dual documentation system for both development and public consumption:

flowchart TD
subgraph subGraph2["Quality Controls"]
    BROKEN["-D rustdoc::broken_intra_doc_linksLink validation"]
    MISSING["-D missing-docsCoverage enforcement"]
end
subgraph subGraph1["Documentation Outputs"]
    LOCALDIR["target/doc/Local documentation"]
    GHPAGES["gh-pages branchPublished documentation"]
    DOCSRS["docs.rsPublic registry docs"]
end
subgraph subGraph0["Documentation Pipeline"]
    RUSTDOC["cargo doc --no-deps --all-featuresAPI documentation generation"]
    INDEX["printf redirect to index.htmlEntry point creation"]
    DEPLOY["JamesIves/github-pages-deploy-actionGitHub Pages deployment"]
end

BROKEN --> RUSTDOC
DEPLOY --> GHPAGES
GHPAGES --> DOCSRS
INDEX --> LOCALDIR
LOCALDIR --> DEPLOY
MISSING --> RUSTDOC
RUSTDOC --> LOCALDIR

Sources: .github/workflows/ci.yml(L32 - L55)  .github/workflows/ci.yml(L40) 

Documentation Standards

The documentation system enforces strict quality standards:

• Broken Link Detection: All intra-documentation links must be valid
• Coverage Requirement: All public APIs must be documented
• Automatic Deployment: Documentation updates are automatically published on the default branch

Sources: .github/workflows/ci.yml(L40) 

Contributing Workflow

Pre-Commit Requirements

Before submitting changes, ensure all quality gates pass:

1. Format Check: cargo fmt --all -- --check
2. Lint Check: cargo clippy --all-features
3. Build Verification: Test on all supported targets
4. Unit Tests: cargo test on x86_64-unknown-linux-gnu

Supported Platforms

Development must consider compatibility across multiple target architectures:

Sources: .github/workflows/ci.yml(L12) 

The development process is designed to maintain the library's core principles of security, performance, and broad platform compatibility while ensuring code quality through automated verification.

Build System and CI

Relevant source files

• .github/workflows/ci.yml
• Cargo.toml

This document covers the build system configuration, continuous integration pipeline, and multi-target support for the cap_access library. It explains how the project maintains code quality across multiple embedded and systems programming targets, automates testing and documentation generation, and ensures compatibility with no_std environments.

For information about the specific target architectures and their embedded considerations, see Multi-Platform Support.

Package Configuration

The cap_access library is configured as a Rust crate with specific metadata optimized for embedded and systems programming environments. The package configuration emphasizes no_std compatibility and integration with the ArceOS ecosystem.

Core Package Metadata

The project is defined in Cargo.toml(L1 - L12)  with the following key characteristics:

The triple licensing scheme specified in Cargo.toml(L7)  (GPL-3.0-or-later OR Apache-2.0 OR MulanPSL-2.0) provides maximum compatibility with different project requirements, particularly important for kernel and embedded development where licensing constraints vary.

Dependencies

The crate maintains minimal dependencies to support no_std environments:

[dependencies]
bitflags = "2.6"

The single dependency on bitflags version 2.6 Cargo.toml(L14 - L15)  provides efficient flag operations for the capability system while maintaining no_std compatibility.

Sources: Cargo.toml(L1 - L16) 

CI Pipeline Architecture

The continuous integration system implements a comprehensive multi-target testing strategy designed for embedded and systems programming environments. The pipeline validates code quality, builds across multiple architectures, and automates documentation deployment.

Pipeline Structure

flowchart TD
subgraph subGraph2["Quality Checks"]
    FMT["cargo fmt --all -- --check"]
    CLIPPY["cargo clippy --target TARGET --all-features"]
    BUILD["cargo build --target TARGET --all-features"]
    TEST["cargo test --target TARGET"]
end
subgraph subGraph1["CI Job Matrix"]
    RUST_VERSION["nightly toolchain"]
    TARGET_X86_LINUX["x86_64-unknown-linux-gnu"]
    TARGET_X86_BARE["x86_64-unknown-none"]
    TARGET_RISCV["riscv64gc-unknown-none-elf"]
    TARGET_ARM["aarch64-unknown-none-softfloat"]
end
subgraph subGraph0["CI Triggers"]
    PUSH["push events"]
    PR["pull_request events"]
end
subgraph subGraph3["Documentation Job"]
    DOC_BUILD["cargo doc --no-deps --all-features"]
    INDEX_GEN["printf redirect to index.html"]
    PAGES_DEPLOY["JamesIves/github-pages-deploy-action@v4"]
end
CI_JOB["CI_JOB"]

CI_JOB --> RUST_VERSION
DOC_BUILD --> INDEX_GEN
INDEX_GEN --> PAGES_DEPLOY
PR --> CI_JOB
PUSH --> CI_JOB
RUST_VERSION --> TARGET_ARM
RUST_VERSION --> TARGET_RISCV
RUST_VERSION --> TARGET_X86_BARE
RUST_VERSION --> TARGET_X86_LINUX
TARGET_ARM --> BUILD
TARGET_ARM --> CLIPPY
TARGET_RISCV --> BUILD
TARGET_RISCV --> CLIPPY
TARGET_X86_BARE --> BUILD
TARGET_X86_BARE --> CLIPPY
TARGET_X86_LINUX --> BUILD
TARGET_X86_LINUX --> CLIPPY
TARGET_X86_LINUX --> FMT
TARGET_X86_LINUX --> TEST

Sources: .github/workflows/ci.yml(L1 - L56) 

Job Configuration Matrix

The CI pipeline uses a matrix strategy to test across multiple targets simultaneously. The configuration in .github/workflows/ci.yml(L8 - L12)  defines:

strategy:
  fail-fast: false
  matrix:
    rust-toolchain: [nightly]
    targets: [x86_64-unknown-linux-gnu, x86_64-unknown-none, riscv64gc-unknown-none-elf, aarch64-unknown-none-softfloat]

The fail-fast: false setting ensures that failures on one target don't prevent testing of other targets, crucial for multi-architecture development.

Sources: .github/workflows/ci.yml(L8 - L12) 

Quality Assurance Pipeline

The quality assurance process implements multiple validation stages to ensure code correctness and consistency across all supported targets.

Toolchain Setup

Each CI run establishes a complete Rust development environment using .github/workflows/ci.yml(L15 - L19) :

- uses: dtolnay/rust-toolchain@nightly
  with:
    toolchain: ${{ matrix.rust-toolchain }}
    components: rust-src, clippy, rustfmt
    targets: ${{ matrix.targets }}

The rust-src component enables building for bare-metal targets that require custom standard libraries.

Code Quality Checks

flowchart TD
subgraph subGraph1["Quality Enforcement"]
    CLIPPY_CONFIG["-A clippy::new_without_default"]
    FORMAT_STRICT["--check flag enforces formatting"]
    TEST_OUTPUT["--nocapture for debugging"]
    ALL_FEATURES["--all-features enables complete validation"]
end
subgraph subGraph0["Quality Gates"]
    VERSION_CHECK["rustc --version --verbose"]
    FORMAT_CHECK["cargo fmt --all -- --check"]
    LINT_CHECK["cargo clippy --target TARGET"]
    BUILD_CHECK["cargo build --target TARGET"]
    UNIT_TEST["cargo test --target TARGET"]
end

BUILD_CHECK --> ALL_FEATURES
BUILD_CHECK --> UNIT_TEST
FORMAT_CHECK --> FORMAT_STRICT
FORMAT_CHECK --> LINT_CHECK
LINT_CHECK --> BUILD_CHECK
LINT_CHECK --> CLIPPY_CONFIG
UNIT_TEST --> TEST_OUTPUT
VERSION_CHECK --> FORMAT_CHECK

The pipeline enforces strict code formatting through .github/workflows/ci.yml(L22 - L23)  and comprehensive linting via .github/workflows/ci.yml(L24 - L25)  The clippy configuration includes -A clippy::new_without_default to suppress warnings about missing Default implementations, which may not be appropriate for capability-wrapped types.

Testing Strategy

Unit tests execute only on the x86_64-unknown-linux-gnu target .github/workflows/ci.yml(L28 - L30)  as bare-metal targets cannot run standard test frameworks. The test command includes --nocapture to display all output for debugging purposes.

Sources: .github/workflows/ci.yml(L20 - L30) 

Multi-Target Build Matrix

The build system supports diverse execution environments ranging from standard Linux development to bare-metal embedded systems.

Target Architecture Mapping

Build Process Flow

flowchart TD
subgraph subGraph2["Validation Per Target"]
    CLIPPY_LINUX["clippy x86_64-unknown-linux-gnu"]
    CLIPPY_X86_BARE["clippy x86_64-unknown-none"]
    CLIPPY_RISCV["clippy riscv64gc-unknown-none-elf"]
    CLIPPY_ARM["clippy aarch64-unknown-none-softfloat"]
end
subgraph subGraph1["Target-Specific Builds"]
    BUILD_LINUX["cargo build --target x86_64-unknown-linux-gnu"]
    BUILD_X86_BARE["cargo build --target x86_64-unknown-none"]
    BUILD_RISCV["cargo build --target riscv64gc-unknown-none-elf"]
    BUILD_ARM["cargo build --target aarch64-unknown-none-softfloat"]
end
subgraph subGraph0["Source Validation"]
    SOURCE_CODE["src/lib.rs"]
    CARGO_CONFIG["Cargo.toml"]
end

BUILD_ARM --> CLIPPY_ARM
BUILD_LINUX --> CLIPPY_LINUX
BUILD_RISCV --> CLIPPY_RISCV
BUILD_X86_BARE --> CLIPPY_X86_BARE
CARGO_CONFIG --> BUILD_ARM
CARGO_CONFIG --> BUILD_LINUX
CARGO_CONFIG --> BUILD_RISCV
CARGO_CONFIG --> BUILD_X86_BARE
SOURCE_CODE --> BUILD_ARM
SOURCE_CODE --> BUILD_LINUX
SOURCE_CODE --> BUILD_RISCV
SOURCE_CODE --> BUILD_X86_BARE

Each target undergoes identical validation through .github/workflows/ci.yml(L24 - L27)  ensuring consistent behavior across all supported platforms.

Sources: .github/workflows/ci.yml(L12)  .github/workflows/ci.yml(L24 - L27) 

Documentation Generation and Deployment

The documentation system automatically generates and deploys API documentation to GitHub Pages, providing accessible reference material for library users.

Documentation Build Process

The documentation job runs independently of the main CI pipeline .github/workflows/ci.yml(L32 - L56)  and includes sophisticated error handling for different branch contexts:

- name: Build docs
  continue-on-error: ${{ github.ref != env.default-branch && github.event_name != 'pull_request' }}
  run: |
    cargo doc --no-deps --all-features
    printf '<meta http-equiv="refresh" content="0;url=%s/index.html">' $(cargo tree | head -1 | cut -d' ' -f1) > target/doc/index.html

The continue-on-error condition in .github/workflows/ci.yml(L45)  allows documentation failures on non-default branches while ensuring they block merges to the main branch.

Automated Index Generation

The documentation build process includes automatic index page creation .github/workflows/ci.yml(L46 - L48)  that redirects to the main crate documentation, improving user experience when accessing the documentation site.

GitHub Pages Deployment

Documentation deployment uses the JamesIves/github-pages-deploy-action@v4 action .github/workflows/ci.yml(L49 - L55)  with single-commit deployment to the gh-pages branch, ensuring clean deployment history.

The deployment only triggers on pushes to the default branch .github/workflows/ci.yml(L50)  preventing unnecessary deployments from feature branches.

Sources: .github/workflows/ci.yml(L32 - L56) 

Build Environment Configuration

Environment Variables and Flags

The documentation build process configures strict linting through the RUSTDOCFLAGS environment variable .github/workflows/ci.yml(L40) :

RUSTDOCFLAGS: -D rustdoc::broken_intra_doc_links -D missing-docs

This configuration treats broken documentation links and missing documentation as errors, ensuring comprehensive and correct documentation.

Permission Configuration

The documentation job requires special permissions .github/workflows/ci.yml(L36 - L37)  to write to the repository for GitHub Pages deployment:

permissions:
  contents: write

Sources: .github/workflows/ci.yml(L36 - L40) 

Multi-Platform Support

Relevant source files

• .github/workflows/ci.yml
• Cargo.toml

This document covers the multi-platform architecture support implemented in cap_access, including the supported target architectures, build matrix configuration, and platform-specific considerations for embedded and bare-metal environments.

For information about the overall build system and continuous integration setup, see Build System and CI. For details about how cap_access integrates with ArceOS across different platforms, see ArceOS Integration.

Supported Target Architectures

The cap_access library is designed to run across multiple hardware architectures and execution environments, with a particular focus on embedded and systems programming contexts. The library supports both hosted and bare-metal execution environments.

Target Architecture Matrix

flowchart TD
subgraph subGraph2["cap_access Library"]
    core_lib["Core Libraryno_std compatible"]
    bitflags_dep["bitflags dependencyVersion 2.6"]
end
subgraph subGraph1["Bare Metal Environments"]
    x86_64_bare["x86_64-unknown-noneBare metal x86_64"]
    riscv64["riscv64gc-unknown-none-elfRISC-V 64-bit with extensions"]
    aarch64["aarch64-unknown-none-softfloatARM64 without hardware floating point"]
end
subgraph subGraph0["Linux Hosted Environment"]
    x86_64_linux["x86_64-unknown-linux-gnuStandard Linux target"]
end

bitflags_dep --> core_lib
core_lib --> aarch64
core_lib --> riscv64
core_lib --> x86_64_bare
core_lib --> x86_64_linux

Target Architecture Details

Sources: .github/workflows/ci.yml(L12)  Cargo.toml(L12) 

Continuous Integration Build Matrix

The multi-platform support is validated through a comprehensive CI pipeline that builds and tests the library across all supported architectures.

CI Pipeline Architecture

flowchart TD
subgraph subGraph3["Quality Checks"]
    fmt_check["cargo fmt --all --check"]
    clippy_check["cargo clippy --target TARGET"]
    build_check["cargo build --target TARGET"]
    unit_test["cargo test --target TARGET"]
end
subgraph subGraph2["Target Matrix Execution"]
    x86_linux_job["x86_64-unknown-linux-gnuBuild + Test + Clippy"]
    x86_bare_job["x86_64-unknown-noneBuild + Clippy"]
    riscv_job["riscv64gc-unknown-none-elfBuild + Clippy"]
    arm_job["aarch64-unknown-none-softfloatBuild + Clippy"]
end
subgraph subGraph1["Build Matrix Strategy"]
    rust_nightly["Rust Nightly Toolchain"]
    fail_fast_false["fail-fast: false"]
end
subgraph subGraph0["GitHub Actions Workflow"]
    trigger["Push/Pull Request Triggers"]
    ubuntu_runner["ubuntu-latest runner"]
end

arm_job --> build_check
arm_job --> clippy_check
fail_fast_false --> arm_job
fail_fast_false --> riscv_job
fail_fast_false --> x86_bare_job
fail_fast_false --> x86_linux_job
riscv_job --> build_check
riscv_job --> clippy_check
rust_nightly --> fail_fast_false
trigger --> ubuntu_runner
ubuntu_runner --> rust_nightly
x86_bare_job --> build_check
x86_bare_job --> clippy_check
x86_linux_job --> build_check
x86_linux_job --> clippy_check
x86_linux_job --> fmt_check
x86_linux_job --> unit_test

CI Pipeline Configuration Details

The CI pipeline implements a matrix strategy with the following characteristics:

• Rust Toolchain: Nightly with rust-src, clippy, and rustfmt components
• Failure Strategy: fail-fast: false allows all targets to complete even if one fails
• Testing Scope: Unit tests only run on x86_64-unknown-linux-gnu due to hosted environment requirements
• Quality Checks: All targets undergo formatting, linting, and build verification

Sources: .github/workflows/ci.yml(L8 - L12)  .github/workflows/ci.yml(L15 - L19)  .github/workflows/ci.yml(L28 - L30) 

Platform-Specific Considerations

No Standard Library Compatibility

The cap_access library is designed with no_std compatibility as a primary requirement, enabling deployment in resource-constrained embedded environments.

Dependency Management

The library maintains a minimal dependency footprint with only the bitflags crate as an external dependency, ensuring compatibility with embedded environments that cannot support the full Rust standard library.

Sources: Cargo.toml(L14 - L15)  Cargo.toml(L12) 

Architecture-Specific Build Considerations

Each target architecture has specific build requirements and constraints:

x86_64 Targets

• x86_64-unknown-linux-gnu: Full hosted environment with standard library support for development and testing
• x86_64-unknown-none: Bare metal target requiring #![no_std] and custom runtime support

RISC-V Target

• riscv64gc-unknown-none-elf: Supports RISC-V 64-bit with general extensions (G) and compressed instructions (C)
• Requires software floating-point operations
• Common target for embedded RISC-V development boards

ARM64 Target

• aarch64-unknown-none-softfloat: ARM64 architecture without hardware floating-point unit
• Optimized for embedded ARM64 devices with software floating-point implementation
• Suitable for resource-constrained ARM-based systems

Sources: .github/workflows/ci.yml(L12) 

Testing and Validation Strategy

The multi-platform support validation employs a targeted testing strategy that accounts for the constraints of different execution environments.

Platform Testing Matrix

flowchart TD
subgraph subGraph1["Target Platform Coverage"]
    x86_linux["x86_64-unknown-linux-gnu✓ Format ✓ Lint ✓ Build ✓ Test"]
    x86_bare["x86_64-unknown-none✓ Format ✓ Lint ✓ Build ✗ Test"]
    riscv["riscv64gc-unknown-none-elf✓ Format ✓ Lint ✓ Build ✗ Test"]
    arm["aarch64-unknown-none-softfloat✓ Format ✓ Lint ✓ Build ✗ Test"]
end
subgraph subGraph0["Test Categories"]
    format_test["Code Formattingcargo fmt --all --check"]
    lint_test["Static Analysiscargo clippy"]
    build_test["Compilationcargo build"]
    unit_test["Runtime Testingcargo test"]
end

build_test --> arm
build_test --> riscv
build_test --> x86_bare
build_test --> x86_linux
format_test --> arm
format_test --> riscv
format_test --> x86_bare
format_test --> x86_linux
lint_test --> arm
lint_test --> riscv
lint_test --> x86_bare
lint_test --> x86_linux
unit_test --> x86_linux

Testing Constraints by Platform

• Hosted Platforms: Full test suite including unit tests can execute in the hosted Linux environment
• Bare Metal Platforms: Limited to static analysis and compilation verification due to lack of test runtime
• Cross-Compilation: All bare metal targets are cross-compiled from the x86_64 Linux host environment

The testing strategy ensures that while runtime testing is limited to hosted environments, all platforms receive comprehensive static analysis and successful compilation verification.

Sources: .github/workflows/ci.yml(L22 - L30)  .github/workflows/ci.yml(L25)  .github/workflows/ci.yml(L29) 

Overview

Relevant source files

• Cargo.toml
• README.md
• src/lib.rs

The kspin crate provides kernel-space spinlock implementations with configurable protection levels for the ArceOS operating system ecosystem. This library offers three distinct spinlock types that control interrupt and preemption states during critical sections, enabling safe concurrent access to shared data in kernel environments.

This document covers the fundamental architecture, protection mechanisms, and usage patterns of the kspin crate. For detailed implementation specifics of the core spinlock logic, see Core Implementation Architecture. For usage guidelines and safety considerations, see Usage Guidelines and Safety.

System Architecture

The kspin crate implements a layered architecture where specialized spinlock types are built upon a generic BaseSpinLock foundation. The system integrates with the kernel_guard crate to provide different levels of protection through compile-time type safety.

Component Architecture

flowchart TD
subgraph subGraph3["Feature Flags"]
    SMPFeature["smp feature"]
end
subgraph subGraph2["External Dependencies"]
    NoOp["kernel_guard::NoOp"]
    NoPreempt["kernel_guard::NoPreempt"]
    NoPreemptIrqSave["kernel_guard::NoPreemptIrqSave"]
    CfgIf["cfg-if"]
end
subgraph subGraph1["Core Implementation"]
    BaseSpinLock["BaseSpinLock"]
    BaseSpinLockGuard["BaseSpinLockGuard"]
end
subgraph subGraph0["Public API Layer"]
    SpinRaw["SpinRaw"]
    SpinNoPreempt["SpinNoPreempt"]
    SpinNoIrq["SpinNoIrq"]
    SpinRawGuard["SpinRawGuard"]
    SpinNoPreemptGuard["SpinNoPreemptGuard"]
    SpinNoIrqGuard["SpinNoIrqGuard"]
end

BaseSpinLock --> CfgIf
BaseSpinLock --> NoOp
BaseSpinLock --> NoPreempt
BaseSpinLock --> NoPreemptIrqSave
BaseSpinLock --> SMPFeature
SpinNoIrq --> BaseSpinLock
SpinNoIrqGuard --> BaseSpinLockGuard
SpinNoPreempt --> BaseSpinLock
SpinNoPreemptGuard --> BaseSpinLockGuard
SpinRaw --> BaseSpinLock
SpinRawGuard --> BaseSpinLockGuard

Sources: src/lib.rs(L1 - L37)  Cargo.toml(L19 - L21)  Cargo.toml(L14 - L17) 

Protection Level Hierarchy

The kspin crate provides three protection levels, each corresponding to different kernel execution contexts and safety requirements. The protection levels are implemented through type aliases that parameterize the generic BaseSpinLock with specific guard types.

Protection Levels and Guard Mapping

flowchart TD
subgraph subGraph3["Usage Context"]
    IRQDisabledContext["IRQ-disabled context"]
    GeneralKernelContext["General kernel context"]
    InterruptHandler["Interrupt handler"]
end
subgraph subGraph2["Protection Behavior"]
    NoBehavior["No protectionManual control required"]
    PreemptionDisabled["Disables preemptionIRQ context required"]
    FullProtection["Disables preemption + IRQsAny context safe"]
end
subgraph subGraph1["Guard Types"]
    NoOp["NoOp"]
    NoPreempt["NoPreempt"]
    NoPreemptIrqSave["NoPreemptIrqSave"]
end
subgraph subGraph0["Spinlock Types"]
    SpinRaw["SpinRaw"]
    SpinNoPreempt["SpinNoPreempt"]
    SpinNoIrq["SpinNoIrq"]
end

FullProtection --> GeneralKernelContext
FullProtection --> InterruptHandler
NoBehavior --> IRQDisabledContext
NoOp --> NoBehavior
NoPreempt --> PreemptionDisabled
NoPreemptIrqSave --> FullProtection
PreemptionDisabled --> IRQDisabledContext
SpinNoIrq --> NoPreemptIrqSave
SpinNoPreempt --> NoPreempt
SpinRaw --> NoOp

Sources: src/lib.rs(L10 - L36)  README.md(L16 - L33) 

Key Design Principles

The crate follows a compile-time optimization strategy where the smp feature flag controls whether actual atomic operations are generated. In single-core environments, the lock state is optimized away entirely, reducing the spinlock to a simple guard management system.

Sources: Cargo.toml(L14 - L17)  README.md(L12) 

Integration with ArceOS Ecosystem

The kspin crate serves as a foundational synchronization primitive within the ArceOS operating system project. It provides the kernel-level locking mechanisms required for:

• Memory management subsystems requiring atomic access to page tables and allocation structures
• Device driver frameworks needing interrupt-safe critical sections
• Scheduler components protecting task queues and scheduling state
• File system implementations ensuring metadata consistency

The library's design emphasizes kernel-space usage through its dependency on kernel_guard, which provides the underlying preemption and interrupt control mechanisms. The three-tier protection model allows different kernel subsystems to choose the appropriate level of protection based on their execution context requirements.

Sources: Cargo.toml(L6)  Cargo.toml(L8)  src/lib.rs(L6) 

Compilation Model

The kspin crate uses conditional compilation to adapt its behavior based on target environment characteristics:

flowchart TD
subgraph subGraph2["Multi-Core Build"]
    AtomicState["AtomicBool lock state"]
    CompareExchange["compare_exchange operations"]
    SpinBehavior["Actual spinning behavior"]
end
subgraph subGraph1["Single-Core Build"]
    NoLockState["No lock state field"]
    NoAtomics["No atomic operations"]
    AlwaysSucceed["Lock always succeeds"]
end
subgraph subGraph0["Feature Detection"]
    SMPCheck["smp feature enabled?"]
end

SMPCheck --> AlwaysSucceed
SMPCheck --> AtomicState
SMPCheck --> CompareExchange
SMPCheck --> NoAtomics
SMPCheck --> NoLockState
SMPCheck --> SpinBehavior

This compilation strategy ensures that embedded and single-core kernel environments receive fully optimized code with no synchronization overhead, while multi-core systems get the full atomic operation implementation required for correct concurrent behavior.

Sources: README.md(L12)  Cargo.toml(L15 - L16) 

Project Structure and Dependencies

Relevant source files

• .gitignore
• Cargo.lock
• Cargo.toml

This document describes the organizational structure of the kspin crate, including its file layout, external dependencies, and build configuration. It covers the project's dependency management, feature flag system, and how the crate is organized to support different compilation targets.

For detailed information about the specific spinlock types and their usage, see Spinlock Types and Public API. For implementation details of the core architecture, see Core Implementation Architecture.

File Structure Overview

The kspin crate follows a minimal but well-organized structure typical of focused Rust libraries. The project consists of core source files, build configuration, and development tooling.

Project File Organization

flowchart TD
subgraph subGraph2["Development Tools"]
    VSCodeDir[".vscode/IDE configuration"]
    TargetDir["target/Build artifacts (ignored)"]
end
subgraph subGraph1["Source Code (src/)"]
    LibRs["lib.rsPublic API & type aliases"]
    BaseRs["base.rsCore BaseSpinLock implementation"]
end
subgraph subGraph0["Root Directory"]
    CargoToml["Cargo.tomlProject metadata & dependencies"]
    CargoLock["Cargo.lockDependency lock file"]
    GitIgnore[".gitignoreVersion control exclusions"]
end
subgraph CI/CD["CI/CD"]
    GithubActions[".github/workflows/Automated testing & docs"]
end

CargoLock --> CargoToml
CargoToml --> BaseRs
CargoToml --> LibRs
GitIgnore --> TargetDir
GitIgnore --> VSCodeDir
LibRs --> BaseRs

Sources: Cargo.toml(L1 - L22)  .gitignore(L1 - L4)  Cargo.lock(L1 - L74) 

Source File Responsibilities

The crate deliberately maintains a minimal file structure with only two source files, emphasizing simplicity and focused functionality.

Sources: Cargo.toml(L1 - L22) 

External Dependencies

The kspin crate has a carefully curated set of external dependencies that provide essential functionality for kernel-space synchronization and conditional compilation.

Direct Dependencies

flowchart TD
subgraph subGraph2["Transitive Dependencies"]
    CrateInterface["crate_interfacev0.1.4Interface definitions"]
    ProcMacro2["proc-macro2v1.0.93Procedural macros"]
    Quote["quotev1.0.38Code generation"]
    Syn["synv2.0.96Syntax parsing"]
    UnicodeIdent["unicode-identv1.0.14Unicode support"]
end
subgraph subGraph1["Direct Dependencies"]
    CfgIf["cfg-ifv1.0.0Conditional compilation"]
    KernelGuard["kernel_guardv0.1.2Protection mechanisms"]
end
subgraph subGraph0["kspin Crate"]
    KSpin["kspinv0.1.0"]
end

CrateInterface --> ProcMacro2
CrateInterface --> Quote
CrateInterface --> Syn
KSpin --> CfgIf
KSpin --> KernelGuard
KernelGuard --> CfgIf
KernelGuard --> CrateInterface
ProcMacro2 --> UnicodeIdent
Quote --> ProcMacro2
Syn --> ProcMacro2
Syn --> Quote
Syn --> UnicodeIdent

Sources: Cargo.toml(L19 - L21)  Cargo.lock(L5 - L74) 

Dependency Roles

The kernel_guard crate is the primary external dependency, providing the guard types that implement different protection levels. The cfg-if crate enables clean conditional compilation based on feature flags.

Sources: Cargo.toml(L20 - L21)  Cargo.lock(L23 - L30) 

Feature Configuration

The kspin crate uses Cargo feature flags to enable compile-time optimization for different target environments, particularly distinguishing between single-core and multi-core systems.

Feature Flag System

flowchart TD
subgraph subGraph2["Generated Code Characteristics"]
    SMPCode["SMP Implementation• AtomicBool for lock state• compare_exchange operations• Actual spinning behavior"]
    SingleCoreCode["Single-core Implementation• No lock state field• Lock always succeeds• No atomic operations"]
end
subgraph subGraph1["Compilation Modes"]
    SMPMode["SMP ModeMulti-core systems"]
    SingleCoreMode["Single-core ModeEmbedded/simple systems"]
end
subgraph subGraph0["Feature Flags"]
    SMPFeature["smpMulti-core support"]
    DefaultFeature["defaultEmpty set"]
end

DefaultFeature --> SingleCoreMode
SMPFeature --> SMPMode
SMPMode --> SMPCode
SingleCoreMode --> SingleCoreCode

Sources: Cargo.toml(L14 - L17) 

Feature Flag Details

The feature system allows the same codebase to generate dramatically different implementations:

• Without smp: Lock operations are compile-time no-ops, eliminating all atomic overhead
• With smp: Full atomic spinlock implementation with proper memory ordering

Sources: Cargo.toml(L14 - L17) 

Build System Organization

The project follows standard Rust crate conventions with specific configurations for kernel-space development and multi-platform support.

Package Metadata Configuration

flowchart TD
subgraph Licensing["Licensing"]
    License["licenseGPL-3.0-or-later OR Apache-2.0 OR MulanPSL-2.0"]
end
subgraph subGraph2["Repository Links"]
    Homepage["homepageArceOS GitHub"]
    Repository["repositorykspin GitHub"]
    Documentation["documentationdocs.rs"]
end
subgraph subGraph1["Package Classification"]
    Keywords["keywords['arceos', 'synchronization', 'spinlock', 'no-irq']"]
    Categories["categories['os', 'no-std']"]
    Description["description'Spinlocks for kernel space...'"]
end
subgraph subGraph0["Package Identity"]
    Name["name = 'kspin'"]
    Version["version = '0.1.0'"]
    Edition["edition = '2021'"]
    Authors["authors = ['Yuekai Jia']"]
end

Description --> Repository
Homepage --> License
Name --> Keywords
Repository --> Documentation
Version --> Categories

Sources: Cargo.toml(L1 - L12) 

Development Environment Setup

The project includes configuration for common development tools:

The .gitignore configuration ensures that build artifacts and IDE-specific files don't pollute the repository, while the committed Cargo.lock file ensures reproducible builds across different environments.

Sources: .gitignore(L1 - L4)  Cargo.lock(L1 - L4) 

Spinlock Types and Public API

Relevant source files

• README.md
• src/lib.rs

This document covers the three main spinlock types exposed by the kspin crate and their public interface. These types provide different levels of protection suitable for various kernel contexts. For detailed implementation internals, see Core Implementation Architecture. For comprehensive usage guidelines and safety requirements, see Usage Guidelines and Safety.

Spinlock Type Overview

The kspin crate provides three specialized spinlock types, each offering a different balance between performance and protection. All types are implemented as type aliases of the generic BaseSpinLock with different guard types from the kernel_guard crate.

Sources: src/lib.rs(L10 - L36) 

Type Hierarchy and Guard Relationships

flowchart TD
subgraph subGraph2["Core Implementation (src/base.rs)"]
    BaseSpinLock["BaseSpinLock<G, T>Generic spinlock"]
    BaseSpinLockGuard["BaseSpinLockGuard<'a, G, T>RAII guard"]
end
subgraph subGraph1["kernel_guard Crate Guards"]
    NoOp["NoOpDoes nothing"]
    NoPreempt["NoPreemptDisables preemption"]
    NoPreemptIrqSave["NoPreemptIrqSaveDisables preemption + IRQs"]
end
subgraph subGraph0["Public API Types (src/lib.rs)"]
    SpinRaw["SpinRaw<T>BaseSpinLock<NoOp, T>"]
    SpinNoPreempt["SpinNoPreempt<T>BaseSpinLock<NoPreempt, T>"]
    SpinNoIrq["SpinNoIrq<T>BaseSpinLock<NoPreemptIrqSave, T>"]
    SpinRawGuard["SpinRawGuard<'a, T>BaseSpinLockGuard<'a, NoOp, T>"]
    SpinNoPreemptGuard["SpinNoPreemptGuard<'a, T>BaseSpinLockGuard<'a, NoPreempt, T>"]
    SpinNoIrqGuard["SpinNoIrqGuard<'a, T>BaseSpinLockGuard<'a, NoPreemptIrqSave, T>"]
end

SpinNoIrq --> BaseSpinLock
SpinNoIrq --> NoPreemptIrqSave
SpinNoIrq --> SpinNoIrqGuard
SpinNoIrqGuard --> BaseSpinLockGuard
SpinNoPreempt --> BaseSpinLock
SpinNoPreempt --> NoPreempt
SpinNoPreempt --> SpinNoPreemptGuard
SpinNoPreemptGuard --> BaseSpinLockGuard
SpinRaw --> BaseSpinLock
SpinRaw --> NoOp
SpinRaw --> SpinRawGuard
SpinRawGuard --> BaseSpinLockGuard

Sources: src/lib.rs(L6 - L36) 

Public API Structure

flowchart TD
subgraph subGraph2["RAII Lifecycle"]
    acquire["Guard AcquisitionProtection enabled"]
    critical["Critical SectionData access"]
    release["Guard DropProtection disabled"]
end
subgraph subGraph1["Guard Operations"]
    deref["Deref::deref()→ &T"]
    deref_mut["DerefMut::deref_mut()→ &mut T"]
    drop_guard["Drop::drop()→ ()"]
end
subgraph subGraph0["Spinlock Operations"]
    new["new(data: T)→ SpinLock<T>"]
    lock["lock()→ Guard<'_, T>"]
    try_lock["try_lock()→ Option<Guard<'_, T>>"]
    is_locked["is_locked()→ bool"]
end

acquire --> deref
acquire --> deref_mut
critical --> drop_guard
deref --> critical
deref_mut --> critical
drop_guard --> release
lock --> acquire
new --> lock
new --> try_lock
try_lock --> acquire

Sources: src/lib.rs(L8)  README.md(L19 - L32) 

Type Definitions and Documentation

SpinRaw

SpinRaw<T> provides the fastest spinlock implementation with no built-in protection mechanisms. It is defined as BaseSpinLock<NoOp, T> where the NoOp guard performs no protection operations.

Key Characteristics:

• Zero protection overhead
• Requires manual IRQ and preemption management
• Must be used in preemption-disabled and IRQ-disabled contexts
• Cannot be used in interrupt handlers

Sources: src/lib.rs(L29 - L33) 

SpinNoPreempt

SpinNoPreempt<T> disables kernel preemption during lock acquisition and critical sections. It is defined as BaseSpinLock<NoPreempt, T>.

Key Characteristics:

• Automatically disables preemption when acquiring the lock
• Safe from task switching but not from interrupts
• Must be used in IRQ-disabled contexts
• Cannot be used in interrupt handlers

Sources: src/lib.rs(L10 - L15) 

SpinNoIrq

SpinNoIrq<T> provides the highest level of protection by disabling both kernel preemption and local IRQs. It is defined as BaseSpinLock<NoPreemptIrqSave, T>.

Key Characteristics:

• Disables both preemption and IRQs
• Safe to use in any context including IRQ-enabled environments
• Highest protection overhead but maximum safety
• Can be used in interrupt handlers

Sources: src/lib.rs(L20 - L24) 

Associated Guard Types

Each spinlock type has a corresponding guard type that implements the RAII pattern:

• SpinRawGuard<'a, T> for SpinRaw<T>
• SpinNoPreemptGuard<'a, T> for SpinNoPreempt<T>
• SpinNoIrqGuard<'a, T> for SpinNoIrq<T>

These guards provide mutable access to the protected data through Deref and DerefMut implementations, and automatically release the lock when dropped.

Sources: src/lib.rs(L17 - L18)  src/lib.rs(L26 - L27)  src/lib.rs(L35 - L36) 

Usage Example from Public Documentation

The crate provides standard usage patterns as demonstrated in the README:

// Raw spinlock - fastest, requires manual protection
let data = SpinRaw::new(());
let mut guard = data.lock();
/* critical section, does nothing while trying to lock. */
drop(guard);

// Preemption-disabled spinlock
let data = SpinNoPreempt::new(());
let mut guard = data.lock();
/* critical section, preemption are disabled. */
drop(guard);

// Full protection spinlock
let data = SpinNoIrq::new(());
let mut guard = data.lock();
/* critical section, both preemption and IRQs are disabled. */
drop(guard);

Sources: README.md(L16 - L33) 

SpinRaw

Relevant source files

• README.md
• src/lib.rs

Purpose and Scope

This page documents SpinRaw<T>, the raw spinlock implementation in the kspin crate that provides no built-in protection mechanisms. SpinRaw offers the fastest performance among the three spinlock types but requires manual management of preemption and interrupt state by the caller.

For information about spinlocks with built-in preemption protection, see SpinNoPreempt. For full protection including IRQ disabling, see SpinNoIrq. For detailed implementation internals, see BaseSpinLock and BaseSpinLockGuard. For comprehensive usage guidelines across all spinlock types, see Usage Guidelines and Safety.

Type Definition and Basic Interface

SpinRaw<T> is implemented as a type alias that specializes the generic BaseSpinLock with the NoOp guard type from the kernel_guard crate.

Core Type Definitions

flowchart TD
subgraph subGraph0["SpinRaw Type System"]
    SpinRaw["SpinRaw<T>Type alias"]
    BaseSpinLock["BaseSpinLock<NoOp, T>Generic implementation"]
    SpinRawGuard["SpinRawGuard<'a, T>RAII guard"]
    BaseSpinLockGuard["BaseSpinLockGuard<'a, NoOp, T>Generic guard"]
    NoOp["NoOpkernel_guard guard type"]
end

BaseSpinLock --> BaseSpinLockGuard
BaseSpinLock --> NoOp
BaseSpinLockGuard --> NoOp
SpinRaw --> BaseSpinLock
SpinRawGuard --> BaseSpinLockGuard

Sources: src/lib.rs(L33 - L36) 

The SpinRaw<T> type provides the standard spinlock interface methods inherited from BaseSpinLock:

Protection Behavior and NoOp Guard

The defining characteristic of SpinRaw is its use of the NoOp guard type, which performs no protection actions during lock acquisition or release.

Protection Flow Diagram

flowchart TD
subgraph subGraph1["NoOp Guard Behavior"]
    NoOpAcquire["NoOp::acquire()Does nothing"]
    NoOpRelease["NoOp::release()Does nothing"]
end
subgraph subGraph0["SpinRaw Lock Acquisition Flow"]
    Start["lock() called"]
    TryAcquire["Attempt atomic acquisition"]
    IsLocked["Lock alreadyheld?"]
    Spin["Spin wait(busy loop)"]
    Acquired["Lock acquired"]
    GuardCreated["SpinRawGuard createdwith NoOp::acquire()"]
end
note1["Note: No preemption disablingNo IRQ disablingNo protection barriers"]

Acquired --> GuardCreated
GuardCreated --> NoOpAcquire
GuardCreated --> NoOpRelease
IsLocked --> Acquired
IsLocked --> Spin
NoOpAcquire --> note1
NoOpRelease --> note1
Spin --> TryAcquire
Start --> TryAcquire
TryAcquire --> IsLocked

Sources: src/lib.rs(L29 - L36)  src/base.rs

Unlike SpinNoPreempt and SpinNoIrq, the NoOp guard performs no system-level protection operations:

• No preemption disabling/enabling
• No interrupt disabling/enabling
• No memory barriers beyond those required for the atomic lock operations

Safety Requirements and Usage Contexts

SpinRaw places the burden of ensuring safe usage entirely on the caller. The lock itself provides only the basic mutual exclusion mechanism without any system-level protections.

Required Caller Responsibilities

flowchart TD
subgraph subGraph1["Consequences of Violation"]
    Deadlock["Potential deadlockif preempted while holding lock"]
    RaceCondition["Race conditionswith interrupt handlers"]
    DataCorruption["Data corruptionfrom concurrent access"]
end
subgraph subGraph0["Caller Must Ensure"]
    PreemptDisabled["Preemption already disabledBefore calling lock()"]
    IRQDisabled["Local IRQs already disabledBefore calling lock()"]
    NoInterruptUse["Never used ininterrupt handlers"]
    ProperContext["Operating in appropriatekernel context"]
end
subgraph subGraph2["Safe Usage Pattern"]
    DisablePreempt["disable_preemption()"]
    DisableIRQ["disable_local_irq()"]
    UseLock["SpinRaw::lock()"]
    CriticalSection["/* critical section */"]
    ReleaseLock["drop(guard)"]
    EnableIRQ["enable_local_irq()"]
    EnablePreempt["enable_preemption()"]
end

CriticalSection --> ReleaseLock
DisableIRQ --> UseLock
DisablePreempt --> DisableIRQ
EnableIRQ --> EnablePreempt
IRQDisabled --> RaceCondition
NoInterruptUse --> RaceCondition
PreemptDisabled --> Deadlock
ProperContext --> DataCorruption
ReleaseLock --> EnableIRQ
UseLock --> CriticalSection

Sources: src/lib.rs(L31 - L32)  README.md(L19 - L22) 

Performance Characteristics

SpinRaw offers the highest performance among the three spinlock types due to its minimal overhead approach.

Performance Comparison

SMP vs Single-Core Behavior

flowchart TD
subgraph subGraph2["Feature Flag Impact on SpinRaw"]
    SMPEnabled["smp featureenabled?"]
    subgraph subGraph1["Single-Core Path (no smp)"]
        NoLockField["No lock fieldoptimized out"]
        NoAtomics["No atomic operationslock always succeeds"]
        NoSpinning["No spinning behaviorimmediate success"]
        NoOverhead["Zero overheadcompile-time optimization"]
    end
    subgraph subGraph0["Multi-Core Path (smp)"]
        AtomicField["AtomicBool lock fieldin BaseSpinLock"]
        CompareExchange["compare_exchange operationsfor acquisition"]
        RealSpin["Actual spinning behavioron contention"]
        MemoryOrder["Memory orderingconstraints"]
    end
end

AtomicField --> CompareExchange
CompareExchange --> RealSpin
NoAtomics --> NoSpinning
NoLockField --> NoAtomics
NoSpinning --> NoOverhead
RealSpin --> MemoryOrder
SMPEnabled --> AtomicField
SMPEnabled --> NoLockField

Sources: README.md(L12)  src/base.rs

In single-core environments (without the smp feature), SpinRaw becomes a zero-cost abstraction since no actual locking is necessary when preemption and interrupts are properly controlled.

Integration with BaseSpinLock Architecture

SpinRaw leverages the generic BaseSpinLock implementation while providing no additional protection through its NoOp guard parameter.

Architectural Mapping

classDiagram
class SpinRaw {
    <<type alias>>
    
    +new(data: T) SpinRaw~T~
    +lock() SpinRawGuard~T~
    +try_lock() Option~SpinRawGuard~T~~
}

class BaseSpinLock~NoOp_T~ {
    -lock_state: AtomicBool
    +new(data: T) Self
    +lock() BaseSpinLockGuard~NoOp_T~
    +try_lock() Option~BaseSpinLockGuard~NoOp_T~~
    -try_lock_inner() bool
}

class SpinRawGuard {
    <<type alias>>
    
    +deref() &T
    +deref_mut() &mut T
}

class BaseSpinLockGuard~NoOp_T~ {
    -lock: BaseSpinLock~NoOp_T~
    -guard_state: NoOp
    +new() Self
    +deref() &T
    +deref_mut() &mut T
}

class NoOp {
    
    +acquire() Self
    +release()
}

SpinRaw  --|>  BaseSpinLock : type alias
SpinRawGuard  --|>  BaseSpinLockGuard : type alias
BaseSpinLock  -->  BaseSpinLockGuard : creates
BaseSpinLockGuard  -->  NoOp : uses

Sources: src/lib.rs(L33 - L36)  src/base.rs

The SpinRaw type inherits all functionality from BaseSpinLock while the NoOp guard ensures minimal overhead by performing no protection operations during the guard's lifetime.

SpinNoPreempt

Relevant source files

• README.md
• src/lib.rs

This document describes the SpinNoPreempt spinlock type, which provides kernel-space synchronization by disabling preemption during critical sections. This spinlock offers a balanced approach between performance and safety, suitable for IRQ-disabled contexts where preemption control is necessary but interrupt masking is already handled externally.

For information about the raw spinlock without protection mechanisms, see SpinRaw. For the full-protection spinlock that also disables IRQs, see SpinNoIrq. For comprehensive usage guidelines across all spinlock types, see Usage Guidelines and Safety.

Type Definition and Core Components

SpinNoPreempt<T> is implemented as a type alias that combines the generic BaseSpinLock with the NoPreempt guard type from the kernel_guard crate. This composition provides preemption-disabled synchronization while maintaining type safety and RAII semantics.

Type Composition Diagram

flowchart TD
SpinNoPreempt["SpinNoPreempt<T>"]
BaseSpinLock["BaseSpinLock<NoPreempt, T>"]
NoPreempt["NoPreempt"]
SpinNoPreemptGuard["SpinNoPreemptGuard<'a, T>"]
BaseSpinLockGuard["BaseSpinLockGuard<'a, NoPreempt, T>"]

BaseSpinLock --> NoPreempt
BaseSpinLock --> SpinNoPreemptGuard
BaseSpinLockGuard --> NoPreempt
SpinNoPreempt --> BaseSpinLock
SpinNoPreemptGuard --> BaseSpinLockGuard

Sources: src/lib.rs(L15 - L18) 

The key components are:

Sources: src/lib.rs(L15 - L18)  src/lib.rs(L6) 

Safety Requirements and Usage Context

SpinNoPreempt has specific safety requirements that must be understood before use. The spinlock is designed for contexts where IRQ handling is already managed externally, but preemption control is needed for the critical section.

Safety Context Requirements

flowchart TD
subgraph subGraph2["SpinNoPreempt Behavior"]
    AcquireLock["lock() called"]
    DisablePreemption["NoPreempt::acquire()"]
    CriticalExecution["Protected code execution"]
    EnablePreemption["NoPreempt::release()"]
    ReleaseLock["Guard dropped"]
end
subgraph subGraph1["Unsafe Usage Contexts"]
    IRQEnabled["IRQ-Enabled Context"]
    InterruptHandler["Interrupt Handler"]
    UserSpace["User Space"]
end
subgraph subGraph0["Safe Usage Contexts"]
    IRQDisabled["IRQ-Disabled Context"]
    KernelCode["Kernel Code with IRQ Control"]
    CriticalSection["Existing Critical Section"]
end

AcquireLock --> DisablePreemption
CriticalExecution --> EnablePreemption
CriticalSection --> AcquireLock
DisablePreemption --> CriticalExecution
EnablePreemption --> ReleaseLock
IRQDisabled --> AcquireLock
IRQEnabled --> AcquireLock
InterruptHandler --> AcquireLock
KernelCode --> AcquireLock

Sources: src/lib.rs(L10 - L14) 

Key Safety Rules

1. IRQ Context Requirement: Must be used in local IRQ-disabled context
2. Interrupt Handler Prohibition: Never use in interrupt handlers
3. Preemption Assumption: Assumes external IRQ management is already in place

The documentation explicitly states: "It must be used in the local IRQ-disabled context, or never be used in interrupt handlers."

Sources: src/lib.rs(L13 - L14) 

Implementation Architecture

SpinNoPreempt leverages the modular architecture of the kspin crate, where the BaseSpinLock provides the core spinning logic and the NoPreempt guard type defines the protection behavior.

Lock Acquisition Flow

Sources: src/lib.rs(L15)  src/base.rs (referenced via BaseSpinLock usage)

Comparison with Other Spinlock Types

SpinNoPreempt occupies the middle ground in the protection spectrum provided by the kspin crate, offering more protection than SpinRaw but less overhead than SpinNoIrq.

Protection Level Comparison

Sources: src/lib.rs(L15)  src/lib.rs(L24)  src/lib.rs(L33) 

Guard Type Mapping

flowchart TD
subgraph subGraph2["Protection Behavior"]
    NoneProtection["No protection"]
    PreemptProtection["Preemption disabled"]
    FullProtection["Preemption + IRQ disabled"]
end
subgraph subGraph1["Guard Types (kernel_guard)"]
    NoOp["NoOp"]
    NoPreempt["NoPreempt"]
    NoPreemptIrqSave["NoPreemptIrqSave"]
end
subgraph subGraph0["Spinlock Types"]
    SpinRaw["SpinRaw<T>"]
    SpinNoPreempt["SpinNoPreempt<T>"]
    SpinNoIrq["SpinNoIrq<T>"]
end

NoOp --> NoneProtection
NoPreempt --> PreemptProtection
NoPreemptIrqSave --> FullProtection
SpinNoIrq --> NoPreemptIrqSave
SpinNoPreempt --> NoPreempt
SpinRaw --> NoOp

Sources: src/lib.rs(L6)  src/lib.rs(L15)  src/lib.rs(L24)  src/lib.rs(L33) 

Usage Patterns and Examples

The typical usage pattern for SpinNoPreempt follows the RAII principle, where the guard automatically manages preemption state during its lifetime.

Basic Usage Pattern

From the repository examples, the standard pattern is:

let data = SpinNoPreempt::new(());
let mut guard = data.lock();
/* critical section, preemption are disabled. */
drop(guard);

Sources: README.md(L24 - L27) 

Method Interface

SpinNoPreempt<T> inherits all methods from BaseSpinLock<NoPreempt, T>, providing the standard spinlock interface:

The guard provides:

• Automatic preemption re-enabling on drop
• Mutable access to protected data via Deref and DerefMut
• Lock release when guard goes out of scope

Sources: src/lib.rs(L15 - L18)  src/base.rs (inherited interface)

SpinNoIrq

Relevant source files

• README.md
• src/lib.rs

SpinNoIrq is the full-protection spinlock implementation in the kspin crate that provides maximum safety by disabling both kernel preemption and local interrupts during lock acquisition and critical sections. This is the safest but most performance-intensive spinlock variant, designed for use in IRQ-enabled contexts where complete isolation is required.

For information about lighter-weight spinlock variants, see SpinRaw and SpinNoPreempt. For comprehensive usage guidelines across all spinlock types, see Usage Guidelines and Safety.

Type Definition and Core Components

SpinNoIrq is implemented as a type alias that specializes the generic BaseSpinLock with the NoPreemptIrqSave guard type from the kernel_guard crate.

flowchart TD
subgraph subGraph0["SpinNoIrq Type System"]
    SpinNoIrq["SpinNoIrq<T>Type alias"]
    BaseSpinLock["BaseSpinLock<NoPreemptIrqSave, T>Generic implementation"]
    SpinNoIrqGuard["SpinNoIrqGuard<'a, T>RAII guard"]
    BaseSpinLockGuard["BaseSpinLockGuard<'a, NoPreemptIrqSave, T>Generic guard"]
    NoPreemptIrqSave["NoPreemptIrqSavekernel_guard protection"]
end

BaseSpinLock --> NoPreemptIrqSave
BaseSpinLockGuard --> NoPreemptIrqSave
SpinNoIrq --> BaseSpinLock
SpinNoIrqGuard --> BaseSpinLockGuard

The core type definitions establish the relationship between the public API and the underlying implementation:

Sources: src/lib.rs(L24 - L27) 

Protection Mechanism

SpinNoIrq implements a dual-protection mechanism that addresses both concurrency sources in kernel environments: task preemption and interrupt handling.

sequenceDiagram
    participant CallingThread as "Calling Thread"
    participant SpinNoIrq as "SpinNoIrq"
    participant NoPreemptIrqSave as "NoPreemptIrqSave"
    participant KernelScheduler as "Kernel Scheduler"
    participant InterruptController as "Interrupt Controller"

    CallingThread ->> SpinNoIrq: lock()
    SpinNoIrq ->> NoPreemptIrqSave: acquire()
    NoPreemptIrqSave ->> KernelScheduler: disable_preemption()
    NoPreemptIrqSave ->> InterruptController: save_and_disable_irqs()
    Note over CallingThread,InterruptController: Critical Section<br>- No task switches possible<br>- No interrupts delivered<br>- Complete isolation
    SpinNoIrq ->> CallingThread: SpinNoIrqGuard
    CallingThread ->> CallingThread: /* access protected data */
    CallingThread ->> SpinNoIrq: drop(guard)
    SpinNoIrq ->> NoPreemptIrqSave: release()
    NoPreemptIrqSave ->> InterruptController: restore_irqs()
    NoPreemptIrqSave ->> KernelScheduler: enable_preemption()

The protection mechanism operates through the NoPreemptIrqSave guard which:

1. Disables Preemption: Prevents the kernel scheduler from switching to other tasks
2. Saves and Disables IRQs: Stores current interrupt state and disables local interrupts
3. Provides Restoration: Automatically restores the previous state when the guard is dropped

Sources: src/lib.rs(L20 - L23) 

Usage Patterns

SpinNoIrq is designed for scenarios requiring complete protection and can be safely used in any kernel context.

Safe Contexts

flowchart TD
subgraph subGraph1["SpinNoIrq Usage"]
    SpinNoIrqLock["SpinNoIrq::lock()"]
    CriticalSection["Protected Critical Section"]
    AutoRestore["Automatic State Restoration"]
end
subgraph subGraph0["Kernel Contexts Where SpinNoIrq is Safe"]
    IRQEnabled["IRQ-EnabledKernel Code"]
    IRQDisabled["IRQ-DisabledKernel Code"]
    SyscallHandler["System CallHandlers"]
    TimerContext["Timer/SoftirqContext"]
    InitCode["InitializationCode"]
end

CriticalSection --> AutoRestore
IRQDisabled --> SpinNoIrqLock
IRQEnabled --> SpinNoIrqLock
InitCode --> SpinNoIrqLock
SpinNoIrqLock --> CriticalSection
SyscallHandler --> SpinNoIrqLock
TimerContext --> SpinNoIrqLock

Typical Usage Pattern

The standard usage follows the RAII pattern where the guard automatically manages protection state:

Sources: README.md(L29 - L33) 

Safety Guarantees

SpinNoIrq provides the strongest safety guarantees among all spinlock variants in the kspin crate.

Protection Matrix

Context Safety Analysis

flowchart TD
subgraph Reasoning["Reasoning"]
    IRQProtection["IRQ disabling providescomplete isolation"]
    PreemptProtection["Preemption disablingprevents task switches"]
    IRQHandlerIssue["Using in IRQ handleris redundant sinceIRQs already disabled"]
end
subgraph subGraph0["Context Safety for SpinNoIrq"]
    AnyContext["Any Kernel Context"]
    IRQHandler["Interrupt Handler"]
    TaskContext["Task Context"]
    SystemCall["System Call"]
    SafeResult["✅ Safe to Use"]
    UnsafeResult["❌ Not Recommended"]
end

AnyContext --> SafeResult
IRQHandler --> UnsafeResult
SafeResult --> IRQProtection
SafeResult --> PreemptProtection
SystemCall --> SafeResult
TaskContext --> SafeResult
UnsafeResult --> IRQHandlerIssue

Sources: src/lib.rs(L20 - L23) 

Performance Considerations

SpinNoIrq trades performance for safety, making it the most expensive but safest option.

Performance Impact Analysis

Performance Comparison

flowchart TD
subgraph subGraph1["Trade-off Characteristics"]
    Performance["Performance"]
    Safety["Safety"]
end
subgraph subGraph0["Relative Performance (Lower is Faster)"]
    SpinRaw["SpinRawOverhead: Minimal"]
    SpinNoPreempt["SpinNoPreemptOverhead: Low"]
    SpinNoIrq["SpinNoIrqOverhead: High"]
end

Performance --> SpinNoIrq
Safety --> SpinNoIrq
SpinNoPreempt --> SpinNoIrq
SpinRaw --> SpinNoPreempt

Sources: src/lib.rs(L20 - L27) 

Relationship to Other Spinlock Types

SpinNoIrq sits at the top of the protection hierarchy, providing comprehensive safety at the cost of performance.

Spinlock Hierarchy

flowchart TD
subgraph subGraph1["Usage Context Requirements"]
    ManualControl["Manual IRQ/preemption control required"]
    IRQDisabledContext["Must be in IRQ-disabled context"]
    AnyKernelContext["Can be used in any kernel context"]
end
subgraph subGraph0["kspin Protection Hierarchy"]
    SpinRaw["SpinRaw<T>BaseSpinLock<NoOp, T>No protection"]
    SpinNoPreempt["SpinNoPreempt<T>BaseSpinLock<NoPreempt, T>Preemption disabled"]
    SpinNoIrq["SpinNoIrq<T>BaseSpinLock<NoPreemptIrqSave, T>Preemption + IRQs disabled"]
end

SpinNoIrq --> AnyKernelContext
SpinNoPreempt --> IRQDisabledContext
SpinNoPreempt --> SpinNoIrq
SpinRaw --> ManualControl
SpinRaw --> SpinNoPreempt

Selection Criteria

Sources: src/lib.rs(L10 - L36)  README.md(L16 - L33) 

Usage Guidelines and Safety

Relevant source files

• README.md
• src/lib.rs

This document provides comprehensive guidelines for safely selecting and using the appropriate spinlock type from the kspin crate. It covers the safety requirements, context restrictions, and performance considerations for each spinlock variant.

For detailed information about the individual spinlock types and their APIs, see SpinRaw, SpinNoPreempt, and SpinNoIrq. For implementation details, see Core Implementation Architecture.

Safety Model Overview

The kspin crate implements a safety model based on execution context and protection levels. Each spinlock type provides different guarantees and has specific usage requirements that must be followed to ensure system correctness.

Protection Level Hierarchy

flowchart TD
A["SpinRaw"]
B["NoOp guard"]
C["SpinNoPreempt"]
D["NoPreempt guard"]
E["SpinNoIrq"]
F["NoPreemptIrqSave guard"]
G["No automatic protection"]
H["Disables preemption"]
I["Disables preemption + IRQs"]
J["Fastest performance"]
K["Balanced performance"]
L["Maximum safety"]
M["Manual context control required"]
N["IRQ-disabled context required"]
O["Any context safe"]

A --> B
B --> G
C --> D
D --> H
E --> F
F --> I
G --> J
G --> M
H --> K
H --> N
I --> L
I --> O

Sources: src/lib.rs(L6)  src/lib.rs(L10 - L36) 

Context Classification

The kernel execution environment is divided into distinct contexts, each with different safety requirements:

Sources: src/lib.rs(L10 - L36) 

Spinlock Selection Decision Tree

flowchart TD
Start["Need spinlock protection?"]
Context["What execution context?"]
IRQEnabled["IRQ-enabled context(general kernel code)"]
IRQDisabled["IRQ-disabled context(critical sections)"]
IntHandler["Interrupt handler"]
PreemptDisabled["Preemption-disabled context"]
UseNoIrq["Use SpinNoIrq"]
UseNoIrq2["Use SpinNoIrq(only safe option)"]
Performance["Performance critical?"]
UseRaw["Use SpinRaw(if preemption also disabled)"]
UseNoPreempt["Use SpinNoPreempt"]
UseNoIrq3["Use SpinNoIrq"]
PerfCritical["Need maximum performance?"]
UseRaw2["Use SpinRaw"]
UseNoIrq4["Use SpinNoIrq"]

Context --> IRQDisabled
Context --> IRQEnabled
Context --> IntHandler
Context --> PreemptDisabled
IRQDisabled --> Performance
IRQEnabled --> UseNoIrq
IntHandler --> UseNoIrq2
PerfCritical --> UseNoIrq4
PerfCritical --> UseRaw2
Performance --> UseNoIrq3
Performance --> UseNoPreempt
Performance --> UseRaw
PreemptDisabled --> PerfCritical
Start --> Context

Sources: src/lib.rs(L10 - L36)  README.md(L16 - L33) 

Context-Specific Usage Rules

IRQ-Enabled Context Usage

In IRQ-enabled contexts (typical kernel code), only SpinNoIrq<T> should be used:

// Safe: SpinNoIrq automatically handles IRQ and preemption state
let data = SpinNoIrq::new(shared_resource);
let guard = data.lock(); // IRQs and preemption disabled automatically
// ... critical section ...
drop(guard); // IRQs and preemption restored

Prohibited patterns:

• Using SpinNoPreempt<T> or SpinRaw<T> in IRQ-enabled contexts
• Assuming manual IRQ control is sufficient

Sources: src/lib.rs(L20 - L24)  README.md(L29 - L32) 

IRQ-Disabled Context Usage

When IRQs are already disabled, you have multiple options based on performance requirements:

// Option 1: Maximum safety (recommended)
let data = SpinNoIrq::new(resource);

// Option 2: Performance optimization when preemption control is needed
let data = SpinNoPreempt::new(resource);

// Option 3: Maximum performance when preemption is already disabled
let data = SpinRaw::new(resource);

Sources: src/lib.rs(L10 - L18)  src/lib.rs(L29 - L36) 

Interrupt Handler Restrictions

Interrupt handlers have strict requirements due to their execution context:

flowchart TD
IntHandler["Interrupt Handler"]
Requirement1["IRQs already disabled"]
Requirement2["Preemption already disabled"]
Requirement3["Cannot use SpinNoPreempt"]
Requirement4["Cannot use SpinRaw"]
Reason1["Would attempt to disablealready-disabled preemption"]
Reason2["No protection againstnested interrupts"]
Solution["Use SpinNoIrq only"]

IntHandler --> Requirement1
IntHandler --> Requirement2
IntHandler --> Requirement3
IntHandler --> Requirement4
IntHandler --> Solution
Requirement3 --> Reason1
Requirement4 --> Reason2

Sources: src/lib.rs(L13 - L15)  src/lib.rs(L31 - L33) 

Common Safety Violations and Pitfalls

Deadlock Scenarios

Understanding potential deadlock situations is critical for safe spinlock usage:

Context Mismatches

Common mistakes when choosing the wrong spinlock type:

// WRONG: SpinRaw in IRQ-enabled context
let data = SpinRaw::new(resource);
let guard = data.lock(); // No protection - race condition possible

// WRONG: SpinNoPreempt in interrupt handler  
let data = SpinNoPreempt::new(resource);
let guard = data.lock(); // May not provide sufficient protection

// CORRECT: SpinNoIrq for maximum compatibility
let data = SpinNoIrq::new(resource);
let guard = data.lock(); // Safe in any context

Sources: src/lib.rs(L10 - L36) 

Performance Considerations

Overhead Comparison

The protection mechanisms impose different performance costs:

flowchart TD
SpinRaw["SpinRaw"]
Cost1["Minimal overhead• Atomic operations only• No guard state changes"]
SpinNoPreempt["SpinNoPreempt"]
Cost2["Moderate overhead• Atomic operations• Preemption control"]
SpinNoIrq["SpinNoIrq"]
Cost3["Higher overhead• Atomic operations• Preemption + IRQ control• State save/restore"]
Perf1["Fastest"]
Perf2["Balanced"]
Perf3["Safest"]

Cost1 --> Perf1
Cost2 --> Perf2
Cost3 --> Perf3
SpinNoIrq --> Cost3
SpinNoPreempt --> Cost2
SpinRaw --> Cost1

SMP vs Single-Core Optimization

The smp feature flag dramatically affects performance characteristics:

Sources: README.md(L12) 

Best Practices Summary

Selection Guidelines

1. Default choice: Use SpinNoIrq<T> unless performance profiling indicates a bottleneck
2. Performance-critical paths: Consider SpinNoPreempt<T> in IRQ-disabled contexts
3. Maximum performance: Use SpinRaw<T> only in preemption-disabled, IRQ-disabled contexts
4. Interrupt handlers: Always use SpinNoIrq<T>

Implementation Patterns

// Pattern 1: Safe default for shared kernel data
static SHARED_DATA: SpinNoIrq<SharedResource> = SpinNoIrq::new(SharedResource::new());

// Pattern 2: Performance-optimized for known IRQ-disabled context
fn irq_disabled_function() {
    static LOCAL_DATA: SpinNoPreempt<LocalResource> = SpinNoPreempt::new(LocalResource::new());
    let guard = LOCAL_DATA.lock();
    // ... critical section ...
}

// Pattern 3: Maximum performance in controlled environment
fn preempt_and_irq_disabled_function() {
    static FAST_DATA: SpinRaw<FastResource> = SpinRaw::new(FastResource::new());
    let guard = FAST_DATA.lock();
    // ... minimal critical section ...
}

Verification Checklist

• Spinlock type matches execution context requirements
• No nested acquisition of the same lock
• Consistent lock ordering across all code paths
• Critical sections are minimal in duration
• Interrupt handlers only use SpinNoIrq<T>
• Performance requirements justify any use of SpinRaw<T> or SpinNoPreempt<T>

Sources: src/lib.rs(L10 - L36)  README.md(L16 - L33) 

Core Implementation Architecture

Relevant source files

• src/base.rs

This page provides a detailed analysis of the core implementation that underlies all spinlock types in the kspin crate. It covers the generic BaseSpinLock architecture, the RAII guard system, and the feature-conditional compilation strategy that enables optimization for different target environments.

For information about the specific spinlock types that users interact with, see Spinlock Types and Public API. For detailed implementation analysis of individual components, see BaseSpinLock and BaseSpinLockGuard, BaseGuard Trait System, SMP vs Single-Core Implementation, and Memory Ordering and Atomic Operations.

Architectural Overview

The kspin crate implements a layered architecture where all public spinlock types (SpinRaw, SpinNoPreempt, SpinNoIrq) are type aliases that wrap a single generic implementation: BaseSpinLock<G, T>. This design provides compile-time specialization through the type system while maintaining a unified codebase.

Core Components Diagram

flowchart TD
subgraph subGraph4["External Dependencies"]
    KernelGuard["kernel_guard crate"]
    CoreHint["core::hint::spin_loop()"]
    CoreSync["core::sync::atomic"]
end
subgraph subGraph3["Data Storage"]
    UnsafeCell["UnsafeCell<T>"]
    AtomicBool["AtomicBool (SMP only)"]
end
subgraph subGraph2["Type System Integration"]
    BaseGuard["BaseGuard trait"]
    PhantomData["PhantomData<G>"]
end
subgraph subGraph1["Generic Implementation Layer"]
    BaseSpinLock["BaseSpinLock<G, T>"]
    BaseSpinLockGuard["BaseSpinLockGuard<'a, G, T>"]
end
subgraph subGraph0["Public API Layer"]
    SpinRaw["SpinRaw<T>"]
    SpinNoPreempt["SpinNoPreempt<T>"]
    SpinNoIrq["SpinNoIrq<T>"]
end

AtomicBool --> CoreSync
BaseGuard --> KernelGuard
BaseSpinLock --> AtomicBool
BaseSpinLock --> BaseSpinLockGuard
BaseSpinLock --> CoreHint
BaseSpinLock --> PhantomData
BaseSpinLock --> UnsafeCell
PhantomData --> BaseGuard
SpinNoIrq --> BaseSpinLock
SpinNoPreempt --> BaseSpinLock
SpinRaw --> BaseSpinLock

Sources: src/base.rs(L27 - L32)  src/base.rs(L37 - L43) 

Generic Type Parameterization

The BaseSpinLock<G, T> struct uses two generic parameters that enable compile-time specialization:

The guard type G determines the protection behavior through the BaseGuard trait, which provides acquire() and release() methods that are called when entering and exiting the critical section.

Type Parameterization Flow

flowchart TD
subgraph subGraph2["Public Type Aliases"]
    SpinRawAlias["SpinRaw<T>"]
    SpinNoPreemptAlias["SpinNoPreempt<T>"]
    SpinNoIrqAlias["SpinNoIrq<T>"]
end
subgraph subGraph1["BaseSpinLock Instantiations"]
    RawLock["BaseSpinLock<NoOp, T>"]
    PreemptLock["BaseSpinLock<NoPreempt, T>"]
    IrqLock["BaseSpinLock<NoPreemptIrqSave, T>"]
end
subgraph subGraph0["Guard Types (kernel_guard)"]
    NoOp["NoOp"]
    NoPreempt["NoPreempt"]
    NoPreemptIrqSave["NoPreemptIrqSave"]
end

IrqLock --> SpinNoIrqAlias
NoOp --> RawLock
NoPreempt --> PreemptLock
NoPreemptIrqSave --> IrqLock
PreemptLock --> SpinNoPreemptAlias
RawLock --> SpinRawAlias

Sources: src/base.rs(L27 - L32)  src/lib.rs

Feature-Conditional Architecture

The implementation uses the smp feature flag to provide dramatically different code paths for single-core versus multi-core environments:

SMP Feature Compilation Strategy

Sources: src/base.rs(L13 - L14)  src/base.rs(L29 - L30)  src/base.rs(L41 - L42)  src/base.rs(L79 - L93)  src/base.rs(L111 - L118)  src/base.rs(L125 - L136) 

Lock Acquisition and Guard Lifecycle

The core operation flow demonstrates how the RAII pattern ensures correct lock management:

Lock Lifecycle Flow

sequenceDiagram
    participant Client as Client
    participant BaseSpinLock as BaseSpinLock
    participant BaseGuard as BaseGuard
    participant AtomicBool as AtomicBool
    participant BaseSpinLockGuard as BaseSpinLockGuard

    Client ->> BaseSpinLock: lock()
    BaseSpinLock ->> BaseGuard: G::acquire()
    Note over BaseGuard: Disable IRQs/preemption
    BaseGuard -->> BaseSpinLock: irq_state
    alt SMP enabled
        BaseSpinLock ->> AtomicBool: compare_exchange_weak(false, true)
    loop While locked
        AtomicBool -->> BaseSpinLock: Err (already locked)
        BaseSpinLock ->> AtomicBool: load(Ordering::Relaxed)
        BaseSpinLock ->> BaseSpinLock: core::hint::spin_loop()
    end
    AtomicBool -->> BaseSpinLock: Ok (acquired)
    else SMP disabled
        Note over BaseSpinLock: Lock always succeeds
    end
    BaseSpinLock -->> Client: BaseSpinLockGuard
    Note over Client: Use protected data via Deref/DerefMut
    Client ->> BaseSpinLockGuard: drop()
    alt SMP enabled
        BaseSpinLockGuard ->> AtomicBool: store(false, Ordering::Release)
    end
    BaseSpinLockGuard ->> BaseGuard: G::release(irq_state)
    Note over BaseGuard: Restore IRQs/preemption

Sources: src/base.rs(L77 - L101)  src/base.rs(L218 - L227) 

Memory Safety and Synchronization

The implementation provides memory safety through several mechanisms:

Data Access Safety Model

flowchart TD
subgraph subGraph2["Safety Guarantees"]
    ExclusiveAccess["Exclusive data access"]
    AutoRelease["Automatic lock release"]
    MemoryOrdering["Proper memory ordering"]
end
subgraph subGraph1["BaseSpinLockGuard Structure"]
    DataPtr["data: *mut T"]
    LockRef["lock: &'a AtomicBool"]
    IrqState["irq_state: G::State"]
    PhantomRef["_phantom: &'a PhantomData<G>"]
end
subgraph subGraph0["BaseSpinLock Structure"]
    UnsafeCellField["data: UnsafeCell<T>"]
    AtomicLock["lock: AtomicBool"]
    PhantomG["_phantom: PhantomData<G>"]
end

AtomicLock --> LockRef
AtomicLock --> MemoryOrdering
DataPtr --> ExclusiveAccess
LockRef --> AtomicLock
LockRef --> AutoRelease
PhantomG --> PhantomRef
PhantomRef --> UnsafeCellField
UnsafeCellField --> DataPtr

Sources: src/base.rs(L27 - L32)  src/base.rs(L37 - L43)  src/base.rs(L195 - L210)  src/base.rs(L218 - L227) 

BaseSpinLock and BaseSpinLockGuard

Relevant source files

• src/base.rs

Purpose and Scope

This document provides detailed technical analysis of the core spinlock implementation in the kspin crate. The BaseSpinLock<G, T> struct and its companion BaseSpinLockGuard<G, T> form the foundational implementation that underlies all public spinlock types in the crate. This generic implementation enables different protection behaviors through type parameterization while providing efficient RAII-based lock management.

For information about the public spinlock APIs that users interact with, see Spinlock Types and Public API. For details about the trait system that enables different protection behaviors, see BaseGuard Trait System.

Architecture Overview

The core implementation consists of two primary components that work together to provide safe, efficient spinlock functionality:

Core Implementation Structure

flowchart TD
subgraph subGraph3["BaseSpinLock Architecture"]
    BaseSpinLock["BaseSpinLock<G, T>Generic spinlock container"]
    BaseSpinLockGuard["BaseSpinLockGuard<G, T>RAII access guard"]
    subgraph subGraph2["Core Operations"]
        AcquireLock["G::acquire() + atomic CAS"]
        ReleaseLock["atomic store + G::release()"]
        DataAccess["Deref/DerefMut traits"]
    end
    subgraph subGraph1["BaseSpinLockGuard Fields"]
        PhantomRef["_phantom: &PhantomData<G>Lifetime-bound guard marker"]
        IrqState["irq_state: G::StateSaved protection state"]
        DataPtr["data: *mut TDirect data access pointer"]
        LockRef["lock: &AtomicBool(SMP only)"]
    end
    subgraph subGraph0["BaseSpinLock Fields"]
        PhantomG["_phantom: PhantomData<G>Zero-cost guard type marker"]
        LockState["lock: AtomicBool(SMP only)"]
        Data["data: UnsafeCell<T>Protected data storage"]
    end
end

AcquireLock --> BaseSpinLockGuard
BaseSpinLock --> AcquireLock
BaseSpinLock --> Data
BaseSpinLock --> LockState
BaseSpinLock --> PhantomG
BaseSpinLockGuard --> DataAccess
BaseSpinLockGuard --> DataPtr
BaseSpinLockGuard --> IrqState
BaseSpinLockGuard --> LockRef
BaseSpinLockGuard --> PhantomRef
BaseSpinLockGuard --> ReleaseLock

Sources: src/base.rs(L27 - L43)  src/base.rs(L49 - L101)  src/base.rs(L218 - L227) 

Method Implementation Map

flowchart TD
subgraph subGraph2["SMP-Conditional Logic"]
    CompareExchange["compare_exchange_weakline 85"]
    SpinLoop["spin_loop()line 90"]
    AtomicStore["store(false)line 224"]
end
subgraph subGraph1["BaseSpinLockGuard Traits"]
    Deref["Deref::deref()line 198"]
    DerefMut["DerefMut::deref_mut()line 206"]
    Drop["Drop::drop()line 222"]
    Debug["Debug::fmt()line 213"]
end
subgraph subGraph0["BaseSpinLock Methods"]
    New["new(data: T)line 52"]
    Lock["lock()line 77"]
    TryLock["try_lock()line 122"]
    IsLocked["is_locked()line 110"]
    ForceUnlock["force_unlock()line 159"]
    GetMut["get_mut()line 170"]
    IntoInner["into_inner()line 63"]
end
BaseSpinLockGuard["BaseSpinLockGuard"]

BaseSpinLockGuard --> Deref
BaseSpinLockGuard --> DerefMut
BaseSpinLockGuard --> Drop
Drop --> AtomicStore
Lock --> CompareExchange
Lock --> SpinLoop
TryLock --> CompareExchange

Sources: src/base.rs(L49 - L175)  src/base.rs(L195 - L227) 

BaseSpinLock Structure Analysis

Field Organization and Purpose

The BaseSpinLock<G, T> struct is carefully designed to minimize memory overhead while supporting both SMP and single-core environments:

The conditional compilation using #[cfg(feature = "smp")] allows the lock state to be completely eliminated in single-core builds, reducing memory overhead and eliminating unnecessary atomic operations.

Sources: src/base.rs(L27 - L32) 

Constructor and Data Access Methods

The new() constructor provides compile-time initialization with zero runtime cost:

// Simplified view of the new() method
pub const fn new(data: T) -> Self {
    Self {
        _phantom: PhantomData,
        data: UnsafeCell::new(data),
        #[cfg(feature = "smp")]
        lock: AtomicBool::new(false),
    }
}

The into_inner() and get_mut() methods provide safe data extraction when exclusive access is statically guaranteed, eliminating the need for runtime locking.

Sources: src/base.rs(L52 - L59)  src/base.rs(L63 - L68)  src/base.rs(L170 - L175) 

BaseSpinLockGuard RAII Implementation

Guard Structure and Lifetime Management

The BaseSpinLockGuard<'a, G, T> implements the RAII pattern to ensure automatic lock release:

flowchart TD
subgraph subGraph2["Guard Lifecycle"]
    Create["Guard Creationlock() or try_lock()"]
    Access["Data AccessDeref/DerefMut"]
    Drop["Automatic CleanupDrop trait"]
    subgraph subGraph1["Drop Steps"]
        AtomicRelease["lock.store(false)(SMP only)"]
        GuardRelease["G::release(irq_state)Restore protection"]
    end
    subgraph subGraph0["Creation Steps"]
        Acquire["G::acquire()Get protection state"]
        CAS["compare_exchange(SMP only)"]
        ConstructGuard["Construct guard withdata pointer & state"]
    end
end

Access --> Drop
Acquire --> CAS
AtomicRelease --> GuardRelease
CAS --> ConstructGuard
ConstructGuard --> Access
Create --> Acquire
Drop --> AtomicRelease

Sources: src/base.rs(L77 - L101)  src/base.rs(L218 - L227) 

Memory Safety Through Type System

The guard uses several mechanisms to ensure memory safety:

1. Lifetime binding: The 'a lifetime ensures the guard cannot outlive the lock
2. Raw pointer storage: Direct *mut T access eliminates borrowing conflicts
3. Phantom reference: &'a PhantomData<G> ties the guard lifetime to the lock
4. Exclusive data access: The guard provides exclusive access through Deref/DerefMut

Sources: src/base.rs(L37 - L43)  src/base.rs(L195 - L210) 

Core Locking Operations

Lock Acquisition Algorithm

The lock() method implements a two-phase spinning algorithm optimized for different contention scenarios:

The algorithm uses compare_exchange_weak for potential efficiency gains on some architectures, falling back to spinning until the lock appears available before retrying.

Sources: src/base.rs(L77 - L101) 

Try-Lock Implementation

The try_lock() method provides non-blocking acquisition using a strong compare-exchange operation:

flowchart TD
subgraph subGraph1["Single-Core Path"]
    AlwaysSuccess["Always succeedsis_unlocked = true"]
    CreateGuard["Create guard"]
end
subgraph subGraph0["SMP Path"]
    StrongCAS["compare_exchange(strong)"]
    Success["Create guard"]
    Failure["Return None"]
end
TryLock["try_lock()"]
Acquire["G::acquire()"]

Acquire --> AlwaysSuccess
Acquire --> StrongCAS
AlwaysSuccess --> CreateGuard
StrongCAS --> Failure
StrongCAS --> Success
TryLock --> Acquire

The use of strong compare-exchange is specifically chosen over weak to avoid unnecessary retry loops in the try-lock scenario.

Sources: src/base.rs(L122 - L149) 

SMP vs Single-Core Optimization

Conditional Compilation Strategy

The crate uses cfg_if! macros to provide dramatically different implementations based on the smp feature:

This approach allows single-core builds to have zero overhead for lock operations while maintaining identical APIs.

Sources: src/base.rs(L13 - L14)  src/base.rs(L29 - L30)  src/base.rs(L111 - L118)  src/base.rs(L125 - L136) 

Memory Ordering Semantics

The SMP implementation uses carefully chosen memory orderings:

• Acquire ordering on successful CAS: Ensures all subsequent reads see writes from the previous critical section
• Relaxed ordering on failed CAS: No synchronization needed for failed attempts
• Release ordering on unlock: Ensures all writes in critical section are visible before lock release
• Relaxed ordering for is_locked(): Only a hint, no synchronization guarantees

Sources: src/base.rs(L85)  src/base.rs(L131)  src/base.rs(L224)  src/base.rs(L113) 

Thread Safety and Sync Implementation

Safety Trait Implementations

The crate provides the same safety guarantees as std::sync::Mutex:

unsafe impl<G: BaseGuard, T: ?Sized + Send> Sync for BaseSpinLock<G, T> {}
unsafe impl<G: BaseGuard, T: ?Sized + Send> Send for BaseSpinLock<G, T> {}

These implementations are safe because:

• The lock ensures exclusive access to the data
• The guard system prevents concurrent access
• The BaseGuard trait handles interrupt/preemption safety

Sources: src/base.rs(L46 - L47) 

Debug and Display Support

Both BaseSpinLock and BaseSpinLockGuard implement Debug to aid in development:

• The lock's debug implementation attempts try_lock() to safely display data
• The guard's debug implementation directly displays the protected data
• Locked spinlocks display "SpinLock { <locked> }" to avoid blocking

Sources: src/base.rs(L184 - L193)  src/base.rs(L212 - L216) 

BaseGuard Trait System

Relevant source files

• src/base.rs
• src/lib.rs

The BaseGuard trait system is the core abstraction that enables different protection behaviors in kspin spinlocks through type parameterization. This system allows BaseSpinLock<G, T> to provide varying levels of interrupt and preemption protection by substituting different guard implementations at compile time.

For information about the specific spinlock types that use these guards, see Spinlock Types and Public API. For details about the underlying BaseSpinLock implementation, see BaseSpinLock and BaseSpinLockGuard.

BaseGuard Trait Interface

The BaseGuard trait is defined in the external kernel_guard crate and provides a standardized interface for managing system-level protection states during critical sections.

classDiagram
class BaseGuard {
    <<trait>>
    +type State
    +acquire() State
    +release(state: State)
}

class NoOp {
    
    +type State =()
    +acquire()()
    +release(state:())
}

class NoPreempt {
    +type State = PreemptState
    +acquire() PreemptState
    +release(state: PreemptState)
}

class NoPreemptIrqSave {
    +type State = IrqState
    +acquire() IrqState
    +release(state: IrqState)
}

BaseGuard  --|>  NoOp
BaseGuard  --|>  NoPreempt
NoPreemptIrqSave  --|>  NoPreempt

BaseGuard Trait Interface

Sources: src/base.rs(L16)  src/lib.rs(L6) 

Integration with BaseSpinLock

The BaseSpinLock<G, T> struct uses the BaseGuard trait as a type parameter to customize protection behavior without runtime overhead. The guard type G determines what system-level protections are applied during lock acquisition and release.

flowchart TD
subgraph subGraph1["Lock Operations"]
    Lock["lock()"]
    TryLock["try_lock()"]
    Drop["Drop::drop()"]
end
subgraph subGraph0["Guard Integration Points"]
    Acquire["G::acquire()"]
    Release["G::release(state)"]
    StateStorage["irq_state: G::State"]
end
BaseSpinLock["BaseSpinLock<G: BaseGuard, T>"]
BaseSpinLockGuard["BaseSpinLockGuard<G, T>"]

Acquire --> StateStorage
BaseSpinLock --> Lock
BaseSpinLock --> TryLock
BaseSpinLockGuard --> Drop
Drop --> Release
Lock --> Acquire
StateStorage --> BaseSpinLockGuard
TryLock --> Acquire

BaseGuard Integration Flow

The integration occurs at three key points in src/base.rs:

1. State acquisition during lock operations src/base.rs(L78)  src/base.rs(L123) 
2. State storage in the guard struct src/base.rs(L39) 
3. State release during guard destruction src/base.rs(L225) 

Sources: src/base.rs(L27)  src/base.rs(L37 - L43)  src/base.rs(L77 - L101)  src/base.rs(L218 - L227) 

Concrete Guard Implementations

The kspin crate uses three specific implementations of BaseGuard from the kernel_guard crate, each providing different levels of system protection.

flowchart TD
subgraph subGraph1["Spinlock Types"]
    SpinRaw["SpinRaw<T>"]
    SpinNoPreempt["SpinNoPreempt<T>"]
    SpinNoIrq["SpinNoIrq<T>"]
end
subgraph subGraph0["Protection Levels"]
    NoOp["NoOpRaw Protection"]
    NoPreempt["NoPreemptPreemption Protection"]
    NoPreemptIrqSave["NoPreemptIrqSaveFull Protection"]
end

NoOp --> SpinRaw
NoPreempt --> SpinNoPreempt
NoPreemptIrqSave --> SpinNoIrq

Guard Type to Spinlock Type Mapping

Sources: src/lib.rs(L6)  src/lib.rs(L15)  src/lib.rs(L24)  src/lib.rs(L33) 

Type-Driven Protection Behavior

The BaseGuard trait system enables compile-time selection of protection behavior through Rust's type system. Each guard implementation provides different acquire() and release() semantics without requiring runtime branching.

sequenceDiagram
    participant Client as Client
    participant BaseSpinLock as BaseSpinLock
    participant GBaseGuard as "G: BaseGuard"
    participant KernelSubsystems as "Kernel Subsystems"

    Client ->> BaseSpinLock: lock()
    BaseSpinLock ->> GBaseGuard: G::acquire()
    GBaseGuard ->> KernelSubsystems: Disable preemption/IRQs
    KernelSubsystems -->> GBaseGuard: Return saved state
    GBaseGuard -->> BaseSpinLock: G::State
    BaseSpinLock ->> BaseSpinLock: Acquire atomic lock
    BaseSpinLock -->> Client: BaseSpinLockGuard
    Note over Client: Use protected data
    Client ->> BaseSpinLock: Drop guard
    BaseSpinLock ->> BaseSpinLock: Release atomic lock
    BaseSpinLock ->> GBaseGuard: G::release(state)
    GBaseGuard ->> KernelSubsystems: Restore preemption/IRQs
    KernelSubsystems -->> GBaseGuard: Complete

Protection State Management Sequence

The type-driven approach ensures that:

• NoOp: acquire() and release() are no-ops, providing zero overhead
• NoPreempt: Manages preemption state to prevent task switching
• NoPreemptIrqSave: Manages both preemption and interrupt state for maximum protection

Sources: src/base.rs(L77 - L79)  src/base.rs(L122 - L124)  src/base.rs(L222 - L225) 

State Management in Guard Lifecycle

The BaseSpinLockGuard stores the protection state returned by G::acquire() and ensures proper cleanup through Rust's RAII pattern. This guarantees that system protection state is always restored, even in the presence of panics.

Guard State Lifecycle

The state management implementation in BaseSpinLockGuard:

• State storage: irq_state: G::State field holds the protection state src/base.rs(L39) 
• State acquisition: Captured during guard creation src/base.rs(L96)  src/base.rs(L141) 
• State restoration: Automatically handled in Drop::drop() src/base.rs(L225) 

This design ensures that protection state is never leaked and that the system always returns to its original state when the critical section ends.

Sources: src/base.rs(L37 - L43)  src/base.rs(L94 - L100)  src/base.rs(L138 - L145)  src/base.rs(L218 - L227) 

SMP vs Single-Core Implementation

Relevant source files

• Cargo.toml
• src/base.rs

Purpose and Scope

This document explains how the kspin crate uses feature flags to provide dramatically different implementations for multi-core (SMP) and single-core environments. The smp feature flag enables compile-time optimization that completely eliminates atomic operations and lock state when they are unnecessary in single-core systems.

For details about the underlying BaseSpinLock structure, see BaseSpinLock and BaseSpinLockGuard. For information about how different guard types interact with both implementations, see BaseGuard Trait System. For technical details about atomic operations used in SMP mode, see Memory Ordering and Atomic Operations.

Feature Flag Architecture

The kspin crate uses conditional compilation through the smp feature flag to generate entirely different code paths for multi-core and single-core environments. This approach enables zero-cost abstractions where single-core systems pay no performance penalty for multi-core synchronization primitives.

Conditional Compilation Flow

flowchart TD
subgraph subGraph1["Single-Core Implementation"]
    SingleStruct["BaseSpinLock {_phantom: PhantomData"]
    SingleGuard["BaseSpinLockGuard {_phantom: &PhantomData"]
    SingleOps["No Atomic Operations:• lock() always succeeds• try_lock() always succeeds• is_locked() always false"]
end
subgraph subGraph0["SMP Implementation"]
    SMPStruct["BaseSpinLock {_phantom: PhantomData"]
    SMPGuard["BaseSpinLockGuard {_phantom: &PhantomData"]
    SMPOps["Atomic Operations:• compare_exchange_weak• load/store with ordering• spin_loop hints"]
end
FeatureFlag["smp feature flag"]
SMPBuild["SMP Build Target"]
SingleBuild["Single-Core Build Target"]

FeatureFlag --> SMPBuild
FeatureFlag --> SingleBuild
SMPBuild --> SMPGuard
SMPBuild --> SMPOps
SMPBuild --> SMPStruct
SingleBuild --> SingleGuard
SingleBuild --> SingleOps
SingleBuild --> SingleStruct

Sources: Cargo.toml(L14 - L16)  src/base.rs(L13 - L14)  src/base.rs(L29 - L31)  src/base.rs(L41 - L43) 

SMP Implementation Details

In SMP environments, the BaseSpinLock maintains actual lock state using atomic operations to coordinate between multiple CPU cores. The implementation provides true mutual exclusion through hardware-level atomic instructions.

SMP Lock Structure and Operations

flowchart TD
subgraph subGraph2["Memory Ordering"]
    AcquireOrder["Ordering::Acquire on success"]
    RelaxedOrder["Ordering::Relaxed on failure"]
    ReleaseOrder["Ordering::Release on unlock"]
end
subgraph subGraph1["Lock Acquisition Process"]
    AcquireGuard["G::acquire()"]
    CompareExchange["compare_exchange_weak(false, true)"]
    SpinLoop["spin_loop() while locked"]
    CreateGuard["BaseSpinLockGuard creation"]
end
subgraph subGraph0["BaseSpinLock SMP Structure"]
    SMPLock["BaseSpinLock"]
    Phantom["_phantom: PhantomData"]
    AtomicLock["lock: AtomicBool"]
    Data["data: UnsafeCell"]
end

AcquireGuard --> CompareExchange
AtomicLock --> CompareExchange
CompareExchange --> AcquireOrder
CompareExchange --> CreateGuard
CompareExchange --> RelaxedOrder
CompareExchange --> SpinLoop
CreateGuard --> ReleaseOrder
SMPLock --> AtomicLock
SMPLock --> Data
SMPLock --> Phantom
SpinLoop --> CompareExchange

The SMP implementation uses a two-phase locking strategy:

1. Guard Acquisition: First acquires the protection guard (disabling preemption/IRQs)
2. Atomic Lock: Then attempts to acquire the atomic lock using compare-and-swap operations

Key SMP Code Paths:

• Lock acquisition with spinning: src/base.rs(L79 - L93) 
• Try-lock with strong compare-exchange: src/base.rs(L126 - L132) 
• Lock status checking: src/base.rs(L112 - L113) 
• Force unlock operation: src/base.rs(L160 - L161) 

Sources: src/base.rs(L27 - L32)  src/base.rs(L77 - L101)  src/base.rs(L122 - L149)  src/base.rs(L159 - L162) 

Single-Core Implementation Details

In single-core environments, the BaseSpinLock completely eliminates the atomic lock state. Since only one CPU core exists, proper guard acquisition (disabling preemption/IRQs) provides sufficient mutual exclusion without any atomic operations.

Single-Core Optimization Strategy

flowchart TD
subgraph subGraph2["Eliminated Operations"]
    NoAtomic["❌ No AtomicBool field"]
    NoCompareExchange["❌ No compare_exchange"]
    NoSpinning["❌ No spinning loops"]
    NoMemoryOrdering["❌ No memory ordering"]
    AcquireGuard2["G::acquire()"]
    SingleLock["BaseSpinLock"]
end
subgraph subGraph0["BaseSpinLock Single-Core Structure"]
    NoCompareExchange["❌ No compare_exchange"]
    SingleLock["BaseSpinLock"]
    Data2["data: UnsafeCell"]
    subgraph subGraph1["Simplified Lock Process"]
        NoAtomic["❌ No AtomicBool field"]
        AcquireGuard2["G::acquire()"]
        DirectAccess["Direct data access"]
        Phantom2["_phantom: PhantomData"]
    end
end

AcquireGuard2 --> DirectAccess
SingleLock --> Data2
SingleLock --> Phantom2

Single-Core Behavior:

• lock() always succeeds immediately after guard acquisition
• try_lock() always returns Some(guard)
• is_locked() always returns false
• force_unlock() performs no atomic operations

Key Single-Core Code Paths:

• Simplified lock acquisition: src/base.rs(L94 - L101) 
• Always-successful try-lock: src/base.rs(L134 - L135) 
• Always-false lock status: src/base.rs(L114 - L115) 
• No-op force unlock: src/base.rs(L159 - L162) 

Sources: src/base.rs(L25 - L26)  src/base.rs(L133 - L135)  src/base.rs(L114 - L116) 

Compile-Time Optimization Benefits

The feature flag approach provides significant performance and size benefits for single-core targets by eliminating unnecessary code at compile time.

Performance Comparison

Optimization Mechanisms

Sources: src/base.rs(L111 - L117)  src/base.rs(L125 - L136)  Cargo.toml(L14 - L16) 

Code Generation Differences

The conditional compilation results in fundamentally different assembly code generation for the two target environments.

Structure Layout Differences

flowchart TD
subgraph subGraph0["SMP Memory Layout"]
    SMPData["data: UnsafeCell(sizeof T bytes)"]
    subgraph subGraph2["Guard Layout Differences"]
        SMPGuardLayout["SMP Guard:• phantom reference• irq_state• data pointer• lock reference"]
        SingleGuardLayout["Single-Core Guard:• phantom reference• irq_state• data pointer"]
        SingleStruct2["BaseSpinLock"]
        SinglePhantom["_phantom: PhantomData"]
        SingleData["data: UnsafeCell(sizeof T bytes)"]
        SMPStruct2["BaseSpinLock"]
        SMPPhantom["_phantom: PhantomData"]
        SMPAtomic["lock: AtomicBool(1 byte + padding)"]
    end
    subgraph subGraph1["Single-Core Memory Layout"]
        SMPGuardLayout["SMP Guard:• phantom reference• irq_state• data pointer• lock reference"]
        SingleGuardLayout["Single-Core Guard:• phantom reference• irq_state• data pointer"]
        SingleStruct2["BaseSpinLock"]
        SinglePhantom["_phantom: PhantomData"]
        SingleData["data: UnsafeCell(sizeof T bytes)"]
        SMPStruct2["BaseSpinLock"]
        SMPPhantom["_phantom: PhantomData"]
        SMPAtomic["lock: AtomicBool(1 byte + padding)"]
    end
end

SMPStruct2 --> SMPAtomic
SMPStruct2 --> SMPData
SMPStruct2 --> SMPPhantom
SingleStruct2 --> SingleData
SingleStruct2 --> SinglePhantom

Function Implementation Differences

The same function signatures produce completely different implementations:

• lock() method: SMP version includes spinning loop src/base.rs(L83 - L92)  single-core version skips directly to guard creation src/base.rs(L94 - L101) 
• try_lock() method: SMP version uses atomic compare-exchange src/base.rs(L129 - L132)  single-core version sets is_unlocked = true src/base.rs(L134) 
• is_locked() method: SMP version loads atomic state src/base.rs(L113)  single-core version returns constant false src/base.rs(L115) 

This design ensures that single-core embedded systems receive highly optimized code while SMP systems get full multi-core safety guarantees.

Sources: src/base.rs(L27 - L32)  src/base.rs(L37 - L43)  src/base.rs(L52 - L59)  src/base.rs(L77 - L149)  src/base.rs(L218 - L226) 

Memory Ordering and Atomic Operations

Relevant source files

• src/base.rs

This document covers the atomic operations and memory ordering semantics used in the kspin crate's spinlock implementation. It details how the BaseSpinLock uses platform-specific atomic primitives to ensure thread safety in multi-core environments, and how these operations are optimized away for single-core systems.

For information about the overall spinlock architecture and guard types, see Core Implementation Architecture. For details about the SMP feature flag system, see SMP vs Single-Core Implementation.

Conditional Atomic Operations

The kspin crate uses conditional compilation to include atomic operations only when targeting multi-core systems. The smp feature flag controls whether atomic synchronization primitives are compiled into the final binary.

flowchart TD
subgraph subGraph2["Lock Operations"]
    AtomicOps["compare_exchange_weakcompare_exchangeload/store operations"]
    NoOps["Always succeedsNo atomic operationsOptimized away"]
end
subgraph subGraph1["Data Structures"]
    AtomicLock["lock: AtomicBool"]
    NoLockField["No lock field"]
end
subgraph subGraph0["Compilation Paths"]
    SMPEnabled["SMP Feature Enabled"]
    SMPDisabled["SMP Feature Disabled"]
end

AtomicLock --> AtomicOps
NoLockField --> NoOps
SMPDisabled --> NoLockField
SMPEnabled --> AtomicLock

The BaseSpinLock struct conditionally includes an AtomicBool field based on the smp feature:

Sources: src/base.rs(L13 - L14)  src/base.rs(L29 - L30)  src/base.rs(L111 - L117) 

Memory Ordering Semantics

The spinlock implementation uses three specific memory orderings to ensure correct synchronization semantics while minimizing performance overhead:

flowchart TD
subgraph Operations["Operations"]
    CompareExchange["compare_exchange(_weak)Acquire + Relaxed"]
    Store["store(false)Release"]
    Load["load()Relaxed"]
end
subgraph subGraph0["Memory Ordering Types"]
    Acquire["Ordering::AcquireLock acquisition"]
    Release["Ordering::ReleaseLock release"]
    Relaxed["Ordering::RelaxedStatus checks"]
end

Acquire --> CompareExchange
Relaxed --> CompareExchange
Relaxed --> Load
Release --> Store

Memory Ordering Usage Patterns

The Acquire ordering on successful lock acquisition ensures that all subsequent reads and writes cannot be reordered before the lock acquisition. The Release ordering on lock release ensures that all previous reads and writes complete before the lock is released.

Sources: src/base.rs(L85)  src/base.rs(L131)  src/base.rs(L161)  src/base.rs(L224)  src/base.rs(L113) 

Atomic Operation Flow

The spinlock uses a two-phase approach for lock acquisition: an optimistic compare-and-swap followed by a passive wait loop.

flowchart TD
Start["lock() called"]
AcquireGuard["G::acquire()"]
TryLock["compare_exchange_weak(false, true)"]
CheckResult["Success?"]
CreateGuard["Create BaseSpinLockGuard"]
CheckLocked["is_locked()"]
SpinLoop["core::hint::spin_loop()"]
StillLocked["Still locked?"]

AcquireGuard --> TryLock
CheckLocked --> StillLocked
CheckResult --> CheckLocked
CheckResult --> CreateGuard
SpinLoop --> CheckLocked
Start --> AcquireGuard
StillLocked --> SpinLoop
StillLocked --> TryLock
TryLock --> CheckResult

Lock Acquisition Pattern

The lock() method implements an efficient two-stage spinning strategy:

1. Active spinning: Attempts to acquire the lock using compare_exchange_weak
2. Passive waiting: When acquisition fails, enters a read-only spin loop checking is_locked()
3. CPU optimization: Uses core::hint::spin_loop() to signal the processor during busy waiting

Sources: src/base.rs(L77 - L101)  src/base.rs(L83 - L92)  src/base.rs(L89 - L91) 

Try-Lock Pattern

The try_lock() method uses a single-shot approach with compare_exchange (strong semantics) rather than the weak variant used in the spinning loop:

flowchart TD
TryLock["try_lock()"]
AcquireGuard["G::acquire()"]
CompareExchange["compare_exchange(false, true)"]
CheckResult["Success?"]
ReturnSome["Some(guard)"]
ReturnNone["None"]

AcquireGuard --> CompareExchange
CheckResult --> ReturnNone
CheckResult --> ReturnSome
CompareExchange --> CheckResult
TryLock --> AcquireGuard

The strong compare-exchange is used because there's no retry loop, making the single operation more likely to succeed on architectures where weak operations can fail spuriously.

Sources: src/base.rs(L122 - L149)  src/base.rs(L129 - L132) 

Lock Release Mechanism

Lock release occurs automatically through the RAII Drop implementation of BaseSpinLockGuard. The release process ensures proper memory ordering and guard state cleanup:

sequenceDiagram
    participant BaseSpinLockGuard as "BaseSpinLockGuard"
    participant AtomicBoollock as "AtomicBool lock"
    participant GBaseGuard as "G: BaseGuard"

    Note over BaseSpinLockGuard: Guard goes out of scope
    BaseSpinLockGuard ->> AtomicBoollock: store(false, Ordering::Release)
    BaseSpinLockGuard ->> GBaseGuard: G::release(irq_state)
    Note over BaseSpinLockGuard: Guard destroyed

The release ordering ensures that all memory operations performed while holding the lock are visible to other threads before the lock becomes available.

Sources: src/base.rs(L218 - L227)  src/base.rs(L224)  src/base.rs(L225) 

Performance Optimizations

CPU Spin Loop Hints

The implementation uses core::hint::spin_loop() to provide architecture-specific optimizations during busy waiting:

• x86/x86_64: Translates to the PAUSE instruction, reducing power consumption
• ARM: May use YIELD or similar instructions
• RISC-V: Architecture-specific power management hints

Weak vs Strong Compare-Exchange

The spinlock strategically chooses between weak and strong compare-exchange operations:

Sources: src/base.rs(L85)  src/base.rs(L131)  src/base.rs(L127 - L128) 

Single-Core Optimization

When compiled without the smp feature, all atomic operations are eliminated:

flowchart TD
subgraph Benefits["Benefits"]
    ZeroCost["Zero-cost abstraction"]
    NoMemoryBarriers["No memory barriers"]
    OptimizedBinary["Smaller binary size"]
end
subgraph subGraph0["SMP Disabled Path"]
    LockCall["lock()"]
    GuardAcquire["G::acquire()"]
    CreateGuard["Create guard immediately"]
    NoAtomics["No atomic operations"]
end

CreateGuard --> NoAtomics
GuardAcquire --> CreateGuard
LockCall --> GuardAcquire
NoAtomics --> NoMemoryBarriers
NoAtomics --> OptimizedBinary
NoAtomics --> ZeroCost

This optimization is particularly important for embedded systems where multi-core synchronization overhead would be unnecessary.

Sources: src/base.rs(L79 - L93)  src/base.rs(L126 - L136)  src/base.rs(L160 - L161)  src/base.rs(L223 - L224) 

Development and Building

Relevant source files

• .github/workflows/ci.yml
• Cargo.toml

This document provides comprehensive information for developers who want to build, test, or contribute to the kspin crate. It covers the build system configuration, feature flag usage, continuous integration pipeline, and development environment setup. For information about the actual spinlock APIs and usage patterns, see Spinlock Types and Public API. For details about the internal implementation architecture, see Core Implementation Architecture.

Build System Overview

The kspin crate uses Cargo as its primary build system with support for multiple target platforms and optional feature flags. The build configuration is centralized in the project's Cargo.toml file, which defines dependencies, metadata, and feature gates that control compilation behavior.

Package Configuration

The crate is configured as a library package targeting kernel-space environments with no-std compatibility. The package metadata includes licensing under multiple schemes (GPL-3.0-or-later, Apache-2.0, MulanPSL-2.0) and categorization for operating system and no-std use cases Cargo.toml(L1 - L13) 

Target Platform Support

The build system supports multiple target architectures commonly used in kernel and embedded development:

Build System Architecture

flowchart TD
subgraph subGraph0["Build Targets"]
    x86Linux["x86_64-unknown-linux-gnu"]
    x86None["x86_64-unknown-none"]
    RiscV["riscv64gc-unknown-none-elf"]
    ARM["aarch64-unknown-none-softfloat"]
end
CargoToml["Cargo.toml"]
Dependencies["Dependencies"]
Features["Feature Flags"]
Metadata["Package Metadata"]
KernelGuard["kernel_guard: 0.1"]
CfgIf["cfg-if: 1.0"]
SMP["smp feature"]
Default["default = []"]
Name["name: kspin"]
Version["version: 0.1.0"]
License["Triple license"]
MultiCore["Multi-core compilation"]
SingleCore["Single-core compilation"]

CargoToml --> ARM
CargoToml --> Dependencies
CargoToml --> Features
CargoToml --> Metadata
CargoToml --> RiscV
CargoToml --> x86Linux
CargoToml --> x86None
Default --> SingleCore
Dependencies --> CfgIf
Dependencies --> KernelGuard
Features --> Default
Features --> SMP
Metadata --> License
Metadata --> Name
Metadata --> Version
SMP --> MultiCore

Sources: Cargo.toml(L1 - L22)  .github/workflows/ci.yml(L12) 

Feature Flag System

The kspin crate uses Cargo feature flags to enable compile-time optimization and conditional compilation based on the target environment. The primary feature flag is smp, which controls whether the spinlock implementation includes multi-core synchronization primitives.

Feature Configuration

The feature system is defined in the [features] section of Cargo.toml:

• smp: Enables multi-core environment support with atomic operations
• default: Empty default feature set for maximum compatibility

When the smp feature is disabled, the implementation optimizes away atomic operations and lock state for single-core environments Cargo.toml(L14 - L17) 

Feature Flag Compilation Flow

flowchart TD
subgraph subGraph2["cfg-if Usage"]
    SMPCheck["smp feature enabled?"]
    CfgIf["cfg-if crate"]
end
subgraph subGraph1["Single-core Build Path"]
    SingleBuild["Single-core Build"]
    NoAtomic["No atomic operations"]
    NoLockState["No lock state field"]
    OptimizedAway["Lock always succeeds"]
end
subgraph subGraph0["SMP Build Path"]
    SMPBuild["SMP Build"]
    AtomicOps["Include AtomicBool"]
    CompareExchange["compare_exchange operations"]
    MemoryOrdering["Memory ordering constraints"]
end
FeatureInput["Feature Selection"]
FinalBinary["Final Binary"]

AtomicOps --> CompareExchange
CfgIf --> SMPCheck
CompareExchange --> MemoryOrdering
FeatureInput --> SMPCheck
MemoryOrdering --> FinalBinary
NoAtomic --> NoLockState
NoLockState --> OptimizedAway
OptimizedAway --> FinalBinary
SMPBuild --> AtomicOps
SMPCheck --> SMPBuild
SMPCheck --> SingleBuild
SingleBuild --> NoAtomic

Sources: Cargo.toml(L14 - L17)  Cargo.toml(L20 - L21) 

Continuous Integration Pipeline

The project uses GitHub Actions for automated testing, building, and documentation deployment. The CI pipeline is defined in .github/workflows/ci.yml and consists of two main jobs: ci for code validation and doc for documentation generation.

CI Job Matrix

The ci job uses a matrix strategy to test across multiple dimensions:

CI Pipeline Stages

CI/CD Pipeline Architecture

flowchart TD
subgraph subGraph2["Documentation Job"]
    DocJob["doc job"]
    DocCheckout["actions/checkout@v4"]
    DocRust["dtolnay/rust-toolchain@nightly"]
    CargoDoc["cargo doc --no-deps --all-features"]
    IndexHTML["Generate index.html redirect"]
    GitHubPages["Deploy to gh-pages"]
end
subgraph subGraph1["CI Steps"]
    Checkout["actions/checkout@v4"]
    InstallHack["install cargo-hack"]
    InstallRust["dtolnay/rust-toolchain@nightly"]
    Components["rust-src, clippy, rustfmt"]
    RustVersion["Check rust version"]
    Format["cargo fmt --check"]
    Clippy["cargo hack clippy --each-feature"]
    Build["cargo hack build --each-feature"]
    Test["cargo hack test --each-feature"]
end
subgraph subGraph0["CI Job Matrix"]
    CIJob["ci job"]
    Matrix["Matrix Strategy"]
    Nightly["rust-toolchain: nightly"]
    Targets["4 target platforms"]
end
Trigger["Push/PR Event"]
Success["CI Success"]
DocSuccess["Documentation Published"]

Build --> Test
CIJob --> Matrix
CargoDoc --> IndexHTML
Checkout --> InstallHack
Clippy --> Build
Components --> RustVersion
DocCheckout --> DocRust
DocJob --> DocCheckout
DocRust --> CargoDoc
Format --> Clippy
GitHubPages --> DocSuccess
IndexHTML --> GitHubPages
InstallHack --> InstallRust
InstallRust --> Components
Matrix --> Checkout
Matrix --> Nightly
Matrix --> Targets
RustVersion --> Format
Test --> Success
Trigger --> CIJob
Trigger --> DocJob

Sources: .github/workflows/ci.yml(L1 - L57) 

Code Quality Checks

The CI pipeline enforces code quality through multiple automated checks:

1. Code Formatting: cargo fmt --all -- --check ensures consistent code style .github/workflows/ci.yml(L24) 
2. Linting: cargo hack clippy --target ${{ matrix.targets }} --each-feature -- -D warnings catches potential issues .github/workflows/ci.yml(L26) 
3. Building: cargo hack build --target ${{ matrix.targets }} --each-feature validates compilation .github/workflows/ci.yml(L28) 
4. Testing: cargo hack test --target ${{ matrix.targets }} --each-feature runs unit tests (Linux only) .github/workflows/ci.yml(L30 - L31) 

Documentation Deployment

The doc job automatically builds and deploys documentation to GitHub Pages when changes are pushed to the default branch. The documentation is built with strict settings that treat broken links and missing documentation as errors .github/workflows/ci.yml(L41) 

Development Environment Setup

To contribute to the kspin crate, developers need to set up a Rust development environment with specific toolchain components and target support.

Required Toolchain Components

The development environment requires the Rust nightly toolchain with the following components:

• rust-src: Source code for cross-compilation
• clippy: Linting tool for code analysis
• rustfmt: Code formatting tool

Target Installation

Install the required compilation targets:

rustup target add x86_64-unknown-linux-gnu
rustup target add x86_64-unknown-none  
rustup target add riscv64gc-unknown-none-elf
rustup target add aarch64-unknown-none-softfloat

Development Tools

Install cargo-hack for feature flag testing:

cargo install cargo-hack

This tool enables testing with each feature flag combination individually, which is essential for ensuring the crate works correctly across different configurations .github/workflows/ci.yml(L15) 

Local Development Workflow

Development Workflow

flowchart TD
subgraph subGraph1["CI Validation"]
    CITrigger["CI Pipeline Triggered"]
    CIFormat["CI: Format check"]
    CIClippy["CI: Clippy check"]
    CIBuild["CI: Build all targets"]
    CITest["CI: Run tests"]
    CIDoc["CI: Build docs"]
end
subgraph subGraph0["Development Loop"]
    DevLoop["Development Loop"]
    CodeChange["Make code changes"]
    LocalFormat["cargo fmt"]
    LocalClippy["cargo clippy"]
    LocalBuild["cargo build"]
    LocalTest["cargo test"]
    Validation["Changes valid?"]
    Commit["git commit"]
end
DevStart["Start Development"]
Clone["git clone repository"]
Setup["Install toolchain components"]
Targets["Install target platforms"]
Push["git push"]
Success["Ready for merge"]

CIBuild --> CITest
CIClippy --> CIBuild
CIDoc --> Success
CIFormat --> CIClippy
CITest --> CIDoc
CITrigger --> CIFormat
Clone --> Setup
CodeChange --> LocalFormat
Commit --> Push
DevLoop --> CodeChange
DevStart --> Clone
LocalBuild --> LocalTest
LocalClippy --> LocalBuild
LocalFormat --> LocalClippy
LocalTest --> Validation
Push --> CITrigger
Setup --> Targets
Targets --> DevLoop
Validation --> CodeChange
Validation --> Commit

Sources: .github/workflows/ci.yml(L14 - L31)  Cargo.toml(L1 - L22) 

Testing Procedures

The kspin crate employs comprehensive testing through both local development tools and automated CI validation. Testing is performed across multiple feature combinations and target platforms to ensure broad compatibility.

Local Testing Commands

CI Testing Matrix

The CI system automatically tests every feature combination across all supported target platforms. Unit tests are executed only on the x86_64-unknown-linux-gnu target, as this is the only hosted environment that supports test execution .github/workflows/ci.yml(L30 - L31) 

The use of cargo-hack ensures that feature flag interactions are properly validated and that the crate maintains compatibility across different compilation configurations .github/workflows/ci.yml(L26 - L31) 

Sources: .github/workflows/ci.yml(L26 - L31)  Cargo.toml(L14 - L22) 

Build System and Feature Flags

Relevant source files

• .github/workflows/ci.yml
• Cargo.toml

This document covers the build system configuration, feature flags, and compilation targets for the kspin crate. It explains how to build the crate with different feature combinations and target platforms, and describes the automated build and testing infrastructure.

For information about the development environment setup and tooling, see Development Environment Setup. For details about the testing infrastructure, see Testing and CI Pipeline.

Feature Flags

The kspin crate uses Cargo feature flags to enable compile-time optimization for different deployment scenarios. The primary feature flag is smp, which controls whether the spinlock implementation includes multi-core synchronization logic.

SMP Feature Flag

The smp feature flag is defined in Cargo.toml(L14 - L16)  and controls fundamental compilation behavior:

Build Matrix: Feature Flag Compilation

When the smp feature is enabled:

• BaseSpinLock includes an AtomicBool state field
• Lock operations use compare_exchange atomic operations
• Full memory ordering constraints are enforced
• Spinning behavior is implemented for contention scenarios

When the smp feature is disabled:

• BaseSpinLock has no state field (zero-cost abstraction)
• Lock operations become no-ops or compile-time optimizations
• No atomic operations are generated
• Suitable for single-core embedded environments

Sources: Cargo.toml(L14 - L16) 

Target Platform Support

The build system supports multiple target architectures through the CI matrix configuration. Each target represents a different deployment environment with specific requirements.

Supported Targets

flowchart TD
subgraph subGraph2["Feature Testing"]
    EachFeature[".github/workflows/ci.yml:26,28--each-feature flag"]
    DefaultFeatures["Default buildNo features enabled"]
    SMPFeatures["SMP buildsmp feature enabled"]
end
subgraph subGraph1["Build Tools"]
    RustToolchain[".github/workflows/ci.yml:11rust-toolchain: [nightly]"]
    CargoHack[".github/workflows/ci.yml:15cargo-hack tool"]
    Components[".github/workflows/ci.yml:19rust-src, clippy, rustfmt"]
end
subgraph subGraph0["CI Build Matrix"]
    Matrix[".github/workflows/ci.yml:10-12matrix.targets"]
    x86Linux["x86_64-unknown-linux-gnuStandard Linux targetFull testing capabilities"]
    x86Bare["x86_64-unknown-noneBare metal x86No std library"]
    RISCV["riscv64gc-unknown-none-elfRISC-V embeddedArceOS target"]
    ARM["aarch64-unknown-none-softfloatARM64 embeddedSoftware floating point"]
end

CargoHack --> EachFeature
Components --> Matrix
EachFeature --> DefaultFeatures
EachFeature --> SMPFeatures
Matrix --> ARM
Matrix --> RISCV
Matrix --> x86Bare
Matrix --> x86Linux
RustToolchain --> Matrix

Sources: .github/workflows/ci.yml(L10 - L12)  .github/workflows/ci.yml(L19) 

Build Commands and Configuration

Basic Build Commands

The standard build commands work with cargo's feature flag system:

# Default build (no features)
cargo build

# Build with SMP support
cargo build --features smp

# Build for specific target
cargo build --target x86_64-unknown-none --features smp

# Build all feature combinations
cargo hack build --each-feature

CI Build Pipeline

The automated build pipeline uses cargo-hack to test all feature combinations across all target platforms:

sequenceDiagram
    participant GitHubActions as "GitHub Actions"
    participant BuildMatrix as "Build Matrix"
    participant cargohack as "cargo-hack"
    participant TargetPlatform as "Target Platform"

    GitHubActions ->> BuildMatrix: Trigger CI workflow
    GitHubActions ->> BuildMatrix: .github/workflows/ci.yml:3
    BuildMatrix ->> cargohack: Install cargo-hack tool
    BuildMatrix ->> cargohack: .github/workflows/ci.yml:15
    loop Each Target Platform
        BuildMatrix ->> TargetPlatform: Setup toolchain
        BuildMatrix ->> TargetPlatform: .github/workflows/ci.yml:16-20
        TargetPlatform ->> cargohack: Check format
        TargetPlatform ->> cargohack: .github/workflows/ci.yml:24
        TargetPlatform ->> cargohack: Run clippy
        TargetPlatform ->> cargohack: .github/workflows/ci.yml:26
        cargohack ->> TargetPlatform: --each-feature flag
        TargetPlatform ->> cargohack: Build all features
        TargetPlatform ->> cargohack: .github/workflows/ci.yml:28
    alt x86_64-unknown-linux-gnu
    alt only
        TargetPlatform ->> cargohack: Run tests
        TargetPlatform ->> cargohack: .github/workflows/ci.yml:30-31
    end
    end
    end

Build Steps Detail:

1. Format Check: cargo fmt --all -- --check .github/workflows/ci.yml(L24) 
2. Linting: cargo hack clippy --target $target --each-feature .github/workflows/ci.yml(L26) 
3. Compilation: cargo hack build --target $target --each-feature .github/workflows/ci.yml(L28) 
4. Testing: cargo hack test --target $target --each-feature (Linux only) .github/workflows/ci.yml(L31) 

Sources: .github/workflows/ci.yml(L24 - L31) 

Dependency Management

The crate's dependencies are managed through Cargo.toml and support the feature flag system:

Dependency Roles:

• cfg-if: Enables conditional compilation based on feature flags and target platform
• kernel_guard: Provides NoOp, NoPreempt, and NoPreemptIrqSave guard types
• smp feature: Controls atomic operation inclusion without additional dependencies

Sources: Cargo.toml(L19 - L21)  Cargo.toml(L14 - L17) 

Documentation Generation

The build system includes automated documentation generation and deployment:

flowchart TD
subgraph Output["Output"]
    TargetDoc["target/doc/Generated documentation"]
    DocsRS["docs.rs/kspinCargo.toml:10"]
end
subgraph subGraph1["Documentation Flags"]
    RustDocFlags["RUSTDOCFLAGS.github/workflows/ci.yml:41-D rustdoc::broken_intra_doc_links-D missing-docs"]
end
subgraph subGraph0["Documentation Pipeline"]
    DocJob[".github/workflows/ci.yml:33doc job"]
    BuildDocs[".github/workflows/ci.yml:48cargo doc --no-deps --all-features"]
    IndexGeneration[".github/workflows/ci.yml:49printf redirect to index.html"]
    GitHubPages[".github/workflows/ci.yml:50-56Deploy to gh-pages branch"]
end

BuildDocs --> IndexGeneration
DocJob --> BuildDocs
GitHubPages --> DocsRS
IndexGeneration --> TargetDoc
RustDocFlags --> BuildDocs
TargetDoc --> GitHubPages

The documentation build enforces strict documentation requirements through RUSTDOCFLAGS and deploys automatically to GitHub Pages for the default branch.

Sources: .github/workflows/ci.yml(L33 - L56)  .github/workflows/ci.yml(L41)  Cargo.toml(L10) 

Testing and CI Pipeline

Relevant source files

• .github/workflows/ci.yml

This document covers the automated testing infrastructure and continuous integration setup for the kspin crate. The testing and CI pipeline ensures code quality, compatibility across multiple target platforms, and automated documentation deployment.

For information about manually building the crate and configuring development environments, see Build System and Feature Flags and Development Environment Setup.

CI Pipeline Architecture

The kspin crate uses GitHub Actions for continuous integration, configured through a single workflow file that handles both testing and documentation deployment. The pipeline is designed to validate the crate across multiple embedded and general-purpose target platforms.

CI Pipeline Overview

flowchart TD
subgraph subGraph3["Doc Job Steps"]
    DocCheckout["actions/checkout@v4"]
    DocRust["dtolnay/rust-toolchain@nightly"]
    BuildDocs["cargo doc --no-deps --all-features"]
    Deploy["JamesIves/github-pages-deploy-action@v4"]
end
subgraph subGraph2["CI Job Steps"]
    Checkout["actions/checkout@v4"]
    InstallHack["taiki-e/install-action@cargo-hack"]
    SetupRust["dtolnay/rust-toolchain@nightly"]
    CheckVersion["rustc --version --verbose"]
    Format["cargo fmt --all -- --check"]
    Clippy["cargo hack clippy"]
    Build["cargo hack build"]
    Test["cargo hack test"]
end
subgraph subGraph1["GitHub Actions Workflow"]
    CIJob["ci jobTesting & Quality"]
    DocJob["doc jobDocumentation"]
end
subgraph subGraph0["Trigger Events"]
    Push["push events"]
    PR["pull_request events"]
end

Build --> Test
BuildDocs --> Deploy
CIJob --> Checkout
CheckVersion --> Format
Checkout --> InstallHack
Clippy --> Build
DocCheckout --> DocRust
DocJob --> DocCheckout
DocRust --> BuildDocs
Format --> Clippy
InstallHack --> SetupRust
PR --> CIJob
PR --> DocJob
Push --> CIJob
Push --> DocJob
SetupRust --> CheckVersion

Sources: .github/workflows/ci.yml(L1 - L57) 

Build Matrix Strategy

The CI pipeline uses a matrix build strategy to validate the codebase across multiple target platforms and feature combinations. This ensures compatibility with the diverse environments where kernel spinlocks are typically deployed.

Target Platform Matrix

flowchart TD
subgraph subGraph1["Target Platforms"]
    LinuxGNU["x86_64-unknown-linux-gnuStandard Linux userspace"]
    x86None["x86_64-unknown-noneBare metal x86_64"]
    RISCV["riscv64gc-unknown-none-elfRISC-V bare metal"]
    ARM["aarch64-unknown-none-softfloatARM64 bare metal"]
end
subgraph subGraph0["Matrix Strategy"]
    Matrix["matrix.targets"]
end
subgraph subGraph2["Feature Testing"]
    EachFeature["--each-feature flagTests all feature combinations"]
    SMPFeature["smp featureMulti-core vs single-core"]
end

EachFeature --> SMPFeature
Matrix --> ARM
Matrix --> LinuxGNU
Matrix --> RISCV
Matrix --> x86None

The cargo-hack tool is used with the --each-feature flag to test all possible feature combinations across all target platforms, ensuring that feature-conditional compilation works correctly.

Sources: .github/workflows/ci.yml(L8 - L20)  .github/workflows/ci.yml(L26 - L31) 

Quality Assurance Pipeline

The CI pipeline enforces code quality through multiple automated checks that must pass before code can be merged.

Quality Check Sequence

sequenceDiagram
    participant GitHubActions as "GitHub Actions"
    participant RustToolchain as "Rust Toolchain"
    participant cargohack as "cargo-hack"
    participant TargetPlatform as "Target Platform"

    GitHubActions ->> RustToolchain: Setup nightly toolchain
    RustToolchain ->> GitHubActions: Install rust-src, clippy, rustfmt
    Note over GitHubActions,TargetPlatform: For each target in matrix
    GitHubActions ->> RustToolchain: cargo fmt --all -- --check
    RustToolchain ->> GitHubActions: ✓ Code formatting validated
    GitHubActions ->> cargohack: cargo hack clippy --target <target> --each-feature
    cargohack ->> TargetPlatform: Run clippy for each feature combination
    TargetPlatform ->> cargohack: ✓ No warnings (-D warnings)
    cargohack ->> GitHubActions: ✓ Linting complete
    GitHubActions ->> cargohack: cargo hack build --target <target> --each-feature
    cargohack ->> TargetPlatform: Build each feature combination
    TargetPlatform ->> cargohack: ✓ Successful build
    cargohack ->> GitHubActions: ✓ Build complete

Code Formatting

• Tool: cargo fmt
• Enforcement: --check flag ensures CI fails if code is not properly formatted
• Scope: All files (--all flag)

Linting

• Tool: cargo clippy
• Configuration: Treats all warnings as errors (-D warnings)
• Coverage: All target platforms and feature combinations
• Command: cargo hack clippy --target ${{ matrix.targets }} --each-feature -- -D warnings

Build Validation

• Tool: cargo build via cargo-hack
• Coverage: All target platforms and feature combinations
• Command: cargo hack build --target ${{ matrix.targets }} --each-feature

Sources: .github/workflows/ci.yml(L24 - L28) 

Testing Strategy

The testing approach recognizes the constraints of kernel-space code while maximizing coverage where possible.

Test Execution Matrix

flowchart TD
subgraph subGraph2["Test Execution"]
    TestRun["if: matrix.targets == 'x86_64-unknown-linux-gnu'cargo hack test --target --each-feature -- --nocapture"]
    BuildOnly["Build-only validationfor bare metal targets"]
end
subgraph subGraph1["Test Types"]
    UnitTests["Unit Testscargo hack test"]
    BuildTests["Build Testscargo hack build"]
    FeatureTests["Feature Tests--each-feature"]
end
subgraph subGraph0["Test Targets"]
    LinuxTarget["x86_64-unknown-linux-gnu"]
    BareMetalTargets["Bare metal targetsx86_64-unknown-noneriscv64gc-unknown-none-elfaarch64-unknown-none-softfloat"]
end

BareMetalTargets --> BuildOnly
BareMetalTargets --> BuildTests
BareMetalTargets --> FeatureTests
FeatureTests --> TestRun
LinuxTarget --> BuildTests
LinuxTarget --> FeatureTests
LinuxTarget --> TestRun
LinuxTarget --> UnitTests
UnitTests --> TestRun

Unit Test Execution

• Platform Restriction: Tests only run on x86_64-unknown-linux-gnu
• Rationale: Bare metal targets cannot execute standard Rust test framework
• Configuration: Tests run with --nocapture for full output visibility
• Feature Coverage: All feature combinations tested via --each-feature

Build-Only Testing

For bare metal targets (x86_64-unknown-none, riscv64gc-unknown-none-elf, aarch64-unknown-none-softfloat), the pipeline performs build-only validation to ensure:

• Code compiles successfully for target architecture
• Feature flags work correctly in no-std environments
• Cross-compilation succeeds without runtime dependencies

Sources: .github/workflows/ci.yml(L30 - L31) 

Documentation Pipeline

The documentation system automatically builds and deploys API documentation to GitHub Pages, ensuring developers always have access to current documentation.

Documentation Workflow

flowchart TD
subgraph Deployment["Deployment"]
    BranchCheck["if: github.ref == env.default-branch"]
    GHPages["JamesIves/github-pages-deploy-action@v4branch: gh-pagesfolder: target/docsingle-commit: true"]
end
subgraph subGraph1["Build Process"]
    DocBuild["cargo doc --no-deps --all-features"]
    IndexGen["Generate redirect index.html$(cargo tree | head -1 | cut -d' ' -f1)"]
    ContinueOnError["continue-on-error: conditionalBased on branch and event type"]
end
subgraph subGraph0["Documentation Job"]
    DocTrigger["Push to default branchOR pull request"]
    DocPerms["permissions:contents: write"]
    DocEnv["RUSTDOCFLAGS:-D rustdoc::broken_intra_doc_links-D missing-docs"]
end

BranchCheck --> GHPages
ContinueOnError --> BranchCheck
DocBuild --> IndexGen
DocEnv --> DocBuild
DocPerms --> DocEnv
DocTrigger --> DocPerms
IndexGen --> ContinueOnError

Documentation Quality Enforcement

The documentation build process enforces strict quality standards:

Deployment Strategy

• Target Branch: gh-pages
• Deployment Condition: Only on pushes to the default branch
• Commit Strategy: single-commit: true keeps deployment history clean
• Index Generation: Automatically creates redirect to main crate documentation

Sources: .github/workflows/ci.yml(L33 - L57) 

Pipeline Robustness Features

The CI configuration includes several features designed to maintain pipeline reliability and provide useful feedback:

Error Handling

• Fail-fast disabled: fail-fast: false allows all matrix jobs to complete even if some fail
• Conditional error handling: Documentation builds continue on error for non-default branches
• Warning promotion: Clippy warnings treated as errors to maintain code quality

Toolchain Management

• Nightly Rust: Uses bleeding-edge features required for no-std development
• Component installation: Automatically installs required components (rust-src, clippy, rustfmt)
• Version verification: Explicit Rust version checking for debugging

Resource Optimization

• Single commit deployment: Minimizes repository size growth from documentation updates
• Targeted testing: Unit tests only run where feasible (Linux target)
• Efficient caching: Standard GitHub Actions caching for Rust toolchain and dependencies

Sources: .github/workflows/ci.yml(L9)  .github/workflows/ci.yml(L41)  .github/workflows/ci.yml(L46) 

Development Environment Setup

Relevant source files

• .github/workflows/ci.yml
• .gitignore
• Cargo.toml

This document provides guidance for setting up a development environment to build, test, and contribute to the kspin crate. It covers the required toolchain, build processes, and development practices used by the project.

For information about the build system's feature flags and compilation targets, see Build System and Feature Flags. For details about the automated testing infrastructure, see Testing and CI Pipeline.

Prerequisites

The kspin crate requires specific Rust toolchain components and supports multiple target platforms. The development environment must be configured to handle both hosted and no-std embedded targets.

Required Rust Toolchain Components

The project uses the Rust nightly toolchain with specific components required for cross-platform development and code quality checks:

Supported Target Platforms

The CI system validates builds across multiple target architectures:

Sources: .github/workflows/ci.yml(L12)  .github/workflows/ci.yml(L18 - L20) 

Development Toolchain Setup

Rust Toolchain Installation

Install the nightly Rust toolchain with required components and target platforms:

# Install nightly toolchain
rustup toolchain install nightly

# Add required components
rustup component add --toolchain nightly rust-src clippy rustfmt

# Add target platforms
rustup target add --toolchain nightly x86_64-unknown-none
rustup target add --toolchain nightly riscv64gc-unknown-none-elf
rustup target add --toolchain nightly aarch64-unknown-none-softfloat

Development Tools

Install cargo-hack for comprehensive feature combination testing:

cargo install cargo-hack

The cargo-hack tool enables testing all feature combinations across different targets, matching the CI environment exactly.

Sources: .github/workflows/ci.yml(L15)  .github/workflows/ci.yml(L16 - L20) 

Development Workflow

Development Environment Flow

flowchart TD
subgraph Documentation["Documentation"]
    DocBuild["cargo doc --no-deps --all-featuresLocal documentation"]
    DocView["Open target/doc/kspin/index.htmlView generated docs"]
end
subgraph subGraph2["Local Development Commands"]
    Format["cargo fmt --all --checkCode formatting"]
    Clippy["cargo hack clippy--target TARGET --each-feature-- -D warnings"]
    Build["cargo hack build--target TARGET --each-feature"]
    Test["cargo hack test--target x86_64-unknown-linux-gnu--each-feature -- --nocapture"]
end
subgraph subGraph1["Development Tools"]
    VSCode[".vscode/VS Code configuration"]
    Git[".gitignoreGit ignore rules"]
    CargoToml["Cargo.tomlDependencies & metadata"]
end
subgraph subGraph0["Local Development Setup"]
    RustInstall["rustup install nightly"]
    ComponentAdd["rustup component addrust-src clippy rustfmt"]
    TargetAdd["rustup target addx86_64-unknown-noneriscv64gc-unknown-none-elfaarch64-unknown-none-softfloat"]
    CargoHack["cargo install cargo-hack"]
end

Build --> Test
CargoHack --> Format
CargoToml --> Build
Clippy --> Build
ComponentAdd --> TargetAdd
DocBuild --> DocView
Format --> Clippy
Git --> VSCode
RustInstall --> ComponentAdd
TargetAdd --> CargoHack
Test --> DocBuild
VSCode --> Format

Sources: .github/workflows/ci.yml(L16 - L31)  .github/workflows/ci.yml(L45 - L49)  .gitignore(L2) 

Local Build and Test Process

Code Quality Checks

Replicate the CI environment locally by running the same commands used in automated testing:

Code Formatting

cargo fmt --all -- --check

Linting with Feature Combinations

# Lint for specific target with all feature combinations
cargo hack clippy --target x86_64-unknown-none --each-feature -- -D warnings
cargo hack clippy --target riscv64gc-unknown-none-elf --each-feature -- -D warnings

Building Across Targets

# Build for all feature combinations on each target
cargo hack build --target x86_64-unknown-none --each-feature
cargo hack build --target riscv64gc-unknown-none-elf --each-feature
cargo hack build --target aarch64-unknown-none-softfloat --each-feature

Testing

# Run tests (only on hosted target)
cargo hack test --target x86_64-unknown-linux-gnu --each-feature -- --nocapture

Sources: .github/workflows/ci.yml(L24)  .github/workflows/ci.yml(L26)  .github/workflows/ci.yml(L28)  .github/workflows/ci.yml(L31) 

Feature Flag Testing

The --each-feature flag tests the following combinations:

• No features (default)
• smp feature enabled
• All features enabled

This ensures the crate works correctly in both single-core and multi-core environments.

Local Development Command Mapping

flowchart TD
subgraph subGraph3["Target Platforms"]
    LinuxGnu["x86_64-unknown-linux-gnu(testing only)"]
    X86None["x86_64-unknown-none(kernel target)"]
    RiscV["riscv64gc-unknown-none-elf(embedded kernel)"]
    ARM["aarch64-unknown-none-softfloat(embedded kernel)"]
end
subgraph subGraph2["Local Development"]
    LocalFormat["cargo fmt"]
    LocalClippy["cargo clippy"]
    LocalBuild["cargo build"]
    LocalTest["cargo test"]
    LocalDoc["cargo doc --no-deps --all-features"]
end
subgraph subGraph1["CI Commands"]
    CIFormat["cargo fmt --all -- --check"]
    CIClippy["cargo hack clippy --target TARGET--each-feature -- -D warnings"]
    CIBuild["cargo hack build --target TARGET--each-feature"]
    CITest["cargo hack test --target TARGET--each-feature -- --nocapture"]
end
subgraph subGraph0["Cargo.toml Configuration"]
    Features["[features]smp = []default = []"]
    Dependencies["[dependencies]cfg-if = '1.0'kernel_guard = '0.1'"]
end

CIBuild --> ARM
CIBuild --> LocalBuild
CIBuild --> RiscV
CIBuild --> X86None
CIClippy --> LocalClippy
CIFormat --> LocalFormat
CITest --> LinuxGnu
CITest --> LocalTest
Dependencies --> LocalBuild
Features --> CIBuild
LocalDoc --> CIBuild

Sources: Cargo.toml(L14 - L17)  Cargo.toml(L19 - L21)  .github/workflows/ci.yml(L12)  .github/workflows/ci.yml(L24 - L31) 

Development Environment Configuration

IDE Setup

The project includes VS Code ignore rules, indicating support for Visual Studio Code development:

/.vscode

Developers can create local .vscode/settings.json configurations for:

• Rust-analyzer settings
• Target-specific build configurations
• Code formatting preferences

Git Configuration

The .gitignore file excludes:

• Build artifacts (/target)
• IDE configurations (/.vscode)
• System files (.DS_Store)

Sources: .gitignore(L1 - L3) 

Documentation Development

Local Documentation Building

Generate and view documentation locally:

# Build documentation with all features
cargo doc --no-deps --all-features

# View in browser
open target/doc/kspin/index.html

The documentation build process matches the CI environment, ensuring consistency with the published GitHub Pages documentation.

Documentation Quality Checks

The CI system enforces documentation quality with specific RUSTDOCFLAGS:

RUSTDOCFLAGS="-D rustdoc::broken_intra_doc_links -D missing-docs" cargo doc --no-deps --all-features

Sources: .github/workflows/ci.yml(L41)  .github/workflows/ci.yml(L45 - L49) 

Continuous Integration Alignment

The local development environment should replicate the CI matrix strategy to ensure compatibility:

Matrix Testing Strategy

CI Job Replication

1. Format Check: cargo fmt --all -- --check
2. Lint Check: cargo hack clippy --target TARGET --each-feature -- -D warnings
3. Build Check: cargo hack build --target TARGET --each-feature
4. Unit Tests: cargo hack test --target x86_64-unknown-linux-gnu --each-feature -- --nocapture
5. Documentation: cargo doc --no-deps --all-features

Running these commands locally before committing ensures smooth CI pipeline execution.

Sources: .github/workflows/ci.yml(L8 - L12)  .github/workflows/ci.yml(L24 - L31) 

Overview

Relevant source files

• Cargo.toml
• README.md
• src/lib.rs

Purpose and Scope

The kernel_guard crate provides RAII (Resource Acquisition Is Initialization) wrappers for creating critical sections in kernel-level code where local interrupts (IRQs) and/or preemption must be temporarily disabled. This crate is specifically designed for operating system kernels and bare-metal systems that require fine-grained control over interrupt handling and task scheduling.

The primary use case is implementing synchronization primitives like spinlocks in kernel code, where critical sections must be protected from both interrupt handlers and preemptive task switching. For detailed information about the core architecture and guard implementations, see Core Architecture. For multi-architecture support details, see Multi-Architecture Support. For integration guidance, see Integration Guide.

Sources: Cargo.toml(L6 - L12)  src/lib.rs(L1 - L11)  README.md(L7 - L11) 

Core Guard Types and RAII Pattern

The crate implements four distinct guard types that follow the RAII pattern, automatically managing critical section entry and exit through constructor and destructor semantics:

Guard Type Architecture

flowchart TD
subgraph subGraph2["Target Dependencies"]
    ARCH["arch::local_irq_save_and_disable()arch::local_irq_restore()"]
    INTERFACE["crate_interface::call_interface!KernelGuardIf::disable_preemptKernelGuardIf::enable_preempt"]
end
subgraph subGraph1["Concrete Guards"]
    NOOP["NoOptype State = ()No operation"]
    IRQ["IrqSavetype State = usizeSaves/restores IRQ state"]
    PREEMPT["NoPreempttype State = ()Disables preemption"]
    BOTH["NoPreemptIrqSavetype State = usizeDisables both"]
end
subgraph subGraph0["BaseGuard Trait"]
    BG["BaseGuardacquire() -> Staterelease(State)"]
end

BG --> BOTH
BG --> IRQ
BG --> NOOP
BG --> PREEMPT
BOTH --> ARCH
BOTH --> INTERFACE
IRQ --> ARCH
PREEMPT --> INTERFACE

Sources: src/lib.rs(L68 - L78)  src/lib.rs(L81 - L111)  src/lib.rs(L134 - L179) 

Sources: src/lib.rs(L113 - L128)  src/lib.rs(L134 - L179)  src/lib.rs(L200 - L237) 

Conditional Compilation Strategy

The crate uses sophisticated conditional compilation to provide different implementations based on the target environment and enabled features:

Compilation Flow and Code Paths

Sources: src/lib.rs(L83 - L111)  src/lib.rs(L130 - L238)  Cargo.toml(L14 - L16) 

Multi-Architecture Support Integration

The crate abstracts platform-specific interrupt handling through a unified architecture interface:

Architecture Module Structure

Sources: src/lib.rs(L56)  src/lib.rs(L139 - L145)  src/lib.rs(L170 - L174) 

User Integration Pattern

The crate uses the crate_interface mechanism to allow users to provide preemption control implementations:

Integration Interface Flow

flowchart TD
subgraph subGraph2["Runtime Behavior"]
    ACQUIRE["acquire() calls disable_preempt"]
    DROP["drop() calls enable_preempt"]
end
subgraph subGraph1["kernel_guard Crate"]
    TRAIT_DEF["#[crate_interface::def_interface]trait KernelGuardIfsrc/lib.rs:59-66"]
    CALL_SITE["crate_interface::call_interface!KernelGuardIf::disable_preemptsrc/lib.rs:154"]
    GUARD_IMPL["NoPreempt BaseGuard implsrc/lib.rs:149-161"]
end
subgraph subGraph0["User Code"]
    USER_IMPL["struct KernelGuardIfImpl"]
    TRAIT_IMPL["#[crate_interface::impl_interface]impl KernelGuardIf for KernelGuardIfImpl"]
    USAGE["let guard = NoPreempt::new()"]
end

CALL_SITE --> TRAIT_IMPL
GUARD_IMPL --> ACQUIRE
GUARD_IMPL --> CALL_SITE
GUARD_IMPL --> DROP
TRAIT_IMPL --> TRAIT_DEF
USAGE --> GUARD_IMPL
USER_IMPL --> TRAIT_IMPL

Sources: src/lib.rs(L58 - L66)  src/lib.rs(L149 - L161)  src/lib.rs(L31 - L52)  README.md(L36 - L58) 

Feature Configuration Summary

The crate provides two primary configuration axes:

Sources: src/lib.rs(L83 - L111)  Cargo.toml(L14 - L16)  src/lib.rs(L153 - L159) 

The crate is specifically designed for the ArceOS ecosystem but provides a generic interface suitable for any kernel or bare-metal system requiring interrupt and preemption management. The modular architecture ensures that only the necessary functionality is compiled for each target platform while maintaining a consistent API across all supported architectures.

Core Architecture

Relevant source files

• README.md
• src/lib.rs

This document describes the core architecture of the kernel_guard crate, focusing on the trait system, RAII guard implementations, and conditional compilation strategy. The architecture provides a unified interface for creating critical sections while abstracting platform-specific interrupt handling and kernel preemption control.

For information about platform-specific implementations, see Multi-Architecture Support. For integration details and feature configuration, see Integration Guide.

Trait System Foundation

The kernel_guard crate is built around two core traits that define the contract for critical section management and kernel integration.

BaseGuard Trait

The BaseGuard trait serves as the fundamental interface that all guard implementations must satisfy. It defines a generic pattern for acquiring and releasing critical section protection.

classDiagram
class BaseGuard {
    <<trait>>
    +type State: Clone + Copy
    +acquire() State
    +release(state: State)
}

class NoOp {
    
    +type State =()
    +acquire()()
    +release(())
}

class IrqSave {
    +type State = usize
    +acquire() usize
    +release(usize)
}

class NoPreempt {
    
    +type State =()
    +acquire()()
    +release(())
}

class NoPreemptIrqSave {
    +type State = usize
    +acquire() usize
    +release(usize)
}

BaseGuard  ..|>  NoOp
BaseGuard  ..|>  IrqSave
BaseGuard  ..|>  NoPreempt
NoPreemptIrqSave  ..|>  IrqSave

BaseGuard Trait Architecture

The trait uses an associated State type to capture platform-specific information needed to restore the system state when the critical section ends. For example, interrupt guards store the previous interrupt flag state, while preemption-only guards use unit type since no state needs preservation.

Sources: src/lib.rs(L68 - L78) 

KernelGuardIf Interface

The KernelGuardIf trait provides the integration point between kernel_guard and the user's kernel implementation. This trait must be implemented by crate users when the preempt feature is enabled.

flowchart TD
subgraph subGraph1["kernel_guard Crate"]
    KernelGuardIf["KernelGuardIf Traitenable_preempt()disable_preempt()"]
    CallInterface["crate_interface::call_interface!Runtime dispatch"]
    NoPreempt["NoPreempt Guard"]
    NoPreemptIrqSave["NoPreemptIrqSave Guard"]
end
subgraph subGraph0["User Crate"]
    UserImpl["User ImplementationKernelGuardIfImpl"]
end

CallInterface --> KernelGuardIf
NoPreempt --> CallInterface
NoPreemptIrqSave --> CallInterface
UserImpl --> KernelGuardIf

KernelGuardIf Integration Pattern

The interface uses the crate_interface crate to provide stable ABI boundaries, allowing the kernel implementation to be provided at runtime rather than compile time.

Sources: src/lib.rs(L58 - L66)  src/lib.rs(L154)  src/lib.rs(L159)  src/lib.rs(L168)  src/lib.rs(L177) 

Guard Implementation Hierarchy

The crate provides four distinct guard types, each designed for specific synchronization requirements in kernel contexts.

Guard Type Matrix

Implementation Strategy

flowchart TD
subgraph subGraph2["Platform Integration"]
    ArchIRQ["arch::local_irq_save_and_disable()"]
    ArchRestore["arch::local_irq_restore(state)"]
    KernelIF["KernelGuardIf::disable_preempt()"]
    KernelRestore["KernelGuardIf::enable_preempt()"]
end
subgraph subGraph1["State Management"]
    IRQState["IRQ State (usize)Platform flags"]
    NoState["No State (())Simple enable/disable"]
end
subgraph subGraph0["Guard Lifecycle"]
    Create["Guard::new()"]
    Acquire["BaseGuard::acquire()"]
    Critical["Critical SectionUser Code"]
    Drop["impl Drop"]
    Release["BaseGuard::release(state)"]
end

Acquire --> ArchIRQ
Acquire --> Critical
Acquire --> KernelIF
ArchIRQ --> IRQState
Create --> Acquire
Critical --> Drop
Drop --> Release
IRQState --> ArchRestore
KernelIF --> NoState
NoState --> KernelRestore
Release --> ArchRestore
Release --> KernelRestore

RAII Guard Lifecycle and Platform Integration

Sources: src/lib.rs(L134 - L179)  src/lib.rs(L181 - L237) 

Conditional Compilation Strategy

The crate uses sophisticated conditional compilation to provide different implementations based on the target environment and available features.

Target Environment Detection

flowchart TD
subgraph subGraph3["Feature Gates"]
    PreemptEnabled["#[cfg(feature = 'preempt')]crate_interface calls"]
    PreemptDisabled["No preemption control"]
end
subgraph subGraph2["Userspace Path"]
    AliasIrqSave["type IrqSave = NoOp"]
    AliasNoPreempt["type NoPreempt = NoOp"]
    AliasNoPreemptIrqSave["type NoPreemptIrqSave = NoOp"]
end
subgraph subGraph1["Bare Metal Path"]
    RealIrqSave["struct IrqSave(usize)"]
    RealNoPreempt["struct NoPreempt"]
    RealNoPreemptIrqSave["struct NoPreemptIrqSave(usize)"]
    ArchIntegration["arch::local_irq_* calls"]
end
subgraph subGraph0["Compilation Decision"]
    CfgIf["cfg_if! macro"]
    TargetCheck["target_os = 'none' or doc?"]
    FeatureCheck["preempt feature enabled?"]
end

CfgIf --> TargetCheck
FeatureCheck --> PreemptDisabled
FeatureCheck --> PreemptEnabled
RealIrqSave --> ArchIntegration
RealNoPreempt --> PreemptEnabled
RealNoPreemptIrqSave --> ArchIntegration
RealNoPreemptIrqSave --> PreemptEnabled
TargetCheck --> AliasIrqSave
TargetCheck --> AliasNoPreempt
TargetCheck --> AliasNoPreemptIrqSave
TargetCheck --> RealIrqSave
TargetCheck --> RealNoPreempt
TargetCheck --> RealNoPreemptIrqSave

Conditional Compilation Flow

The compilation strategy ensures that:

1. Bare metal targets (target_os = "none") receive full guard implementations with platform-specific interrupt control
2. Userspace targets receive no-op aliases to prevent compilation errors while maintaining API compatibility
3. Feature-gated preemption only compiles preemption control when the preempt feature is enabled

Sources: src/lib.rs(L83 - L111)  src/lib.rs(L130 - L238)  src/lib.rs(L153 - L154)  src/lib.rs(L158 - L159)  src/lib.rs(L167 - L168)  src/lib.rs(L176 - L177) 

Architecture Module Integration

The core library integrates with platform-specific implementations through the arch module, which provides a uniform interface for interrupt control across different CPU architectures.

Architecture Abstraction Interface

flowchart TD
subgraph subGraph2["Platform Implementations"]
    X86["x86::local_irq_*"]
    RISCV["riscv::local_irq_*"]
    AArch64["aarch64::local_irq_*"]
    LoongArch["loongarch64::local_irq_*"]
end
subgraph subGraph1["Architecture Module"]
    ArchMod["mod arch"]
    LocalIrqSave["local_irq_save_and_disable()"]
    LocalIrqRestore["local_irq_restore(state)"]
end
subgraph subGraph0["Core Library"]
    IrqSave["IrqSave::acquire()"]
    IrqRestore["IrqSave::release()"]
    NoPreemptIrqSave["NoPreemptIrqSave"]
end

ArchMod --> LocalIrqRestore
ArchMod --> LocalIrqSave
IrqRestore --> LocalIrqRestore
IrqSave --> LocalIrqSave
LocalIrqRestore --> AArch64
LocalIrqRestore --> LoongArch
LocalIrqRestore --> RISCV
LocalIrqRestore --> X86
LocalIrqSave --> AArch64
LocalIrqSave --> LoongArch
LocalIrqSave --> RISCV
LocalIrqSave --> X86
NoPreemptIrqSave --> LocalIrqRestore
NoPreemptIrqSave --> LocalIrqSave

Architecture Module Integration Pattern

The architecture module provides two critical functions that abstract platform-specific interrupt handling:

• local_irq_save_and_disable(): Returns current interrupt state and disables interrupts
• local_irq_restore(state): Restores interrupt state from saved value

Sources: src/lib.rs(L56)  src/lib.rs(L139)  src/lib.rs(L145)  src/lib.rs(L170)  src/lib.rs(L174) 

RAII Lifecycle Management

The crate implements the RAII (Resource Acquisition Is Initialization) pattern to ensure critical sections are properly managed without requiring explicit cleanup calls.

Drop Implementation Pattern

sequenceDiagram
    participant UserCode as "User Code"
    participant GuardInstance as "Guard Instance"
    participant BaseGuardacquirerelease as "BaseGuard::acquire/release"
    participant PlatformLayer as "Platform Layer"

    UserCode ->> GuardInstance: "Guard::new()"
    GuardInstance ->> BaseGuardacquirerelease: "acquire()"
    BaseGuardacquirerelease ->> PlatformLayer: "disable IRQ/preemption"
    PlatformLayer -->> BaseGuardacquirerelease: "return state"
    BaseGuardacquirerelease -->> GuardInstance: "return state"
    GuardInstance -->> UserCode: "return guard instance"
    Note over UserCode: Critical section executes
    UserCode ->> GuardInstance: "drop(guard) or scope end"
    GuardInstance ->> BaseGuardacquirerelease: "release(state)"
    BaseGuardacquirerelease ->> PlatformLayer: "restore IRQ/preemption"
    PlatformLayer -->> BaseGuardacquirerelease: "complete"
    BaseGuardacquirerelease -->> GuardInstance: "complete"
    GuardInstance -->> UserCode: "destruction complete"

RAII Lifecycle Sequence

Each guard type implements the Drop trait to ensure that critical section protection is automatically released when the guard goes out of scope, preventing resource leaks and ensuring system stability.

Sources: src/lib.rs(L126 - L128)  src/lib.rs(L188 - L192)  src/lib.rs(L208 - L212)  src/lib.rs(L227 - L231) 

RAII Guards

Relevant source files

• README.md
• src/lib.rs

This document describes the four RAII guard types provided by the kernel_guard crate: NoOp, IrqSave, NoPreempt, and NoPreemptIrqSave. These guards implement the Resource Acquisition Is Initialization (RAII) pattern to automatically manage critical sections by disabling interrupts and/or preemption when created and restoring the previous state when dropped.

For information about the underlying trait system that enables these guards, see Trait System. For architecture-specific implementations of interrupt control, see Multi-Architecture Support.

Overview

The RAII guards in kernel_guard provide automatic critical section management through Rust's ownership system. Each guard type disables specific kernel features upon creation and restores them when the guard goes out of scope, ensuring that critical sections are properly bounded even in the presence of early returns or panics.

Guard Type Hierarchy

Sources: src/lib.rs(L68 - L78)  src/lib.rs(L80 - L111)  src/lib.rs(L113 - L128) 

RAII Lifecycle Pattern

sequenceDiagram
    participant UserCode as "User Code"
    participant GuardStruct as "Guard Struct"
    participant BaseGuardacquire as "BaseGuard::acquire()"
    participant archlocal_irq_ as "arch::local_irq_*"
    participant KernelGuardIf as "KernelGuardIf"
    participant Dropdrop as "Drop::drop()"

    UserCode ->> GuardStruct: "new()"
    GuardStruct ->> BaseGuardacquire: "acquire()"
    alt IrqSave or NoPreemptIrqSave
        BaseGuardacquire ->> archlocal_irq_: "local_irq_save_and_disable()"
        archlocal_irq_ -->> BaseGuardacquire: "saved_flags: usize"
    end
    alt NoPreempt or NoPreemptIrqSave
        BaseGuardacquire ->> KernelGuardIf: "disable_preempt()"
    end
    BaseGuardacquire -->> GuardStruct: "state"
    GuardStruct -->> UserCode: "guard_instance"
    Note over UserCode: Critical section code runs
    UserCode ->> Dropdrop: "guard goes out of scope"
    Dropdrop ->> BaseGuardacquire: "release(state)"
    alt IrqSave or NoPreemptIrqSave
        BaseGuardacquire ->> archlocal_irq_: "local_irq_restore(state)"
    end
    alt NoPreempt or NoPreemptIrqSave
        BaseGuardacquire ->> KernelGuardIf: "enable_preempt()"
    end

Sources: src/lib.rs(L134 - L179)  src/lib.rs(L181 - L237) 

Guard Types

NoOp Guard

The NoOp guard provides a no-operation implementation that does nothing around critical sections. It serves as a placeholder when guard functionality is not needed or not available.

The NoOp guard is always available and implements BaseGuard with empty operations:

// Implementation reference from src/lib.rs:113-117
impl BaseGuard for NoOp {
    type State = ();
    fn acquire() -> Self::State {}
    fn release(_state: Self::State) {}
}

Sources: src/lib.rs(L80 - L81)  src/lib.rs(L113 - L128) 

IrqSave Guard

The IrqSave guard disables local interrupts and saves the previous interrupt state, restoring it when dropped. This guard is only available on bare-metal targets (target_os = "none").

On non-bare-metal targets, IrqSave becomes a type alias to NoOp:

// Conditional compilation from src/lib.rs:83-111
cfg_if::cfg_if! {
    if #[cfg(any(target_os = "none", doc))] {
        pub struct IrqSave(usize);
    } else {
        pub type IrqSave = NoOp;
    }
}

The IrqSave implementation calls architecture-specific interrupt control functions:

Sources: src/lib.rs(L88)  src/lib.rs(L102 - L103)  src/lib.rs(L134 - L147)  src/lib.rs(L181 - L198) 

NoPreempt Guard

The NoPreempt guard disables kernel preemption for the duration of the critical section. It requires the preempt feature to be enabled and a user implementation of KernelGuardIf.

The preemption control is conditional on the preempt feature:

// Feature-gated implementation from src/lib.rs:149-161
impl BaseGuard for NoPreempt {
    type State = ();
    fn acquire() -> Self::State {
        #[cfg(feature = "preempt")]
        crate_interface::call_interface!(KernelGuardIf::disable_preempt);
    }
    fn release(_state: Self::State) {
        #[cfg(feature = "preempt")]
        crate_interface::call_interface!(KernelGuardIf::enable_preempt);
    }
}

Sources: src/lib.rs(L92)  src/lib.rs(L105 - L106)  src/lib.rs(L149 - L161)  src/lib.rs(L200 - L218) 

NoPreemptIrqSave Guard

The NoPreemptIrqSave guard combines both preemption and interrupt control, providing the strongest level of critical section protection. It disables preemption first, then interrupts, and restores them in reverse order.

The ordering ensures proper nesting: preemption is disabled before IRQs and re-enabled after IRQs are restored:

// Ordered disable/enable from src/lib.rs:163-179
impl BaseGuard for NoPreemptIrqSave {
    type State = usize;
    fn acquire() -> Self::State {
        // disable preempt first
        #[cfg(feature = "preempt")]
        crate_interface::call_interface!(KernelGuardIf::disable_preempt);
        // then disable IRQs
        super::arch::local_irq_save_and_disable()
    }
    fn release(state: Self::State) {
        // restore IRQs first
        super::arch::local_irq_restore(state);
        // then enable preempt
        #[cfg(feature = "preempt")]
        crate_interface::call_interface!(KernelGuardIf::enable_preempt);
    }
}

Sources: src/lib.rs(L100)  src/lib.rs(L108 - L109)  src/lib.rs(L163 - L179)  src/lib.rs(L220 - L237) 

Conditional Compilation Strategy

The guards use cfg_if macros to provide different implementations based on the target platform. This ensures that the crate can be used in both kernel and userspace contexts.

Target-Based Implementation Selection

Sources: src/lib.rs(L83 - L111)  src/lib.rs(L130 - L238) 

Usage Patterns

All guards follow the same basic usage pattern, differing only in their protection scope:

The RAII pattern ensures automatic cleanup:

// Pattern from src/lib.rs:45-51
let guard = GuardType::new();
// Critical section automatically begins here
// ... critical section code ...
// Critical section automatically ends when guard is dropped

Sources: src/lib.rs(L12 - L19)  src/lib.rs(L45 - L51)  src/lib.rs(L181 - L237) 

Trait System

Relevant source files

• Cargo.toml
• src/lib.rs

This document explains the trait-based architecture that forms the foundation of the kernel_guard crate. The trait system defines the interfaces for implementing critical section guards and provides extension points for user code to integrate preemption control. For information about specific guard implementations, see RAII Guards. For details on architecture-specific implementations, see Multi-Architecture Support.

Core Trait Architecture

The kernel_guard crate is built around two primary traits that define the interface contracts for guard behavior and user integration.

BaseGuard Trait

The BaseGuard trait serves as the foundational interface that all guard types must implement. It defines the basic lifecycle operations for entering and exiting critical sections using the RAII pattern.

flowchart TD
BG["BaseGuard trait"]
ST["Associated Type: State"]
ACQ["acquire() -> State"]
REL["release(state: State)"]
CLONE["Clone + Copy bounds"]
BEFORE["Execute before critical section"]
AFTER["Execute after critical section"]
IMPL1["NoOp"]
IMPL2["IrqSave"]
IMPL3["NoPreempt"]
IMPL4["NoPreemptIrqSave"]

ACQ --> BEFORE
BG --> ACQ
BG --> REL
BG --> ST
IMPL1 --> BG
IMPL2 --> BG
IMPL3 --> BG
IMPL4 --> BG
REL --> AFTER
ST --> CLONE

BaseGuard Trait Definition

The trait defines three key components at src/lib.rs(L68 - L78) :

Sources: src/lib.rs(L68 - L78) 

KernelGuardIf Trait

The KernelGuardIf trait provides an extension point for user code to implement preemption control functionality. This trait uses the crate_interface mechanism to enable runtime dispatch to user-provided implementations.

flowchart TD
DEF["KernelGuardIf trait definition"]
ENABLE["enable_preempt()"]
DISABLE["disable_preempt()"]
IMPL["User Implementation"]
CRATE_IMPL["#[crate_interface::impl_interface]"]
RUNTIME["Runtime dispatch"]
CALL1["NoPreempt::acquire()"]
DISPATCH1["crate_interface::call_interface!"]
CALL2["NoPreempt::release()"]
DISPATCH2["crate_interface::call_interface!"]

CALL1 --> DISPATCH1
CALL2 --> DISPATCH2
CRATE_IMPL --> RUNTIME
DEF --> DISABLE
DEF --> ENABLE
DISPATCH1 --> RUNTIME
DISPATCH2 --> RUNTIME
IMPL --> CRATE_IMPL
RUNTIME --> IMPL

Interface Definition

The trait is defined at src/lib.rs(L59 - L66)  with two required methods:

• enable_preempt(): Called when preemption should be re-enabled
• disable_preempt(): Called when preemption should be disabled

Sources: src/lib.rs(L59 - L66) 

Runtime Dispatch Mechanism

The crate uses the crate_interface library to implement a stable interface between the kernel_guard crate and user code. This mechanism allows the library to call user-provided functions at runtime without compile-time dependencies.

crate_interface Integration

Interface Declaration

The trait is declared as an interface using #[crate_interface::def_interface] at src/lib.rs(L59)  which generates the necessary infrastructure for runtime dispatch.

User Implementation Pattern

Users must implement the trait using the #[crate_interface::impl_interface] attribute, as shown in the example at src/lib.rs(L35 - L43) :

#![allow(unused)]
fn main() {
#[crate_interface::impl_interface]
impl KernelGuardIf for KernelGuardIfImpl {
    fn enable_preempt() { /* implementation */ }
    fn disable_preempt() { /* implementation */ }
}
}

Runtime Calls

The library invokes user implementations using crate_interface::call_interface! macro at several locations:

• src/lib.rs(L154)  - Disable preemption in NoPreempt::acquire()
• src/lib.rs(L159)  - Enable preemption in NoPreempt::release()
• src/lib.rs(L168)  - Disable preemption in NoPreemptIrqSave::acquire()
• src/lib.rs(L177)  - Enable preemption in NoPreemptIrqSave::release()

Sources: src/lib.rs(L59)  src/lib.rs(L35 - L43)  src/lib.rs(L154)  src/lib.rs(L159)  src/lib.rs(L168)  src/lib.rs(L177) 

Trait Implementation Patterns

Feature-Conditional Implementation

The KernelGuardIf calls are conditionally compiled based on the preempt feature flag. When the feature is disabled, the calls become no-ops:

Conditional Compilation Points:

• src/lib.rs(L153 - L154)  - disable_preempt in NoPreempt::acquire()
• src/lib.rs(L158 - L159)  - enable_preempt in NoPreempt::release()
• src/lib.rs(L167 - L168)  - disable_preempt in NoPreemptIrqSave::acquire()
• src/lib.rs(L176 - L177)  - enable_preempt in NoPreemptIrqSave::release()

Sources: src/lib.rs(L153 - L154)  src/lib.rs(L158 - L159)  src/lib.rs(L167 - L168)  src/lib.rs(L176 - L177) 

State Management Patterns

Different guard types use different State type strategies:

Sources: src/lib.rs(L114)  src/lib.rs(L135)  src/lib.rs(L150)  src/lib.rs(L164) 

Complete Trait Interaction Flow

The following diagram shows how the traits interact during a complete guard lifecycle:

sequenceDiagram
    participant UserCode as "User Code"
    participant GuardInstance as "Guard Instance"
    participant BaseGuardacquire as "BaseGuard::acquire()"
    participant archlocal_irq_ as "arch::local_irq_*"
    participant KernelGuardIf as "KernelGuardIf"
    participant UserImplementation as "User Implementation"

    UserCode ->> GuardInstance: new()
    GuardInstance ->> BaseGuardacquire: acquire()
    alt NoPreempt or NoPreemptIrqSave
        BaseGuardacquire ->> KernelGuardIf: crate_interface::call_interface!
        KernelGuardIf ->> UserImplementation: disable_preempt()
        UserImplementation -->> KernelGuardIf: ​
        KernelGuardIf -->> BaseGuardacquire: ​
    end
    alt IrqSave or NoPreemptIrqSave
        BaseGuardacquire ->> archlocal_irq_: local_irq_save_and_disable()
        archlocal_irq_ -->> BaseGuardacquire: flags: usize
    end
    BaseGuardacquire -->> GuardInstance: State
    GuardInstance -->> UserCode: Guard instance
    Note over UserCode: Critical Section Execution
    UserCode ->> GuardInstance: drop()
    GuardInstance ->> BaseGuardacquire: release(state)
    alt IrqSave or NoPreemptIrqSave
        BaseGuardacquire ->> archlocal_irq_: local_irq_restore(flags)
        archlocal_irq_ -->> BaseGuardacquire: ​
    end
    alt NoPreempt or NoPreemptIrqSave
        BaseGuardacquire ->> KernelGuardIf: crate_interface::call_interface!
        KernelGuardIf ->> UserImplementation: enable_preempt()
        UserImplementation -->> KernelGuardIf: ​
        KernelGuardIf -->> BaseGuardacquire: ​
    end
    BaseGuardacquire -->> GuardInstance: ​
    GuardInstance -->> UserCode: ​

Sources: src/lib.rs(L183 - L185)  src/lib.rs(L202 - L205)  src/lib.rs(L222 - L224)  src/lib.rs(L134 - L147)  src/lib.rs(L149 - L161)  src/lib.rs(L163 - L179) 

Multi-Architecture Support

Relevant source files

• Cargo.toml
• src/arch/mod.rs

This document covers how the kernel_guard crate provides cross-platform support for multiple CPU architectures through conditional compilation and architecture-specific implementations. It explains the architecture selection mechanism, supported platforms, and how platform-specific interrupt control is abstracted behind a unified interface.

For detailed implementation specifics of each architecture, see Architecture Abstraction Layer, x86/x86_64 Implementation, RISC-V Implementation, AArch64 Implementation, and LoongArch64 Implementation. For information about how these implementations integrate with the core guard system, see Core Architecture.

Architecture Selection Mechanism

The kernel_guard crate uses the cfg_if macro to conditionally compile architecture-specific code based on the target platform. The selection logic is centralized in the architecture module, which determines which platform-specific implementation to include at compile time.

flowchart TD
CfgIf["cfg_if::cfg_if! macro"]
X86Check["target_arch = 'x86' or 'x86_64'"]
RiscvCheck["target_arch = 'riscv32' or 'riscv64'"]
ArmCheck["target_arch = 'aarch64'"]
LoongCheck["target_arch = 'loongarch64'"]
X86Mod["mod x86"]
RiscvMod["mod riscv"]
ArmMod["mod aarch64"]
LoongMod["mod loongarch64"]
X86Use["pub use self::x86::*"]
RiscvUse["pub use self::riscv::*"]
ArmUse["pub use self::aarch64::*"]
LoongUse["pub use self::loongarch64::*"]
UnifiedApi["Unified arch:: interface"]

ArmCheck --> ArmMod
ArmMod --> ArmUse
ArmUse --> UnifiedApi
CfgIf --> ArmCheck
CfgIf --> LoongCheck
CfgIf --> RiscvCheck
CfgIf --> X86Check
LoongCheck --> LoongMod
LoongMod --> LoongUse
LoongUse --> UnifiedApi
RiscvCheck --> RiscvMod
RiscvMod --> RiscvUse
RiscvUse --> UnifiedApi
X86Check --> X86Mod
X86Mod --> X86Use
X86Use --> UnifiedApi

The conditional compilation ensures that only the relevant architecture-specific code is included in the final binary, reducing both compile time and binary size. Each architecture module provides the same interface functions but with platform-specific implementations.

Sources: src/arch/mod.rs(L3 - L17) 

Supported Architectures

The crate currently supports four major CPU architecture families, each with specific register and instruction handling for interrupt control:

Each architecture implementation provides the same core functions: local_irq_save, local_irq_restore, local_irq_enable, and local_irq_disable. The specific mechanism for manipulating interrupt state varies by platform but the interface remains consistent.

Sources: src/arch/mod.rs(L4 - L16) 

Conditional Compilation Strategy

The architecture abstraction uses a hierarchical conditional compilation strategy that first selects the appropriate architecture module, then re-exports its symbols to create a unified interface:

flowchart TD
CompileTime["Compile Time"]
TargetArch["target_arch evaluation"]
ModSelection["Module Selection"]
X86Path["x86.rs module"]
RiscvPath["riscv.rs module"]
Aarch64Path["aarch64.rs module"]
LoongPath["loongarch64.rs module"]
ReExport["pub use self::arch::*"]
GuardImpl["Guard implementations access arch functions"]
IrqSave["IrqSave::acquire() calls arch::local_irq_save()"]
NoPreemptIrqSave["NoPreemptIrqSave::acquire() calls arch functions"]

Aarch64Path --> ReExport
CompileTime --> TargetArch
GuardImpl --> IrqSave
GuardImpl --> NoPreemptIrqSave
LoongPath --> ReExport
ModSelection --> Aarch64Path
ModSelection --> LoongPath
ModSelection --> RiscvPath
ModSelection --> X86Path
ReExport --> GuardImpl
RiscvPath --> ReExport
TargetArch --> ModSelection
X86Path --> ReExport

This design allows the core guard implementations to remain architecture-agnostic while delegating platform-specific operations to the appropriate architecture module. The cfg_if macro ensures clean compilation without unused code warnings on platforms where certain modules are not applicable.

Sources: src/arch/mod.rs(L1 - L17)  Cargo.toml(L19) 

Dead Code Handling

The architecture module includes a conditional compilation attribute to handle scenarios where architecture-specific code might not be used on certain targets:

#![cfg_attr(not(target_os = "none"), allow(dead_code, unused_imports))]

This attribute prevents compiler warnings when building for non-bare-metal targets (where target_os != "none"), as some architecture-specific functionality may not be utilized in hosted environments where the operating system handles interrupt management.

Sources: src/arch/mod.rs(L1) 

Integration Points

The multi-architecture support integrates with the broader kernel_guard system through several key mechanisms:

• Guard Implementations: The IrqSave and NoPreemptIrqSave guards call architecture-specific functions through the unified arch:: interface
• Feature Gates: The cfg_if dependency enables the conditional compilation logic
• Target OS Detection: The crate can detect bare-metal vs. hosted environments and adjust behavior accordingly
• Interface Consistency: All architecture modules provide the same function signatures, ensuring guard implementations work across platforms

This architecture enables the same guard code to work across multiple CPU architectures while maintaining platform-specific optimizations for interrupt control.

Sources: src/arch/mod.rs(L3 - L17)  Cargo.toml(L19) 

Architecture Abstraction Layer

Relevant source files

• src/arch/mod.rs

Purpose and Scope

The Architecture Abstraction Layer provides a unified interface for interrupt control across multiple CPU architectures through conditional compilation. This module serves as the entry point that selects and re-exports the appropriate architecture-specific implementation based on the target compilation architecture.

For details on specific architecture implementations, see x86/x86_64 Implementation, RISC-V Implementation, AArch64 Implementation, and LoongArch64 Implementation. For information about how these implementations are used by the core guard system, see RAII Guards.

Conditional Compilation Strategy

The architecture abstraction layer uses the cfg_if macro to perform compile-time architecture selection. This approach ensures that only the relevant code for the target architecture is included in the final binary, reducing both code size and complexity.

Architecture Selection Flow

flowchart TD
START["Compilation Start"]
CFGIF["cfg_if::cfg_if! macro"]
X86_CHECK["target_arch = x86 or x86_64?"]
RISCV_CHECK["target_arch = riscv32 or riscv64?"]
ARM_CHECK["target_arch = aarch64?"]
LOONG_CHECK["target_arch = loongarch64?"]
X86_MOD["mod x86"]
X86_USE["pub use self::x86::*"]
RISCV_MOD["mod riscv"]
RISCV_USE["pub use self::riscv::*"]
ARM_MOD["mod aarch64"]
ARM_USE["pub use self::aarch64::*"]
LOONG_MOD["mod loongarch64"]
LOONG_USE["pub use self::loongarch64::*"]
UNIFIED["Unified arch:: namespace"]
GUARDS["Used by guard implementations"]

ARM_CHECK --> ARM_MOD
ARM_MOD --> ARM_USE
ARM_USE --> UNIFIED
CFGIF --> ARM_CHECK
CFGIF --> LOONG_CHECK
CFGIF --> RISCV_CHECK
CFGIF --> X86_CHECK
LOONG_CHECK --> LOONG_MOD
LOONG_MOD --> LOONG_USE
LOONG_USE --> UNIFIED
RISCV_CHECK --> RISCV_MOD
RISCV_MOD --> RISCV_USE
RISCV_USE --> UNIFIED
START --> CFGIF
UNIFIED --> GUARDS
X86_CHECK --> X86_MOD
X86_MOD --> X86_USE
X86_USE --> UNIFIED

Sources: src/arch/mod.rs(L3 - L17) 

Module Structure and Re-exports

The abstraction layer follows a simple but effective pattern where each supported architecture has its own module that implements the same interface. The main module conditionally includes and re-exports the appropriate implementation:

Sources: src/arch/mod.rs(L4 - L16) 

Code Entity Mapping

flowchart TD
subgraph FUNCTIONS["Exported functions"]
    LOCAL_IRQ_SAVE["local_irq_save()"]
    LOCAL_IRQ_RESTORE["local_irq_restore()"]
end
subgraph ARCH_MODULES["Architecture-specific modules"]
    X86_RS["src/arch/x86.rs"]
    RISCV_RS["src/arch/riscv.rs"]
    ARM_RS["src/arch/aarch64.rs"]
    LOONG_RS["src/arch/loongarch64.rs"]
end
subgraph MOD_RS["src/arch/mod.rs"]
    CFGIF_MACRO["cfg_if::cfg_if!"]
    X86_BRANCH["x86/x86_64 branch"]
    RISCV_BRANCH["riscv32/riscv64 branch"]
    ARM_BRANCH["aarch64 branch"]
    LOONG_BRANCH["loongarch64 branch"]
end

ARM_BRANCH --> ARM_RS
ARM_RS --> LOCAL_IRQ_RESTORE
ARM_RS --> LOCAL_IRQ_SAVE
CFGIF_MACRO --> ARM_BRANCH
CFGIF_MACRO --> LOONG_BRANCH
CFGIF_MACRO --> RISCV_BRANCH
CFGIF_MACRO --> X86_BRANCH
LOONG_BRANCH --> LOONG_RS
LOONG_RS --> LOCAL_IRQ_RESTORE
LOONG_RS --> LOCAL_IRQ_SAVE
RISCV_BRANCH --> RISCV_RS
RISCV_RS --> LOCAL_IRQ_RESTORE
RISCV_RS --> LOCAL_IRQ_SAVE
X86_BRANCH --> X86_RS
X86_RS --> LOCAL_IRQ_RESTORE
X86_RS --> LOCAL_IRQ_SAVE

Sources: src/arch/mod.rs(L1 - L18) 

Compiler Attributes and Target Handling

The module includes a conditional compiler attribute that suppresses warnings for unused code when targeting non-bare-metal environments:

#![cfg_attr(not(target_os = "none"), allow(dead_code, unused_imports))]

This attribute serves an important purpose:

• When target_os = "none" (bare metal/no_std environments), the architecture-specific code is actively used
• When targeting other operating systems (like Linux), the interrupt control functions may not be used by the guard implementations, leading to dead code warnings
• The attribute prevents these warnings without removing the code, maintaining consistency across build targets

Sources: src/arch/mod.rs(L1) 

Integration with Core Library

The architecture abstraction layer provides the low-level interrupt control functions that are consumed by the guard implementations in the core library. The local_irq_save() and local_irq_restore() functions exposed through this layer are called by:

• IrqSave guard for interrupt-only protection
• NoPreemptIrqSave guard for combined interrupt and preemption protection

This design ensures that the same high-level guard interface can work across all supported architectures while utilizing the most efficient interrupt control mechanism available on each platform.

Sources: src/arch/mod.rs(L3 - L17) 

x86/x86_64 Implementation

Relevant source files

• src/arch/x86.rs

Purpose and Scope

This document covers the x86 and x86_64 architecture-specific implementation of interrupt control within the kernel_guard crate. The x86 implementation provides low-level primitives for disabling and restoring local interrupts by manipulating the EFLAGS register using inline assembly.

This implementation is automatically selected when compiling for target_arch = "x86" or target_arch = "x86_64" through the conditional compilation system. For information about other architecture implementations, see RISC-V Implementation, AArch64 Implementation, and LoongArch64 Implementation. For details about the architecture selection mechanism, see Architecture Abstraction Layer.

x86 Interrupt Control Mechanism

The x86 architecture provides interrupt control through the Interrupt Flag (IF) bit in the EFLAGS register. When this bit is set, the processor responds to maskable hardware interrupts; when cleared, such interrupts are ignored.

x86 Architecture Integration

flowchart TD
CFGIF["cfg_if! macro evaluation"]
X86_CHECK["target_arch == x86 or x86_64?"]
X86_MOD["mod x86"]
OTHER_ARCH["Other architecture modules"]
REEXPORT["pub use self::arch::*"]
LOCAL_IRQ_SAVE["local_irq_save_and_disable()"]
LOCAL_IRQ_RESTORE["local_irq_restore()"]
IRQSAVE_GUARD["IrqSave guard"]
NOPREEMPT_IRQ_GUARD["NoPreemptIrqSave guard"]

CFGIF --> X86_CHECK
LOCAL_IRQ_RESTORE --> IRQSAVE_GUARD
LOCAL_IRQ_RESTORE --> NOPREEMPT_IRQ_GUARD
LOCAL_IRQ_SAVE --> IRQSAVE_GUARD
LOCAL_IRQ_SAVE --> NOPREEMPT_IRQ_GUARD
OTHER_ARCH --> REEXPORT
REEXPORT --> LOCAL_IRQ_RESTORE
REEXPORT --> LOCAL_IRQ_SAVE
X86_CHECK --> OTHER_ARCH
X86_CHECK --> X86_MOD
X86_MOD --> REEXPORT

Sources: src/arch/x86.rs(L1 - L21) 

Implementation Details

The x86 implementation consists of two core functions that manipulate the EFLAGS register through inline assembly.

Interrupt Flag Constants

The implementation defines the Interrupt Flag bit position as a constant:

Core Functions

local_irq_save_and_disable()

This function atomically saves the current interrupt state and disables interrupts. It returns the previous state of the Interrupt Flag for later restoration.

Implementation Strategy:

• Uses pushf instruction to push EFLAGS onto the stack
• Uses pop instruction to retrieve EFLAGS value into a register
• Uses cli instruction to clear the Interrupt Flag
• Returns only the IF bit status (masked with IF_BIT)

local_irq_restore(flags)

This function restores the interrupt state based on the previously saved flags value.

Implementation Strategy:

• Checks if the saved flags indicate interrupts were enabled
• Uses sti instruction to set the Interrupt Flag if interrupts should be enabled
• Uses cli instruction to clear the Interrupt Flag if interrupts should remain disabled

Interrupt Control Flow

flowchart TD
ACQUIRE["Guard Acquire"]
SAVE_DISABLE["local_irq_save_and_disable()"]
PUSHF["pushf (push EFLAGS)"]
POP["pop reg (get EFLAGS value)"]
CLI["cli (disable interrupts)"]
MASK["flags & IF_BIT"]
RETURN_FLAGS["return saved_flags"]
CRITICAL["Critical Section Execution"]
RELEASE["Guard Release"]
RESTORE["local_irq_restore(saved_flags)"]
CHECK_FLAGS["saved_flags != 0?"]
STI["sti (enable interrupts)"]
CLI_RESTORE["cli (keep disabled)"]
COMPLETE["Interrupts Restored"]

ACQUIRE --> SAVE_DISABLE
CHECK_FLAGS --> CLI_RESTORE
CHECK_FLAGS --> STI
CLI --> MASK
CLI_RESTORE --> COMPLETE
CRITICAL --> RELEASE
MASK --> RETURN_FLAGS
POP --> CLI
PUSHF --> POP
RELEASE --> RESTORE
RESTORE --> CHECK_FLAGS
RETURN_FLAGS --> CRITICAL
SAVE_DISABLE --> PUSHF
STI --> COMPLETE

Sources: src/arch/x86.rs(L7 - L20) 

Assembly Instructions Reference

The x86 implementation uses specific assembly instructions for interrupt control:

EFLAGS Register Structure

The implementation specifically targets bit 9 of the EFLAGS register:

flowchart TD
EFLAGS["EFLAGS Register (32/64-bit)"]
BIT9["Bit 9: Interrupt Flag (IF)"]
ENABLED["1 = Interrupts Enabled"]
DISABLED["0 = Interrupts Disabled"]
IF_BIT_CONST["IF_BIT = 1 << 9"]
MASK_OP["flags & IF_BIT"]
IF_STATE["Extract IF state"]

BIT9 --> DISABLED
BIT9 --> ENABLED
EFLAGS --> BIT9
IF_BIT_CONST --> BIT9
MASK_OP --> IF_STATE

Sources: src/arch/x86.rs(L3 - L4)  src/arch/x86.rs(L10) 

Integration with Guard System

The x86 interrupt control functions integrate directly with the RAII guard implementations. When guards are created in bare-metal environments (target_os = "none"), they call these architecture-specific functions to provide actual interrupt control functionality.

Function Usage by Guards:

• IrqSave guard calls local_irq_save_and_disable() on creation and local_irq_restore() on drop
• NoPreemptIrqSave guard uses the same interrupt control functions in addition to preemption control

The inline assembly ensures minimal overhead and atomic operation for critical section protection in kernel environments.

Sources: src/arch/x86.rs(L1 - L21) 

RISC-V Implementation

Relevant source files

• src/arch/riscv.rs

This document covers the RISC-V-specific implementation of interrupt control functionality within the kernel_guard crate. The RISC-V implementation provides low-level interrupt disable/restore operations by manipulating the sstatus Control and Status Register (CSR), specifically the Supervisor Interrupt Enable (SIE) bit.

For the overall architecture abstraction mechanism, see Architecture Abstraction Layer. For other architecture implementations, see x86/x86_64 Implementation, AArch64 Implementation, and LoongArch64 Implementation.

RISC-V CSR Architecture Context

The RISC-V implementation operates within the Supervisor mode privilege level, using the sstatus CSR to control interrupt delivery. The implementation focuses on atomic manipulation of the SIE bit to provide safe critical section entry and exit.

RISC-V Architecture Selection Flow

flowchart TD
cfg_if["cfg_if! macro evaluation"]
riscv_check["target_arch = riscv32 or riscv64?"]
riscv_mod["mod riscv;"]
other_arch["Other architecture modules"]
pub_use["pub use self::riscv::*;"]
local_irq_save["local_irq_save_and_disable()"]
local_irq_restore["local_irq_restore()"]
guard_acquire["BaseGuard::acquire()"]
guard_release["BaseGuard::release()"]
irq_save_guard["IrqSave guard"]
no_preempt_irq_save["NoPreemptIrqSave guard"]

cfg_if --> riscv_check
guard_acquire --> irq_save_guard
guard_acquire --> no_preempt_irq_save
guard_release --> irq_save_guard
guard_release --> no_preempt_irq_save
local_irq_restore --> guard_release
local_irq_save --> guard_acquire
pub_use --> local_irq_restore
pub_use --> local_irq_save
riscv_check --> other_arch
riscv_check --> riscv_mod
riscv_mod --> pub_use

Sources: src/arch/mod.rs(L1 - L50)  src/arch/riscv.rs(L1 - L19) 

CSR Manipulation Implementation

The RISC-V implementation consists of two core functions that provide atomic interrupt state management through direct CSR manipulation.

Core Function Mapping

flowchart TD
subgraph subGraph2["Hardware Registers"]
    sstatus_reg["sstatus CSR"]
    sie_bit["SIE bit (bit 1)"]
end
subgraph subGraph1["RISC-V Assembly"]
    csrrc_instr["csrrc instruction"]
    csrrs_instr["csrrs instruction"]
end
subgraph subGraph0["Code Functions"]
    save_disable["local_irq_save_and_disable()"]
    restore["local_irq_restore(flags)"]
end

csrrc_instr --> sstatus_reg
csrrs_instr --> sstatus_reg
restore --> csrrs_instr
save_disable --> csrrc_instr
sstatus_reg --> sie_bit

Sources: src/arch/riscv.rs(L6 - L18) 

Assembly Instruction Analysis

The implementation uses RISC-V CSR atomic read-modify-write instructions to ensure interrupt state changes are atomic and cannot be interrupted.

CSR Instruction Details

The SIE_BIT constant is defined as 1 << 1, targeting bit 1 of the sstatus register which controls Supervisor Interrupt Enable.

CSR Operation Flow

sequenceDiagram
    participant IrqSaveGuard as "IrqSave Guard"
    participant local_irq_save_and_disable as "local_irq_save_and_disable()"
    participant sstatusCSR as "sstatus CSR"
    participant local_irq_restore as "local_irq_restore()"

    IrqSaveGuard ->> local_irq_save_and_disable: acquire()
    local_irq_save_and_disable ->> sstatusCSR: csrrc flags, sstatus, SIE_BIT
    sstatusCSR -->> local_irq_save_and_disable: return old sstatus value
    local_irq_save_and_disable -->> IrqSaveGuard: return (flags & SIE_BIT)
    Note over IrqSaveGuard: Critical section execution
    IrqSaveGuard ->> local_irq_restore: release(flags)
    local_irq_restore ->> sstatusCSR: csrrs x0, sstatus, flags
    sstatusCSR -->> local_irq_restore: (discard result)

Sources: src/arch/riscv.rs(L7 - L11)  src/arch/riscv.rs(L15 - L17) 

Implementation Details

Interrupt Save and Disable

The local_irq_save_and_disable() function src/arch/riscv.rs(L7 - L12)  performs an atomic clear-and-read operation:

• Uses inline assembly with csrrc (CSR Read and Clear bits)
• Clears the SIE_BIT in the sstatus register
• Returns only the relevant bit state (flags & SIE_BIT) rather than the entire register
• Ensures the returned value is either 0 (interrupts were disabled) or SIE_BIT (interrupts were enabled)

Interrupt Restore

The local_irq_restore() function src/arch/riscv.rs(L15 - L18)  performs an atomic set operation:

• Uses inline assembly with csrrs (CSR Read and Set bits)
• Sets bits specified by the flags parameter in the sstatus register
• Uses x0 as the destination register to discard the read result
• Only modifies the interrupt state without returning any value

Register Usage and Safety

The implementation uses specific register constraints:

• out(reg) for capturing the old CSR value
• in(reg) for providing the restore flags
• const SIE_BIT for compile-time constant bit mask
• All operations are marked unsafe due to direct hardware manipulation

Sources: src/arch/riscv.rs(L1 - L19) 

AArch64 Implementation

Relevant source files

• src/arch/aarch64.rs

This document details the AArch64-specific implementation of interrupt control mechanisms within the kernel_guard crate. It covers the ARM64 architecture's DAIF register manipulation and the assembly instructions used to save and restore interrupt states for RAII guard implementations.

For information about the overall architecture abstraction system, see Architecture Abstraction Layer. For comparisons with other CPU architectures, see x86/x86_64 Implementation, RISC-V Implementation, and LoongArch64 Implementation.

DAIF Register and Interrupt Control

The AArch64 implementation centers around the DAIF (Debug, SError, IRQ, FIQ) system register, which controls various exception types. The kernel_guard crate specifically manipulates the IRQ (Interrupt Request) bit to implement critical sections.

DAIF Register Structure

flowchart TD
subgraph subGraph2["Assembly Instructions"]
    MRS["mrs (Move from System Register)Read DAIF value"]
    MSR_SET["msr daifset, #2Set I bit (disable IRQs)"]
    MSR_RESTORE["msr daif, registerRestore full DAIF"]
end
subgraph subGraph1["kernel_guard Operations"]
    SAVE["local_irq_save_and_disable()Read DAIF + Set I bit"]
    RESTORE["local_irq_restore(flags)Write saved DAIF"]
end
subgraph subGraph0["DAIF Register (64-bit)"]
    D["D (bit 9)Debug exceptions"]
    A["A (bit 8)SError interrupts"]
    I["I (bit 7)IRQ interrupts"]
    F["F (bit 6)FIQ interrupts"]
end

MRS --> A
MRS --> D
MRS --> F
MRS --> I
MSR_RESTORE --> A
MSR_RESTORE --> D
MSR_RESTORE --> F
MSR_RESTORE --> I
MSR_SET --> I
RESTORE --> MSR_RESTORE
SAVE --> MRS
SAVE --> MSR_SET

Sources: src/arch/aarch64.rs(L1 - L15) 

Core Implementation Functions

The AArch64 implementation provides two primary functions that form the foundation for all interrupt-disabling guards on this architecture.

Interrupt Save and Disable

The local_irq_save_and_disable function captures the current interrupt state and disables IRQs atomically:

The function uses two ARM64 instructions in sequence:

1. mrs {}, daif - Move the DAIF register value to a general-purpose register
2. msr daifset, #2 - Set bit 1 (which corresponds to the IRQ mask bit) in DAIF

Interrupt Restore

The local_irq_restore function restores the previously saved interrupt state:

This function directly writes the saved flags back to the DAIF register, restoring the complete interrupt state.

Sources: src/arch/aarch64.rs(L3 - L14) 

Integration with Guard System

The AArch64 implementation integrates with the broader kernel_guard architecture through the conditional compilation system and provides the low-level primitives for RAII guards.

flowchart TD
subgraph subGraph3["RAII Pattern"]
    ACQUIRE["BaseGuard::acquire()"]
    DROP["Drop implementation"]
end
subgraph subGraph2["Guard Implementations"]
    IRQ_GUARD["IrqSave guard"]
    COMBO_GUARD["NoPreemptIrqSave guard"]
end
subgraph subGraph1["AArch64 Module (src/arch/aarch64.rs)"]
    SAVE_FN["local_irq_save_and_disable()"]
    RESTORE_FN["local_irq_restore(flags)"]
end
subgraph subGraph0["Architecture Selection"]
    CFG_IF["cfg_if! macro"]
    AARCH64_CHECK["target_arch = 'aarch64'"]
end

AARCH64_CHECK --> RESTORE_FN
AARCH64_CHECK --> SAVE_FN
CFG_IF --> AARCH64_CHECK
COMBO_GUARD --> ACQUIRE
COMBO_GUARD --> DROP
IRQ_GUARD --> ACQUIRE
IRQ_GUARD --> DROP
RESTORE_FN --> COMBO_GUARD
RESTORE_FN --> IRQ_GUARD
SAVE_FN --> COMBO_GUARD
SAVE_FN --> IRQ_GUARD

Sources: src/arch/aarch64.rs(L1 - L15) 

Assembly Instruction Details

The AArch64 implementation relies on specific ARM64 assembly instructions for system register manipulation:

System Register Access Instructions

Bit Manipulation Strategy

flowchart TD
subgraph subGraph2["Critical Section State"]
    BEFORE["IRQs enabled (I=0)"]
    DURING["IRQs disabled (I=1)"]
    AFTER["IRQs restored"]
end
subgraph subGraph1["daifset #2 Operation"]
    IMM2["Immediate value #2"]
    SHIFT["Left shift by 6 positions"]
    RESULT["Sets bit 7 (IRQ mask)"]
end
subgraph subGraph0["DAIF Bit Positions"]
    BIT9["Bit 9: Debug"]
    BIT8["Bit 8: SError"]
    BIT7["Bit 7: IRQ"]
    BIT6["Bit 6: FIQ"]
end

BEFORE --> DURING
BIT7 --> DURING
DURING --> AFTER
IMM2 --> SHIFT
RESULT --> BIT7
SHIFT --> RESULT

The daifset #2 instruction specifically targets the IRQ bit by using immediate value 2, which when processed by the instruction becomes a mask for bit 7 of the DAIF register.

Sources: src/arch/aarch64.rs(L7 - L13) 

Safety and Inline Optimization

Both functions are marked with #[inline] for performance optimization and use unsafe blocks for assembly code execution:

• Inline annotation: Ensures the assembly instructions are inlined at call sites for minimal overhead
• Unsafe blocks: Required for all inline assembly operations in Rust
• Register constraints: Uses out(reg) and in(reg) to specify register allocation for the assembler

The implementation assumes that the DAIF register is accessible in the current execution context, which is typically true for kernel-level code running at EL1 (Exception Level 1) or higher privilege levels.

Sources: src/arch/aarch64.rs(L3 - L14) 

LoongArch64 Implementation

Relevant source files

• src/arch/loongarch64.rs

Purpose and Scope

This document covers the LoongArch64-specific implementation of interrupt control mechanisms within the kernel_guard crate. The LoongArch64 implementation provides platform-specific functions for saving, disabling, and restoring interrupt states using Control Status Register (CSR) manipulation.

For general architecture abstraction concepts, see Architecture Abstraction Layer. For other architecture implementations, see x86/x86_64 Implementation, RISC-V Implementation, and AArch64 Implementation.

Architecture Integration

The LoongArch64 implementation is conditionally compiled as part of the multi-architecture support system. It provides the same interface as other architectures but uses LoongArch64-specific Control Status Registers and the csrxchg instruction for atomic CSR exchange operations.

Architecture Selection Flow

flowchart TD
CFGIF["cfg_if! macro evaluation"]
LOONG_CHECK["target_arch = loongarch64?"]
LOONG_MOD["mod loongarch64"]
OTHER_ARCH["Other architecture modules"]
PUB_USE["pub use self::loongarch64::*"]
LOCAL_IRQ_SAVE["local_irq_save_and_disable()"]
LOCAL_IRQ_RESTORE["local_irq_restore()"]
IRQ_SAVE_GUARD["IrqSave guard"]
NO_PREEMPT_IRQ_SAVE["NoPreemptIrqSave guard"]

CFGIF --> LOONG_CHECK
IRQ_SAVE_GUARD --> NO_PREEMPT_IRQ_SAVE
LOCAL_IRQ_RESTORE --> IRQ_SAVE_GUARD
LOCAL_IRQ_SAVE --> IRQ_SAVE_GUARD
LOONG_CHECK --> LOONG_MOD
LOONG_CHECK --> OTHER_ARCH
LOONG_MOD --> PUB_USE
PUB_USE --> LOCAL_IRQ_RESTORE
PUB_USE --> LOCAL_IRQ_SAVE

Sources: src/arch/loongarch64.rs(L1 - L18) 

Interrupt Control Implementation

The LoongArch64 implementation centers around two core functions that manipulate the interrupt enable bit in Control Status Registers using the atomic csrxchg instruction.

Core Functions

CSR Manipulation Details

flowchart TD
subgraph local_irq_restore["local_irq_restore"]
    RESTORE_START["Function entryflags parameter"]
    CSRXCHG_RESTORE["csrxchg {}, {}, 0x0in(reg) flagsin(reg) IE_MASK"]
    RESTORE_END["Function return"]
end
subgraph local_irq_save_and_disable["local_irq_save_and_disable"]
    SAVE_START["Function entry"]
    FLAGS_INIT["flags: usize = 0"]
    CSRXCHG_SAVE["csrxchg {}, {}, 0x0inout(reg) flagsin(reg) IE_MASK"]
    MASK_RETURN["Return flags & IE_MASK"]
end
subgraph subGraph0["LoongArch64 CSR Operations"]
    IE_MASK["IE_MASK constant1 << 2 (bit 2)"]
    CSRXCHG["csrxchg instructionAtomic CSR exchange"]
end

CSRXCHG_RESTORE --> RESTORE_END
CSRXCHG_SAVE --> MASK_RETURN
FLAGS_INIT --> CSRXCHG_SAVE
IE_MASK --> CSRXCHG_RESTORE
IE_MASK --> CSRXCHG_SAVE
RESTORE_START --> CSRXCHG_RESTORE
SAVE_START --> FLAGS_INIT

Sources: src/arch/loongarch64.rs(L3 - L17) 

Control Status Register (CSR) Operations

The implementation uses CSR address 0x0 (likely CRMD - Current Mode) with the csrxchg instruction for atomic read-modify-write operations on the interrupt enable bit.

Interrupt Enable Bit Manipulation

The IE_MASK constant defines bit 2 as the interrupt enable bit:

flowchart TD
subgraph subGraph1["IE_MASK Constant"]
    MASK_VAL["1 << 2 = 0x4"]
    MASK_PURPOSE["Isolates IE bitfor CSR operations"]
end
subgraph subGraph0["CSR Bit Layout"]
    BIT0["Bit 0"]
    BIT1["Bit 1"]
    BIT2["Bit 2IE (Interrupt Enable)"]
    BIT3["Bit 3"]
    BITN["Bit N"]
end

BIT2 --> MASK_VAL
MASK_VAL --> MASK_PURPOSE

Sources: src/arch/loongarch64.rs(L3) 

Assembly Instruction Details

The csrxchg instruction performs atomic exchange operations:

• Save Operation: csrxchg {flags}, {IE_MASK}, 0x0 clears the IE bit and returns the old CSR value
• Restore Operation: csrxchg {flags}, {IE_MASK}, 0x0 sets the IE bit based on the flags parameter

The instruction syntax uses:

• inout(reg) flags for read-modify-write of the flags variable
• in(reg) IE_MASK for the bit mask input
• 0x0 as the CSR address

Sources: src/arch/loongarch64.rs(L9 - L16) 

Integration with Guard System

The LoongArch64 functions integrate seamlessly with the kernel_guard's RAII guard system through the architecture abstraction layer.

Guard Usage Flow

sequenceDiagram
    participant IrqSaveGuard as "IrqSave Guard"
    participant ArchitectureLayer as "Architecture Layer"
    participant LoongArch64Implementation as "LoongArch64 Implementation"
    participant LoongArch64CSR as "LoongArch64 CSR"

    Note over IrqSaveGuard: Guard creation
    IrqSaveGuard ->> ArchitectureLayer: BaseGuard::acquire()
    ArchitectureLayer ->> LoongArch64Implementation: local_irq_save_and_disable()
    LoongArch64Implementation ->> LoongArch64CSR: csrxchg (clear IE)
    LoongArch64CSR -->> LoongArch64Implementation: Previous CSR value
    LoongArch64Implementation -->> ArchitectureLayer: Masked IE state
    ArchitectureLayer -->> IrqSaveGuard: Saved flags
    Note over IrqSaveGuard: Critical section execution
    Note over IrqSaveGuard: Guard destruction
    IrqSaveGuard ->> ArchitectureLayer: BaseGuard::release(flags)
    ArchitectureLayer ->> LoongArch64Implementation: local_irq_restore(flags)
    LoongArch64Implementation ->> LoongArch64CSR: csrxchg (restore IE)
    LoongArch64CSR -->> LoongArch64Implementation: Updated CSR
    LoongArch64Implementation -->> ArchitectureLayer: Return
    ArchitectureLayer -->> IrqSaveGuard: Return

Sources: src/arch/loongarch64.rs(L6 - L17) 

Integration Guide

Relevant source files

• Cargo.toml
• README.md
• src/lib.rs

This page provides a practical guide for integrating the kernel_guard crate into your kernel or OS project. It covers dependency setup, feature configuration, and implementing the required interfaces to enable preemption control.

For detailed information about the available guard types and their behavior, see RAII Guards. For architecture-specific implementation details, see Multi-Architecture Support.

Integration Overview

The kernel_guard crate integration follows a two-phase approach: dependency configuration and interface implementation. The crate uses conditional compilation to provide different functionality levels based on target platform and enabled features.

Integration Flow Diagram

flowchart TD
START["Start Integration"]
CARGO["Add kernel_guard to Cargo.toml"]
FEATURE_CHOICE["Enable preempt feature?"]
IMPL_TRAIT["Implement KernelGuardIf trait"]
USE_GUARDS["Use IRQ-only guards"]
CRATE_INTERFACE["Use crate_interface::impl_interface"]
DEFINE_IMPL["Define enable_preempt() and disable_preempt()"]
FULL_GUARDS["Access all guard types"]
LIMITED_GUARDS["Access IrqSave and NoOp guards"]
USAGE["Use guards in critical sections"]
RUNTIME["Runtime protection active"]

CARGO --> FEATURE_CHOICE
CRATE_INTERFACE --> DEFINE_IMPL
DEFINE_IMPL --> FULL_GUARDS
FEATURE_CHOICE --> IMPL_TRAIT
FEATURE_CHOICE --> USE_GUARDS
FULL_GUARDS --> USAGE
IMPL_TRAIT --> CRATE_INTERFACE
LIMITED_GUARDS --> USAGE
START --> CARGO
USAGE --> RUNTIME
USE_GUARDS --> LIMITED_GUARDS

Sources: Cargo.toml(L14 - L16)  src/lib.rs(L58 - L66)  src/lib.rs(L83 - L111) 

Dependency Configuration

Add kernel_guard to your Cargo.toml dependencies section:

[dependencies]
kernel_guard = "0.1.2"

For preemptive systems that need both IRQ and preemption control:

[dependencies]
kernel_guard = { version = "0.1.2", features = ["preempt"] }

Supported Dependencies

Sources: Cargo.toml(L18 - L20) 

Interface Implementation Requirements

When the preempt feature is enabled, you must implement the KernelGuardIf trait to provide preemption control functionality.

KernelGuardIf Implementation Pattern

flowchart TD
subgraph subGraph2["Runtime Dispatch"]
    NOPREEMPT_ACQUIRE["NoPreempt::acquire()"]
    NOPREEMPT_RELEASE["NoPreempt::release()"]
    COMBINED_ACQUIRE["NoPreemptIrqSave::acquire()"]
    COMBINED_RELEASE["NoPreemptIrqSave::release()"]
end
subgraph subGraph1["kernel_guard Crate"]
    TRAIT_DEF["#[crate_interface::def_interface] trait KernelGuardIf"]
    CALL_SITES["crate_interface::call_interface! call sites"]
end
subgraph subGraph0["User Crate"]
    USER_STRUCT["struct KernelGuardIfImpl"]
    IMPL_MACRO["#[crate_interface::impl_interface]"]
    ENABLE_FN["fn enable_preempt()"]
    DISABLE_FN["fn disable_preempt()"]
end

CALL_SITES --> COMBINED_ACQUIRE
CALL_SITES --> COMBINED_RELEASE
CALL_SITES --> NOPREEMPT_ACQUIRE
CALL_SITES --> NOPREEMPT_RELEASE
DISABLE_FN --> CALL_SITES
ENABLE_FN --> CALL_SITES
IMPL_MACRO --> DISABLE_FN
IMPL_MACRO --> ENABLE_FN
TRAIT_DEF --> CALL_SITES
USER_STRUCT --> IMPL_MACRO

Sources: src/lib.rs(L59 - L66)  src/lib.rs(L153 - L159)  src/lib.rs(L167 - L177) 

Implementation Template

The following template shows the required implementation structure:

#![allow(unused)]
fn main() {
use kernel_guard::KernelGuardIf;

struct KernelGuardIfImpl;

#[crate_interface::impl_interface]
impl KernelGuardIf for KernelGuardIfImpl {
    fn enable_preempt() {
        // Platform-specific preemption enable code
    }
    
    fn disable_preempt() {
        // Platform-specific preemption disable code
    }
}
}

Sources: src/lib.rs(L30 - L43)  README.md(L36 - L49) 

Target Platform Considerations

The crate behavior varies based on the target platform:

Platform-Specific Guard Availability

*Requires preempt feature and KernelGuardIf implementation

Sources: src/lib.rs(L83 - L111) 

Conditional Compilation Logic

flowchart TD
COMPILE_START["Compilation begins"]
TARGET_CHECK["target_os == 'none' || doc?"]
REAL_IMPL["Real guard implementations"]
ALIAS_IMPL["NoOp type aliases"]
PREEMPT_CHECK["preempt feature enabled?"]
FULL_PREEMPT["Full preemption control"]
IRQ_ONLY["IRQ control only"]
NOOP_GUARDS["All guards = NoOp"]
CALL_INTERFACE["crate_interface::call_interface!"]
ARCH_IRQ["arch::local_irq_* functions"]
USER_IMPL["User KernelGuardIf implementation"]
PLATFORM_CODE["Platform-specific IRQ code"]

ALIAS_IMPL --> NOOP_GUARDS
ARCH_IRQ --> PLATFORM_CODE
CALL_INTERFACE --> USER_IMPL
COMPILE_START --> TARGET_CHECK
FULL_PREEMPT --> CALL_INTERFACE
IRQ_ONLY --> ARCH_IRQ
PREEMPT_CHECK --> FULL_PREEMPT
PREEMPT_CHECK --> IRQ_ONLY
REAL_IMPL --> PREEMPT_CHECK
TARGET_CHECK --> ALIAS_IMPL
TARGET_CHECK --> REAL_IMPL

Sources: src/lib.rs(L83 - L111)  src/lib.rs(L130 - L238) 

Usage Patterns

Basic Guard Usage

All guards follow the RAII pattern where the critical section begins at guard creation and ends when the guard is dropped:

// IRQ protection only
let _guard = IrqSave::new();
// Critical section protected from interrupts

// Preemption protection (requires preempt feature + KernelGuardIf)
let _guard = NoPreempt::new();
// Critical section protected from preemption

// Combined protection
let _guard = NoPreemptIrqSave::new();
// Critical section protected from both interrupts and preemption

Integration Verification

To verify your integration is working correctly:

1. Compilation Test: Ensure your project compiles with the desired feature set
2. Runtime Test: Verify that critical sections actually disable the expected mechanisms
3. Documentation Test: Use cargo doc to check that all guard types are available

Sources: src/lib.rs(L181 - L237)  README.md(L50 - L58) 

Feature Configuration

Relevant source files

• Cargo.toml
• src/lib.rs

This document explains the feature-based configuration system in the kernel_guard crate, specifically focusing on the preempt feature and its impact on guard availability and functionality. For information about implementing the required traits when using features, see Implementing KernelGuardIf.

Overview

The kernel_guard crate uses Cargo features to provide conditional functionality that adapts to different system requirements. The primary feature is preempt, which enables kernel preemption control capabilities in guard implementations. This feature system allows the crate to be used in both simple interrupt-only scenarios and more complex preemptive kernel environments.

Feature Definitions

The crate defines its features in the Cargo manifest with a minimal configuration approach:

Sources: Cargo.toml(L14 - L16) 

Preempt Feature Behavior

Feature Impact on Guard Implementations

The preempt feature primarily affects two guard types: NoPreempt and NoPreemptIrqSave. When this feature is enabled, these guards will attempt to disable and re-enable kernel preemption around critical sections.

Compilation-Time Feature Resolution

flowchart TD
COMPILE["Compilation Start"]
FEATURE_CHECK["preempt featureenabled?"]
PREEMPT_ENABLED["Preemption ControlActive"]
PREEMPT_DISABLED["Preemption ControlNo-Op"]
NOPRE_IMPL["NoPreempt::acquire()calls KernelGuardIf::disable_preempt"]
NOPRE_REL["NoPreempt::release()calls KernelGuardIf::enable_preempt"]
NOPRE_NOOP["NoPreempt::acquire()no operation"]
NOPRE_NOOP_REL["NoPreempt::release()no operation"]
COMBO_IMPL["NoPreemptIrqSave::acquire()calls disable_preempt + IRQ disable"]
COMBO_REL["NoPreemptIrqSave::release()IRQ restore + enable_preempt"]
COMBO_IRQ["NoPreemptIrqSave::acquire()IRQ disable only"]
COMBO_IRQ_REL["NoPreemptIrqSave::release()IRQ restore only"]

COMPILE --> FEATURE_CHECK
FEATURE_CHECK --> PREEMPT_DISABLED
FEATURE_CHECK --> PREEMPT_ENABLED
PREEMPT_DISABLED --> COMBO_IRQ
PREEMPT_DISABLED --> COMBO_IRQ_REL
PREEMPT_DISABLED --> NOPRE_NOOP
PREEMPT_DISABLED --> NOPRE_NOOP_REL
PREEMPT_ENABLED --> COMBO_IMPL
PREEMPT_ENABLED --> COMBO_REL
PREEMPT_ENABLED --> NOPRE_IMPL
PREEMPT_ENABLED --> NOPRE_REL

Sources: src/lib.rs(L149 - L161)  src/lib.rs(L163 - L179) 

Guard Behavior Matrix

The following table shows how each guard type behaves based on feature configuration:

Implementation Details

NoPreempt Guard Feature Integration

Sources: src/lib.rs(L149 - L161)  src/lib.rs(L200 - L217) 

NoPreemptIrqSave Combined Behavior

The NoPreemptIrqSave guard demonstrates the most complex feature-dependent behavior, combining both IRQ control and optional preemption control:

sequenceDiagram
    participant UserCode as "User Code"
    participant NoPreemptIrqSave as "NoPreemptIrqSave"
    participant KernelGuardIf as "KernelGuardIf"
    participant archlocal_irq_ as "arch::local_irq_*"

    UserCode ->> NoPreemptIrqSave: new()
    NoPreemptIrqSave ->> NoPreemptIrqSave: acquire()
    alt preempt feature enabled
        NoPreemptIrqSave ->> KernelGuardIf: disable_preempt()
        Note over KernelGuardIf: Kernel preemption disabled
    else preempt feature disabled
        Note over NoPreemptIrqSave: Skip preemption control
    end
    NoPreemptIrqSave ->> archlocal_irq_: local_irq_save_and_disable()
    archlocal_irq_ -->> NoPreemptIrqSave: irq_state
    Note over NoPreemptIrqSave,archlocal_irq_: Critical section active
    UserCode ->> NoPreemptIrqSave: drop()
    NoPreemptIrqSave ->> NoPreemptIrqSave: release(irq_state)
    NoPreemptIrqSave ->> archlocal_irq_: local_irq_restore(irq_state)
    alt preempt feature enabled
        NoPreemptIrqSave ->> KernelGuardIf: enable_preempt()
        Note over KernelGuardIf: Kernel preemption restored
    else preempt feature disabled
        Note over NoPreemptIrqSave: Skip preemption control
    end

Sources: src/lib.rs(L163 - L179)  src/lib.rs(L220 - L237) 

Integration Requirements

Feature Dependencies

When the preempt feature is enabled, user code must provide an implementation of the KernelGuardIf trait using the crate_interface mechanism. The relationship between feature activation and implementation requirements is:

Runtime Interface Resolution

The crate uses crate_interface::call_interface! macros to dynamically dispatch to user-provided implementations at runtime. This occurs only when the preempt feature is active:

flowchart TD
FEATURE_ENABLED["preempt featureenabled"]
MACRO_CALL["crate_interface::call_interface!(KernelGuardIf::disable_preempt)"]
RUNTIME_DISPATCH["Runtime InterfaceResolution"]
USER_IMPL["User Implementationof KernelGuardIf"]
ACTUAL_DISABLE["Actual PreemptionDisable Operation"]
FEATURE_DISABLED["preempt featuredisabled"]
COMPILE_SKIP["Conditional CompilationSkips Call"]
NO_OPERATION["No PreemptionControl"]

COMPILE_SKIP --> NO_OPERATION
FEATURE_DISABLED --> COMPILE_SKIP
FEATURE_ENABLED --> MACRO_CALL
MACRO_CALL --> RUNTIME_DISPATCH
RUNTIME_DISPATCH --> USER_IMPL
USER_IMPL --> ACTUAL_DISABLE

Sources: src/lib.rs(L153 - L154)  src/lib.rs(L158 - L159)  src/lib.rs(L167 - L168)  src/lib.rs(L176 - L177) 

Configuration Examples

Basic Usage Without Preemption

[dependencies]
kernel_guard = "0.1"

In this configuration, NoPreempt and NoPreemptIrqSave guards will only control IRQs, making them functionally equivalent to IrqSave for the IRQ portion.

Full Preemptive Configuration

[dependencies]
kernel_guard = { version = "0.1", features = ["preempt"] }

This configuration enables full preemption control capabilities, requiring the user to implement KernelGuardIf.

Sources: Cargo.toml(L14 - L16)  src/lib.rs(L21 - L26) 

Implementing KernelGuardIf

Relevant source files

• README.md
• src/lib.rs

This page provides a comprehensive guide for implementing the KernelGuardIf trait to enable preemption control in the kernel_guard crate. This implementation is required when using guards that need to disable kernel preemption, such as NoPreempt and NoPreemptIrqSave. For information about feature configuration, see Feature Configuration. For details about the core guard types, see RAII Guards.

When KernelGuardIf Implementation is Required

The KernelGuardIf trait must be implemented by users when the preempt feature is enabled and they want to use preemption-aware guards. Without this implementation, preemption control operations become no-ops.

Sources: src/lib.rs(L80 - L111)  src/lib.rs(L149 - L179) 

Trait Definition and Interface

The KernelGuardIf trait defines the interface for kernel preemption control:

flowchart TD
subgraph subGraph2["Guard Usage"]
    ACQUIRE["BaseGuard::acquire()"]
    RELEASE["BaseGuard::release()"]
    CALL["crate_interface::call_interface!"]
end
subgraph subGraph1["User Implementation"]
    IMPL["User struct implementing KernelGuardIf#[crate_interface::impl_interface]"]
    ENABLE_IMPL["enable_preempt() implementation"]
    DISABLE_IMPL["disable_preempt() implementation"]
end
subgraph subGraph0["KernelGuardIf Trait Interface"]
    TRAIT["KernelGuardIf trait#[crate_interface::def_interface]"]
    ENABLE["fn enable_preempt()"]
    DISABLE["fn disable_preempt()"]
end

ACQUIRE --> CALL
CALL --> DISABLE_IMPL
CALL --> ENABLE_IMPL
IMPL --> DISABLE_IMPL
IMPL --> ENABLE_IMPL
RELEASE --> CALL
TRAIT --> DISABLE
TRAIT --> ENABLE

The trait is defined using the crate_interface::def_interface attribute, which creates a stable interface that can be implemented by external crates. The methods are called through the crate_interface::call_interface! macro.

Sources: src/lib.rs(L58 - L66) 

Implementation Steps

Step 1: Define Implementation Struct

Create a struct that will implement the KernelGuardIf trait:

struct KernelGuardIfImpl;

The struct typically doesn't need any fields, as preemption control is usually a global system operation.

Step 2: Implement the Trait

Use the #[crate_interface::impl_interface] attribute to implement the trait:

flowchart TD
subgraph subGraph0["Implementation Pattern"]
    ATTR["#[crate_interface::impl_interface]"]
    IMPL_BLOCK["impl KernelGuardIf for UserStruct"]
    ENABLE_FN["fn enable_preempt()"]
    DISABLE_FN["fn disable_preempt()"]
end

ATTR --> IMPL_BLOCK
IMPL_BLOCK --> DISABLE_FN
IMPL_BLOCK --> ENABLE_FN

The #[crate_interface::impl_interface] attribute registers the implementation with the crate_interface system, making it available for dynamic dispatch.

Sources: src/lib.rs(L35 - L43)  README.md(L41 - L49) 

Step 3: Implement Method Bodies

Provide platform-specific implementations for enabling and disabling preemption:

• enable_preempt(): Should re-enable kernel preemption
• disable_preempt(): Should disable kernel preemption

These implementations are highly platform-specific and depend on the kernel or operating system being used.

Interface Mechanism and Call Flow

The crate_interface mechanism provides runtime dispatch to user implementations:

sequenceDiagram
    participant Guard as Guard
    participant call_interface as call_interface!
    participant UserImplementation as User Implementation

    Note over Guard: Guard creation (e.g., NoPreempt::new())
    Guard ->> call_interface: BaseGuard::acquire()
    call_interface ->> UserImplementation: KernelGuardIf::disable_preempt()
    UserImplementation -->> call_interface: Platform-specific disable
    call_interface -->> Guard: Return
    Note over Guard: Critical section execution
    Note over Guard: Guard drop
    Guard ->> call_interface: BaseGuard::release()
    call_interface ->> UserImplementation: KernelGuardIf::enable_preempt()
    UserImplementation -->> call_interface: Platform-specific enable
    call_interface -->> Guard: Return

The guards call the interface methods conditionally based on feature flags:

• NoPreempt calls the interface in both acquire() and release() methods
• NoPreemptIrqSave calls the interface alongside IRQ control operations
• Calls are wrapped in #[cfg(feature = "preempt")] conditionals

Sources: src/lib.rs(L153 - L154)  src/lib.rs(L158 - L159)  src/lib.rs(L167 - L168)  src/lib.rs(L176 - L177) 

Complete Implementation Example

Here's a complete example showing the implementation pattern:

use kernel_guard::{KernelGuardIf, NoPreempt};

struct KernelGuardIfImpl;

#[crate_interface::impl_interface]
impl KernelGuardIf for KernelGuardIfImpl {
    fn enable_preempt() {
        // Platform-specific implementation
        // Example: atomic decrement of preemption counter
        // or direct scheduler manipulation
    }
    
    fn disable_preempt() {
        // Platform-specific implementation  
        // Example: atomic increment of preemption counter
        // or direct scheduler manipulation
    }
}

// Usage after implementation
let guard = NoPreempt::new();
// Critical section with preemption disabled
drop(guard); // Preemption re-enabled

Sources: src/lib.rs(L30 - L52)  README.md(L36 - L58) 

Guard Behavior with KernelGuardIf

The following diagram shows how different guards utilize the KernelGuardIf implementation:

flowchart TD
subgraph subGraph1["NoPreemptIrqSave Guard"]
    NPIS_IRQ_DISABLE["arch::local_irq_save_and_disable()"]
    NPIS_ENABLE["call_interface!(enable_preempt)"]
    subgraph subGraph0["NoPreempt Guard"]
        NPIS_NEW["NoPreemptIrqSave::new()"]
        NPIS_ACQUIRE["BaseGuard::acquire()"]
        NPIS_DISABLE["call_interface!(disable_preempt)"]
        NPIS_DROP["Drop::drop()"]
        NPIS_RELEASE["BaseGuard::release()"]
        NPIS_IRQ_RESTORE["arch::local_irq_restore()"]
        NP_NEW["NoPreempt::new()"]
        NP_ACQUIRE["BaseGuard::acquire()"]
        NP_DISABLE["call_interface!(disable_preempt)"]
        NP_DROP["Drop::drop()"]
        NP_RELEASE["BaseGuard::release()"]
        NP_ENABLE["call_interface!(enable_preempt)"]
    end
end

NPIS_ACQUIRE --> NPIS_DISABLE
NPIS_DISABLE --> NPIS_IRQ_DISABLE
NPIS_DROP --> NPIS_RELEASE
NPIS_IRQ_RESTORE --> NPIS_ENABLE
NPIS_NEW --> NPIS_ACQUIRE
NPIS_RELEASE --> NPIS_IRQ_RESTORE
NP_ACQUIRE --> NP_DISABLE
NP_DROP --> NP_RELEASE
NP_NEW --> NP_ACQUIRE
NP_RELEASE --> NP_ENABLE

Note the ordering in NoPreemptIrqSave: preemption is disabled first, then IRQs are disabled. On release, IRQs are restored first, then preemption is re-enabled.

Sources: src/lib.rs(L149 - L179) 

Best Practices and Considerations

Implementation Guidelines

1. Thread Safety: Ensure implementations are thread-safe, as they may be called from multiple contexts
2. Performance: Keep implementations lightweight, as they're called frequently in critical sections
3. Error Handling: Implementations should not panic, as this would break RAII guarantees
4. Platform Specific: Implementations must match the target platform's preemption semantics

Common Implementation Patterns

Feature Flag Considerations

When the preempt feature is disabled, all calls to KernelGuardIf methods are compiled out. This means:

• No runtime overhead when preemption control is not needed
• Guards still provide IRQ control functionality
• Implementation is not required when feature is disabled

Sources: src/lib.rs(L23 - L26)  src/lib.rs(L153)  src/lib.rs(L158)  src/lib.rs(L167)  src/lib.rs(L176) 

Development

Relevant source files

• .github/workflows/ci.yml
• .gitignore
• Cargo.toml

This document provides comprehensive information for contributors and maintainers about the development workflow, testing procedures, and CI/CD pipeline for the kernel_guard crate. It covers the automated build system, multi-architecture testing strategy, documentation generation process, and local development environment setup.

For information about integrating kernel_guard into other projects, see Integration Guide. For details about the core architecture and implementation, see Core Architecture.

Development Workflow Overview

The kernel_guard project follows a streamlined development workflow centered around GitHub Actions for continuous integration and automated documentation deployment.

Development Process Flow

flowchart TD
DEV["Developer"]
CLONE["git clone"]
LOCAL["Local Development"]
FORMAT["cargo fmt"]
CLIPPY["cargo clippy"]
BUILD["cargo build"]
TEST["cargo test"]
COMMIT["git commit"]
PUSH["git push / PR"]
TRIGGER["GitHub Actions Trigger"]
CI_JOB["ci job"]
DOC_JOB["doc job"]
MATRIX["Multi-target Matrix"]
FMT_CHECK["cargo fmt --check"]
CLIPPY_CHECK["cargo clippy"]
BUILD_CHECK["cargo build"]
TEST_CHECK["cargo test"]
DOC_BUILD["cargo doc"]
PAGES["GitHub Pages Deploy"]
PASS["All Checks Pass?"]
MERGE["Merge/Deploy"]
FAIL["Build Failure"]

BUILD --> TEST
BUILD_CHECK --> PASS
CI_JOB --> MATRIX
CLIPPY --> BUILD
CLIPPY_CHECK --> PASS
CLONE --> LOCAL
COMMIT --> PUSH
DEV --> CLONE
DOC_BUILD --> PAGES
DOC_JOB --> DOC_BUILD
FAIL --> LOCAL
FMT_CHECK --> PASS
FORMAT --> CLIPPY
LOCAL --> FORMAT
MATRIX --> BUILD_CHECK
MATRIX --> CLIPPY_CHECK
MATRIX --> FMT_CHECK
MATRIX --> TEST_CHECK
PASS --> FAIL
PASS --> MERGE
PUSH --> TRIGGER
TEST --> COMMIT
TEST_CHECK --> PASS
TRIGGER --> CI_JOB
TRIGGER --> DOC_JOB

Sources: .github/workflows/ci.yml(L1 - L56)  Cargo.toml(L1 - L21) 

CI/CD Pipeline Architecture

The continuous integration system is defined in .github/workflows/ci.yml and consists of two primary jobs: ci and doc, each serving distinct purposes in the development pipeline.

CI Job Matrix Configuration

flowchart TD
subgraph subGraph3["Quality Gates"]
    FORMAT["cargo fmt --all --check"]
    CLIPPY["cargo clippy --target TARGET --all-features"]
    BUILD["cargo build --target TARGET --all-features"]
    UNITTEST["cargo test (Linux only)"]
end
subgraph subGraph2["Target Matrix"]
    T1["x86_64-unknown-linux-gnu"]
    T2["x86_64-unknown-none"]
    T3["riscv64gc-unknown-none-elf"]
    T4["aarch64-unknown-none-softfloat"]
    T5["loongarch64-unknown-none-softfloat"]
end
subgraph subGraph1["Matrix Configuration"]
    TOOLCHAIN["rust-toolchain: nightly"]
    TARGETS["Target Architectures"]
end
subgraph subGraph0["CI Pipeline"]
    TRIGGER["Push/Pull Request"]
    CI["ci job"]
    STRATEGY["fail-fast: false"]
    MATRIX["Matrix Strategy"]
end

BUILD --> UNITTEST
CI --> STRATEGY
CLIPPY --> BUILD
FORMAT --> CLIPPY
MATRIX --> TARGETS
MATRIX --> TOOLCHAIN
STRATEGY --> MATRIX
T1 --> FORMAT
T2 --> FORMAT
T3 --> FORMAT
T4 --> FORMAT
T5 --> FORMAT
TARGETS --> T1
TARGETS --> T2
TARGETS --> T3
TARGETS --> T4
TARGETS --> T5
TRIGGER --> CI

Sources: .github/workflows/ci.yml(L6 - L30) 

Build and Test Matrix

The CI system uses a matrix strategy to test across multiple target architectures simultaneously:

The conditional test execution is controlled by the matrix condition at .github/workflows/ci.yml(L29) : if: ${{ matrix.targets == 'x86_64-unknown-linux-gnu' }}.

Sources: .github/workflows/ci.yml(L11 - L12)  .github/workflows/ci.yml(L28 - L30) 

Toolchain and Dependencies

Rust Toolchain Requirements

The project requires Rust nightly toolchain with specific components:

• Toolchain: nightly .github/workflows/ci.yml(L17) 
• Components: rust-src, clippy, rustfmt .github/workflows/ci.yml(L18) 
• Targets: All supported architectures .github/workflows/ci.yml(L19) 

Crate Dependencies

The project maintains minimal dependencies as defined in Cargo.toml(L18 - L20) :

Sources: Cargo.toml(L18 - L20)  .github/workflows/ci.yml(L15 - L19) 

Quality Assurance Process

Code Quality Checks

The CI pipeline enforces code quality through multiple automated checks:

flowchart TD
subgraph subGraph3["Build Verification"]
    MULTI_TARGET["All target architectures"]
    ALL_FEAT["All feature combinations"]
end
subgraph subGraph2["Format Enforcement"]
    FAIL_FMT["Formatting violations fail CI"]
end
subgraph subGraph1["Clippy Configuration"]
    FEATURES["--all-features"]
    ALLOW["-A clippy::new_without_default"]
end
subgraph subGraph0["Quality Gates"]
    FMT["cargo fmt --all --check"]
    CLIPPY["cargo clippy"]
    BUILD["cargo build"]
    TEST["cargo test"]
end

BUILD --> ALL_FEAT
BUILD --> MULTI_TARGET
BUILD --> TEST
CLIPPY --> ALLOW
CLIPPY --> BUILD
CLIPPY --> FEATURES
FMT --> CLIPPY
FMT --> FAIL_FMT

Sources: .github/workflows/ci.yml(L22 - L27) 

Testing Strategy

Unit testing is architecture-specific and only executed on the Linux target:

• Test Execution: .github/workflows/ci.yml(L28 - L30) 
• Test Command: cargo test --target x86_64-unknown-linux-gnu -- --nocapture
• Rationale: Bare metal targets cannot execute standard unit tests

Sources: .github/workflows/ci.yml(L28 - L30) 

Documentation Pipeline

Automated Documentation Generation

The doc job handles documentation building and deployment:

flowchart TD
subgraph subGraph0["Documentation Flags"]
    RUSTDOC_FLAGS["RUSTDOCFLAGS environment"]
    BROKEN_LINKS["-D rustdoc::broken_intra_doc_links"]
    MISSING_DOCS["-D missing-docs"]
end
DOC_TRIGGER["Push to main branch"]
DOC_JOB["doc job"]
DOC_BUILD["cargo doc --no-deps --all-features"]
INDEX_GEN["Generate index.html redirect"]
DEPLOY_CHECK["Is main branch?"]
PAGES_DEPLOY["GitHub Pages Deploy"]
CONTINUE_ERROR["continue-on-error"]
BRANCH["gh-pages branch"]
FOLDER["target/doc folder"]

DEPLOY_CHECK --> CONTINUE_ERROR
DEPLOY_CHECK --> PAGES_DEPLOY
DOC_BUILD --> INDEX_GEN
DOC_JOB --> RUSTDOC_FLAGS
DOC_TRIGGER --> DOC_JOB
INDEX_GEN --> DEPLOY_CHECK
PAGES_DEPLOY --> BRANCH
PAGES_DEPLOY --> FOLDER
RUSTDOC_FLAGS --> BROKEN_LINKS
RUSTDOC_FLAGS --> DOC_BUILD
RUSTDOC_FLAGS --> MISSING_DOCS

Sources: .github/workflows/ci.yml(L32 - L56)  .github/workflows/ci.yml(L40) 

Documentation Configuration

The documentation system includes several important configurations:

• Strict Documentation: -D missing-docs flag requires all public items to be documented
• Link Validation: -D rustdoc::broken_intra_doc_links prevents broken documentation links
• Automatic Indexing: Dynamic index.html generation using cargo tree output .github/workflows/ci.yml(L48) 

Sources: .github/workflows/ci.yml(L40)  .github/workflows/ci.yml(L47 - L48) 

Development Environment Setup

Local Development Requirements

For local development, ensure your environment excludes build artifacts and temporary files as specified in .gitignore(L1 - L4) :

/target
/.vscode
.DS_Store
Cargo.lock

Feature Development

The crate supports feature-based development through Cargo.toml(L14 - L16) :

• Default Features: None (default = [])
• Optional Features: preempt for preemption control functionality

Local Testing Commands

For effective local development, use these commands that mirror the CI pipeline:

# Format check
cargo fmt --all -- --check

# Linting
cargo clippy --all-features -- -A clippy::new_without_default

# Multi-target builds
cargo build --target x86_64-unknown-none --all-features
cargo build --target riscv64gc-unknown-none-elf --all-features

# Unit testing (Linux only)
cargo test --target x86_64-unknown-linux-gnu -- --nocapture

# Documentation generation
cargo doc --no-deps --all-features

Sources: .github/workflows/ci.yml(L22 - L30)  .gitignore(L1 - L4)  Cargo.toml(L14 - L16) 

Build System and CI

Relevant source files

• .github/workflows/ci.yml

This document covers the automated build system and continuous integration (CI) pipeline for the kernel_guard crate. The CI system is implemented using GitHub Actions and provides multi-architecture testing, code quality enforcement, and automated documentation deployment.

For information about setting up a local development environment, see Development Environment. For details about the specific architectures supported, see Multi-Architecture Support.

CI Pipeline Overview

The kernel_guard project uses GitHub Actions for continuous integration, defined in a single workflow file that handles both build/test operations and documentation deployment. The pipeline is triggered on all push and pull request events.

CI Pipeline Structure

flowchart TD
TRIGGER["on: [push, pull_request]"]
JOBS["GitHub Actions Jobs"]
CI_JOB["ci job"]
DOC_JOB["doc job"]
MATRIX["strategy.matrix"]
CI_STEPS["CI Steps"]
DOC_PERMISSIONS["permissions: contents: write"]
DOC_STEPS["Documentation Steps"]
TOOLCHAIN["rust-toolchain: [nightly]"]
TARGETS["targets: [5 architectures]"]
CHECKOUT["actions/checkout@v4"]
TOOLCHAIN_SETUP["dtolnay/rust-toolchain@nightly"]
FORMAT_CHECK["cargo fmt --all -- --check"]
CLIPPY_CHECK["cargo clippy"]
BUILD_STEP["cargo build"]
TEST_STEP["cargo test"]
DOC_BUILD["cargo doc --no-deps --all-features"]
PAGES_DEPLOY["JamesIves/github-pages-deploy-action@v4"]

CI_JOB --> CI_STEPS
CI_JOB --> MATRIX
CI_STEPS --> BUILD_STEP
CI_STEPS --> CHECKOUT
CI_STEPS --> CLIPPY_CHECK
CI_STEPS --> FORMAT_CHECK
CI_STEPS --> TEST_STEP
CI_STEPS --> TOOLCHAIN_SETUP
DOC_JOB --> DOC_PERMISSIONS
DOC_JOB --> DOC_STEPS
DOC_STEPS --> DOC_BUILD
DOC_STEPS --> PAGES_DEPLOY
JOBS --> CI_JOB
JOBS --> DOC_JOB
MATRIX --> TARGETS
MATRIX --> TOOLCHAIN
TRIGGER --> JOBS

Sources: .github/workflows/ci.yml(L1 - L56) 

CI Job Configuration

The primary ci job runs on ubuntu-latest and uses a matrix strategy to test multiple configurations simultaneously. The job is configured with fail-fast: false to ensure all matrix combinations are tested even if some fail.

Matrix Strategy

The build matrix tests against multiple target architectures using the nightly Rust toolchain:

Matrix Configuration Flow

flowchart TD
MATRIX_START["strategy.matrix"]
TOOLCHAIN_CONFIG["rust-toolchain: nightly"]
TARGET_CONFIG["targets: 5 architectures"]
NIGHTLY["nightly toolchain"]
X86_LINUX["x86_64-unknown-linux-gnu"]
X86_NONE["x86_64-unknown-none"]
RISCV["riscv64gc-unknown-none-elf"]
AARCH64["aarch64-unknown-none-softfloat"]
LOONG["loongarch64-unknown-none-softfloat"]
COMPONENTS["components: rust-src, clippy, rustfmt"]
TEST_ENABLED["Unit tests enabled"]
BUILD_ONLY["Build only"]

AARCH64 --> BUILD_ONLY
LOONG --> BUILD_ONLY
MATRIX_START --> TARGET_CONFIG
MATRIX_START --> TOOLCHAIN_CONFIG
NIGHTLY --> COMPONENTS
RISCV --> BUILD_ONLY
TARGET_CONFIG --> AARCH64
TARGET_CONFIG --> LOONG
TARGET_CONFIG --> RISCV
TARGET_CONFIG --> X86_LINUX
TARGET_CONFIG --> X86_NONE
TOOLCHAIN_CONFIG --> NIGHTLY
X86_LINUX --> TEST_ENABLED
X86_NONE --> BUILD_ONLY

Sources: .github/workflows/ci.yml(L8 - L12)  .github/workflows/ci.yml(L16 - L19) 

Quality Assurance Steps

The CI job enforces code quality through a series of automated checks:

Quality Assurance Workflow

flowchart TD
SETUP["Rust Toolchain Setup"]
VERSION_CHECK["rustc --version --verbose"]
FORMAT_CHECK["cargo fmt --all -- --check"]
CLIPPY_CHECK["cargo clippy --target TARGET --all-features"]
BUILD_STEP["cargo build --target TARGET --all-features"]
TEST_DECISION["TARGET == x86_64-unknown-linux-gnu?"]
UNIT_TEST["cargo test --target TARGET -- --nocapture"]
COMPLETE["Job Complete"]
CLIPPY_ALLOW["-A clippy::new_without_default"]

BUILD_STEP --> TEST_DECISION
CLIPPY_CHECK --> BUILD_STEP
CLIPPY_CHECK --> CLIPPY_ALLOW
FORMAT_CHECK --> CLIPPY_CHECK
SETUP --> VERSION_CHECK
TEST_DECISION --> COMPLETE
TEST_DECISION --> UNIT_TEST
UNIT_TEST --> COMPLETE
VERSION_CHECK --> FORMAT_CHECK

The clippy step includes a specific allowance for the new_without_default lint, configured via the -A clippy::new_without_default flag.

Sources: .github/workflows/ci.yml(L20 - L30) 

Documentation Job and GitHub Pages

The doc job handles automated documentation generation and deployment to GitHub Pages. This job requires write permissions to the repository contents for deployment.

Documentation Build Process

The documentation job uses specific environment variables and build flags to ensure high-quality documentation:

RUSTDOCFLAGS: -D rustdoc::broken_intra_doc_links -D missing-docs

Documentation Deployment Flow

flowchart TD
DOC_TRIGGER["doc job trigger"]
PERMISSIONS_CHECK["permissions.contents: write"]
ENV_SETUP["RUSTDOCFLAGS environment"]
BRANCH_CHECK["default-branch variable"]
DOC_BUILD["cargo doc --no-deps --all-features"]
INDEX_GEN["Generate index.html redirect"]
BRANCH_CONDITION["github.ref == default-branch?"]
DEPLOY_PAGES["JamesIves/github-pages-deploy-action@v4"]
SKIP_DEPLOY["Skip deployment"]
PAGES_CONFIG["single-commit: truebranch: gh-pagesfolder: target/doc"]
STRICT_DOCS["Broken links fail buildMissing docs fail build"]

BRANCH_CHECK --> DOC_BUILD
BRANCH_CONDITION --> DEPLOY_PAGES
BRANCH_CONDITION --> SKIP_DEPLOY
DEPLOY_PAGES --> PAGES_CONFIG
DOC_BUILD --> INDEX_GEN
DOC_TRIGGER --> PERMISSIONS_CHECK
ENV_SETUP --> BRANCH_CHECK
ENV_SETUP --> STRICT_DOCS
INDEX_GEN --> BRANCH_CONDITION
PERMISSIONS_CHECK --> ENV_SETUP

The index.html generation uses a shell command to extract the crate name and create a redirect:

printf '<meta http-equiv="refresh" content="0;url=%s/index.html">' $(cargo tree | head -1 | cut -d' ' -f1) > target/doc/index.html

Sources: .github/workflows/ci.yml(L32 - L56)  .github/workflows/ci.yml(L40)  .github/workflows/ci.yml(L46 - L48) 

Build and Test Execution

The CI system executes different build and test strategies based on the target architecture:

Target-Specific Behavior

flowchart TD
BUILD_START["cargo build --target TARGET --all-features"]
TARGET_CHECK["Check target architecture"]
LINUX_TARGET["x86_64-unknown-linux-gnu"]
BAREMETAL_X86["x86_64-unknown-none"]
BAREMETAL_RISCV["riscv64gc-unknown-none-elf"]
BAREMETAL_ARM["aarch64-unknown-none-softfloat"]
BAREMETAL_LOONG["loongarch64-unknown-none-softfloat"]
BUILD_SUCCESS["Build Success"]
TEST_CHECK["if: matrix.targets == 'x86_64-unknown-linux-gnu'"]
UNIT_TESTS["cargo test --target TARGET -- --nocapture"]
NO_TESTS["Skip unit tests"]
TEST_COMPLETE["All checks complete"]

BAREMETAL_ARM --> BUILD_SUCCESS
BAREMETAL_LOONG --> BUILD_SUCCESS
BAREMETAL_RISCV --> BUILD_SUCCESS
BAREMETAL_X86 --> BUILD_SUCCESS
BUILD_START --> TARGET_CHECK
BUILD_SUCCESS --> TEST_CHECK
LINUX_TARGET --> BUILD_SUCCESS
NO_TESTS --> TEST_COMPLETE
TARGET_CHECK --> BAREMETAL_ARM
TARGET_CHECK --> BAREMETAL_LOONG
TARGET_CHECK --> BAREMETAL_RISCV
TARGET_CHECK --> BAREMETAL_X86
TARGET_CHECK --> LINUX_TARGET
TEST_CHECK --> NO_TESTS
TEST_CHECK --> UNIT_TESTS
UNIT_TESTS --> TEST_COMPLETE

Unit tests are only executed on the x86_64-unknown-linux-gnu target because the bare metal targets cannot run standard Rust test frameworks.

Sources: .github/workflows/ci.yml(L26 - L30) 

The CI pipeline ensures that the kernel_guard crate builds correctly across all supported architectures while maintaining code quality standards through automated formatting, linting, and testing.

Development Environment

Relevant source files

• .gitignore
• Cargo.toml

This section provides setup instructions for local development of the kernel_guard crate, including toolchain requirements, dependency management, and project configuration. For information about the CI/CD pipeline and automated testing, see Build System and CI.

Prerequisites and Toolchain Setup

The kernel_guard crate is designed for kernel-level development and supports multiple target architectures. Development requires a properly configured Rust toolchain with cross-compilation capabilities.

Rust Toolchain Requirements

The project uses Rust 2021 edition and requires a recent stable Rust compiler. The crate is designed for no-std environments, making it suitable for bare-metal kernel development.

flowchart TD
RUST["rustc (stable)"]
EDITION["2021 edition"]
NOSTD["no-std compatibility"]
TARGETS["Multi-target support"]
X86["x86_64-unknown-linux-gnux86_64-unknown-none"]
RISCV["riscv64gc-unknown-none-elf"]
AARCH64["aarch64-unknown-none-softfloat"]
LOONG["loongarch64-unknown-none-softfloat"]
CARGO["Cargo build system"]
KERNEL["Kernel development"]

EDITION --> CARGO
NOSTD --> KERNEL
RUST --> EDITION
RUST --> NOSTD
RUST --> TARGETS
TARGETS --> AARCH64
TARGETS --> LOONG
TARGETS --> RISCV
TARGETS --> X86

Rust Toolchain Setup

# Install required targets for cross-compilation
rustup target add x86_64-unknown-none
rustup target add riscv64gc-unknown-none-elf
rustup target add aarch64-unknown-none-softfloat
rustup target add loongarch64-unknown-none-softfloat

Sources: Cargo.toml(L4)  Cargo.toml(L12) 

Project Dependencies and Configuration

The project maintains minimal dependencies to ensure compatibility with kernel environments. All dependencies are carefully selected for no-std compatibility.

Core Dependencies

The project relies on two primary dependencies that enable its architecture-agnostic design and conditional compilation features.

flowchart TD
CARGO["Cargo.toml"]
DEPS["Dependencies"]
CFGIF["cfg-if = \1.0\"]
CRATEIF["crate_interface = \0.1\"]
ARCH["Architecture selection"]
TRAIT["KernelGuardIf trait"]
COMPILE["Conditional compilation"]
INTERFACE["User implementation"]

ARCH --> COMPILE
CARGO --> DEPS
CFGIF --> ARCH
CRATEIF --> TRAIT
DEPS --> CFGIF
DEPS --> CRATEIF
TRAIT --> INTERFACE

Sources: Cargo.toml(L18 - L20) 

Feature Configuration

The crate provides optional features that control guard functionality and compilation behavior.

flowchart TD
FEATURES["Crate Features"]
DEFAULT["default = []"]
PREEMPT["preempt"]
BASIC["Basic IRQ guards only"]
ADVANCED["NoPreempt + NoPreemptIrqSave"]
IRQSAVE["IrqSave guard"]
NOPREEMPT["NoPreempt guard"]
COMBINED["NoPreemptIrqSave guard"]

ADVANCED --> COMBINED
ADVANCED --> NOPREEMPT
BASIC --> IRQSAVE
DEFAULT --> BASIC
FEATURES --> DEFAULT
FEATURES --> PREEMPT
PREEMPT --> ADVANCED

Sources: Cargo.toml(L14 - L16) 

Local Development Workflow

Project Structure

The development environment excludes common build artifacts and editor-specific files to maintain a clean repository state.

Excluded Files and Directories

• /target - Cargo build artifacts and dependencies
• /.vscode - Visual Studio Code workspace settings
• .DS_Store - macOS file system metadata
• Cargo.lock - Dependency lock file (excluded for libraries)

flowchart TD
REPO["Repository Root"]
SRC["src/"]
CARGO["Cargo.toml"]
GITIGNORE[".gitignore"]
EXCLUDED["Excluded Files"]
TARGET["/target"]
VSCODE["/.vscode"]
DSSTORE[".DS_Store"]
LOCK["Cargo.lock"]
BUILD["Build artifacts"]
DEPS["Downloaded dependencies"]
EDITOR["Editor configuration"]
VERSIONS["Dependency versions"]

EXCLUDED --> DSSTORE
EXCLUDED --> LOCK
EXCLUDED --> TARGET
EXCLUDED --> VSCODE
GITIGNORE --> EXCLUDED
LOCK --> VERSIONS
REPO --> CARGO
REPO --> GITIGNORE
REPO --> SRC
TARGET --> BUILD
TARGET --> DEPS
VSCODE --> EDITOR

Sources: .gitignore(L1 - L4) 

Build Commands

Basic Development Commands

# Build for host target
cargo build

# Build for specific target
cargo build --target x86_64-unknown-none

# Enable preempt feature
cargo build --features preempt

# Check formatting
cargo fmt --check

# Run linting
cargo clippy

Cross-Compilation Workflow

# Build for all supported architectures
cargo build --target x86_64-unknown-none
cargo build --target riscv64gc-unknown-none-elf
cargo build --target aarch64-unknown-none-softfloat
cargo build --target loongarch64-unknown-none-softfloat

Testing Limitations

Due to the kernel-specific nature of the crate, comprehensive testing is only available on hosted environments. The guards provide no-op implementations when not running on bare metal, allowing basic compilation and unit testing on development machines.

flowchart TD
ENV["Development Environment"]
HOSTED["Hosted (Linux/macOS)"]
BAREMETAL["Bare Metal Target"]
NOOP["NoOp guard implementations"]
TESTS["Unit tests available"]
REAL["Real guard implementations"]
LIMITED["Limited testing"]
COMPILE["Compilation verification"]
CI["CI pipeline validation"]

BAREMETAL --> LIMITED
BAREMETAL --> REAL
ENV --> BAREMETAL
ENV --> HOSTED
HOSTED --> NOOP
HOSTED --> TESTS
NOOP --> COMPILE
TESTS --> CI

Sources: Cargo.toml(L12) 

Documentation Development

The project uses standard Rust documentation tools with GitHub Pages integration for hosting.

Documentation Commands

# Generate local documentation
cargo doc --open

# Generate documentation with all features
cargo doc --all-features --open

# Check documentation examples
cargo test --doc

The documentation is automatically deployed to GitHub Pages through the CI pipeline, providing up-to-date API reference at the configured documentation URL.

Sources: Cargo.toml(L10) 

Overview

Relevant source files

• Cargo.toml
• README.md

This document covers the timer_list crate, a Rust library that provides efficient timer event management for the ArceOS operating system. The crate implements a priority queue-based system for scheduling and triggering time-based events in no-std environments. For detailed API documentation, see Core API Reference. For practical implementation examples, see Usage Guide and Examples.

Purpose and Core Design

The timer_list crate serves as a foundational component for time-based event scheduling in operating system kernels and embedded systems. It provides a TimerList data structure that manages TimerEvent objects, ensuring they are triggered sequentially when their deadlines expire.

Core Design Principles

The following diagram illustrates the core system architecture and maps natural language concepts to specific code entities:

flowchart TD
subgraph subGraph2["Internal Implementation"]
    HEAP["BinaryHeap"]
    WRAP["TimerEventWrapper"]
    ORD["Ord implementation"]
end
subgraph subGraph1["Core Operations"]
    SET["set(deadline, event)"]
    EXP["expire_one(now)"]
    EMPTY["is_empty()"]
    NEXT["next_deadline()"]
end
subgraph subGraph0["Public Interface"]
    TL["TimerList"]
    TE["TimerEvent trait"]
    TEF["TimerEventFn struct"]
    TV["TimeValue type alias"]
end

EXP --> HEAP
HEAP --> WRAP
SET --> HEAP
TE --> TEF
TEF --> TL
TL --> EMPTY
TL --> EXP
TL --> NEXT
TL --> SET
WRAP --> ORD

Sources: Cargo.toml(L1 - L15)  README.md(L12 - L34) 

System Architecture

The timer_list crate implements a min-heap based priority queue system for efficient timer management. The following diagram shows the complete system architecture:

flowchart TD
subgraph subGraph3["ArceOS Integration"]
    KERNEL["Kernel Timer System"]
    NOSTD["no-std Environment"]
    TARGETS["Multi-architecture Support"]
end
subgraph subGraph2["Data Management"]
    PQUEUE["Priority Queue (BinaryHeap)"]
    EVENTS["TimerEventWrapper objects"]
    ORDERING["Min-heap ordering by deadline"]
end
subgraph subGraph1["timer_list Crate"]
    API["TimerList API"]
    TRAIT["TimerEvent trait"]
    WRAPPER["TimerEventFn wrapper"]
end
subgraph subGraph0["Application Layer"]
    APP["User Code"]
    CB["Event Callbacks"]
end

API --> KERNEL
API --> NOSTD
API --> PQUEUE
APP --> API
APP --> TRAIT
CB --> WRAPPER
EVENTS --> ORDERING
NOSTD --> TARGETS
PQUEUE --> ORDERING
TRAIT --> EVENTS
WRAPPER --> EVENTS

Sources: Cargo.toml(L6 - L7)  Cargo.toml(L12)  README.md(L7 - L8) 

Key Capabilities

The timer_list crate provides the following core capabilities:

Sequential Processing Model

The crate enforces sequential processing of timer events, where events are triggered one at a time in deadline order. This design ensures deterministic behavior suitable for real-time systems and kernel environments.

sequenceDiagram
    participant UserCode as User Code
    participant TimerList as TimerList
    participant BinaryHeap as BinaryHeap
    participant TimerEvent as TimerEvent

    UserCode ->> TimerList: "set(deadline, event)"
    TimerList ->> BinaryHeap: "push(TimerEventWrapper)"
    Note over BinaryHeap: "Auto-sorts by deadline"
    loop "Event Processing"
        UserCode ->> TimerList: "expire_one(current_time)"
        TimerList ->> BinaryHeap: "peek() - check earliest"
    alt "Event expired"
        BinaryHeap -->> TimerList: "Return wrapper"
        TimerList ->> BinaryHeap: "pop() - remove"
        TimerList -->> UserCode: "Some((deadline, event))"
        UserCode ->> TimerEvent: "event.callback(now)"
    else "No expired events"
        TimerList -->> UserCode: "None"
    end
    end

Sources: README.md(L24 - L33) 

ArceOS Ecosystem Integration

The timer_list crate is designed specifically for integration with the ArceOS operating system ecosystem. Key integration aspects include:

• No-std Compatibility: Designed for kernel and embedded environments without standard library dependencies
• Multi-architecture Support: Compatible with x86_64, RISC-V, and ARM architectures
• License Flexibility: Triple-licensed (GPL-3.0, Apache-2.0, MulanPSL-2.0) for broad ecosystem compatibility
• Crates.io Publication: Available as a standalone library for reuse in other projects

The crate serves as a foundational component that other ArceOS modules can depend on for timer-based functionality, from interrupt handling to task scheduling.

Sources: Cargo.toml(L7 - L12)  README.md(L3 - L5) 

Core API Reference

Relevant source files

• src/lib.rs

This document provides comprehensive reference documentation for all public types, traits, and methods exposed by the timer_list crate. The API consists of four main components: the TimerList data structure for managing timed events, the TimerEvent trait for defining event callbacks, the TimerEventFn wrapper for closure-based events, and the TimeValue type alias for time representation.

For practical usage examples and integration patterns, see Usage Guide and Examples. For detailed explanations of the internal architecture, see TimerList Data Structure and TimerEvent System.

Type System Overview

flowchart TD
TimeValue["TimeValue(type alias)"]
Duration["core::time::Duration"]
TimerEvent["TimerEvent(trait)"]
callback["callback(self, now: TimeValue)"]
TimerEventFn["TimerEventFn(struct)"]
BoxedClosure["Box<dyn FnOnce(TimeValue)>"]
TimerList["TimerList<E: TimerEvent>(struct)"]
BinaryHeap["BinaryHeap<TimerEventWrapper<E>>"]
TimerEventWrapper["TimerEventWrapper<E>(internal)"]
deadline["deadline: TimeValue"]
event["event: E"]

BinaryHeap --> TimerEventWrapper
TimeValue --> Duration
TimerEvent --> callback
TimerEventFn --> BoxedClosure
TimerEventFn --> TimerEvent
TimerEventWrapper --> deadline
TimerEventWrapper --> event
TimerList --> BinaryHeap
TimerList --> TimerEvent

Type Relationships in timer_list Crate

This diagram shows the complete type hierarchy and relationships within the crate. The TimerList is parameterized over types implementing TimerEvent, while TimerEventFn provides a concrete implementation for closure-based events.

Sources: src/lib.rs(L10 - L32)  src/lib.rs(L108 - L127) 

Core Types

TimeValue

pub type TimeValue = Duration;

The TimeValue type is an alias for core::time::Duration and represents all time values used throughout the timer system. This includes event deadlines, current time measurements, and time deltas.

Sources: src/lib.rs(L10 - L13) 

TimerEvent Trait

The TimerEvent trait defines the interface that all timed events must implement. It consists of a single required method:

#![allow(unused)]
fn main() {
pub trait TimerEvent {
    fn callback(self, now: TimeValue);
}
}

The callback method takes ownership of the event (self) and receives the current time when the event expires. This design ensures that each event can only be triggered once.

Sources: src/lib.rs(L15 - L19) 

TimerEventFn Wrapper

The TimerEventFn struct provides a convenient way to create timer events from closures without implementing the TimerEvent trait manually.

pub struct TimerEventFn(Box<dyn FnOnce(TimeValue) + 'static>);

The wrapper automatically implements TimerEvent by calling the stored closure when the event expires.

Sources: src/lib.rs(L108 - L127) 

TimerList API Methods

Constructor and State

The TimerList also implements Default, which delegates to new().

Sources: src/lib.rs(L55 - L66)  src/lib.rs(L102 - L106) 

Event Management

The set method has O(log n) complexity due to the underlying min-heap structure. The cancel method currently has O(n) complexity and includes a TODO comment for performance optimization.

Sources: src/lib.rs(L68 - L99) 

Event Processing Flow

sequenceDiagram
    participant ClientCode as "Client Code"
    participant TimerList as "TimerList"
    participant BinaryHeap as "BinaryHeap"
    participant TimerEventWrapper as "TimerEventWrapper"

    Note over ClientCode,TimerEventWrapper: Event Scheduling
    ClientCode ->> TimerList: "set(deadline, event)"
    TimerList ->> TimerEventWrapper: "TimerEventWrapper::new"
    TimerList ->> BinaryHeap: "push(wrapper)"
    Note over BinaryHeap: "Min-heap reorders by deadline"
    Note over ClientCode,TimerEventWrapper: Event Expiration
    ClientCode ->> TimerList: "expire_one(now)"
    TimerList ->> BinaryHeap: "peek()"
    BinaryHeap -->> TimerList: "earliest event"
    alt "deadline <= now"
        TimerList ->> BinaryHeap: "pop()"
        BinaryHeap -->> TimerList: "TimerEventWrapper"
        TimerList -->> ClientCode: "Some((deadline, event))"
        ClientCode ->> ClientCode: "event.callback(now)"
    else "deadline > now"
        TimerList -->> ClientCode: "None"
    end

Event Lifecycle from Scheduling to Expiration

This sequence diagram illustrates the complete flow from event scheduling through expiration processing, showing how the TimerList coordinates with the internal BinaryHeap and TimerEventWrapper structures.

Sources: src/lib.rs(L21 - L24)  src/lib.rs(L68 - L99) 

Internal Implementation Details

TimerEventWrapper

The internal TimerEventWrapper<E> struct combines an event with its deadline and implements the ordering traits required for the min-heap:

struct TimerEventWrapper<E> {
    deadline: TimeValue,
    event: E,
}

The wrapper implements Ord, PartialOrd, Eq, and PartialEq with reversed ordering to create a min-heap from Rust's max-heap BinaryHeap. The comparison is based solely on the deadline field.

Sources: src/lib.rs(L21 - L24)  src/lib.rs(L34 - L52) 

Min-Heap Architecture

flowchart TD
subgraph subGraph0["Ordering Property"]
    parent["Parent deadline"]
    child1["Child1 deadline"]
    child2["Child2 deadline"]
end
TimerList["TimerList<E>"]
events["events: BinaryHeap"]
root["Root: earliest deadline"]
left["Left child"]
right["Right child"]
leftleft["..."]
leftright["..."]
rightleft["..."]
rightright["..."]

TimerList --> events
events --> root
left --> leftleft
left --> leftright
parent --> child1
parent --> child2
right --> rightleft
right --> rightright
root --> left
root --> right

Internal Min-Heap Structure for Event Ordering

The BinaryHeap maintains the min-heap property where each parent node has a deadline less than or equal to its children, ensuring O(1) access to the earliest event and O(log n) insertion.

Sources: src/lib.rs(L26 - L32)  src/lib.rs(L40 - L43) 

TimerList Data Structure

Relevant source files

• src/lib.rs

This document provides detailed technical documentation of the TimerList struct, which serves as the core data structure for managing timed events in the timer_list crate. It covers the internal min-heap architecture, public methods, performance characteristics, and implementation details.

For information about the TimerEvent trait and event callback system, see TimerEvent System. For practical usage examples, see Usage Guide and Examples.

Core Structure Overview

The TimerList<E: TimerEvent> struct provides an efficient priority queue implementation for managing timed events. It internally uses a binary heap data structure to maintain events in deadline order, enabling O(log n) insertions and O(1) access to the next expiring event.

Primary Components

flowchart TD
subgraph subGraph0["Type Constraints"]
    TC["E: TimerEvent"]
end
TL["TimerList<E>"]
BH["BinaryHeap<TimerEventWrapper<E>>"]
TEW1["TimerEventWrapper<E>"]
TEW2["TimerEventWrapper<E>"]
TEW3["TimerEventWrapper<E>"]
DL1["deadline: TimeValue"]
EV1["event: E"]
DL2["deadline: TimeValue"]
EV2["event: E"]
DL3["deadline: TimeValue"]
EV3["event: E"]

BH --> TEW1
BH --> TEW2
BH --> TEW3
TEW1 --> DL1
TEW1 --> EV1
TEW2 --> DL2
TEW2 --> EV2
TEW3 --> DL3
TEW3 --> EV3
TL --> BH
TL --> TC

Sources: src/lib.rs(L30 - L32)  src/lib.rs(L21 - L24) 

The structure consists of three main components:

Min-Heap Architecture

The TimerList implements a min-heap through custom ordering logic on TimerEventWrapper<E>. This ensures that events with earlier deadlines are always at the top of the heap for efficient retrieval.

Heap Ordering Implementation

flowchart TD
subgraph subGraph2["Trait Implementations"]
    ORD["Ord"]
    PORD["PartialOrd"]
    EQT["Eq"]
    PEQ["PartialEq"]
end
subgraph subGraph1["Min-Heap Property"]
    ROOT["Earliest Deadline"]
    L1["Later Deadline"]
    R1["Later Deadline"]
    L2["Even Later"]
    R2["Even Later"]
end
subgraph subGraph0["TimerEventWrapper Ordering"]
    CMP["cmp()"]
    REV["other.deadline.cmp(&self.deadline)"]
    PCMP["partial_cmp()"]
    EQ["eq()"]
    COMP["self.deadline == other.deadline"]
end

CMP --> REV
CMP --> ROOT
EQ --> COMP
EQT --> EQ
L1 --> L2
L1 --> R2
ORD --> CMP
PCMP --> CMP
PEQ --> EQ
PORD --> PCMP
ROOT --> L1
ROOT --> R1

Sources: src/lib.rs(L34 - L52) 

The ordering implementation uses reversed comparison logic:

Public Methods

The TimerList provides a clean API for timer management operations:

Core Operations

Query Operations

Sources: src/lib.rs(L54 - L100) 

Internal Implementation Details

Event Scheduling Flow

sequenceDiagram
    participant Client as Client
    participant TimerList as TimerList
    participant BinaryHeap as BinaryHeap
    participant TimerEventWrapper as TimerEventWrapper

    Client ->> TimerList: "set(deadline, event)"
    TimerList ->> TimerEventWrapper: "TimerEventWrapper { deadline, event }"
    TimerList ->> BinaryHeap: "push(wrapper)"
    Note over BinaryHeap: "Auto-reorders via Ord trait"
    BinaryHeap -->> TimerList: "Heap maintains min property"
    TimerList -->> Client: "Event scheduled"

Sources: src/lib.rs(L69 - L71) 

Event Expiration Flow

sequenceDiagram
    participant Client as Client
    participant TimerList as TimerList
    participant BinaryHeap as BinaryHeap

    Client ->> TimerList: "expire_one(now)"
    TimerList ->> BinaryHeap: "peek()"
    BinaryHeap -->> TimerList: "Some(earliest_wrapper)"
    alt "deadline <= now"
        TimerList ->> BinaryHeap: "pop()"
        BinaryHeap -->> TimerList: "TimerEventWrapper"
        TimerList -->> Client: "Some((deadline, event))"
    else "deadline > now"
        TimerList -->> Client: "None"
    end

Sources: src/lib.rs(L92 - L99) 

Data Structure Memory Layout

The TimerList maintains minimal memory overhead with efficient heap allocation:

flowchart TD
subgraph subGraph1["Heap Properties"]
    HP1["Min-heap ordering"]
    HP2["O(log n) rebalancing"]
    HP3["Contiguous memory"]
end
subgraph subGraph0["Memory Layout"]
    TLS["TimerList Struct"]
    BHS["BinaryHeap Storage"]
    VEC["Vec<TimerEventWrapper>"]
    TEW1["TimerEventWrapper { deadline, event }"]
    TEW2["TimerEventWrapper { deadline, event }"]
    TEWN["..."]
end

BHS --> HP1
BHS --> HP2
BHS --> VEC
TLS --> BHS
VEC --> HP3
VEC --> TEW1
VEC --> TEW2
VEC --> TEWN

Sources: src/lib.rs(L30 - L32)  src/lib.rs(L21 - L24) 

Performance Characteristics

The min-heap implementation provides optimal performance for the primary use case of sequential event processing by deadline order.

Sources: src/lib.rs(L54 - L100) 

TimerEvent System

Relevant source files

• src/lib.rs

This document covers the timer event system that defines how callbacks are executed when timers expire in the timer_list crate. It focuses on the TimerEvent trait and its implementations, particularly the TimerEventFn wrapper for closure-based events.

For information about the underlying timer storage and scheduling mechanisms, see TimerList Data Structure.

Purpose and Scope

The TimerEvent system provides the interface and implementations for executable timer callbacks in the timer_list crate. It defines how events are structured and executed when their deadlines are reached, supporting both custom event types and simple closure-based events.

TimerEvent Trait

The TimerEvent trait serves as the core interface that all timer events must implement. It defines a single callback method that consumes the event when executed.

Trait Definition

The trait is defined with a simple interface at src/lib.rs(L15 - L19) :

#![allow(unused)]
fn main() {
pub trait TimerEvent {
    fn callback(self, now: TimeValue);
}
}

Key Characteristics

The trait design ensures that events cannot be accidentally reused after execution, providing memory safety and preventing common timer-related bugs.

TimerEvent Trait Architecture

classDiagram
class TimerEvent {
    <<trait>>
    
    +callback(self, now: TimeValue)
}

class TimerEventFn {
    
    -Box~dyn FnOnce(TimeValue) ~
    +new(f: F) TimerEventFn
    +callback(self, now: TimeValue)
}

class CustomEvent {
    <<user-defined>>
    
    +callback(self, now: TimeValue)
}

TimerEvent  ..|>  TimerEventFn : implements
TimerEvent  ..|>  CustomEvent : implements

Sources: src/lib.rs(L15 - L19)  src/lib.rs(L108 - L127) 

TimerEventFn Implementation

The TimerEventFn struct provides a convenient wrapper that allows closures to be used as timer events without requiring custom trait implementations.

Structure and Construction

The TimerEventFn wraps a boxed closure at src/lib.rs(L111) :

pub struct TimerEventFn(Box<dyn FnOnce(TimeValue) + 'static>);

Construction is handled by the new method at src/lib.rs(L114 - L121) :

TimerEvent Implementation

The trait implementation at src/lib.rs(L123 - L127)  simply extracts and calls the wrapped closure:

#![allow(unused)]
fn main() {
impl TimerEvent for TimerEventFn {
    fn callback(self, now: TimeValue) {
        (self.0)(now)
    }
}
}

This design enables functional programming patterns while maintaining the trait's consumption semantics.

TimerEventFn Data Flow

flowchart TD
A["closure: FnOnce(TimeValue)"]
B["TimerEventFn::new(closure)"]
C["TimerEventFn(Box::new(closure))"]
D["TimerList::set(deadline, event)"]
E["TimerEventWrapper { deadline, event }"]
F["BinaryHeap::push(wrapper)"]
G["TimerList::expire_one(now)"]
H["BinaryHeap::pop()"]
I["event.callback(now)"]
J["(closure)(now)"]

A --> B
B --> C
C --> D
D --> E
E --> F
G --> H
H --> I
I --> J

Sources: src/lib.rs(L108 - L127)  src/lib.rs(L69 - L71) 

Event Lifecycle Integration

Timer events integrate with the TimerList through a well-defined lifecycle that ensures proper execution timing and resource management.

Event Scheduling Process

Events are scheduled through the TimerList::set method, which wraps them in TimerEventWrapper structures for heap management:

Execution Semantics

When events expire, they follow a strict execution pattern defined at src/lib.rs(L92 - L99) :

• Events are processed one at a time in deadline order
• Only events with deadline <= now are eligible for execution
• Events are removed from the heap before callback execution
• Callbacks receive the actual current time, not the original deadline

Event Execution Flow

sequenceDiagram
    participant ClientCode as "Client Code"
    participant TimerList as "TimerList"
    participant BinaryHeapTimerEventWrapper as "BinaryHeap<TimerEventWrapper>"
    participant TimerEventcallback as "TimerEvent::callback"

    Note over ClientCode,TimerEventcallback: Event Scheduling
    ClientCode ->> TimerList: set(deadline, event)
    TimerList ->> BinaryHeapTimerEventWrapper: push(TimerEventWrapper)
    Note over ClientCode,TimerEventcallback: Event Processing
    loop Processing Loop
        ClientCode ->> TimerList: expire_one(now)
        TimerList ->> BinaryHeapTimerEventWrapper: peek()
    alt deadline <= now
        BinaryHeapTimerEventWrapper -->> TimerList: earliest event
        TimerList ->> BinaryHeapTimerEventWrapper: pop()
        TimerList ->> TimerEventcallback: callback(now)
        TimerEventcallback -->> ClientCode: side effects
        TimerList -->> ClientCode: Some((deadline, event))
    else deadline > now
        TimerList -->> ClientCode: None
    end
    end

Sources: src/lib.rs(L69 - L71)  src/lib.rs(L92 - L99)  src/lib.rs(L21 - L24) 

Custom Event Implementation

While TimerEventFn handles simple closure cases, custom event types can implement TimerEvent directly for more complex scenarios. The test suite demonstrates this pattern at src/lib.rs(L140 - L153) :

Example Pattern

#![allow(unused)]
fn main() {
struct TestTimerEvent(usize, TimeValue);

impl TimerEvent for TestTimerEvent {
    fn callback(self, now: TimeValue) {
        // Custom logic with access to event data
        println!("Event {} executed at {:?}", self.0, now);
    }
}
}

This approach allows events to carry additional data and implement complex callback logic while maintaining the same execution guarantees as TimerEventFn.

Code Entity Mapping

flowchart TD
subgraph subGraph2["Test Examples"]
    H["TestTimerEvent[src/lib.rs:140-153]"]
    I["test_timer_list_fn[src/lib.rs:183-206]"]
end
subgraph subGraph1["Integration Points"]
    E["TimerList::set()[src/lib.rs:69-71]"]
    F["TimerList::expire_one()[src/lib.rs:92-99]"]
    G["TimerEventWrapper[src/lib.rs:21-24]"]
end
subgraph subGraph0["TimerEvent System API"]
    A["TimerEvent trait[src/lib.rs:15-19]"]
    B["TimerEventFn struct[src/lib.rs:111]"]
    C["TimerEventFn::new()[src/lib.rs:114-121]"]
    D["TimeValue type[src/lib.rs:10-13]"]
end

A --> B
A --> D
A --> H
B --> C
B --> I
E --> G
F --> A

Sources: src/lib.rs(L15 - L19)  src/lib.rs(L108 - L127)  src/lib.rs(L69 - L71)  src/lib.rs(L92 - L99)  src/lib.rs(L140 - L153)  src/lib.rs(L183 - L206) 

Usage Guide and Examples

Relevant source files

• README.md
• src/lib.rs

This document provides practical examples and usage patterns for the timer_list crate, demonstrating how to integrate timer management functionality into applications. The examples range from basic single-timer usage to advanced patterns for managing multiple concurrent timers with custom events.

For detailed API documentation of the core types and methods, see Core API Reference. For information about the internal implementation architecture, see TimerList Data Structure and TimerEvent System.

Basic Timer Usage with Closures

The simplest way to use timer_list is with the TimerEventFn wrapper, which allows you to schedule closures to execute at specific deadlines.

Simple Timer Example

sequenceDiagram
    participant ApplicationCode as "Application Code"
    participant TimerListTimerEventFn as "TimerList<TimerEventFn>"
    participant TimerEventFn as "TimerEventFn"

    ApplicationCode ->> TimerListTimerEventFn: "new()"
    ApplicationCode ->> TimerEventFn: "new(closure)"
    ApplicationCode ->> TimerListTimerEventFn: "set(deadline, event)"
    loop "Event Processing Loop"
        ApplicationCode ->> TimerListTimerEventFn: "expire_one(now)"
    alt "Event Ready"
        TimerListTimerEventFn -->> ApplicationCode: "Some((deadline, event))"
        ApplicationCode ->> TimerEventFn: "callback(now)"
    else "No Events Ready"
        TimerListTimerEventFn -->> ApplicationCode: "None"
    end
    end

Basic Timer Setup and Processing

The core pattern involves creating a TimerList, setting timer events with deadlines, and periodically checking for expired events in a processing loop.

Sources: README.md(L12 - L34)  src/lib.rs(L111 - L127) 

Implementation Pattern

The basic usage follows this pattern:

1. Create a TimerList<TimerEventFn> instance
2. Use TimerEventFn::new() to wrap closures as timer events
3. Call set() method with a TimeValue deadline and the event
4. Periodically call expire_one() with current time to process expired events
5. Execute the callback when events are returned

flowchart TD
subgraph subGraph1["Event Processing"]
    D["Current Time"]
    E["timer_list.expire_one(now)"]
    F["Event Expired?"]
    G["event.callback(now)"]
    H["None returned"]
end
subgraph subGraph0["Timer Creation"]
    A["TimerList::new()"]
    B["TimerEventFn::new(closure)"]
    C["timer_list.set(deadline, event)"]
end

A --> B
B --> C
C --> E
D --> E
E --> F
F --> G
F --> H
G --> E
H --> E

Timer Event Lifecycle from Creation to Execution

Sources: README.md(L16 - L33)  src/lib.rs(L69 - L98) 

Custom Timer Events

For more complex use cases, implement the TimerEvent trait directly to create custom timer events with specific behavior and data.

Custom Event Implementation

The TimerEvent trait requires implementing a single callback method that consumes the event and receives the current time.

classDiagram
class TimerEvent {
    <<trait>>
    
    +callback(self, now: TimeValue)
}

class TimerEventFn {
    
    -closure: Box~dyn FnOnce(TimeValue) ~
    +new(f: F) TimerEventFn
    +callback(self, now: TimeValue)
}

class CustomEvent {
    -id: usize
    -expected_deadline: TimeValue
    +new(id: usize, deadline: TimeValue) CustomEvent
    +callback(self, now: TimeValue)
}

TimerEvent  ..|>  TimerEventFn
TimerEvent  ..|>  CustomEvent

TimerEvent Trait Implementation Hierarchy

Sources: src/lib.rs(L15 - L19)  src/lib.rs(L123 - L127)  src/lib.rs(L140 - L153) 

Custom Event Example

The test case in the source code demonstrates a custom TestTimerEvent that tracks execution order and timing accuracy:

The custom event pattern allows embedding application-specific data and logic within timer events, enabling complex scheduling scenarios.

Sources: src/lib.rs(L140 - L153) 

Advanced Usage Patterns

Multiple Timer Management

When managing multiple concurrent timers, the TimerList maintains them in deadline order using an internal min-heap structure.

flowchart TD
subgraph subGraph2["Sequential Processing"]
    I["expire_one() - Timer 1"]
    J["expire_one() - Timer 2"]
    K["expire_one() - Timer 3"]
    L["expire_one() - Timer 4"]
    M["Timer 5 (canceled)"]
end
subgraph subGraph1["Internal Organization"]
    G["BinaryHeap"]
    H["Min-heap by deadline"]
end
subgraph subGraph0["Multiple Timer Setup"]
    A["Timer 1 (0.5s)"]
    D["TimerList::set()"]
    B["Timer 2 (1.0s)"]
    C["Timer 3 (2.99s)"]
    E["Timer 4 (3.0s)"]
    F["Timer 5 (4.0s)"]
end

A --> D
B --> D
C --> D
D --> G
E --> D
F --> D
G --> H
H --> I
I --> J
J --> K
K --> L
L --> M

Multiple Timer Processing Order

The timers are processed in deadline order regardless of insertion sequence. The min-heap ensures O(log n) insertion and O(1) access to the earliest deadline.

Sources: src/lib.rs(L157 - L167)  src/lib.rs(L30 - L32)  src/lib.rs(L40 - L43) 

Timer Cancellation

The cancel() method allows removing events that match a specified condition before they expire.

The cancellation mechanism uses a closure to test each event, providing flexible filtering capabilities. The implementation uses BinaryHeap::retain() to remove matching events.

Sources: src/lib.rs(L73 - L80)  src/lib.rs(L171 - L173) 

Integration Patterns

Event Loop Integration

Timer management typically integrates with application event loops or system schedulers using a polling pattern.

flowchart TD
subgraph subGraph1["Timer State"]
    I["TimerList"]
    J["BinaryHeap ordering"]
    K["next_deadline()"]
    L["Optimal sleep duration"]
end
subgraph subGraph0["Application Event Loop"]
    A["Loop Start"]
    B["Get Current Time"]
    C["timer_list.expire_one(now)"]
    D["Event Expired?"]
    E["Execute Callback"]
    F["Other Processing"]
    G["Continue Loop"]
    H["Sleep/Yield"]
end

A --> B
B --> C
C --> D
C --> I
D --> E
D --> F
E --> G
F --> G
G --> H
H --> B
I --> J
J --> K
K --> L
L --> H

Event Loop Integration Pattern

Applications can use next_deadline() to calculate optimal sleep durations, reducing unnecessary CPU usage while maintaining timer accuracy.

Sources: src/lib.rs(L169 - L178)  src/lib.rs(L84 - L86) 

No-std Environment Usage

The crate is designed for no-std environments, making it suitable for embedded systems and kernel-level code.

The design ensures predictable performance characteristics essential for real-time and embedded applications.

Sources: src/lib.rs(L1)  src/lib.rs(L4)  src/lib.rs(L10 - L13) 

Common Patterns and Best Practices

Error Handling and Edge Cases

The TimerList API is designed to be infallible for core operations, with Option types indicating state rather than errors.

flowchart TD
subgraph subGraph1["State Handling"]
    I["Some: Event ready"]
    J["None: No events ready"]
    K["Some: Next deadline"]
    L["None: No events scheduled"]
end
subgraph subGraph0["Safe Operations"]
    A["set(deadline, event)"]
    B["Always succeeds"]
    C["expire_one(now)"]
    D["Option<(TimeValue, E)>"]
    E["next_deadline()"]
    F["Option"]
    G["is_empty()"]
    H["bool"]
end

A --> B
C --> D
D --> I
D --> J
E --> F
F --> K
F --> L
G --> H

API Safety and State Management

All operations are memory-safe and return clear indicators of timer list state, eliminating common timer management error scenarios.

Sources: src/lib.rs(L54 - L100) 

Performance Considerations

The min-heap structure provides efficient access to the earliest deadline, but cancellation operations require full heap traversal. For frequent cancellation scenarios, consider alternative approaches like event flags.

Sources: src/lib.rs(L69 - L71)  src/lib.rs(L92 - L98)  src/lib.rs(L74 - L80) 

Development Workflow

Relevant source files

• .github/workflows/ci.yml
• .gitignore

This document provides guidance for contributors working on the timer_list crate. It covers local development setup, build processes, testing procedures, and the automated CI/CD pipeline. For detailed API documentation, see Core API Reference. For usage examples and integration patterns, see Usage Guide and Examples.

Local Development Environment

The timer_list crate requires the Rust nightly toolchain with specific components and target architectures. The development environment must support cross-compilation for embedded and bare-metal targets.

Required Toolchain Components

flowchart TD
A["rust-toolchain: nightly"]
B["rust-src component"]
C["clippy component"]
D["rustfmt component"]
E["Target Architectures"]
F["x86_64-unknown-linux-gnu"]
G["x86_64-unknown-none"]
H["riscv64gc-unknown-none-elf"]
I["aarch64-unknown-none-softfloat"]

A --> B
A --> C
A --> D
A --> E
E --> F
E --> G
E --> H
E --> I

Toolchain Setup

The project requires rustc nightly with cross-compilation support for multiple architectures. Install the required components:

rustup toolchain install nightly
rustup component add rust-src clippy rustfmt --toolchain nightly
rustup target add x86_64-unknown-none riscv64gc-unknown-none-elf aarch64-unknown-none-softfloat --toolchain nightly

Sources: .github/workflows/ci.yml(L15 - L19) 

Build and Development Commands

Core Development Workflow

flowchart TD
A["cargo fmt --all -- --check"]
B["cargo clippy --target TARGET --all-features"]
C["cargo build --target TARGET --all-features"]
D["cargo test --target x86_64-unknown-linux-gnu"]
E["cargo doc --no-deps --all-features"]
F["Format Check"]
G["Lint Analysis"]
H["Cross-Platform Build"]
I["Unit Testing"]
J["Documentation Generation"]

A --> B
B --> C
C --> D
D --> E
F --> A
G --> B
H --> C
I --> D
J --> E

Format Checking

cargo fmt --all -- --check

Lint Analysis

cargo clippy --target <TARGET> --all-features -- -A clippy::new_without_default

Building for Specific Targets

cargo build --target <TARGET> --all-features

Running Tests

cargo test --target x86_64-unknown-linux-gnu -- --nocapture

Sources: .github/workflows/ci.yml(L22 - L30) 

Multi-Target Architecture Support

The crate supports four distinct target architectures, each serving different deployment scenarios:

flowchart TD
A["timer_list crate"]
B["x86_64-unknown-linux-gnu"]
C["x86_64-unknown-none"]
D["riscv64gc-unknown-none-elf"]
E["aarch64-unknown-none-softfloat"]
F["Linux DevelopmentUnit Testing"]
G["Bare-metal x86_64Build Verification"]
H["RISC-V EmbeddedBuild Verification"]
I["ARM64 EmbeddedBuild Verification"]

A --> B
A --> C
A --> D
A --> E
B --> F
C --> G
D --> H
E --> I

Unit tests execute only on x86_64-unknown-linux-gnu due to the no-std nature of other targets and the lack of standard library support for test execution.

Sources: .github/workflows/ci.yml(L12)  .github/workflows/ci.yml(L29 - L30) 

Continuous Integration Pipeline

CI Job Matrix Strategy

flowchart TD
subgraph subGraph1["Documentation Pipeline"]
    C["Documentation Job"]
    H["cargo doc build"]
    I["GitHub Pages Deploy"]
end
subgraph subGraph0["CI Job Matrix"]
    B["CI Job"]
    D["Format Check"]
    E["Clippy Analysis"]
    F["Multi-Target Build"]
    G["Unit Tests"]
end
A["GitHub Push/PR Trigger"]
J["x86_64-unknown-linux-gnu build"]
K["x86_64-unknown-none build"]
L["riscv64gc-unknown-none-elf build"]
M["aarch64-unknown-none-softfloat build"]
N["x86_64-unknown-linux-gnu tests only"]

A --> B
A --> C
B --> D
B --> E
B --> F
B --> G
C --> H
C --> I
F --> J
F --> K
F --> L
F --> M
G --> N

CI Job Execution Steps:

1. Environment Setup: Ubuntu latest with nightly Rust toolchain
2. Format Verification: cargo fmt --all -- --check
3. Lint Analysis: cargo clippy with custom configuration
4. Cross-Compilation: Build for all four target architectures
5. Test Execution: Unit tests on Linux target only

Documentation Job Features:

• Builds documentation with strict link checking
• Enforces complete documentation coverage
• Deploys to GitHub Pages on default branch pushes
• Generates redirect index page automatically

Sources: .github/workflows/ci.yml(L6 - L31)  .github/workflows/ci.yml(L32 - L55) 

Documentation Standards

Documentation Pipeline Configuration

flowchart TD
A["RUSTDOCFLAGS Environment"]
B["-D rustdoc::broken_intra_doc_links"]
C["-D missing-docs"]
D["cargo doc --no-deps --all-features"]
E["Documentation Build"]
F["Index Page Generation"]
G["GitHub Pages Deployment"]
H["Default Branch Push"]
I["Pull Request"]
J["Build Only"]

A --> B
A --> C
D --> E
E --> F
F --> G
H --> G
I --> J

The documentation system enforces strict standards:

• Broken Link Detection: All intra-doc links must resolve correctly
• Complete Coverage: Missing documentation generates build failures
• Dependency Exclusion: Only project documentation is generated (--no-deps)
• Feature Complete: All features are documented (--all-features)

The system automatically generates an index redirect page using the crate name extracted from cargo tree output.

Sources: .github/workflows/ci.yml(L40)  .github/workflows/ci.yml(L47 - L48) 

Repository Structure and Ignored Files

Git Configuration

flowchart TD
A["Repository Root"]
B["Source Files"]
C["Ignored Artifacts"]
D["src/"]
E["Cargo.toml"]
F[".github/workflows/"]
G["/target"]
H["/.vscode"]
I[".DS_Store"]
J["Cargo.lock"]

A --> B
A --> C
B --> D
B --> E
B --> F
C --> G
C --> H
C --> I
C --> J

Ignored Files and Directories:

• /target: Rust build artifacts and compiled binaries
• /.vscode: Visual Studio Code workspace settings
• .DS_Store: macOS filesystem metadata files
• Cargo.lock: Dependency lock file (excluded for library crates)

The Cargo.lock exclusion indicates this crate follows Rust library conventions, allowing downstream projects to resolve their own dependency versions.

Sources: .gitignore(L1 - L4) 

Contributing Guidelines

Code Quality Requirements

All contributions must pass the complete CI pipeline:

1. Format Compliance: Code must conform to rustfmt standards
2. Lint Compliance: Must pass clippy analysis with project-specific exceptions
3. Cross-Platform Compatibility: Must build successfully on all four target architectures
4. Test Coverage: New functionality requires corresponding unit tests
5. Documentation: All public APIs must include comprehensive documentation

Development Branch Strategy

The project uses a straightforward branching model:

• Default Branch: Primary development and release branch
• Feature Branches: Individual contributions via pull requests
• GitHub Pages: Automatic deployment from default branch

Documentation deployment occurs automatically on default branch pushes, ensuring the published documentation remains current with the latest code changes.

Sources: .github/workflows/ci.yml(L3)  .github/workflows/ci.yml(L50) 

Building and Testing

Relevant source files

• .github/workflows/ci.yml

This page documents the automated build and testing infrastructure for the timer_list crate, including the CI/CD pipeline configuration, supported target architectures, and local development commands. The information covers both automated workflows triggered by Git events and manual testing procedures for local development.

For information about the project file structure and development environment setup, see Project Structure.

CI/CD Pipeline Overview

The timer_list crate uses GitHub Actions for continuous integration and deployment. The pipeline consists of two main jobs that ensure code quality, cross-platform compatibility, and automated documentation deployment.

Pipeline Architecture

flowchart TD
A["push/pull_request"]
B["GitHub Actions Trigger"]
C["ci job"]
D["doc job"]
E["ubuntu-latest runner"]
F["ubuntu-latest runner"]
G["Matrix Strategy"]
H["rust-toolchain: nightly"]
I["4 target architectures"]
J["Format Check"]
K["Clippy Linting"]
L["Multi-target Build"]
M["Unit Tests"]
N["Documentation Build"]
O["GitHub Pages Deploy"]
P["x86_64-unknown-linux-gnu only"]
Q["gh-pages branch"]

A --> B
B --> C
B --> D
C --> E
D --> F
E --> G
E --> J
E --> K
E --> L
E --> M
F --> N
F --> O
G --> H
G --> I
M --> P
O --> Q

The pipeline implements a fail-fast strategy set to false, allowing all target builds to complete even if one fails, providing comprehensive feedback across all supported architectures.

Sources: .github/workflows/ci.yml(L1 - L56) 

Build Matrix Configuration

The CI system uses a matrix strategy to test across multiple configurations simultaneously:

flowchart TD
A["Matrix Strategy"]
B["nightly toolchain"]
C["Target Matrix"]
D["x86_64-unknown-linux-gnu"]
E["x86_64-unknown-none"]
F["riscv64gc-unknown-none-elf"]
G["aarch64-unknown-none-softfloat"]
H["rust-src component"]
I["clippy component"]
J["rustfmt component"]

A --> B
A --> C
B --> H
B --> I
B --> J
C --> D
C --> E
C --> F
C --> G

The pipeline installs additional Rust components (rust-src, clippy, rustfmt) and configures targets for each architecture in the matrix.

Sources: .github/workflows/ci.yml(L8 - L19) 

Target Architecture Support

The crate supports four target architectures, reflecting its use in embedded and operating system environments:

Architecture Details

flowchart TD
A["timer_list Crate"]
B["Cross-Platform Support"]
C["x86_64-unknown-linux-gnu"]
D["x86_64-unknown-none"]
E["riscv64gc-unknown-none-elf"]
F["aarch64-unknown-none-softfloat"]
G["cargo test enabled"]
H["cargo build only"]
I["cargo build only"]
J["cargo build only"]
K["Unit test execution"]
L["no-std compatibility"]
M["RISC-V validation"]
N["ARM64 validation"]

A --> B
B --> C
B --> D
B --> E
B --> F
C --> G
D --> H
E --> I
F --> J
G --> K
H --> L
I --> M
J --> N

Unit tests execute only on x86_64-unknown-linux-gnu due to the testing framework requirements, while other targets verify no-std compatibility and cross-compilation success.

Sources: .github/workflows/ci.yml(L12)  .github/workflows/ci.yml(L29 - L30) 

Build and Test Commands

The CI pipeline executes a specific sequence of commands for each target architecture. These commands can also be run locally for development purposes.

Core CI Commands

sequenceDiagram
    participant DeveloperCI as "Developer/CI"
    participant RustToolchain as "Rust Toolchain"
    participant Cargo as "Cargo"
    participant TargetBinary as "Target Binary"

    DeveloperCI ->> RustToolchain: "rustc --version --verbose"
    RustToolchain -->> DeveloperCI: "Version information"
    DeveloperCI ->> Cargo: "cargo fmt --all -- --check"
    Cargo -->> DeveloperCI: "Format validation"
    DeveloperCI ->> Cargo: "cargo clippy --target TARGET --all-features"
    Cargo -->> DeveloperCI: "Lint results"
    DeveloperCI ->> Cargo: "cargo build --target TARGET --all-features"
    Cargo ->> TargetBinary: "Compile for target"
    TargetBinary -->> DeveloperCI: "Build artifacts"
    alt "x86_64-unknown-linux-gnu only"
        DeveloperCI ->> Cargo: "cargo test --target TARGET -- --nocapture"
        Cargo -->> DeveloperCI: "Test results"
    end

Local Development Commands

For local development, developers can run the same commands used in CI:

The --all-features flag ensures that all conditional compilation features are enabled during builds and linting.

Sources: .github/workflows/ci.yml(L22 - L30) 

Documentation Generation

The doc job handles automated documentation generation and deployment to GitHub Pages.

Documentation Workflow

flowchart TD
A["doc job trigger"]
B["ubuntu-latest"]
C["Rust nightly setup"]
D["cargo doc build"]
E["RUSTDOCFLAGS validation"]
F["broken_intra_doc_links check"]
G["missing-docs check"]
H["target/doc generation"]
I["index.html redirect"]
J["default branch?"]
K["Deploy to gh-pages"]
L["Skip deployment"]
M["GitHub Pages"]

A --> B
B --> C
C --> D
D --> E
D --> H
E --> F
E --> G
H --> I
I --> J
J --> K
J --> L
K --> M

The documentation job includes strict validation using RUSTDOCFLAGS to ensure documentation quality by failing on broken internal links and missing documentation.

Documentation Commands

The documentation generation process uses these key commands:

• cargo doc --no-deps --all-features - Generate documentation without dependencies
• cargo tree | head -1 | cut -d' ' -f1 - Extract crate name for redirect
• Auto-generated index.html redirect to the main crate documentation

Sources: .github/workflows/ci.yml(L32 - L55)