diff options
Diffstat (limited to 'libjava/classpath/native/target/readme.txt')
| -rw-r--r-- | libjava/classpath/native/target/readme.txt | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/libjava/classpath/native/target/readme.txt b/libjava/classpath/native/target/readme.txt new file mode 100644 index 00000000000..6fee79eba63 --- /dev/null +++ b/libjava/classpath/native/target/readme.txt @@ -0,0 +1,149 @@ +The GNU classpath native layer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable GNU classpath to run on a diverse array of different hardware +platforms, a new native software layer has been added. This layer hide all +machine and hardware dependent issues except common available definitions, +which are ANSI C functions. For each targets system where the GNU classpath +library is to be used, a specific set of native layer functions have to be +provided. A generic set of functions is provided for Unix like systems +(currently tested only with Linux). For a new target system, some or +all native layer functions have to be rewritten. The following scheme +illustrate the native layer. + + Java API + ---------------------- + | Java classes | + | -------------------- | + | C native functions | + | -------------------- | + >> | C native layer | << + | -------------------- | + | operating system | + | -------------------- | + | hardware | + ---------------------- + +The C native layer is implemented as a set of C pre-processor native macros. +These macros expand to the appropriated native code. Macros are used +instead function calls to give optimal performance and small code size. +Of course in special cases, a macro can also expand to a function call +if this is needed. This approach provide a flexible and efficient +implementation of the native layer. + +The naming pattern for native macros is like follows: + + TARGET_NATIVE_<module name>_<macro name> + +where <module name> is a name of a module, e. g. FILE; <macro name> is +the name of the specific native macro, e. g. OPEN_READ. + +The parameters for the macro use in general (with a few exceptions) the +scheme + + <parameter>,<parameter>,...,<result> + +where <parameter> is input/output parameter and <result> is the result +code TARGET_NATIVE_OK or TARGET_NATIVE_ERROR. Specific error codes +and error strings can be gotten with + + TARGET_NATIVE_LAST_ERROR and + TARGET_NATIVE_LAST_ERROR_STRING + +(see also file target_generic.h). + +For a single target system there exists two sets of native macros in +the files + + a) <target name>/target_native_<module name>.h + b) generic/target_generic_<module name>.h + +The macros in "a" are target specific implementations of native +functions, the macros in "b" are generic implementations (for Unix) of +the same native functions. If a native macro is not defined in the file +"a", then the definition in file "b" is used (there is a check to see if +a native macros is already defined elsewhere). This technique enables +"a" to 'overwrite' single generic native macros with specific native +macros for a specific target. In the default case, where only the +generic implementation of the native macros is used, the files in the +directory '<target name>' are empty except for the mandatory include of the +generic header file in the directory 'generic' at the end. Please +look at the existing Linux target specific files. + +The directory and file structure is as follows. + + native + ... + | + |--- target + | | + | |--- Linux + | | |--- target_native_<module name>.h + | | |--- ... + | | ... + | |--- ... + | |--- generic + | | |--- target_generic_<module name>.h + | | |--- ... + ... ... ... + + +Include hierarchy is as follows. + + native file <name> + --> include 'target_native_<module name>.h' + ... + <target specific definitions> + ... + --> include 'target_generic_<module name>.h' + ... + <generic definitions> + ... + +When writing native code, please take care with the following. + + - Use _only_ ANSI C specific functions directly which are available + on all target systems with the same parameters, e. g. strdup() is + not an ANSI C function, thus is is not available on all systems; mkdir() + expect on some systems different parameters. + + !!!Do NOT use this functions in your native code!!! + + Instead + + * if a function is not available, create a native macro in the file + + <target name>/target_native_<module name>.h + + * if it is a generic function, include a generic implementation in + + generic/target_generic_<module name>.h + + * Then use this macro in your native code. + + - Avoid _all_ OS specific data types and constants, e. g. structures or error + numbers. Instead, wrap them in a native macro and convert the values to + basic scalar types like char, int, double or long. + + - Take care with 64 bit values; the are machine dependent. Not all + target system support 64 bit operations. The macros in + target_generic_math_int.h give a set of macros implementing 64 bit + operations and constants. + + - Avoid - if possible - non-reentrant functions. Non-reentrant functions + cause strange problems on some multitasking systems. + + - Avoid - if possible - dynamic data types created by malloc() and similar + functions. Instead use (local) static variables to avoid stack usage. + On some target systems, dynamic memory management is either slow or even + dangerous. Moreover malloc()-calls can cause fragmentation of the system + memory, which could result in a system crash or an application failure. + +For some examples, please look in the current implementation for +Linux in the directory 'target/Linux' and the generic implementation in +the directory 'target/generic'. + + + aicas GmbH, February 2003 + + |