User: Password:
|
|
Subscribe / Log in / New account

The code is the documentation often

The code is the documentation often

Posted Oct 10, 2006 8:32 UTC (Tue) by arjan (subscriber, #36785)
Parent article: Device drivers and non-disclosure agreements

(disclaimer: I work for Intel but don't speak for Intel nor do I speak about Intel below; my comments are generic and from a broad experience outside Intel in a previous life)

It's nice to request documentation for hardware, some people do it politely, others try to use unfriendly ways such as verbal abuse or blackmail. And for many things, documentation is actually available. If you look at it, most things that have good driver-writer documentation available are those which are around for a long time, with slightly different revisions over time (e1000 is such an example from Intel, other companies have similar examples; especially in the server/enterprise space you will find this kind of hardware with good docs).

However that's only one half of the story. For many pieces of hardware, no such driver-writer level documentation exists! At all. Often the driver (often only the Windows one) gets developed together with the hardware, and the driver ends up BEING the documentation. (sometimes there is a document that claims to be documentation but is utterly useless for writing an actual driver from; and often even that doesn't exist).

Theo and others can jump up and down the vendors throat all they want, but what doesn't exist doesn't exist. No amount of begging, pleading, violence, threats and PR changes that.

In addition, with a consumer product shelf life of 3 to 6 months, companies that make such consumer electronics usually don't want to waste the time (and time to market) to create detailed and good enough documentation. And once the product is on the shelves, they're no longer going to care, they know it's gone in 3 months so spending resources is only a waste of money. That's not bad will, that's simple economics of the cutthroat market. Again the server space is better for this, and you'll see companies care more there.

Now it's not all bleak: there is documentation! Just not in the traditional PDF form. It exists in the form of source code that is released for, say, Linux. If you're lucky that is. The sucky cases are when there isn't any open driver at all (hi Nvidia). Let me repeat that: A good open source driver is usually worth 100 times more than the shoddy PDF that's called "documentation"; if it exists at all.

A note about your webcam example: Even the best and most open driver-documentation will have tables like "to make this work, put these 20 values in the registers". Sometimes a vendor can explain what each value means, but often it's just a case of "these 20 worked and we tested that. anything else we don't know". It's nice to know each individual value and what it means, but reality is that often an individual value has no meaning on it's own. This is especially true for calibration and such settings, but often also for cases where multiple analogue components work together.


(Log in to post comments)

The code is the documentation often

Posted Oct 10, 2006 10:01 UTC (Tue) by nix (subscriber, #2304) [Link]

A previous life? What do Red Hat *do* to people who leave their employ? ;)

(come to that, I know several people who've gone around the rotisserie from RH to somewhere else and then back to RH... should we call it the Wheel of Karma?)

(sorry, I'm feeling rather silly today. Coffee overdose, perhaps.)

The code is the documentation often

Posted Oct 10, 2006 10:06 UTC (Tue) by nix (subscriber, #2304) [Link]

(Speaking a little more seriously than in my last post)

Another reason why code is often preferable to docs is that the code is, as it were, self-validating. The docs often, how shall we say, *drift* with respect to differing versions of the hardware, but there's no way you can tell if that's happened. If the code drifts with respect to the hardware, it's immediately obvious, because the driver doesn't work any more.

Also, check FCC registration info

Posted Oct 10, 2006 17:10 UTC (Tue) by AJWM (guest, #15888) [Link]

>In addition, with a consumer product shelf life of 3 to 6 months, companies that make such consumer electronics usually don't want to waste the time (and time to market) to create detailed and good enough documentation.

But, if the thing emits any kind of RF at all (as almost any digital device does), they do have to register it with the FCC. Which can include some pretty detailed filings.

> Now it's not all bleak: there is documentation! Just not in the traditional PDF form.

FCC registration info is, if available at all (it may be sealed), is available in PDF, but non-traditional. This will include anything from cover letters to photographs of the device, to test reports, to block diagrams to user manuals.

If you have the device's FCC registration ID (maybe on a label on the case, or on a sticker inside, or may not be present) you can just enter it into the FCC search page (http://www.fcc.gov/oet/fccid/). They also have a new page that lets you search on all kinds of different fields (https://gullfoss2.fcc.gov/prod/oet/cf/eas/reports/Generic...).

No guarantee that you'll find any info about your particular device (I don't know what the rules are about registering, or how long it takes the information to become available or stay available on FCC's site), let alone programmer-friendly information, but it can be worth a look.

Also, check FCC registration info

Posted Oct 10, 2006 19:37 UTC (Tue) by tetromino (subscriber, #33846) [Link]

I don't see why the FCC docs would help. I mean, how does knowing how many watts of RF the device emits help a programmer who is trying to figure out what random bit of hex needs to written to which register to make the device emit those watts?

Also, check FCC registration info

Posted Oct 10, 2006 23:07 UTC (Tue) by AJWM (guest, #15888) [Link]

As I said, the FCC info may not help. But sometimes it does -- it might help you discover that device Foo contains an Xyz1234 chip, for which specs or a driver is available. (I got an old cheap digital camera whose USB ID was unrecognized to work this way.) Sometimes the info is more useful to hardware hackers than driver writers.

It doesn't cost anything but a little time to look.

The code is the documentation often

Posted Oct 12, 2006 1:33 UTC (Thu) by bignose (subscriber, #40) [Link]

> For many pieces of hardware, no such driver-writer level documentation
> exists! At all. Often the driver (often only the Windows one) gets
> developed together with the hardware, and the driver ends up BEING the
> documentation.

This doesn't change the request. If the hardware vendor wants their hardware to work with free operating systems, they should be providing documentation in whatever best form they have. If their best documentation is the source code for a driver, then that is what they can release.

If they *choose* to restrict this best form of documentation under a non-free license (either by choosing that license, or accepting it from another party), then they choose to lock themselves out of free operating systems.

It is *not* within the power of a free software developer to create that documentation under a free license. It *is* within the hardware vendor's power to provide the documentation as requested; if they choose not to participate, that is their decision, and they must wear the consequences.

The code is the documentation often

Posted Oct 12, 2006 6:59 UTC (Thu) by arjan (subscriber, #36785) [Link]

and guess what... Intel (one of the attacked parties here) does provide drivers for just about anything under open source Licenses....

also you "and they must wear the consequences" sentence starts to smell like we open source people have real power other than "your device is not supported"; guess what, we don't. It's not a small power, given the market size of open source today (esp Linux) in the server world, but in the desktop world... that power is near zero unfortunately.

The code is the documentation often

Posted Oct 17, 2006 4:51 UTC (Tue) by bignose (subscriber, #40) [Link]

> also you "and they must wear the consequences" sentence starts to smell
> like we open source people have real power other than "your device is
> not supported"; guess what, we don't.

That seems like power enough. Linux is the kernel with the most hardware support, ever, out of the box. Customers with lots of money are realising this.

If the hardware vendors want in on that, consistently and with a minimum of maintenance costs, they need to play by the rules. The rules say that proprietary drivers in the kernel are illegal, unworkable, and unethical.

http://www.kroah.com/log/linux/ols_2006_keynote.html


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