The Kernel API Reference

26.6.2006 21:32 | Přečteno: 1138× | Software | poslední úprava: 27.6.2006 21:30

Nepříjemným problémem při vývoji nových ovladačů (a dalších věcí do jádra) pro Linux je chybějící referenční dokumentace API linuxového jádra. Nyní už je tu ale něco, co by mohlo v tomto ohledu pomoci.

Možná si ještě někdo vzpomene, že jsem se tu zhruba před rokem ptal v diskusi, zda někde neexistuje referenční dokumentace API Linuxu. Dostal jsem tehdy pár podnětných odpovědí - jedna z nich vedla na skutečný pokus o takovou dokumentaci, ovšem pro jádra 2.4 a ještě v dost neúplné podobě. Mnohem důležitější se ale ukázal jiný nápad - generovat dokumentaci ze zdrojáků.

Protože muset každou chvíli prolézat headery jádra jen kvůli tomu, abych věděl, jak volat nějakou funkci nebo jaké položky obsahuje nějaká struktura, je dost otravné, skutečně jsem tehdy skončil u toho, že jsem si pomocí programu Doxygen jakousi referenční dokumentaci API vygeneroval. Byla užitečná, nicméně tomu něco chybělo.

To "něco" byly informace, co příslušná funkce nebo makro dělá, co znamenají jednotlivé argumenty, totéž pro struktury atd. Problém je, že headery takovými informacemi buď vůbec neoplývají, a když, tak hodně strohými. Ale i za tyto informace by byl člověk vděčný, ovšem v podobě, v jaké normálně jsou, je Doxygen nevstřebá.

Postupem času jsem tedy vytvořil pravidla pro sed, která se na hlavičkové soubory aplikují, a komentáře u struktur a prototypů funkcí se jimi zpracují do použitelnější podoby. Pak už skutečně stačí spustit Doxygen a nechat si vygenerovat dokumentaci.

Protože je jasné, že by výsledek tohoto snažení mohl být užitečný i pro další lidi, dávám ho nyní k dispozici na adrese www.kernel-api.org. Dokumentace je tam k dispozici pro všechna jádra řady 2.6, a pak vždy pro poslední jádra všech stabilních řad. Čistě pro zajímavost je tam též prapůvodní jádro 0.99.

Dokumentaci lze prohlížet přímo online, anebo stáhnout v některém nabízeném formátu (GZIP, BZIP2, ZIP). Pozor ovšem, zejména u posledních verzí se jedná o balíky o řádové velikosti 40-70 MB.

Je jasné, že vzniklá dokumentace je velice nedokonalá (tím spíš, že byla generována automaticky a nebylo v mých silách ani časových možnostech ji kontrolovat). Nabízím ji proto, že je v tuto chvíli aspoň něco a do budoucna se na tom dá dále pracovat. Samozřejmě uvítám jakékoli náměty a připomínky. Ještě připomínám (uvádím to i přímo u dokumentace), že to nemá být konkurence cross-referencí Linuxu - naopak, oba zdroje se dobře doplňují. Možná by to šlo v budoucnu sloučit, uvidí se.

Takže kdo má zájem, nechť prohlíží a stahuje. Kdyby to někomu i jen sebenepatrněji pomohlo, má tento projekt smysl.

UPDATE 27.6.2006: Zasláno do LKML - zde je přímý odkaz.

---

• Adresa: www.kernel-api.org

       

Komentáře

[Thunder.m]

Teda, fakt hodně zajímavé!

[Zdeněk Štěpánek]

Nenapsal jsi o tom, tak nevim jestli neco v tehle veci uz nepodnikas.

Myslim si, ze by bylo fajn to oznamit do LKML a navrhnout stadnard pro psani komentaru k funkcim, aby bylo z ceho cerpat zminene informace.

Zdenek

[Luk]

V tomto jsem zatím nepodnikl vůbec nic, i když s tím počítám, a to co nejdřív.

Jen u toho psaní komentářů jsem docela skeptický. Je to bohužel tak, že většina vývojářů (nejen jádra) je píše dost nerada. Ale třeba by se někteří nechali přesvědčit

[Robert Krátký]

V tomto jsem zatím nepodnikl vůbec nic, i když s tím počítám, a to co nejdřív.

Hodíš sem pak link na to vlákno?

[Luk]

Je to tam

[Marián André]

K tomuto by som si dovolil doplniť odkaz na vznikajúci Linux Device Driver Kit.

[Nikola Ciprich]

super!

ohledne psani komentaru vyvojari bych nebyl takovy skepticky - myslim ze tento projekt ma potencial ukazat jejich uzitecnost, a staci kdyz to udela dojem na Linuse aby trosku updatoval Documentation/CodingStyle

respect!

[Bluebear]

Aleluja! Tohle bylo uz dlouho potreba, diky ti!