From patchwork Thu May 25 21:43:14 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: SeongJae Park X-Patchwork-Id: 13255705 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 0A3C2C7EE2F for ; Thu, 25 May 2023 21:43:47 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 15BA3900006; Thu, 25 May 2023 17:43:31 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 0F7EB90000B; Thu, 25 May 2023 17:43:31 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id D55C2900006; Thu, 25 May 2023 17:43:30 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0016.hostedemail.com [216.40.44.16]) by kanga.kvack.org (Postfix) with ESMTP id C02AD900009 for ; Thu, 25 May 2023 17:43:30 -0400 (EDT) Received: from smtpin29.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay04.hostedemail.com (Postfix) with ESMTP id 8A3D61A0CD2 for ; Thu, 25 May 2023 21:43:30 +0000 (UTC) X-FDA: 80830104180.29.4A49B19 Received: from dfw.source.kernel.org (dfw.source.kernel.org [139.178.84.217]) by imf29.hostedemail.com (Postfix) with ESMTP id 42BE0120013 for ; Thu, 25 May 2023 21:43:28 +0000 (UTC) Authentication-Results: imf29.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=oQoq8UhP; spf=pass (imf29.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=1685051008; a=rsa-sha256; cv=none; b=Dv+4y3UkzYiw0eV+aNdMbpCN2xX97kIqdZEmARmNfZDHK7TUp9CWrtHjSpk5kK364qm0cz VpJnCm13h4WENX9ymLWIUgPdn52HUMGhPbTH7xpvLH4yH5oBknQQXD5cGuSVvOd654fWfw sPAhBHXTbP5GALKzIdumPwOWcR5TRwU= ARC-Authentication-Results: i=1; imf29.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=oQoq8UhP; spf=pass (imf29.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=1685051008; 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=C8HK/wu9JHzuMNBAUGD9ZvBrx/8Nv6JG92qxVoJ3sNo=; b=nrvxJYtWVXih91IlPwL3La4dXSPXiiwLuavMDz/HHOsKRqgA8NHSOfQi4Yw9uG/8B2nL/k 0b6e0HIYWOUo/6BOL9gcTjppjTKeGU8o5jWgtmqrmFJuNVaJKbDbNuuRhnVZz3IIWNsvRj /I8XXH5rxnV8f4zPmpVQtUrJ9DbDRMU= Received: from smtp.kernel.org (relay.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dfw.source.kernel.org (Postfix) with ESMTPS id 8142464B66; Thu, 25 May 2023 21:43:28 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id CEB18C4339B; Thu, 25 May 2023 21:43:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1685051008; bh=FlZuBr64knJ/8JP07S/l782gvTE23ogKRh6IGqK2gr4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=oQoq8UhP0KDP7dsBgoau7JHv8ZbqA6Mk7eyiEYs20eSZPB60Mjy409eVD8M/aQbcD mhvONiRVkwQMiWpQGy2aEq1iysz8wQCGutpD9He8OmINpO43C2I9f5UyxRx6vhrG4Z GwcABZVvgk4YVQjaRrLPmRteCzz0RDRcEUGPTHo7kGfrm/9Wut7jkkoODWdXCwnyqL 2QSlv7J+B+eRSGGOID/CsZSG7dx3wZpcXnLYkLriEdYkwxsu2Cwwh9ggRTJ9ddWH/H TYT5d7LSPqBsKYp11iYGrWaFXldnJdRFsJi8Mfohaq/HnpLfAVzXP4HIjxacxLtoHc acztIb1xTvRQA== 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 10/10] Docs/mm/damon/design: add a section for the modules layer Date: Thu, 25 May 2023 21:43:14 +0000 Message-Id: <20230525214314.5204-11-sj@kernel.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20230525214314.5204-1-sj@kernel.org> References: <20230525214314.5204-1-sj@kernel.org> MIME-Version: 1.0 X-Rspamd-Server: rspam08 X-Rspamd-Queue-Id: 42BE0120013 X-Stat-Signature: 6rbhhc5fgxhofhtjuwgdcuk5qw156qiq X-Rspam-User: X-HE-Tag: 1685051008-530507 X-HE-Meta: U2FsdGVkX1/Z+Wo7ONdDMDT0gV32k7Z8LWvpN2KfCxrkP5wBPmA6W0Cu7TAdu4iO1/S0IO+piDadB+c/c0IRjJmMjFtPzo65Jj9y6qY0/kmG0AHTYVEzIqmziZMvpUEbUcMUmOA1c+0Xe3Vtjfeb3iDDRiO+rozWQt7GlEFeefg7R3+KIqog9m03oUGCH12bMbp6W8UxWQVL8LnOrJxPZ+iwSKT3rmBK47wcoCM7IN1+Z881LJXSbOCpV85N4Mz6aQjalLxVsOb4vTy1gwD8RxW/3bSSufhHg1LjPX21E0DWjG2SNNoXhqaIIsOZU0CeGNYRj1heRML9EgkINDyB3vN6DvnhY4n+KY4ZAaGK+73JEvFiq4b/3us4cVWnX5SIHTFCZuDunin8Cuo1kfLzyA8Fe3PU1/v++BsIjtWn+DkmEHaOCnBQ+a8TFsbkMTpBe07FFYQabYjJqvUIOo+IyUK48XZ0XaC6GuUlzxQ8tdGo/bHQY7RCKyGfk9zAtlzbqMrkp6uwLoNCCcaqimGbjTCdUqyFnqdXMoHe/pvFE2pKimR4UwshqTu0VhIHJZdAfCruNcPmid6cB4V8eHTRjK19Bua8yeesI0aHvq1Glc8ELnk7xc1N0SsXcu3WPP94blgQfVLFtYJbD26J0sexnbje/8UmvY6+szDiVqXz/CQFTYSGOh3SaJMCEOJORNDn97mmoEE8y8FmSeHoyBUgSpPa7+IU0AgcZQVkM049fpb6nu5j+s3sJvmGHSq0FyWitUkeY9+YceJoAPysBdFIut/ESkNT9gg3XsE/Rez6QVpc7SfYF10UYOB0eS15COgbq8ozPfCSwBLccM/FVAIczdc4TsLLY2j9KVmE/hZktdVXpVYRncr68sCZkH5uIAHO9kZVJkbyOt+YItUtwAjLIW7rH2eTe2F+PPB4VBx8POOlxhmABIljUireJHijH5J5hOvRN9+m21izvuJRTfS 2KJ6Lx8/ 1mF0Jt3YxC4CvXbN1CKvB3vKFQxwPjbnn0u9ok5P6hYOSHT+7M7GNhj/ThxbB5FEfPSHAK94NwZcznSHE+2MQDDTMIj241b0zbNdynn2NXdBfz4thdKGHMZGie8nwRDnVQO2I/5r6Zy86IXQJ6DUD5cZEkcSdTt0vvAc7OM0/BiBImFg8pvcER/FOqpd79KVOOSfH/NJWKwMTf9nM7G/Gw3/lOqDaak1IyCh1gxJIFSdSWI9cFdxeUPt1lzbTCyCf9S0nlwAddbEhR+aao1ZkLkwPME5eVR6OZ6AuT43AkP8LQtIdYsPsjp2+gDEZOO8ehm4itQpQ3aj9PT2BpTE3RitO9TSDBh2ZLJCM7aA1yQ2ogutJr25Uo0YVPe2PRCy27zjt5ihXaJTr/XNsfquFc7mj8ifgeOj5FUS2G6qis2NjdjvqeT+D6qSukwLoOFHt1at0Oajofa7T+Zz7VmneTPTV/EmMv1zlJySr 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: Add a section for covering DAMON modules layer to the design document. Signed-off-by: SeongJae Park --- Documentation/mm/damon/design.rst | 61 +++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst index 0ccdd2f6af9f..da110e89cab4 100644 --- a/Documentation/mm/damon/design.rst +++ b/Documentation/mm/damon/design.rst @@ -370,3 +370,64 @@ access-aware applications using DAMON's core features. For this, DAMON exposes its all features to other kernel components via its application programming interface, namely ``include/linux/damon.h``. Please refer to the API :doc:`document ` for details of the interface. + + +Modules +======= + +Because the core of DAMON is a framework for kernel components, it doesn't +provide any direct interface for the user space. Such interfaces should be +implemented by each DAMON API user kernel components, instead. DAMON subsystem +itself implements such DAMON API user modules, which are supposed to be used +for general purpose DAMON control and special purpose data access-aware system +operations, and provides stable application binary interfaces (ABI) for the +user space. The user space can build their efficient data access-aware +applications using the interfaces. + + +General Purpose User Interface Modules +-------------------------------------- + +DAMON modules that provide user space ABIs for general purpose DAMON usage in +runtime. + +DAMON user interface modules, namely 'DAMON sysfs interface' and 'DAMON debugfs +interface' are DAMON API user kernel modules that provide ABIs to the +user-space. Please note that DAMON debugfs interface is currently deprecated. + +Like many other ABIs, the modules create files on sysfs and debugfs, allow +users to specify their requests to and get the answers from DAMON by writing to +and reading from the files. As a response to such I/O, DAMON user interface +modules control DAMON and retrieve the results as user requested via the DAMON +API, and return the results to the user-space. + +The ABIs are designed to be used for user space applications development, +rather than human beings' fingers. Human users are recommended to use such +user space tools. One such Python-written user space tool is available at +Github (https://github.com/awslabs/damo), Pypi +(https://pypistats.org/packages/damo), and Fedora +(https://packages.fedoraproject.org/pkgs/python-damo/damo/). + +Please refer to the ABI :doc:`document ` for +details of the interfaces. + + +Special-Purpose Access-aware Kernel Modules +------------------------------------------- + +DAMON modules that provide user space ABI for specific purpose DAMON usage. + +DAMON sysfs/debugfs user interfaces are for full control of all DAMON features +in runtime. For each special-purpose system-wide data access-aware system +operations such as proactive reclamation or LRU lists balancing, the interfaces +could be simplified by removing unnecessary knobs for the specific purpose, and +extended for boot-time and even compile time control. Default values of DAMON +control parameters for the usage would also need to be optimized for the +purpose. + +To support such cases, yet more DAMON API user kernel modules that provide more +simple and optimized user space interfaces are available. Currently, two +modules for proactive reclamation and LRU lists manipulation are provided. For +more detail, please read the usage documents for those +(:doc:`/admin-guide/mm/damon/reclaim` and +:doc:`/admin-guide/mm/damon/lru_sort`).