Contents | Prev | Next
J2ME CDC 1.0
Porting Guide

Host Programming Interface (HPI) Reference

This chapter describes the definitions required by the Host Programming Interface (HPI). The HPI defines the set of APIs that must be implemented when porting CVM.

The HPI connects the CVM to its target operating system. The HPI is defined in the header files in src/share/javavm/include/porting/. These shared header files "include" machine-dependent header files that reside in src/<platform>/javavm/include/.

Note: Some parts of the HPI are implemented as functions and other parts as macros. The macros are defined in header files that are included by the HPI header files.

The following table summarizes the header files that define the HPI. Additional information for each header file follows this table.
 
Header File Description
defs.h Lists CVM primitive types, macros for ANSI header file locations, macros for HPI included header file locations, and macros indicating whether the implementation supports certain advanced features. Explicitly includes a machine-dependent definitions header file. The reference implementation of the included file resides in src/<platform>/javavm/include/defs_md.h.
doubleword.h Declares 64-bit conversion functions, and functions related to the long and double data types.
endianness.h Lists macros that indicate endianness (big endian or little endian).
float.h Declares functions related to the float data types.
globals.h Lists functions related to the per-VM global state and the per-address-space static state.
int.h Lists functions related to the integer (int) data types.
io.h Lists I/O-related macros and functions.
jni.h Lists functions and other information related to the Java Native Interface (JNI).
linker.h Lists functions and other information related to dynamic linking.
net.h Lists functions related to networking.
path.h Lists macros and a function related to paths.
sync.h Lists functions used to facilitate thread synchronization and mutual exclusion locks.
system.h Lists functions and other information related to system functions.
threads.h Lists functions and other information related to threads.
time.h Lists time functions.
vm-defs.h Declares CVM data structure names and data types. The data types are exported to the HPI implementation.

defs.h

The file src/share/javavm/include/porting/defs.h specifies the following definition requirements.

Type Definitions

Type Description
CVMfloat32 Single-precision IEEE floating point type.
CVMfloat64 Double-precision IEEE floating point type.
CVMInt8 Signed 8-bit integer type.
CVMInt16 Signed 16-bit integer type.
CVMInt32 Signed 32-bit integer type.
CVMInt64 Signed 64-bit integer type.
CVMSize Size in bytes of a data type. Equivalent to ANSI C size_t.
CVMUint8 Unsigned 8-bit integer type.
CVMUint16 Unsigned 16-bit integer type.
CVMUint32 Unsigned 32-bit integer type.
CVMUint64 Unsigned 64-bit integer type.

ANSI Header File Locations

Macro Description
CVM_HDR_ANSI_ASSERT_H Provides the location of the ANSI header file assert.h.
CVM_HDR_ANSI_CTYPE_H Provides the location of the ANSI header file ctype.h.
CVM_HDR_ANSI_ERRNO_H Provides the location of the ANSI header file errno.h.
CVM_HDR_ANSI_LIMITS_H Provides the location of the ANSI header file limits.h.
CVM_HDR_ANSI_SETJMP_H Provides the location of the ANSI header file setjmp.h.
CVM_HDR_ANSI_STDARG_H Provides the location of the ANSI header file stdarg.h.
CVM_HDR_ANSI_STDDEF_H Provides the location of the ANSI header file stddef.h.
CVM_HDR_ANSI_STDIO_H Provides the location of the ANSI header file stdio.h.
CVM_HDR_ANSI_STDLIB_H Provides the location of the ANSI header file stdlib.h.
CVM_HDR_ANSI_STRING_H Provides the location of the ANSI header file string.h.
CVM_HDR_ANSI_TIME_H Provides the location of the ANSI header file time.h.

HPI Included Header File Locations

Macro Description
CVM_HDR_DOUBLEWORD_H Provides the location of the HPI header file included by porting/doubleword.h.
CVM_HDR_ENDIANNESS_H Provides the location of the HPI header file included by porting/endianness.h.
CVM_HDR_FLOAT_H Provides the location of the HPI header file included by porting/float.h.
CVM_HDR_GLOBALS_H Provides the location of the HPI header file included by porting/globals.h.
CVM_HDR_INT_H Provides the location of the HPI header file included by porting/int.h.
CVM_HDR_IO_H Provides the location of the HPI header file included by porting/io.h.
CVM_HDR_JNI_H Provides the location of the HPI header file included by porting/jni.h.
CVM_HDR_LINKER_H Provides the location of the HPI header file included by porting/linker.h.
CVM_HDR_NET_H Provides the location of the HPI header file included by porting/net.h.
CVM_HDR_PATH_H Provides the location of the HPI header file included by porting/path.h.
CVM_HDR_SYNC_H Provides the location of the HPI header file included by porting/sync.h.
CVM_HDR_THREADS_H Provides the location of the HPI header file included by porting/threads.h.
CVM_HDR_TIME_H Provides the location of the HPI header file included by porting/time.h.

Advanced Platform Features

The following macros represent advanced features. These features are not required, but they support VM optimization such as fast locking. If the macros are not defined, a default implementation is used.

For information about the functions referenced in the descriptions below, see the section on the sync.h header file.
 
Macro Description
CVM_ADV_ATOMIC_CMPANDSWAP Define this if atomic compare-and-swap (CVMatomicCompareAndSwap) is supported.
CVM_ADV_ATOMIC_INCDEC Define this if atomic increment (CVMatomicIncrement) and atomic decrement (CVMatomicDecrement) are supported.
CVM_ADV_ATOMIC_SWAP Define this if atomic swap (CVMatomicSwap) is supported.
CVM_ADV_MUTEX_SET_OWNER Define this if setting the owner of a mutex (CVMmutexSetOwner) is supported.
CVM_ADV_SCHEDLOCK Define this if a scheduler lock (CVMschedLock) is supported.

doubleword.h

The file src/share/javavm/include/porting/doubleword.h specifies the following definition requirements.

64-bit Conversion Functions

Declaration Description
void CVMdouble2Jvm(CVMUint32 location[2], CVMJavaDouble val); Reads a 64-bit Java double in native representation from val and writes the result in two-word JVM representation to location.
CVMJavaDouble CVMjvm2Double(const CVMUint32 location[2]); Reads a 64-bit Java double in two-word JVM representation from location and returns the result in native representation. There is no restriction on the JVM representation, except that a value written using CVMdouble2Jvm() must return the same value when CVMjvm2Double() is called (The operation is reversible).
CVMJavaLong CVMjvm2Long(const CVMUint32 location[2]); Reads a 64-bit Java long in two-word JVM representation from location and returns the result in native representation. There is no restriction on the JVM representation, except that a value written using CVMlong2Jvm() must return the same value when CVMjvm2Long() is called (The operation is reversible).
void CVMlong2Jvm(CVMUint32 location[2], CVMJavaLong val); Reads a 64-bit Java long in native representation from val and writes the result in two-word JVM representation to location.
void CVMmemCopy64(CVMUint32 to[2], const CVMUint32 from[2]); Copies two typeless 32-bit words from one location to another. This is semantically equivalent to:
to[0] = from[0];
to[1] = from[1];
but this interface is provided for those platforms that could optimize this into a single 64-bit transfer.

Long Conversion Functions

Declaration Description
extern CVMJavaLong CVMdouble2Long(CVMJavaDouble val); Converts double to long, according to d2l bytecode semantics.
extern CVMJavaLong CVMdouble2LongBits(CVMJavaDouble val); Converts double bits to long bits, according to Double.doubleToRawLongBits().
extern CVMJavaLong CVMint2Long(CVMJavaInt val); Converts int to long, according to i2l bytecode semantics.
extern CVMJavaDouble CVMlong2Double(CVMJavaLong val); Converts long to double, according to l2d bytecode semantics.
extern CVMJavaFloat CVMlong2Float(CVMJavaLong val); Converts long to float, according to l2f bytecode semantics.
extern CVMJavaInt CVMlong2Int(CVMJavaLong val); Converts long to int, according to l2i bytecode semantics.
extern void * CVMlong2VoidPtr(CVMJavaLong val); Converts long to void *.
extern CVMJavaDouble CVMlongBits2Double(CVMJavaLong val); Converts long bits to double bits, according to Double.longBitsToDouble().
extern CVMJavaLong CVMvoidPtr2Long(void * val); Converts void * to long.

Long Arithmetic Functions

Declaration Description
CVMJavaLong CVMlongAdd(CVMJavaLong op1, CVMJavaLong op2); Follows the ladd bytecode semantics.
CVMJavaLong CVMlongAnd(CVMJavaLong op1, CVMJavaLong op2); Follows the land bytecode semantics.
CVMJavaLong CVMlongDiv(CVMJavaLong op1, CVMJavaLong op2); Follows the ldiv bytecode semantics.
CVMJavaLong CVMlongMul(CVMJavaLong op1, CVMJavaLong op2); Follows the lmul bytecode semantics.
CVMJavaLong CVMlongOr(CVMJavaLong op1, CVMJavaLong op2); Follows the lor bytecode semantics.
CVMJavaLong CVMlongRem(CVMJavaLong op1, CVMJavaLong op2); Follows the lrem bytecode semantics.
CVMJavaLong CVMlongSub(CVMJavaLong op1, CVMJavaLong op2); Follows the lsub bytecode semantics.
CVMJavaLong CVMlongXor(CVMJavaLong op1, CVMJavaLong op2); Follows the lxor bytecode semantics.

More Long Functions

Declaration Description
CVMInt32 CVMlongCompare(CVMJavaLong op1, CVMJavaLong op2); Compares op1 and op2 according to the lcmp bytecode semantics. Return type is CVMInt32 (value is 0, 1, or -1).
CVMJavaLong CVMlongConstZero(); Follows the lconst_0 bytecode semantics.
CVMJavaLong CVMlongConstOne(); Follows the lconst_1 bytecode semantics.
CVMInt32 CVMlongEq(CVMJavaLong op1, CVMJavaLong op2); Evaluates whether op1 is equal to op2. Return type is CVMBool (value is CVM_TRUE or CVM_FALSE).
CVMInt32 CVMlongEqz(CVMJavaLong op); Evaluates whether op is equal to zero. Return type is CVMBool (value is CVM_TRUE or CVM_FALSE).
CVMInt32 CVMlongGe(CVMJavaLong op1, CVMJavaLong op2); Evaluates whether op1 is greater than or equal to op2. Return type is CVMBool (value is CVM_TRUE or CVM_FALSE).
CVMInt32 CVMlongGez(CVMJavaLong op); Evaluates whether op is greater than or equal to zero. Return type is CVMBool (value is CVM_TRUE or CVM_FALSE).
CVMInt32 CVMlongGt(CVMJavaLong op1, CVMJavaLong op2); Evaluates whether op1 is greater than op2. Return type is CVMBool (value is CVM_TRUE or CVM_FALSE).
CVMInt32 CVMlongLe(CVMJavaLong op1, CVMJavaLong op2); Evaluates whether op1 is less than or equal to op2. Return type is CVMBool (value is CVM_TRUE or CVM_FALSE).
CVMInt32 CVMlongLt(CVMJavaLong op1, CVMJavaLong op2); Evaluates whether op1 is less than op2. Return type is CVMBool (value is CVM_TRUE or CVM_FALSE).
CVMInt32 CVMlongLtz(CVMJavaLong op); Evaluates whether op is less than zero. Return type is CVMBool (value is CVM_TRUE or CVM_FALSE).
CVMInt32 CVMlongNe(CVMJavaLong op1, CVMJavaLong op2); Evaluates whether op1 is not equal to op2. Return type is CVMBool (value is CVM_TRUE or CVM_FALSE).
CVMJavaLong CVMlongNeg(CVMJavaLong op); Returns the negation of op, according to the lneg bytecode semantics.
CVMJavaLong CVMlongNot(CVMJavaLong op); Returns the complement of op according to the lnot bytecode semantics.
CVMJavaLong CVMlongShl(CVMJavaLong op1, CVMJavaInt op2); Returns the signed shift left of op, according to the lshl bytecode semantics.
CVMJavaLong CVMlongShr(CVMJavaLong op1, CVMJavaInt op2); Returns the signed shift right of op, according to the lshr bytecode semantics.
CVMJavaLong CVMlongUshr(CVMJavaLong op1, CVMJavaInt op2); Returns the unsigned shift right of op, according to the lushr bytecode semantics.

Double Functions

Declaration Description
CVMJavaFloat CVMdouble2Float(CVMJavaDouble val); Converts the double val to a float, according to the d2f bytecode semantics.
CVMJavaInt CVMdouble2Int(CVMJavaDouble val); Converts the double val to an int, according to the d2i bytecode semantics.
CVMJavaDouble CVMdoubleAdd(CVMJavaDouble op1, CVMJavaDouble op2); Adds op1 to op2 according to the dadd bytecode semantics.
CVMInt32 CVMdoubleCompare(CVMJavaDouble op1, CVMJavaDouble op2, CVMInt32 direction); Compares op1 and op2, according to the dcmpl (direction is -1) or dcmpg (direction is 1) bytecode semantics.
CVMJavaDouble CVMdoubleConstOne(); Follows the dconst_1 bytecode semantics.
CVMJavaDouble CVMdoubleConstZero(); Follows the dconst_0 bytecode semantics.
CVMJavaDouble CVMdoubleDiv(CVMJavaDouble op1, CVMJavaDouble op2); Follows the ddiv bytecode semantics.
CVMJavaDouble CVMdoubleMul(CVMJavaDouble op1, CVMJavaDouble op2); Follows the dmul bytecode semantics.
CVMJavaDouble CVMdoubleNeg(CVMJavaDouble op); Returns the negation of op, according to the dneg bytecode semantics.
CVMJavaDouble CVMdoubleRem(CVMJavaDouble op1, CVMJavaDouble op2); Follows the drem bytecode semantics.
CVMJavaDouble CVMdoubleSub(CVMJavaDouble op1, CVMJavaDouble op2); Follows the dsub bytecode semantics.
CVMJavaDouble CVMint2Double(CVMJavaInt val); Converts int to double, according to the i2d bytecode semantics.

endianness.h

The file src/share/javavm/include/porting/endianness.h specifies the following definition requirements.
 
Declaration Description
CVM_DOUBLE_ENDIANNESS Indicates whether the platform uses the big endian convention or the little endian convention for the double data types. Set this to CVM_LITTLE_ENDIAN or CVM_BIG_ENDIAN as appropriate for your platform.
CVM_ENDIANNESS Indicates whether the platform uses the big endian convention or the little endian convention. Set this to CVM_LITTLE_ENDIAN or CVM_BIG_ENDIAN as appropriate for your platform.

float.h

The file src/share/javavm/include/porting/float.h specifies the following definition requirements.
 
Declaration Description
CVMJavaDouble CVMfloat2Double(CVMJavaFloat op); Converts float to double, according to the f2d bytecode semantics.
CVMJavaInt CVMfloat2Int(CVMJavaFloat op); Converts float to int, according to the f2i bytecode semantics.
extern CVMJavaLong CVMfloat2Long(CVMJavaFloat op); Converts float to long, according to the f2l bytecode semantics.
CVMJavaFloat CVMfloatAdd(CVMJavaFloat op1, CVMJavaFloat op2); Follows the fadd bytecode semantics.
CVMInt32 CVMfloatCompare(CVMJavaFloat op1, CVMJavaFloat op2, CVMInt32 direction); Compares op1 and op2, according to the fcmpl (direction is -1) or fcmpg (direction is 1) bytecode semantics.
CVMJavaFloat CVMfloatDiv(CVMJavaFloat op1, CVMJavaFloat op2); Follows the fdiv bytecode semantics.
CVMJavaFloat CVMfloatMul(CVMJavaFloat op1, CVMJavaFloat op2); Follows the fmul bytecode semantics.
CVMJavaFloat CVMfloatNeg(CVMJavaFloat op1, CVMJavaFloat op2); Follows the fneg bytecode semantics.
CVMJavaFloat CVMfloatRem(CVMJavaFloat op1, CVMJavaFloat op2); Follows the frem bytecode semantics.
CVMJavaFloat CVMfloatSub(CVMJavaFloat op1, CVMJavaFloat op2); Follows the fsub bytecode semantics.

globals.h

The file src/share/javavm/include/porting/globals.h specifies the following definition requirements.
 
Declaration Description
extern void CVMdestroyStaticState(); Destroys platform-specific per-address-space static state.
extern void CVMdestroyVMTargetGlobalState(CVMTargetGlobalState *); Destroys platform-specific per-VM global state.
extern void CVMinitStaticState(); Initializes platform-specific per-address-space static state.
extern void CVMinitVMTargetGlobalState(CVMTargetGlobalState *); Initializes platform-specific per-VM global state.
struct CVMTargetGlobalState {}; Defines the platform-specific global state.

int.h

The file src/share/javavm/include/porting/int.h specifies the following definition requirements.
 
Declaration Description
CVMJavaInt CVMintAdd(CVMJavaInt op1, CVMJavaInt op2); Adds two integers according to the iadd bytecode semantics.
CVMJavaInt CVMintSub(CVMJavaInt op1, CVMJavaInt op2); Subtracts two integers according to the isub bytecode semantics.
CVMJavaInt CVMintMul(CVMJavaInt op1, CVMJavaInt op2); Multiplies two integers according to the imul bytecode semantics.
CVMJavaInt CVMintDiv(CVMJavaInt op1, CVMJavaInt op2); Divides two integers according to the idiv bytecode semantics.
CVMJavaInt CVMintRem(CVMJavaInt op1, CVMJavaInt op2); Returns the remainder of the division of two integers according to the irem bytecode semantics.
CVMJavaInt CVMintAND(CVMJavaInt op1, CVMJavaInt op2); ANDs two integers according to the iand bytecode semantics.
CVMJavaInt CVMintOr(CVMJavaInt op1, CVMJavaInt op2); ORs two integers according to the ior bytecode semantics.
CVMJavaInt CVMintXor(CVMJavaInt op1, CVMJavaInt op2); XORs two integers according to the ixor bytecode semantics.
CVMJavaInt CVMintNeg(CVMJavaInt op); Negates the specified integer according to the ineg bytecode semantics.
CVMJavaInt CVMintUshr(CVMJavaInt op1, CVMJavaInt num); Performs an unsigned right shift according to the iushr bytecode semantics.
CVMJavaInt CVMintShl(CVMJavaInt op1, CVMJavaInt num); Performs an left shift according to the ishl bytecode semantics.
CVMJavaInt CVMintShr(CVMJavaInt op1, CVMJavaInt num); Performs an right shift according to the iushr bytecode semantics.
CVMJavaInt CVMintNeg(CVMJavaInt op); Performs a negation operation according to the ineg bytecode semantics.
CVMJavaFloat CVMint2Float(CVMJavaInt val); Converts an integer to a float according to the i2f bytecode semantics.
CVMJavaByte CVMint2Byte(CVMJavaInt val); Converts an integer to a byte according to the i2b bytecode semantics.
CVMJavaChar CVMint2Char(CVMJavaInt val); Converts an integer to a char according to the i2c bytecode semantics.
CVMJavaShort CVMint2Short(CVMJavaInt val); Converts an integer to a short according to the i2s bytecode semantics.
CVMUint16 CVMgetUint16(CVMconst CVMUint8 *ptr); Returns an 8 bit unsigned integer as a 16 bit unsigned integer.
CVMUint32 CVMgetUint32(CVMconst CVMUint8 *ptr); Returns an 8 bit unsigned integer as a 32 bit unsigned integer.
CVMInt16 CVMgetInt16(CVMconst CVMUint8 *ptr); Returns an 8 bit unsigned integer as a 16 bit signed integer.
CVMInt32 CVMgetInt32(CVMconst CVMUint8 *ptr); Returns an 8 bit unsigned integer as a 32 bit signed integer.
CVMInt32 CVMgetAlignedInt32(ptr_) (constCVMUint8 *ptr); Macro for accessing word aligned big-endian integers. A little-endian platform like x86 would need to make sure the bytes get reversed.

io.h

The file src/share/javavm/include/porting/io.h specifies the following definition requirements.
 
Declaration Description
CVMInt32 CVMioGetLastErrorString(char *buf, int len); Gets the last error string using a caller supplied buffer.
char* CVMioReturnLastErrorString(); Returns the last error string without any caller buffers.
char * CVMioNativePath(char *path); Converts a pathname into native format. This function does syntactic cleanup, such as removing redundant separator characters. It modifies the specified pathname string in place.
CVMInt32 CVMioFileType(const char *path); Returns the file type of the specified file path. Valid values are:
CVM_IO_FILETYPE_REGULAR (0)
CVM_IO_FILETYPE_DIRECTORY (1)
CVM_IO_FILETYPE_OTHER (2)
CVM_IO_FILETYPE_EEXIST (-100)
CVM_IO_FILETYPE_ERR (-1)
CVMInt32 CVMioOpen(const char *name, CVMInt32 openMode, CVMInt32 filePerm); Opens a file descriptor. This function returns a negative error code on error, or if the file opened is a directory. The return value is a non-negative integer that is the file descriptor on success. Valid values are:
CVM_IO_FILETYPE_REGULAR (0)
CVM_IO_FILETYPE_DIRECTORY (1)
CVM_IO_FILETYPE_OTHER (2)
CVM_IO_FILETYPE_EEXIST (-100)
CVM_IO_FILETYPE_ERR (-1)
CVMInt32 CVMioClose(CVMInt32 fd); Closes a file descriptor fd. This function returns -1 on error, and 0 on success.
CVMInt64 CVMioSeek(CVMInt32 fd, CVMInt64 offset, CVMInt32 whence); Moves the file pointer to where the next read from the file will come from.
fd -- the file pointer to move.
offset -- the number of bytes to move the file pointer by.
whence -- the start from where to move the file pointer.
CVMInt32 CVMioSetLength(CVMInt32 fd, CVMInt64 length); Sets the length of the file associated with the given descriptor to the given length. If the new length is longer than the current length, then the file is extended; the contents of the extended portion are not defined.
fd -- the file descriptor.
length -- the new file length.
CVMInt32 CVMioSync(CVMInt32 fd); Synchronizes the file descriptor's in memory state with that of the physical device. Returns -1 on error, 0 for success.
fd - the file descriptor.
CVMInt32 CVMioAvailable(CVMInt32 fd, CVMInt64 *bytes); Returns the number of bytes available for reading from a given file descriptor.
fd -- the file descriptor.
bytes -- the number of bytes to read.
size_t CVMioRead(CVMInt32 fd, void *buf, CVMUint32 nBytes); Reads data from a file descriptor into an untyped buffer. This function returns -1 on error, 0 on success.
fd -- the file descriptor to read from.
buf -- the buffer to put the data into.
nbytes -- the number of bytes to read.
size_t CVMioWrite(CVMInt32 fd, const void *buf, CVMUint32 nBytes); Writes data from the specified buffer to a file descriptor. This function returns -1 on error, 0 on success.
fd -- the file descriptor to write to.
buf -- the buffer to fetch the data.
nbytes -- the number of bytes to write.
CVMInt32 CVMioFileSizeFD(CVMInt32 fd, CVMInt64 *size); Returns the file size in bytes.
fd -- the file descriptor.
bytes -- the number of bytes.

jni.h

The file src/share/javavm/include/porting/jni.h specifies the following definition requirements.
 
Declaration Description
CVMInt32 CVMjniInvokeNative(void *env, void *nativeCode, CVMUint32 *args, CVMUint32 *terseSig, CVMInt32 argsSize, void *classObject, CVMJNIReturnValue *returnValue); Translates the "Java" calling convention into the "C" calling convention used in native methods. The Java VM passes all the arguments in the Java stack, and places the results there as well. Arguments are copied into the C stack (or registers), and return values are placed into the CVMJNIReturnValue structure pointed to by "returnValue". Upon return, the Java VM copies the result from there to the Java stack.

Arguments

The following table describes the CVMjniInvokeNative arguments.
Argument Description
env Pointer to the JNI environment, which should be passed unmodified as the first argument to the native method.
nativeCode Pointer to the "real" native method function.
args Pointer to the Java stack, where all the arguments are stored (as args[0], args[1], etc.). The Java stack slot for a single-word integer and float arguments can be read as a jint and jfloat, respectively, and passed to the native method unchanged. For double-word arguments, a jlong or jdouble value should be read from the current two stack slots using the same method as CVMjvm2Lond and CVMjvm2Double, respectively. For an object argument, a NULL (0) value should be passed if the stack slot contains 0, otherwise the address of the stack slot should be passed as a jobject to the native method.
terseSig The encoded "terse" signature of the native method. It contains 32-bit words containing 8 4-bit nibbles each. Each nibble contains a signature parsing code or the type code of an argument in the native method signature:

0x00 RELOAD
0x01 END
0x02 void ("V") (never seen in an argument, only in a return value)
0x03 int ("I")
0x04 short ("S")
0x05 char ("C")
0x06 long ("J")
0x07 byte ("B")
0x08 float ("F")
0x09 double ("D")
0x0A boolean ("Z")
0x0B object ("Z")

The return type comes first, then the arguments, followed by an END code. Nibbles are read from the least-significant bits of the word first. Most signatures fit in a single word. For longer signatures, multiple words are used. A RELOAD nibble is used as an escape code to signal that the next word is a pointer to a new terse signature word, which allows chaining of words for longer signatures.
argsSize The total size (in 32-bit words) of the arguments on the Java stack. Note that the Java stack does not have any alignment requirement, and stores all arguments consecutively in words and double words. The argument size includes the "this" pointer for non-static methods.
classObject NULL (0) for non-static methods, or a jclass for static methods. Non-static native methods receive an object reference as the second argument (which is simply the address of args[0]). The "real" method arguments to non-static methods begin at args[1]. Static native methods receive a class reference ("classObject") as the second argument.
returnValue The return value of the native method is placed in returnValue->i for word-sized results, or returnValue->64 for double-word-sized results, according to the following values:

jdouble - CVMdouble2Jvm to returnValue->64
jlong - CVMlong2Jvm to returnValue->64
jint - copy to returnValue->i
jbyte - CVMbyte2Int to returnValue->i
jchar - CVMchar2Int to returnValue->i
jshort - CVMshort2Int to returnValue->i
jfloat - CVMfloat2Int to returnValue->f
jobject - CVMobject2Int to returnValue->o

Return Value

The CVMJNIReturnValue union is used to return the jni method result. It is passed to CVMjniInvokeNative, which stores the result in the union after the java method returns to CVMjniInvokeNative.

typedef union {
    CVMInt32 i;
    CVMJavaFloat f;
    CVMUint32 v64[2];
    void *o;
} CVMJNIReturnValue;

Function return value

The return value of CVMjniInvokeNative is:

linker.h

The file src/share/javavm/include/porting/linker.h specifies the following definition requirements.

These routines look very similar to the dynamic linking facilities on Solaris. However, on VxWorks, there is currently no notion of a local symbol table. Therefore, symbol lookup is slow on VxWorks as we have to iterate through the entire system symbol table every time. It is required by the Java libraries that sit above these routines that a notion of local symbol namespaces be maintained.

On VxWorks, these routines require three libraries to be built into your project if they are not already:

Declaration Description
void * CVMdynlinkOpen(const void *absolutePathName); Dynamically links in a shared object. This takes a platform-dependent, absolute pathname to the shared object. Calling code is responsible for constructing this name.

Returns an abstract "handle" to the shared object which must be used for later symbol queries, or NULL if an error occurred.
void * CVMdynlinkSym(void *dsoHandle, const void *name); Finds a function or data pointer in an already-opened shared object. Takes the dynamic shared object handle and a platform-dependent symbol as an argument (typically, but not always, a char*). On systems that support it, this can be a global symbol table lookup; otherwise an internal list of shared objects will have to be searched for the symbol. This function is also responsible for adding any necessary "decorations" to the symbol name before doing the lookup.
void * CVMdynlinkClose(void *dsoHandle); Closes a dynamic shared object. This should probably have the semantics that its symbols are unloaded, but VxWorks, at least, doesn't currently appear to have a module unloading facility. This function takes the dynamic shared object handle from CVMdynlinkOpen.
CVMBool CVMdynlinkBuildLibName(void *holder, int holderlen, void *pname, void *fname); This is a Java-specific function that creates a string for the dynamic lib open call by adding the appropriate prefixs and extensions to a filename and the path.
holder - the destination buffer
holderlen - the buffer size in bytes
pname - the directory prefix or NULL
fname - the "base name" of the library.

For example, CVMdynlinkBuildLibName(buf, bufLen, "foo", "bar") might result in a library name of "foo/libbar.so".

All buffers are of a platform-specific data type, but are typically char*. Returns CVM_FALSE if the holder buffer is not big enough.

net.h

The file src/share/javavm/include/porting/net.h specifies the following definition requirements.

Data types

struct sockaddr;
struct protoent *CVMnetGetProtoByName(char *protoName);

Functions

Declaration Description
CVMInt32 CVMnetSocketClose(CVMInt32 fd); Closes the socket associated with the file descriptor. Corresponds to X/Open "close".
CVMInt32 CVMnetSocketShutdown(CVMInt32 fd, CVMInt32 howto); Shuts down either the send, receive, or both sides of a socket, based on the value of howto. Corresponds to X/Open "shutdown".
CVMInt32 CVMnetSocketAvailable(CVMInt32 fd, CVMInt32 *pbytes); Gets the number of bytes available for the given socket for reading and stores the result into the value pointed to by the second argument. The result should satisfy the requirements of java.net.SocketInputStream.available().
CVMInt32 CVMnetConnect(CVMInt32 fd, struct sockaddr *him, CVMInt32 len); Corresponds to X/Open "connect" in <sys/socket.h>.
CVMInt32 CVMnetAccept(CVMInt32 fd, struct sockaddr *him, CVMInt32 *len); Corresponds to X/Open "accept" in <sys/socket.h>.
CVMInt32 CVMnetSendTo(CVMInt32 fd, char *buf, CVMInt32 len, CVMInt32 flags, struct sockaddr *to, CVMInt32 tolen); Corresponds to X/Open "sendto" in <sys/socket.h>.
CVMInt32 CVMnetRecvFrom(CVMInt32 fd, char *buf, CVMInt32 nBytes, CVMInt32 flags, struct sockaddr *from, CVMInt32 *fromlen); Corresponds to X/Open "recvfrom" in <sys/socket.h>.
CVMInt32 CVMnetListen(CVMInt32 fd, CVMInt32 count); Corresponds to X/Open "listen" in <sys/socket.h>.
CVMInt32 CVMnetRecv(CVMInt32 fd, char *buf, CVMInt32 nBytes, CVMInt32 flags); Corresponds to X/Open "recv" in <sys/socket.h>.
CVMInt32 CVMnetSend(CVMInt32 fd, char *buf, CVMInt32 nBytes, CVMInt32 flags); Corresponds to X/Open "send" in <sys/socket.h>.
CVMInt32 CVMnetTimeout(CVMInt32 fd, CVMInt32 timeout); Used to timeout blocking operations, as defined by java.net.SocketOptions.SO_TIMEOUT. Returns immediately if an "accept", "recv", or "recvfrom" operation would succeed without blocking. Otherwise blocks for up to "timeout" milliseconds.

Corresponds to X/Open "poll" in <sys/socket.h> with the "POLLIN" flag set.
CVMInt32 CVMnetSocket(CVMInt32 domain, CVMInt32 type, CVMInt32 protocol); Corresponds to X/Open "socket" in <sys/socket.h>.
CVMInt32 CVMnetSetSockOpt(CVMInt32 fd, CVMInt32 type, CVMInt32 dir, const void *arg, CVMInt32 argSize); Corresponds to X/Open "setsockopt" in <sys/socket.h>.
CVMInt32 CVMnetGetSockOpt(CVMInt32 fd, CVMInt32 proto, CVMInt32 flag, void *in_addr, CVMInt32 *inSize); Corresponds to X/Open "getsockopt" in <sys/socket.h>.
CVMInt32 CVMnetGetSockName(CVMInt32 fd, struct sockaddr *lclAddr, CVMInt32 *lclSize); Corresponds to X/Open "getsockname" in <sys/socket.h>.
CVMInt32 CVMnetGetHostName(char *hostname, CVMInt32 maxlen); Corresponds to X/Open "gethostname" in <sys/socket.h>.
CVMInt32 CVMnetBind(CVMInt32 fd, struct sockaddr *bindAddr, CVMInt32 size); Corresponds to X/Open "bind" in <sys/socket.h>.

path.h

The file src/share/javavm/include/porting/path.h specifies the following definition requirements.

Macros

Declaration Description
CVM_PATH_CLASSFILEEXT Usually "class".
CVM_PATH_CLASSPATH_SEPARATOR Usually ":".
CVM_PATH_CURDIR Usually ".".
CVM_PATH_LOCAL_DIR_SEPARATOR Usually "/".
CVM_PATH_MAXLEN Usually the same as PATH_MAX.

Function

Declaration Description
extern int CVMcanonicalize(char* path,
const char* out, int len);
Changes path to its canonical or simplest explicit form, and places the result in out. For example, this function replaces notation such as "../" in the path name with the explicit path. You can use this function to standardize two paths before comparing them.

sync.h

The file src/share/javavm/include/porting/sync.h specifies the following definition requirements.

Defines

The platform defines the CVM_MICROLOCK_TYPE variable to be one of the following values:

The platform defines the CVM_FASTLOCK_TYPE variable to be one of the following:

The platform must provide definitions for the following opaque structures:

Functions

Declaration Description
extern void CVMmutexSetOwner(CVMThreadID *self,
CVMMutex* m, CVMThreadID *ti);
Locks and unlockes the mutex on behalf of another thread. The result is identical to the thread having called CVMmutexLock itself.
extern void CVMschedLock(void); Locks the scheduler. The current thread will remain running and no other threads in this VM instance can become runnable until the scheduler lock is released.
extern void CVMschedUnlock(void); Releases the scheduler lock acquired by CVMschedLock. Normal thread scheduling will resume.
CVMBool CVMmutexInit(CVMMutex *m); Initializes the given CVMMutex, allocating additional resources if necessary.
void CVMmutexDestroy(CVMMutex *m); Destroys the given CVMMutex, releasing any resources that were previously allocated by CVMMutexInit.
CVMBool CVMmutexTryLock(CVMMutex *m); Attempts to acquire a lock for the given mutex. This call must return immediately and never block. CVM_TRUE is returned if the lock was acquired, Otherwise CVM_FALSE is returned.
void CVMmutLock(CVMMutex *m); Acquires a lock for the given mutex. This call may block. A thread will never attempt to acquire the same mutex more than once, so a counter to keep track of recursive entry is not required.
void CVMmutexUnlock(CVMMutex *m); Releases a lock previously acquired by CVMMutexLock.
void CVMmutexSetOwner(CVMThreadId *self, CVMMutex *m, CVMThreadID *ti); Locks an unlocked mutex on behalf of another thread. The result will be identical to the thread having called CVMMutexLock itself.
CVMBool CVMcondvarInit(CVMCondVar *c, CVMMutex *m); Initializes the given CVMCondVar, allocating additional resources if necessary. The CVMMutex that will be used by any future calls to CVMcondvarWait is also provided, for those platforms that require the mutex for proper condition variable initialization.
void CVMcondvarDestroy(CVMCondVar *c); Destroys the given CVMCondVar, releasing any resources that were previously allocated by CVMcondvarInit.
CVMBool CVMcondvarWait(CVMCondVar* c, CVMMutex *m, CVMJavaLong millis); Performs a timed wait on a condition variable. The mutex is unlocked while the thread blocks and locked again when it wakes up. CVM_FALSE is returned if the operation is interrupted by CVMthreadInterruptWait. This function is used to implement Object.wait, therefore the atomicity of unlocking the lock and checking for notification or an interrupt must follow the rules described by Object.wait. A timeout of 0 ms is treated as infinity, or "wait forever".
void CVMcondvarNotify(CVMCondVar *c); Wakes up a thread waiting on the given CVMCondVar, as defined by the semantics of Object.notify.
void CVMcondvarNotifyAll(CVMCondVar *c); Wakes up all threads waiting on the given CVMCondVar, as defined by the semantics of Object.notifyAll.

Advanced Functions

See "Advanced Platform Features" for information on when it is necessary to implement the following functions.

Declaration Description
void CVMschedLock(void); Locks the scheduler. The current thread will remain running and no other threads in this VM instance can become runnable until the scheduler lock is released.
void CVMschedUnlock(void); Releases the scheduler lock acquired by CVMschedLock. Normal thread scheduling will resume.
CVMint32 CVMatomicCompareAndSwap(volatile CVMUint32 *addr, CVMUint32 new, CVMUint32 old); Sets a word (conditionally) in memory, returning the previous value. The new value "new" is written to address "addr" only if the current value matches the value given by "old".
CVMint32 CVMatomicSwap(volatile CVMUint32 *addr, CVMUint32 new); Atomically sets a word in memory, returning the previous value.
CVMUint32 CVMatomicIncrement(CVMUint32 *addr); Atomically increments a word in memory, returning the new value.
CVMUint32 CVMatomicDecrement(CVMUint32 *addr); Atomically decrements a word in memory, returning the new value.

system.h

The file src/share/javavm/include/porting/system.h specifies the following definition requirement.
 
Declaration Description
void CVMhalt(CVMInt32 status); Forcibly terminate the VM with the given status, as defined by java.lang.Runtime.halt(). The function should never return.
void CVMSystemPanic(const char *msg); Something bad has happened, even in a non-debug VM. Prints the specified msg on an appropriate console and halts the computation in a system-dependent manner. It may cause either a core dump or a suspended thread. If CVM_DEBUG is defined, then call CVMassertHook first for ease of debuging.

threads.h

A reference implementation of thread functions, based on the POSIX threads library, is provided in src/porting/posix/posix_threads_md.c.

The file src/share/javavm/include/porting/threads.h specifies the following definition requirements.
 

Macros

The platform must provide definitions for the following opaque structure:

The following macros are used in C stack check codes for various recursive functions.

Declaration Description
CVM_REDZONE_ILOOP Stack space required for interpreter loop in CVMgcUnsafeExecuteJavaMethod().
CVM_REDZONE_CVMclassLookupFromClassLoader Stack space required for class loading in a deep class lookup hierarchy in CVMclassLookupFromClassLoader().
CVM_REDZONE_CVMclassLink Stack space required for class linking in CVMclassLink().
CVM_REDZONE_CVMclassScan Stack space required for traversing the scannable stateof one class by the garbage collector in CVMclassScan().
CVM_REDZONE_CVMimplementsInterface Stack space required for checking whether a non-array class is an interface type class in CVMimplementsInterface().
CVM_REDZONE_CVMCstackCVMpc2string Stack space required for building a formatted string %P format of PC information for console I/O in CVMformatStringVaList().
CVM_REDZONE_CVMCstackCVMID_objectGetClassAndHashSafe Stack space required for building a formatted string %I format of class name information for console I/O in CVMformatStringVaList().
CVM_REDZONE_CVMCstackmerge_fullinfo_to_types Stack space required for class verifier to do type merging between two object types or two arrays of object types in merge_fullinfo_types().
CVM_REDZONE_CVMsignalErrorVaList Stack space required for signaling an exception in CVMsignalErrorVaList()..

Recursive functions

Recursive functions that have a C stack check are listed below:

C stack redzones used in the recursive functions are defined as:

Functions

Declaration Description
CVMInt32 CVMthreadCreate(CVMSize stackSize, CVMInt16 priority, void (*func)(void *), void *arg); Creates a new, runnable thread with the given Java priority and C stacksize. The new thread must call func(arg) upon creation and clean up after itself and exit when func() returns.
void CVMthreadYield(void); Yields to other threads, as defined by Thread.yield().
void CVMthreadSetPriority(CVMThreadID *thread, CVMInt32 prio); Sets the priority of a thread to the given value, mapping the Java priority to an appropriate value.
void CVMthreadSuspend(CVMThreadID *thread); Suspends a thread, according to the semantics of Thread.suspend() (which has been deprecated) or JVMDI SuspendThread().
void CVMthreadResume(CVMThreadID *thread); Resumes a suspended thread, according to the semantics of Thread.resume() (which has been deprecated) or JVMDI SuspendThread().
void CVMthreadAttach(CVMThreadID *self); Associates a CVMThreadID pointer with the current thread.
void CVMthreadDetach(CVMThreadID *self); Removes the CVMThreadID pointer from the current thread.
CVMThreadID * CVMthreadSelf(void); Returns the CVMThreadID pointer previously associated with the current thread by CVMthreadAttach, or NULL if CVMthreadAttach has not been called yet or CVMthreadDetach has been called.
void CVMthreadInterruptWait(CVMThreadID *thread); Breaks the given thread out of a CVMcondvarWait call, causing that call to return CVM_FALSE, signaling that the wait was interrupted. If the given thread is not currently in CVMcondvarWait, the request is remembered until CVMcondvarWait is called, which immediately return CVM_FALSE.
CVMBool CVMthreadIsInterrupted(CVMThreadID *thread, CVMBool clearInterrupted); Returns the current interrupted state for the thread. If clearInterrupted is true, cancel any previous interrupt requests made by CVMthreadInterruptWait.
Note: Currently, we only set clearInterrupted when thread is the current thread.
CVMBool CVMthreadStackCheck(CVMThreadID *self, CVMUint32 redZone); Checks for a stack overflow. Returns CVM_TRUE if the stack of the current thread has at least redZone bytes free, CVM_FALSE otherwise.

time.h

The file src/share/javavm/include/porting/time.h specifies the following definition requirement.
 
Declaration Description
CVMInt64 CVMtimeMillis(void); Returns the current time in milliseconds, as defined by System.currentTimeMillis.

vm-defs.h

The file src/share/javavm/include/porting/vm-defs.h specifies the following definition requirements.

The following macros are defined for convenience:

  #define CVM_STRUCT_TYPEDEF(structName) typedef struct structName structName
  #define CVM_UNION_TYPEDEF(structName)  typedef union structName structName
  #define CVM_ENUM_TYPEDEF(structName)   typedef enum structName structName

The following are C types corresponding to Java types:

  typedef CVMInt8    CVMJavaByte;
  typedef CVMInt16   CVMJavaShort;
  typedef CVMUint16  CVMJavaChar;
  typedef CVMUint8   CVMJavaBoolean;
  typedef CVMInt32   CVMJavaInt;
  typedef CVMfloat32 CVMJavaFloat;
  typedef CVMInt64   CVMJavaLong;
  typedef CVMfloat64 CVMJavaDouble;

Forward declarations defined by the porting layer:

  CVM_STRUCT_TYPEDEF(CVMMutex);
  CVM_STRUCT_TYPEDEF(CVMCondVar);
  CVM_STRUCT_TYPEDEF(CVMThreadID);
  CVM_STRUCT_TYPEDEF(CVMTargetGlobalState);

Contents | Prev | Next
Copyright ) 2000 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: jcp-cdc-comments@eng.sun.com
Sun