Documentation/core-api/packing.rst

6 -----------------
10 One can memory-map a pointer to a carefully crafted struct over the hardware
15 definitions from the hardware documentation into bit field indices for the
18 (sometimes even 64 bit ones). This creates the inconvenience of having to
23 were performed byte-by-byte. Also the code can easily get cluttered, and the
24 high-level idea might get lost among the many bit shifts required.
25 Many drivers take the bit-shifting approach and then attempt to reduce the
30 ------------
34   - Packing a CPU-usable number into a memory buffer (with hardware
36   - Unpacking a memory buffer (which has hardware constraints/quirks)
37     into a CPU-usable number.
44 perspective, bit 63 always means bit offset 7 of byte 7, albeit only
45 logically. The question is: where do we lay this bit out in memory?
57   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
60 That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the
63 bit i corresponds to the number 2^i. This is also referred to in the code
73   24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23  8  9 10 11 12 13 14 15  0  1  2  3  4  5  6  7
77 inverts bit offsets inside a byte.
86   7  6  5  4  3  2  1  0  15 14 13 12 11 10  9  8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
90 byte from each 4-byte word is placed at its mirrored position compared to
100   0  1  2  3  4  5  6  7  8   9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
108   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
114 4 bytes correspond to the least significant 4-byte word, next 4 bytes to
115 the more significant 4-byte word.
123   24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23  8  9 10 11 12 13 14 15  0  1  2  3  4  5  6  7
134   7  6  5  4  3  2  1  0  15 14 13 12 11 10  9  8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
145   0  1  2  3  4  5  6  7  8   9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
155 ------------
160 xxx_packing() that calls it using the proper QUIRK_* one-hot bits set.
162 The packing() function returns an int-encoded error code, which protects the