linux-next: manual merge of the akpm tree with the jc_docs tree

linux-next: manual merge of the akpm tree with the jc_docs tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 6427 bytes --]

Hi all,

Today's linux-next merge of the akpm tree got conflicts in:

  Documentation/memory-hotplug.txt
  Documentation/admin-guide/mm/memory-hotplug.rst

between commits:

  6bf53999a3a2 ("docs: move memory hotplug description into admin-guide/mm")
  98cee6742c80 ("docs/vm: split memory hotplug notifier description to Documentation/core-api")

from the jc_docs tree and patch:

  "memory-hotplug.txt: add some details about locking internals"

from the akpm tree.

I fixed it up (see below) and can carry the fix as necessary. This
is now fixed as far as linux-next is concerned, but any non trivial
conflicts should be mentioned to your upstream maintainer when your tree
is submitted for merging.  You may also want to consider cooperating
with the maintainer of the conflicting tree to minimise any particularly
complex conflicts.

-- 
Cheers,
Stephen Rothwell

diff --cc Documentation/admin-guide/mm/memory-hotplug.rst
index 0b9c83effaa4,ce4faa5530fa..000000000000
--- a/Documentation/admin-guide/mm/memory-hotplug.rst
+++ b/Documentation/admin-guide/mm/memory-hotplug.rst
@@@ -413,6 -413,128 +413,46 @@@ 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.
 -
+ 
+ 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
  ===========
  

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: linux-next: manual merge of the akpm tree with the jc_docs tree

[Mike Rapoport]

On Mon, Oct 08, 2018 at 06:38:40PM +1100, Stephen Rothwell wrote:
> Hi all,
> 
> Today's linux-next merge of the akpm tree got conflicts in:
> 
>   Documentation/memory-hotplug.txt
>   Documentation/admin-guide/mm/memory-hotplug.rst
> 
> between commits:
> 
>   6bf53999a3a2 ("docs: move memory hotplug description into admin-guide/mm")
>   98cee6742c80 ("docs/vm: split memory hotplug notifier description to Documentation/core-api")
> 
> from the jc_docs tree and patch:
> 
>   "memory-hotplug.txt: add some details about locking internals"
> 
> from the akpm tree.
> 
> I fixed it up (see below) and can carry the fix as necessary. This
> is now fixed as far as linux-next is concerned, but any non trivial
> conflicts should be mentioned to your upstream maintainer when your tree
> is submitted for merging.  You may also want to consider cooperating
> with the maintainer of the conflicting tree to minimise any particularly
> complex conflicts.

Somehow I've managed to miss the patches from David :(

I should have called the new
Documentation/core-api/memory-hotplug-notifier.rst memory-hotplug.rst and
then the details about locking would fit there just fine.

I can do the renaming and add the patch

  "memory-hotplug.txt: add some details about locking internals"

on top of the jc_docs tree.

Does it sound Ok?

> -- 
> Cheers,
> Stephen Rothwell
> 
> diff --cc Documentation/admin-guide/mm/memory-hotplug.rst
> index 0b9c83effaa4,ce4faa5530fa..000000000000
> --- a/Documentation/admin-guide/mm/memory-hotplug.rst
> +++ b/Documentation/admin-guide/mm/memory-hotplug.rst
> @@@ -413,6 -413,128 +413,46 @@@ 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.
>  -
> + 
> + 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
>   ===========
>   



-- 
Sincerely yours,
Mike.

Re: linux-next: manual merge of the akpm tree with the jc_docs tree

[David Hildenbrand]

On 08/10/2018 10:13, Mike Rapoport wrote:
> On Mon, Oct 08, 2018 at 06:38:40PM +1100, Stephen Rothwell wrote:
>> Hi all,
>>
>> Today's linux-next merge of the akpm tree got conflicts in:
>>
>>   Documentation/memory-hotplug.txt
>>   Documentation/admin-guide/mm/memory-hotplug.rst
>>
>> between commits:
>>
>>   6bf53999a3a2 ("docs: move memory hotplug description into admin-guide/mm")
>>   98cee6742c80 ("docs/vm: split memory hotplug notifier description to Documentation/core-api")
>>
>> from the jc_docs tree and patch:
>>
>>   "memory-hotplug.txt: add some details about locking internals"
>>
>> from the akpm tree.
>>
>> I fixed it up (see below) and can carry the fix as necessary. This
>> is now fixed as far as linux-next is concerned, but any non trivial
>> conflicts should be mentioned to your upstream maintainer when your tree
>> is submitted for merging.  You may also want to consider cooperating
>> with the maintainer of the conflicting tree to minimise any particularly
>> complex conflicts.
> 
> Somehow I've managed to miss the patches from David :(
> 
> I should have called the new
> Documentation/core-api/memory-hotplug-notifier.rst memory-hotplug.rst and
> then the details about locking would fit there just fine.
> 

Yes, my changes certainly don't belong into the admin guide, so having
internal memory-hotplug.rst sounds good to me.

> I can do the renaming and add the patch
> 
>   "memory-hotplug.txt: add some details about locking internals"
> 
> on top of the jc_docs tree.
> 
> Does it sound Ok?
> 

Fine with me.

Thanks!

-- 

Thanks,

David / dhildenb

Re: linux-next: manual merge of the akpm tree with the jc_docs tree

[Jonathan Corbet]

On Mon, 8 Oct 2018 10:38:29 +0200
David Hildenbrand <david@redhat.com> wrote:

> > I can do the renaming and add the patch
> > 
> >   "memory-hotplug.txt: add some details about locking internals"
> > 
> > on top of the jc_docs tree.
> > 
> > Does it sound Ok?
> >   
> 
> Fine with me.

Works for me too.

Andrew, what is your preference for mm docs patches going forward?  It
seems we should try to focus them on one tree or the other.  My preference
would be to keep carrying them to avoid conflicts elsewhere, but I can
certainly direct them youward if you'd rather they went that way.

Thanks,

jon

Re: linux-next: manual merge of the akpm tree with the jc_docs tree

[Andrew Morton]

On Mon, 8 Oct 2018 08:32:28 -0600 Jonathan Corbet <corbet@lwn.net> wrote:

> On Mon, 8 Oct 2018 10:38:29 +0200
> David Hildenbrand <david@redhat.com> wrote:
> 
> > > I can do the renaming and add the patch
> > > 
> > >   "memory-hotplug.txt: add some details about locking internals"
> > > 
> > > on top of the jc_docs tree.
> > > 
> > > Does it sound Ok?
> > >   
> > 
> > Fine with me.
> 
> Works for me too.
> 
> Andrew, what is your preference for mm docs patches going forward?  It
> seems we should try to focus them on one tree or the other.  My preference
> would be to keep carrying them to avoid conflicts elsewhere, but I can
> certainly direct them youward if you'd rather they went that way.

Gee.  Case-by-case, I guess.  A lot of these changes are three-line
alterations as part of a larger patch which necessitated that
alteration.

linux-next: manual merge of the akpm tree with the jc_docs tree

[Stephen Rothwell]

[-- Attachment #1: Type: text/plain, Size: 3552 bytes --]

Hi all,

Today's linux-next merge of the akpm tree got a conflict in:

  Documentation/dev-tools/kasan.rst

between commit:

  1a37e18bd4b9 ("Documentation: fix typos in dev-tools/kasan.rst")

from the jc_docs tree and commit:

  bb26c2574ff9 ("kasan: update documentation")

from the akpm tree.

I fixed it up (see below) and can carry the fix as necessary. This
is now fixed as far as linux-next is concerned, but any non trivial
conflicts should be mentioned to your upstream maintainer when your tree
is submitted for merging.  You may also want to consider cooperating
with the maintainer of the conflicting tree to minimise any particularly
complex conflicts.

-- 
Cheers,
Stephen Rothwell

diff --cc Documentation/dev-tools/kasan.rst
index 6d9abe57feaa,0d5d77919b1a..000000000000
--- a/Documentation/dev-tools/kasan.rst
+++ b/Documentation/dev-tools/kasan.rst
@@@ -357,37 -410,30 +410,30 @@@ Or, if one of the tests failed:
  
          not ok 1 - kasan
  
- (1) Loadable Module
- ~~~~~~~~~~~~~~~~~~~~
+ 
+ There are a few ways to run KUnit-compatible KASAN tests.
+ 
+ 1. Loadable module
+ ~~~~~~~~~~~~~~~~~~
  
  With ``CONFIG_KUNIT`` enabled, ``CONFIG_KASAN_KUNIT_TEST`` can be built as
- a loadable module and run on any architecture that supports KASAN
- using something like insmod or modprobe. The module is called ``test_kasan``.
+ a loadable module and run on any architecture that supports KASAN by loading
+ the module with insmod or modprobe. The module is called ``test_kasan``.
  
- (2) Built-In
- ~~~~~~~~~~~~~
+ 2. Built-In
+ ~~~~~~~~~~~
  
  With ``CONFIG_KUNIT`` built-in, ``CONFIG_KASAN_KUNIT_TEST`` can be built-in
- on any architecture that supports KASAN. These and any other KUnit
- tests enabled will run and print the results at boot as a late-init
- call.
 -on any architecure that supports KASAN. These and any other KUnit tests enabled
++on any architecture that supports KASAN. These and any other KUnit tests enabled
+ will run and print the results at boot as a late-init call.
  
- (3) Using kunit_tool
- ~~~~~~~~~~~~~~~~~~~~~
+ 3. Using kunit_tool
+ ~~~~~~~~~~~~~~~~~~~
  
- With ``CONFIG_KUNIT`` and ``CONFIG_KASAN_KUNIT_TEST`` built-in, we can also
- use kunit_tool to see the results of these along with other KUnit
- tests in a more readable way. This will not print the KASAN reports
- of tests that passed. Use `KUnit documentation <https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html>`_ for more up-to-date
- information on kunit_tool.
+ With ``CONFIG_KUNIT`` and ``CONFIG_KASAN_KUNIT_TEST`` built-in, it's also
+ possible use ``kunit_tool`` to see the results of these and other KUnit tests
+ in a more readable way. This will not print the KASAN reports of the tests that
+ passed. Use `KUnit documentation <https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html>`_
+ for more up-to-date information on ``kunit_tool``.
  
  .. _KUnit: https://www.kernel.org/doc/html/latest/dev-tools/kunit/index.html
- 
- ``CONFIG_TEST_KASAN_MODULE`` is a set of KASAN tests that could not be
- converted to KUnit. These tests can be run only as a module with
- ``CONFIG_TEST_KASAN_MODULE`` built as a loadable module and
- ``CONFIG_KASAN`` built-in. The type of error expected and the
- function being run is printed before the expression expected to give
- an error. Then the error is printed, if found, and that test
- should be interpreted to pass only if the error was the one expected
- by the test.

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: linux-next: manual merge of the akpm tree with the jc_docs tree

[Mimi Zohar]

On Wed, 2016-11-09 at 15:19 +1100, Stephen Rothwell wrote:
> Hi Andrew,
> 
> Today's linux-next merge of the akpm tree got a conflict in:
> 
>   Documentation/admin-guide/kernel-parameters.rst
> 
> between commit:
> 
>   e52347bd66f6 ("Documentation/admin-guide: split the kernel parameter list to a separate file")
> 
> from the jc_docs tree and patch:
> 
>   "ima: define a canonical binary_runtime_measurements list format"
> 
> from the akpm tree.
> 
> I fixed it up (I moved the change to
> Documentation/admin-guide/kernel-parameters.txt) and can carry the fix
> as necessary. This is now fixed as far as linux-next is concerned, but
> any non trivial conflicts should be mentioned to your upstream
> maintainer when your tree is submitted for merging.  You may also want
> to consider cooperating with the maintainer of the conflicting tree to
> minimise any particularly complex conflicts.

Thank you for fixing and carrying the change.

Mimi

linux-next: manual merge of the akpm tree with the jc_docs tree

[Stephen Rothwell]

Hi Andrew,

Today's linux-next merge of the akpm tree got a conflict in:

  Documentation/admin-guide/kernel-parameters.rst

between commit:

  e52347bd66f6 ("Documentation/admin-guide: split the kernel parameter list to a separate file")

from the jc_docs tree and patch:

  "ima: define a canonical binary_runtime_measurements list format"

from the akpm tree.

I fixed it up (I moved the change to
Documentation/admin-guide/kernel-parameters.txt) and can carry the fix
as necessary. This is now fixed as far as linux-next is concerned, but
any non trivial conflicts should be mentioned to your upstream
maintainer when your tree is submitted for merging.  You may also want
to consider cooperating with the maintainer of the conflicting tree to
minimise any particularly complex conflicts.

-- 
Cheers,
Stephen Rothwell