Much of firmware development focuses on interfacing with registers. Documentation plays a key role in this effort since engineers must refer to it constantly to look up register and bit details. In particular, engineers need to generate or decode hex numbers, where the value of each bit must be clearly understood. Documentation styles and formats should help, not hinder that process.
The following example of a 32-bit register will illustrate some key points about proper documentation.
| MSB | Status Register | LSB | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Pos | 31 | 30 | 29 | 28 | 27 | 26 | 25 | 24 | 23 | 22 | 21 | 20 | 19 | 18 | 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
| Bit | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | R | Q | P | O | N | M | S | D | C | C | C | – | – | F | A |
| A | Active: If this bit is set, the block is active, processing data. |
| F | Forward: If this bit is set, the data is being processed forward. If clear, it is being processed backwards. |
| C | Compression: Specifies the compression type. 0=no compression, 1=run-length, 2=LZW, 3=Huffman, 4=PPM. 5-7 are illegal values. |
| D | Data Error: The incoming data is corrupted. |
| S | Size Error: The amount of data received did not match expected. |
| … | |
| R | Restart: Request a restart of the operation. |
First, note that the horizontal orientation of the register diagram makes it easier to decode the hex value read from the register. The 32 bits are grouped by fours to facilitate alignment with hex digits. Decoding 0x000040A1 indicates that the Active bit is set, Compression is set to 2, the Data Error bit is set, and the Restart bit is set. Similarly, the horizontal format of the table also makes it easier to determine a hex value. It is easy to see that the hex code for the Forward bit is 0x00000002. To set the Forward bit in the register, we can OR the existing contents with 0x00000002 to get 0x000040A3, the value to write to the register to set the Forward bit in this case.
- Best Practice: In the block’s documentation, display the register diagram in a horizontal format.
To make sure the hex codes determined from the horizontal table are correct for the processor, put the LSB (Least Significant Bit) on the right. If the above diagram were formatted in the other direction (that is, MSB on the right), decoding register values would require more mental gymnastics: we’d have to read the table backwards to get the right hex codes.
- Best Practice: In the horizontal register diagram, put the LSB on the right side.
Since English and many other languages scan from left to right, it seems natural to assign bits from the left side of a register, starting with the MSB (Most Significant Bit). However, MSB-based bit assignment tends to make associated register bit values less readable. For instance, the bitmask for the Active bit in our sample register (with LSB-based assignment) has a hex value of 0x1, a very readable value that can be expressed without leading 0s. However, the corresponding bitmask for an Active bit assigned MSB-first would be 0x80000000, which is harder to read and thus can lead to coding errors. In addition, many firmware functions scan for bits in an integer (e.g., to determine which interrupt occurred) starting with LSB and then scan up. Assigning bits starting at LSB allows firmware to be a little more efficient with such scans.
- Best Practice: Assign bits to the register starting on the right side at LSB keeping unused bits on the left side.
A 32-column table results in very narrow columns, which does not allow much room for the description of the bit. This forces the detailed description of the bits to follow the horizontal table. This is actually good because it allows as much room as needed for the description of each bit. Since bits are assigned in order from LSB, the order of the bit descriptions should start with LSB and move down to MSB. Often, more important bits are assigned closer to LSB so their descriptions should be near the top of the list. New bits should be added to the left of the last assigned bit in the horizontal table, and their respective descriptions added at the bottom of the list.
- Best Practice: Sort the descriptions of the bits starting with the LSB first down to the MSB last.
These guidelines for documenting registers are based on my experience of reading many flavors of hardware documentation. The best practices may seem nit-picky and trivial, but attention to those details pays in terms of clarity and ease of use during development. Some of you may be accustomed to documentation styles that differ from my recommendations. If so, I invite you to tell me about your recommendations and why they work better for you.
Until the next bit of documentation…