More on Documenting Registers
Documenting Registers
February 28, 2008Sniffing I2C
May 31, 2008More on Documenting Registers
Last month’s newsletter discussed some best practices for documenting register layouts, illustrating key points with a sample register diagram. One reader, Joel Saks, noted that my register diagram did not clearly indicate whether the bits were read/write bits or read-only bits. Joel makes an excellent point and also exposes one of the pitfalls of the newsletter format: limited space. I try to keep these newsletters brief, so some subjects have to span multiple newsletters. This month, I will continue with the discussion of register documentation where we left off last month.
Let’s waste no time and immediately address Joel’s concern: The following modification to the register table from last month now indicates the access type, read/write or read-only, of the bits in the register.
| MSB | Status Register | LSB | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Bit | 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 |
| RW | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | C | C | C | – | – | F | A |
| RO | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | R | Q | P | O | N | M | S | D | – | – | – | – | – | – | – |
The row with the bits has been split into two rows, one for read/write bits and one for read-only bits, as indicated in the first column. For registers that have only read/write bits or read-only bits, but not both, only one row is needed with the first column indicating the type of bits.
In the next example, the register deals with a byte count. Firmware can only write a byte count value that is a multiple of 64. But firmware can read a count of any value as the counter counts down the bytes one at a time. This is illustrated through the use of read-only and write-only bits occupying the same bit position.
| MSB | Byte Count Register | LSB | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Bit | 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 |
| RO | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | B | B | B | B | B | B | B | B | B | B | B | B | B | B | B | B |
| WO | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | C | C | C | C | C | C | C | C | C | C | – | – | – | – | – | – |
- Best Practice: Indicate in the register diagram if bits are read-only, write-only, or read/write.
Firmware engineers also need to know the power-on default for each of these bits. We can add another row to the diagram to convey that information.
| MSB | Status Register | LSB | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Bit | 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 |
| RW | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | C | C | C | – | – | F | A |
| RO | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | – | R | Q | P | O | N | M | S | D | – | – | – | – | – | – | – |
| Def | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | X | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 |
Most of the bits (including the undefined bits) default to 0 when power is applied. One bit, F, defaults to 1. The default of “X” for the M bit indicates that the initial setting is unknown. An example of an unknown setting is when the bit reflects the current level of an input pin, which depends on how it is driven externally.
- Best Practice: Document the power-on defaults for each bit in the register diagram.
Until the next read-only newsletter…