analysis of popular FFI frameworks and their layout descriptions

[Maurizio Cimadamore]

Hi Stephen

On 25/01/18 18:59, Stephen Kell wrote:

> I guess one trick in Panama is making sure there is a common core that
> doesn't bake in too much about headers, Clang, C/C++, etc.. Can you
> point me at the best reference to the Panama API? Am I right that it's
> mostly the annotation classes in java.nicl?

You are quite right - this is the challenge, and, admittedly, the 
implementation is a bit all over the map right now, but we’re working on 
a revised proposal which we’ll be sharing soon.

As things stand now, the API is comprised of a set of annotations in 
java.nicl.metadata - below is an attempt to define the minimum 
requirements for an annotated interface to fit the Panama runtime criteria:

header class:

  * @Header is not needed

native methods (FFI):

  * @C annotation needed (but values discarded)
  * @NativeType needed - all values discarded but layout() - which needs
    to have layout for all arguments/return type
  * @CallingConvention anno needed - value needs is irrelevant and can
    be left out (only System V supported for now anyway)

struct class:

  * @C annotation needed (but values discarded)
  * @NativeType needed - following values needed:
      o layout() - which needs to have layout for the struct
      o isRecord - which needs to be set to true
      o size() - the size (in bytes) of the struct

struct accessors (setters/getters)

  * @C annotation needed (but values discarded)
  * @NativeType needed - following values needed:
      o layout() - which needs to have layout for the accessed field
      o size() - the size (in bytes) of the field
  * @Offset needed, whose value must be the offset (in /bits/) of the
    field in the struct

As for the layout language used, the grammar is scattered through 
comments in the DescriptorParser class [1], here’s an attempt to capture 
it in one shot (but be aware that we have plans here too :-)):

|layout = 1*elementType / functionType descriptor = scalarType / 
arrayType / containerType / functionType functionType = '(' *elementType 
['*'] ')' elementType elementType = *separator (scalarType / arrayType / 
pointerType / containerType) *separator comment = "#" *octet 1*(CR / LF) 
whitespace = 1*(SP / HTAB / CR / LF) separator = whitespace / comment 
arrayType = arraySize elementType pointerType = p [':' descriptor ] 
scalarType = integerType / realType / miscType / bitFields / sizedType 
integerType = [endianness] (standardSizeType / 'i') realType = 
[endianness] ('f' / 'd' / 'e') miscType = 'B' / 'V' / 'c' / 'x' 
sizedType = [endianness] "=" (standardSizeType | number explicitSizeType 
| vectorType) standardSizeType = 'o' / 's' / 'l' / 'q' explicitSizeType 
= 'i' / 'f' vectorType = "=" number 'v' bitFields = integerType ':' 
1*bitField bitField = [number] 'b' endianness = '>' / '<' / '@' 
containerType = [endianness] '[' elementType *(elementType / 
unionMember) ']' unionMember = "|" elementType |

I hope this helps.

[1] - 
http://hg.openjdk.java.net/panama/dev/file/8499209102d4/src/java.base/share/classes/jdk/internal/nicl/types/DescriptorParser.java

Maurizio

​