[foreign-memaccess+abi] RFR: Refresh FFM documents [v2]

[ExE Boss]

On Wed, 20 Dec 2023 10:04:22 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> This PR brings the FFM documents in sync with the finalized API in JDK 22. The most obvious changes are:
>> 
>> * in the foreign memory document, the section on structured access has been rectified, to take into account the extra offset parameter that is added to memory access var handles;
>> * in both documents, several calls to `allocateArray` and `allocateUtf8String` have been replaced with `allocateFrom`
>> * the section introducing the `Linker` in the ffi document has been revamped; it now talks more at length about the mapping between layouts and C types. The table with Linux/x64 mappings has been moved to a section in the appendix, and I have also added a mention of `Linker::canonicalLayouts`
>
> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Address review comments

doc/panama_ffi.md line 114:

> 112: * lookup the `strlen` symbol
> 113: * describe the signature of the C function using a function descriptor
> 114: 

Suggestion:

doc/panama_ffi.md line 254:

> 252: ```
> 253: 
> 254: While this works, and provides optimal performance, it has some limitations<a href="#2"><sup>3</sup></a>:

Suggestion:

While this works, and provides optimal performance, it has some limitations<a href="#3"><sup>3</sup></a>:

doc/panama_ffi.md line 377:

> 375: * <a id="1"/>(<sup>1</sup>):<small> In reality this is not entirely new; even in JNI, when you call a `native` method the VM trusts that the corresponding implementing function in C will feature compatible parameter types and return values; if not a crash might occur.</small>
> 376: * <a id="2"/>(<sup>2</sup>):<small> Linker options can be used to customize the linkage request in various ways, for instance to allow clients to pass heap segments to native functions without copying, to remove Java to native thread transitions and to save the state of special runtime variables (such as `errno`). </small>
> 377: * <a id="3"/>(<sup>2</sup>):<small> Previous iterations of the FFM API provided a `VaList` class that could be used to model a C `va_list`. This class was later dropped from the FFM API as too implementation specific. It is possible that a future version of the `jextract` tool might provide higher-level bindings for variadic calls. </small>

Suggestion:

* <a id="3"/>(<sup>3</sup>):<small> Previous iterations of the FFM API provided a `VaList` class that could be used to model a C `va_list`. This class was later dropped from the FFM API as too implementation specific. It is possible that a future version of the `jextract` tool might provide higher-level bindings for variadic calls. </small>

-------------

PR Review Comment: https://git.openjdk.org/panama-foreign/pull/914#discussion_r1437300552
PR Review Comment: https://git.openjdk.org/panama-foreign/pull/914#discussion_r1437300275
PR Review Comment: https://git.openjdk.org/panama-foreign/pull/914#discussion_r1437300185