Add functional description, fixes #519

Author: twall

CHANGES.md

@@ -11,6 +11,7 @@ Features
 * [#510](https://github.com/java-native-access/jna/pull/510): Added `GetCommState`, `GetCommTimeouts` `SetCommState` and `SetCommTimeouts` to `com.sun.jna.platform.win32.Kernel32`. Added `DCB` structure to `com.sun.jna.platform.win32.WinBase` - [@MBollig](https://github.com/MBollig).
 * [#512](https://github.com/java-native-access/jna/pull/512): Make loading debug flags mutable [@lwahonen](https://github.com/lwahonen).
 * [#514](https://github.com/java-native-access/jna/pull/514): Added `host_processor_info` to `com.sun.jna.platform.mac.SystemB`  - [@dbwiddis](https://github.com/dbwiddis).
+* [#519](https://github.com/java-native-access/jna/pull/519): Added JNA functional overview - [@twall](https://github.com/twall).
 
 Bug Fixes
 ---------

README.md

@@ -11,7 +11,7 @@ JNA provides Java programs easy access to native shared libraries without writin
 
 JNA allows you to call directly into native functions using natural Java method invocation. The Java call looks just like the call does in native code. Most calls require no special handling or configuration; no boilerplate or generated code is required.
 
-JNA uses a small JNI library stub to dynamically invoke native code. The developer uses a Java interface to describe functions and structures in the target native library. This makes it quite easy to take advantage of native platform features without incurring the high overhead of configuring and building JNI code for multiple platforms.
+JNA uses a small JNI library stub to dynamically invoke native code. The developer uses a Java interface to describe functions and structures in the target native library. This makes it quite easy to take advantage of native platform features without incurring the high overhead of configuring and building JNI code for multiple platforms.  Read this [more in-depth description](https://github.com/java-native-access/jna/blob/master/www/FunctionalDescription.md).
 
 While significant attention has been paid to performance, correctness and ease of use take priority.
 
@@ -112,6 +112,7 @@ Using the Library
 =================
 
 * [Getting Started](https://github.com/java-native-access/jna/blob/master/www/GettingStarted.md)
+* [Functional Description](https://github.com/java-native-access/jna/blob/master/www/FunctionalDescription.md).
 * [Mapping between Java and Native](https://github.com/java-native-access/jna/blob/master/www/Mappings.md)
 * [Using Pointers and Arrays](https://github.com/java-native-access/jna/blob/master/www/PointersAndArrays.md)
 * [Using Structures and Unions](https://github.com/java-native-access/jna/blob/master/www/StructuresAndUnions.md)

www/FunctionalDescription.md

@@ -0,0 +1,65 @@
+Functional Overview
+===================
+
+JNA's platform-specific functionality is provided by the [libffi
+library](https://github.com/atgreen/libffi).   Previous to the integration of
+libffi into JNA (largely performed by wmeissner), hand-coded assembly was used
+to support linux, sparc, windows, and Mac OSX (intel and PPC targets).   The
+libffi library provides an abstraction for calling arbitrary target addresses
+with an arbitrary set of typed arguments.
+
+The `ffi_prep_cif()` call describes how the target function wishes to be
+called, while `ffi_call()` actually performs the call, provided the CIF
+structure returned by `ffi_prep_cif()`, an arguments array, and a buffer for a
+return value. 
+
+
+Interface Mapping
+-----------------
+When you instantiate a native library interface via `Native.loadLibrary()`,
+JNA creates a proxy which routes all method invocations through a single
+`invoke` function in `Library.Handler`.  This method looks up an appropriate
+`Function` object which represents a function exported by the native library.
+The proxy handler may perform some initial name translation to derive the
+actual native library function name from the invoked proxy function.
+
+Once the `Function` object is found, its generic `invoke` method is called
+with all available arguments.  The proxy function signature is used to figure
+out the types of the incoming arguments and the desired return type.
+
+The `Function` object performs any necessary conversion of arguments,
+converting `NativeMapped` types into their native representation, or applying
+a `TypeMapper` to any incoming types which have registered for `TypeMapper`
+conversion.   Similar conversion is performed on function return.  By default,
+all `Structure` objects have their Java fields copied into their native memory
+before the native function call, and copied back out after the call.
+
+All `Function` invocations are routed through different native methods based
+on their return type, but all those native methods are dispatched through the
+same `dispatch` call in `native/dispatch.c`.  That function performs any final
+conversions of Java objects into native representations before building a
+function call description for use by libffi.
+
+The libffi library requires a description of the target function's arguments
+and return type in order to perform a platform-specific construction of the
+stack suitable for the final native call invocation.  Once libffi has
+performed the native call (via `ffi_call()`), it copies the result into a
+buffer provided by JNA, which then converts it back into an appropriate Java
+object. 
+
+Direct Mapping
+--------------
+JNI provides for registering a native function to be called directly when a
+method marked `native` is called from Java.  JNA constructs code stubs with
+libffi for each native method registered via the `Native.register()` call (JNA
+uses reflection to identify all methods with the `native` qualifier in the
+direct-mapped class).  Each stub dispatches to the function `dispatch_direct`
+in `native/dispatch.c`, and has an associated structure allocated which fully
+describes the function invocation to avoid any reflection costs at runtime.  
+
+The central `dispatch_direct` function attempts to pass the Java call stack
+as-is to the native function (again, using `ffi_call()` from libffi).
+The more non-primitive arguments are used, the more the direct dispatch has to
+do extra work to convert Java objects into native representations on the
+stack.  Ideal performance is achieved by using only primitive or `Pointer`
+arguments.