pcpu_embed_first_chunk(9)

📦 version 7.3.1, in nixpkgs unstable

💖 pcpu_embed_first_chunk — Kernel API Manual ✨

okay so bestie, welcome to the pcpu_embed_first_chunk(9) page from the Kernel API Manual 💅 this one's all about embedding the first percpu chunk into bootmem, and honestly? it's giving allocation realness 🎀

🌸 NAME 🌸

pcpu_embed_first_chunk — embed the first percpu chunk into bootmem 🧚

✨ SYNOPSIS ✨

int pcpu_embed_first_chunk (size_t reserved_size , size_t dyn_size ,
size_t atom_size , pcpu_fc_cpu_distance_fn_t cpu_distance_fn ,
pcpu_fc_cpu_to_node_fn_t cpu_to_nd_fn );

like, that's the whole signature, no cap 💜

🦋 ARGUMENTS 🦋

  • reserved_size — the size of the reserved percpu area, in bytes 📏
  • dyn_size — the minimum free size for dynamic allocation, in bytes 🍓
  • atom_size — the allocation atom size ⭐
  • cpu_distance_fn — a callback to determine the distance between cpus; it's optional, so no pressure 🫶
  • cpu_to_nd_fn — a callback to convert a cpu to its node; also optional 🙈

💀 DESCRIPTION 💀

so this function is a little helper whose whole job is to make setting up the embedded first percpu chunk easier, and you can call it anywhere pcpu_setup_first_chunk is expected 👑

if this function is what you use to set up the first chunk, then that chunk gets allocated by calling pcpu_fc_alloc and it's used as-is, like literally without being mapped into the vmalloc area 😭

allocations are always whole multiples of atom_size, aligned to atom_size — that's the vibe check it always passes ✨

this is what lets the first chunk piggy back on the linear physical mapping, which often uses a larger page size 🔥

⚠️ but bestie, please note: this can result in a very sparse cpu->unit mapping on NUMA machines, which then requires a large vmalloc address space. so don't use this allocator if vmalloc space is not orders of magnitude larger than the distances between node memory addresses (ie. 32bit NUMA machines). like, that's the warning, take it seriously 💅

dyn_size specifies the minimum dynamic area size 🌈

and if the needed size is smaller than the minimum or the specified unit size, the leftover is returned using pcpu_fc_free 🎀

⭐ RETURN ⭐

0 on success, -errno on failure 😤 that's it, that's the whole return section, and yes it ate 💖

💜 SEE ALSO 💜

the kernel file ./mm/percpu.c, plus this whole friend group of functions (iykyk) 🦋:

and that's the whole page, bestie 🫶 this one lives in ./mm and it's dated October 2026 — mwah, go forth and embed your chunks 💋👑

📦 where this page comes from