diff mbox series

[2/2] docs/vm: split memory hotplug notifier description to Documentation/core-api

Message ID 1538691061-31289-3-git-send-email-rppt@linux.vnet.ibm.com (mailing list archive)
State New, archived
Headers show
Series docs: ReSTify memory-hotplug description | expand

Commit Message

Mike Rapoport Oct. 4, 2018, 10:11 p.m. UTC 
The memory hotplug notifier description is about kernel internals rather
than admin/user visible API. Place it appropriately.

Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
---
 Documentation/admin-guide/mm/memory-hotplug.rst    | 83 ---------------------
 Documentation/core-api/index.rst                   |  2 +
 Documentation/core-api/memory-hotplug-notifier.rst | 84 ++++++++++++++++++++++
 3 files changed, 86 insertions(+), 83 deletions(-)
 create mode 100644 Documentation/core-api/memory-hotplug-notifier.rst

Comments

Jonathan Corbet Oct. 7, 2018, 2:46 p.m. UTC | #1 
On Fri,  5 Oct 2018 01:11:01 +0300
Mike Rapoport <rppt@linux.vnet.ibm.com> wrote:

> The memory hotplug notifier description is about kernel internals rather
> than admin/user visible API. Place it appropriately.
> 
> Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>

One little nit...

>  Documentation/admin-guide/mm/memory-hotplug.rst    | 83 ---------------------
>  Documentation/core-api/index.rst                   |  2 +
>  Documentation/core-api/memory-hotplug-notifier.rst | 84 ++++++++++++++++++++++
>  3 files changed, 86 insertions(+), 83 deletions(-)
>  create mode 100644 Documentation/core-api/memory-hotplug-notifier.rst
> 
> diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst b/Documentation/admin-guide/mm/memory-hotplug.rst
> index a33090c..0b9c83e 100644
> --- a/Documentation/admin-guide/mm/memory-hotplug.rst
> +++ b/Documentation/admin-guide/mm/memory-hotplug.rst
> @@ -31,7 +31,6 @@ be changed often.
>      6.1 Memory offline and ZONE_MOVABLE
>      6.2. How to offline memory
>    7. Physical memory remove
> -  8. Memory hotplug event notifier
>    9. Future Work List

That leaves a gap in the numbering here.

In general, the best solution to this sort of issue is to take the TOC out
entirely and let Sphinx worry about generating it.  People tend not to
think about updating the TOC when they make changes elsewhere, so it often
goes out of sync with the rest of the document anyway.

I'll apply these, but please feel free to send a patch to fix this up.

Thanks,

jon
Mike Rapoport Oct. 7, 2018, 4:32 p.m. UTC | #2 
On Sun, Oct 07, 2018 at 08:46:40AM -0600, Jonathan Corbet wrote:
> On Fri,  5 Oct 2018 01:11:01 +0300
> Mike Rapoport <rppt@linux.vnet.ibm.com> wrote:
> 
> > The memory hotplug notifier description is about kernel internals rather
> > than admin/user visible API. Place it appropriately.
> > 
> > Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
> 
> One little nit...
> 
> >  Documentation/admin-guide/mm/memory-hotplug.rst    | 83 ---------------------
> >  Documentation/core-api/index.rst                   |  2 +
> >  Documentation/core-api/memory-hotplug-notifier.rst | 84 ++++++++++++++++++++++
> >  3 files changed, 86 insertions(+), 83 deletions(-)
> >  create mode 100644 Documentation/core-api/memory-hotplug-notifier.rst
> > 
> > diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst b/Documentation/admin-guide/mm/memory-hotplug.rst
> > index a33090c..0b9c83e 100644
> > --- a/Documentation/admin-guide/mm/memory-hotplug.rst
> > +++ b/Documentation/admin-guide/mm/memory-hotplug.rst
> > @@ -31,7 +31,6 @@ be changed often.
> >      6.1 Memory offline and ZONE_MOVABLE
> >      6.2. How to offline memory
> >    7. Physical memory remove
> > -  8. Memory hotplug event notifier
> >    9. Future Work List
> 
> That leaves a gap in the numbering here.
> 
> In general, the best solution to this sort of issue is to take the TOC out
> entirely and let Sphinx worry about generating it.  People tend not to
> think about updating the TOC when they make changes elsewhere, so it often
> goes out of sync with the rest of the document anyway.
> 
> I'll apply these, but please feel free to send a patch to fix this up.

Sure, below
 
> Thanks,
> 
> jon
> 

From 45ef951bd04e9d440a0158f991a188fc8ca6e7d4 Mon Sep 17 00:00:00 2001
From: Mike Rapoport <rppt@linux.vnet.ibm.com>
Date: Sun, 7 Oct 2018 19:29:00 +0300
Subject: [PATCH] docs/admin-guide: memory-hotplug: remove table of contents

Remove "manual" table of contents and leave only the ReST tag so that
Sphinx will take care of TOC generation.

Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
---
 Documentation/admin-guide/mm/memory-hotplug.rst | 21 ---------------------
 1 file changed, 21 deletions(-)

diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst b/Documentation/admin-guide/mm/memory-hotplug.rst
index 0b9c83e..25157ae 100644
--- a/Documentation/admin-guide/mm/memory-hotplug.rst
+++ b/Documentation/admin-guide/mm/memory-hotplug.rst
@@ -13,27 +13,6 @@ be changed often.
 
 .. contents:: :local:
 
-.. CONTENTS
-
-  1. Introduction
-    1.1 Purpose of memory hotplug
-    1.2. Phases of memory hotplug
-    1.3. Unit of Memory online/offline operation
-  2. Kernel Configuration
-  3. sysfs files for memory hotplug
-  4. Physical memory hot-add phase
-    4.1 Hardware(Firmware) Support
-    4.2 Notify memory hot-add event by hand
-  5. Logical Memory hot-add phase
-    5.1. State of memory
-    5.2. How to online memory
-  6. Logical memory remove
-    6.1 Memory offline and ZONE_MOVABLE
-    6.2. How to offline memory
-  7. Physical memory remove
-  9. Future Work List
-
-
 .. note::
 
     (1) x86_64's has special implementation for memory hotplug.
diff mbox series

Patch

diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst b/Documentation/admin-guide/mm/memory-hotplug.rst
index a33090c..0b9c83e 100644
--- a/Documentation/admin-guide/mm/memory-hotplug.rst
+++ b/Documentation/admin-guide/mm/memory-hotplug.rst
@@ -31,7 +31,6 @@  be changed often.
     6.1 Memory offline and ZONE_MOVABLE
     6.2. How to offline memory
   7. Physical memory remove
-  8. Memory hotplug event notifier
   9. Future Work List
 
 
@@ -414,88 +413,6 @@  Need more implementation yet....
  - Notification completion of remove works by OS to firmware.
  - Guard from remove if not yet.
 
-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 MEMORY_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 MEMORY_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.
-
 Future Work
 ===========
 
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 165d7688..4f8a426 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -32,6 +32,8 @@  Core utilities
    gfp_mask-from-fs-io
    timekeeping
    boot-time-mm
+   memory-hotplug-notifier
+
 
 Interfaces for kernel debugging
 ===============================
diff --git a/Documentation/core-api/memory-hotplug-notifier.rst b/Documentation/core-api/memory-hotplug-notifier.rst
new file mode 100644
index 0000000..35347cc
--- /dev/null
+++ b/Documentation/core-api/memory-hotplug-notifier.rst
@@ -0,0 +1,84 @@ 
+.. _memory_hotplug_notifier:
+
+=============================
+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.