| Message ID | 20210201181347.13262-3-david@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | drivers/base/memory: clarify some memory block properties | expand |
On Mon, Feb 01, 2021 at 07:13:47PM +0100, David Hildenbrand wrote: > In commit 53cdc1cb29e8 ("drivers/base/memory.c: indicate all memory blocks > as removable") we changed the output of the "removable" property of memory > devices to return "1" if and only if the kernel supports memory offlining. > > Let's update documentation, stating that the interface is legacy. Also > update documentation of the "state" property and "valid_zones" > properties. > > Acked-by: Michal Hocko <mhocko@suse.com> > Cc: Andrew Morton <akpm@linux-foundation.org> > Cc: Dave Hansen <dave.hansen@intel.com> > Cc: Michal Hocko <mhocko@suse.com> > Cc: Oscar Salvador <osalvador@suse.de> > Cc: Jonathan Corbet <corbet@lwn.net> > Cc: David Hildenbrand <david@redhat.com> > Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org> > Cc: Jonathan Cameron <Jonathan.Cameron@huawei.com> > Cc: Ilya Dryomov <idryomov@gmail.com> > Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> > Cc: Geert Uytterhoeven <geert+renesas@glider.be> > Cc: linux-doc@vger.kernel.org > Signed-off-by: David Hildenbrand <david@redhat.com> Reviewed-by: Oscar Salvador <osalvador@suse.de> > --- > .../ABI/testing/sysfs-devices-memory | 53 ++++++++++++------- > .../admin-guide/mm/memory-hotplug.rst | 16 +++--- > 2 files changed, 41 insertions(+), 28 deletions(-) > > diff --git a/Documentation/ABI/testing/sysfs-devices-memory b/Documentation/ABI/testing/sysfs-devices-memory > index 58dbc592bc57..d8b0f80b9e33 100644 > --- a/Documentation/ABI/testing/sysfs-devices-memory > +++ b/Documentation/ABI/testing/sysfs-devices-memory > @@ -13,13 +13,13 @@ What: /sys/devices/system/memory/memoryX/removable > Date: June 2008 > Contact: Badari Pulavarty <pbadari@us.ibm.com> > Description: > - The file /sys/devices/system/memory/memoryX/removable > - indicates whether this memory block is removable or not. > - This is useful for a user-level agent to determine > - identify removable sections of the memory before attempting > - potentially expensive hot-remove memory operation > + The file /sys/devices/system/memory/memoryX/removable is a > + legacy interface used to indicated whether a memory block is > + likely to be offlineable or not. Newer kernel versions return > + "1" if and only if the kernel supports memory offlining. > Users: hotplug memory remove tools > http://www.ibm.com/developerworks/wikis/display/LinuxP/powerpc-utils > + lsmem/chmem part of util-linux > > What: /sys/devices/system/memory/memoryX/phys_device > Date: September 2008 > @@ -44,23 +44,25 @@ Date: September 2008 > Contact: Badari Pulavarty <pbadari@us.ibm.com> > Description: > The file /sys/devices/system/memory/memoryX/state > - is read-write. When read, its contents show the > - online/offline state of the memory section. When written, > - root can toggle the the online/offline state of a removable > - memory section (see removable file description above) > - using the following commands:: > + is read-write. When read, it returns the online/offline > + state of the memory block. When written, root can toggle > + the online/offline state of a memory block using the following > + commands:: > > # echo online > /sys/devices/system/memory/memoryX/state > # echo offline > /sys/devices/system/memory/memoryX/state > > - For example, if /sys/devices/system/memory/memory22/removable > - contains a value of 1 and > - /sys/devices/system/memory/memory22/state contains the > - string "online" the following command can be executed by > - by root to offline that section:: > - > - # echo offline > /sys/devices/system/memory/memory22/state > - > + On newer kernel versions, advanced states can be specified > + when onlining to select a target zone: "online_movable" > + selects the movable zone. "online_kernel" selects the > + applicable kernel zone (DMA, DMA32, or Normal). However, > + after successfully setting one of the advanced states, > + reading the file will return "online"; the zone information > + can be obtained via "valid_zones" instead. > + > + While onlining is unlikely to fail, there are no guarantees > + that offlining will succeed. Offlining is more likely to > + succeed if "valid_zones" indicates "Movable". > Users: hotplug memory remove tools > http://www.ibm.com/developerworks/wikis/display/LinuxP/powerpc-utils > > @@ -70,8 +72,19 @@ Date: July 2014 > Contact: Zhang Zhen <zhenzhang.zhang@huawei.com> > Description: > The file /sys/devices/system/memory/memoryX/valid_zones is > - read-only and is designed to show which zone this memory > - block can be onlined to. > + read-only. > + > + For online memory blocks, it returns in which zone memory > + provided by a memory block is managed. If multiple zones > + apply (not applicable for hotplugged memory), "None" is returned > + and the memory block cannot be offlined. > + > + For offline memory blocks, it returns by which zone memory > + provided by a memory block can be managed when onlining. > + The first returned zone ("default") will be used when setting > + the state of an offline memory block to "online". Only one of > + the kernel zones (DMA, DMA32, Normal) is applicable for a single > + memory block. > > What: /sys/devices/system/memoryX/nodeY > Date: October 2009 > diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst b/Documentation/admin-guide/mm/memory-hotplug.rst > index 245739f55ac7..5307f90738aa 100644 > --- a/Documentation/admin-guide/mm/memory-hotplug.rst > +++ b/Documentation/admin-guide/mm/memory-hotplug.rst > @@ -162,14 +162,14 @@ Under each memory block, you can see 5 files: > which will be performed on all sections in the block. > ``phys_device`` read-only: legacy interface only ever used on s390x to > expose the covered storage increment. > -``removable`` read-only: contains an integer value indicating > - whether the memory block is removable or not > - removable. A value of 1 indicates that the memory > - block is removable and a value of 0 indicates that > - it is not removable. A memory block is removable only if > - every section in the block is removable. > -``valid_zones`` read-only: designed to show which zones this memory block > - can be onlined to. > +``removable`` read-only: legacy interface that indicated whether a memory > + block was likely to be offlineable or not. Newer kernel > + versions return "1" if and only if the kernel supports > + memory offlining. > +``valid_zones`` read-only: designed to show by which zone memory provided by > + a memory block is managed, and to show by which zone memory > + provided by an offline memory block could be managed when > + onlining. > > The first column shows it`s default zone. > > -- > 2.29.2 >
diff --git a/Documentation/ABI/testing/sysfs-devices-memory b/Documentation/ABI/testing/sysfs-devices-memory index 58dbc592bc57..d8b0f80b9e33 100644 --- a/Documentation/ABI/testing/sysfs-devices-memory +++ b/Documentation/ABI/testing/sysfs-devices-memory @@ -13,13 +13,13 @@ What: /sys/devices/system/memory/memoryX/removable Date: June 2008 Contact: Badari Pulavarty <pbadari@us.ibm.com> Description: - The file /sys/devices/system/memory/memoryX/removable - indicates whether this memory block is removable or not. - This is useful for a user-level agent to determine - identify removable sections of the memory before attempting - potentially expensive hot-remove memory operation + The file /sys/devices/system/memory/memoryX/removable is a + legacy interface used to indicated whether a memory block is + likely to be offlineable or not. Newer kernel versions return + "1" if and only if the kernel supports memory offlining. Users: hotplug memory remove tools http://www.ibm.com/developerworks/wikis/display/LinuxP/powerpc-utils + lsmem/chmem part of util-linux What: /sys/devices/system/memory/memoryX/phys_device Date: September 2008 @@ -44,23 +44,25 @@ Date: September 2008 Contact: Badari Pulavarty <pbadari@us.ibm.com> Description: The file /sys/devices/system/memory/memoryX/state - is read-write. When read, its contents show the - online/offline state of the memory section. When written, - root can toggle the the online/offline state of a removable - memory section (see removable file description above) - using the following commands:: + is read-write. When read, it returns the online/offline + state of the memory block. When written, root can toggle + the online/offline state of a memory block using the following + commands:: # echo online > /sys/devices/system/memory/memoryX/state # echo offline > /sys/devices/system/memory/memoryX/state - For example, if /sys/devices/system/memory/memory22/removable - contains a value of 1 and - /sys/devices/system/memory/memory22/state contains the - string "online" the following command can be executed by - by root to offline that section:: - - # echo offline > /sys/devices/system/memory/memory22/state - + On newer kernel versions, advanced states can be specified + when onlining to select a target zone: "online_movable" + selects the movable zone. "online_kernel" selects the + applicable kernel zone (DMA, DMA32, or Normal). However, + after successfully setting one of the advanced states, + reading the file will return "online"; the zone information + can be obtained via "valid_zones" instead. + + While onlining is unlikely to fail, there are no guarantees + that offlining will succeed. Offlining is more likely to + succeed if "valid_zones" indicates "Movable". Users: hotplug memory remove tools http://www.ibm.com/developerworks/wikis/display/LinuxP/powerpc-utils @@ -70,8 +72,19 @@ Date: July 2014 Contact: Zhang Zhen <zhenzhang.zhang@huawei.com> Description: The file /sys/devices/system/memory/memoryX/valid_zones is - read-only and is designed to show which zone this memory - block can be onlined to. + read-only. + + For online memory blocks, it returns in which zone memory + provided by a memory block is managed. If multiple zones + apply (not applicable for hotplugged memory), "None" is returned + and the memory block cannot be offlined. + + For offline memory blocks, it returns by which zone memory + provided by a memory block can be managed when onlining. + The first returned zone ("default") will be used when setting + the state of an offline memory block to "online". Only one of + the kernel zones (DMA, DMA32, Normal) is applicable for a single + memory block. What: /sys/devices/system/memoryX/nodeY Date: October 2009 diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst b/Documentation/admin-guide/mm/memory-hotplug.rst index 245739f55ac7..5307f90738aa 100644 --- a/Documentation/admin-guide/mm/memory-hotplug.rst +++ b/Documentation/admin-guide/mm/memory-hotplug.rst @@ -162,14 +162,14 @@ Under each memory block, you can see 5 files: which will be performed on all sections in the block. ``phys_device`` read-only: legacy interface only ever used on s390x to expose the covered storage increment. -``removable`` read-only: contains an integer value indicating - whether the memory block is removable or not - removable. A value of 1 indicates that the memory - block is removable and a value of 0 indicates that - it is not removable. A memory block is removable only if - every section in the block is removable. -``valid_zones`` read-only: designed to show which zones this memory block - can be onlined to. +``removable`` read-only: legacy interface that indicated whether a memory + block was likely to be offlineable or not. Newer kernel + versions return "1" if and only if the kernel supports + memory offlining. +``valid_zones`` read-only: designed to show by which zone memory provided by + a memory block is managed, and to show by which zone memory + provided by an offline memory block could be managed when + onlining. The first column shows it`s default zone.
In commit 53cdc1cb29e8 ("drivers/base/memory.c: indicate all memory blocks as removable") we changed the output of the "removable" property of memory devices to return "1" if and only if the kernel supports memory offlining. Let's update documentation, stating that the interface is legacy. Also update documentation of the "state" property and "valid_zones" properties. Acked-by: Michal Hocko <mhocko@suse.com> Cc: Andrew Morton <akpm@linux-foundation.org> Cc: Dave Hansen <dave.hansen@intel.com> Cc: Michal Hocko <mhocko@suse.com> Cc: Oscar Salvador <osalvador@suse.de> Cc: Jonathan Corbet <corbet@lwn.net> Cc: David Hildenbrand <david@redhat.com> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Cc: Jonathan Cameron <Jonathan.Cameron@huawei.com> Cc: Ilya Dryomov <idryomov@gmail.com> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Cc: Geert Uytterhoeven <geert+renesas@glider.be> Cc: linux-doc@vger.kernel.org Signed-off-by: David Hildenbrand <david@redhat.com> --- .../ABI/testing/sysfs-devices-memory | 53 ++++++++++++------- .../admin-guide/mm/memory-hotplug.rst | 16 +++--- 2 files changed, 41 insertions(+), 28 deletions(-)