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 Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id 2C15AC00528 for ; Sun, 6 Aug 2023 07:50:00 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id EA9F68D0007; Sun, 6 Aug 2023 03:49:57 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id E59718D0009; Sun, 6 Aug 2023 03:49:57 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id B4C108D0007; Sun, 6 Aug 2023 03:49:57 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0010.hostedemail.com [216.40.44.10]) by kanga.kvack.org (Postfix) with ESMTP id 985A08D0007 for ; Sun, 6 Aug 2023 03:49:57 -0400 (EDT) Received: from smtpin28.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay06.hostedemail.com (Postfix) with ESMTP id 68439B1D00 for ; Sun, 6 Aug 2023 07:49:57 +0000 (UTC) X-FDA: 81092906034.28.BCA0EFF Received: from mail-pl1-f182.google.com (mail-pl1-f182.google.com [209.85.214.182]) by imf07.hostedemail.com (Postfix) with ESMTP id A60FD40003 for ; Sun, 6 Aug 2023 07:49:55 +0000 (UTC) Authentication-Results: imf07.hostedemail.com; dkim=pass header.d=smartx-com.20221208.gappssmtp.com header.s=20221208 header.b=iV89qfci; spf=none (imf07.hostedemail.com: domain of xueshi.hu@smartx.com has no SPF policy when checking 209.85.214.182) smtp.mailfrom=xueshi.hu@smartx.com; dmarc=none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1691308195; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=g7ukv7uj/w5L1DuqNzfxmyygr180TVulkR/8ipJmp+k=; b=6NUI0AqX5y1liZrTFiXv/IRoIs6waQydtEspkGWuQ3jS+7pat01FGhUYZMTC1bRa6QIA5r dE/0QHwSRZOrgvsav8ZLwEuE1/0oHvQDtzk3umKyTVX3Foma4HGNYcrnv2cYJQoIM8PIGp /AaWcbmn4hXZWKqayP4NPxl5Kmw5Vgs= ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1691308195; a=rsa-sha256; cv=none; b=w8BYpyFymNMHjXCwvpm61g4/NR90Xu0BIPzM4y6g2QBkDcqJuysAO9zG5ko4wJsU4Q0na0 iODe0i2g8asmNAI+mx88s+4D81lEnXkhiCuGIWtWp3WVP6XQeK/io9qu2jimj5PxjJmKZq FTt+UaaC2CpbGlQ+wIC12zyhwiVV+Uw= ARC-Authentication-Results: i=1; imf07.hostedemail.com; dkim=pass header.d=smartx-com.20221208.gappssmtp.com header.s=20221208 header.b=iV89qfci; spf=none (imf07.hostedemail.com: domain of xueshi.hu@smartx.com has no SPF policy when checking 209.85.214.182) smtp.mailfrom=xueshi.hu@smartx.com; dmarc=none Received: by mail-pl1-f182.google.com with SMTP id d9443c01a7336-1b8b2b60731so21532445ad.2 for ; Sun, 06 Aug 2023 00:49:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=smartx-com.20221208.gappssmtp.com; s=20221208; t=1691308194; x=1691912994; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=g7ukv7uj/w5L1DuqNzfxmyygr180TVulkR/8ipJmp+k=; b=iV89qfcivx30bnrPidqV+sz8dB408ao/3ENbC1N6bI2l0QJR+YT/+1cX1vN+pozdYi BETlcmIm8BT/djSIEZ/EQkbv0UAh3Lysoya7v2QHY8W9F35Ulmcz/aSaOXLMr5SJ5JT7 tMXNQIKqQnPDTkDxV1JbdyHUUTk6uJOS+Hs6CLsO9lzXnUAvJzCsMxhAd6qW6S4REktS HaR/uucxRMnizZbNahn6Dr32mk0kj5MRdC5eXJ7tYxRj+vvvRvF01m9nKvvkUWhvVVIk TGl6w1lGYA6SssLtkXx8HnSu81Y027gjcKA5hbaYqIkLCdtLHzQczpWAiJxfEEymTObb 7WBQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1691308194; x=1691912994; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=g7ukv7uj/w5L1DuqNzfxmyygr180TVulkR/8ipJmp+k=; b=HA4d6lD2WLGR9ZT04OncsaWTfqN9fduYYha6yeTpTVggEViq/OsyG7hHIcC9TT8mnJ F9snVd+FP4d1SC76jA4L9zxgLsPhzGNVK8iW2FanVVEF/zosQ1w1ekM07qqje5Qn6NP5 VGn+B9hElrsPpw2/Z2WDmPpmu0c9x4Z8w5o5pA994XV3yUoqf0N7lSU7mHCL5YngU8MU 5hry8o+vYNJ4gzXkBLpxtRrix36rh0rP/L9FlvlNATVTX9yUeiLUPP5BdMZfZv+A9evw hkV239hQcQK5bITg52r418iclzV1IDAd3uipfpIN8Abs0IUdFpH6btohZPZ8oi79bvhr 6QzA== X-Gm-Message-State: AOJu0YySU1XoglZM8scq2CVoyhDbdQaE0BYRdwMfAn+RXw1GHLmVjsKq jmjgi6OrokVu23FuAnCZXZN1Lw98ZgHiPiiNvYc1Fe7I1ZE= X-Google-Smtp-Source: AGHT+IHxATCv/rO3OTpBId6jyTeTGK4oKIAByqysePNAn4BrejBAbZaw6UMgxcgwXeZXeXacgjMsFQ== X-Received: by 2002:a17:903:230b:b0:1bc:239:a7e3 with SMTP id d11-20020a170903230b00b001bc0239a7e3mr6387495plh.44.1691308194509; Sun, 06 Aug 2023 00:49:54 -0700 (PDT) Received: from nixos.tailf4e9e.ts.net ([47.75.78.161]) by smtp.googlemail.com with ESMTPSA id j3-20020a170902c3c300b001b9cf6342e2sm4522814plj.42.2023.08.06.00.49.52 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 06 Aug 2023 00:49:54 -0700 (PDT) From: Xueshi Hu To: mike.kravetz@oracle.com, muchun.song@linux.dev, corbet@lwn.net, akpm@linux-foundation.org, n-horiguchi@ah.jp.nec.com, osalvador@suse.de Cc: linux-mm@kvack.org, Xueshi Hu Subject: [PATCH v2 4/4] docs: hugetlbpage.rst: make the meaning of persistent hugetlb pages clear Date: Sun, 6 Aug 2023 15:48:53 +0800 Message-Id: <20230806074853.317203-5-xueshi.hu@smartx.com> X-Mailer: git-send-email 2.40.1 In-Reply-To: <20230806074853.317203-1-xueshi.hu@smartx.com> References: <20230806074853.317203-1-xueshi.hu@smartx.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Rspamd-Queue-Id: A60FD40003 X-Rspam-User: X-Stat-Signature: 74kuzzhccwhzc95w8hmp4y6pamcpyjq3 X-Rspamd-Server: rspam03 X-HE-Tag: 1691308195-413983 X-HE-Meta: U2FsdGVkX18mjmJ0R91hE0tHvSnwNXG0NEOo99kZ14kMjmg6OCi4Puzfa57QoyK1tXooVRH2VJHXDQMnhpwK3+D9JpJwS3JArDZOe2oJaDtwOns97cKESEC1l3tMUkUxYgVCGroq8DC5GLYMvCrNsWa86NqPlDcjENGs8Ma8KuVFYVmyHci1hFmXD7MCa53fvr77WDJhgCU+h29CnG9TOF5JqRL3StbKW21ucAY9+qw2zp9zz+ZJ657MBJIUZ5IZRPSLb25up+Z+Ep+TIEnERI4q9mH3EU7MCLeVFudeGXDB8pr7Ls7U2+OwbQkjWBivbeKEdJHRK/+hrQxjubT50XS8+uINMziy1fGTSyWSG9vXP7qE+uEKyrxvBv97PlLDajDth0Mmm/Clo/Ixr+fa4evDXW6aoD/Vzj1PizVgO9Zg1EqSwtCC4Je91Ch5zG8VgmEg47f5nYlFgOfWUfSM//Uy+VF+dVzSl+r4BXS8hXY9qjRM9xaLn8DP7AUuthLdIJ6sK3XQZBLaWpplmJigXpICys4bmDoKTOv+j3Z4I4MYuvk9/SNy0T+Y/N0ZC3Rrbz9K/7bq1P8T/JHCgLrq/2HPQdyCEkUnFpIQcUgYOVppesfxTxjRTahbrteRlFVy82o3ljL6LAwWS2pSJkxsZIW1eAkKxIMIk35IzHHLrgD4vBF/TsViZrw8ASN6c/bspfowq3cr5+oazsVZ5061ITSTaxi1/TxszHVorUYHHCY3GMAnXtIsne7uDGHgLsBEg7dSXrxozVBx2EQ0h+ZmzJU6CuMahyM5bh5PnerAPsAO6Gux/bFRpp6uJiiOttmkYnII4TEu7SABc6SzMbsum+PJVvAP+cuzHxjNSs4HiinhhAlz8Uwd3ZyrWMHpntslgKmZl7ZMuj9BRsUliZhpWgXNgzQLIDeLPDl5TBgiXwoOPFR2ztWEJ/c4fEuLSdCm5EZC+HfDLZk9NYhv9sJ GYHS4ALR goVLkAXrnlrPZmG625c9nSj6Ia5dK0krM68KLnODSbKjD9l5/PpeP5jfnbL6KaJ2fAwjgfYcrUKxUp3URVr+Iw2hUiUmaXF/ChZ99SA+hZxAHMgNlu0WvEW70wRqz/jjheFT+O2gMREToEJGO/P5gxtn50Z+keM3j7xcb7O7gkt9hc2wKzJJ6ALJ/1pWe38iweOc2OhnN1WkMhgj2YmiIiUT8V0ihFDMaK1ZVFaH3oERK5rJnv/wWoPR+I0ogUNNGtkQ/rDpfXJnK4y55hvjB67SK26eFWLiryln44MhRo7tKvIhlB0P88e1eEj4L0mY+qgCEIvR1XkVcYH14bwSqF2/UwipT2ONoz6NwV8M3zTXeAhMnVFv7UKN4IE3HM4ZLB7fWt8N+mRov1PdHjOoyRhxYoGOP24lA7bgHfuaSoecpXZc= 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: 1. Provide a definition for persistent huge pages prior to mentioning it. 2. Correct the definition of '/proc/sys/vm/nr_hugepages'. 3. Correct several incorrect usages of the word "persistent". Signed-off-by: Xueshi Hu --- Documentation/admin-guide/mm/hugetlbpage.rst | 31 ++++++++++---------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/Documentation/admin-guide/mm/hugetlbpage.rst b/Documentation/admin-guide/mm/hugetlbpage.rst index e4d4b4a8dc97..1cf3cf58bd99 100644 --- a/Documentation/admin-guide/mm/hugetlbpage.rst +++ b/Documentation/admin-guide/mm/hugetlbpage.rst @@ -25,7 +25,7 @@ automatically when CONFIG_HUGETLBFS is selected) configuration options. The ``/proc/meminfo`` file provides information about the total number of -persistent hugetlb pages in the kernel's huge page pool. It also displays +hugetlb pages in the kernel's huge page pool. It also displays default huge page size and information about the number of free, reserved and surplus huge pages in the pool of huge pages of default size. The huge page size is needed for generating the proper alignment and @@ -54,10 +54,11 @@ HugePages_Rsvd guarantee that an application will be able to allocate a huge page from the pool of huge pages at fault time. HugePages_Surp - is short for "surplus," and is the number of huge pages in - the pool above the value in ``/proc/sys/vm/nr_hugepages``. The - maximum number of surplus huge pages is controlled by - ``/proc/sys/vm/nr_overcommit_hugepages``. + is short for "surplus," and is the number of huge pages which will be + freed back to the kernel's normal page pool upon becoming unused. In + contrast, persistent huge pages will not be freed back even if the task + no longer uses it. The maximum number of surplus huge pages is + controlled by ``/proc/sys/vm/nr_overcommit_hugepages``. Note: When the feature of freeing unused vmemmap pages associated with each hugetlb page is enabled, the number of surplus huge pages may be temporarily larger than the maximum number of surplus huge @@ -76,11 +77,11 @@ Hugetlb ``/proc/filesystems`` should also show a filesystem of type "hugetlbfs" configured in the kernel. -``/proc/sys/vm/nr_hugepages`` indicates the current number of "persistent" huge -pages in the kernel's huge page pool. "Persistent" huge pages will be -returned to the huge page pool when freed by a task. A user with root -privileges can dynamically allocate more or free some persistent huge pages -by increasing or decreasing the value of ``nr_hugepages``. +``/proc/sys/vm/nr_hugepages`` returns the total number of huge pages. When this +file is written, the number of persistent huge pages will be adjusted to the +specified value. A user with root privileges can dynamically allocate more or +free some persistent huge pages by increasing or decreasing the value of +``nr_hugepages``. Note: When the feature of freeing unused vmemmap pages associated with each hugetlb page is enabled, we can fail to free the huge pages triggered by @@ -95,7 +96,7 @@ pool, a user with appropriate privilege can use either the mmap system call or shared memory system calls to use the huge pages. See the discussion of :ref:`Using Huge Pages `, below. -The administrator can allocate persistent huge pages on the kernel boot +The administrator can allocate huge pages on the kernel boot command line by specifying the "hugepages=N" parameter, where 'N' = the number of huge pages requested. This is the most reliable method of allocating huge pages as memory has not yet become fragmented. @@ -173,7 +174,7 @@ default sized persistent huge pages:: echo 20 > /proc/sys/vm/nr_hugepages This command will try to adjust the number of default sized huge pages in the -huge page pool to 20, allocating or freeing huge pages, as required. +persistent huge page pool to 20, allocating or freeing huge pages, as required. On a NUMA platform, the kernel will attempt to distribute the huge page pool over all the set of allowed nodes specified by the NUMA memory policy of the @@ -406,12 +407,12 @@ default huge page size and associated pool will be used. The ``size`` option sets the maximum value of memory (huge pages) allowed for that filesystem (``/mnt/huge``). The ``size`` option can be specified -in bytes, or as a percentage of the specified huge page pool (``nr_hugepages``). -The size is rounded down to HPAGE_SIZE boundary. +in bytes, or as a percentage of the specified persistent huge page pool +(``nr_hugepages``). The size is rounded down to HPAGE_SIZE boundary. The ``min_size`` option sets the minimum value of memory (huge pages) allowed for the filesystem. ``min_size`` can be specified in the same way as ``size``, -either bytes or a percentage of the huge page pool. +either bytes or a percentage of the persistent huge page pool. At mount time, the number of huge pages specified by ``min_size`` are reserved for use by the filesystem. If there are not enough free huge pages available, the mount will fail. -- 2.40.1