Documentation: clarify that struct.pack_into() does not guarantee exact memory-access semantics

[bit-otter-jp]

Documentation

This is a documentation clarification request, not a request to change
struct.pack_into() behavior.

The current documentation for struct.pack_into() says that it writes the
packed bytes into a writable buffer:

https://docs.python.org/3/library/struct.html#struct.pack_into

For ordinary memory this is straightforward, but it may be misleading when
the writable buffer is backed by memory-mapped I/O (MMIO), where the number,
width, and ordering of actual memory accesses can be semantically significant.

For example:

struct.pack_into("<I", mmio_buffer, offset, value)

may look like a natural way to perform one 32-bit MMIO write.

However, the Python-level operation should not be assumed to correspond to
one native store or one device transaction.

In one tested CPython environment, a single struct.pack_into("<I", ...)
operation was observed to produce three native stores, with values equivalent
to:

0
0
value

The PCIe device observed three corresponding Memory Write requests.

This is intentionally not a claim that struct.pack_into() always performs
three stores. The observed access shape is implementation-, compiler-,
runtime-, platform-, and mapping-dependent. It should not be treated as a
Python or CPython API guarantee.

I think a short documentation note would make this abstraction boundary clear.
For example:

pack_into() specifies the packed bytes written to the buffer, but does not
guarantee the number, width, or ordering of the underlying native memory
accesses used to perform the write. In particular, writable buffers backed
by memory-mapped I/O (MMIO) should not be treated as exact-width register
access interfaces. Code that depends on exact MMIO access semantics should
use an interface designed for that purpose and verify its behavior for the
target implementation and platform.

I am not suggesting that MMIO should become a supported special case of
struct, nor that the current implementation is incorrect. The requested
change is only to document that a writable-buffer operation does not imply an
exact-MMIO-access contract.

Tested environment:

• CPython 3.10.12 (/usr/bin/python3)
• Ubuntu 22.04.5 LTS
• Linux 6.8
• x86-64, Intel Xeon E5-1620 v3
• glibc 2.35
• GCC 11.4

The investigation separated the Python-level operation, native load/store
instructions, PCIe requests, and FPGA-side observations.

Supporting evidence and reproduction records are public here:

https://github.com/bit-otter-jp/AS02MC04-XCKU3P

Relevant directories:

• 02_as02mc04_pcie/WORK6/PART1_ANNEX3

  • investigation of Python MMIO access behavior
  • native instruction / PCIe request observations

• 02_as02mc04_pcie/WORK6/PART1_ANNEX4

  • native CPython C-extension reference implementation
  • explicit read32() / write32() primitives
  • final-binary and hardware qualification