Index: trunk/vm/include/jit_import_rt.h =================================================================== --- trunk/vm/include/jit_import_rt.h (revision 487512) +++ trunk/vm/include/jit_import_rt.h (working copy) @@ -14,16 +14,12 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -/** - * @author Intel, Alexei Fedotov - * @version $Revision: 1.1.2.1.4.3 $ - */ +/** + * @file + * These are the functions that a JIT built as a DLL may call. + */ -// -// These are the functions that a JIT built as a DLL may call. -// - #ifndef _JIT_IMPORT_RT_H #define _JIT_IMPORT_RT_H @@ -34,38 +30,44 @@ #ifdef __cplusplus extern "C" { #endif - - -/////////////////////////////////////////////////////// -// begin root set enumeration functions. - - -// Enumerate a root entry. The argument is a pointer to the memory -// location that contains a managed reference. The GC may update -// this location if the object pointed to has been moved during -// collection. +/** + * Begin root set enumeration functions. + * + * Enumerate a root entry. The argument is a pointer to the memory + * location that contains a managed reference. The GC may update + * this location if the object pointed to has been moved during + * collection. + */ VMEXPORT void vm_enumerate_root_reference(Managed_Object_Handle *ref, Boolean is_pinned); -// Resembles vm_enumerate_root_reference() but is passed the address of -// a slot containing a compressed reference. +/** + * Resembles vm_enumerate_root_reference(), but is passed the + * address of a slot containing a compressed reference. + */ VMEXPORT void vm_enumerate_compressed_root_reference(uint32 *ref, Boolean is_pinned); -// Like vm_enumerate_root_reference() but the first argument points -// to a location that contains a pointer to an inside of an object. +/** + * Like vm_enumerate_root_reference(), but the first argument + * points to a location that contains a pointer to an inside of an object. + */ VMEXPORT void vm_enumerate_root_interior_pointer(void **slot, int offset, Boolean is_pinned); -// The JIT enumerates a managed pointer. The pointer can be declared as -// pinned. The pointer can point to the managed heap or any other area -// where data can be stored: stack or static fields. It is the responsibility -// of the runtime system to ignore pointers that are not in the managed heap. +/** + * The JIT enumerates a managed pointer. The pointer can be declared as + * pinned. The pointer can point to the managed heap or any other area + * where data can be stored: stack or static fields. It is the responsibility + * of the runtime system to ignore pointers that are not in the managed heap. + */ VMEXPORT void vm_enumerate_root_pointer(void **ptr, Boolean is_pinned); -// end root set enumeration functions. -/////////////////////////////////////////////////////// +/** + * End root set enumeration functions. + */ -/////////////////////////////////////////////////////// -//enumerates alive references for owned monitor calculation +/** + * Enumerates alive references for owned monitor calculation. + */ VMEXPORT void vm_check_if_monitor(void **reference, void **base_reference, Index: trunk/vm/include/jit_runtime_support.h =================================================================== --- trunk/vm/include/jit_runtime_support.h (revision 487512) +++ trunk/vm/include/jit_runtime_support.h (working copy) @@ -14,31 +14,24 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -/** - * @author Intel, Evgueni Brevnov, Ivan Volosyuk - * @version $Revision: 1.1.2.2.4.4 $ - */ - - - #ifndef _JIT_RUNTIME_SUPPORT_H_ #define _JIT_RUNTIME_SUPPORT_H_ #include "open/types.h" -// -// This is a complete set of functions used by the code generated by the JIT. -// The address of a function is obtained from the VM by invoking the -// function vm_get_rt_support_addr (see below). -// +/** + * This is a complete set of functions used by the code generated by the JIT. + * The address of a function is obtained from the VM by invoking the + * function vm_get_rt_support_addr (see below). + * + * We should also note which exceptions can be thrown by each + * of those function. + * + * If changes are made to enum VM_RT_SUPPORT below, the list of + * JIT support functions in vm_stats.cpp must also be changed. + */ -// We should also note which exceptions can be thrown by each -// of those function. - -// If changes are made to enum VM_RT_SUPPORT below, the list of JIT support functions in vm_stats.cpp must also be changed. - - #ifdef __cplusplus extern "C" { #endif // __cplusplus @@ -46,378 +39,459 @@ typedef enum VM_RT_SUPPORT { - ////////////////////////////////////////////////////////////////////////// - // Object creation routines - ////////////////////////////////////////////////////////////////////////// +/** + * Object creation routines. + */ VM_RT_NEW_RESOLVED_USING_VTABLE_AND_SIZE=100, - // Arguments: - // - Size of the instance to be created - // - Allocation_Handle for the class whose instance we want to create - // Return value: - // - Reference to the new object - // - // Like VM_RT_NEW_VECTOR_USING_VTABLE, allocates a new object of a class, but also takes a - // size argument. The size can be obtained using class_get_boxed_data_size(Class_Handle). - // This function should be used for classes which inherit the finalize method - // of java.lang.Object. +/** + * @param The parameters are the following: + * \arg Size of the instance to be created + * \arg Allocation_Handle for the class whose instance we want to create + * + * @return Reference to the new object. + * + * Like VM_RT_NEW_VECTOR_USING_VTABLE, allocates a new object of + * a class, but also takes a size argument. The size can be obtained using + * class_get_boxed_data_size(Class_Handle). + * This function should be used for classes which inherit the finalize method + * of java.lang.Object. + */ VM_RT_NEW_VECTOR_USING_VTABLE=101, - // Arguments: - // - Allocation_Handle for the vector class - // - Vector length - // Return value: - // - Reference to the new object - // - // Like VM_RT_NEW_VECTOR. creates a vector (zero-based, one dimensional array) of the given type, - // but takes a Allocation_Handle instead of a Class_Handle. - +/** + * @param The parameters are the following: + * \arg Allocation_Handle for the vector class + * \arg Vector length + * + * @return Reference to the new object. + * + * Like VM_RT_NEW_VECTOR creates a vector + * (zero-based, one dimensional array) of the given type, + * but takes a Allocation_Handle instead of a + * Class_Handle. + */ VM_RT_MULTIANEWARRAY_RESOLVED=102, - // There is a variable # of arguments: - // - Class handle - // - Number of dimensions - // - Count_n - // - ... - // - Count_1 - // Return value: - // - Reference to the new object - // - // This is __cdecl function and the caller must pop the arguments. - // Create a multidimensional Java array - // + /** + * There is a variable # of arguments: + * \arg Class handle + * \arg Number of dimensions + * \arg Count_n + * \arg ... + * \arg Count_1 + * + * @return Reference to the new object. + * + * This is __cdecl function and the caller must pop the arguments. + * Create a multidimensional Java array. + */ VM_RT_LDC_STRING=103, - // Arguments: - // - Const pool index pointing to a CONSTANT_Class. - // - Class handle of the class owning the const pool - // Return value: - // - Reference to the String object. - // - // Returns a reference to the const string represented by an entry in the - // const pool. +/** + * @param The parameters are the following: + * \arg Const pool index pointing to a CONSTANT_Class. + * \arg Class handle of the class owning the const pool + * + * @return \arg Reference to the String object. + * \arg Reference to the const string represented by an entry in the + * const pool. + */ +///// +// Exception throwing routines +///// - - ////////////////////////////////////////////////////////////////////////// - // Exception throwing routines - ////////////////////////////////////////////////////////////////////////// - VM_RT_THROW=200, - // Arguments: - // - Object reference - // Return value: none. - // - // The only argument is a reference to the exception to be thrown. - // Throw the exception without modifying the stack trace associated - // with the exception object. This function is appropriate for the - // JVML athrow instruction. - // This function never returns. +/** + * @param Object reference + * + * @return None. + * + * The only argument is a reference to the exception to be thrown. + * Throw the exception without modifying the stack trace associated + * with the exception object. This function is appropriate for the + * JVML athrow instruction. + * This function never returns. + */ VM_RT_THROW_SET_STACK_TRACE=210, - // Arguments: - // - Object reference - // Return value: none. - // - // The only argument is a reference to the exception to be thrown. - // Throw the exception and set the stack trace associated - // with the exception object. This function is appropriate for the - // CIL throw instruction. - // This function never returns. + + +/** + * @param Object reference. + * + * @return None. + * + * The only argument is a reference to the exception to be thrown. + * Throw the exception and set the stack trace associated + * with the exception object. This function is appropriate for the + * CIL throw instruction. + * + *This function never returns. + */ - VM_RT_THROW_LAZY=201, - // Arguments: - // - Method handle - // - ... - // - arg 2 - // - arg 1 - // - Class handle - // Return value: none. - // - // The arguments to the constructor are pushed the same way they would have - // been pushed to invoke the constructor, except that the (non-existing) - // this pointer is replaced with the class handle of the exception. - // The method handle representing the constructor is pushed last. - // - // This function never returns. +/** + * @param The parameters are the following: + * \arg Method handle + * \arg ... + * \arg arg 2 + * \arg arg 1 + * \arg Class handle + * + * @return None. + * + * The arguments to the constructor are pushed the same way they would have + * been pushed to invoke the constructor, except that the (non-existing) + * this pointer is replaced with the class handle of the exception. + * The method handle representing the constructor is pushed last. + * + * This function never returns. + */ VM_RT_IDX_OUT_OF_BOUNDS=202, - // Arguments: none - // Return value: none. - // - // Throw the java/lang/ArrayIndexOutOfBoundsException - // This function never returns. - + +/** + * @param none + * + * @return None. + * + * Throw the java/lang/ArrayIndexOutOfBoundsException. + * + * This function never returns. + */ VM_RT_NULL_PTR_EXCEPTION=203, - // Arguments: none - // Return value: none. - // - // Throw the java/lang/NullPointerException - // This function never returns. - + +/** + * @param none + * + * @return None. + * + * Throw the java/lang/NullPointerException + * + * This function never returns. + */ VM_RT_DIVIDE_BY_ZERO_EXCEPTION=204, - // Arguments: none - // Return value: none. - // - // Throw the java/lang/ArithmeticException - // This function never returns. + +/** + * @param none + * + * @return None. + * + * Throw the java/lang/ArithmeticException. + * + * This function never returns. + */ VM_RT_ARRAY_STORE_EXCEPTION=205, - // Arguments: none - // Return value: none. - // - // Throw the java/lang/ArrayStoreException - // This function never returns. + +/** + * @param none + * + * @return None. + * + * Throw the java/lang/ArrayStoreException. + * + * This function never returns. + */ VM_RT_THROW_LINKING_EXCEPTION=206, - // Arguments: - // - Const pool index. - // - Class handle of the class owning the const pool. - // - Loader exception returned by the VM. - // Return value: none. - // - // Throws a linking exception reported by the VM at compile-time. +/** + * @param The parameters are the following: + * \arg Const pool index + * \arg Class handle of the class owning the const pool + * \arg Loader exception returned by the VM + * + * @return None. + * + * Throws a linking exception reported by the VM at compile-time. + */ + //// + // Synchronization routines + //// - ////////////////////////////////////////////////////////////////////////// - // Synchronization routines - ////////////////////////////////////////////////////////////////////////// - VM_RT_MONITOR_ENTER=300, - // Arguments: - // - Object - // Return value: none. - // - // Acquire the monitor associated with the object. - // Throw java/lang/NullPointerException if the argument is null. - +/** + * @param Object + * + * @return None. + * + * Acquire the monitor associated with the object. + * Throw java/lang/NullPointerException, if the argument is null. + */ VM_RT_MONITOR_ENTER_NON_NULL=304, - // Arguments: - // - Object - // Return value: none. - // - // Acquire the monitor associated with the object. - // This function is identical to VM_RT_MONITOR_ENTER except that it - // assumes that the argument is non-null. Passing a null argument - // will result in undefined behavior. - + /** + * @param Object + * + * @return None. + * + * Acquire the monitor associated with the object. + * This function is identical to VM_RT_MONITOR_ENTER except that it + * assumes that the argument is non-null. Passing a null argument + * will result in undefined behavior. + */ VM_RT_MONITOR_EXIT=301, - // Arguments: - // - Object - // Return value: none. - // - // Release the monitor associated with the object. - // Throw java/lang/NullPointerException if the argument is null. - // Throw java/lang/IllegalMonitorStateException if the current thread - // is not the owner of the lock. - +/** + * @param Object + * + * @return None. + * + * Release the monitor associated with the object. + * Throw java/lang/NullPointerException, if the argument is null. + * Throw java/lang/IllegalMonitorStateException, if the current + * thread is not the owner of the lock. + */ VM_RT_MONITOR_EXIT_NON_NULL=305, - // Arguments: - // - Object - // Return value: none. - // - // Release the monitor associated with the object. - // This function is identical to VM_RT_MONITOR_EXIT except that it - // assumes that the argument is non-null. Passing a null argument - // will result in undefined behavior. - // Throw java/lang/IllegalMonitorStateException if the current thread - // is not the owner of the lock. - + +/** + * @param Object + * + * @return None. + * + * Release the monitor associated with the object. + * This function is identical to VM_RT_MONITOR_EXIT except that it + * assumes that the argument is non-null. Passing a null argument + * will result in undefined behavior. + * Throw java/lang/IllegalMonitorStateException, if the current thread + * is not the owner of the lock. + */ VM_RT_MONITOR_ENTER_STATIC=302, - // Arguments: - // - Class handle - // Return value: none. - // - // Acquire the monitor associated with the class passed as the argument. - +/** + * @param Class handle + * + * @return None. + * + * Acquire the monitor associated with the class passed as the argument. + */ VM_RT_MONITOR_EXIT_STATIC=303, - // Arguments: - // - Class handle - // Return value: none. - // - // Release the monitor associated with the class passed as the argument. - // Throw java/lang/IllegalMonitorStateException if the current thread - // is not the owner of the lock. +/** + * @param Class handle + * + * @return None. + * + * Release the monitor associated with the class passed as the argument. + * Throw java/lang/IllegalMonitorStateException, if the current thread + * is not the owner of the lock. + */ +//// +// Type access routines +//// - - - ////////////////////////////////////////////////////////////////////////// - // Type access routines - ////////////////////////////////////////////////////////////////////////// - VM_RT_CHECKCAST=400, - // Arguments: - // - Object - // - Class - // Return value: - // - Object - // - // If object can't be cast to class, throw ClassCastException +/** + * @param The parameters are the following: + * \arg Object + * \arg Class + * + * @return Object. + * + * If object can't be cast to class, throw ClassCastException + */ - VM_RT_INSTANCEOF=401, - // Arguments: - // - Object - // - Class - // Return value: - // - 1 if object is not null and can be cast to class - // - 0 otherwise - +/** + * @param The parameters are the following: + * \arg Object + * \arg Class + * + * @return 1 if object is not null and can be cast to class; + * 0 otherwise + */ VM_RT_AASTORE=402, - // Arguments: - // - Element - // - Index - // - Array - // Return value: none. - // - // Store a reference element into into an array. - +/** + * @param The parameters are the following: + * \arg Element + * \arg Index + * \arg Array + * + * @return None. + * + * Store a reference element into into an array. + */ VM_RT_AASTORE_TEST=403, - // Arguments: - // - Element - // - Array - // Return value: 1 if the element can be stored in the array, 0 otherwise. - // - // Check if a reference element into into an array. If the 'array' - // argument is null, return 0. This function does not throw exceptions. - +/** + * @param The parameters are the following: + * \arg Element + * \arg Array + * + * @return 1 if the element can be stored in the array; 0 otherwise. + * + * Check if a reference element into into an array. If the array + * argument is null, return 0. This function does not throw exceptions. + */ VM_RT_GET_INTERFACE_VTABLE_VER0=404, - // Arguments: - // - Object reference - // - Class handle for the interface - // Return value: - // - Interface vtable with method entries for the implementation - // of that interface by the actual class of the object. +/** + * @param The parameters are the following: + * \arg Object reference + * \arg Class handle for the interface + * + * @return Interface vtable with method entries for the implementation + * of that interface by the actual class of the object. + */ + ///// + //Class initialization + ///// - - ////////////////////////////////////////////////////////////////////////// - // Class initialization - ////////////////////////////////////////////////////////////////////////// - VM_RT_INITIALIZE_CLASS=500, - // Arguments: - // - Class handle - // Return value: none. - // - // If the class hasn't been initialized yet, initialize it. - // - // A call to this function must be generated before every putstatic - // and getstatic unless the JIT can prove that the class would have - // been already initialized at that point. +/** + * @param Class handle + * + * @return None. + * + * If the class hasn't been initialized yet, initialize it. + * + * A call to this function must be generated before every putstatic + * and getstatic unless the JIT can prove that the class would have + * been already initialized at that point. + */ + //// + // Write barrier routines + //// - - - ////////////////////////////////////////////////////////////////////////// - // Write barrier routines - ////////////////////////////////////////////////////////////////////////// - VM_RT_GC_HEAP_WRITE_REF=600, - // Arguments: - // - Address of the base of the object (or array) being written to. - // - Address of a memory location being written to - // - Value being written. - // Return value: none. - // - // Write barrier for GC. Updates the slot with the value provided. - // The type being written is indicated in the name. - +/** + * @param The parameters are the following: + * \arg Address of the base of the object (or array) being written to + * \arg Address of a memory location being written to + * \arg Value being written + * + * @return None. + * + * Write barrier for GC. Updates the slot with the value provided. + * The type being written is indicated in the name. + */ VM_RT_GC_SAFE_POINT=601, - // Arguments: none - // Return value: none. - // Use this helper to notify GC about safe point in managed code - +/** + * @param none + * + * @return None. + * + * Use this helper to notify GC about safe point in managed code. + */ VM_RT_GC_GET_TLS_BASE=602, - // Arguments: none - // Return value: pointer to int-sized suspension request flag - // - // When the flag is non zero, managed code should call VM_RT_GC_SAFE_POINT - // helper. - // Note: The flag must be used for read only ! +/** + * @param none + * + * @return Pointer to int-sized suspension request flag. + * + * When the flag is non zero, managed code should call VM_RT_GC_SAFE_POINT + * helper. + * + * @note The flag must be used for read only! + */ + + + ///// + // JVMTI specific routines + ///// - ////////////////////////////////////////////////////////////////////////// - // JVMTI specific routines - ////////////////////////////////////////////////////////////////////////// - VM_RT_JVMTI_METHOD_ENTER_CALLBACK = 700, - // Arguments: handle of the method which gets control - // Return value: none - // - // This call-back should be used to notify about method enter event. - // Do a call-back when such capability is requested only. - +/** + * @param handle of the method which gets control + * + * @return None. + * + * This call-back should be used to notify about method enter event. + * Do a call-back when such capability is requested only. + */ VM_RT_JVMTI_METHOD_EXIT_CALLBACK = 701, - // Arguments: - // - handle of the method which is about to lose control - // - method's return value - // Return value: none - // - // This call-back should be used to notify about method exit event. - // Do a call-back when such capability is requested only. +/** + * @param The parameters are the following: + * \arg handle of the method which is about to lose control + * \arg method's return value + * + * @return None. + * + * This call-back should be used to notify about method exit event. + * Do a call-back when such capability is requested only. + */ + + VM_RT_JVMTI_FIELD_ACCESS_CALLBACK = 702, - VM_RT_JVMTI_FIELD_ACCESS_CALLBACK = 702, - // Arguments: - // - handle of the field under access - // - handle of the method, which accesses field - // - location of code which accesses field - // - pointer to the reference of the object, which field is beeng - // accessed or NULL for static field - // Return value: none - // - // Notifies about field access. - +/** + * @param The parameters are the following: + * arg\ handle of the field under access + * arg\ handle of the method, which accesses field + * arg\ location of code which accesses field + * arg\ pointer to the reference of the object, which field is beeng + * accessed or NULL for static field + * + * @return None. + * + * Notifies about field access. + */ VM_RT_JVMTI_FIELD_MODIFICATION_CALLBACK = 703, - // Arguments: - // - handle of the field under modification - // - handle of the method, which modifies field - // - location of code which modifies field - // - pointer to the reference of the object, which field is beeng - // modified or NULL for static field - // - pointer to the new value for the field - // Return value: none - // - // Notifies about field modification. +/** + * @param The parameters are the following: + * arg\ handle of the field under modification + * arg\ handle of the method, which modifies field + * arg\ location of code which modifies field + * arg\ pointer to the reference of the object, which field is beeng + * modified or NULL for static field + * arg\ pointer to the new value for the field + * + * @return none + * + * Notifies about field modification. + */ - ////////////////////////////////////////////////////////////////////////// - // Runtime resolution routine - ////////////////////////////////////////////////////////////////////////// + ///// + /// Runtime resolution routine + ///// VM_RT_RESOLVE = 801, - // Arguments: - // - Class handle - // - Constant pool index of an item to be resolved - // - A java byte code instruction (JavaByteCodes) the resolution - // is performed for - // - // The helper performs resolution of symbolic references during runtime. - // If resolution failed, the helper throws appropriate LinkageError. - // Otherwise, the value depends on byte code passed: - // - // === JavaByteCodes === === result of call === - // OPCODE_INVOKESTATIC: resolve_static_method - // OPCODE_INVOKEINTERFACE: resolve_interface_method - // OPCODE_INVOKEVIRTUAL, - // OPCODE_INVOKESPECIAL: resolve_virtual_method - // OPCODE_INSTANCEOF, - // OPCODE_CHECKCAST, - // OPCODE_MULTIANEWARRAY resolve_class - // OPCODE_ANEWARRAY: class_get_array_of_class(resolve_class()) - // OPCODE_NEW: resolve_class_new - // OPCODE_GETFIELD, - // OPCODE_PUTFIELD: resolve_nonstatic_field - // OPCODE_PUTSTATIC, - // OPCODE_GETSTATIC: resolve_static_field - // - // The helper initializes class if the class hasn't been initialized yet - // for PUTSTATIC and GETSTATIC - // + +/** + * @param The parameters are the following: + * arg\ Class handle + * arg\ Constant pool index of an item to be resolved + * arg\ A java byte code instruction (JavaByteCodes) + * the resolution is performed for + * + * The helper performs resolution of symbolic references during runtime. + * If resolution failed, the helper throws appropriate LinkageError. + * Otherwise, the value depends on byte code passed: + * + * === JavaByteCodes === === result of call === + * + * OPCODE_INVOKESTATIC: resolve_static_method + * + * OPCODE_INVOKEINTERFACE: resolve_interface_method + * + * OPCODE_INVOKEVIRTUAL, + * + * OPCODE_INVOKESPECIAL: resolve_virtual_method + * + * OPCODE_INSTANCEOF, + * + * OPCODE_CHECKCAST, + * + * OPCODE_MULTIANEWARRAY resolve_class + * + * OPCODE_ANEWARRAY: class_get_array_of_class(resolve_class()) + * + * OPCODE_NEW: resolve_class_new + * + * OPCODE_GETFIELD, + * + * OPCODE_PUTFIELD: resolve_nonstatic_field + * + * OPCODE_PUTSTATIC, + * + * OPCODE_GETSTATIC: resolve_static_field + * + * The helper initializes class if the class hasn't been initialized yet + * for PUTSTATIC and GETSTATIC. + */ - ////////////////////////////////////////////////////////////////////////// - // Non-VM specific helpers for the JIT - ////////////////////////////////////////////////////////////////////////// + ///// + // Non-VM specific helpers for the JIT + ///// VM_RT_F2I=900, VM_RT_F2L=901, @@ -429,16 +503,16 @@ VM_RT_LSHL=910, VM_RT_LSHR=911, VM_RT_LUSHR=912, - // Arguments: - // (new version) - // - Long value to be shifted - // - Int value with count - // (old version) - // - (edx:eax) A long value to be shifted - // - (ecx) Count - // Return value: (edx:eax) - // - The shifted value - // + * Arguments: + * (new version) + * - Long value to be shifted + * - Int value with count + * (old version) + * - (edx:eax) A long value to be shifted + * - (ecx) Count + * Return value: (edx:eax) + * - The shifted value + * VM_RT_LMUL=920, @@ -464,57 +538,62 @@ // Float/double arithmetic VM_RT_CHAR_ARRAYCOPY_NO_EXC=950, - // Arguments: - // - Object reference for the source array. Must be non-null and refer to an array - // of 16 bit chars. - // - int32 containing the starting index of the source array to copy. - // - Object reference for the destination array. Must be non-null and refer to an array - // of 16 bit chars. - // - int32 containing the starting index of the destination array to copy into. - // - int32 containing the number of 16 bit chars to copy. - // Return value: none. - // - // This runtime helper function provides a specialized implementation for System.arraycopy - // for the common case where the elements of the arrays are - // 16 bit characters and the array references are both non-null. The JIT must guarantee - // that no exceptions will need to be thrown. That is, both array references are non-null, - // the types match (and are both arrays of 16 bit characters), - // and the starting indexes and length are such that the copying will only access - // data in the bounds of the arrays. +/** + * @param The parameters are the following: + * arg\ Object reference for the source array. Must be non-null and refer to an array + * of 16 bit chars + * arg\ int32 containing the starting index of the source array to copy + * arg\ Object reference for the destination array. Must be non-null and refer to an array + * of 16 bit chars. + * arg\ int32 containing the starting index of the destination array to copy into. + * arg\ int32 containing the number of 16 bit chars to copy. + * + * @return None. + * + * This runtime helper function provides a specialized implementation for System.arraycopy + * for the common case where the elements of the arrays are + * 16 bit characters and the array references are both non-null. The JIT must guarantee + * that no exceptions will need to be thrown. That is, both array references are non-null, + * the types match (and are both arrays of 16 bit characters), + * and the starting indexes and length are such that the copying will only access + * data in the bounds of the arrays. + */ + //// + // Deprecated routines + //// - - ////////////////////////////////////////////////////////////////////////// - // Deprecated routines - ////////////////////////////////////////////////////////////////////////// - VM_RT_NEW_RESOLVED=1000, - // Arguments: - // - Class handle for the class whose object we want to create - // Return value: - // - Reference to the new object - // - // Allocates a new object of the class. This function should be used - // for classes which inherit the finalize method of java.lang.Object. - // See also VM_RT_NEW_RESOLVED_USING_VTABLE. - +/** + * @param Class handle for the class whose object we want to create + * + * @return Reference to the new object. + * + * Allocates a new object of the class. This function should be used + * for classes which inherit the finalize method of java.lang.Object. + * See also VM_RT_NEW_RESOLVED_USING_VTABLE. + */ VM_RT_NEW_VECTOR=1001, - // Arguments: - // - Vector length - // - Class handle of the vector class - // Return value: - // - Reference to the new object - // - // Create a vector (zero-based, one dimensional array) - // of the given type. See also VM_RT_NEW_VECTOR_USING_VTABLE. - +/** + * @param The parameters are the following: + * arg\ Vector length + * arg\ Class handle of the vector class + * + * @return Reference to the new object + * + * Create a vector (zero-based, one dimensional array) + * of the given type. See also VM_RT_NEW_VECTOR_USING_VTABLE. + */ VM_RT_WRITE_BARRIER_FASTCALL=1002 - // Arguments: - // - Address of a memory location being written to - // - Object reference being written. - // Return value: none. - // - // Write barrier for GC. +/** + * @param The parameters are the following: + * arg\ Address of a memory location being written to + * arg\ Object reference being written. + * + * @return None. + * + * Write barrier for GC. + */ } VM_RT_SUPPORT; //VM_RT_SUPPORT @@ -525,16 +604,18 @@ VMEXPORT void *vm_get_rt_support_addr(VM_RT_SUPPORT f); -/* temporary interface addition - * same as vm_get_rt_support_addr, but tries to optimize the stubs it creates, +/** + * Temporary interface addition + * same as vm_get_rt_support_addr, but tries to optimize the stubs it creates, * by specializing them. */ VMEXPORT void *vm_get_rt_support_addr_optimized(VM_RT_SUPPORT f, Class_Handle c); - -// instead of returning a stub address, this support function returns -// parsed LIL code. -typedef struct LilCodeStub LilCodeStub; +/** + * Instead of returning a stub address, this support function returns + * parsed LIL code. + */ + typedef struct LilCodeStub LilCodeStub; VMEXPORT LilCodeStub *vm_get_rt_support_stub(VM_RT_SUPPORT f, Class_Handle c); Index: trunk/vm/include/open/common.h =================================================================== --- trunk/vm/include/open/common.h (revision 487512) +++ trunk/vm/include/open/common.h (working copy) @@ -14,18 +14,14 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -/** - * @author Aleksey Ignatenko - * @version $Revision: 1.1.2.1.4.3 $ - */ // excluding remarks: #if defined (__INTEL_COMPILER) -#pragma warning (disable:1684) // conversion from pointer to same-sized integral type (potential portability problem) -#pragma warning (disable:279) // controlling expression is constant -#pragma warning (disable:444) // destructor for base class is not virtual -#pragma warning (disable:981) // operands are evaluated in unspecified order -#pragma warning (disable:181) // argument is incompatible with corresponding format string conversion (in printf) +#pragma warning (disable:1684) // conversion from pointer to same-sized integral type (potential portability problem) +#pragma warning (disable:279) // controlling expression is constant +#pragma warning (disable:444) // destructor for base class is not virtual +#pragma warning (disable:981) // operands are evaluated in unspecified order +#pragma warning (disable:181) // argument is incompatible with corresponding format string conversion (in printf) #pragma warning (disable:1599) // declaration hides variable "dclazz" (declared at line NN) #endif // _MSC_VER @@ -33,7 +29,9 @@ #pragma warning (disable:4800) // forcing value to bool 'true' or 'false' (performance warning) #endif -//Warning appears when local variable is defined and not used +/** + * Warning appears when local variable is defined and not used. + */ #if defined (__INTEL_COMPILER) && defined(__GNUC__) #pragma warning (disable:177) #define UNUSED @@ -48,7 +46,10 @@ #define UNUSED #endif // !__GNUC__ -//Warning appears when function parameter is not used in function body +/** + * Warning appears when function parameter is not used in + * function body. + */ #if defined (__INTEL_COMPILER) && defined(__GNUC__) #pragma warning (disable:869) #define UNREF Index: trunk/vm/include/open/ee_em_intf.h =================================================================== --- trunk/vm/include/open/ee_em_intf.h (revision 487512) +++ trunk/vm/include/open/ee_em_intf.h (working copy) @@ -1,23 +1,20 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You under the Apache License, Version 2.0 - * (the "License"); you may not use this file except in compliance with - * the License. You may obtain a copy of the License at + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at * - * http://www.apache.org/licenses/LICENSE-2.0 + * http://www.apache.org/licenses/LICENSE-2.0 * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. */ -/** - * @author Mikhail Y. Fursov - * @version $Revision: 1.1.2.1.4.4 $ - */ + #ifndef _EE_EM_H_ #define _EE_EM_H_ @@ -44,9 +41,9 @@ * The given method is called only once per JIT instance. * * @param[in] jit - the run-time JIT handle used at run-time to refer to - * the given JIT instance + * the given JIT instance * @param[in] name - the persistent JIT name that the compiler uses to separate - * its configuration settings from the ones of other JITs + * its configuration settings from the ones of other JITs */ JITEXPORT void JIT_init(JIT_Handle jit, const char* name); @@ -86,19 +83,18 @@ * by the role parameter. * The profile type and the profile collector are defined by the profile * collector handle. - * * @param[in] jit - the JIT instance * @param[in] pc - the handle of the profile collector instance * @param[in] role - the role of JIT in profiling defining whether to collect - * or to use the profile + * or to use the profile * * @return TRUE if JIT does profiling of the pc type - * according the role parameter, FALSE if profiling is not - * supported. + * according to the role parameter; FALSE if + * profiling is not supported. * * @note The given method is optional. A JIT compiler without profiling - * support does not need this method. + * support does not need this method. */ JITEXPORT bool JIT_enable_profiling(JIT_Handle jit, PC_Handle pc, EM_JIT_PC_Role role); Index: trunk/vm/include/open/hycomp.h =================================================================== --- trunk/vm/include/open/hycomp.h (revision 487512) +++ trunk/vm/include/open/hycomp.h (working copy) @@ -18,36 +18,54 @@ #if !defined(hycomp_h) #define hycomp_h -/* -USE_PROTOTYPES: Use full ANSI prototypes. -CLOCK_PRIMS: We want the timer/clock prims to be used -LITTLE_ENDIAN: This is for the intel machines or other - little endian processors. Defaults to big endian. -NO_LVALUE_CASTING: This is for compilers that don't like the left side - of assigns to be cast. It hacks around to do the - right thing. -ATOMIC_FLOAT_ACCESS: So that float operations will work. -LINKED_USER_PRIMITIVES: Indicates that user primitives are statically linked - with the VM executeable. -OLD_SPACE_SIZE_DIFF: The 68k uses a different amount of old space. - This "legitimizes" the change. -SIMPLE_SIGNAL: For machines that don't use real signals in C. - (eg: PC, 68k) -OS_NAME_LOOKUP: Use nlist to lookup user primitive addresses. -VMCALL: Tag for all functions called by the VM. -VMAPICALL: Tag for all functions called via the PlatformFunction - callWith: mechanism. - -SYS_FLOAT: For some math functions where extended types (80 or 96 bits) are returned - Most platforms return as a double -FLOAT_EXTENDED: If defined, the type name for extended precision floats. -PLATFORM_IS_ASCII: Must be defined if the platform is ASCII -EXE_EXTENSION_CHAR: the executable has a delimiter that we want to stop at as part of argv[0]. -*/ -/* By default order doubles in the native (i.e. big/little endian) ordering. */ +/** + * USE_PROTOTYPES: Use full ANSI prototypes. + * + * CLOCK_PRIMS: We want the timer/clock prims to be used + * + * LITTLE_ENDIAN: This is for the intel machines or other + * little endian processors. Defaults to big endian. + * + * NO_LVALUE_CASTING: This is for compilers that don't like the left side + * of assigns to be cast. It hacks around to do the + * right thing. + * + * ATOMIC_FLOAT_ACCESS: So that float operations will work. + * + * LINKED_USER_PRIMITIVES: Indicates that user primitives are statically linked + * with the VM executeable. + * + * OLD_SPACE_SIZE_DIFF: The 68k uses a different amount of old space. + * This "legitimizes" the change. + * + * SIMPLE_SIGNAL: For machines that don't use real signals in C. + * (eg: PC, 68k) + * + * OS_NAME_LOOKUP: Use nlist to lookup user primitive addresses. + * + * VMCALL: Tag for all functions called by the VM. + * + * VMAPICALL: Tag for all functions called via the PlatformFunction + * callWith: mechanism. + * + * SYS_FLOAT: For some math functions where extended types (80 or 96 bits) are returned + * Most platforms return as a double + * + * FLOAT_EXTENDED: If defined, the type name for extended precision floats. + * + * PLATFORM_IS_ASCII: Must be defined if the platform is ASCII + * + * EXE_EXTENSION_CHAR: the executable has a delimiter that we want to stop at as part of argv[0]. + * + * By default order doubles in the native (that is big/little endian) ordering. + */ + #define HY_PLATFORM_DOUBLE_ORDER #if defined(LINUX) -/* NOTE: Linux supports different processors -- do not assume 386 */ + +/** + * @note Linux supports different processors - do not assume 386. + */ #if defined(LINUXPPC64) || defined(POINTER64) #define DATA_TYPES_DEFINED typedef unsigned long int UDATA; /* 64bits */ @@ -78,7 +96,9 @@ #define DIR_SEPARATOR '/' #define DIR_SEPARATOR_STR "/" -/* no priorities on Linux */ +/** + * No priorities on Linux + */ #define HY_PRIORITY_MAP {0,0,0,0,0,0,0,0,0,0,0,0} #if (defined(LINUXPPC) && !defined(LINUXPPC64)) @@ -89,7 +109,9 @@ #define GLOBAL_DATA(symbol) ((void*)&(symbol)) #define GLOBAL_TABLE(symbol) GLOBAL_DATA(symbol) -/* Win32 - Windows 3.1 & NT using Win32 */ +/** + * Win32 - Windows 3.1 & NT using Win32 + */ #if defined(WIN32) typedef __int64 I_64; @@ -104,9 +126,17 @@ #define DIR_SEPARATOR '\\' #define DIR_SEPARATOR_STR "\\" -/* Modifications for the Alpha running WIN-NT */ +/** + * Modifications for the Alpha running WIN-NT + */ + #if defined(_ALPHA_) -#undef small /* defined as char in rpcndr.h */ +#undef small + +/** + * Defined as char in rpcndr.h + */ + typedef double FLOAT_EXTENDED; #endif @@ -130,26 +160,39 @@ #define VMAPICALL #endif #define PVMCALL VMCALL * -/* Provide some reasonable defaults for the VM "types": - UDATA unsigned data, can be used as an integer or pointer storage. - IDATA signed data, can be used as an integer or pointer storage. - U_64 / I_64 unsigned/signed 64 bits. - U_32 / I_32 unsigned/signed 32 bits. - U_16 / I_16 unsigned/signed 16 bits. - U_8 / I_8 unsigned/signed 8 bits (bytes -- not to be confused with char) - BOOLEAN something that can be zero or non-zero. -*/ + +/** + * Provide some reasonable defaults for the VM types: + * + */ #if !defined(DATA_TYPES_DEFINED) typedef unsigned int UDATA; typedef unsigned int U_32; typedef unsigned short U_16; typedef unsigned char U_8; -/* no generic U_64 or I_64 */ +/** + * No generic U_64 or I_64. + */ typedef int IDATA; typedef int I_32; typedef short I_16; typedef char I_8; -/* don't typedef BOOLEAN since it's already def'ed on Win32 */ + +/** + * Don't typedef BOOLEAN since it's already def'ed on Win32. + */ + #endif #ifdef LINUX #define BOOLEAN UDATA @@ -160,12 +203,22 @@ #endif #if !defined(HY_DEFAULT_SCHED) -/* by default, pthreads platforms use the SCHED_OTHER thread scheduling policy */ + +/** + * By default, pthreads platforms use the SCHED_OTHER thread + * scheduling policy. + */ + #define HY_DEFAULT_SCHED SCHED_OTHER #endif #if !defined(HY_PRIORITY_MAP) -/* if no priority map if provided, priorities will be determined algorithmically */ + +/** + * If no priority map if provided, priorities will be determined + * algorithmically. + */ + #endif #if !defined(FALSE) @@ -190,17 +243,29 @@ #define PROTOTYPE(x) () #define VARARGS #endif -/* Assign the default line delimiter if it was not set */ + +/** + * Assign the default line delimiter, if it was not set. + */ + #if !defined(PLATFORM_LINE_DELIMITER) #define PLATFORM_LINE_DELIMITER "\015\012" #endif -/* Set the max path length if it was not set */ + +/** + * Set the max path length, if it was not set. + */ + #if !defined(MAX_IMAGE_PATH_LENGTH) #define MAX_IMAGE_PATH_LENGTH (2048) #endif typedef double ESDOUBLE; typedef float ESSINGLE; -/* helpers for U_64s */ + +/** + * Helpers for U_64s. + */ + #define CLEAR_U64(u64) (u64 = (U_64)0) #define LOW_LONG(l) (*((U_32 *) &(l))) #define HIGH_LONG(l) (*(((U_32 *) &(l)) + 1)) @@ -220,7 +285,11 @@ #define CLASSP(x) ((Class *) (x)) #define CLASSPP(x) ((Class **) (x)) #define BYTEP(x) ((BYTE *) (x)) -/* Test - was conflicting with OS2.h */ + +/** + * Test - was conflicting with OS2.h + */ + #define ESCHAR(x) ((CHARACTER) (x)) #define FLT(x) ((FLOAT) x) #define FLTP(x) ((FLOAT *) (x)) @@ -262,7 +331,11 @@ #define LFLT(x) FLT((x)) #define LFLTP(x) FLTP((x)) #endif -/* Macros for converting between words and longs and accessing bits */ + +/** + * Macros for converting between words and longs and accessing bits. + */ + #define HIGH_WORD(x) U16(U32((x)) >> 16) #define LOW_WORD(x) U16(U32((x)) & 0xFFFF) #define LOW_BIT(o) (U32((o)) & 1) @@ -278,24 +351,39 @@ #define HY_CFUNC #define HY_CDATA #endif -/* Macros for tagging functions which read/write the vm thread */ + +/** + * Macros for tagging functions which read/write the vm thread. + */ + #define READSVMTHREAD #define WRITESVMTHREAD #define REQUIRESSTACKFRAME -/* macro for tagging functions which never return */ + +/** + * Macro for tagging functions, which never return. + */ + #if defined(__GNUC__) -/* on GCC, we can actually pass this information on to the compiler */ + +/** + * On GCC, we can actually pass this information on to the compiler. + */ + #define NORETURN __attribute__((noreturn)) #else #define NORETURN #endif -/* on some systems va_list is an array type. This is probably in - * violation of the ANSI C spec, but it's not entirely clear. Because of this, we end - * up with an undesired extra level of indirection if we take the address of a - * va_list argument. + +/** + * On some systems va_list is an array type. This is probably in + * violation of the ANSI C spec, but it's not entirely clear. Because of this, + * we end up with an undesired extra level of indirection if we take the address + * of a va_list argument. * - * To get it right ,always use the VA_PTR macro + * To get it right, always use the VA_PTR macro. */ + #if !defined(VA_PTR) #define VA_PTR(valist) (&valist) #endif @@ -306,7 +394,11 @@ #if !defined(TOC_STORE_TOC) #define TOC_STORE_TOC(dest,wrappedPointer) #endif -/* Macros for accessing I_64 values */ + +/** + * Macros for accessing I_64 values. + */ + #if defined(ATOMIC_LONG_ACCESS) #define PTR_LONG_STORE(dstPtr, aLongPtr) ((*U32P(dstPtr) = *U32P(aLongPtr)), (*(U32P(dstPtr)+1) = *(U32P(aLongPtr)+1))) #define PTR_LONG_VALUE(dstPtr, aLongPtr) ((*U32P(aLongPtr) = *U32P(dstPtr)), (*(U32P(aLongPtr)+1) = *(U32P(dstPtr)+1))) @@ -314,11 +406,19 @@ #define PTR_LONG_STORE(dstPtr, aLongPtr) (*(dstPtr) = *(aLongPtr)) #define PTR_LONG_VALUE(dstPtr, aLongPtr) (*(aLongPtr) = *(dstPtr)) #endif -/* Macro used when declaring tables which require relocations.*/ + +/** + * Macro used when declaring tables which require relocations. + */ + #if !defined(HYCONST_TABLE) #define HYCONST_TABLE const #endif -/* ANSI qsort is not always available */ + +/** + * ANSI qsort is not always available. + */ + #if !defined(HY_SORT) #define HY_SORT(base, nmemb, size, compare) qsort((base), (nmemb), (size), (compare)) #endif Index: trunk/vm/include/open/vm.h =================================================================== --- trunk/vm/include/open/vm.h (revision 487512) +++ trunk/vm/include/open/vm.h (working copy) @@ -1,6 +1,6 @@ /* * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with + * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with @@ -14,17 +14,12 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + /** - * @author Intel, Alexei Fedotov - * @version $Revision: 1.1.2.2.4.3 $ + * These are the functions that a VM built as a DLL must export. + * Some functions may be optional and are marked as such. */ - -// -// These are the functions that a VM built as a DLL must export. -// Some functions may be optional and are marked as such. -// - #ifndef _VM_EXPORT_H #define _VM_EXPORT_H @@ -40,8 +35,10 @@ extern "C" { #endif -// This structure is meant to be opaque. External modules should not -// attempt to directly access any of its fields. +/** + * This structure is meant to be opaque. External modules should not. + */ + attempt to directly access any of its fields. typedef struct ChaClassIterator { Class_Handle _root_class; Class_Handle _current; @@ -49,8 +46,10 @@ } ChaClassIterator; -// This structure is meant to be opaque. External modules should not -// attempt to directly access any of its fields. +/** + * This structure is meant to be opaque. External modules should not. + */ + attempt to directly access any of its fields. typedef struct ChaMethodIterator { Method_Handle _method; Method_Handle _current; @@ -58,629 +57,919 @@ } ChaMethodIterator; -///////////////////////////////////////////////////////////////// -// begin class-related functions. +/** + * Begin class-related functions. + */ - -// Returns a handle for the object class. For Java applications, it's -// java.lang.Object. +/** + * @return A handle for the Object class. For Java applications, it's + * java.lang.Object. + */ VMEXPORT Class_Handle get_system_object_class(); -// Returns a handle for the class class. For Java applications, it's -// java.lang.Class. +/** + * @return A handle for the Class class. For Java applications, it's + * java.lang.Class. + */ VMEXPORT Class_Handle get_system_class_class(); -// Returns a handle for the string class. For Java applications, it's -// java.lang.String. +/** + * @return A handle for the string class. For Java applications, it's + * java.lang.String. + */ + VMEXPORT Class_Handle get_system_string_class(); -// Loads a class of a given name. If a class cannot be loaded, returns NULL +/** + * Loads a class of a given name. + * + * @return NULL if a class cannot be loaded. + */ + VMEXPORT Class_Handle class_load_class_by_name_using_bootstrap_class_loader(const char *name); -// The following three functions will be eventually renamed to -// class_is_final, class_is_abstract and class_is_interface, -// but right now that would conflict with the names of some internal macros. +/** + * The following three functions will be eventually renamed to + * \arg class_is_final + * \arg class_is_abstract + * \arg class_is_interface + * but right now that would conflict + * with the names of some internal macros. + */ + VMEXPORT Boolean class_property_is_final(Class_Handle ch); VMEXPORT Boolean class_property_is_abstract(Class_Handle ch); VMEXPORT Boolean class_property_is_interface2(Class_Handle ch); -// Returns TRUE if th class is likely to be used as an exception object. -// This is a hint only. If the result is FALSE, the class may still -// be used for exceptions but it is less likely. +/** + * @return TRUE if the class is likely to be used as an exception object. + * This is a hint only. If the result is FALSE, the class may still + * be used for exceptions but it is less likely. + */ VMEXPORT Boolean class_hint_is_exceptiontype(Class_Handle ch); -// Returns TRUE if the class is a value type. -VMEXPORT Boolean class_is_valuetype(Class_Handle ch); +/** + * @return TRUE if the class is a value type. + */ + VMEXPORT Boolean class_is_valuetype(Class_Handle ch); -// Return TRUE if the class represents an enum. For Java 1.4 always returns FALSE. +/** + * @return TRUE if the class represents an enum. + * For Java 1.4 always returns FALSE. + */ VMEXPORT Boolean class_is_enum(Class_Handle ch); -// This function can only be called if (class_is_enum(ch) == TRUE) -// The returned value is the type of the underlying int type. +/** + * This function can only be called if (class_is_enum(ch) == TRUE) + * The returned value is the type of the underlying int type. + */ VMEXPORT VM_Data_Type class_get_enum_int_type(Class_Handle ch); -// Returns TRUE if the class represents a primitive type (int, float, etc.) -VMEXPORT Boolean class_is_primitive(Class_Handle ch); +/** + * @return TRUE if the class represents a primitive type (int, float, etc.) + */ + VMEXPORT Boolean class_is_primitive(Class_Handle ch); -// Returns the name of the class. -VMEXPORT const char *class_get_name(Class_Handle ch); +/** + * @return The name of the class. + */ + VMEXPORT const char *class_get_name(Class_Handle ch); -// Returns the name of the package containing the class. -VMEXPORT const char *class_get_package_name(Class_Handle ch); +/** + * @return The name of the package containing the class. + */ + VMEXPORT const char *class_get_package_name(Class_Handle ch); -// Returns the super class of the current class. -// Returns NULL for the system object class, i.e. -// class_get_super_class(get_system_object_class()) == NULL +/** + * The super class of the current class. + * @return NULL for the system object class, i.e. + * class_get_super_class(get_system_object_class()) == NULL + */ VMEXPORT Class_Handle class_get_super_class(Class_Handle ch); -// Return the vtable handle of the given class. -VMEXPORT VTable_Handle class_get_vtable(Class_Handle ch); +/** + * @return The vtable handle of the given class. + */ + VMEXPORT VTable_Handle class_get_vtable(Class_Handle ch); -// Returns the allocation handle to be used for the object allocation -// routines, given a class handle. +/** + * @return The allocation handle to be used for the object allocation + * routines, given a class handle. + */ VMEXPORT Allocation_Handle class_get_allocation_handle(Class_Handle ch); -// Returns the class handle corresponding to a given allocation handle. +/** + * @return The class handle corresponding to a given allocation handle. + */ VMEXPORT Class_Handle allocation_handle_get_class(Allocation_Handle ah); -// Return an VM_Data_Type value for a given class. -VMEXPORT VM_Data_Type class_get_primitive_type_of_class(Class_Handle ch); +/** + * @return An VM_Data_Type value for a given class. + */ + VMEXPORT VM_Data_Type class_get_primitive_type_of_class(Class_Handle ch); -// Return a class corresponding to a primitive type. For all primitive types t -// t == class_get_primitive_type_of_class(class_get_class_of_primitive_type(t)) -VMEXPORT Class_Handle class_get_class_of_primitive_type(VM_Data_Type typ); +/** + * @return A class corresponding to a primitive type. For all primitive types t + * t == class_get_primitive_type_of_class(class_get_class_of_primitive_type(t)) + */ + VMEXPORT Class_Handle class_get_class_of_primitive_type(VM_Data_Type typ); -// Returns TRUE is the class is an array. +/** + * @return TRUE is the class is an array. + */ VMEXPORT Boolean class_is_array(Class_Handle ch); -// Returns TRUE if class s is assignment compatible with class t. +/** + * @return TRUE if class s is assignment + * compatible with class t. + */ VMEXPORT Boolean class_is_instanceof(Class_Handle s, Class_Handle t); -// Given a class handle cl construct a class handle of the type -// representing array of cl. If class cl is value type, assume -// that the element is a reference to a boxed instance of that type. -VMEXPORT Class_Handle class_get_array_of_class(Class_Handle ch); +/** + * Given a class handle cl construct a class handle of the type + * representing array of cl. If class cl is value type, assume + * that the element is a reference to a boxed instance of that type. + */ + VMEXPORT Class_Handle class_get_array_of_class(Class_Handle ch); -// Given a class handle cl construct a class handle of the type -// representing array of cl. Class cl is assumed to be a -// value type. Return NULL if cl is not a value type. -VMEXPORT Class_Handle class_get_array_of_unboxed(Class_Handle ch); +/** + * Given a class handle cl construct a class handle of the type + * representing array of cl. Class cl is assumed to be a + * value type. + * + * @return NULL if cl is not a value type. + */ + VMEXPORT Class_Handle class_get_array_of_unboxed(Class_Handle ch); -// For a class that is an array return the type info for the elements -// of the array -VMEXPORT Type_Info_Handle class_get_element_type_info(Class_Handle ch); +/** + * @return For a class that is an array return the type info for the elements + * of the array. + */ + VMEXPORT Type_Info_Handle class_get_element_type_info(Class_Handle ch); -// Returns TRUE if the class is already fully initialized. -VMEXPORT Boolean class_is_initialized(Class_Handle ch); + /** + * @return TRUE if the class is already fully initialized. + */ + VMEXPORT Boolean class_is_initialized(Class_Handle ch); -// Returns TRUE if the class is neither initialized nor in the process -// of being initialized. The intention is that the JIT will emit a call -// to VM_RT_INITIALIZE_CLASS before every access to a static field in -// Java. -VMEXPORT Boolean class_needs_initialization(Class_Handle ch); +/** + * @return TRUE if the class is neither initialized nor in the process + * of being initialized. The intention is that the JIT will emit a call + * to VM_RT_INITIALIZE_CLASS before every access to a static + * field in Java. + */ + VMEXPORT Boolean class_needs_initialization(Class_Handle ch); -// For Java returns FALSE. -VMEXPORT Boolean class_is_before_field_init(Class_Handle ch); +/** + * For Java returns FALSE. + */ + VMEXPORT Boolean class_is_before_field_init(Class_Handle ch); -// Number of instance fields defined in a class. That doesn't include -// inherited fields. -VMEXPORT unsigned class_num_instance_fields(Class_Handle ch); +/** + * Number of instance fields defined in a class. That doesn't include + * inherited fields. + */ + VMEXPORT unsigned class_num_instance_fields(Class_Handle ch); -// Get the handle for a field. If idx is greater than or equal to -// class_num_instance_fields, return NULL. -// The value of idx indexes into the fields defined in this class and -// doesn't include inherited fields. -VMEXPORT Field_Handle class_get_instance_field(Class_Handle ch, unsigned idx); +/** + * Get the handle for a field. If idx is greater than or equal to + * class_num_instance_fields. + * + * @return NULL + * + * The value of idx indexes into the fields defined in this class and + * doesn't include inherited fields. + */ + VMEXPORT Field_Handle class_get_instance_field(Class_Handle ch, unsigned idx); -// Number of instance fields defined in a class. This number includes -// inherited fields. +/** + * Number of instance fields defined in a class. This number includes + * inherited fields. + */ + VMEXPORT unsigned class_num_instance_fields_recursive(Class_Handle ch); - -// Get the handle for a field. If idx is greater than or equal to -// class_num_instance_fields_recursive, return NULL. -// The value of idx indexes into the set of fields that includes both fields -// defined in this class and inherited fields. +/** + * Get the handle for a field. + * + * @return NULL if idx is greater than or equal to + * class_num_instance_fields_recursive. + * + * The value of idx indexes into the set of fields that includes both fields + * defined in this class and inherited fields. + */ VMEXPORT Field_Handle class_get_instance_field_recursive(Class_Handle ch, unsigned idx); -// Number of methods declared in the class -VMEXPORT unsigned class_get_number_methods(Class_Handle ch); +/** + * Number of methods declared in the class. + */ + VMEXPORT unsigned class_get_number_methods(Class_Handle ch); -// Get handle for a method declared in class -VMEXPORT Method_Handle class_get_method(Class_Handle ch, unsigned index); +/** + * Get handle for a method declared in class. + */ + VMEXPORT Method_Handle class_get_method(Class_Handle ch, unsigned index); +/** + * @return TRUE if all instances of this class are pinned. + */ + VMEXPORT Boolean class_is_pinned(Class_Handle ch); -// Returns TRUE if all instances of this class are pinned. -VMEXPORT Boolean class_is_pinned(Class_Handle ch); +/** + * @return TRUE if all instances of this class are pinned. + */ + VMEXPORT void* class_alloc_via_classloader(Class_Handle ch, int32 size); -// Returns TRUE if all instances of this class are pinned. -VMEXPORT void* class_alloc_via_classloader(Class_Handle ch, int32 size); +/** + * @return TRUE if this is an array of primitives. + */ + VMEXPORT Boolean class_is_non_ref_array(Class_Handle ch); -// Returns TRUE if this is an array of primitives. -VMEXPORT Boolean class_is_non_ref_array(Class_Handle ch); +/** + * @return TRUE if the class has a non-trivial finalizer. + */ + VMEXPORT Boolean class_is_finalizable(Class_Handle ch); -// Returns TRUE if the class has a non-trivial finalizer. -VMEXPORT Boolean class_is_finalizable(Class_Handle ch); -// This exactly what I want. -// Get the alignment of the class. -VMEXPORT unsigned class_get_alignment(Class_Handle ch); +/** + * This exactly what I want. + * Get the alignment of the class. + */ + VMEXPORT unsigned class_get_alignment(Class_Handle ch); -// Get the alignment of the class when it's unboxed. -VMEXPORT unsigned class_get_alignment_unboxed(Class_Handle ch); +/** + * Get the alignment of the class when it's unboxed. + */ + VMEXPORT unsigned class_get_alignment_unboxed(Class_Handle ch); -// For a class handle that represents and array, return the size of the -// element of the array. -VMEXPORT unsigned class_element_size(Class_Handle ch); +/** + * @return For a class handle that represents and array, return the size of the + * element of the array. + */ + VMEXPORT unsigned class_element_size(Class_Handle ch); -// Return the size in bytes of an instance in the heap. -VMEXPORT unsigned class_get_boxed_data_size(Class_Handle ch); +/** + * @return The size in bytes of an instance in the heap. + */ + VMEXPORT unsigned class_get_boxed_data_size(Class_Handle ch); -// Return the offset to the start of user data form the start of a boxed -// instance. -VMEXPORT unsigned class_get_unboxed_data_offset(Class_Handle ch); +/** + * @return The offset to the start of user data form the start of a boxed + * instance. + */ + VMEXPORT unsigned class_get_unboxed_data_offset(Class_Handle ch); -// Return the class of the array element of the given class. -// The behavior is undefined if the parameter does not represent -// an array class. -VMEXPORT Class_Handle class_get_array_element_class(Class_Handle ch); +/** + * @return The class of the array element of the given class. + * + * The behavior is undefined if the parameter does not represent + * an array class. + */ + VMEXPORT Class_Handle class_get_array_element_class(Class_Handle ch); -// Returns the offset from the start of the vtable at which the -// superclass hierarchy is stored. This is for use with fast type -// checking. -VMEXPORT int vtable_get_super_array_offset(); +/** + * @return The offset from the start of the vtable at which the + * superclass hierarchy is stored. This is for use with fast type + * checking. + */ + VMEXPORT int vtable_get_super_array_offset(); -// Returns class handle given object's VTable_Handle. -VMEXPORT Class_Handle vtable_get_class(VTable_Handle vh); +/** + * @return Class handle given object's VTable_Handle. + */ + VMEXPORT Class_Handle vtable_get_class(VTable_Handle vh); -// Returns the number of superclass hierarchy elements that are -// stored within the vtable. This is for use with fast type checking. -VMEXPORT int vm_max_fast_instanceof_depth(); +/** + * @return The number of superclass hierarchy elements that are + * stored within the vtable. This is for use with fast type checking. + */ + VMEXPORT int vm_max_fast_instanceof_depth(); -///////////////////////////////////////////////////////////////// +//// // begin class iterator related functions. +//// -// Initializes the CHA_Class_Iterator, to iterate over all classes that -// descend from root_class, including root_class itself. -// Returns TRUE if iteration is supported over root_class, FALSE if not. -VMEXPORT Boolean class_iterator_initialize(ChaClassIterator*, Class_Handle root_class); +/** + * Initializes the CHA_Class_Iterator, to iterate over all + * classes that descend from root_class, including + * root_class itself. + * + * @return TRUE if iteration is supported over + * root_class, FALSE if not. + */ + VMEXPORT Boolean class_iterator_initialize(ChaClassIterator*, Class_Handle root_class); -// Returns the current class of the iterator. NULL is returned if -// therea are no more classes. -VMEXPORT Class_Handle class_iterator_get_current(ChaClassIterator*); +/** + * @return The current class of the iterator. NULL if + * there are no more classes. + */ + VMEXPORT Class_Handle class_iterator_get_current(ChaClassIterator*); -// Advances the iterator. -VMEXPORT void class_iterator_advance(ChaClassIterator*); +/** + * Advances the iterator. + */ + VMEXPORT void class_iterator_advance(ChaClassIterator*); - -///////////////////////////////////////////////////////////////// +//// // begin inner-class related functions. +/// -// Returns TRUE the number of inner classes -VMEXPORT unsigned class_number_inner_classes(Class_Handle ch); +/** + * @return TRUE the number of inner classes. + */ + VMEXPORT unsigned class_number_inner_classes(Class_Handle ch); -// Returns TRUE if an inner class is public -VMEXPORT Boolean class_is_inner_class_public(Class_Handle ch, unsigned idx); +/** + * @return TRUE if an inner class is public. + */ + VMEXPORT Boolean class_is_inner_class_public(Class_Handle ch, unsigned idx); -// Return an inner class -VMEXPORT Class_Handle class_get_inner_class(Class_Handle ch, unsigned idx); +/** + * @return an inner class + */ + VMEXPORT Class_Handle class_get_inner_class(Class_Handle ch, unsigned idx); -// Return the class that declared this one, or NULL if top-level class -VMEXPORT Class_Handle class_get_declaring_class(Class_Handle ch); +/** + * @return the class that declared this one, or NULL if top-level class + */ + VMEXPORT Class_Handle class_get_declaring_class(Class_Handle ch); -// end inner-class related functions. -///////////////////////////////////////////////////////////////// +/// +// end class-related functions. +/// - +//// // end class-related functions. -///////////////////////////////////////////////////////////////// +//// - - -///////////////////////////////////////////////////////////////// +//// // begin field-related functions. +//// +/** + * @return TRUE is the field is static. + */ + VMEXPORT Boolean field_is_static(Field_Handle fh); -// Returns TRUE is the field is static. -VMEXPORT Boolean field_is_static(Field_Handle fh); +/** + * @return The type info that represents the type of the field. + */ + VMEXPORT Type_Info_Handle field_get_type_info_of_field_value(Field_Handle fh); -// Returns the type info that represents the type of the field. -VMEXPORT Type_Info_Handle field_get_type_info_of_field_value(Field_Handle fh); +/** + * @return The class that represents the type of the field. + */ + VMEXPORT Class_Handle field_get_class_of_field_value(Field_Handle fh); -// Returns the class that represents the type of the field. -VMEXPORT Class_Handle field_get_class_of_field_value(Field_Handle fh); +/** + * @return The class that defined that field. + */ + VMEXPORT Class_Handle field_get_class(Field_Handle fh); -// Returns the class that defined that field. -VMEXPORT Class_Handle field_get_class(Field_Handle fh); +/** + * @return TRUE if the field is of a reference type. + * + * This function doesn't cause resolution of the class of the field. + */ + VMEXPORT Boolean field_is_reference(Field_Handle fh); -// Returns TRUE if the field is of a reference type. -// This function doesn't cause resolution of the class of the field. -VMEXPORT Boolean field_is_reference(Field_Handle fh); +/** + * @return TRUE if the field is literal. In Java, it means that the + * field had the ConstantValue attribute set (JVMS2, Section 4.7.2). + */ + VMEXPORT Boolean field_is_literal(Field_Handle fh); -// Returns TRUE if the field is literal. In Java, it means that the -// field had the ConstantValue attribute set (JVMS2, Section 4.7.2). -VMEXPORT Boolean field_is_literal(Field_Handle fh); +/** + * For Java always FALSE. + */ + VMEXPORT Boolean field_is_unmanaged_static(Field_Handle fh); -// For Java always FALSE. -VMEXPORT Boolean field_is_unmanaged_static(Field_Handle fh); +/** + * @return The offset to an instance field. + */ + VMEXPORT unsigned field_get_offset(Field_Handle fh); -// Returns the offset to an instance field. -VMEXPORT unsigned field_get_offset(Field_Handle fh); +/** + * @return An address of a static field. + */ + VMEXPORT void *field_get_address(Field_Handle fh); -// Returns an address of a static field. -VMEXPORT void *field_get_address(Field_Handle fh); +/** + * @return A name of the field. + */ + VMEXPORT const char *field_get_name(Field_Handle fh); -// Returns a name of the field. -VMEXPORT const char *field_get_name(Field_Handle fh); +/** + * @return The field descriptor. The descriptor is a string representation + * of the field types as defined by the JVM spec. + */ + VMEXPORT const char *field_get_descriptor(Field_Handle fh); -// Returns the field descriptor. The descriptor is a string representation -// of the field types as defined by the -// JVM spec. -VMEXPORT const char *field_get_descriptor(Field_Handle fh); +/** + * @return TRUE if the field is final. + */ + VMEXPORT Boolean field_is_final(Field_Handle fh); -// Returns TRUE if the field is final. -VMEXPORT Boolean field_is_final(Field_Handle fh); +/** + * @return TRUE if the field is volatile. + */ + VMEXPORT Boolean field_is_volatile(Field_Handle fh); -// Returns TRUE if the field is volatile. -VMEXPORT Boolean field_is_volatile(Field_Handle fh); +/** + * @return TRUE if the field is private. + */ + VMEXPORT Boolean field_is_private(Field_Handle fh); -// Returns TRUE if the field is private. -VMEXPORT Boolean field_is_private(Field_Handle fh); - /** - * Returns the address and bit mask, for the flag which determine whether field - * access event should be sent. JIT may use the following expression to - * determine if specified field access should be tracked: - * ( **address & *mask != 0 ) - * @param field - handle of the field - * @param[out] address - pointer to the address of the byte which contains the flag - * @param[out] mask - pointer to the bit mask of the flag + * @return The address and bit mask, for the flag which determine whether field + * access event should be sent. JIT may use the following expression to + * determine if specified field access should be tracked: + * ( **address & *mask != 0 ) + * + * @param field - handle of the field + * @param[out] address - pointer to the address of the byte which contains the flag + * @param[out] mask - pointer to the bit mask of the flag */ VMEXPORT void field_get_track_access_flag(Field_Handle field, char** address, char* mask); /** - * Returns the address and bit mask, for the flag which determine whether field - * modification event should be sent. JIT may use the following expression to - * determine if specified field modification should be tracked: - * ( **address & *mask != 0 ) - * @param field - handle of the field - * @param[out] address - pointer to the address of the byte which contains the flag - * @param[out] mask - pointer to the bit mask of the flag + * @return the address and bit mask, for the flag which determine whether field + * modification event should be sent. JIT may use the following expression to + * determine if specified field modification should be tracked: + * ( **address & *mask != 0 ) + * + * @param field - handle of the field + * @param[out] address - pointer to the address of the byte which contains the flag + * @param[out] mask - pointer to the bit mask of the flag */ VMEXPORT void field_get_track_modification_flag(Field_Handle field, char** address, char* mask); - +//// // end field-related functions. -///////////////////////////////////////////////////////////////// +//// - - -///////////////////////////////////////////////////////////////// +//// // begin method-related functions. +//// - -// Returns TRUE if this a Java method. Every Java JIT must call this -// function before compiling a method and return JIT_FAILURE if -// method_is_java returned FALSE. +/** + * @return TRUE if this a Java method. Every Java JIT must call this + * function before compiling a method and return JIT_FAILURE if + * method_is_java returned FALSE. + */ VMEXPORT Boolean method_is_java(Method_Handle mh); -// Returns the method name. +/** + * @return The method name. + */ VMEXPORT const char *method_get_name(Method_Handle mh); -// Returns the method descriptor. The descriptor is a string representation -// of the parameter and return value types as defined by the -// JVM spec. +/** + * @return The method descriptor. The descriptor is a string representation + * of the parameter and return value types as defined by the JVM spec. + */ VMEXPORT const char *method_get_descriptor(Method_Handle mh); -// Returns a class in which the method is declared. +/** + * @return A class in which the method is declared. + */ VMEXPORT Class_Handle method_get_class(Method_Handle mh); -// Returns TRUE if the method is private. +/** + * @return TRUE if the method is private. + */ VMEXPORT Boolean method_is_private(Method_Handle mh); -// Returns TRUE if the method is static. +/** + * @return TRUE if the method is static. + */ VMEXPORT Boolean method_is_static(Method_Handle mh); -// Returns TRUE if the method is final. +/** + * @return TRUE if the method is final. + */ VMEXPORT Boolean method_is_final(Method_Handle mh); -// Returns TRUE if the method is native. +/** + * @return TRUE if the method is native. + */ VMEXPORT Boolean method_is_native(Method_Handle mh); -// Returns TRUE if the method is synchronized. +/** + * @return TRUE if the method is synchronized. + */ VMEXPORT Boolean method_is_synchronized(Method_Handle mh); -// Returns TRUE if the method is abstract. +/** + * @return TRUE if the method is abstract. + */ VMEXPORT Boolean method_is_abstract(Method_Handle mh); -// Java methods may have a flag set to indicate that floating point operations -// must be performed in the strict mode. method_is_strict() returns TRUE is -// the ACC_STRICT flag is set for a Java method and FALSE otherwise. +/** + * Java methods may have a flag set to indicate that floating point operations + * must be performed in the strict mode. + * + * @return method_is_strict() returns TRUE if + * the ACC_STRICT flag is set for a Java method and FALSE otherwise. + */ VMEXPORT Boolean method_is_strict(Method_Handle m); -// Returns TRUE if the method has been overriden in a subclass and FALSE -// otherwise. Note that if method_is_overridden returns FALSE, loading -// of a subclass later in the execution of the program may change invalidate -// this condition. If a JIT uses method_is_overridden to implement -// unconditional inlining, it must be prepared to patch the code later -// (see vm_register_jit_overridden_method_callback). +/** + * @return TRUE if the method has been overriden in a subclass + * and FALSE otherwise. + * + * @note If method_is_overridden returns FALSE, loading + * of a subclass later in the execution of the program may change + * invalidate this condition. If a JIT uses method_is_overridden + * to implement unconditional inlining, it must be prepared to patch the code later + * (see vm_register_jit_overridden_method_callback). + */ VMEXPORT Boolean method_is_overridden(Method_Handle m); -// Returns TRUE if the method should not be inlined. There may also -// be other reasons why a method shouldn't be inlined, e.g., native methods -// can't be inlined and in Java you can't inlined methods that are -// loaded by a different class loader than the caller. -// Always FALSE for Java. +/** + * @return TRUE if the method should not be inlined. There may also + * be other reasons why a method shouldn't be inlined, e.g., native methods + * can't be inlined and in Java you can't inlined methods that are + * loaded by a different class loader than the caller. + * Always FALSE for Java. + */ VMEXPORT Boolean method_is_no_inlining(Method_Handle mh); -// Always FALSE for Java. +/** + * Always FALSE for Java. + */ VMEXPORT Boolean method_is_require_security_object(Method_Handle mh); -// Return a signature that can be used to iterate over method's arguments -// and query the type of the method result. +/** + * @return A signature that can be used to iterate over method's arguments + * and query the type of the method result. + */ VMEXPORT Method_Signature_Handle method_get_signature(Method_Handle mh); -// Class ch is a subclass of method_get_class(mh). The function returns a method handle -// for an accessible method overriding mh in ch or in its closest superclass that overrides mh. -// Class ch must be a class not an interface. +/** + * Class ch is a subclass of method_get_class(mh). + * The function returns a method handle for an accessible method overriding + * mh in ch or in its closest superclass that overrides + * mh. + * Class ch must be a class not an interface. + */ VMEXPORT Method_Handle method_find_overridden_method(Class_Handle ch, Method_Handle mh); - -///////////////////////////////////////////////////////////////// +//// // begin method iterator related functions. +/// -// Initializes the CHA_Method_Iterator, to iterate over all methods that -// match the method signature and descend from root_class (including root_class itself). -// Returns TRUE if iteration is supported over root_class, FALSE if not. +/** + * Initializes the CHA_Method_Iterator, to iterate over all methods that + * match the method signature and descend from root_class + * (including root_class itself). + * + * @return TRUE if iteration is supported over root_class, + * FALSE if not. + */ VMEXPORT Boolean method_iterator_initialize(ChaMethodIterator*, Method_Handle method, Class_Handle root_class); -// Returns the current method of the iterator. NULL is returned if -// therea are no more methods. +/** + * @return The current method of the iterator. NULL is returned if + * therea are no more methods. + */ VMEXPORT Method_Handle method_iterator_get_current(ChaMethodIterator*); -// Advances the iterator. +/** + * Advances the iterator. + */ VMEXPORT void method_iterator_advance(ChaMethodIterator*); - -/////////////////////////////////////////////////////// +//// // begin method signature-related functions. +//// -// Returns the method descriptor for a given method signature. -// See method_get_descriptor(). +/** + * @return The method descriptor for a given method signature. + * See method_get_descriptor(). + */ VMEXPORT const char *method_sig_get_descriptor(Method_Signature_Handle s); -// Return a signature that can be used to iterate over method's arguments -// and query the type of the method result. -// Java doesn't have standalone signatures, so for Java, always return NULL. +/** + * Return a signature that can be used to iterate over method's arguments + * and query the type of the method result. + * Java doesn't have standalone signatures, so for Java, always return NULL. + */ VMEXPORT Method_Signature_Handle method_standalone_signature(Class_Handle ch, unsigned idx); +//// // end method signature-related functions. -/////////////////////////////////////////////////////// +//// - -/////////////////////////////////////////////////////// +//// // begin local variables-related functions. +/// -// Returns the number of local variables defined for the method. +/** + * @return the number of local variables defined for the method. + */ VMEXPORT unsigned method_vars_get_number(Method_Handle mh); -// Return the type info of the local variable number idx. -// Since local variables are not typed in Java. this function -// always returns NULL for Java methods. +/** + * Return the type info of the local variable number idx. + * Since local variables are not typed in Java. this function + * always returns NULL for Java methods. + */ VMEXPORT Type_Info_Handle method_vars_get_type_info(Method_Handle mh, unsigned idx); - -// Returns TRUE if the local variable is a managed pointer. +/** + * @return TRUE if the local variable is a managed pointer. + */ VMEXPORT Boolean method_vars_is_managed_pointer(Method_Handle mh, unsigned idx); -// Returns TRUE if the local variable is pinned. +/** + * @return TRUE if the local variable is pinned. + */ VMEXPORT Boolean method_vars_is_pinned(Method_Handle mh, unsigned idx); -// end local variables-related functions. -/////////////////////////////////////////////////////// +/** + * end local variables-related functions. + */ +/** + * begin argument-related functions. + */ -/////////////////////////////////////////////////////// -// begin argument-related functions. - -// Returns the number of arguments defined for the method. -// This number automatically includes the this pointer (if present). +/** + * @return the number of arguments defined for the method. + * This number automatically includes the this pointer (if present). + */ VMEXPORT unsigned method_args_get_number(Method_Signature_Handle msh); VMEXPORT Boolean method_args_has_this(Method_Signature_Handle msh); -// Return the class handle of the argument number idx. -// That's true even for primitive types like int or float. +/** + * Return the class handle of the argument number idx. + * That's TRUE even for primitive types like int or float. + */ VMEXPORT Type_Info_Handle method_args_get_type_info(Method_Signature_Handle msh, unsigned idx); - -// Returns TRUE if the argument is a managed pointer. +/** + * @return TRUE if the argument is a managed pointer. + */ VMEXPORT Boolean method_args_is_managed_pointer(Method_Signature_Handle msh, unsigned idx); +//// // end argument-related functions. -/////////////////////////////////////////////////////// +//// - -/////////////////////////////////////////////////////// +//// // begin return value-related functions. - +//// VMEXPORT Type_Info_Handle method_ret_type_get_type_info(Method_Signature_Handle msh); -// Returns TRUE if the return value is a managed pointer. +/** + * @return TRUE if the return value is a managed pointer. + */ VMEXPORT Boolean method_ret_type_is_managed_pointer(Method_Signature_Handle msh); +//// // end return value-related functions. -/////////////////////////////////////////////////////// +//// - +//// // end method-related functions. -///////////////////////////////////////////////////////////////// +//// - - -/////////////////////////////////////////////////////// +//// // begin type info-related functions. +//// -// Array shapes and custom modifiers are not implemented yet. - -// If type info is a reference, type_info_get_class will return the class -// of the reference. +/** + * Array shapes and custom modifiers are not implemented yet. + * + * If type info is a reference, type_info_get_class + * will return the class of the reference. + */ VMEXPORT Boolean type_info_is_reference(Type_Info_Handle tih); -// If type info is unboxed, type_info_get_class will return the class -// of the unboxed type and class_is_primitive will return its VM_Data_Type. +/** + * If type info is unboxed, type_info_get_class + * will return the class of the unboxed type and class_is_primitive + * will return its VM_Data_Type. + */ VMEXPORT Boolean type_info_is_unboxed(Type_Info_Handle tih); -// Returns TRUE if the type is a primitive type. type_info_is_primitive does -// not cause resolution in contrast to the otherwise equivalentcall sequence -// suggested in the description of type_info_is_unboxed (i.e. -// type_info_is_unboxed-->type_info_get_class-->class_is_primitive). +/** + * @return TRUE if the type is a primitive type. + * type_info_is_primitive does + * not cause resolution in contrast to the otherwise equivalentcall sequence + * suggested in the description of type_info_is_unboxed + * (i.e. type_info_is_unboxed-->type_info_get_class-->class_is_primitive). + */ VMEXPORT Boolean type_info_is_primitive(Type_Info_Handle tih); -// If TRUE, then -// type_info_get_type_info returns the type info that the pointer -// points to. +/** + * If TRUE, then type_info_get_type_info + * returns the type info that the pointer points to. + */ VMEXPORT Boolean type_info_is_unmanaged_pointer(Type_Info_Handle tih); -// For a return value a type can be void when it is not an unmanaged pointer. -// In all other contexts, if type_info_is_void is TRUE then -// type_info_is_unmanaged_pointer is TRUE too. +/** + * For a return value a type can be void when it is not an unmanaged pointer. + * In all other contexts, if type_info_is_void is TRUE then + * type_info_is_unmanaged_pointer is TRUE too. + */ VMEXPORT Boolean type_info_is_void(Type_Info_Handle tih); -// If TRUE, use type_info_get_method_sig to retrieve the method signature. +/** + * If TRUE, use type_info_get_method_sig to + * retrieve the method signature. + */ VMEXPORT Boolean type_info_is_method_pointer(Type_Info_Handle tih); -// Is it a vector, i.e., a one-dimensional, zero-based array. +/** + * Is it a vector, i.e., a one-dimensional, zero-based array. + */ VMEXPORT Boolean type_info_is_vector(Type_Info_Handle tih); -// Is it a general array, i.e., either multidimensional or non zero-based. -// Returns FALSE for vectors. Always FALSE for Java. +/** + * Is it a general array, i.e., either multidimensional or non zero-based. + * + * @return FALSE for vectors. Always FALSE for Java. + */ VMEXPORT Boolean type_info_is_general_array(Type_Info_Handle tih); -// Get the class if type_info_is_reference or type_info_is_unboxed -// returned TRUE. If the type info is a vector or a general array, return the -// class handle for the array type (not the element type). +/** + * Get the class if type_info_is_reference or + * type_info_is_unboxed returned TRUE. + * If the type info is a vector or a general array, return the + * class handle for the array type (not the element type). + */ VMEXPORT Class_Handle type_info_get_class(Type_Info_Handle tih); -// Get the method signature if type_info_is_method_pointer returned TRUE. +/** + * Get the method signature if type_info_is_method_pointer + * returned TRUE. + */ VMEXPORT Method_Signature_Handle type_info_get_method_sig(Type_Info_Handle tih); -// Get recursively type info if type_info_is_unmanaged_pointer, -// type_info_is_vector or type_info_is_general_array returned TRUE. +/** + * Get recursively type info if type_info_is_unmanaged_pointer, + * type_info_is_vector or type_info_is_general_array + * returned TRUE. + */ VMEXPORT Type_Info_Handle type_info_get_type_info(Type_Info_Handle tih); -// Return an VM_Data_Type corresponding to a type info. -// This function is provided for convenience as it can be implemented in terms -// of other functions provided in this interface. +/** + * Return an VM_Data_Type corresponding to a type info. + * This function is provided for convenience as it can be implemented in terms + * of other functions provided in this interface. + */ VMEXPORT VM_Data_Type type_info_get_type(Type_Info_Handle tih); +//// // end type info-related functions. -/////////////////////////////////////////////////////// +//// - - -///////////////////////////////////////////////////////////////// +//// // begin vector layout functions. +//// -// Vectors are one-dimensional, zero-based arrays. All Java "arrays" are -// vectors. -// Functions provided in this section do not work on multidimensional or -// non-zero based arrays (i.e. arrays with a lower bound that is non-zero -// for at least one of the dimensions. +/** + * Vectors are one-dimensional, zero-based arrays. All Java + * arrays are vectors. + * Functions provided in this section do not work on multidimensional or + * non-zero based arrays (i.e. arrays with a lower bound that is non-zero + * for at least one of the dimensions. + */ - -// Return the offset to the length field of the array. That field has -// the same offset for vectors of all types. +/** + * Return the offset to the length field of the array. That field has + * the same offset for vectors of all types. + */ VMEXPORT int vector_length_offset(); -// Deprecated. Please use vector_length_offset instead. -//VMEXPORT int array_length_offset(); +/** + * Deprecated. Please use vector_length_offset instead. + */ +VMEXPORT int array_length_offset(); -// Return the offset to the first element of the vector of the given type. -// This function is provided for the cases when the class handle of the -// element is not available. +/** + * Return the offset to the first element of the vector of the given type. + * This function is provided for the cases when the class handle of the + * element is not available. + */ VMEXPORT int vector_first_element_offset(VM_Data_Type element_type); -// Deprecated. Please use vector_first_element_offset instead. -//VMEXPORT int array_first_element_offset(VM_Data_Type element_type); +/** + * Deprecated. Please use vector_first_element_offset instead. + */ +VMEXPORT int array_first_element_offset(VM_Data_Type element_type); -// Return the offset to the first element of the vector of the given type. -// Assume that the elements are boxed. Byte offset. + +/** + * Return the offset to the first element of the vector of the given type. + * Assume that the elements are boxed. Byte offset. + */ VMEXPORT int vector_first_element_offset_class_handle(Class_Handle element_type); VMEXPORT int vector_first_element_offset_vtable_handle(VTable_Handle element_type); -// Deprecated. Please use vector_first_element_offset_class_handle instead. -//VMEXPORT int array_first_element_offset_class_handle(Class_Handle element_type); +/** + * Deprecated. Please use vector_first_element_offset_class_handle instead. + */ +VMEXPORT int array_first_element_offset_class_handle(Class_Handle element_type); -// Return the offset to the first element of the vector of the given type. -// If the class is a value type, assume that elements are unboxed. -// If the class is not a value type, assume that elements are references. +/** + * Return the offset to the first element of the vector of the given type. + * If the class is a value type, assume that elements are unboxed. + * If the class is not a value type, assume that elements are references. + */ VMEXPORT int vector_first_element_offset_unboxed(Class_Handle element_type); -// Deprecated. Please use vector_first_element_offset_unboxed instead. -//VMEXPORT int array_first_element_offset_unboxed(Class_Handle element_type); +/** + * Deprecated. Please use vector_first_element_offset_unboxed instead. + */ +VMEXPORT int array_first_element_offset_unboxed(Class_Handle element_type); -// Return the length of a vector. The caller must ensure that GC will not -// move or deallocate the vector while vector_get_length() is active. +/** + * Return the length of a vector. The caller must ensure that GC will not + * move or deallocate the vector while vector_get_length() is active. + */ VMEXPORT int32 vector_get_length(Vector_Handle vector); -// Return the address to an element of a vector of references. -// The caller must ensure that GC will not move or deallocate the vector -// while vector_get_element_address_ref() is active. +/** + * Return the address to an element of a vector of references. + * The caller must ensure that GC will not move or deallocate the vector + * while vector_get_element_address_ref() is active. + */ VMEXPORT Managed_Object_Handle * vector_get_element_address_ref(Vector_Handle vector, int32 idx); -// Return the size of a vector of a given number of elements. -// The size is rounded up to take alignment into account. +/** + * Return the size of a vector of a given number of elements. + * The size is rounded up to take alignment into account. + */ VMEXPORT unsigned vm_vector_size(Class_Handle vector_class, int length); - +//// // end vector layout functions. -///////////////////////////////////////////////////////////////// +//// - - -///////////////////////////////////////////////////////////////// +//// // begin miscellaneous functions. +//// - -// Returns TRUE if references within objects and vector elements are -// to be treated as offsets rather than raw pointers. +/** + * @return TRUE if references within objects and vector elements are + * to be treated as offsets rather than raw pointers. + */ VMEXPORT Boolean vm_references_are_compressed(); -// Returns the starting address of the GC heap. +/** + * @return The starting address of the GC heap. + */ VMEXPORT void *vm_heap_base_address(); -// Returns the ending address of the GC heap. +/** + * @return The ending address of the GC heap. + */ VMEXPORT void *vm_heap_ceiling_address(); -// Returns TRUE if vtable pointers within objects are to be treated -// as offsets rather than raw pointers. +/** + * @return TRUE if vtable pointers within objects are to be treated + * as offsets rather than raw pointers. + */ VMEXPORT Boolean vm_vtable_pointers_are_compressed(); -// Returns the offset to the vtable pointer in an object. +/** + * @return The offset to the vtable pointer in an object. + */ VMEXPORT int object_get_vtable_offset(); -// Returns the base address of the vtable memory area. This value will -// never change and can be cached at startup. +/** + * @return The base address of the vtable memory area. This value will + * never change and can be cached at startup. + */ VMEXPORT POINTER_SIZE_INT vm_get_vtable_base(); -// Returns the width in bytes (e.g. 4 or 8) of the vtable type -// information in each object's header. This is typically used -// by the JIT for generating type-checking code, e.g. for inlined -// type checks or for inlining of virtual methods. +/** + * @return The width in bytes (e.g. 4 or 8) of the vtable type + * information in each object's header. This is typically used + * by the JIT for generating type-checking code, e.g. for inlined + * type checks or for inlining of virtual methods. + */ VMEXPORT unsigned vm_get_vtable_ptr_size(); -// Returns a printable signature. The character buffer is owned by the -// caller. Call free_string_buffer to reclaim the memory. +/** + * @return A printable signature. The character buffer is owned by the + * caller. Call free_string_buffer to reclaim the memory. + */ VMEXPORT char *method_sig_get_string(Method_Signature_Handle msh); -// Free a string buffer returned by method_sig_get_string. +/** + * Free a string buffer returned by method_sig_get_string. + */ VMEXPORT void free_string_buffer(char *buffer); @@ -690,42 +979,69 @@ JAVA_PROPERTIES = 1 } PropertyTable; -//Sets the property for table_number property table. NULL value is supported. +/** + * Sets the property for table_number property table. NULL value is supported. + */ VMEXPORT void set_property(const char* key, const char* value, PropertyTable table_number); -//Returns the value of the property from table_number property table if it -//has been set by set_property function. Otherwise returns NULL. +/** + * @return The value of the property from table_number property table if it + * has been set by set_property function. Otherwise NULL. + */ VMEXPORT char* get_property(const char* key, PropertyTable table_number); -//Safety frees memory of value returned by get_property function. +/** + * Safety frees memory of value returned by get_property function. + */ VMEXPORT void destroy_property_value(char* value); -//Checks if the property is set. Return: -// -1 if table_number is incorrect. -// 1 if property is set in table_number property table. -// 0 otherwise. +/** + * Checks if the property is set. + * + * @return -1 if table_number is incorrect.
+ * 1 if property is set in table_number property table.
+ * 0 otherwise. + */ VMEXPORT int is_property_set(const char* key, PropertyTable table_number); -//Unsets the property in table_number property table. +/** + * Unsets the property in table_number property table. + */ VMEXPORT void unset_property(const char* key, PropertyTable table_number); -//Returns an array of keys from table_number properties table. +/** + * @return An array of keys from table_number properties table. + */ VMEXPORT char** get_properties_keys(PropertyTable table_number); -//Returns an array of keys which start with specified prefix from table_number properties table. +/** + * @return An array of keys which start with specified prefix from + * table_number properties table. + */ VMEXPORT char** get_properties_keys_staring_with(const char* prefix, PropertyTable table_number); -//Safety frees array of keys memory which returned by get_properties_keys -//or get_properties_keys_staring_with functions. +/** + * Safety frees array of keys memory which returned by get_properties_keys + * or get_properties_keys_staring_with functions. + */ VMEXPORT void destroy_properties_keys(char** keys); -//Tries to interpret property value as Boolean and returns it. In case of failure returns default_value. +/** + * Tries to interpret property value as Boolean and returns it. + * In case of failure returns default_value. + */ VMEXPORT Boolean get_boolean_property(const char* property, Boolean default_value, PropertyTable table_number); -//Tries to interpret property value as int and returns it. In case of failure returns default_value. +/** + * Tries to interpret property value as int and returns it. In case of failure + * returns default_value. + */ VMEXPORT int get_int_property(const char *property_name, int default_value, PropertyTable table_number); + + +//// // end miscellaneous functions. -///////////////////////////////////////////////////////////////// +//// #ifdef __cplusplus } Index: trunk/vm/include/open/vm_util.h =================================================================== --- trunk/vm/include/open/vm_util.h (revision 487512) +++ trunk/vm/include/open/vm_util.h (working copy) @@ -14,12 +14,7 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -/** - * @author Intel, Alexei Fedotov - * @version $Revision: 1.1.2.2.4.3 $ - */ - #ifndef _VM_UTILS_H_ #define _VM_UTILS_H_ @@ -59,16 +54,17 @@ extern VTable *cached_object_array_vtable_ptr; +/** + * Runtime support functions exported directly, because they + * may be called from native code. + */ - -//////////////////////////////////////////////////////////////////////////// -// Runtime support functions exported directly, because they may be called -// from native code. -//////////////////////////////////////////////////////////////////////////// - Boolean class_is_subtype(Class *sub, Class *super); -// Like class_is_subtype, but sub must not be an interface class. +/** + * Like class_is_subtype, but sub must not be an + * interface class. + */ Boolean class_is_subtype_fast(VTable *sub, Class *super); @@ -155,12 +151,12 @@ /** * @brief Generates an VM's helper to invoke the provided function. * - * The helper takes 'void*' parameter which is passed to the function after - * some preparation made (namely GC and stack info are prepared to allow GC - * to work properly). + * The helper takes the void* parameter, which is passed + * to the function after some preparation made (namely GC and stack + * info are prepared to allow GC to work properly). * - * The function must follow stdcall convention, which takes 'void*' and - * returns 'void*', so does the helper. + * The function must follow stdcall convention, which takes void* and + * returns void*, so does the helper. * On a return from the function, the helper checks whether an exception * was raised for the current thread, and rethrows it if necessary. */