From 42bd110d9ec63594cc028f3ee8a459424b1d2ae0 Mon Sep 17 00:00:00 2001 From: Sven Gothel Date: Sat, 17 Jun 2023 07:07:52 +0200 Subject: Drop .md -> .html generated docs (ugly), use our cgit md -> html via refined pandoc styles Would need to fix my standalone pandoc setup to produce proper standalone docs. --- doc/GlueGen_Mapping.html | 1054 ------------------------------------------ doc/JogAmpMacOSVersions.html | 184 -------- 2 files changed, 1238 deletions(-) delete mode 100644 doc/GlueGen_Mapping.html delete mode 100644 doc/JogAmpMacOSVersions.html (limited to 'doc') diff --git a/doc/GlueGen_Mapping.html b/doc/GlueGen_Mapping.html deleted file mode 100644 index 28e1e62..0000000 --- a/doc/GlueGen_Mapping.html +++ /dev/null @@ -1,1054 +0,0 @@ - - - - - - - GlueGen_Mapping.md - - - - - - - -

GlueGen Native -Data & Function Mapping for Java™

-

References

- -

Overview

-

GlueGen is a compiler -for function and data-structure declarations, generating Java and JNI C -code offline at compile time and allows using native libraries within -your Java application.

-

It reads ANSI C header files and separate configuration files which -provide control over many aspects of the glue code generation. GlueGen -uses a complete ANSI C parser and an internal representation (IR) -capable of representing all C types to represent the APIs for which it -generates interfaces. It has the ability to perform significant -transformations on the IR before glue code emission.

-

GlueGen can produce native foreign function bindings to Java as well -as map native data structures to be fully accessible from Java including -potential calls to embedded function pointer.

-

GlueGen is also capable to bind even low-level APIs such as the Java -Native Interface (JNI) and the AWT Native Interface (JAWT) back up to -the Java programming language.

-

GlueGen utilizes JCPP, migrated C -preprocessor written in Java.

-

GlueGen is used for the JogAmp -projects JOAL, JOGL and JOCL.

-

GlueGen is part of the JogAmp -project.

-

Primitive Mapping

-

Gluegen has build-in types (terminal symbols) for:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
typejava-bitsnative-bits
x32
native bits
x64
typesignedorigin
void000voidvoidANSI-C
char888integeranyANSI-C
short161616integeranyANSI-C
int323232integeranyANSI-C
long643232integeranyANSI-C - Windows
long643264integeranyANSI-C - Unix
float323232floatsignedANSI-C
double646464doublesignedANSI-C
__int32323232integeranywindows
__int64646464integeranywindows
int8_t888integersignedstdint.h
uint8_t888integerunsignedstdint.h
int16_t161616integersignedstdint.h
uint16_t161616integerunsignedstdint.h
int32_t323232integersignedstdint.h
uint32_t323232integerunsignedstdint.h
int64_t646464integersignedstdint.h
uint64_t646464integerunsignedstdint.h
intptr_t643264integersignedstdint.h
uintptr_t643264integerunsignedstdint.h
ptrdiff_t643264integersignedstddef.h
size_t643264integerunsignedstddef.h
wchar_t323232integersignedstddef.h
-

Warning: Try to avoid unspecified bit sized types, -especially long, since it differs on Unix and -Windows!
-Notes:

- -

String Mapping

-

Function return String -values

-

Function return values are currently mapped from char* -to Java String using UTF-8 via JNI function

-
-

jstring NewStringUTF(JNIEnv *env, const char *bytes)

-
-

FIXME: This might need more flexibility in case UTF-8 is not -suitable for 8-bit wide char mappings or wide characters, -e.g. for UTF-16 needs to be supported.

-

Function argument String -values

-

Function argument values are either mapped from char* to -Java String using UTF-8 via JNI function

-
-

const char * GetStringUTFChars(JNIEnv *env, jstring string, jboolean *isCopy).

-
-

Alternatively, if a 16-bit wide character type has been -detected, i.e. short, the native character are mapped -to Java using UTF-16 via JNI function

-
-

void GetStringRegion(JNIEnv *env, jstring str, jsize start, jsize len, jchar *buf).

-
-

Struct String mapping

-

String value mapping for Struct fields is performed -solely from the Java side using Charset and is hence most -flexible.

-

By default, UTF-8 is being used for getter and setter of -String values.
-The Struct class provides two methods to get and set the used -Charset for conversion

-
  /** Returns the Charset for this class's String mapping, default is StandardCharsets.UTF_8. */
-  public static Charset getCharset() { return _charset; };
-
-  /** Sets the Charset for this class's String mapping, default is StandardCharsets.UTF_8. */
-  public static void setCharset(Charset cs) { _charset = cs; }
-
-

In case the String length has not been configured via -ReturnedArrayLength, it will be dynamically calculated via -strnlen(aptr, max_len).
-The maximum length default for the strnlen(..) operation is -8192 bytes and can be get and set using:

-
  /** Returns the maximum number of bytes to read to determine native string length using `strnlen(..)`, default is 8192. */
-  public static int getMaxStrnlen() { return _max_strnlen; };
-
-  /** Sets the maximum number of bytes to read to determine native string length using `strnlen(..)`, default is 8192. */
-  public static void setMaxStrnlen(int v) { _max_strnlen = v; }
-

FIXME: This only works reliable using an 8-bit Charset -encoding, e.g. the default UTF-8.

-

Alignment for Compound Data

-

In general, depending on CPU and it's configuration (OS), alignment -is set up for each type (char, short, int, long, ..).

-

Compounds (structures) are aligned naturally, i.e. their inner -components are aligned
-and are itself aligned to it's largest element.

-

See:

- -

Simple alignment arithmetic

-

Modulo operation, where the 2nd handles the case offset == -alignment:

-
-

padding = ( alignment - ( offset % alignment ) ) % alignment ;
-aligned_offset = offset + padding ;

-
-

Optimization utilizing alignment as a multiple of 2 --> x % 2n == x & ( 2n - 1 )

-
-

remainder = offset & ( alignment - 1 ) ;
-padding = ( remainder > 0 ) ? alignment - remainder : 0 ;
-aligned_offset = offset + padding ;

-
-

Without branching, using the 2nd modulo operation for the case offset -== alignment:

-
-

padding = ( alignment - ( offset & ( alignment - 1 ) ) ) & ( -alignment - 1 ) ;
-aligned_offset = offset + padding ;

-
-

See -com.jogamp.gluegen.cgram.types.SizeThunk.align(..).

-

Type -Size & Alignment for x86, x86_64, armv6l-32bit-eabi and -Window(mingw/mingw64)

-

Runtime query is implemented as follows:

-
   typedef struct {
-     char   fill;  // nibble one byte
-                   // padding to align s1: padding_0 
-     type_t s1;    // 
-   } test_struct_type_t;
-  
-             padding_0 = sizeof(test_struct_type_t) - sizeof(type_t) - sizeof(char) ;
-   alignmentOf(type_t) = sizeof(test_struct_type_t) - sizeof(type_t) ;
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
typesize
32 bit
alignment
32 bit
size
64 bit
alignment
64 bit
char1111
short2222
int4444
float4444
long448†,4∗8†,4∗
pointer4488
long long84†,8∗+88
double84†,8∗+88
long double12†∗,8+,16-4†∗,8+,16-1616
-

† Linux, Darwin
-+armv7l-eabi
-- MacOsX-32bit-gcc4
-∗ Windows

-

Struct Mapping

-

A Struct is a C compound type declaration, which can be -mapped to a Java class.

-

A Struct may utilize the following data types for its -fields

- -

A field may be a direct aggregation, i.e. instance, within the struct -including an array or a reference to a single element or array via a -pointer.

-

Both, primitive and struct field type mappings only -produce pure Java code, utilizing the GlueGen Runtime. Hence no -additional native code must be compiled nor a resulting additional -library loaded to use the mapping.

-

Only when mapping function-pointer within structs, -additional native glue-code is produced to call the underlying native -function which has to be compiled and its library loaded.

-

The generated method -public static boolean usesNativeCode() can be used to -validate whether the produced Java class requires a corresponding -library for additional native code.

-

GlueGen Struct Settings

-

ImmutableAccess -symbol

-

Immutable access can be set for a whole struct or a single field of a -struct.

-

Immutable access will simply suppress generating setters in the Java -code and hence also reduces the footprint of the generated Java class -for such struct.

- -

MaxOneElement -symbol

- -

ReturnedArrayLength -symbol expression

- -

ReturnsString -symbol

-

A direct C code char array or indirect array via pointer -can be interpreted as a Java String.

- -

ReturnsStringOnly -symbol

- -

Struct Mapping Notes

- -

Struct Java Signature Table

-

Please find below signature table as generated by the C -Declaration including its C Modifier, e.g. -const for constant, [const] for const and -non-const and empty for non-const (variable).

-

Further, the GlueGen Setting (see above) impacts the code -generation as well.

-

Below table demonstrates primitive types being mapped within -a struct named TK_Struct. A similar mapping is -produced for struct types, i.e. compounds.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
C ModC DeclarationJava SetterJava GetterGlueGen SettingOwnershipRemarks
static boolean usesNativeCode()Java, static,
true if using -native code
static int size()Java, static,
native size in -bytes
static TK_Struct create()Java, static ctor
static TK_Struct create(ByteBuffer)Java, static ctor
w/ existing -ByteBuffer
static TK_Struct derefPointer(long -addr)Java, static ctor
dereferencing -ByteBuffer
at native address of size()
ByteBuffer getBuffer()Java,
underlying ByteBuffer
long getDirectBufferAddress()Java, native address
of underlying -getBuffer()
int32_t valsetVal(int v)int getVal()Static
constint32_t valnoneint getVal()StaticRead only
int32_t valnoneint getVal()ImmutableAccessStaticRead only
[const]int32_t* valsetVal(int v) [1][2]
-releaseVal()
int getVal()
boolean isValNull()
-int getValElemCount()
MaxOneElementJavaStarts w/ null elements,
max 1 -element
constint32_t* valnoneint getVal()
boolean isValNull()
-static int getValElemCount()
ReturnedArrayLength -1NativeConst element count 1
int32_t* valsetVal(int v)int getVal()
boolean isValNull()
-static int getValElemCount()
ReturnedArrayLength -1NativeConst element count 1
int32_t val[3]setVal(int[] src, int srcPos, int destPos, -int len)IntBuffer getVal()
int[] getVal(int -srcPos, int[] dest, int destPos, int len)
Static
constint32_t val[3]noneIntBuffer getVal()
int[] getVal(int -srcPos, int[] dest, int destPos, int len)
StaticRead only
constint32_t* valnoneIntBuffer getVal()
int[] getVal(int -srcPos, int[] dest, int destPos, int len)
boolean isValNull()
-static int getValElemCount()
ReturnedArrayLength -3NativeRead only
Const element count 3
int32_t* valsetVal(int[] src, int srcPos, int destPos, -int len)IntBuffer getVal()
int[] getVal(int -srcPos, int[] dest, int destPos, int len)
boolean isValNull()
-static int getValElemCount()
ReturnedArrayLength -3NativeConst element count 3
int32_t* valsetVal(boolean subset, int[] src, int -srcPos, int destPos, int len)
releaseVal()
IntBuffer getVal()
int[] getVal(int -srcPos, int[] dest, int destPos, int len)
boolean isValNull()
-int getValElemCount()
JavaStarts w/ null elements
constint32_t* valsetVal(int[] src, int srcPos, int destPos, -int len)
releaseVal()
IntBuffer getVal()
int[] getVal(int -srcPos, int[] dest, int destPos, int len)
boolean isValNull()
-int getValElemCount()
JavaStarts w/ null elements
[const]int32_t* valsetVal(int[] src, int srcPos, int destPos, -int len)
releaseVal()
IntBuffer getVal()
int[] getVal(int -srcPos, int[] dest, int destPos, int len)
boolean isValNull()
ReturnedArrayLength -getValCount()AmbiguousVariable element count
using field -valCount,
which has getter and setter
[const]char* namesetName(String srcVal)
-releaseVal()
String getName()
boolean isNameNull() -
int getNameElemCount()
ReturnsStringOnlyJavaString only, w/ EOS
[const]char* namesetName(String srcVal)
setName(byte[] -src, int srcPos, int destPos, int len)
releaseVal()
String getNameAsString()
ByteBuffer -getName()
boolean isNameNull()
int getNameElemCount()
ReturnsStringJavaString and byte access, w/ EOS
-

Signature -int32_t * MaxOneElement, Java owned

-
  /**
-   * Setter for native field <code>variaInt32PointerMaxOneElem</code>, referencing an array with initial element count of <code>0</code>. Maximum element count is <code>1</code>.
-   * <p>
-   * NativeSig <code>(PointerType) 'int32_t *' -> (int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1</code>
-   * </p>
-   */
-  public final TK_Field setVariaInt32PointerMaxOneElem(int src) { .. }
-

Will reuse memory if existing, otherwise allocating memory.

-

Signature -const int32_t * MaxOneElement, Java owned

-
  /**
-   * Setter for native field <code>constInt32PointerMaxOneElem</code>, referencing an array with initial element count of <code>0</code>. Maximum element count is <code>1</code>.
-   * <p>
-   * NativeSig <code>(PointerType) 'int32_t *' -> (const int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1</code>
-   * </p>
-   */
-  public final TK_Field setConstInt32PointerMaxOneElem(int src) { .. }
-  
-

Always replaces memory due to const value modifier.

-

Signature -int32_t * ConstElemCount 3, Natively owned

-
  /**
-   * Setter for native field <code>variaInt32PointerConstLen</code>, referencing a natively owned array with fixed element count of <code>3</code>.
-   * <p>
-   * NativeSig <code>(PointerType) 'int32_t *' -> (int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1</code>
-   * </p>
-   * <p>
-   * Copies the given source elements into the respective field's existing memory.
-   * </p>
-   * @param src the source array of elements
-   * @param srcPos starting element position within the source array with 'srcPos >= 0` &&  `srcPos + length <= src.length`, otherwise an {@link IndexOutOfBoundsException} is thrown
-   * @param destPos starting element position within the destination with 'destPos >= 0` && `destPos + length <= elemCount`, otherwise an exception is thrown
-   * @param length the element count to be copied with 'length >= 0` &&  `srcPos + length <= src.length` && `destPos + length <= elemCount`, otherwise an {@link IndexOutOfBoundsException} is thrown
-   * @return this instance of chaining
-   */
-  public final TK_Field setVariaInt32PointerConstLen(int[] src, final int srcPos, final int destPos, final int length) { .. }
-

Signature -int32_t * FreeSize, Java owned

-
  /**
-   * Setter for native field <code>variaInt32PointerVariaLen</code>, referencing an array with initial element count of <code>0</code>.
-   * <p>
-   * NativeSig <code>(PointerType) 'int32_t *' -> (int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1</code>
-   * </p>
-   * <p>
-   * Copies the given source elements into the respective field, either writing into the existing memory or creating a new memory and referencing it.
-   * </p>
-   * @param subset if `true` keeps the underlying memory and only allows to set up to `elemCount` elements. Otherwise may replace the underlying memory if `destPos + length != elemCount`.
-   * @param src the source array of elements
-   * @param srcPos starting element position within the source array with 'srcPos >= 0` &&  `srcPos + length <= src.length`, otherwise an {@link IndexOutOfBoundsException} is thrown
-   * @param destPos starting element position within the destination with 'destPos >= 0`. If `subset == true`, `destPos + length <= elemCount` also must be be `true`. Otherwise an exception is thrown
-   * @param length the element count to be copied with 'length >= 0` &&  `srcPos + length <= src.length`, otherwise an {@link IndexOutOfBoundsException} is thrown
-   * @return this instance of chaining
-   */
-  public final TK_Field setVariaInt32PointerVariaLen(final boolean subset, int[] src, final int srcPos, final int destPos, final int length) { .. }  
-

Struct Setter Pseudo-Code

- -

Platform Header Files

-

GlueGen provides convenient platform headers,
-which can be included in your C header files for native compilation and -GlueGen code generation.

-

Example:

-
   #include <gluegen_stdint.h>
-   #include <gluegen_stddef.h>
- 
-   uint64_t test64;
-   size_t size1;
-   ptrdiff_t ptr1;
-

To compile this file you have to include the following folder to your -compilers system includes, ie -I:

-
    gluegen/make/stub_includes/platform
-

To generate code for this file you have to include the following -folder to your GlueGen includeRefid element:

-
    gluegen/make/stub_includes/gluegen
-

Pre-Defined Macros

-

To identity a GlueGen code generation run, GlueGen defines the -following macros:

-
     #define __GLUEGEN__ 2
- - diff --git a/doc/JogAmpMacOSVersions.html b/doc/JogAmpMacOSVersions.html deleted file mode 100644 index 34cce37..0000000 --- a/doc/JogAmpMacOSVersions.html +++ /dev/null @@ -1,184 +0,0 @@ - - - - - - - JogAmpMacOSVersions.md - - - - - - - -

JogAmp's MacOS Version -Support

-

References

- -

Overview

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MacOS VersionRelease NameDarwin VersionJogAmp Relation
10.7Lion11Min deployment target
10.13High Sierra17Test node 10.13.6, -x86_64
10.14Mojave18
10.15Catalina19
11Big Sur20
12Monterey21Build node 12.6.5, w/ Xcode 14.2, -x86_64
13Ventura22Test node 13.1, arm64
-

OpenJDK

-

Available Java(tm) VMs

- -

JogAmp Build and Test Setup

-

MacOS 12.6.5 (Monterey), -Darwin 21, x86_64

- -

MacOS 10.13.6 (High -Sierra), Darwin 17, x86_64

- -

MacOS 13.1 (Ventura), Darwin -22, arm64

- -

Change History

- - - - - - - - - - - - - -
DateNote
2023-05-06Initial Version for JogAmp Release -2.5.0
- - -- cgit v1.2.3