User: Password:
Subscribe / Log in / New account

Drivers as documentation

Drivers as documentation

Posted Nov 24, 2011 10:30 UTC (Thu) by wsa (guest, #52415)
Parent article: Drivers as documentation

The recommendations given here how code and documentation should be are very valid. Yet, I feel you have been hit by a bad example (which _are_ in the kernel, sadly), and generalize from that, which I feel, is inapropriate.

I am mainly active in driver subsystems which are used for current SoCs, so more than one. In none of those subsystems, such hardcoded values you mentioned would hardly ever pass a review. Comments are also required every time the datasheet is wrong or unclear. Most reviewers are very aware of that and insist on that. The bigger problem here IMHO is that it is often very hard to see if a developer spent days on a simple writel(), because it is one of many writel() in the code. So, for a review which goes into that level of detail, a reviewer would have to study the datasheet at least as deep as the driver author. Deeper would be even better. Given that usually around 60% of all changes per release go to drivers, this is unlikely to happen. Most subsystems are already short of reviewers, because the code affects less people. We have a scaling problem here, and sadly, this is no news. Spreading the word like this hopefully helps a little bit, although I'd think this should more go to driver developers than reviewers...

(Log in to post comments)

Drivers as documentation

Posted Nov 25, 2011 5:59 UTC (Fri) by jzbiciak (subscriber, #5246) [Link]

It wouldn't surprise me if some of these magic constants bleed into kernel code because they came from a poorly documented reference implementation from the vendor itself. It could be that the Linux driver writer never knew the full interpretation of the magic constant to begin with.

Drivers as documentation

Posted Nov 25, 2011 10:10 UTC (Fri) by wsa (guest, #52415) [Link]

Yup, that's why I wrote 'hardly'. There are also drivers which mainly copy sniffed behaviour, but work fine, nonetheless. But that's a detail, the bigger issues are outlined above.

Copyright © 2018, Eklektix, Inc.
Comments and public postings are copyrighted by their creators.
Linux is a registered trademark of Linus Torvalds