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 236D8C433EF for ; Thu, 9 Dec 2021 13:50:25 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 89D126B0072; Thu, 9 Dec 2021 08:50:14 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 84C4B6B0073; Thu, 9 Dec 2021 08:50:14 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 713DB6B0074; Thu, 9 Dec 2021 08:50:14 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0254.hostedemail.com [216.40.44.254]) by kanga.kvack.org (Postfix) with ESMTP id 5EE236B0072 for ; Thu, 9 Dec 2021 08:50:14 -0500 (EST) Received: from smtpin11.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay05.hostedemail.com (Postfix) with ESMTP id 1FA0F185759B3 for ; Thu, 9 Dec 2021 13:50:04 +0000 (UTC) X-FDA: 78898389528.11.A736DA5 Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by imf31.hostedemail.com (Postfix) with ESMTP id 1AEF020006 for ; Thu, 9 Dec 2021 13:50:03 +0000 (UTC) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 8EA0411B3; Thu, 9 Dec 2021 05:50:02 -0800 (PST) Received: from e113632-lin (e113632-lin.cambridge.arm.com [10.1.196.57]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 584633F73B; Thu, 9 Dec 2021 05:50:01 -0800 (PST) From: Valentin Schneider To: Huang Ying , Peter Zijlstra , Mel Gorman Cc: linux-mm@kvack.org, linux-kernel@vger.kernel.org, Huang Ying , Mel Gorman , Greg Kroah-Hartman , stable@vger.kernel.org Subject: Re: [PATCH -V2] numa balancing: move some document to make it consistent with the code In-Reply-To: <20211209004442.999696-1-ying.huang@intel.com> References: <20211209004442.999696-1-ying.huang@intel.com> Date: Thu, 09 Dec 2021 13:49:58 +0000 Message-ID: <8735n1anw9.mognet@arm.com> MIME-Version: 1.0 Content-Type: text/plain X-Rspamd-Server: rspam01 X-Rspamd-Queue-Id: 1AEF020006 X-Stat-Signature: eztpeheasyh5dgtqfezi3erbb8x6puwm Authentication-Results: imf31.hostedemail.com; dkim=none; spf=pass (imf31.hostedemail.com: domain of valentin.schneider@arm.com designates 217.140.110.172 as permitted sender) smtp.mailfrom=valentin.schneider@arm.com; dmarc=pass (policy=none) header.from=arm.com X-HE-Tag: 1639057803-870443 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: On 09/12/21 08:44, Huang Ying wrote: > After commit 8a99b6833c88 ("sched: Move SCHED_DEBUG sysctl to > debugfs"), some NUMA balancing sysctls enclosed with SCHED_DEBUG has > been moved to debugfs. This patch move the document for these > sysctls from > > Documentation/admin-guide/sysctl/kernel.rst > > to > > Documentation/scheduler/debug.txt > AFAIA new documentation files should be written in reST, and the "source" file is .rst so the new one should be too (as much as Peter hates it). Also, most files in there are named sched-*.rst, does that want to be sched-debug.rst ? > to make the document consistent with the code. > > Signed-off-by: "Huang, Ying" > Fixes: 8a99b6833c88 ("sched: Move SCHED_DEBUG sysctl to debugfs") > Cc: Mel Gorman > Cc: Peter Zijlstra (Intel) > Cc: Greg Kroah-Hartman > Cc: Valentin Schneider > Cc: stable@vger.kernel.org # since v5.13 > diff --git a/Documentation/scheduler/debug.txt b/Documentation/scheduler/debug.txt > new file mode 100644 > index 000000000000..848d83c3123c > --- /dev/null > +++ b/Documentation/scheduler/debug.txt > @@ -0,0 +1,48 @@ > +Scheduler debugfs > + How about a small intro? --- diff --git a/Documentation/scheduler/debug.txt b/Documentation/scheduler/debug.txt index 848d83c3123c..08600de5b90e 100644 --- a/Documentation/scheduler/debug.txt +++ b/Documentation/scheduler/debug.txt @@ -1,4 +1,10 @@ +================= Scheduler debugfs +================= + +Booting a kernel with CONFIG_SCHED_DEBUG=y will give access to scheduler +-specific debug files under /sys/kernel/debug/sched. Some of those files are +described below. numa_balancing -------------- --- > +numa_balancing > +-------------- I think you got the heading ordering wrong, see Documentation/doc-guide/sphinx.rst#Specific guidelines for the kernel documentation IIRC Sphinx/reST only requires heading ordering to be consistent within a given file, but having consistency throughout the project simplifies reviewing/contributing. In this case, headings with "=" must appear before headings with "-". > + > +`numa_balancing` directory is used to hold files to control NUMA > +balancing feature. If the system overhead from the feature is too > +high then the rate the kernel samples for NUMA hinting faults may be > +controlled by the `scan_period_min_ms, scan_delay_ms, > +scan_period_max_ms, scan_size_mb` files. > + > + > +scan_period_min_ms, scan_delay_ms, scan_period_max_ms, scan_size_mb > +=================================================================== > + > +Automatic NUMA balancing scans tasks address space and unmaps pages to > +detect if pages are properly placed or if the data should be migrated to a > +memory node local to where the task is running. Every "scan delay" the task > +scans the next "scan size" number of pages in its address space. When the > +end of the address space is reached the scanner restarts from the beginning. > + > +In combination, the "scan delay" and "scan size" determine the scan rate. > +When "scan delay" decreases, the scan rate increases. The scan delay and > +hence the scan rate of every task is adaptive and depends on historical > +behaviour. If pages are properly placed then the scan delay increases, > +otherwise the scan delay decreases. The "scan size" is not adaptive but > +the higher the "scan size", the higher the scan rate. > + > +Higher scan rates incur higher system overhead as page faults must be > +trapped and potentially data must be migrated. However, the higher the scan > +rate, the more quickly a tasks memory is migrated to a local node if the > +workload pattern changes and minimises performance impact due to remote > +memory accesses. These files control the thresholds for scan delays and > +the number of pages scanned. > + > +``scan_period_min_ms`` is the minimum time in milliseconds to scan a > +tasks virtual memory. It effectively controls the maximum scanning > +rate for each task. > + > +``scan_delay_ms`` is the starting "scan delay" used for a task when it > +initially forks. > + > +``scan_period_max_ms`` is the maximum time in milliseconds to scan a > +tasks virtual memory. It effectively controls the minimum scanning > +rate for each task. > + > +``scan_size_mb`` is how many megabytes worth of pages are scanned for > +a given scan. > -- > 2.30.2