MEMBLOCK OVERVIEW(9)

📦 version 7.3.1, in nixpkgs unstable

💖 memblock overview(9) 💖

Kernel API Manual · the one where memory gets managed before anything else is ready

Okay so picture this: it's early boot, the usual kernel memory allocators are not up and running yet — like, nobody's at the party, the lights are off, the DJ hasn't shown. And memblock is there anyway. Memblock is literally the method of managing memory regions during the early boot period, before the real allocators wake up. Main character energy fr. 🫶

✨ the collections ✨

Memblock views the system memory as collections of contiguous regions. There are several types of these collections:

  • memory — describes the physical memory available to the kernel. this may differ from the actual physical memory installed in the system, for instance when the memory is restricted with mem= command line parameter
  • reserved — describes the regions that were allocated
  • physmem — describes the actual physical memory available during boot regardless of the possible restrictions and memory hot(un)plug; the physmem type is only available on some architectures

🌸 the structs, iykyk 🌸

Each region is represented by struct memblock_region, which defines the region extents, its attributes and NUMA node id on NUMA systems. Every memory type is described by the struct memblock_type, which contains an array of memory regions along with the allocator metadata. The memory and reserved types are nicely wrapped with struct memblock — cute, tidy, wrapped up. 🎀

This structure is statically initialized at build time. The region arrays are initially sized to INIT_MEMBLOCK_MEMORY_REGIONS for memory and INIT_MEMBLOCK_RESERVED_REGIONS for reserved. The region array for physmem is initially sized to INIT_PHYSMEM_REGIONS.

Then there's memblock_allow_resize, which enables automatic resizing of the region arrays during addition of new regions.

⚠️ bestie, this feature should be used with care so that memory allocated for the region array will not overlap with areas that should be reserved, for example initrd. like pls be careful, the vibes are delicate here.

🦋 the early setup era 🦋

The early architecture setup should tell memblock what the physical memory layout is by using memblock_add or memblock_add_node functions.

The first function does not assign the region to a NUMA node and it is appropriate for UMA systems. Yet — and this is the slay part — it is possible to use it on NUMA systems as well, and assign the region to a NUMA node later in the setup process using memblock_set_node. The memblock_add_node performs such an assignment directly. no extra steps, no notes app, just done. 💅

🔥 allocating: pick your variant 🔥

Once memblock is setup, the memory can be allocated using one of the API variants:

  • memblock_phys_alloc*() — these functions return the physical address of the allocated memory
  • memblock_alloc*() — these functions return the virtual address of the allocated memory

Note that both API variants use implicit assumptions about allowed memory ranges and the fallback methods. Consult the documentation of memblock_alloc_internal and memblock_alloc_range_nid functions for more elaborate description — they said it best, go read them. 📖

🧚 the inevitable ending 🧚

As the system boot progresses, the architecture specific mem_init function frees all the memory to the buddy page allocator. passing the torch, iconic behaviour. ✨

Unless an architecture enables CONFIG_ARCH_KEEP_MEMBLOCK, the memblock data structures (except physmem) will be discarded after the system initialization completes. gone but not forgotten ngl 💀

✨ SEE ALSO ✨

Kernel file ./mm/memblock.c — and literally all of these, go wild:

and that's the whole page bestie 🎀 this one's from ./mm, dated October 2026, and it's called memblock overview(9) — go forth and manage your early boot memory, ily, mwah 💋

📦 where this page comes from