LWN：改進內(nèi)存管理相關(guān)的文檔！

關(guān)注了就能看到更多這么棒的文章哦～

Improving memory-management documentation

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

如同內(nèi)核的大部分內(nèi)容一樣，內(nèi)存管理子系統(tǒng)的文檔是不太夠的，而且大部分現(xiàn)存文檔也不完全是符合最新情況的。在 2022 年的 Linux 存儲、文件系統(tǒng)、內(nèi)存管理和 BPF 峰會（LSFMM）上，Mike Rapoport 主持了一個關(guān)于內(nèi)存管理的文檔的會議，以及如何改進它。這成功地重新激發(fā)了人們對文檔的興趣，但只有時間才能證明這些興趣會帶來什么實際的改進。

Rapoport 首先指出，幾年前，他對內(nèi)存管理相關(guān)文檔的現(xiàn)狀進行了仔細的檢查。他發(fā)現(xiàn)的情況可以被總結(jié)為 "Mel's book and some text files"。這本書是 Mel Gorman 的 Understanding the Linux Virtual Memory Manager，它讓人們想起了許多古老的 Unix 書籍：基本概念在很大程度上都是仍然適用的，但細節(jié)都已經(jīng)過時了，也就是有問題的。有許多重要的內(nèi)存管理功能如 transparent huge page 根本就沒有提到。

關(guān)于內(nèi)核 documentation 目錄中的文本文件，Rapoport 努力將它們轉(zhuǎn)換為 restructured 格式的文本，并將它們整合到內(nèi)核的文檔系統(tǒng)中，在這個過程中進行了一些非常需要的重新組織。他增加了更多一些內(nèi)部 API 的覆蓋，但仍有很多需要改進的地方。因此，他問道，怎樣才能改進文檔，并鼓勵人們編寫更多的文檔？

他繼續(xù)說，有一個主意是讓 reviewer 在 review 內(nèi)存管理 patch 時，要注意 review 相關(guān)的文檔。他一直在朝這個方向努力，但還沒有看到其他 reviewer 效仿。Matthew Wilcox 插了一句說，maple tree patch 都有很好的文檔。Rapoport 同意，但他說這并不能改變內(nèi)存管理社區(qū)還有很多 "部落知識（tribal wisdom）" 尚未以書面形式存在的事實。

另一位開發(fā)者指出，文檔可以在兩個不同的地方找到：在代碼中，以及在內(nèi)核的文檔目錄（Documentation/）下。他說，后者的文檔并不盡如人意。有一些部分是用清晰的敘述文件（narrative）寫的，但它混雜在 "噪音和寫得不好的內(nèi)容" 中。渲染生成的文檔，將代碼中的 kerneldoc 注釋提取到了獨立的文件中，這會把所有的東西混雜在一起，會讓人難以使用。Andrew Morton 說，Documentation/ 適合存放面向用戶的文檔材料，但是其他情況下，應(yīng)該在 code 里面來尋找文檔。

作為 Documentation 目錄的維護者，我這時候覺得有必要插一句了。我必須得對 Morton 的論調(diào)表示反對，我不贊同他說的獨立文檔只對最終用戶有好處。有很多信息是跟開發(fā)者相關(guān)的，但這些信息并不適合在 kerneldoc 注釋中出現(xiàn)，而且很難采用 kerneldoc 注釋方式在代碼中講述一個連貫的故事。認為代碼中的注釋會比專門的文檔能得到更好的維護的想法，最起碼來說也是與現(xiàn)實不相符的。

在文檔的組織方面，確實可以把介紹性的（introductory）以及上下文（contextual）信息放到 kerneldoc 注釋中，并從這些注釋中產(chǎn)生一個跟代碼一致性很好的手冊，但還是必須要為此做出額外努力了，而且最終結(jié)果只能在 build 系統(tǒng)完成文檔生成之后才會出現(xiàn)在文檔中，并不是存放在代碼中。DRM 文檔是一個很好的例子，這足以說明當開發(fā)者投入精力時，可以做什么。

確實文檔組織工作一直是個問題；當我成為文檔維護者時，內(nèi)核的文檔目錄是一個看起來很隨意的各種獨立文件的集合。多年來，從事文檔工作的開發(fā)人員一直在努力對這些材料進行更好地組織整理，關(guān)注重點是文檔的讀者是誰。因此，就出現(xiàn)了核心 API 手冊、用戶空間 API 指南、維護者手冊以及其他一些手冊。這雖然只是先創(chuàng)造了一堆文件較小的、無良好組織起來的、經(jīng)常是過時的材料，但這是一個開始。可惜人們很少有時間去嘗試改進這些手冊，或者把每個手冊變成一個連貫的文件，而不是像現(xiàn)在這樣的所有關(guān)聯(lián)文件的集合。

Wilcox 提到 Neil Brown 的 readahead 文檔則剛好是個例子，代表了另一類問題。新增的文檔 "90%是正確的"；Wilcox 應(yīng)該是 review 過的，但沒有被 copy 過，因為找不到是什么時候了。他認為 Brown 在做這些工作時沒有使用代碼中已經(jīng)存在的文檔，這讓人感到沮喪。

一個反復(fù)出現(xiàn)的話題是，沒有足夠的人有時間和專業(yè)知識來做文檔工作；應(yīng)該鼓勵開發(fā)者們?nèi)ビ握f他們的雇主來支持這項工作。Michal Hocko 說，你不能隨便找 "任意一個技術(shù)作家" 來寫內(nèi)存管理的文檔；要寫出有用的文檔，會需要很多知識，所以需要有經(jīng)驗的人去寫。Brown 的方法很好，因為他是使用這個接口的專家級用戶，可以通過這些經(jīng)驗來審視和撰寫。同時，Hocko 說，他在尋找文檔時一般避免翻閱代碼，而是查找 LWN 的檔案。

我同意 Hocko 的觀點，但不得不補充說，寫文檔是獲得所需專業(yè)知識的一個好方法。我所知道的很多東西都是在從事 Linux 設(shè)備驅(qū)動工作時學(xué)到的；可以說，我在開始那個項目時并沒有相關(guān)能力資格。

Davidlohr Bueso 聲稱，內(nèi)核中最好的文件，也是其他人應(yīng)該效仿的文件，是知名度很高的 memory-barriers.txt。它是由具有高水平的專業(yè)知識的開發(fā)人員所編寫的，內(nèi)容清晰，并得到了積極的維護；即使是新手也能從中得到一些收獲。Johannes Weiner 說，memory-barriers.txt 的優(yōu)點之一是，該文件從一開始就有一個很好的結(jié)構(gòu)；這使得其他人來補充內(nèi)容時就相對容易了。內(nèi)存管理子系統(tǒng)需要有人來創(chuàng)建一個類似的文檔結(jié)構(gòu)。

Dan Williams 問道，內(nèi)存管理文檔的近期重點應(yīng)該是什么，Rapoport 是否有計劃要處理哪幾個具體的 API 了？Rapoport 回答說，他的目標是使文檔總體上更好，以便其他人能夠理解 Linux 內(nèi)存管理的工作方式。Williams 說這是 "一個很好的 mission statement"，但他更想看到的是一個有可操作的任務(wù)。Rapoport 建議以 speculative page fault 或 multi-generational LRU（這兩個都還尚未合入 mainline）來開始。

Kent Overstreet 說，開發(fā)人員在代碼 review 期間經(jīng)常不會提出文檔，而且子系統(tǒng)中沒有一個人對文檔應(yīng)該是什么樣子有一個總體一致的概念。Liam Howlett 說，作為一個新上手進行內(nèi)存管理的開發(fā)人員，他遇到了許多他不理解的功能。當他修改代碼時，他試圖改進其文檔。他特別提到了 find_vma()，這個函數(shù)的行為與它的名字或文檔并不相符。

David Hildenbrand 問道，一般來說，內(nèi)存管理需要什么文件。Rapoport 回答說，他希望首先在 admin guide 里面能看到更多的材料，最好是關(guān)于系統(tǒng)工作方式的一個總體概述。改進 kerneldoc 的注釋在他的清單上則排在較后的位置，但這卻也是比較容易做到的任務(wù)。會議圍繞是更需要內(nèi)部文檔還是更需要面向用戶的文檔進行了一些討論。有人建議，也許開發(fā)者對一些內(nèi)部 API 進行的說明有些過多了，導(dǎo)致用戶在他們其實不應(yīng)該使用這些功能的時候使用了它們。

在會議結(jié)束時，Wilcox 建議，好的做法是，首先以 Gorman 的書為指導(dǎo)，創(chuàng)建一個新的內(nèi)存管理文檔，并自告奮勇來做這個工作。那本書的結(jié)構(gòu)很明顯得到了讀者們的認可，那么從這個結(jié)構(gòu)開始就可以解決文檔組織結(jié)構(gòu)的問題，并使開發(fā)人員容易改進。可以按照這個思路來創(chuàng)建一個 ReStructured Text 文件，并將現(xiàn)有的文檔放入其中適當?shù)牡胤健４蠹移毡檎J為這是一件好事。毫無疑問，有一個愿意采取起始步驟的開發(fā)者的存在，對這件事就是有巨大幫助的。此后，Wilcox 發(fā)布了新的文檔結(jié)構(gòu)的初始版本來供大家 review。

全文完
LWN 文章遵循 CC BY-SA 4.0 許可協(xié)議。

長按下面二維碼關(guān)注，關(guān)注 LWN 深度文章以及開源社區(qū)的各種新近言論～