From patchwork Wed Dec 13 19:03:37 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: SeongJae Park X-Patchwork-Id: 13491787 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 7A427C4167B for ; Wed, 13 Dec 2023 19:04:04 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 7A9EF8D0054; Wed, 13 Dec 2023 14:03:58 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 759208D0049; Wed, 13 Dec 2023 14:03:58 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 586418D0054; Wed, 13 Dec 2023 14:03:58 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0017.hostedemail.com [216.40.44.17]) by kanga.kvack.org (Postfix) with ESMTP id 3936D8D0049 for ; Wed, 13 Dec 2023 14:03:58 -0500 (EST) Received: from smtpin30.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay07.hostedemail.com (Postfix) with ESMTP id F01A41602B7 for ; Wed, 13 Dec 2023 19:03:57 +0000 (UTC) X-FDA: 81562719714.30.9BE2714 Received: from dfw.source.kernel.org (dfw.source.kernel.org [139.178.84.217]) by imf24.hostedemail.com (Postfix) with ESMTP id 8D1DD180033 for ; Wed, 13 Dec 2023 19:03:54 +0000 (UTC) Authentication-Results: imf24.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=F4ZYtp9e; spf=pass (imf24.hostedemail.com: domain of sj@kernel.org designates 139.178.84.217 as permitted sender) smtp.mailfrom=sj@kernel.org; dmarc=pass (policy=none) header.from=kernel.org ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1702494234; 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-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=V5H5VveeMnDDzqbWQaVm9TZlhjPnJIl6dXPxA89NsM0=; b=tUmxxSMY9VXIp/vrjCnMGKC8z8ykyqws1SFVIugRPxTjgN9TZslOi2tEbQl05njNw4oohn itpHgrqoPTbgNzONXwecEmDatlP0jJBJwYPmWmXs5H2Vy/iHXXTP4qCnvR9ddrkYkKQ2Fj UJYhtPgGZ45fRnUrxS3YB232Q6d8P8w= ARC-Authentication-Results: i=1; imf24.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=F4ZYtp9e; spf=pass (imf24.hostedemail.com: domain of sj@kernel.org designates 139.178.84.217 as permitted sender) smtp.mailfrom=sj@kernel.org; dmarc=pass (policy=none) header.from=kernel.org ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1702494234; a=rsa-sha256; cv=none; b=JwdhmMhHaDYpH1yHsm5Idc6b7PMXP4SF6CTuzLWIdXO2lBN9BGeOhex6QE3buiZBkrjp+F FyAIInr5PpisNDd7oeYqqtnh8y2hCHhSdvIJA0WByuvk9YW//61owEfBmW6HismgFTpbij Vzcy8KdplYh3VI3etJXEIuD6J+TFIqw= Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by dfw.source.kernel.org (Postfix) with ESMTP id D1A2761F49; Wed, 13 Dec 2023 19:03:53 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id EBF17C433CB; Wed, 13 Dec 2023 19:03:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1702494233; bh=KJAl103OAFoAr+UeUtJKB48jbALa8Ynn0eVxO6I87hY=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=F4ZYtp9e6u1S7vJVoTQuManLwGlrjOeID7BQLcnqFPRmQJPlm0o42k6kIz6uqAfU+ /HE5a9iWB/nCg4QL7ho2iGnYV78Rzv91bOo4uwfG8hwgqoniBuN+bYKp600U99SX/2 z4TYpYXhvBqmr2HXUHooXJ56cx0BIyv65XrswEfh3fot7+WOrwj6Dh0fGrxS/qXJ0d MwDbUOg8Llty3aCoY3Nb/Jb2XinjBJdNkkEJeB7L5Oujli7nQ2ACJPkBYBdVMKlALB XDyzklyW5EI8kshSqnJnQ21yO5J4ZdyD+hN/+Ljd+y7ttdyvcWB2x/pINClxdh92EA KiEA+aTGWd87A== From: SeongJae Park To: Andrew Morton Cc: SeongJae Park , Jonathan Corbet , damon@lists.linux.dev, linux-mm@kvack.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 5/6] Docs/admin-guide/mm/damon/usage: add links to sysfs files hierarchy Date: Wed, 13 Dec 2023 19:03:37 +0000 Message-Id: <20231213190338.54146-6-sj@kernel.org> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20231213190338.54146-1-sj@kernel.org> References: <20231213190338.54146-1-sj@kernel.org> MIME-Version: 1.0 X-Rspamd-Queue-Id: 8D1DD180033 X-Rspam-User: X-Stat-Signature: fcnwsxaqic5xbi3fwc6bom5e8hu34dqr X-Rspamd-Server: rspam01 X-HE-Tag: 1702494234-132750 X-HE-Meta: U2FsdGVkX1/zMvWgmui3t4VBvFcirfHgNF0H9ylk5pC3sw9g0NCE65nPx/Y04P6BmgQOuhZaKFJpvopPoP5CDsrcbX5Nz8jbqyPmMYyZRSCWIP2Hc2neVNQzGpuhQ1s4yTRrjlvL8AAmY6CEsjtu7+8aa69OKBHEajWtSEU2/SC8Qi1hsBMrxGTD6bY36U8OvdYKuSf1G2iqIW5vR7giCXjRzVq8GKME5ZBuoiWFbidlGjxEW/tDWxBf+768LpMJHn2tVwkVk9Ffw1xsXttdM3/sJwv/6EIxMF8wjIfQZXa8agpvjzf/xwHSOqm3xeZoJuDOndSFk0xJMFgXlys1hIuO3RIQtDou32eHbHq2Xvv1qurx96dYquQoZ9oqXnO116RuWsvJpWdcv3ecdGW/cPGf7z55SD8jHX74MZT1Eqc+YUeBERiPLX1ftSREBMlx0mOTfrbtbWfINs7a3My7158ufoFtHAc2FDS6pfK95QfFyxifBW4QJoy93s4213daAprqOiv8luvhHobYgm41BMQfe2ZTl2Ak24aj6iKc8QGiQW/7WNQVkutPuuHfpPJxBgldMwdnRhSgBJxmy18JT8fU6PJ+xET/0irxizmxKkyd4mDxiX0AZ0JeA5RNXQYrsOjHxx7/qMEkjeriNXuaC8WC13L7pyAJqswO3tgR1IIaodIxz9XYranXI2JSJJuZi5rocGrnqhQzmL46HfNR/QsckhkJAFfb6K74P2+f3asZfqgiEmRQW+sJUGiZ64WPR2T8gA1FIWBGsnumO9Mdh8wBL8jHzR0oQpaNpGajVoXwPNQ0XSsYSaj1Ht2xm/E8D1NxLrHYMryHbdN8kduPxb2tg8C99rNdIWIseQI6pd/TaZU+NX3U+jgD2LAxDNicDD2/pNPQ1Mm+84RbIStQIhzndguOz+yd2LgwLwF3XRUeAPQPVL1GV6AHxaLRverMdxWhRzjSeA8MRlz9GQ2 GM9waSh/ 5f6XmNjRFxRKc0iK329NWG681aBYyIBJcu8qymZDzrtQwUzWAB1RggFYle4GfcJQ2vBLlJzrkg5ynGTTgxG2JzWqOq0brZyMrP0B5ApCR0WLH4N1Gb3RlbDaZ/G4zJluq9f9BCxbj1me8/eurllXgWF81kZUoj+Go6NQNJQArCPJRkKx5rFTzKLYvMVXjXj7jYlCeSqBrzax5BNgNqSnZgRyeSC8COvx5Bb+jXW5XzlWsAvxqUhuVl9N+lw== 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: List-Subscribe: List-Unsubscribe: 'Sysfs Files Hierarchy' section of DAMON usage document shows whole picture of the interface. Then sections for detailed explanation of the files follow. Due to the amount of the files, navigating between the whole picture and the section for specific files sometimes require no subtle amount of scrolling. Add links from the whole picture to the dedicated sections for making the navigation easier. Signed-off-by: SeongJae Park --- Documentation/admin-guide/mm/damon/usage.rst | 70 ++++++++++++++------ 1 file changed, 49 insertions(+), 21 deletions(-) diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst index d3514367703b..671d3e50b998 100644 --- a/Documentation/admin-guide/mm/damon/usage.rst +++ b/Documentation/admin-guide/mm/damon/usage.rst @@ -59,43 +59,47 @@ Files Hierarchy The files hierarchy of DAMON sysfs interface is shown below. In the below figure, parents-children relations are represented with indentations, each directory is having ``/`` suffix, and files in each directory are separated by -comma (","). :: - - /sys/kernel/mm/damon/admin - │ kdamonds/nr_kdamonds - │ │ 0/state,pid - │ │ │ contexts/nr_contexts - │ │ │ │ 0/avail_operations,operations - │ │ │ │ │ monitoring_attrs/ +comma (","). + +.. parsed-literal:: + + :ref:`/sys/kernel/mm/damon `/admin + │ :ref:`kdamonds `/nr_kdamonds + │ │ :ref:`0 `/state,pid + │ │ │ :ref:`contexts `/nr_contexts + │ │ │ │ :ref:`0 `/avail_operations,operations + │ │ │ │ │ :ref:`monitoring_attrs `/ │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us │ │ │ │ │ │ nr_regions/min,max - │ │ │ │ │ targets/nr_targets - │ │ │ │ │ │ 0/pid_target - │ │ │ │ │ │ │ regions/nr_regions - │ │ │ │ │ │ │ │ 0/start,end + │ │ │ │ │ :ref:`targets `/nr_targets + │ │ │ │ │ │ :ref:`0 `/pid_target + │ │ │ │ │ │ │ :ref:`regions `/nr_regions + │ │ │ │ │ │ │ │ :ref:`0 `/start,end │ │ │ │ │ │ │ │ ... │ │ │ │ │ │ ... - │ │ │ │ │ schemes/nr_schemes - │ │ │ │ │ │ 0/action,apply_interval_us - │ │ │ │ │ │ │ access_pattern/ + │ │ │ │ │ :ref:`schemes `/nr_schemes + │ │ │ │ │ │ :ref:`0 `/action,apply_interval_us + │ │ │ │ │ │ │ :ref:`access_pattern `/ │ │ │ │ │ │ │ │ sz/min,max │ │ │ │ │ │ │ │ nr_accesses/min,max │ │ │ │ │ │ │ │ age/min,max - │ │ │ │ │ │ │ quotas/ms,bytes,reset_interval_ms + │ │ │ │ │ │ │ :ref:`quotas `/ms,bytes,reset_interval_ms │ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil - │ │ │ │ │ │ │ │ goals/nr_goals + │ │ │ │ │ │ │ │ :ref:`goals `/nr_goals │ │ │ │ │ │ │ │ │ 0/target_value,current_value - │ │ │ │ │ │ │ watermarks/metric,interval_us,high,mid,low - │ │ │ │ │ │ │ filters/nr_filters + │ │ │ │ │ │ │ :ref:`watermarks `/metric,interval_us,high,mid,low + │ │ │ │ │ │ │ :ref:`filters `/nr_filters │ │ │ │ │ │ │ │ 0/type,matching,memcg_id - │ │ │ │ │ │ │ stats/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds - │ │ │ │ │ │ │ tried_regions/total_bytes + │ │ │ │ │ │ │ :ref:`stats `/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds + │ │ │ │ │ │ │ :ref:`tried_regions `/total_bytes │ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age │ │ │ │ │ │ │ │ ... │ │ │ │ │ │ ... │ │ │ │ ... │ │ ... +.. _sysfs_root: + Root ---- @@ -104,6 +108,8 @@ has one directory named ``admin``. The directory contains the files for privileged user space programs' control of DAMON. User space tools or daemons having the root permission could use this directory. +.. _sysfs_kdamonds: + kdamonds/ --------- @@ -154,6 +160,8 @@ If the state is ``on``, reading ``pid`` shows the pid of the kdamond thread. ``contexts`` directory contains files for controlling the monitoring contexts that this kdamond will execute. +.. _sysfs_contexts: + kdamonds//contexts/ ---------------------- @@ -214,6 +222,8 @@ writing to and rading from the files. For more details about the intervals and monitoring regions range, please refer to the Design document (:doc:`/mm/damon/design`). +.. _sysfs_targets: + contexts//targets/ --------------------- @@ -221,6 +231,8 @@ In the beginning, this directory has only one file, ``nr_targets``. Writing a number (``N``) to the file creates the number of child directories named ``0`` to ``N-1``. Each directory represents each monitoring target. +.. _sysfs_target: + targets// ------------ @@ -255,6 +267,8 @@ In the beginning, this directory has only one file, ``nr_regions``. Writing a number (``N``) to the file creates the number of child directories named ``0`` to ``N-1``. Each directory represents each initial monitoring target region. +.. _sysfs_region: + regions// ------------ @@ -265,6 +279,8 @@ region by writing to and reading from the files, respectively. Each region should not overlap with others. ``end`` of directory ``N`` should be equal or smaller than ``start`` of directory ``N+1``. +.. _sysfs_schemes: + contexts//schemes/ --------------------- @@ -276,6 +292,8 @@ In the beginning, this directory has only one file, ``nr_schemes``. Writing a number (``N``) to the file creates the number of child directories named ``0`` to ``N-1``. Each directory represents each DAMON-based operation scheme. +.. _sysfs_scheme: + schemes// ------------ @@ -310,6 +328,8 @@ Note that support of each action depends on the running DAMON operations set The ``apply_interval_us`` file is for setting and getting the scheme's :ref:`apply_interval ` in microseconds. +.. _sysfs_access_pattern: + schemes//access_pattern/ --------------------------- @@ -323,6 +343,8 @@ to and reading from the ``min`` and ``max`` files under ``sz``, ``nr_accesses``, and ``age`` directories, respectively. Note that the ``min`` and the ``max`` form a closed interval. +.. _sysfs_quotas: + schemes//quotas/ ------------------- @@ -369,6 +391,8 @@ metrics for the values. Note that users should write ``commit_schemes_quota_goals`` to the ``state`` file of the :ref:`kdamond directory ` to pass the feedback to DAMON. +.. _sysfs_watermarks: + schemes//watermarks/ ----------------------- @@ -388,6 +412,8 @@ as below. The ``interval`` should written in microseconds unit. +.. _sysfs_filters: + schemes//filters/ -------------------- @@ -483,6 +509,8 @@ and query-like efficient data access monitoring results retrievals. For the latter use case, in particular, users can set the ``action`` as ``stat`` and set the ``access pattern`` as their interested pattern that they want to query. +.. _sysfs_schemes_tried_region: + tried_regions// ------------------