| From 59899f9abe57874c4d68d3c014eb7cabd26a24e1 Mon Sep 17 00:00:00 2001 |
| From: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> |
| Date: Fri, 26 Jul 2019 09:51:20 -0300 |
| Subject: [PATCH] docs: packing: move it to core-api book and adjust markups |
| |
| commit 1ec779b9fabcdbfaa06971b5c2a4d9a6e4b45b3a upstream. |
| |
| 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: 554aae35007e ("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> |
| Signed-off-by: Paul Gortmaker <paul.gortmaker@windriver.com> |
| |
| diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst |
| index ee1bb8983a88..60d2f3522db6 100644 |
| --- a/Documentation/core-api/index.rst |
| +++ b/Documentation/core-api/index.rst |
| @@ -25,6 +25,7 @@ Core utilities |
| librs |
| genalloc |
| errseq |
| + packing |
| printk-formats |
| circular-buffers |
| generic-radix-tree |
| diff --git a/Documentation/packing.txt b/Documentation/core-api/packing.rst |
| similarity index 61% |
| rename from Documentation/packing.txt |
| rename to Documentation/core-api/packing.rst |
| index f830c98645f1..d8c341fe383e 100644 |
| --- a/Documentation/packing.txt |
| +++ b/Documentation/core-api/packing.rst |
| @@ -30,6 +30,7 @@ The solution |
| ------------ |
| |
| This API deals with 2 basic operations: |
| + |
| - Packing a CPU-usable number into a memory buffer (with 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: |
| |
| -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 |
| -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 |
| + 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 |
| 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: |
| |
| -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 |
| -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 |
| + 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 |
| 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: |
| |
| -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 |
| -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 |
| + 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 |
| 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 |
| 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 |
| -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 |
| + 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: |
| |
| -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 |
| -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 |
| + 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 |
| 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 |
| 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 |
| -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 |
| + 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 |
| 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 |
| -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 |
| + 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 |
| 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 |
| -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 |
| + 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 |
| diff --git a/MAINTAINERS b/MAINTAINERS |
| index d75037e77a5a..080ae6b10b1f 100644 |
| --- a/MAINTAINERS |
| +++ b/MAINTAINERS |
| @@ -11871,7 +11871,7 @@ L: netdev@vger.kernel.org |
| S: Supported |
| F: lib/packing.c |
| F: include/linux/packing.h |
| -F: Documentation/packing.txt |
| +F: Documentation/core-api/packing.rst |
| |
| PADATA PARALLEL EXECUTION MECHANISM |
| M: Steffen Klassert <steffen.klassert@secunet.com> |
| -- |
| 2.27.0 |
| |
