Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Subject: Re: [PATCH v2 2/2] memory-hotplug.rst: complete admin-guide overhaul
To:     linux-kernel@vger.kernel.org
Cc:     linux-mm@kvack.org, Andrew Morton <akpm@linux-foundation.org>,
        Anshuman Khandual <anshuman.khandual@arm.com>,
        Dave Hansen <dave.hansen@linux.intel.com>,
        Jonathan Corbet <corbet@lwn.net>,
        Matthew Wilcox <willy@infradead.org>,
        Michal Hocko <mhocko@suse.com>,
        Mike Kravetz <mike.kravetz@oracle.com>,
        Mike Rapoport <rppt@kernel.org>,
        Muchun Song <songmuchun@bytedance.com>,
        Oscar Salvador <osalvador@suse.de>,
        Pavel Tatashin <pasha.tatashin@soleen.com>,
        Stephen Rothwell <sfr@canb.auug.org.au>,
        linux-doc@vger.kernel.org
References: <20210608133855.20397-1-david@redhat.com>
 <20210608133855.20397-3-david@redhat.com>
From:   David Hildenbrand <david@redhat.com>
Organization: Red Hat
Message-ID: <c13a08c1-723e-fa83-d02c-68ad0733231a@redhat.com>
Date:   Tue, 8 Jun 2021 17:26:21 +0200
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101
 Thunderbird/78.10.1
MIME-Version: 1.0
In-Reply-To: <20210608133855.20397-3-david@redhat.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 08.06.21 15:38, David Hildenbrand wrote:
> The memory hot(un)plug documentation is outdated and incomplete. Most of
> the content dates back to 2007, so it's time for a major overhaul.
> 
> Let's rewrite, reorganize and update most parts of the documentation. In
> addition to memory hot(un)plug, also add some details regarding
> ZONE_MOVABLE, with memory hotunplug being one of its main consumers.
> 
> Drop the file history, that information can more reliably be had from
> the git log.
> 
> The style of the document is also properly fixed that e.g., "restview"
> renders it cleanly now.
> 
> In the future, we might add some more details about virt users like
> virtio-mem, the XEN balloon, the Hyper-V balloon and ppc64 dlpar.
> 
> Acked-by: Michal Hocko <mhocko@suse.com>
> Cc: Andrew Morton <akpm@linux-foundation.org>
> Cc: Oscar Salvador <osalvador@suse.de>
> Cc: Michal Hocko <mhocko@suse.com>
> Cc: Mike Kravetz <mike.kravetz@oracle.com>
> Cc: Mike Rapoport <rppt@kernel.org>
> Cc: Dave Hansen <dave.hansen@linux.intel.com>
> Cc: Matthew Wilcox <willy@infradead.org>
> Cc: Anshuman Khandual <anshuman.khandual@arm.com>
> Cc: Muchun Song <songmuchun@bytedance.com>
> Cc: Pavel Tatashin <pasha.tatashin@soleen.com>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Stephen Rothwell <sfr@canb.auug.org.au>
> Cc: linux-doc@vger.kernel.org
> Signed-off-by: David Hildenbrand <david@redhat.com>


After a follow-up discussion on v1, the following on top:

diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst b/Documentation/admin-guide/mm/memory-hotplug.rst
index 353b67e76439..15330ad4b764 100644
--- a/Documentation/admin-guide/mm/memory-hotplug.rst
+++ b/Documentation/admin-guide/mm/memory-hotplug.rst
@@ -35,7 +35,7 @@ used to expose persistent memory, other performance-differentiated memory and
  reserved memory regions as ordinary system RAM to Linux.
  
  Linux only supports memory hot(un)plug on selected 64 bit architectures, such as
-x86_64, aarch64, ppc64, s390x and ia64.
+x86_64, arm64, ppc64, s390x and ia64.
  
  Memory Hot(Un)Plug Granularity
  ------------------------------
@@ -178,9 +178,9 @@ Or one can explicitly request a kernel zone (usually ZONE_NORMAL) by::
  
         % echo online_kernel > /sys/devices/system/memory/memoryXXX/state
  
-In any case, if offline succeeds, the state of the memory block is changed to be
-"online". If it fails, an error will be returned by the kernel via the system
-call that triggered the respective file modification.
+In any case, if onlining succeeds, the state of the memory block is changed to
+be "online". If it fails, the state of the memory block will remain unchanged
+and the above commands will fail.
  
  Onlining Memory Blocks Automatically
  ------------------------------------
@@ -234,8 +234,15 @@ Or alternatively::
  
         % echo 0 > /sys/devices/system/memory/memoryXXX/online
  
-If offline succeeds, the state of the memory block is changed to be "offline".
-If it fails, an error will be returned by the kernel.
+If offlining succeeds, the state of the memory block is changed to be "offline".
+If it fails, the state of the memory block will remain unchanged and the above
+commands will fail, for example, via::
+
+       bash: echo: write error: Device or resource busy
+
+or via::
+
+       bash: echo: write error: Invalid argument
  
  Observing the State of Memory Blocks
  ------------------------------------
@@ -535,7 +542,7 @@ block might fail:
    offlining; this applies to memory blocks present during boot only.
  
  - Special memory blocks prevented by the system from getting offlined. Examples
-  include any memory available during boot on aarch64 or memory blocks spanning
+  include any memory available during boot on arm64 or memory blocks spanning
    the crashkernel area on s390x; this usually applies to memory blocks present
    during boot only.
  

-- 
Thanks,

David / dhildenb