Drivers as documentation

In some cases, the "reserved" bits exist to disable or modify some feature, say as part of a test mode. They get marked "reserved", because a future product in the same family might want to use that bit for some other functionality. Or, the behavior of the test modes themselves might change between different revisions of the device.

So it doesn't surprise me at all that there might not be reasonable customer-level documentation for some of these "reserved" bits. At the same time, I can also see that workarounds for flaky designs ("Oops, the frobnitz accelerator sometimes frotzes when it should gronk, if two quux DMAs come in consecutive cycles") might rely on these "reserved" bits. The bit in the article above might be documented internally as "disable frobnitz acceleration (internal test purposes only; do not use for normal operation)".

Other times, it's due to the same peripheral getting used in different configurations on different chips, and the field in question should be "irrelevant" for this particular chip. So the bit exists and the feature it controls exists, but the feature isn't necessarily useful on this chip, or wasn't spec'd to be on this chip, and so it might not be tested. The fact that enabling it anyway stops DMAs from randomly crashing might be a happy accident.

In my day job, I'm at the head of one of these pipelines, writing specs that lead to the hardware and later to the customer documentation. I also had some good chuckles reading through this article. From what I've seen, the process of turning my specs into end customer documentation involves a lot of deleting (missing some of the internal implementation details, but invariably deleting some important detail customers need), and inserting several *ahem* interesting grammatical twists and confusing diagrams. I don't envy the folks that have to make the end-customer documentation from my specs, but sausage making is sausage making, no matter who makes it.