diff options
Diffstat (limited to 'libjava/classpath/native/target/readme.txt')
| -rw-r--r-- | libjava/classpath/native/target/readme.txt | 149 |
1 files changed, 0 insertions, 149 deletions
diff --git a/libjava/classpath/native/target/readme.txt b/libjava/classpath/native/target/readme.txt deleted file mode 100644 index 6fee79eba63..00000000000 --- a/libjava/classpath/native/target/readme.txt +++ /dev/null @@ -1,149 +0,0 @@ -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 - - |