[mirror_ubuntu-jammy-kernel.git] / Documentation / core-api / memory-hotplug.rst

.. _memory_hotplug:

==============
Memory hotplug
==============

Memory hotplug event notifier
=============================

Hotplugging events are sent to a notification queue.

There are six types of notification defined in ``include/linux/memory.h``:

MEM_GOING_ONLINE
  Generated before new memory becomes available in order to be able to
  prepare subsystems to handle memory. The page allocator is still unable
  to allocate from the new memory.

MEM_CANCEL_ONLINE
  Generated if MEM_GOING_ONLINE fails.

MEM_ONLINE
  Generated when memory has successfully brought online. The callback may
  allocate pages from the new memory.

MEM_GOING_OFFLINE
  Generated to begin the process of offlining memory. Allocations are no
  longer possible from the memory but some of the memory to be offlined
  is still in use. The callback can be used to free memory known to a
  subsystem from the indicated memory block.

MEM_CANCEL_OFFLINE
  Generated if MEM_GOING_OFFLINE fails. Memory is available again from
  the memory block that we attempted to offline.

MEM_OFFLINE
  Generated after offlining memory is complete.

A callback routine can be registered by calling::

  hotplug_memory_notifier(callback_func, priority)

Callback functions with higher values of priority are called before callback
functions with lower values.

A callback function must have the following prototype::

  int callback_func(
    struct notifier_block *self, unsigned long action, void *arg);

The first argument of the callback function (self) is a pointer to the block
of the notifier chain that points to the callback function itself.
The second argument (action) is one of the event types described above.
The third argument (arg) passes a pointer of struct memory_notify::

	struct memory_notify {
		unsigned long start_pfn;
		unsigned long nr_pages;
		int status_change_nid_normal;
		int status_change_nid_high;
		int status_change_nid;
	}

- start_pfn is start_pfn of online/offline memory.
- nr_pages is # of pages of online/offline memory.
- status_change_nid_normal is set node id when N_NORMAL_MEMORY of nodemask
  is (will be) set/clear, if this is -1, then nodemask status is not changed.
- status_change_nid_high is set node id when N_HIGH_MEMORY of nodemask
  is (will be) set/clear, if this is -1, then nodemask status is not changed.
- status_change_nid is set node id when N_MEMORY of nodemask is (will be)
  set/clear. It means a new(memoryless) node gets new memory by online and a
  node loses all memory. If this is -1, then nodemask status is not changed.

  If status_changed_nid* >= 0, callback should create/discard structures for the
  node if necessary.

The callback routine shall return one of the values
NOTIFY_DONE, NOTIFY_OK, NOTIFY_BAD, NOTIFY_STOP
defined in ``include/linux/notifier.h``

NOTIFY_DONE and NOTIFY_OK have no effect on the further processing.

NOTIFY_BAD is used as response to the MEM_GOING_ONLINE, MEM_GOING_OFFLINE,
MEM_ONLINE, or MEM_OFFLINE action to cancel hotplugging. It stops
further processing of the notification queue.

NOTIFY_STOP stops further processing of the notification queue.

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.
Commit	Line	Data
52d7e21f MR	1	.. _memory_hotplug:
	2
	3	==============
	4	Memory hotplug
	5	==============
98cee674	6
98cee674 MR	7	Memory hotplug event notifier
	8	=============================
	9
	10	Hotplugging events are sent to a notification queue.
	11
	12	There are six types of notification defined in ``include/linux/memory.h``:
	13
	14	MEM_GOING_ONLINE
	15	Generated before new memory becomes available in order to be able to
	16	prepare subsystems to handle memory. The page allocator is still unable
	17	to allocate from the new memory.
	18
	19	MEM_CANCEL_ONLINE
	20	Generated if MEM_GOING_ONLINE fails.
	21
	22	MEM_ONLINE
	23	Generated when memory has successfully brought online. The callback may
	24	allocate pages from the new memory.
	25
	26	MEM_GOING_OFFLINE
	27	Generated to begin the process of offlining memory. Allocations are no
	28	longer possible from the memory but some of the memory to be offlined
	29	is still in use. The callback can be used to free memory known to a
	30	subsystem from the indicated memory block.
	31
	32	MEM_CANCEL_OFFLINE
	33	Generated if MEM_GOING_OFFLINE fails. Memory is available again from
	34	the memory block that we attempted to offline.
	35
	36	MEM_OFFLINE
	37	Generated after offlining memory is complete.
	38
	39	A callback routine can be registered by calling::
	40
	41	hotplug_memory_notifier(callback_func, priority)
	42
	43	Callback functions with higher values of priority are called before callback
	44	functions with lower values.
	45
	46	A callback function must have the following prototype::
	47
	48	int callback_func(
	49	struct notifier_block self, unsigned long action, void arg);
	50
	51	The first argument of the callback function (self) is a pointer to the block
	52	of the notifier chain that points to the callback function itself.
	53	The second argument (action) is one of the event types described above.
	54	The third argument (arg) passes a pointer of struct memory_notify::
	55
	56	struct memory_notify {
	57	unsigned long start_pfn;
	58	unsigned long nr_pages;
	59	int status_change_nid_normal;
	60	int status_change_nid_high;
	61	int status_change_nid;
	62	}
	63
	64	- start_pfn is start_pfn of online/offline memory.
	65	- nr_pages is # of pages of online/offline memory.
	66	- status_change_nid_normal is set node id when N_NORMAL_MEMORY of nodemask
	67	is (will be) set/clear, if this is -1, then nodemask status is not changed.
	68	- status_change_nid_high is set node id when N_HIGH_MEMORY of nodemask
	69	is (will be) set/clear, if this is -1, then nodemask status is not changed.
	70	- status_change_nid is set node id when N_MEMORY of nodemask is (will be)
71	set/clear. It means a new(memoryless) node gets new memory by online and a
72	node loses all memory. If this is -1, then nodemask status is not changed.
73
74	If status_changed_nid* >= 0, callback should create/discard structures for the
75	node if necessary.
76
77	The callback routine shall return one of the values
78	NOTIFY_DONE, NOTIFY_OK, NOTIFY_BAD, NOTIFY_STOP
79	defined in ``include/linux/notifier.h``
80
81	NOTIFY_DONE and NOTIFY_OK have no effect on the further processing.
82
83	NOTIFY_BAD is used as response to the MEM_GOING_ONLINE, MEM_GOING_OFFLINE,
84	MEM_ONLINE, or MEM_OFFLINE action to cancel hotplugging. It stops
85	further processing of the notification queue.
86
87	NOTIFY_STOP stops further processing of the notification queue.
3a7452c5 DH	88
	89	Locking Internals
	90	=================
	91
	92	When adding/removing memory that uses memory block devices (i.e. ordinary RAM),
	93	the device_hotplug_lock should be held to:
	94
	95	- synchronize against online/offline requests (e.g. via sysfs). This way, memory
	96	block devices can only be accessed (.online/.state attributes) by user
	97	space once memory has been fully added. And when removing memory, we
	98	know nobody is in critical sections.
	99	- synchronize against CPU hotplug and similar (e.g. relevant for ACPI and PPC)
	100
	101	Especially, there is a possible lock inversion that is avoided using
	102	device_hotplug_lock when adding memory and user space tries to online that
	103	memory faster than expected:
	104
	105	- device_online() will first take the device_lock(), followed by
	106	mem_hotplug_lock
	107	- add_memory_resource() will first take the mem_hotplug_lock, followed by
	108	the device_lock() (while creating the devices, during bus_add_device()).
	109
	110	As the device is visible to user space before taking the device_lock(), this
	111	can result in a lock inversion.
	112
	113	onlining/offlining of memory should be done via device_online()/
	114	device_offline() - to make sure it is properly synchronized to actions
	115	via sysfs. Holding device_hotplug_lock is advised (to e.g. protect online_type)
	116
	117	When adding/removing/onlining/offlining memory or adding/removing
	118	heterogeneous/device memory, we should always hold the mem_hotplug_lock in
	119	write mode to serialise memory hotplug (e.g. access to global/zone
	120	variables).
	121
	122	In addition, mem_hotplug_lock (in contrast to device_hotplug_lock) in read
	123	mode allows for a quite efficient get_online_mems/put_online_mems
	124	implementation, so code accessing memory can protect from that memory
	125	vanishing.