Bagaimana cara membuat kernel bagian 9 mengelola halaman mana fungsi dokumen, struktur data, dan header?

Kernel sumber mengandung fungsi dan struktur data yang didokumentasikan, misalnya dalam 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, ...)

Alih-alih menelusuri sumber setiap kali, akan bermanfaat untuk melihat API tersebut sebagai halaman manual dan memanfaatkan kerangka dokumentasi yang ada ini.

Bagaimana Anda menginstal / membuat halaman kernel bagian 9 ( /usr/share/man/man9) yang mendokumentasikan fungsi dan struktur data yang disebutkan di atas?

Konten diuraikan secara langsung (lihat juga ini ) dari sumber .c file ¹ :

Untuk menyediakan dokumentasi yang tertanam, 'C', mudah dipelihara, tetapi konsisten dan dapat diekstrak dari fungsi dan struktur data di kernel Linux, kernel Linux telah mengadopsi gaya yang konsisten untuk mendokumentasikan fungsi dan parameternya, dan struktur serta anggota

Format untuk dokumentasi ini disebut format kernel-doc. Itu didokumentasikan dalam file Documentation / kernel-doc-nano-HOWTO.txt ini.

Gaya ini menyematkan dokumentasi dalam file sumber, menggunakan beberapa konvensi sederhana. Script / skrip perl kernel-doc, beberapa templat SGML di Dokumentasi / DocBook, dan alat-alat lain memahami konvensi ini, dan digunakan untuk mengekstrak dokumentasi tersemat ini ke dalam berbagai dokumen. [...]

Tanda komentar pembuka "/ **" dicadangkan untuk komentar kernel-doc. Hanya komentar yang ditandai yang akan dipertimbangkan oleh skrip kernel-doc, dan komentar apa pun yang ditandai harus dalam format kernel-doc.

Yang berarti hanya komentar yang diformat yang dapat diekstraksi dengan cara ini dan Anda dapat memanfaatkan skrip Perl yang digunakan oleh proses:kernel-doc make

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

dan karena itu Anda tidak terbatas pada target mandocs :

Setelah instalasi, "make psdocs", "make pdfdocs", "make htmldocs", atau "make mandocs" akan menyajikan dokumentasi dalam format yang diminta.

Ada juga file teks khusus driver di repositori / sumber kernel. Secara umum, proyek halaman manual Linux mereka ( man1 hingga man8 ) tersedia untuk diunduh. Pada catatan terakhir kernel.org juga menyimpan beberapa dokumentasi keluaran .

^{1. Kernel bukan satu-satunya kasus di mana teknik seperti itu digunakan untuk menghasilkan halaman manual. GNU coreutils adalah salah satu kasus lainnya; sebagian besar halaman manualnya dihasilkan menggunakan output dari command --helpkonten yang dalam fungsi penggunaan file sumber utilitas ( 1 2 ).}

Dengan asumsi Anda menggunakan Ubuntu,

apt-get install linux-manual-3.2

atau serupa (pilih versi yang benar). Ada juga paket dokumentasi lain

apt-get install linux-doc

tapi ini html.

Unduh kode sumber kernel dan jalankan di source source

make mandocs

Setelah dokumen pria dibuat, jalankan

make installmandocs

Ini akan menginstal halaman buku panduan /usr/local/man/man9/. Sekarang Anda dapat melihat halaman manual dengan mengetik man <api-name>, atau jika Anda mengedit vimcukup tekan Knama API.