linux-stable/Documentation/core-api
Vladimir Oltean a636ba5e86 lib: packing: adjust definitions and implementation for arbitrary buffer lengths
Jacob Keller has a use case for packing() in the intel/ice networking
driver, but it cannot be used as-is.

Simply put, the API quirks for LSW32_IS_FIRST and LITTLE_ENDIAN are
naively implemented with the undocumented assumption that the buffer
length must be a multiple of 4. All calculations of group offsets and
offsets of bytes within groups assume that this is the case. But in the
ice case, this does not hold true. For example, packing into a buffer
of 22 bytes would yield wrong results, but pretending it was a 24 byte
buffer would work.

Rather than requiring such hacks, and leaving a big question mark when
it comes to discontinuities in the accessible bit fields of such buffer,
we should extend the packing API to support this use case.

It turns out that we can keep the design in terms of groups of 4 bytes,
but also make it work if the total length is not a multiple of 4.
Just like before, imagine the buffer as a big number, and its most
significant bytes (the ones that would make up to a multiple of 4) are
missing. Thus, with a big endian (no quirks) interpretation of the
buffer, those most significant bytes would be absent from the beginning
of the buffer, and with a LSW32_IS_FIRST interpretation, they would be
absent from the end of the buffer. The LITTLE_ENDIAN quirk, in the
packing() API world, only affects byte ordering within groups of 4.
Thus, it does not change which bytes are missing. Only the significance
of the remaining bytes within the (smaller) group.

No change intended for buffer sizes which are multiples of 4. Tested
with the sja1105 driver and with downstream unit tests.

Link: https://lore.kernel.org/netdev/a0338310-e66c-497c-bc1f-a597e50aa3ff@intel.com/
Signed-off-by: Vladimir Oltean <vladimir.oltean@nxp.com>
Tested-by: Jacob Keller <jacob.e.keller@intel.com>
Signed-off-by: Jacob Keller <jacob.e.keller@intel.com>
Reviewed-by: Przemek Kitszel <przemyslaw.kitszel@intel.com>
Reviewed-by: Vladimir Oltean <vladimir.oltean@nxp.com>
Link: https://patch.msgid.link/20241002-packing-kunit-tests-and-split-pack-unpack-v2-2-8373e551eae3@intel.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
2024-10-03 15:32:03 -07:00
..
irq Documentation: irqdomain: Fix typo of "at least once" 2022-08-18 11:11:52 -06:00
wrappers docs: put atomic*.txt and memory-barriers.txt into the core-api book 2022-09-29 12:55:06 -06:00
asm-annotations.rst docs: move x86 documentation into Documentation/arch/ 2023-03-30 12:58:51 -06:00
assoc_array.rst Documentation: Use "while" instead of "whilst" 2018-11-20 09:30:43 -07:00
boot-time-mm.rst docs/boot-time-mm: remove bootmem documentation 2018-10-31 08:54:16 -07:00
cachetlb.rst mm: remove ARCH_IMPLEMENTS_FLUSH_DCACHE_FOLIO 2023-08-24 16:20:19 -07:00
circular-buffers.rst doc: Remove ".vnet" from paulmck email addresses 2019-05-28 09:02:57 -07:00
cleanup.rst cleanup: Add usage and style documentation 2024-08-05 16:54:41 +02:00
cpu_hotplug.rst Document/kexec: generalize crash hotplug description 2024-09-01 20:43:37 -07:00
debug-objects.rst doc: debugobjects: actually pull in the kerneldoc comments 2016-11-29 14:44:14 -07:00
debugging-via-ohci1394.rst Documentation: Drop or replace remaining mentions of IA64 2023-09-11 08:13:18 +00:00
dma-api-howto.rst docs: dma: correct dma_set_mask() sample code 2024-04-02 10:07:15 -06:00
dma-api.rst docs: dma-api: Fix description of the sync_sg API 2023-11-17 08:52:13 -07:00
dma-attributes.rst Reinstate some of "swiotlb: rework "fix info leak with DMA_FROM_DEVICE"" 2022-03-28 11:37:05 -07:00
dma-isa-lpc.rst docs: core-api: avoid using ReST :doc:foo markup 2021-06-17 13:24:37 -06:00
entry.rst Docs: typos/spelling 2024-05-02 10:02:29 -06:00
errseq.rst errseq: Add to documentation tree 2018-01-01 12:40:27 -07:00
floating-point.rst arch: add ARCH_HAS_KERNEL_FPU_SUPPORT 2024-05-19 14:36:17 -07:00
folio_queue.rst netfs: Add folio_queue API documentation 2024-09-30 14:10:51 +02:00
genalloc.rst lib/genalloc.c: rename addr_in_gen_pool to gen_pool_has_addr 2019-12-04 19:44:13 -08:00
generic-radix-tree.rst generic radix trees 2019-03-12 10:04:02 -07:00
genericirq.rst Updates for the interrupt subsystem: 2024-07-22 13:52:05 -07:00
gfp_mask-from-fs-io.rst docs: core-api/gfp_mask-from-fs-io: add a label for cross-referencing 2018-09-20 11:02:32 -06:00
idr.rst IDR: Note that the IDR API is deprecated 2022-07-10 21:17:30 -04:00
index.rst Documentation: add missing folio_queue entry 2024-10-01 17:04:32 +02:00
kernel-api.rst Documentation: core-api: Drop :export: for int_log.h 2023-07-25 17:40:25 +01:00
kobject.rst kobject documentation: remove default_attrs information 2022-01-07 11:23:37 +01:00
kref.rst docs: move the kref doc into the core-api book 2020-05-15 12:02:19 -06:00
librs.rst docs-rst: convert librs book to ReST 2017-05-16 08:44:16 -03:00
local_ops.rst timers: Update the documentation to reflect on the new timer_shutdown() API 2022-11-24 15:09:12 +01:00
maple_tree.rst maple_tree: update the documentation of maple tree 2023-12-10 16:51:32 -08:00
memory-allocation.rst docs/core-api: memory-allocation: GFP_NOWAIT doesn't need __GFP_NOWARN 2024-07-29 15:10:25 -06:00
memory-hotplug.rst mm/memory_hotplug: remove HIGHMEM leftovers 2021-11-06 13:30:42 -07:00
mm-api.rst mm/slab, docs: switch mm-api docs generation from slab.c to slub.c 2023-12-05 11:11:34 +01:00
netlink.rst doc/netlink: Update genetlink-legacy documentation 2023-08-27 17:17:09 -07:00
packing.rst lib: packing: adjust definitions and implementation for arbitrary buffer lengths 2024-10-03 15:32:03 -07:00
padata.rst Documentation: core-api: padata: correct spelling 2023-02-16 16:58:01 -07:00
pin_user_pages.rst mm: remove page_mkclean() 2024-07-03 19:30:17 -07:00
printk-basics.rst printk: Move the printk() kerneldoc comment to its new home 2021-07-26 12:36:44 +02:00
printk-formats.rst printf: remove %pGt support 2024-09-03 21:15:42 -07:00
printk-index.rst docs:core-api: fixed typos and grammar in printk-index page 2024-05-07 08:01:11 -06:00
protection-keys.rst Documentation/protection-keys: Clean up documentation for User Space pkeys 2022-06-07 16:06:22 -07:00
rbtree.rst docs: rbtree.rst: Fix a typo 2021-03-25 11:38:51 -06:00
refcount-vs-atomic.rst docs: remove :c:func: from refcount-vs-atomic.rst 2019-10-07 09:08:56 -06:00
swiotlb.rst Documentation/core-api: correct reference to SWIOTLB_DYNAMIC 2024-05-27 16:52:09 +02:00
symbol-namespaces.rst doc: module: update file references 2022-07-01 14:50:01 -07:00
this_cpu_ops.rst arch: Remove cmpxchg_double 2023-06-05 09:36:39 +02:00
timekeeping.rst timekeeping: Introduce fast accessor to clock tai 2022-04-14 16:19:30 +02:00
tracepoint.rst doc: Sphinxify the tracepoint docbook 2016-11-29 14:44:23 -07:00
unaligned-memory-access.rst move asm/unaligned.h to linux/unaligned.h 2024-10-02 17:23:23 -04:00
union_find.rst Documentation: Fix the compilation errors in union_find.rst 2024-08-02 08:58:16 -10:00
watch_queue.rst Documentation: move watch_queue to core-api 2022-04-22 09:47:25 -06:00
workqueue.rst workqueue: doc: Fix function name, remove markers 2024-08-05 18:33:36 -10:00
xarray.rst XArray: Document the locking requirement for the xa_state 2022-02-03 15:56:50 -05:00