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@xxxxxxxx>
> Cc: Andrew Morton <akpm@xxxxxxxxxxxxxxxxxxxx>
> Cc: Dave Hansen <dave.hansen@xxxxxxxxx>
> Cc: Michal Hocko <mhocko@xxxxxxxx>
> Cc: Oscar Salvador <osalvador@xxxxxxx>
> Cc: Jonathan Corbet <corbet@xxxxxxx>
> Cc: David Hildenbrand <david@xxxxxxxxxx>
> Cc: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
> Cc: Jonathan Cameron <Jonathan.Cameron@xxxxxxxxxx>
> Cc: Ilya Dryomov <idryomov@xxxxxxxxx>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> Cc: Geert Uytterhoeven <geert+renesas@xxxxxxxxx>
> Cc: linux-doc@xxxxxxxxxxxxxxx
> Signed-off-by: David Hildenbrand <david@xxxxxxxxxx>
Reviewed-by: Oscar Salvador <osalvador@xxxxxxx>
> ---
> .../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@xxxxxxxxxx>
> 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@xxxxxxxxxx>
> 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@xxxxxxxxxx>
> 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
>
--
Oscar Salvador
SUSE L3
