docs: packing: move it to core-api book and adjust markups
The packing.txt file was misplaced, as docs should be part of
a documentation book, and not at the root dir.
So, move it to the core-api directory and add to its index.
Also, ensure that the file will be properly parsed and the bitmap
ascii artwork will use a monotonic font.
Fixes: 554aae3500
("lib: Add support for generic packing operations")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Reviewed-by: Vladimir Oltean <olteanv@gmail.com>
Tested-by: Vladimir Oltean <olteanv@gmail.com>
Reviewed-by: Mike Rapoport <rppt@linux.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
parent
f6ae22d644
commit
1ec779b9fa
|
@ -25,6 +25,7 @@ Core utilities
|
||||||
librs
|
librs
|
||||||
genalloc
|
genalloc
|
||||||
errseq
|
errseq
|
||||||
|
packing
|
||||||
printk-formats
|
printk-formats
|
||||||
circular-buffers
|
circular-buffers
|
||||||
generic-radix-tree
|
generic-radix-tree
|
||||||
|
|
|
@ -30,6 +30,7 @@ The solution
|
||||||
------------
|
------------
|
||||||
|
|
||||||
This API deals with 2 basic operations:
|
This API deals with 2 basic operations:
|
||||||
|
|
||||||
- Packing a CPU-usable number into a memory buffer (with hardware
|
- Packing a CPU-usable number into a memory buffer (with hardware
|
||||||
constraints/quirks)
|
constraints/quirks)
|
||||||
- Unpacking a memory buffer (which has hardware constraints/quirks)
|
- Unpacking a memory buffer (which has hardware constraints/quirks)
|
||||||
|
@ -49,10 +50,12 @@ What the examples show is where the logical bytes and bits sit.
|
||||||
|
|
||||||
1. Normally (no quirks), we would do it like this:
|
1. Normally (no quirks), we would do it like this:
|
||||||
|
|
||||||
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
|
::
|
||||||
7 6 5 4
|
|
||||||
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
|
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
|
||||||
3 2 1 0
|
7 6 5 4
|
||||||
|
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
|
||||||
|
3 2 1 0
|
||||||
|
|
||||||
That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the
|
That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the
|
||||||
LSByte (0) of the u64 sits at memory offset 7.
|
LSByte (0) of the u64 sits at memory offset 7.
|
||||||
|
@ -63,10 +66,12 @@ comments as "logical" notation.
|
||||||
|
|
||||||
2. If QUIRK_MSB_ON_THE_RIGHT is set, we do it like this:
|
2. If QUIRK_MSB_ON_THE_RIGHT is set, we do it like this:
|
||||||
|
|
||||||
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
|
::
|
||||||
7 6 5 4
|
|
||||||
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
|
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
|
||||||
3 2 1 0
|
7 6 5 4
|
||||||
|
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
|
||||||
|
3 2 1 0
|
||||||
|
|
||||||
That is, QUIRK_MSB_ON_THE_RIGHT does not affect byte positioning, but
|
That is, QUIRK_MSB_ON_THE_RIGHT does not affect byte positioning, but
|
||||||
inverts bit offsets inside a byte.
|
inverts bit offsets inside a byte.
|
||||||
|
@ -74,10 +79,12 @@ inverts bit offsets inside a byte.
|
||||||
|
|
||||||
3. If QUIRK_LITTLE_ENDIAN is set, we do it like this:
|
3. If QUIRK_LITTLE_ENDIAN is set, we do it like this:
|
||||||
|
|
||||||
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
|
::
|
||||||
4 5 6 7
|
|
||||||
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
|
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
|
||||||
0 1 2 3
|
4 5 6 7
|
||||||
|
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
|
||||||
|
0 1 2 3
|
||||||
|
|
||||||
Therefore, QUIRK_LITTLE_ENDIAN means that inside the memory region, every
|
Therefore, QUIRK_LITTLE_ENDIAN means that inside the memory region, every
|
||||||
byte from each 4-byte word is placed at its mirrored position compared to
|
byte from each 4-byte word is placed at its mirrored position compared to
|
||||||
|
@ -86,18 +93,22 @@ the boundary of that word.
|
||||||
4. If QUIRK_MSB_ON_THE_RIGHT and QUIRK_LITTLE_ENDIAN are both set, we do it
|
4. If QUIRK_MSB_ON_THE_RIGHT and QUIRK_LITTLE_ENDIAN are both set, we do it
|
||||||
like this:
|
like this:
|
||||||
|
|
||||||
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
|
::
|
||||||
4 5 6 7
|
|
||||||
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
|
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
|
||||||
0 1 2 3
|
4 5 6 7
|
||||||
|
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
|
||||||
|
0 1 2 3
|
||||||
|
|
||||||
|
|
||||||
5. If just QUIRK_LSW32_IS_FIRST is set, we do it like this:
|
5. If just QUIRK_LSW32_IS_FIRST is set, we do it like this:
|
||||||
|
|
||||||
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
|
::
|
||||||
3 2 1 0
|
|
||||||
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
|
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
|
||||||
7 6 5 4
|
3 2 1 0
|
||||||
|
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
|
||||||
|
7 6 5 4
|
||||||
|
|
||||||
In this case the 8 byte memory region is interpreted as follows: first
|
In this case the 8 byte memory region is interpreted as follows: first
|
||||||
4 bytes correspond to the least significant 4-byte word, next 4 bytes to
|
4 bytes correspond to the least significant 4-byte word, next 4 bytes to
|
||||||
|
@ -107,28 +118,34 @@ the more significant 4-byte word.
|
||||||
6. If QUIRK_LSW32_IS_FIRST and QUIRK_MSB_ON_THE_RIGHT are set, we do it like
|
6. If QUIRK_LSW32_IS_FIRST and QUIRK_MSB_ON_THE_RIGHT are set, we do it like
|
||||||
this:
|
this:
|
||||||
|
|
||||||
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
|
::
|
||||||
3 2 1 0
|
|
||||||
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
|
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
|
||||||
7 6 5 4
|
3 2 1 0
|
||||||
|
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
|
||||||
|
7 6 5 4
|
||||||
|
|
||||||
|
|
||||||
7. If QUIRK_LSW32_IS_FIRST and QUIRK_LITTLE_ENDIAN are set, it looks like
|
7. If QUIRK_LSW32_IS_FIRST and QUIRK_LITTLE_ENDIAN are set, it looks like
|
||||||
this:
|
this:
|
||||||
|
|
||||||
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
|
::
|
||||||
0 1 2 3
|
|
||||||
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
|
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
|
||||||
4 5 6 7
|
0 1 2 3
|
||||||
|
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
|
||||||
|
4 5 6 7
|
||||||
|
|
||||||
|
|
||||||
8. If QUIRK_LSW32_IS_FIRST, QUIRK_LITTLE_ENDIAN and QUIRK_MSB_ON_THE_RIGHT
|
8. If QUIRK_LSW32_IS_FIRST, QUIRK_LITTLE_ENDIAN and QUIRK_MSB_ON_THE_RIGHT
|
||||||
are set, it looks like this:
|
are set, it looks like this:
|
||||||
|
|
||||||
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
|
::
|
||||||
0 1 2 3
|
|
||||||
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
|
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
|
||||||
4 5 6 7
|
0 1 2 3
|
||||||
|
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
|
||||||
|
4 5 6 7
|
||||||
|
|
||||||
|
|
||||||
We always think of our offsets as if there were no quirk, and we translate
|
We always think of our offsets as if there were no quirk, and we translate
|
|
@ -12099,7 +12099,7 @@ L: netdev@vger.kernel.org
|
||||||
S: Supported
|
S: Supported
|
||||||
F: lib/packing.c
|
F: lib/packing.c
|
||||||
F: include/linux/packing.h
|
F: include/linux/packing.h
|
||||||
F: Documentation/packing.txt
|
F: Documentation/core-api/packing.rst
|
||||||
|
|
||||||
PADATA PARALLEL EXECUTION MECHANISM
|
PADATA PARALLEL EXECUTION MECHANISM
|
||||||
M: Steffen Klassert <steffen.klassert@secunet.com>
|
M: Steffen Klassert <steffen.klassert@secunet.com>
|
||||||
|
|
Loading…
Reference in New Issue