linux-kernel - Re: [PATCH v17 12/15] Documentation/admin-guide/mm: Add a document for DAMON

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Tue, 7 Jul 2020 10:49:06 +0300
From:   Mike Rapoport <rppt@...nel.org>
To:     SeongJae Park <sjpark@...zon.com>
Cc:     akpm@...ux-foundation.org, SeongJae Park <sjpark@...zon.de>,
        Jonathan.Cameron@...wei.com, aarcange@...hat.com, acme@...nel.org,
        alexander.shishkin@...ux.intel.com, amit@...nel.org,
        benh@...nel.crashing.org, brendan.d.gregg@...il.com,
        brendanhiggins@...gle.com, cai@....pw, colin.king@...onical.com,
        corbet@....net, dwmw@...zon.com, foersleo@...zon.de,
        irogers@...gle.com, jolsa@...hat.com, kirill@...temov.name,
        mark.rutland@....com, mgorman@...e.de, minchan@...nel.org,
        mingo@...hat.com, namhyung@...nel.org, peterz@...radead.org,
        rdunlap@...radead.org, riel@...riel.com, rientjes@...gle.com,
        rostedt@...dmis.org, sblbir@...zon.com, shakeelb@...gle.com,
        shuah@...nel.org, sj38.park@...il.com, snu@...zon.de,
        vbabka@...e.cz, vdavydov.dev@...il.com, yang.shi@...ux.alibaba.com,
        ying.huang@...el.com, david@...hat.com, linux-damon@...zon.com,
        linux-mm@...ck.org, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH v17 12/15] Documentation/admin-guide/mm: Add a document
 for DAMON

Hello SeongJae,

On Mon, Jul 06, 2020 at 01:53:19PM +0200, SeongJae Park wrote:
> From: SeongJae Park <sjpark@...zon.de>
> 
> This commit adds a document for DAMON under
> `Documentation/admin-guide/mm/damon/`.
> 
> Signed-off-by: SeongJae Park <sjpark@...zon.de>
> ---
>  Documentation/admin-guide/mm/damon/api.rst    |  20 ++
>  .../admin-guide/mm/damon/damon_heatmap.png    | Bin 0 -> 8366 bytes
>  .../admin-guide/mm/damon/damon_wss_change.png | Bin 0 -> 7211 bytes
>  .../admin-guide/mm/damon/damon_wss_dist.png   | Bin 0 -> 6173 bytes
>  Documentation/admin-guide/mm/damon/eval.rst   | 222 +++++++++++++
>  Documentation/admin-guide/mm/damon/faq.rst    |  59 ++++
>  .../admin-guide/mm/damon/freqmine_heatmap.png | Bin 0 -> 9999 bytes
>  .../admin-guide/mm/damon/freqmine_wss_sz.png  | Bin 0 -> 5589 bytes
>  .../mm/damon/freqmine_wss_time.png            | Bin 0 -> 6550 bytes
>  Documentation/admin-guide/mm/damon/guide.rst  | 194 ++++++++++++
>  Documentation/admin-guide/mm/damon/index.rst  |  35 +++
>  .../admin-guide/mm/damon/mechanisms.rst       | 159 ++++++++++
>  Documentation/admin-guide/mm/damon/plans.rst  |  29 ++
>  Documentation/admin-guide/mm/damon/start.rst  | 117 +++++++
>  .../mm/damon/streamcluster_heatmap.png        | Bin 0 -> 42210 bytes
>  .../mm/damon/streamcluster_wss_sz.png         | Bin 0 -> 6327 bytes
>  .../mm/damon/streamcluster_wss_time.png       | Bin 0 -> 8830 bytes
>  Documentation/admin-guide/mm/damon/usage.rst  | 296 ++++++++++++++++++
>  Documentation/admin-guide/mm/index.rst        |   1 +

It's really cool to see documentation along with the code!

I'd suggest to reorganize the DAMON docs to better match the current
structure of Documentation/ directory.

The description of DAMON usage from the userspace and reference for the
userland tools does belong to Documentation/admin-guide/mm. However, the
kernel APIs are better to be placed in Documentation/core-api or even
Documentation/dev-tools. As for the detailed description of the internal
DAMON operation, this would naturally belong to Documentation/vm.

Another thing is that this patch is really hard to review because of the
encoded png blobs. In general, we try to keep Documentation/ readable in
plain text, but if you think that the images are essential and must be a
part of DAMON in-tree docs rather than links to an external resource,
please split them to a separate patch.

-- 
Sincerely yours,
Mike.