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 0C978C433F5 for ; Mon, 13 Dec 2021 01:59:13 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 94B0E6B0071; Sun, 12 Dec 2021 20:59:02 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 8FAAA6B0073; Sun, 12 Dec 2021 20:59:02 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 79A826B0074; Sun, 12 Dec 2021 20:59:02 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0169.hostedemail.com [216.40.44.169]) by kanga.kvack.org (Postfix) with ESMTP id 6BFCF6B0071 for ; Sun, 12 Dec 2021 20:59:02 -0500 (EST) Received: from smtpin06.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay03.hostedemail.com (Postfix) with ESMTP id 26C738249980 for ; Mon, 13 Dec 2021 01:58:52 +0000 (UTC) X-FDA: 78911112504.06.B58A955 Received: from mga05.intel.com (mga05.intel.com [192.55.52.43]) by imf20.hostedemail.com (Postfix) with ESMTP id E8CA61C000E for ; Mon, 13 Dec 2021 01:58:49 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1639360731; x=1670896731; h=from:to:cc:subject:references:date:in-reply-to: message-id:mime-version; bh=BPIBQRh24j1r5R+LEj2YcwdDa2KSusG9g9vBSZKllJg=; b=FeQlGLSKesip4JLTbftU9XLP8T1+dFWjaeTdwO7Q9PSTC26zXSuO/Afa Uo7V/GVWC2JmgMjV3gq0gp00klUk2ynK0ZwHqSlqp1Du5uNXZm84t/NJL uRw66v6CVjdAiFu7en1jn381kVVPYaGmnqejFHt8OgyxZrhsHkiZWiOW2 69eE2yiVq3itxH0+YCw4tMRpW/Rt+QjiHJ0zyxq9A2j1Qp5L+P5f8h81S 84hCzEeQkriQMHID5/oDaWW+2QupYaOPY8snHKK9EboDW0vy1/yRGB8Tl QGJlt7UrKGwOsA9XEMItKOnBVE1XE0E6qGuc150yOaq+8yv6CGvbHoJHm A==; X-IronPort-AV: E=McAfee;i="6200,9189,10196"; a="324913764" X-IronPort-AV: E=Sophos;i="5.88,201,1635231600"; d="scan'208";a="324913764" Received: from orsmga005.jf.intel.com ([10.7.209.41]) by fmsmga105.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 12 Dec 2021 17:58:49 -0800 X-IronPort-AV: E=Sophos;i="5.88,201,1635231600"; d="scan'208";a="681462946" Received: from yhuang6-desk2.sh.intel.com (HELO yhuang6-desk2.ccr.corp.intel.com) ([10.239.159.50]) by orsmga005-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 12 Dec 2021 17:58:46 -0800 From: "Huang, Ying" To: Valentin Schneider Cc: Peter Zijlstra , Mel Gorman , , , Mel Gorman , "Greg Kroah-Hartman" , Subject: Re: [PATCH -V2] numa balancing: move some document to make it consistent with the code References: <20211209004442.999696-1-ying.huang@intel.com> <8735n1anw9.mognet@arm.com> Date: Mon, 13 Dec 2021 09:58:44 +0800 In-Reply-To: <8735n1anw9.mognet@arm.com> (Valentin Schneider's message of "Thu, 9 Dec 2021 13:49:58 +0000") Message-ID: <87bl1lw9ij.fsf@yhuang6-desk2.ccr.corp.intel.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=ascii X-Rspamd-Queue-Id: E8CA61C000E Authentication-Results: imf20.hostedemail.com; dkim=pass header.d=intel.com header.s=Intel header.b=FeQlGLSK; spf=none (imf20.hostedemail.com: domain of ying.huang@intel.com has no SPF policy when checking 192.55.52.43) smtp.mailfrom=ying.huang@intel.com; dmarc=pass (policy=none) header.from=intel.com X-Rspamd-Server: rspam04 X-Stat-Signature: 5adi638p14t79e8mmqf68wt7rd7hd15d X-HE-Tag: 1639360729-424122 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: Valentin Schneider writes: > 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 ? OK. Will do that. >> 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 "-". Thanks for reminding. Will change it in the next version. Best Regards, Huang, Ying >> + >> +`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