Ohledně té dokumentace --- pamatuji si třeba na bugu v jádrech 2.0, která byla nedostatečnou dokumentací způsobena: původně byla funkce mark_buffer_dirty() napsána tak, že se neblokuje. Autor ext2 filesystému si přečetl její implementaci, viděl, že se neblokuje, a použil ji takovým způsobem, že jeho kód na tom ne-blokování závisel. Po nějaké době vývojáři VFS změnili implementaci mark_buffer_dirty, aby se blokovala, a nevědomky tak udělali v ext2 race-condition.
Nejsem příznivce nějaké veliké byro-specifikace, ale u každé funkce, kterou mohou používat drivery, by se aspoň mělo napsat blokuje/neblokuje, může se volat z procesu/interruptu/timeru/softirq, může/musí/nesmí být drženy tyto locky. A pokud se tyto podmínky změní, tak nejlépe změnit název funkce, aby se drivery, co ji používají, neslinkovaly. Pokud jako vývojář driveru naleznu v jádře funkci, která se blokuje, pokud dostane argument třeba "3", nijak z toho kódu nepoznám, jestli je to blokování součást implementace (později ji můžou vývojáři přepsat, aby se blokovala za jiných podmínek) nebo jestli je to součástí architektury a je zaručeno, že se ve všech budoucích verzích bude blokovat pouze s tímto parametrem.

