Skip to main content

Crate ax_cpu

Crate ax_cpu 

Source
Expand description

ax-cpu

Privileged instruction and structure abstractions for various CPU architectures

Crates.io Docs.rs Rust License

English | 中文

§Introduction

ax-cpu provides Privileged instruction and structure abstractions for various CPU architectures. It is maintained as part of the TGOSKits component set and is intended for Rust projects that integrate with ArceOS, AxVisor, or related low-level systems software.

ax-cpu was derived from https://github.com/arceos-org/axcpu

§TLS and userspace features

tls requests kernel thread-local storage. uspace takes precedence over tls: enabling both selects the same register ownership and context-switch path as uspace alone, without kernel TLS. User-space TLS is still saved and restored by the user-context APIs. Kernel thread-pointer accessors are available only when tls is enabled and uspace is disabled. build.rs derives the internal kernel_tls cfg; callers should select Cargo features instead of setting this cfg themselves. Existing single-feature modes keep their behavior and task-context layout.

§Quick Start

§Installation

Add this crate to your Cargo.toml:

[dependencies]
ax-cpu = "0.5.0"

§Run Check and Test

# Enter the crate directory
cd components/axcpu

# Format code
cargo fmt --all

# Run clippy
cargo clippy --all-targets --all-features

# Run tests
cargo test --all-features

# Build documentation
cargo doc --no-deps

§Integration

§Example

use ax_cpu as _;

fn main() {
    // Integrate `ax-cpu` into your project here.
}

§Documentation

Generate and view API documentation:

cargo doc --no-deps --open

Online documentation: docs.rs/ax-cpu

§Contributing

  1. Fork the repository and create a branch
  2. Run local format and checks
  3. Run local tests relevant to this crate
  4. Submit a PR and ensure CI passes

§License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Re-exports§

pub use trap::TrapOrigin;

Modules§

asm
Wrapper functions for assembly instructions.
cap
CPU capability helpers.
init
Helper functions to initialize the CPU states on systems bootstrapping.
paging
Page-table metadata for the active architecture.
trap
Trap handling.
uspaceuspace
Structures and functions for user space.

Structs§

ExtendedState
Extended state of a task, such as FP/SIMD states.
FxsaveArea
A 512-byte memory region for the FXSAVE/FXRSTOR instruction to save and restore the x87 FPU, MMX, XMM, and MXCSR registers.
InstalledAddressSpace
Complete software identity installed with one hardware page-table root.
KernelTlsBase
Kernel task-local storage base owned by one execution context.
KernelTrapFrame
Lifetime-bound view of a kernel-origin x86 trap frame.
TaskContext
Saved hardware states of a task.
TaskLocalState
Architecture-neutral task state participating in the final switch tail.
UserRegisters
Saved registers when a trap (interrupt or exception) occurs.
UserXstate
A 64-byte-aligned memory region for the XSAVE/XRSTOR instructions, which save and restore the full XCR0-enabled extended state (x87, SSE/XMM, and the upper 128 bits of the AVX YMM registers that FXSAVE/FXRSTOR drop).

Enums§

InstalledAddressSpaceMode
Hardware tag policy carried with an installed userspace address space.
UserAccessErroruspace
Failure returned by a nofault user read.
UserAccessTypeuspace
Direction of an architecture-level user-memory access check.
UserAtomicErroruspace
Failure returned by a nofault user atomic operation.
UserAtomicU32Opuspace
Atomic operation supported by user_atomic_u32.

Functions§

user_atomic_u32⚠uspace
Atomically updates one aligned user-space word without resolving faults.
user_read_u32⚠uspace
Reads one aligned user-space word without resolving faults.