helenos-nicf team mailing list archive

["Jan Záloha" <jzaloha@xxxxxxxxxx>]

Ahoj,
pracuji na dokumentaci uzivatelskeho rozhrani DMA alokatoru a DMA driver frameworku. Ale chtel bych se zeptat, jestli by nebylo lepsi dokumentaci kernelove casti presunout do kernel/doc/dma.
Jinak ad #69, o tom jsme se jiz bavili. Pokud pouzivame jine zpusoby WoL, tak asi neni nutne podporovat tenhle jeden specialni Mikrosroti, zvlaste pokud neni podporovan ani v Linuxu. Pokud po nem nekdo bude zasadne touzit, tak si jej muze naimplementovat sam.

Honza

______________________________________________________________
> Od: "Jirka Michalec" <michy@xxxxxxxxxx>
> Komu: "helenos-nicf" <helenos-nicf@xxxxxxxxxxxxxxxxxxx>
> Datum: 26.08.2011 22:53
> Předmět: [Helenos-nicf] Dokumentace
>
>Ahoj,
>
>doufal jsem, že budeme mít dnes příležitost probrat v kompletním počtu 
>na jabberu všechny nedodělky, ale Radimovi zřejmě nemoc znemožnila býti 
>online. Jelikož je dokumentace projektu dosti důležitou věcí (Zavoral 
>jednomu "svému" týmu sdělil, že dokumentace a prezentace jsou v podstatě 
>to, na základě čeho se projektová komise rozhoduje o obhájení), měli 
>bychom se domluvit na nějakém konceptu a kdo co do/sepíše a dovést 
>dokumentaci do nějakého slušného stavu.
>
>Za prvé s čistou instalací asciidocu + source-highlighting filteru 
>nejsem schopen vygenerovat dokumentaci do té podoby, v jaké je 
>commitnutá. Prosím tedy Radima, aby napsal stručný návod, jak toho 
>docílit - při generování příkazem 'asciidoc -f conf/asciidoc.conf -f 
>conf/xhtml11.conf helnet.txt' se neaplikuje žádné css krom oranžové 
>barvy u názvů $nazev, při nepoužití těchto konfiguračních souborů 
>('asciidoc helnet.txt') jsou zase tyto texty černé a včetně onoho dolaru 
>(ale na vše ostatní se stylování aplikuje stejně jako ve vygenerovaném 
>dokumentu).
>
>Co se jednotlivých částí týče, viděl bych to asi takto (ano, vím že 
>některé části už v dokumentaci jsou):
>1) Obsah s odkazy - ví někdo, jak toho docílit? Nejlépe tak, aby ve 
>vytištěné dokumentaci byla čísla stránek?
>2) Úvod s tím, co je HelenOS, že je síťování důležitou součástí dnešních 
>operačních systémů...
>---- prostě zdůraznění užitečnosti naší práce
>---- ve stávajícím textu vypustit zmíňky o předpokládaných znalostech a 
>vše relevantní popsat
>3) Přehledový popis architektury síťového stacku, DDF a memory 
>managementu v HelenOS
>---- principy IPC v HelenOS, async session a výhody
>---- principy memory backendů
>---- v podstatě to co tam je, nejlépe rozšířit o přehledové obrázky 
>(přeci obrázek občas zastoupí i několik odstavců textu)
>4) Popis NICF
>---- zdůraznit snahu o přesunutí co nejvíce práce do defaultních 
>implementací (zejména snaha o volání ručně psaného kódu jen pokud je 
>třeba sáhnout na HW)
>---- napojení na DDF, obrázek zobrazující možnou spolupráci DDF vrstvy, 
>NICF rozhraní, defaultních implementací, ručně psaného kódu (příp. i 
>HW), NICF knihovny (draft obrázku jsem si načrtl na papír, takže ho 
>předělám do elekntronického formátu)
>---- nejsem si jist, jestli výčet všech funkcí tak, jak je, je vhodný do 
>dokumentace, spíše do nějaké přílohy, spíše napsat, z jakých částí se 
>celkově NICF skládá a co k čemu slouží (libnic, nic_interface,...)
>5) Popis podpory DMA
>---- co a jak řeší, spolupráce se stávajícími alokátory, nový backend, 
>uspace rozhraní (co to umí)
>6) Popis jednotlivých implementovaných driverů
>---- tady je víceméně jasné, že kdo co dělal si zdokumentuje, bude 
>stačit popis toho, co karta umí, specifika jak pracuje a co je 
>implementované
>7) Vyvinuté nástroje + nepřímo související věci (mm registry v 
>přerušení),...
>---- spíše než koncepce ala man pages včetně všech možných argumentů (to 
>by bylo též vhodné spíše přesunout do přílohy) co to umí, proč to tam je 
>a příklady použití
>8) Jak napsat NIC driver
>---- základní driver, v podstatě po doplnění (a kontrole odpovídá-li to 
>současnému stavu) to, co napsal Radim
>9) Jak otestovat driver
>---- spuštění qemu, ping, spuštění více instancí, nictest
>---- čili jednak návod pro autora driveru, jak si co nejlépe otestovat 
>driver (aby měl i parametry qemu po ruce)
>---- a zároveň návod pro toho, kdo bude projekt testovat, jak si naše 
>vymoženosti vyzkouší
>---- tady mám docela rozmyšleno, co tam napsat, takže to bude další věc, 
>které bych se ujal přednostně sám
>
>10) User dokumentace
>---- popis jak si někdo může přeložit náš kód, kde získat aktuální 
>verzi, na jakých platformách apod.
>
>Future development
>---- určitě přidávání dalších driverů
>---- power management (uspávání při vytažení kabelu,...)
>---- další nápady?
>---- třeba odebírání karet (USB/PCMCIA)
>Project timeline
>---- tady bude muset někdo z nás projít zápisy, maily a logy z 
>repozitáře a dát to dohromady
>
>Co tam má být dále dle pořadavků z pravidel projektu:
>- Zasazení vytvořeného díla do kontextu existujících programových děl 
>řešících obdobnou problematiku
>---- což chápu tak, že bychom měli uvést i případná řešení v jiných OS, 
>dal bych to jako součást úvodu
>- kritické zhodnocení přijatých řešení a možnosti dalšího vývoje
>---- čili zmínit kontroverznější rozhodnutí a zvažované alternativy, z 
>hlavy si vzpomínám na architektury filtrů a stavy, ze zápisů toho bude 
>zřejmé více
>
>Další věcí, kterou musíme zkompletovat, je doxygenová stránka NICF a DMA 
>a provázanost s dalšími stránkami.
>
>Dále jsou stále v mantisu nepřidělené reporty, ale vesměs se jedná o 
>drobnosti (snad #77 by stálo za opravu a k #69 bych rád dostal nějaké 
>reakce). A Honzu bych poprosil o nějaké přehledové představení memory 
>serveru (řeší nebezpečí uvolnění paměti při pádu driveru, ačkoliv 
>hardware ji stále používá - memory server si ji na žádost driveru 
>nasdílí dokud mu driver neřekne, že danou paměť už HW nepoužívá), 
>abychom toto mohli ještě zakomponovat do driverů. A rozhodně by to pak 
>nemělo chybět v celkové dokumentaci.
>
>Prosím vyjádřete se k tomu, zda-li s takovouto strukturou souhlasíte, co 
>tam je navíc, chybí či má být jinak. Dále napiště, kdo co bude udělat 
>(včetně již naplánované práce jako testování či nedodělky v kódu). V 
>podstatě jsem vycházel z již stávajícího Radimova základu a podíval se 
>do pravidel projektů a dokumentace usb projektu.
>
>Já osobně krom zdokumentování rtl, popisu testování karet a přehledového 
>obrázku spolupráce vrstev uvnitř driveru, ještě naposledy otestuji karty 
>na reálném HW, včetně dosud neotestovaného zpracování pause packetu a 
>WoL. Samozřejmě si vezmu na starost i další věci, které mi budou 
>přiděleny při rozdělování.
>
>Jinak další věcí, na které se musíme domluvit, je kdo dokumentaci 
>vytiskne (zde by bylo opět vhodné sepsat, jak z asciidocu vygenerovat 
>tisknutelný dokument), vypálí CD a odevzdá. Bohužel jsem nikde nenašel, 
>kdy má paní sekretářka KTIML úřední hodiny, tudíž ani do kdy ve čtvrtek 
>se má dílo odevzdat.
>
>Jirka
>
>_______________________________________________
>Mailing list: https://launchpad.net/~helenos-nicf
>Post to     : helenos-nicf@xxxxxxxxxxxxxxxxxxx
>Unsubscribe : https://launchpad.net/~helenos-nicf
>More help   : https://help.launchpad.net/ListHelp
>