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