[foreign-jextract] RFR: Refresh panama documents to reflect API changes

[Athijegannathan Sundararajan]

On Thu, 23 Sep 2021 13:59:44 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This change updates the memory access/linker markdown documents, to reflect the latest API changes described in [1].
> 
> [1] - https://inside.java/2021/09/16/finalizing-the-foreign-apis/

doc/panama_ffi.md line 29:

> 27: try (ResourceScope scope = ResourceScope.newConfinedScope()) {
> 28: 	MemorySegment segment = MemorySegment.ofAddressNative(100, scope);
> 29: 	int x = MemoryAccess.getInt(segment);

Using MemoryAccess

doc/panama_ffi.md line 33:

> 31: ```
> 32: 
> 33: Both `MemoryAddress` and `MemorySegment`, implements the `Addressable` interface, which is an interface modelling entities that can be passed *by reference* — that is, which can be projected to a `MemoryAddress` instance. In the case of `MemoryAddress` such a projection is the identity function; in the case of a memory segment, the projection returns the `MemoryAddres` instance for the segment's base address. This abstraction allows to pass either memory address or memory segments where an address is expected (this is especially useful when generating native bindings).

"Both `MemoryAddress` and `MemorySegment`, implement the..."

doc/panama_ffi.md line 88:

> 86: ### Symbol lookups
> 87: 
> 88: The first ingredient of any foreign function support is a mechanism to lookup symbols in native libraries. In traditional Java/JNI, this is done via the `System::loadLibrary` and `System::load` methods, which internally map into calls to `dlopen`. Unfortunately, these methods do not provide a way for clients to obtain the address associated with a given library symbol. For this reason, the Foreign Linker API introduces a new abstraction, namely `SymbolLookup` (similar in spirit to a method handle lookup), which provides capabilities to lookup named symbols; we can obtain a symbol lookup in 2 different ways <a href="#1"><sup>1</sup></a>:

'dlopen' or 'LoadLlibrary' ?

doc/panama_ffi.md line 133:

> 131: | `struct Point { int x; int y; };`<br />`union Choice { float a; int b; };`<br />... | `GroupLayout`  | `MemorySegment`                    |
> 132: 
> 133: Note that all C pointer types are modelled using the `ADDRESS` layout constant; the Java carrier type associated with this layout is either `Addressable` or `MemoryAddress` depending on whether the layout appears in a parameter position (resp. return position) in the function descriptor associated with a downcall method handle (resp. upcall stub). This maximizes applicability of e.g. downcall method handles, ensuring that any implementation of `Addressable` (e.g. memory segments, memory address, upcall stubs, va lists) can be passed where a pointer is expected.

Can the first sentence be reworded a bit?" depending on ..." part.

doc/panama_ffi.md line 284:

> 282: ```java
> 283: printf.invoke(CLinker.toCString("%d plus %d equals %d").address(), 2, 2, 4); //prints "2 plus 2 equals 4"
> 284: ```

Older CLinker.toCString used

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

PR: https://git.openjdk.java.net/panama-foreign/pull/578