Update README

Author: manuelbl

README.md

@@ -1,12 +1,12 @@
 # Java Does USB: USB Library for Java
 
-> **Development branch for JDK 20**
-
 [![javadoc](https://javadoc.io/badge2/net.codecrete.usb/java-does-usb/javadoc.svg)](https://javadoc.io/doc/net.codecrete.usb/java-does-usb)
 
-*Java Does USB* is a library for working with USB devices. It allows to query information about all conntected USB devices and to communicate with USB devices using custom / vendor specific protocols. (It is not intended for communication with standard types of USB devices such as mass storage devices, keyboards etc.)
+*Java Does USB* is a Java library for working with USB devices. It allows to query information about all conntected USB devices and to communicate with USB devices using custom / vendor specific protocols. (It is not intended for communication with standard types of USB devices such as mass storage devices, keyboards etc.)
+
+The library uses the [Foreign Function & Memory API](https://github.com/openjdk/panama-foreign) to access native APIs of the underlying operating system. It only uses Java code and does not need JNI or any native third-party library. The *Foreign Function & Memory API* (aka as project Panama) is in preview and will be introduced in a future Java version. Currently, it can be used with Java 19 or Java 20 (with preview features enabled).
 
-The library uses the [Foreign Function & Memory API](https://github.com/openjdk/panama-foreign) to access native APIs of the underlying operating system. It only uses Java code and does not need JNI or any native third-party library. The *Foreign Function & Memory API* (aka as project Panama) is in preview and will be introduced in a future Java version. Currently, it can be used with Java 19 (with preview features enabled).
+*Note: The main branch and published versions ≥ 0.5.0 work with JDK 20 only. For JDK 19, use version 0.4.x.*
 
 
 ## Features
@@ -16,12 +16,12 @@ The library uses the [Foreign Function & Memory API](https://github.com/openjdk/
 - Control, bulk and interrupt transfers (optionally with timeout)
 - Notifications about connected/disconnected devices
 - Descriptive information about interfaces, settings and endpoints
+- High-throughput input/output streams
 - Support for alternate interface settings, composite devices and interface association
 - Published on Maven Central
 
 ### Planned
 
-- High-throughput input/output streams
 - Isochronous transfer
 
 ### Not planned
@@ -41,7 +41,7 @@ If you are using Maven, add the below dependency to your pom.xml:
 <dependency>
       <groupId>net.codecrete.usb</groupId>
       <artifactId>java-does-usb</artifactId>
-      <version>0.4.1</version>
+      <version>0.5.0</version>
 </dependency>
 ```
 
@@ -85,7 +85,7 @@ public class EnumerateDevices {
 - Java 20, preview features enabled (available at https://www.azul.com/downloads/?package=jdk)
 - Windows (x86 64-bit), macOS (x86 64-bit, ARM 64-bit) or Linux 64 bit (x86 64-bit, ARM 64-bit)
 
-For a version compatible with JDK 20, see the branch `jdk20`.
+For JDK 19, use the latest published version 0.4.x.
 
 
 ## Platform-specific Considerations
@@ -126,7 +126,7 @@ The library has not been tested on Windows for ARM64. It might or might not work
 
 ### 32-bit versions
 
-The Foreign Function & Memory API has not been implemented for 32-bit operating systems / JDKs. So it does not support them (and likely never will).
+The Foreign Function & Memory API has not been implemented for 32-bit operating systems / JDKs  (and likely never will be).
 
 
 

java-does-usb/jextract/README.md

@@ -13,7 +13,11 @@ The resulting code is then committed to the source code repository. Before the c
 
 ## General limitations
 
-- Binaries of *jextract* can be downloaded from https://jdk.java.net/jextract/. x64 binaries are available but no ARM64 binaries. According to the mailing list, cross-compiling is not possible, i.e. ARM64 binaries are needed on macOS with Apple Silicon. But so far, the x64 binaries (using the Rosetta2 emulation) have worked without problems.
+- The binaries for *jextract* on https://jdk.java.net/jextract/ have not been updated for JDK 20. So it must be built from source. Instructions can be found at [Building & Testing](https://github.com/openjdk/jextract#building--testing).
+
+- According to the jextract mailing list, it would be required to create separate code form Intel x64 and ARM64 architecture. And jextract would need to be run on each architecture separately (no cross-compilation). Fortunately, this doesn't seem to be the case. Linux code generated on Intel x64 also runs on ARM64 without change. The same holds for macOS. However, jextract needs to be run on each operating system separately.
+
+- JDK 20 introduced a new feature for saving the thread-specific error values (`GetLastError()` on Windows, `errno` on Linux). To use it, an additional parameter must be added to function calls. Unfortuntely, this is not yet supported by jextract. So with the JDK 20 updates, more code is written manually and less is generated by jextract.
 
 - `typedef` and `struct`:
 
@@ -64,7 +68,7 @@ SymbolLookup loaderLookup = SymbolLookup.libraryLookup("libudev.so", MemorySessi
 
 ## MacOS
 
-Most of the required native functions on macOS are part of a framework. Framework internally have a more complex file organization of header and binary files than appears on the outside. Thus they require a special logic to locate framework header files. *clang* supports it with the `-F`. *jextract* allows to specify the options via `compiler_flags.txt` file. Since the file must be in the local directory and since it does not apply to Linux and Windows, separate directories must be used for the operating systems.
+Most of the required native functions on macOS are part of a framework. Frameworks internally have a more complex file organization of header and binary files than appears from the outside. Thus they require a special logic to locate framework header files. *clang* supports it with the `-F`. *jextract* allows to specify the options via `compiler_flags.txt` file. Since the file must be in the local directory and since it does not apply to Linux and Windows, separate directories must be used for the operating systems.
 
 The generated code has the same problem as the Linux code for *udev*. It must be manually changed to use `SymbolLookup.libraryLookup()` for the libraries `CoreFoundation.framework/CoreFoundation` and `IOKit.framework/IOKit` respectively.
 
@@ -73,6 +77,8 @@ The generated code has the same problem as the Linux code for *udev*. It must be
 
 Most Windows SDK header files are not independent. They require that `Windows.h` is included first. So instead of specifying the target header files directly, a helper header file (`windows_headers.h` in this directory) is specified.
 
+Compared to Linux and macOS, the code generation on Windows is very slow (about 1 min vs 3 seconds). And jextract crashes sometimes.
+
 The known limitations are:
 
 - Variable size `struct`: Several Windows struct are of variable size. The last member is an array. The `struct` definition specifies array length 1. But you are expected to allocate more space depending on the actual array size you need. *jextract* generates code for array length 1 and when access array members, the length is checked. So the generated code is difficult to use. Variable size `struct`s are a pain - in any language.