LWN：改进内存管理相关的文档！

关注了就能看到更多这么棒的文章哦～

Improving memory-management documentation

By Jonathan Corbet
May 10, 2022
LSFMM
DeepL assisted translation
https://lwn.net/Articles/894374/

如同内核的大部分内容一样，内存管理子系统的文档是不太够的，而且大部分现存文档也不完全是符合最新情况的。在 2022 年的 Linux 存储、文件系统、内存管理和 BPF 峰会（LSFMM）上，Mike Rapoport 主持了一个关于内存管理的文档的会议，以及如何改进它。这成功地重新激发了人们对文档的兴趣，但只有时间才能证明这些兴趣会带来什么实际的改进。

Rapoport 首先指出，几年前，他对内存管理相关文档的现状进行了仔细的检查。他发现的情况可以被总结为 "Mel's book and some text files"。这本书是 Mel Gorman 的 Understanding the Linux Virtual Memory Manager，它让人们想起了许多古老的 Unix 书籍：基本概念在很大程度上都是仍然适用的，但细节都已经过时了，也就是有问题的。有许多重要的内存管理功能如 transparent huge page 根本就没有提到。

关于内核 documentation 目录中的文本文件，Rapoport 努力将它们转换为 restructured 格式的文本，并将它们整合到内核的文档系统中，在这个过程中进行了一些非常需要的重新组织。他增加了更多一些内部 API 的覆盖，但仍有很多需要改进的地方。因此，他问道，怎样才能改进文档，并鼓励人们编写更多的文档？

他继续说，有一个主意是让 reviewer 在 review 内存管理 patch 时，要注意 review 相关的文档。他一直在朝这个方向努力，但还没有看到其他 reviewer 效仿。Matthew Wilcox 插了一句说，maple tree patch 都有很好的文档。Rapoport 同意，但他说这并不能改变内存管理社区还有很多 "部落知识（tribal wisdom）" 尚未以书面形式存在的事实。

另一位开发者指出，文档可以在两个不同的地方找到：在代码中，以及在内核的文档目录（Documentation/）下。他说，后者的文档并不尽如人意。有一些部分是用清晰的叙述文件（narrative）写的，但它混杂在 "噪音和写得不好的内容" 中。渲染生成的文档，将代码中的 kerneldoc 注释提取到了独立的文件中，这会把所有的东西混杂在一起，会让人难以使用。Andrew Morton 说，Documentation/ 适合存放面向用户的文档材料，但是其他情况下，应该在 code 里面来寻找文档。

作为 Documentation 目录的维护者，我这时候觉得有必要插一句了。我必须得对 Morton 的论调表示反对，我不赞同他说的独立文档只对最终用户有好处。有很多信息是跟开发者相关的，但这些信息并不适合在 kerneldoc 注释中出现，而且很难采用 kerneldoc 注释方式在代码中讲述一个连贯的故事。认为代码中的注释会比专门的文档能得到更好的维护的想法，最起码来说也是与现实不相符的。

在文档的组织方面，确实可以把介绍性的（introductory）以及上下文（contextual）信息放到 kerneldoc 注释中，并从这些注释中产生一个跟代码一致性很好的手册，但还是必须要为此做出额外努力了，而且最终结果只能在 build 系统完成文档生成之后才会出现在文档中，并不是存放在代码中。DRM 文档是一个很好的例子，这足以说明当开发者投入精力时，可以做什么。

确实文档组织工作一直是个问题；当我成为文档维护者时，内核的文档目录是一个看起来很随意的各种独立文件的集合。多年来，从事文档工作的开发人员一直在努力对这些材料进行更好地组织整理，关注重点是文档的读者是谁。因此，就出现了核心 API 手册、用户空间 API 指南、维护者手册以及其他一些手册。这虽然只是先创造了一堆文件较小的、无良好组织起来的、经常是过时的材料，但这是一个开始。可惜人们很少有时间去尝试改进这些手册，或者把每个手册变成一个连贯的文件，而不是像现在这样的所有关联文件的集合。

Wilcox 提到 Neil Brown 的 readahead 文档则刚好是个例子，代表了另一类问题。新增的文档 "90%是正确的"；Wilcox 应该是 review 过的，但没有被 copy 过，因为找不到是什么时候了。他认为 Brown 在做这些工作时没有使用代码中已经存在的文档，这让人感到沮丧。

一个反复出现的话题是，没有足够的人有时间和专业知识来做文档工作；应该鼓励开发者们去游说他们的雇主来支持这项工作。Michal Hocko 说，你不能随便找 "任意一个技术作家" 来写内存管理的文档；要写出有用的文档，会需要很多知识，所以需要有经验的人去写。Brown 的方法很好，因为他是使用这个接口的专家级用户，可以通过这些经验来审视和撰写。同时，Hocko 说，他在寻找文档时一般避免翻阅代码，而是查找 LWN 的档案。

我同意 Hocko 的观点，但不得不补充说，写文档是获得所需专业知识的一个好方法。我所知道的很多东西都是在从事 Linux 设备驱动工作时学到的；可以说，我在开始那个项目时并没有相关能力资格。

Davidlohr Bueso 声称，内核中最好的文件，也是其他人应该效仿的文件，是知名度很高的 memory-barriers.txt。它是由具有高水平的专业知识的开发人员所编写的，内容清晰，并得到了积极的维护；即使是新手也能从中得到一些收获。Johannes Weiner 说，memory-barriers.txt 的优点之一是，该文件从一开始就有一个很好的结构；这使得其他人来补充内容时就相对容易了。内存管理子系统需要有人来创建一个类似的文档结构。

Dan Williams 问道，内存管理文档的近期重点应该是什么，Rapoport 是否有计划要处理哪几个具体的 API 了？Rapoport 回答说，他的目标是使文档总体上更好，以便其他人能够理解 Linux 内存管理的工作方式。Williams 说这是 "一个很好的 mission statement"，但他更想看到的是一个有可操作的任务。Rapoport 建议以 speculative page fault 或 multi-generational LRU（这两个都还尚未合入 mainline）来开始。

Kent Overstreet 说，开发人员在代码 review 期间经常不会提出文档，而且子系统中没有一个人对文档应该是什么样子有一个总体一致的概念。Liam Howlett 说，作为一个新上手进行内存管理的开发人员，他遇到了许多他不理解的功能。当他修改代码时，他试图改进其文档。他特别提到了 find_vma()，这个函数的行为与它的名字或文档并不相符。

David Hildenbrand 问道，一般来说，内存管理需要什么文件。Rapoport 回答说，他希望首先在 admin guide 里面能看到更多的材料，最好是关于系统工作方式的一个总体概述。改进 kerneldoc 的注释在他的清单上则排在较后的位置，但这却也是比较容易做到的任务。会议围绕是更需要内部文档还是更需要面向用户的文档进行了一些讨论。有人建议，也许开发者对一些内部 API 进行的说明有些过多了，导致用户在他们其实不应该使用这些功能的时候使用了它们。

在会议结束时，Wilcox 建议，好的做法是，首先以 Gorman 的书为指导，创建一个新的内存管理文档，并自告奋勇来做这个工作。那本书的结构很明显得到了读者们的认可，那么从这个结构开始就可以解决文档组织结构的问题，并使开发人员容易改进。可以按照这个思路来创建一个 ReStructured Text 文件，并将现有的文档放入其中适当的地方。大家普遍认为这是一件好事。毫无疑问，有一个愿意采取起始步骤的开发者的存在，对这件事就是有巨大帮助的。此后，Wilcox 发布了新的文档结构的初始版本来供大家 review。

全文完
LWN 文章遵循 CC BY-SA 4.0 许可协议。

长按下面二维码关注，关注 LWN 深度文章以及开源社区的各种新近言论～