Merge branch 'akpm' (patches from Andrew)

Pratyush Anand <pratyush.anand@gmail.com> <pratyush.anand@st.com>

Praveen BP <praveenbp@ti.com>

Qais Yousef <qsyousef@gmail.com> <qais.yousef@imgtec.com>

Oleksij Rempel <linux@rempel-privat.de> <bug-track@fisher-privat.net>

Oleksij Rempel <linux@rempel-privat.de> <external.Oleksij.Rempel@de.bosch.com>

Oleksij Rempel <linux@rempel-privat.de> <fixed-term.Oleksij.Rempel@de.bosch.com>

Oleksij Rempel <linux@rempel-privat.de> <o.rempel@pengutronix.de>

Oleksij Rempel <linux@rempel-privat.de> <ore@pengutronix.de>

Rajesh Shah <rajesh.shah@intel.com>

Ralf Baechle <ralf@linux-mips.org>

Ralf Wildenhues <Ralf.Wildenhues@gmx.de>

==============

:Created:							Jul 28 2007

:Updated: Add description of notifier of memory hotplug:	Oct 11 2007

:Updated: Add some details about locking internals:		Aug 20 2018

This document is about memory hotplug including how-to-use and current status.

Because Memory Hotplug is still under development, contents of this text will

 - Notification completion of remove works by OS to firmware.

 - Guard from remove if not yet.

Locking Internals

=================

When adding/removing memory that uses memory block devices (i.e. ordinary RAM),

the device_hotplug_lock should be held to:

- synchronize against online/offline requests (e.g. via sysfs). This way, memory

  block devices can only be accessed (.online/.state attributes) by user

  space once memory has been fully added. And when removing memory, we

  know nobody is in critical sections.

- synchronize against CPU hotplug and similar (e.g. relevant for ACPI and PPC)

Especially, there is a possible lock inversion that is avoided using

device_hotplug_lock when adding memory and user space tries to online that

memory faster than expected:

- device_online() will first take the device_lock(), followed by

  mem_hotplug_lock

- add_memory_resource() will first take the mem_hotplug_lock, followed by

  the device_lock() (while creating the devices, during bus_add_device()).

As the device is visible to user space before taking the device_lock(), this

can result in a lock inversion.

onlining/offlining of memory should be done via device_online()/

device_offline() - to make sure it is properly synchronized to actions

via sysfs. Holding device_hotplug_lock is advised (to e.g. protect online_type)

When adding/removing/onlining/offlining memory or adding/removing

heterogeneous/device memory, we should always hold the mem_hotplug_lock in

write mode to serialise memory hotplug (e.g. access to global/zone

variables).

In addition, mem_hotplug_lock (in contrast to device_hotplug_lock) in read

mode allows for a quite efficient get_online_mems/put_online_mems

implementation, so code accessing memory can protect from that memory

vanishing.

Future Work

===========

Early system initialization cannot use "normal" memory management

simply because it is not set up yet. But there is still need to

allocate memory for various data structures, for instance for the

physical page allocator. To address this, a specialized allocator

called the :ref:`Boot Memory Allocator <bootmem>`, or bootmem, was

introduced. Several years later PowerPC developers added a "Logical

Memory Blocks" allocator, which was later adopted by other

architectures and renamed to :ref:`memblock <memblock>`. There is also

a compatibility layer called `nobootmem` that translates bootmem

allocation interfaces to memblock calls.

physical page allocator.

The selection of the early allocator is done using

``CONFIG_NO_BOOTMEM`` and ``CONFIG_HAVE_MEMBLOCK`` kernel

configuration options. These options are enabled or disabled

statically by the architectures' Kconfig files.

* Architectures that rely only on bootmem select

  ``CONFIG_NO_BOOTMEM=n && CONFIG_HAVE_MEMBLOCK=n``.

* The users of memblock with the nobootmem compatibility layer set

  ``CONFIG_NO_BOOTMEM=y && CONFIG_HAVE_MEMBLOCK=y``.

* And for those that use both memblock and bootmem the configuration

  includes ``CONFIG_NO_BOOTMEM=n && CONFIG_HAVE_MEMBLOCK=y``.

Whichever allocator is used, it is the responsibility of the

architecture specific initialization to set it up in

:c:func:`setup_arch` and tear it down in :c:func:`mem_init` functions.

A specialized allocator called ``memblock`` performs the

boot time memory management. The architecture specific initialization

must set it up in :c:func:`setup_arch` and tear it down in

:c:func:`mem_init` functions.

Once the early memory management is available it offers a variety of

functions and macros for memory allocations. The allocation request

may be directed to the first (and probably the only) node or to a

particular node in a NUMA system. There are API variants that panic

when an allocation fails and those that don't. And more recent and

advanced memblock even allows controlling its own behaviour.

.. _bootmem:

Bootmem

=======

when an allocation fails and those that don't.

(mostly stolen from Mel Gorman's "Understanding the Linux Virtual

Memory Manager" `book`_)

Memblock also offers a variety of APIs that control its own behaviour.

.. _book: https://www.kernel.org/doc/gorman/

.. kernel-doc:: mm/bootmem.c

   :doc: bootmem overview

.. _memblock:

Memblock

========

Memblock Overview

=================

.. kernel-doc:: mm/memblock.c

   :doc: memblock overview

Functions and structures

========================

Common API

----------

The functions that are described in this section are available

regardless of what early memory manager is enabled.

.. kernel-doc:: mm/nobootmem.c

Bootmem specific API

--------------------

These interfaces available only with bootmem, i.e when ``CONFIG_NO_BOOTMEM=n``

.. kernel-doc:: include/linux/bootmem.h

.. kernel-doc:: mm/bootmem.c

   :functions:

Memblock specific API

---------------------

Here is the description of memblock data structures, functions and

macros. Some of them are actually internal, but since they are

documented it would be silly to omit them. Besides, reading the

	select ODD_RT_SIGACTION

	select OLD_SIGSUSPEND

	select CPU_NO_EFFICIENT_FFS if !ALPHA_EV67

	select HAVE_MEMBLOCK

	select NO_BOOTMEM

	help

	  The Alpha is a 64-bit general-purpose processor designed and

	  marketed by the Digital Equipment Corporation of blessed memory,

#include <linux/personality.h>	/* for ADDR_LIMIT_32BIT */

/*

 * Returns current instruction pointer ("program counter").

 */

#define current_text_addr() \

  ({ void *__pc; __asm__ ("br %0,.+4" : "=r"(__pc)); __pc; })

/*

 * We have a 42-bit user address space: 4TB user VM...

 */