Documentation: sysfs/memory: clarify some memory block device properties

In commit 53cdc1cb29 ("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.

Link: https://lkml.kernel.org/r/20210201181347.13262-3-david@redhat.com
Signed-off-by: David Hildenbrand <david@redhat.com>
Acked-by: Michal Hocko <mhocko@suse.com>
Reviewed-by: Oscar Salvador <osalvador@suse.de>
Cc: Dave Hansen <dave.hansen@intel.com>
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>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

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
+		The file /sys/devices/system/memory/memoryX/removable is a
-		indicates whether this memory block is removable or not.
+		legacy interface used to indicated whether a memory block is
-		This is useful for a user-level agent to determine
+		likely to be offlineable or not.  Newer kernel versions return
-		identify removable sections of the memory before attempting
+		"1" if and only if the kernel supports memory offlining.
-		potentially expensive hot-remove memory operation
 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
+		is read-write.  When read, it returns the online/offline
-		online/offline state of the memory section.  When written,
+		state of the memory block.  When written, root can toggle
-		root can toggle the the online/offline state of a removable
+		the online/offline state of a memory block using the following
-		memory section (see removable file description above)
+		commands::
-		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
+		On newer kernel versions, advanced states can be specified
-		contains a value of 1 and
+		when onlining to select a target zone: "online_movable"
-		/sys/devices/system/memory/memory22/state contains the
+		selects the movable zone.  "online_kernel" selects the
-		string "online" the following command can be executed by
+		applicable kernel zone (DMA, DMA32, or Normal).  However,
-		by root to offline that section::
+		after successfully setting one of the advanced states,
-
+		reading the file will return "online"; the zone information
-		  # echo offline > /sys/devices/system/memory/memory22/state
+		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
+		read-only.
-		block can be onlined to.
+
+		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

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
+``removable``	    read-only: legacy interface that indicated whether a memory
-                    whether the memory block is removable or not
+		    block was likely to be offlineable or not.  Newer kernel
-                    removable.  A value of 1 indicates that the memory
+		    versions return "1" if and only if the kernel supports
-                    block is removable and a value of 0 indicates that
+		    memory offlining.
-                    it is not removable. A memory block is removable only if
+``valid_zones``     read-only: designed to show by which zone memory provided by
-                    every section in the block is removable.
+		    a memory block is managed, and to show by which zone memory
-``valid_zones``     read-only: designed to show which zones this memory block
+		    provided by an offline memory block could be managed when
-		    can be onlined to.
+		    onlining.
 
 		    The first column shows it`s default zone.