From 3ffae4b43012d800c6c853046d8514d6f5f74bd7 Mon Sep 17 00:00:00 2001 From: "Daniel Doubrovkine (dB.) @dblockdotorg" Date: Fri, 9 Oct 2015 09:51:08 -0400 Subject: [PATCH 1/2] Made CHANGES.md a little more pretty. --- CHANGES.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 3c0cd6e397..62beb90046 100755 --- a/CHANGES.md +++ b/CHANGES.md @@ -61,16 +61,16 @@ Features * [#428](https://github.com/java-native-access/jna/pull/428): Added Wincon.h related functions and definitions to `com.sun.jna.platform.win32.Kernel32` - [@lgoldstein](https://github.com/lgoldstein). * [#430](https://github.com/java-native-access/jna/issues/430): Add android `aarch64`, `x86-64`, `mips`, and `mips64` targets - [@twall](https://github.com/twall). * [#431](https://github.com/java-native-access/jna/pull/431): Added named pipe API support to `com.sun.jna.platform.win32.Kernel32` - [@lgoldstein](https://github.com/lgoldstein). -* [#432](https://github.com/java-native-access/jna/pull/432): Added SetLocalTime definition to 'com.sun.jna.platform.win32.Kernel32' - [@lgoldstein](https://github.com/lgoldstein). -* [#434](https://github.com/java-native-access/jna/pull/434): Added GetEnvironmentStrings to 'com.sun.jna.platform.win32.Kernel32' - [@lgoldstein](https://github.com/lgoldstein). +* [#432](https://github.com/java-native-access/jna/pull/432): Added `com.sun.jna.platform.win32.Kernel32.SetLocalTime` - [@lgoldstein](https://github.com/lgoldstein). +* [#434](https://github.com/java-native-access/jna/pull/434): Added `com.sun.jna.platform.win32.Kernel32.GetEnvironmentStrings` - [@lgoldstein](https://github.com/lgoldstein). * Loosen OSGI OS name matching to accommodate Windows 8 family - Niels Bertram. * [#436] (https://github.com/java-native-access/jna/pull/469): Added basic Pdh API implementation to 'com.sun.jna.platform.win32' - [@lgoldstein](https://github.com/lgoldstein). * [#451] (https://github.com/java-native-access/jna/pull/451): Add VARIANT support for CHAR and BYTE - [@mitkola](https://github.com/mitkola). * [#478] (https://github.com/java-native-access/jna/issues/451): Ask ldconfig for more places to search for libraries - [@gohal](https://github.com/gohal). -* [#481] (https://github.com/java-native-access/jna/pull/481): Added volume management functions to 'com.sun.jna.platform.win32' - [@lgoldstein](https://github.com/lgoldstein). -* [#483] (https://github.com/java-native-access/jna/pull/483): Found and fixed duplicate method definitions for the same API in 'com.sun.jna.platform.win32' - [@lgoldstein](https://github.com/lgoldstein). -* [#485] (https://github.com/java-native-access/jna/pull/485): Implemented Comparable interface for many of the base types in 'com.sun.jna.platform.win32.WinDef' - [@lgoldstein](https://github.com/lgoldstein). -* [#488] (https://github.com/java-native-access/jna/pull/488): Added GetRawInputDeviceList definition and utility to 'com.sun.jna.platform.win32' User32 and User32Util - [@lgoldstein](https://github.com/lgoldstein). +* [#481] (https://github.com/java-native-access/jna/pull/481): Added volume management functions to `com.sun.jna.platform.win32` - [@lgoldstein](https://github.com/lgoldstein). +* [#483] (https://github.com/java-native-access/jna/pull/483): Found and fixed duplicate method definitions for the same API in `com.sun.jna.platform.win32` - [@lgoldstein](https://github.com/lgoldstein). +* [#485] (https://github.com/java-native-access/jna/pull/485): Implemented `Comparable` interface for many of the base types in `com.sun.jna.platform.win32.WinDef` - [@lgoldstein](https://github.com/lgoldstein). +* [#488] (https://github.com/java-native-access/jna/pull/488): Added `GetRawInputDeviceList` to `com.sun.jna.platform.win32.User32` and `User32Util` - [@lgoldstein](https://github.com/lgoldstein). * [#490](https://github.com/java-native-access/jna/issues/490): Allow arbitrary calling convention specification, including FFI_MS_CDECL which alters handling of struct return values, and multiple Linux/PowerPC conventions - [@twall](https://github.com/twall). Bug Fixes @@ -175,7 +175,7 @@ Features * [PR#192](https://github.com/java-native-access/jna/pull/192): Added Win32 `SHGetSpecialFolderPath()` and initialization file (.ini) API functions from `kernel32.dll` - [@headcrashing](https://github.com/headcrashing). * [PR#194](https://github.com/java-native-access/jna/pull/194): Added Unit Test for `CLSIDFromProgID()` - [@headcrashing](https://github.com/headcrashing). * [PR#196](https://github.com/java-native-access/jna/pull/196): Added Win32 `RegisterWindowMessage()` and new wrapper `User32Util` for convenient use of `RegisterWindowMessage`, `CreateWindow` and `CreateWindowEx` - [@headcrashing](https://github.com/headcrashing). -* [PR#187](https://github.com/java-native-access/jna/pull/187): Allow StructureFieldOrderTest unit test in platform project to run on Linux. - [@bhamail](https://github.com/bhamail). +* [PR#187](https://github.com/java-native-access/jna/pull/187): Allow `StructureFieldOrderTest` unit test in platform project to run on Linux. - [@bhamail](https://github.com/bhamail). Bug Fixes --------- From 506a03ba99d327efaf131761f72cec4967f52a04 Mon Sep 17 00:00:00 2001 From: Timothy Wall Date: Sat, 17 Oct 2015 18:27:02 -0400 Subject: [PATCH 2/2] Add functional description, fixes #519 --- CHANGES.md | 1 + README.md | 3 +- www/FunctionalDescription.md | 65 ++++++++++++++++++++++++++++++++++++ 3 files changed, 68 insertions(+), 1 deletion(-) create mode 100644 www/FunctionalDescription.md diff --git a/CHANGES.md b/CHANGES.md index 62beb90046..d11fcff10f 100755 --- a/CHANGES.md +++ b/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 --------- diff --git a/README.md b/README.md index a915d4a52d..f9df0facfd 100644 --- a/README.md +++ b/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) diff --git a/www/FunctionalDescription.md b/www/FunctionalDescription.md new file mode 100644 index 0000000000..44b28ab41c --- /dev/null +++ b/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. \ No newline at end of file