150 lines
5.5 KiB
Plaintext
150 lines
5.5 KiB
Plaintext
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
|
|
|
|
|