Как сделать разделы ядра 9 справочными страницами, в которых описываются функции, структуры данных и заголовки?

Исходники ядра содержат функции и структуры данных, которые документированы, например, в panic.c:

/**
 *  panic - halt the system
 *  @fmt: The text string to print
 *
 *  Display a message, then perform cleanups.
 *
 *  This function never returns.
 */
void panic(const char *fmt, ...)

Вместо того, чтобы каждый раз просматривать источники, было бы полезно рассматривать эти API как справочные страницы и использовать существующую структуру документации.

Как установить / сделать раздел ядра 9 manpages ( /usr/share/man/man9), который документирует вышеупомянутые функции и структуры данных?

Содержание анализируется непосредственно (см также это ) от источника .c файлов ¹ :

Для обеспечения встроенной, удобной в обслуживании, удобной в обслуживании, но непротиворечивой и извлекаемой документации функций и структур данных в ядре Linux, ядро ​​Linux приняло согласованный стиль для документирования функций и их параметров, а также структур и их члены.

Формат этой документации называется форматом kernel-doc. Это задокументировано в этом файле Documentation / kernel-doc-nano-HOWTO.txt.

Этот стиль встраивает документацию в исходные файлы, используя несколько простых соглашений. Сценарии Perl scripts / kernel-doc, некоторые шаблоны SGML в Documentation / DocBook и другие инструменты понимают эти соглашения и используются для извлечения этой встроенной документации в различные документы. [...]

Начальная отметка комментария "/ **" зарезервирована для комментариев ядра-документа. Сценарии kernel-doc будут рассматривать только помеченные комментарии, а любой помеченный комментарий должен быть в формате kernel-doc.

Это означает, что таким образом могут быть извлечены только такие отформатированные комментарии, и что вы можете использовать скрипт Perl, используемый процессом:kernel-doc make

kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]
  [ -no-doc-sections ]
  [ -function funcname [ -function funcname ...] ]
  c file(s)s > outputfile

и , следовательно, вы не ограничены mandocs цели :

После установки "make psdocs", "make pdfdocs", "make htmldocs" или "make mandocs" отобразит документацию в требуемом формате.

В репозитории / источнике ядра также есть текстовые файлы драйверов . В более общем плане, их проект man-страниц Linux (от man1 до man8 ) доступен для скачивания. И последнее замечание: kernel.org также поддерживает некоторую выходную документацию.

^{1. Ядро - не единственный случай, когда такая техника используется для генерации man-страниц. GNU coreutils - еще один такой случай; большинство его страниц руководств которые генерируются с использованием выходного сигнала command --helpсодержания , который находится в использовании функции утилиты исходного файл ( 1 2 ).}

Предполагая, что вы используете Ubuntu,

apt-get install linux-manual-3.2

или аналогичный (выберите правильную версию). Существует также еще один пакет документации

apt-get install linux-doc

но это HTML.

Загрузите исходный код ядра и в исходном каталоге выполните dir

make mandocs

После того, как мужчина документы были сделаны, выполните

make installmandocs

Это установит справочные страницы в /usr/local/man/man9/. Теперь вы можете просматривать справочные страницы, набрав man <api-name>, или, если вы редактируете, vimпросто нажмите Kна имя API.