Posted Jul 5, 2010 17:35 UTC (Mon) by avik
In reply to: s/driver/documentation/
Parent article: A line in the sand for graphics drivers
Once you're at the point of something as complex as a graphics driver, interface documentation is unlikely to be both precise and accurate.
Then the driver+documentation is unlikely to be accepted. We need to insist on quality docs, just as we insist on quality code.
Say we end up with an open kernel driver, a closed userspace implementation and an open userspace implementation. Part of the interface documentation can be interpreted in two different ways, and interpreting it one way gives a significant performance boost to the open component and breaks the closed component. Do we accept the patch or refuse the patch?
We request a clarification to the specification.
What if one interpretation allows DMAing to arbitrary addresses?
Then it's clearly a bug. Both driver and documentation need to be fixed.
None of the above change when you get an open source driver instead of documentation. In fact, a driver is less likely to be complete (since it won't implement all capabilities), though more likely to be accurate (since it can be tested). Documentation contains a superset of the information in a driver, since you can write a driver based on the documentation, but you can't write the entire documentation from reading the driver source.
And this ignores the fact that any interface documentation for a graphics driver's kernel component is likely to be of the form "This ioctl submits a buffer of GPU commands to the device".
Such documentation should be rejected. Documentation should describe exactly what happens with the bits, either directly or by referring to hardware documentation.
These commands will typically not be interpreted by the kernel code beyond certain sanity checking, so documenting the interface does little to tell us how to implement a userspace version of the same code. Interface documentation is better than no interface documentation, and hardware documentation is better still.
what you describe is not an interface documentation, but a tunnel documentation. That should be rejected.
But if we have a kernel component with a well-defined ABI then that impairs our ability to implement a userspace driver unless we also develop a parallel kernel component. And that way lies madness.
Certainly, I got confused just reading that last paragraph.
to post comments)