helenos-nicf team mailing list archive

[Jirka Michalec <michy@xxxxxxxxxx>]

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