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?
55   63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
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
71   56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
77 inverts bit offsets inside a byte.
84   39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
90 byte from each 4-byte word is placed at its mirrored position compared to
98   32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
110   63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
114 4 bytes correspond to the least significant 4-byte word, next 4 bytes to
115 the more significant 4-byte word.
125   56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
136   39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
147   32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
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