System Components

Relevant source files

• Cargo.toml
• percpu/Cargo.toml
• percpu_macros/Cargo.toml

Purpose and Scope

This document details the architectural components of the percpu crate ecosystem, focusing on the two main crates (percpu and percpu_macros) and their integration with dependencies. It covers the workspace structure, feature configuration, and how the components collaborate to provide per-CPU data management functionality.

For platform-specific implementation details, see Supported Platforms. For detailed API usage, see API Reference.

Core Components Architecture

Workspace Component Structure

flowchart TD
subgraph percpu_workspace["percpu Workspace"]
    subgraph macro_deps["Macro Dependencies"]
        PROC_MACRO2["proc-macro2"]
        SYN["syn"]
        QUOTE["quote"]
    end
    subgraph dependencies["Core Dependencies"]
        CFG_IF["cfg-if"]
        KERNEL_GUARD["kernel_guard(optional)"]
        X86_DEP["x86(x86_64 only)"]
        SPIN_DEP["spin(non-none OS)"]
    end
    subgraph percpu_macros_crate["percpu_macros Crate"]
        MACRO_LIB["lib.rsProcedural Macros"]
        DEF_PERCPU["def_percpu macro"]
        CODE_GEN["Code Generation"]
    end
    subgraph percpu_crate["percpu Crate"]
        PERCPU_LIB["lib.rsRuntime Implementation"]
        PERCPU_ACCESS["Access Methods"]
        PERCPU_INIT["Initialization Functions"]
    end
end

CODE_GEN --> PERCPU_INIT
DEF_PERCPU --> PERCPU_ACCESS
MACRO_LIB --> PROC_MACRO2
MACRO_LIB --> QUOTE
MACRO_LIB --> SYN
PERCPU_LIB --> CFG_IF
PERCPU_LIB --> KERNEL_GUARD
PERCPU_LIB --> MACRO_LIB
PERCPU_LIB --> SPIN_DEP
PERCPU_LIB --> X86_DEP

Sources: Cargo.toml(L4 - L7)  percpu/Cargo.toml(L27 - L36)  percpu_macros/Cargo.toml(L27 - L30) 

Runtime Implementation (percpuCrate)

The percpu crate provides the runtime infrastructure for per-CPU data management. It handles memory allocation, initialization, and provides safe access methods to per-CPU variables.

Key Responsibilities

Feature Configuration

The runtime crate supports three main feature flags:

• sp-naive: Single-processor mode using global variables instead of per-CPU storage
• preempt: Enables preemption safety with kernel_guard integration
• arm-el2: ARM-specific support for EL2 privilege level execution

Sources: percpu/Cargo.toml(L15 - L25) 

Macro Implementation (percpu_macrosCrate)

The percpu_macros crate provides compile-time code generation through procedural macros. It transforms user-defined per-CPU variable declarations into architecture-specific implementation code.

Macro Processing Pipeline

flowchart TD
subgraph output_components["Generated Components"]
    STORAGE_VAR["__PERCPU_VAR(.percpu section)"]
    WRAPPER_STRUCT["VarWrapper(access methods)"]
    PUBLIC_STATIC["VAR: VarWrapper(public interface)"]
end
subgraph code_generation["Code Generation"]
    ARCH_DETECT["Architecture Detection"]
    FEATURE_CHECK["Feature Flag Processing"]
    QUOTE_GEN["quote! Templates"]
end
subgraph input_parsing["Input Parsing"]
    USER_CODE["#[def_percpu]static VAR: Type = init;"]
    SYN_PARSER["syn::parse"]
    AST_TOKENS["TokenStream AST"]
end

ARCH_DETECT --> FEATURE_CHECK
AST_TOKENS --> ARCH_DETECT
FEATURE_CHECK --> QUOTE_GEN
QUOTE_GEN --> PUBLIC_STATIC
QUOTE_GEN --> STORAGE_VAR
QUOTE_GEN --> WRAPPER_STRUCT
SYN_PARSER --> AST_TOKENS
USER_CODE --> SYN_PARSER

Macro Dependencies

Sources: percpu_macros/Cargo.toml(L27 - L30)  percpu_macros/Cargo.toml(L32 - L33) 

Component Integration and Data Flow

Inter-Component Communication

flowchart TD
subgraph arch_specific["Architecture-Specific"]
    X86_SUPPORT["x86 crate(MSR operations)"]
    GS_BASE["GS_BASE register"]
    TPIDR_REGS["TPIDR_EL1/EL2"]
    GP_REG["gp register (RISC-V)"]
end
subgraph feature_integration["Feature Integration"]
    SP_NAIVE_MODE["sp-naive Mode(Global Variables)"]
    PREEMPT_GUARD["NoPreemptGuard(kernel_guard)"]
    ARM_EL2_REGS["EL2 Register Access(ARM)"]
end
subgraph runtime_components["Runtime Components"]
    INIT_FUNC["percpu::init()"]
    CPU_AREAS["Per-CPU Memory Areas"]
    ACCESS_METHODS["read_current/write_current"]
    REMOTE_ACCESS["remote_ptr/remote_ref"]
end
subgraph compile_time["Compile Time"]
    MACRO_INPUT["User Macro Invocation"]
    MACRO_PROC["percpu_macros Processing"]
    CODE_OUTPUT["Generated Runtime Code"]
end

ACCESS_METHODS --> GP_REG
ACCESS_METHODS --> TPIDR_REGS
ACCESS_METHODS --> X86_SUPPORT
CODE_OUTPUT --> ARM_EL2_REGS
CODE_OUTPUT --> INIT_FUNC
CODE_OUTPUT --> PREEMPT_GUARD
CODE_OUTPUT --> SP_NAIVE_MODE
CPU_AREAS --> ACCESS_METHODS
CPU_AREAS --> REMOTE_ACCESS
INIT_FUNC --> CPU_AREAS
MACRO_INPUT --> MACRO_PROC
MACRO_PROC --> CODE_OUTPUT
X86_SUPPORT --> GS_BASE

Workspace Configuration

The workspace is configured as a multi-crate project with shared metadata and dependency management:

• Version: 0.2.0 across all crates
• Edition: Rust 2021
• License: Triple-licensed (GPL-3.0-or-later OR Apache-2.0 OR MulanPSL-2.0)
• Target Platforms: no-std embedded systems and kernel environments

Sources: Cargo.toml(L9 - L24) 

Feature Flag Synchronization

Both crates maintain identical feature flag definitions to ensure consistent behavior across the macro generation and runtime execution phases:

This synchronization ensures that macro-generated code matches the runtime environment configuration.

Sources: percpu/Cargo.toml(L18 - L25)  percpu_macros/Cargo.toml(L18 - L25)