The binding operators defined in the Binding class can be combined into argument and return value processing 'recipes'. The binding operators are interpreted using a stack-base interpreter. Operators can either consume operands from the stack, or push them onto the stack. In the description of each binding we talk about 'boxing' and 'unboxing'. - Unboxing is the process of taking a Java value and decomposing it, and storing components into machine storage locations. As such, the binding interpreter stack starts with the Java value on it, and should end empty. - Boxing is the process of re-composing a Java value by pulling components from machine storage locations. If a MemorySegment is needed to store the result, one should be allocated using the ALLOCATE_BUFFER operator. The binding interpreter stack starts off empty, and ends with the value to be returned as the only value on it. A binding operator can be interpreted differently based on whether we are boxing or unboxing a value. For example, the CONVERT_ADDRESS operator 'unboxes' a MemoryAddress to a long, but 'boxes' a long to a MemoryAddress. Here are some examples of binding recipes derived from C declarations, and according to the Windows ABI (recipes are ABI-specific). Note that each argument has its own recipe, which is indicated by '[number]:' (though, the only example that has multiple arguments is the one using varargs). -------------------- void f(int i); Argument bindings: 0: VM_STORE(rcx, int.class) // move an 'int' into the RCX register Return bindings: none -------------------- void f(int* i); Argument bindings: 0: UNBOX_ADDRESS // the 'MemoryAddress' is converted into a 'long' VM_STORE(rcx, long.class) // the 'long' is moved into the RCX register Return bindings: none -------------------- int* f(); Argument bindings: none Return bindings: 0: VM_LOAD(rax, long) // load a 'long' from the RAX register BOX_ADDRESS // convert the 'long' into a 'MemoryAddress' -------------------- typedef struct { // fits into single register int x; int y; } MyStruct; void f(MyStruct ms); Argument bindings: 0: BUFFER_LOAD(0, long.class) // From the struct's memory region, load a 'long' from offset '0' VM_STORE(rcx, long.class) // and copy that into the RCX register Return bindings: none -------------------- typedef struct { // does not fit into single register long long x; long long y; } MyStruct; void f(MyStruct ms); For the Windows ABI: Argument bindings: 0: COPY(16, 8) // copy the memory region containing the struct BASE_ADDRESS // take the base address of the copy UNBOX_ADDRESS // converts the base address to a 'long' VM_STORE(rcx, long.class) // moves the 'long' into the RCX register Return bindings: none For the SysV ABI: Argument bindings: 0: DUP // duplicates the MemoryRegion operand BUFFER_LOAD(0, long.class) // loads a 'long' from offset '0' VM_STORE(rdx, long.class) // moves the long into the RDX register BUFFER_LOAD(8, long.class) // loads a 'long' from offset '8' VM_STORE(rcx, long.class) // moves the long into the RCX register Return bindings: none -------------------- typedef struct { // fits into single register int x; int y; } MyStruct; MyStruct f(); Argument bindings: none Return bindings: 0: ALLOCATE(GroupLayout(C_INT, C_INT)) // allocate a buffer with the memory layout of the struct DUP // duplicate the allocated buffer VM_LOAD(rax, long.class) // loads a 'long' from rax BUFFER_STORE(0, long.class) // stores a 'long' at offset 0 -------------------- typedef struct { // does not fit into single register long long x; long long y; } MyStruct; MyStruct f(); !! uses synthetic argument, which is a pointer to a pre-allocated buffer Argument bindings: 0: UNBOX_ADDRESS // unbox the MemoryAddress synthetic argument VM_STORE(rcx, long.class) // moves the 'long' into the RCX register Return bindings: none -------------------- void f(int dummy, ...); // varargs f(0, 10f); // passing a float Argument bindings: 0: VM_STORE(rcx, int.class) // moves the 'int dummy' into the RCX register 1: DUP // duplicates the '10f' argument VM_STORE(rdx, float.class) // move one copy into the RDX register VM_STORE(xmm1, float.class) // moves the other copy into the xmm2 register Return bindings: none --------------------