Commit a89107c0 authored by David Hildenbrand's avatar David Hildenbrand Committed by Linus Torvalds
Browse files

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

In commit 53cdc1cb ("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: default avatarDavid Hildenbrand <david@redhat.com>
Acked-by: default avatarMichal Hocko <mhocko@suse.com>
Reviewed-by: default avatarOscar 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: default avatarAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent e9a2e48e

Documentation/ABI/testing/sysfs-devices-memory

+33 −20
Original line number Diff line number Diff line
@@ -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

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

+8 −8
Original line number Diff line number Diff line
@@ -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.