Documentation/core-api/boot-time-mm.rst

   1 ===========================
   2 Boot time memory management
   3 ===========================
   4
   5 Early system initialization cannot use "normal" memory management
   6 simply because it is not set up yet. But there is still need to
   7 allocate memory for various data structures, for instance for the
   8 physical page allocator. To address this, a specialized allocator
   9 called the :ref:`Boot Memory Allocator <bootmem>`, or bootmem, was
  10 introduced. Several years later PowerPC developers added a "Logical
  11 Memory Blocks" allocator, which was later adopted by other
  12 architectures and renamed to :ref:`memblock <memblock>`. There is also
  13 a compatibility layer called `nobootmem` that translates bootmem
  14 allocation interfaces to memblock calls.
  15
  16 The selection of the early allocator is done using
  17 ``CONFIG_NO_BOOTMEM`` and ``CONFIG_HAVE_MEMBLOCK`` kernel
  18 configuration options. These options are enabled or disabled
  19 statically by the architectures' Kconfig files.
  20
  21 * Architectures that rely only on bootmem select
  22   ``CONFIG_NO_BOOTMEM=n && CONFIG_HAVE_MEMBLOCK=n``.
  23 * The users of memblock with the nobootmem compatibility layer set
  24   ``CONFIG_NO_BOOTMEM=y && CONFIG_HAVE_MEMBLOCK=y``.
  25 * And for those that use both memblock and bootmem the configuration
  26   includes ``CONFIG_NO_BOOTMEM=n && CONFIG_HAVE_MEMBLOCK=y``.
  27
  28 Whichever allocator is used, it is the responsibility of the
  29 architecture specific initialization to set it up in
  30 :c:func:`setup_arch` and tear it down in :c:func:`mem_init` functions.
  31
  32 Once the early memory management is available it offers a variety of
  33 functions and macros for memory allocations. The allocation request
  34 may be directed to the first (and probably the only) node or to a
  35 particular node in a NUMA system. There are API variants that panic
  36 when an allocation fails and those that don't. And more recent and
  37 advanced memblock even allows controlling its own behaviour.
  38
  39 .. _bootmem:
  40
  41 Bootmem
  42 =======
  43
  44 (mostly stolen from Mel Gorman's "Understanding the Linux Virtual
  45 Memory Manager" `book`_)
  46
  47 .. _book: https://www.kernel.org/doc/gorman/
  48
  49 .. kernel-doc:: mm/bootmem.c
  50    :doc: bootmem overview
  51
  52 .. _memblock:
  53
  54 Memblock
  55 ========
  56
  57 .. kernel-doc:: mm/memblock.c
  58    :doc: memblock overview
  59
  60
  61 Functions and structures
  62 ========================
  63
  64 Common API
  65 ----------
  66
  67 The functions that are described in this section are available
  68 regardless of what early memory manager is enabled.
  69
  70 .. kernel-doc:: mm/nobootmem.c
  71
  72 Bootmem specific API
  73 --------------------
  74
  75 These interfaces available only with bootmem, i.e when ``CONFIG_NO_BOOTMEM=n``
  76
  77 .. kernel-doc:: include/linux/bootmem.h
  78 .. kernel-doc:: mm/bootmem.c
  79    :functions:
  80
  81 Memblock specific API
  82 ---------------------
  83
  84 Here is the description of memblock data structures, functions and
  85 macros. Some of them are actually internal, but since they are
  86 documented it would be silly to omit them. Besides, reading the
  87 descriptions for the internal functions can help to understand what
  88 really happens under the hood.
  89
  90 .. kernel-doc:: include/linux/memblock.h
  91 .. kernel-doc:: mm/memblock.c
  92    :functions: