In a survey I conducted of several firmware engineers, lack of good documentation of hardware was the number one complaint. It is because firmware engineers so heavily rely on the hardware documentation to correctly do their job. Some of the engineers said that wrong documentation is worse than no documentation because of the wasted time producing incorrect code.
It is a problem because one group (hardware engineers in this case) has to produce documentation for a different group (firmware engineers). They generally are in different physical locations, come from different engineering backgrounds, have different terminology, and have different perspectives on the end products. To overcome these differences, hardware and firmware engineers need to collaborate with each other.
Writing documentation is difficult. When I write, I understand perfectly well what I meant to say. I know and understand unwritten details and nuances that are second nature to me without realizing that my reader might not. I’m reminded of that when I have someone else review my writing and they bring up missing and incomplete sections.
While both hardware and firmware engineers should be actively involved in the collaboration, it is primarily the hardware engineers who do the majority of the work with documentation and design. When ready for review, they should give the documentation to firmware engineers for review. Firmware engineers should, in a timely fashion, review the documentation and provide hardware engineers with comments on incomplete, unclear, and incorrect sections and any issues that they might discover. Firmware review of hardware documentation should be part of the checklist for milestone completions.
- Best Practice: Give hardware documentation to firmware engineers to review and respond with comments and issues.
Before firmware engineers can understand the specifics of how the block works, they need to have an overall picture of the purpose and operations of the block. If they focus too much on details, specific registers, and bits, it is hard to see what the overall operation should be. Not having a high-level description can be compared to seeing a box full of nuts, bolts, springs, levers, and other parts and not being able to recognize that it is supposed to be a toaster. But by first stepping back and looking at a high-level description of the toaster as a whole and understanding how it toasts bread, then it is easier to understand how to assemble the components to make a functional toaster.
The same concept applies to a block on the chip. Firmware engineers need to see and understand the big picture of how that block should operate, within itself and in conjunction with other parts of the system, before they can understand the detailed registers and bits.
- Best Practice: Produce and have reviewed a high-level description of the block that describes its theory of operation, its function in the system, and its parts.
In addition to the high-level documentation, a detailed documentation is needed and should contain both a reference section and a tutorial section. A reference section has a list of all registers in the block, typically in address order. It gives details for each register and the bits and/or bit fields in that register. The tutorial section describes when, how, and in what order to use those registers and bits to carry out a task.
An example of reference documentations is the UNIX man pages (and Linux and other variants) which contains all commands and functions in alphabetical order, each one describing their respective options in order. On the other hand, the well-known book by Kernighan and Ritchie, “The C Programming Language,” is written in tutorial style, explaining how to do various tasks, using necessary C constructs to accomplish the tasks.
- Best Practice: Provide both a reference section and a tutorial section in the detailed documentation of a block.
Until the next writing…