From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-13.5 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id D4729C433E0 for ; Mon, 1 Feb 2021 10:52:20 +0000 (UTC) Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.kernel.org (Postfix) with ESMTP id 495DC64E2A for ; Mon, 1 Feb 2021 10:52:20 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 495DC64E2A Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix) id C30FB6B0072; Mon, 1 Feb 2021 05:52:19 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id C06006B0073; Mon, 1 Feb 2021 05:52:19 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id ACC746B0074; Mon, 1 Feb 2021 05:52:19 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0004.hostedemail.com [216.40.44.4]) by kanga.kvack.org (Postfix) with ESMTP id 97B786B0072 for ; Mon, 1 Feb 2021 05:52:19 -0500 (EST) Received: from smtpin23.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay05.hostedemail.com (Postfix) with ESMTP id 65582181AEF10 for ; Mon, 1 Feb 2021 10:52:19 +0000 (UTC) X-FDA: 77769384798.23.cap45_0611919275c1 Received: from filter.hostedemail.com (10.5.16.251.rfc1918.com [10.5.16.251]) by smtpin23.hostedemail.com (Postfix) with ESMTP id 40D6637604 for ; Mon, 1 Feb 2021 10:52:19 +0000 (UTC) X-HE-Tag: cap45_0611919275c1 X-Filterd-Recvd-Size: 9186 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by imf09.hostedemail.com (Postfix) with ESMTP for ; Mon, 1 Feb 2021 10:52:18 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1612176738; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=JnHeDpI4bvTxudk3KhEYwjLYvMmvMtJjXyTPeOgb0Is=; b=ByBtY7XFjieob04k1Q0ONjI4UYMqeLK6rhEdUnG5L0D6s8W12S73bZhRFdXLF3LQt6r7l2 tB/q2wsx56tTFYG2q8uuSJn2x4hC8l1M+3TJmkoUKQ75Vwt2F/bhc3if+Dd7lYahsLGtDk alxF/VC9ovUkZQa5IR0Z/1l5/Bmi9LQ= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-324-Xh8r5YozM_-Og_jNIsx-ww-1; Mon, 01 Feb 2021 05:52:14 -0500 X-MC-Unique: Xh8r5YozM_-Og_jNIsx-ww-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 6B30F801817; Mon, 1 Feb 2021 10:52:12 +0000 (UTC) Received: from t480s.redhat.com (ovpn-115-24.ams2.redhat.com [10.36.115.24]) by smtp.corp.redhat.com (Postfix) with ESMTP id 700FB27CA9; Mon, 1 Feb 2021 10:52:08 +0000 (UTC) From: David Hildenbrand To: linux-kernel@vger.kernel.org Cc: linux-mm@kvack.org, David Hildenbrand , Andrew Morton , Dave Hansen , Michal Hocko , Oscar Salvador , Jonathan Corbet , Greg Kroah-Hartman , Jonathan Cameron , Ilya Dryomov , Mauro Carvalho Chehab , Geert Uytterhoeven , linux-doc@vger.kernel.org Subject: [PATCH v1 2/2] Documentation: sysfs/memory: clarify some memory block device properties Date: Mon, 1 Feb 2021 11:51:58 +0100 Message-Id: <20210201105158.6393-3-david@redhat.com> In-Reply-To: <20210201105158.6393-1-david@redhat.com> References: <20210201105158.6393-1-david@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 Content-Transfer-Encoding: quoted-printable X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: In commit 53cdc1cb29e8 ("drivers/base/memory.c: indicate all memory block= s as removable") we changed the output of the "removable" property of memor= y 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. Cc: Andrew Morton Cc: Dave Hansen Cc: Michal Hocko Cc: Oscar Salvador Cc: Jonathan Corbet Cc: David Hildenbrand Cc: Greg Kroah-Hartman Cc: Jonathan Cameron Cc: Ilya Dryomov Cc: Mauro Carvalho Chehab Cc: Geert Uytterhoeven Cc: linux-doc@vger.kernel.org Signed-off-by: David Hildenbrand --- .../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/Documentati= on/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 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 =20 What: /sys/devices/system/memory/memoryX/phys_device Date: September 2008 @@ -44,23 +44,25 @@ Date: September 2008 Contact: Badari Pulavarty 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:: =20 # echo online > /sys/devices/system/memory/memoryX/state # echo offline > /sys/devices/system/memory/memoryX/state =20 - 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 =20 @@ -70,8 +72,19 @@ Date: July 2014 Contact: Zhang Zhen 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. =20 What: /sys/devices/system/memoryX/nodeY Date: October 2009 diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst b/Documentat= ion/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 onl= y 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 m= emory + 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 pro= vided by + a memory block is managed, and to show by which zone memory + provided by an offline memory block could be managed when + onlining. =20 The first column shows it`s default zone. =20 --=20 2.29.2