Crate percpu

source ·
Expand description

Define and access per-CPU data structures.

All per-CPU data is placed into several contiguous memory regions called per-CPU data areas, the number of which is the number of CPUs. Each CPU has its own per-CPU data area. The architecture-specific thread pointer register (e.g., GS_BASE on x86_64) is set to the base address of the area on initialization.

When accessing the per-CPU data on the current CPU, it first use the thread pointer register to obtain the corresponding per-CPU data area, and then add an offset to access the corresponding field.

Notes

Since RISC-V does not provide separate thread pointer registers for user and kernel mode, we temporarily use the gp register to point to the per-CPU data area, while the tp register is used for thread-local storage.

Examples

#[percpu::def_percpu]
static CPU_ID: usize = 0;

// initialize per-CPU data for 4 CPUs.
percpu::init(4);
// set the thread pointer register to the per-CPU data area 0.
percpu::set_local_thread_pointer(0);

// access the per-CPU data `CPU_ID` on the current CPU.
println!("{}", CPU_ID.read_current()); // prints "0"
CPU_ID.write_current(1);
println!("{}", CPU_ID.read_current()); // prints "1"

Cargo Features

  • sp-naive: For single-core use. In this case, each per-CPU data is just a global variable, architecture-specific thread pointer register is not used.
  • preempt: For preemptible system use. In this case, we need to disable preemption when accessing per-CPU data. Otherwise, the data may be corrupted when it’s being accessing and the current thread happens to be preempted.

Structs

Statics

Functions

  • get_local_thread_pointer
    Read the architecture-specific thread pointer register on the current CPU.
  • init
    Initialize the per-CPU data area for max_cpu_num CPUs.
  • percpu_area_base
    Returns the base address of the per-CPU data area on the given CPU.
  • percpu_area_size
    Returns the per-CPU data area size for one CPU.
  • set_local_thread_pointer
    Set the architecture-specific thread pointer register to the per-CPU data area base on the current CPU.

Attribute Macros