harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nadi...@apache.org
Subject svn commit: r536108 - in /harmony/enhanced/drlvm/trunk/vm/interpreter/src: interp_defs.h interp_native.h interp_vm_helpers.h
Date Tue, 08 May 2007 07:34:12 GMT
Author: nadinem
Date: Tue May  8 00:34:10 2007
New Revision: 536108

URL: http://svn.apache.org/viewvc?view=rev&rev=536108
Log:
HARMONY-3310; fixing internal headers

Modified:
    harmony/enhanced/drlvm/trunk/vm/interpreter/src/interp_defs.h
    harmony/enhanced/drlvm/trunk/vm/interpreter/src/interp_native.h
    harmony/enhanced/drlvm/trunk/vm/interpreter/src/interp_vm_helpers.h

Modified: harmony/enhanced/drlvm/trunk/vm/interpreter/src/interp_defs.h
URL: http://svn.apache.org/viewvc/harmony/enhanced/drlvm/trunk/vm/interpreter/src/interp_defs.h?view=diff&rev=536108&r1=536107&r2=536108
==============================================================================
--- harmony/enhanced/drlvm/trunk/vm/interpreter/src/interp_defs.h (original)
+++ harmony/enhanced/drlvm/trunk/vm/interpreter/src/interp_defs.h Tue May  8 00:34:10 2007
@@ -1,10 +1,10 @@
-/*
+/**
  *  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
- *  the License.  You may obtain a copy of the License at
+ *  the License. You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
@@ -14,10 +14,14 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  */
-/** 
- * @author Ivan Volosyuk
+/**
  * @version $Revision: 1.23.4.1.4.3 $
- */  
+ */
+
+/**
+ * @file
+ * Major interpreter-related definitions.
+ */
 
 #define LOG_DOMAIN "interpreter.unspecified"
 #include "cxxlog.h"
@@ -30,29 +34,60 @@
 #include "jvmti_types.h"
 
 //#define INTERPRETER_DEEP_DEBUG
+/** \def DEBUG_PRINT(a)
+  * \brief Calls <code>TRACE2</code> with the interpreter category.*/
 #define DEBUG_PRINT(a) TRACE2("interpreter", a)
 
+/** \def DEBUG(a)
+  * \brief Does nothing.*/
 #define DEBUG(a)
 
 #ifdef NDEBUG
+/** \def DEBUG_BYTECODE(a)
+  * \brief If <code>DEBUG</code> is off, does nothing.*/
 #  define DEBUG_BYTECODE(a)
 #else
+/** \def DEBUG_BYTECODE(a)
+  * \brief If <code>DEBUG</code> is on, calls DEBUG_PRINT(a).*/
 #  define DEBUG_BYTECODE(a) { if (frame.dump_bytecodes)  DEBUG_PRINT(a); }
 #endif
+
+/** \def DEBUG_GC(a)
+  * \brief Calls <code>TRACE2</code> with the <code>gc_interpreter</code>
+  * category.
+  */
 #define DEBUG_GC(a)             TRACE2("gc_interpreter", a)
 
+/** \def DEBUG2(a)
+  * \brief Calls <code>INFO(a)</code>.*/
 #define DEBUG2(a) INFO(a)
-
+/** <code>TRUE</code> if the interpreter enables debug.*/
 extern bool interpreter_enable_debug;
+
+/** \def DEBUG_TRACE_PLAIN(a) 
+  * \brief Calls <code>TRACE2</code> with the interpreter category.*/
 #define DEBUG_TRACE_PLAIN(a)    TRACE2("interpreter", a)
+
+/** \def DEBUG_TRACE(a)
+  * \brief Calls <code>TRACE2</code> with the <code>folded_interpreter</code>
+  * category.*/
 #define DEBUG_TRACE(a)          TRACE2("folded_interpreter", a)
 
+/** \def ASSERT_TAGS(a)
+  * \brief Does nothing.*/
 #define ASSERT_TAGS(a)
 
+/** \def ASSERT_OBJECT(a)
+  * \brief Checks the object.*/
 #define ASSERT_OBJECT(a) assert((a == 0) || ((*((a)->vt()->clss->get_class_handle()))->vt()->clss
== VM_Global_State::loader_env->JavaLangClass_Class))
 
 #ifndef INTERPRETER_USE_MALLOC_ALLOCATION
+/** \def ALLOC_FRAME(sz)
+  * \brief Calls <code>alloca(sz)</code>.*/
 #define ALLOC_FRAME(sz) alloca(sz)
+/** \def FREE_FRAME(ptr)
+  * \brief If <code>INTERPRETER_USE_MALLOC_ALLOCATION</code> is on, does
+  * nothing.*/
 #define FREE_FRAME(ptr)
 #else
 #define ALLOC_FRAME(sz) m_malloc(sz)
@@ -76,158 +111,377 @@
 #  endif
 #else
 // no define for: COMPACT_FIELDS
+/** The unsigned <code>int</code> value */
 #    define uword uint32
+/** The signed <code>int</code> value */
 #    define word int32
-
+/** The compressed reference */
 #    define CREF uint32
 #    define PTR32
 #endif
 
 #ifdef COMPRESS_MODE
-
+/** \def COMPRESS_REF(ref)
+  * \brief Calls <code>compress_reference(ref)</code>.*/
 #define COMPRESS_REF(ref) compress_reference(ref)
+/** \def UNCOMPRESS_REF(cref)
+  * \brief Calls <code>uncompress_compressed_reference(cref)</code>.*/
 #define UNCOMPRESS_REF(cref) uncompress_compressed_reference(cref)
 
 #else /* ! COMPRESS_MODE */
 
+/**
+ * The fake compressed reference.
+ * 
+ * @param[in] obj - the object to compress
+ * @return The compressed reference.
+ */
 static inline CREF
 fake_compress_reference(ManagedObject *obj) {
     return (CREF) obj;
 }
+
+/**
+ * Uncompresses the compressed reference.
+ * 
+ * @param[in] compressed_ref - the compressed reference
+ * @return The uncompressed reference.
+ */
 static inline ManagedObject*
 fake_uncompress_compressed_reference(CREF compressed_ref) {
     return (ManagedObject*) compressed_ref;
 }
 
+/** \def COMPRESS_REF(ref)
+  * \brief Calls <code>fake_compress_reference(ref)</code>.*/
 #define COMPRESS_REF(ref) fake_compress_reference(ref)
+/** \def UNCOMPRESS_REF(cref)
+  * \brief Calls <code>fake_uncompress_compressed_reference(cref)</code>.*/
 #define UNCOMPRESS_REF(cref) fake_uncompress_compressed_reference(cref)
 
 #endif
 
-// Defines byte ordering in Value2 in different situations
-#define s0 1 // stack val, NOTE: Values on java stack placed in reversed order
-#define s1 0 // so that reversed copy in function call to work correctly
-#define l0 0 // local val
+/** Defines byte ordering in Value2 in different situations.*/
+
+/** The stack value.
+ * @note Values on the java stack are placed in the reversed order, so that the
+ *       reversed copy in the function call works correctly.*/
+#define s0 1 
+#define s1 0 
+/** The local value.*/
+#define l0 0
+/** The local value.*/
 #define l1 1
-#define c0 0 // const val
+/** The constant value.*/
+#define c0 0
+/** The constant value.*/
 #define c1 1
-#define a0 0 // arg val
+/** The argument value.*/
+#define a0 0
+/** The argument value.*/
 #define a1 1
-#define ar0 0 // array val
+/** The array value.*/
+#define ar0 0
+/** The array value.*/
 #define ar1 1
+/** The result value.*/
 #define res0 1
+/** The result value.*/
 #define res1 0
 
-
+/** Holds 32-bit values.*/
 union Value {
+/** The unsigned integer value.*/
     uint32 u;
+/** The integer value.*/
     int32 i;
+/** The float value.*/
     float f;
+/** The compressed reference.*/
     CREF cr;
 };
 
+/** Holds 64-bit values */
 union Value2 {
 #ifdef PTR32
+/** Two 32-bit values */
     Value v[2];
 #else
     Value v0;
 #endif
+/** The long-long value.*/
     int64 i64;
+/** The unsigned long-long value */
     uint64 u64;
+/** The double value */
     double d;
 };
 
+/** The local variable types.*/
 enum {
+/** The element of stack or local variables that is not an object.*/
     FLAG_NONE = 0,
+/** The container for the return address from a subroutine.*/
     FLAG_RET_ADDR = 2,
+/** The containter for an object reference.*/
     FLAG_OBJECT = 3
 };
 
+/** The <code>pop_frame</code> states.*/
 enum PopFrameState {
+/** Indicates that the frame cannot be popped.*/
     POP_FRAME_UNAVAILABLE,
+/** Indicates that the frame can be popped.*/
     POP_FRAME_AVAILABLE,
+/** Indicates that the frame is being popped.*/
     POP_FRAME_NOW
 };
 
+/**
+ * @brief %The stack for executing the Java method.
+ *
+ * This structure contains a set of operations specific for the Java stack.
+ */
+
 class Stack {
+/** The stack element value.*/
     Value *data;
+/** The value to the object reference.*/
     uint8 *refs;
+/** The number of elements on the stack.*/
     int32 index;
+/** The stack size.*/
     int32 size;
 
     public:
+/** The empty constructor.*/
     inline Stack() {}
+/** The destructor.*/
     inline ~Stack();
 
+/**
+ * Initializes the stack of a method.
+ * 
+ * @param[in] ptr  - the pointer to the data
+ * @param[in] size - the stack size
+ */
     inline void init(void *ptr, int size);
 
-    // get reference to value on top of stack
+/**
+ * Returns the reference to the value on the top of the stack.
+ * 
+ * @param[in] offset - the offset value
+ * @return The reference to the value on the top of the stack.
+ */
     inline Value& pick(int offset = 0);
 
-    // set/reset value to be object reference
+/**
+ * Sets and resets the value to the object reference.
+ * 
+ * @param[in] offset - the offset value
+ * @return The value to the object reference.
+ */
     inline uint8& ref(int offset = 0);
-
-    // just move stack pointer
+    
+/**
+ * Only moves the stack pointer.
+ * 
+ * @param[in] size - the size value
+ */
     inline void push(int size = 1);
+    
+/**
+ * Decreases the stack pointer.
+ * By default, decreases the pointer by one step or as specified in <i>size</i>.
+ *
+ * @param[in] size - the required size
+ */
     inline void pop(int size = 1);
+
+/**
+ * Is similar to pop().
+ * Does the same as pop() and clears the type value associated with
+ * every cleared stack element via the ref() function.
+ *
+ * @param[in] size - the required size
+ */
     inline void popClearRef(int size = 1);
 
+/**
+ * Sets the value of an object of the <code>Long</code> or <code>Double</code>
type
+ * contained in two adjacent stack elements.
+ * 
+ * @param[in] idx - the pointer to the stack depth of the <code>Long</code> value
+ * @param[in] val - the <code>Long</code> value
+ */
     inline void setLong(int idx, Value2 val);
+
+/**
+ * Returns the <code>Long</code> value located at the depth specified by <i>idx</i>.
+ *
+ * @param[in] idx - the value identifier
+ * @return The <code>Long</code> value.
+ */
     inline Value2 getLong(int idx);
 
-    // Clear stack
+/** Clears the stack.*/
     inline void clear();
 
+/**
+ * Returns the size of the allocated stack area by the elements' size.
+ * 
+ * @param[in] size - the size in elements
+ * @return The size of the allocated area.
+ */
     static inline int getStorageSize(int size);
+
+/**
+ * Returns the number of elements on the stack.
+ * 
+ * @return The number of elements on the stack.
+ */
     inline int getIndex() { return index + 1; }
+
+/**
+ * Enumerates references associated with the thread.
+ * 
+ * @param[in] VM_thread - the pointer to the thread
+ */
     friend void interp_enumerate_root_set_single_thread_on_stack(VM_thread*);
+
+/**
+ * Enumerates references associated with the thread.
+ * 
+ * @param[in] ti_env    - the pointer to the jvmti environment
+ * @param[in] VM_thread - the pointer to the thread
+ */
     friend void interp_ti_enumerate_root_set_single_thread_on_stack(jvmtiEnv* ti_env, VM_thread
*thread);
 };
 
+/** The storage for local variables of the executed Java method.*/
 class Locals {
+    // local variable value
     Value *var;
+    // references to the local variable type
     uint8 *refs;
+    // locals size
     uint32 varNum;
 
     public:
+/** The empty constructor.*/
     inline Locals() {}
+/** The desctructor.*/
     inline ~Locals();
 
+/**
+ * Initializes the stack of a method.
+ * 
+ * @param[in] ptr  - the pointer to the data
+ * @param[in] size - the locals size value
+ */
     inline void init(void *ptr, uint32 size);
+
+/**
+ * Returns the reference to the local variable of the specifie ID.
+ * 
+ * @param[in] id - the local variable ID
+ * @return The reference to the requested local variable.
+ */
     inline Value& operator () (uint32 id);
+
+/**
+ * Sets the value of an object of the <code>Long</code> or <code>Double</code>
+ * type contained in two adjacent elements.
+ *
+ * @param[in] idx - the local variable number
+ * @param[in] val - the local variable value
+ */
     inline void setLong(int idx, Value2 val);
+
+/**
+ * Returns the value of an object of the <code>Long</code> or <code>Double</code>
+ * type contained in two adjacent elements.
+ *
+ * @param[in] idx - the local variable number
+ * @return The requested object value.
+ */
     inline Value2 getLong(int idx);
 
+/**
+ * Returns the reference to the type of the local variable.
+ * 
+ * @param[in] idx - the local variable number
+ * @return The reference to the local variable type.
+ * @sa     FLAG_NONE, FLAG_RET_ADDR, FLAG_OBJECT
+ */
     inline uint8& ref(uint32 id);
 
+/**
+ * Returns the size of the allocated locals area by its size in elements.
+ * 
+ * @param[in] size - size of locals area in elements
+ * @return The size of the allocated area.
+ */
     static inline int getStorageSize(int size);
+
+/**
+ * Returns the number of local variables in this object.
+ * 
+ * @return The number of local variables.*/
     inline uint32 getLocalsNumber() { return varNum; }
 
+/**
+ * Enumerates references associated with the thread.
+ * 
+ * @param[in] VM_thread - the pointer to the thread*/
     friend void interp_enumerate_root_set_single_thread_on_stack(VM_thread*);
+
+/**
+ * Enumerates references associated with the thread.
+ * 
+ * @param[in] ti_env    - the pointer to the jvmti environment
+ * @param[in] VM_thread - the pointer to the thread */
     friend void interp_ti_enumerate_root_set_single_thread_on_stack(jvmtiEnv* ti_env, VM_thread
*thread);
 };
 
+/** The list of functions that listen for the <code>PopFrame</code> event.*/
 struct FramePopListener {
+/** The pointer to the listener.*/
     void *listener;
+/** The next element.*/
     FramePopListener *next;
 };
 
+/** The list of monitors locked by this method.*/
 struct MonitorList {
+/** The pointer to the monitor.*/
     ManagedObject *monitor;
+/** The next element.*/
     MonitorList *next;
 };
 
+/** The representation of the method being executed.*/
 struct StackFrame {
     public:
+/** The address of the bytecode being executed.*/
     uint8 *ip;
+/** The stack of this method.*/
     Stack stack;
+/** The local variables of this method.*/
     Locals locals;
+/** The pointer to the structure of this method.*/
     Method *method;
+/** The reference to the caller method.*/
     StackFrame *prev;
+/** The list of functions listening for the <code>PopFrame</code> event.*/
     FramePopListener *framePopListener;
+/** <code>This</code> pointer of the method being executed.*/
     ManagedObject *This;
+/** The list of locked monitors.*/
     struct MonitorList *locked_monitors;
+/** The auxiliary structure for storing available monitor structures.*/
     struct MonitorList *free_monitors;
+/** The method state: whether the JVMTI frame pop can be performed on it.*/
     PopFrameState jvmti_pop_frame;
 #ifndef NDEBUG
     bool dump_bytecodes;
@@ -236,54 +490,186 @@
     uint8 last_bytecodes[8];
     int n_last_bytecode;
 #endif
+/** The <code>Exception</code> object that has been thrown and for which
+  * the JVMTI <code>Exception</code> (?) event has been sent.*/
     ManagedObject *exc;
+/** The <code>Exception</code> object that has been caught and for which
+  * the JVMTI <code>ExceptionCaught</code> (?) event has been sent.*/
     ManagedObject *exc_catch;
 };
 
-/********* PROTOTYPES ********/
+/**
+ * \defgroup Prototypes Prototypes
+ */
+/*@{*/
+
+/**
+ * The function for interpreter breakpoint processing.
+ *
+ * @param[in] frame - the method ID*/
 extern uint8 Opcode_BREAKPOINT(StackFrame& frame);
+
+/**
+ * Enumerates references associated with the thread.
+ * 
+ * @param[in] VM_thread - the pointer to the thread*/
 extern void interp_enumerate_root_set_single_thread_on_stack(VM_thread*);
+
+/**
+ * Executes the native method.
+ *
+ * @param[in] method        - the native-method structure pointer
+ * @param[out] return_value - the return value pointer
+ * @param[in] args          - the method arguments pointer*/
 extern void interpreter_execute_native_method(
         Method *method, jvalue *return_value, jvalue *args);
+
+/**
+ * Calls the static native method.
+ * 
+ * @param[in] prevFrame - the previous frame pointer
+ * @param[in] frame     - the frame pointer
+ * @param[in] method    - the native-method structure pointer*/
 extern void interpreterInvokeStaticNative(
         StackFrame& prevFrame, StackFrame& frame, Method *method);
+
+/**
+ * Calls the virtual native method.
+ * 
+ * @param[in] prevFrame - the previous frame pointer
+ * @param[in] frame     - the frame pointer
+ * @param[in] method    - the method structure pointer*/
 extern void interpreterInvokeVirtualNative(
         StackFrame& prevFrame, StackFrame& frame, Method *method, int sz);
 
+/**
+ * Executes the method.
+ * 
+ * @param[in] method        - the method structure pointer
+ * @param[out] return_value - the return value pointer
+ * @param[in] args          - the method arguments pointer*/
 extern void interpreter_execute_method(
         Method *method, jvalue *return_value, jvalue *args);
 
+
+/**
+ * Processes method entry events.
+ * 
+ * @param[in] method - the method structure pointer*/
 void method_entry_callback(Method *method);
+
+/**
+ * Processes method exit events.
+ * 
+ * @param[in] method                  - the method structure pointer
+ * @param[in] was_popped_by_exception - if was popped by exception
+ * @param[in] ret_val                 - the return value pointer*/
 void method_exit_callback(Method *method, bool was_popped_by_exception, jvalue ret_val);
+
+/**
+ * Processes method exit events.
+ * 
+ * @param[in] method - the method structure pointer
+ * @param[in] frame  - the frame pointer*/
 void method_exit_callback_with_frame(Method *method, StackFrame& frame);
+
+/**
+ * Processes the field modification event.
+ * 
+ * @param[in] field - the field structure pointer
+ * @param[in] frame - the frame pointer*/
 void putfield_callback(Field *field, StackFrame& frame);
+
+/**
+ * Processes the field modification event.
+ * 
+ * @param[in] field - the field structure pointer
+ * @param[in] frame - the frame pointer*/
 void getfield_callback(Field *field, StackFrame& frame);
+
+/**
+ * Processes the field modification event.
+ * 
+ * @param[in] field - the field structure pointer
+ * @param[in] frame - the frame pointer*/
 void putstatic_callback(Field *field, StackFrame& frame);
+
+/**
+ * Processes the field modification event.
+ * 
+ * @param[in] field - the field structure pointer
+ * @param[in] frame - the frame pointer*/
 void getstatic_callback(Field *field, StackFrame& frame);
+
+/**
+ * Processes the frame pop event.
+ * 
+ * @param[in] l                       - the pointer to the list of functions that
+ *                                      listen for the <code>PopFrame</code>
event
+ * @param[in] method                  - the pointer to the method structure
+ * @param[in] was_popped_by_exception - if <code>was_popped_by_exception</code>*/
 void frame_pop_callback(FramePopListener *l, Method *method, jboolean was_popped_by_exception);
+
+/**
+ * Processes the single step event.
+ * 
+ * @param[in] frame - the frame pointer*/
 void single_step_callback(StackFrame &frame);
+
+/**
+ * Finds the exception handler.
+ * 
+ * @param[in] frame     - the frame pointer
+ * @param[in] exception - the exception pointer
+ * @param[in] h -       - the pointer to the representation of a catch block in
+ *                        a method's code array
+ * @return <code>TRUE</code> on success.*/
 bool findExceptionHandler(StackFrame& frame, ManagedObject **exception, Handler **h);
+
+/**
+ * Loads method handled exceptions.
+ * 
+ * @param[in] method - the method structure pointer
+ * @return <code>TRUE</code> on success.*/
 bool load_method_handled_exceptions(Method *m);
+/*@}*/
 
-/********* INLINE FUNCTIONS *******/
+/**
+ * \defgroup Inlines Inline Functions
+ */
+/*@{*/
+
+/**
+ * Returns the last stack frame.
+ * 
+ * @return The last stack frame.*/
 static inline StackFrame*
 getLastStackFrame() {
     return (StackFrame*)get_thread_ptr()->lastFrame;
 }
 
+/**
+ * Returns the last stack frame.
+ * 
+ * @param[in] thread - the thread pointer
+ * @return The last stack frame.*/
 static inline StackFrame*
 getLastStackFrame(VM_thread *thread) {
     return (StackFrame*)(thread->lastFrame);
 }
-
+/** The interpreter states.*/
 enum interpreter_state {
     INTERP_STATE_STACK_OVERFLOW = 1
 };
 
+/**
+ * Sets the last stack frame.
+ *
+ * @param[in] frame - the frame pointer*/
 static inline void setLastStackFrame(StackFrame *frame) {
     get_thread_ptr()->lastFrame = frame;
 }
-
+/*@}*/
 void
 Stack::init(void *ptr, int sz) {
     data = (Value*)ptr;
@@ -413,7 +799,7 @@
     return (size * (sizeof(Value) + sizeof(uint8)) + 7) & ~7;
 }
 
-// Setup locals and stack on C stack.
+/** Sets up locals and stack on the C stack.*/
 #define SETUP_LOCALS_AND_STACK(frame,method)                   \
     int max_stack = method->get_max_stack();                   \
     frame.stack.init(ALLOC_FRAME(                              \
@@ -422,20 +808,30 @@
     frame.locals.init(ALLOC_FRAME(                             \
                 Locals::getStorageSize(max_locals)), max_locals)
 
+/** The interpreter jvmti events.*/
 enum interpreter_ti_events {
+/** The method entry event.*/
     INTERPRETER_TI_METHOD_ENTRY_EVENT = 1,
+/** The method exit event.*/
     INTERPRETER_TI_METHOD_EXIT_EVENT  = 2,
+/** The single step event.*/
     INTERPRETER_TI_SINGLE_STEP_EVENT  = 4,
+/** The pop-frame event.*/
     INTERPRETER_TI_POP_FRAME_EVENT = 8,
+/** The field access event.*/
     INTERPRETER_TI_FIELD_ACCESS = 16,
+/** The field modification event.*/
     INTERPRETER_TI_FIELD_MODIFICATION = 32,
+/** For other events.*/
     INTERPRETER_TI_OTHER = 64 /* EXCEPTION, EXCEPTION_CATCH */
 };
 
 /**
- * Global flags section.
+ * The global flags' section.
  *
- *  Bitwise or of enabled interpreter_ti_events:
+ * Bitwise or of enabled <code>interpreter_ti_events</code>
  */
 extern int interpreter_ti_notification_mode;
+
+
 

Modified: harmony/enhanced/drlvm/trunk/vm/interpreter/src/interp_native.h
URL: http://svn.apache.org/viewvc/harmony/enhanced/drlvm/trunk/vm/interpreter/src/interp_native.h?view=diff&rev=536108&r1=536107&r2=536108
==============================================================================
--- harmony/enhanced/drlvm/trunk/vm/interpreter/src/interp_native.h (original)
+++ harmony/enhanced/drlvm/trunk/vm/interpreter/src/interp_native.h Tue May  8 00:34:10 2007
@@ -1,10 +1,10 @@
-/*
+/**
  *  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
- *  the License.  You may obtain a copy of the License at
+ *  the License. You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
@@ -14,10 +14,16 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  */
-/** 
+/**
  * @author Ivan Volosyuk
  * @version $Revision: 1.8.4.2.4.3 $
  */
+
+/**
+ * @file
+ * Defines native-related macros and functions used by the interpreter.
+ */
+
 #include "vm_core_types.h"
 
 #ifdef _IPF_
@@ -28,11 +34,23 @@
 #include "../m2n_ia32_internal.h"
 #endif
 
+/**
+ * Enumerates thread-assocciated references that are not stored on the
+ * thread's stack.
+ *
+ * @param[in] thread - the thread pointer
+ */
 extern void
 vm_enumerate_root_set_single_thread_not_on_stack(VM_thread * thread);
-extern VMEXPORT void free_local_object_handles2(ObjectHandles * head);
 
+/**
+ * Frees and deletes all local object handles.
+ *
+ * @param[in] head - the object handles pointer
+ */
+extern VMEXPORT void free_local_object_handles2(ObjectHandles * head);
 
+/** Allocates memory.*/
 #define M2N_ALLOC_MACRO                                     \
     assert(!hythread_is_suspend_enabled());                      \
     M2nFrame m2n;                                           \
@@ -49,11 +67,19 @@
     handles.nw.next = 0;                                    \
     m2n_set_local_handles(&m2n, (ObjectHandles*)&handles)
 
+/** Frees memory.*/
 #define M2N_FREE_MACRO                                      \
     assert(!hythread_is_suspend_enabled());                      \
     free_local_object_handles2(m2n_get_local_handles(&m2n));\
     m2n_set_last_frame(m2n_get_previous_frame(&m2n))
 
-
+/**
+ * Looks up the implementation for the native method.
+ *
+ * @param[in] method - the searching native-method structure
+ * @return The pointer to find the native function.
+ */
 GenericFunctionPointer interpreterGetNativeMethodAddr(Method*);
+
+
 

Modified: harmony/enhanced/drlvm/trunk/vm/interpreter/src/interp_vm_helpers.h
URL: http://svn.apache.org/viewvc/harmony/enhanced/drlvm/trunk/vm/interpreter/src/interp_vm_helpers.h?view=diff&rev=536108&r1=536107&r2=536108
==============================================================================
--- harmony/enhanced/drlvm/trunk/vm/interpreter/src/interp_vm_helpers.h (original)
+++ harmony/enhanced/drlvm/trunk/vm/interpreter/src/interp_vm_helpers.h Tue May  8 00:34:10
2007
@@ -1,10 +1,10 @@
-/*
+/**
  *  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
- *  the License.  You may obtain a copy of the License at
+ *  the License. You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
@@ -14,78 +14,144 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  */
-/** 
+/**
  * @author Ivan Volosyuk
  * @version $Revision: 1.2.12.2.4.3 $
- */  
+ */
+
+/**
+ * @file
+ * Defines helper interfaces used by the interpreter.
+ *
+ * The current DRLVM implementation describes the following helper interfaces:
+ * <ul>
+ * <li>resolving handling functionality</li>
+ * <li>exceptions handling functionality</li>
+ * </ul>
+ */
 
 #include "vm_core_types.h"
 #include "Class.h"
 
 /**
- * Set thread-local exception with name 'exc'.
+ * Sets the thread-local exception with the name <code>exc</code>.
+ *
+ * @param[in] exc - the exception name
  */
 void interp_throw_exception(const char* exc);
 
 /**
- * Set thread-local exception with name 'exc' and 'message'.
+ * Sets the thread-local exception with the names <code>exc</code> and
+ * <code>message</code>.
+ *
+ * @param[in] exc     - the exception name
+ * @param[in] message - the message
  */
 void interp_throw_exception(const char* exc, const char *message);
 
 /**
- * Looks up implementation for native method
+ * Looks up the implementation for the native method.
+ *
+ * @param[in] method - the searching native-method structure
+ * @return The pointer to find the native function.
  */
 GenericFunctionPointer interp_find_native(Method_Handle method);
 
 /**
- * Resolve class in constant pool of 'clazz' with index = 'classId'. Throw
- * exception if resolution error.
+ * Resolves the class in the <code>clazz</code> constant pool with the index
+ * <code>classId</code>. Throws an exception if a resolution error occurs.
+ *
+ * @param[in] clazz   - the class which constant pool contains the reference to
+ *                      the target class
+ * @param[in] classId - the constant-pool index
+ * @return A resolved class, if a resolution attempt succeeds.
  */
 Class* interp_resolve_class(Class *clazz, int classId);
 
 /**
- * Resolve class suitable for new operation in constant pool of 'clazz' with
- * index = 'classId'. Throw exception if resolution error.
+ * Resolves the class suitable for a new operation in the <code>clazz</code>
+ * constant pool with the index <code>classId</code>. Throws an exception if
+ * a resolution error occurs.
+ *
+ * @param[in] clazz   - the class which constant pool contains the reference to
+ *                      the target class
+ * @param[in] classId - the constant-pool index
+ * @return A resolved class, if a resolution attempt succeeds.
  */
 Class* interp_resolve_class_new(Class *clazz, int classId);
 
 /**
- * Resolve static field in constant pool of 'clazz' with index = 'fieldId'.
- * Throw exception if resolution error.
+ * Resolves the static field in the <code>clazz</code> constant pool with the
+ * index <code>fieldId</code>. Throws an exception if a resolution error occurs.
+ *
+ * @param[in] clazz    - the class which constant pool contains the reference
+ *                       to the target field
+ * @param[in] fieldId  - the constant-pool index
+ * @param[in] putfield - location where to put/get the field
+ * @return A resolved field, if a resolution attempt succeeds.
  */
 Field* interp_resolve_static_field(Class *clazz, int fieldId, bool putfield);
 
 /**
- * Resolve nonstatic field in constant pool of 'clazz' with index = 'fieldId'.
- * Throw exception if resolution error.
+ * Resolves the nonstatic field in the <code>clazz</code> constant pool with
the
+ * index <code>fieldId</code>. Throws an exception if a resolution error occurs.
+ *
+ * @param[in] clazz    - the class which constant pool contains the reference
+ *                       to the target field
+ * @param[in] fieldId  - the constant-pool index
+ * @param[in] putfield - location where to put/get thee field
+ * @return A resolved field, if a resolution attempt succeeds.
  */
 Field* interp_resolve_nonstatic_field(Class *clazz, int fieldId, bool putfield);
 
 /**
- * Resolve virtual method in constant pool of 'clazz' with index = 'methodId'.
- * Throw exception if resolution error.
+ * Resolves the virtual method in the <code>clazz</code> constant pool with the
+ * index <code>methodId</code>. Throws an exception if a resolution error occurs.
+ *
+ * @param[in] clazz       - the class which constant pool contains the reference
+ *                          to the method
+ * @param[in] methodId    - the constant-pool index
+ * @return A resolved method, if a resolution attempt succeeds.
  */
 Method* interp_resolve_virtual_method(Class *clazz, int methodId);
 
 /**
- * Resolve interface method in constant pool of 'clazz' with index = 'methodId'.
- * Throw exception if resolution error.
- */
+ * Resolves the interface method in the <code>clazz</code> constant pool with
+ * the index <code>methodId</code>. Throws an exception if a resolution error
+ * occurs.
+ *
+ * @param[in] clazz    - the class which constant pool contains the reference
+ *                       to the method
+ * @param[in] methodId - the constant-pool index
+ * @return A resolved method, if a resolution attempt succeeds.*/
 Method* interp_resolve_interface_method(Class *clazz, int methodId);
 
 /**
- * Resolve virtual method in constant pool of 'clazz' with index = 'methodId'.
- * Throw exception if resolution error.
+ * Resolves the static method in the <code>clazz</code> constant pool with the
+ * index <code>methodId</code>. Throws an exception if a resolution error
+ * occurs.
+ *
+ * @param[in] clazz    - the class which constant pool contains the reference
+ *                       to the method
+ * @param[in] methodId - the constant-pool index
+ * @return A resolved method, if a resolution attempt succeeds.
  */
 Method* interp_resolve_static_method(Class *clazz, int methodId);
 
 /**
- * Resolve virtual method in constant pool of 'clazz' with index = 'methodId'.
- * Throw exception if resolution error.
- */
+ * Resolves the special method in the <code>clazz</code> constant pool with the
+ * index <code>methodId</code>. Throws an exception if a resolution error occurs.
+ *
+ * @param[in] clazz    - the class which constant pool contains the reference
+ *                       to the method
+ * @param[in] methodId - the constant pool index
+ * @return A resolved method, if a resolution attempt succeeds.*/
 Method* interp_resolve_special_method(Class *clazz, int methodId);
 
 /**
- * Resolve array of class for specified objClass.
+ * Resolves the class array for specified <code>objClass</code>.
+ *
+ * @param[in] objClass - specified <code>objClass</code>
+ * @return A resolved array if a resolution attempt succeeds.
  */
 Class* interp_class_get_array_of_class(Class *objClass);



Mime
View raw message