Summary
-------
Update the MemoryLayout API so that sizes are expressed in bytes, not bits.
Problem
-------
Memory
segments are expressed as "bag of bytes". All their sizes and offsets
are expressed in number of bytes, which obviously makes sense given that
(a) memory addressing is byte-oriented and (b) ByteBuffer API also works
that way (which means it's relatively easy to update code using ByteBuffer to use MemorySegment instead).
On the other hand, memory layouts are expressed in bits. The historical
reasons for this can be found in John's great [LDL document](https://cr.openjdk.org/~jrose/panama/minimal-ldl.html).
Essentially, the layout language proposed in the LDL document was
originally intended to model both memory **and** registers.
While this asymmetry can rarely be observed in practice, it is
bothersome for a number of reasons:
* Factories accepting layouts (e.g.
SegmentAllocator::allocate(MemoryLayout)) cannot be expressed as simple
sugar for factories expressed in byte size/alignment (e.g.
SegmentAllocator::allocate(long, long)). That is, there is always some
segments that can be allocated in one factory which can't be allocated
in the other.
* Var handles generated using the memory layout API have different
constraints from those generated directly from MethodHandles. The latter
just accepts a byte offset (in sync with what memory segments do), while
the former perform all internal computation, as well as range checking,
in bits - which again leads to asymmetries.
More details on this problem can be found [here](https://mail.openjdk.org/pipermail/panama-dev/2023-May/019059.html).
Solution
--------
While in principle we could tweak memory segments to express their sizes and offsets in bits, such a solution would hurt adoption of the MemorySegment API (as noted above). The only realistic solution is to change the memory layout API to express sizes in bytes rather than in bits. This comes with few consequences:
* Some duplicate methods in the layout API are removed. For instance, instead of having both `MemoryLayout::bitSize` and `MemoryLayout::byteSize`, only the latter should be retained;
* The `MemoryLayout::withBitAlignment` method should be renamed to `MemoryLayout::withByteAlignment` and its semantics expressed in bytes;
* The padding layout factory (`MemorySegment::paddingLayout(long)`) should now take a byte size.
Specification
-------------
A summary of the required changes is attached to this CSR (see 8308276_v1.zip). Links are also included below:
javadoc: https://cr.openjdk.org/~mcimadamore/jdk/8308276/8308276/v1/javadoc/java.base/java/lang/foreign/package-summary.html
specdiff: https://cr.openjdk.org/~mcimadamore/jdk/8308276/8308276/v1/specdiff_out/overview-summary.html