Index: include/interpreter.h =================================================================== --- include/interpreter.h (revision 521647) +++ include/interpreter.h (working copy) @@ -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.1.2.1.4.3 $ - */ + */ + +/** + * @file + * Interpreter header file.The interpreter component executes bytecode and is used in the VM interchangeably with the JIT compiler. + * In the current implementation, the interpreter is mainly used to simplify debugging. The interpreter also enables VM portability because most of its code is platform-independent. + */ #ifndef _INTERPRETER_H_ #define _INTERPRETER_H_ @@ -25,8 +31,16 @@ #include "stack_trace.h" #include "interpreter_exports.h" +/** + * Returns TRUE if the interpreter is enabled. + * + * @return TRUE on success. + */ extern bool interpreter_enabled(); +/** + * If the interpreter is enabled, aborts execution. + * */ #define ASSERT_NO_INTERPRETER assert(!interpreter_enabled()); #endif Index: include/interpreter_exports.h =================================================================== --- include/interpreter_exports.h (revision 521647) +++ include/interpreter_exports.h (working copy) @@ -1,4 +1,4 @@ -/* +/** * 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. @@ -15,6 +15,10 @@ * limitations under the License. */ +/** + * @file + * Export Interfaces provided by the interpreter. In the current DRLVM implementation the interpreter exports its enumeration, stack trace generation and JVMTI support functions via a single method table making up the Interpreter interface.*/ + #ifndef _INTERPRETER_EXPORTS_H_ #define _INTERPRETER_EXPORTS_H_ @@ -23,86 +27,299 @@ typedef struct FrameHandle FrameHandle; +/** + * @ingroup + * Interpreter table + */ + typedef struct { + +/** + * Fills the stack trace frame at the given depth for the current thread. + * + * @param[in] target_depth - the zero-based depth of the frame or inlined method, + * information about which will be stored at the given + * stack trace frame, stf + * @param[out] stf - the pointer to the StackTraceFrame + * structure that needs to be filled with the data on + * the frame or inlined method corresponding to the + * given depth + * @return TRUE on success, FALSE if the depth is greater than + * or equal to the current thread stack trace length.*/ bool (*interpreter_st_get_frame) (unsigned target_depth, struct StackTraceFrame* stf); + +/** + * Fills the stack trace frames for the specified number of frames of the specified thread. + * + * @param[in] thread - the pointer to the thread + * @param[in] res_depth - the number of frames including inlined methods, + * information about which should be stored + * @param[out] stfs - the pointer to the array of stack trace frames + * created by this function and returned via this pointer + * @note The caller is responsible for freeing the memory.*/ void (*interpreter_st_get_trace) (class VM_thread *thread, unsigned* res_depth, struct StackTraceFrame** stfs); + +/** + * Enumerates references associated with the thread. + * + * @param thread - the pointer to the thread*/ void (*interpreter_enumerate_thread) (class VM_thread *thread); +/** + * Returns the last frame. + * + * @param thread - the pointer to the thread + * @return The pointer to the last frame.*/ FrameHandle* (*interpreter_get_last_frame) (class VM_thread *thread); + +/** Returns the previous frame. + * + * @param frame - the pointer to the frame + * @return The pointer to the previous frame.*/ FrameHandle* (*interpreter_get_prev_frame) (FrameHandle* frame); + +/** + * Returns the frame method. + * + * @param frame - the pointer to the frame + * @return The pointer to the method.*/ Method_Handle (*interpreter_get_frame_method) (FrameHandle* frame); + +/** + * Returns the pointer to the bytecode. + * + * @param frame - the pointer to the frame + * @return The pointer to the bytecode.*/ uint8* (*interpreter_get_frame_bytecode_ptr) (FrameHandle* frame); // 'end' is not inclusive + +/** + * Returns TRUE if the frame is native. + * + * @param frame - the pointer to the frame + * @param begin - the pointer to the register + * @param end - the pointer to the register + * @return TRUE on success.*/ bool (*is_frame_in_native_frame) (struct FrameHandle* frame, void* begin, void* end); +/** + * Enumerates references associated with the thread. + * + * @param thread - the pointer to the thread + * @param jvmtiEnv - the pointer to the jvmti environment*/ void (*interpreter_ti_enumerate_thread) (jvmtiEnv*, class VM_thread *thread); #ifdef _IPF_ +/** + * Returns the stacked register address. + * + * @param bsp - the pointer to the register + * @param reg - the register + * @return The stacked register address.*/ uint64* (*interpreter_get_stacked_register_address) (uint64* bsp, unsigned reg); #endif +/** + * Returns the frame location. + * + * @param jvmtiEnv - the pointer to the jvmti environment + * @param thread - the pointer to the thread + * @param depth - the pointer to the depth + * @param _jmethodID - the pointer to the method + * @param jlocation - the pointer to the location + * @return JVMTI_ERROR_NONE - a successfully added notification
+ * JVMTI_ERROR_NO_MORE_FRAMES - depth is too large*/ jvmtiError (*interpreter_ti_getFrameLocation) ( jvmtiEnv*, class VM_thread*, int, struct _jmethodID * *, int64 *); + +/** + * Returns the value of the 32 bit local variable. + * + * @param jvmtiEnv - the pointer to the jvmti environment + * @param thread - the pointer to the thread + * @param depth - the pointer to the depth + * @param slot - the pointer to the slot + * @param value_ptr - the pointer to the value + * @return JVMTI_ERROR_NONE - a successfully added notification
+ * JVMTI_ERROR_NO_MORE_FRAMES - depth is too large
+ * JVMTI_ERROR_OPAQUE_FRAME - no frame
+ * JVMTI_ERROR_INVALID_SLOT - a bad slot
+ * JVMTI_ERROR_TYPE_MISMATCH - an invalid variable type*/ jvmtiError (*interpreter_ti_getLocal32) ( jvmtiEnv*, class VM_thread*, int, int, int *); + +/** + * Returns the value of 64 bit local variable. + * + * @param jvmtiEnv - the pointer to the jvmti environment + * @param thread - the pointer to the thread + * @param depth - the pointer to the depth + * @param slot - the pointer to the slot + * @param value_ptr - the pointer to the value + * @return JVMTI_ERROR_NONE - a successfully added notification
+ * JVMTI_ERROR_NO_MORE_FRAMES - depth is too large
+ * JVMTI_ERROR_OPAQUE_FRAME - no frame
+ * JVMTI_ERROR_INVALID_SLOT - a bad slot
+ * JVMTI_ERROR_TYPE_MISMATCH - an invalid variable type*/ jvmtiError (*interpreter_ti_getLocal64) ( jvmtiEnv*, class VM_thread*, int, int, int64 *); + +/** + * Returns the value of the Object type local variable. + * + * @param jvmtiEnv - the pointer to the jvmti environment + * @param thread - the pointer to the thread + * @param depth - the pointer to the depth + * @param slot - the pointer to the slot + * @param value_ptr - the pointer to the value + * @return JVMTI_ERROR_NONE - a successfully added notification
+ * JVMTI_ERROR_NO_MORE_FRAMES - depth is too large
+ * JVMTI_ERROR_OPAQUE_FRAME - no frame
+ * JVMTI_ERROR_INVALID_SLOT - a bad slot
+ * JVMTI_ERROR_TYPE_MISMATCH - an invalid variable type*/ jvmtiError (*interpreter_ti_getObject) ( jvmtiEnv*, class VM_thread*, int, int, struct _jobject * *); + +/** + * Returns stack trace data. + * + * @param jvmtiEnv - the pointer to the jvmti environment + * @param thread - the pointer to the thread + * @param start_depth - the pointer to the depth + * @param max_frame_count - the pointer to max_frame_count + * @param frame_buffer - the pointer to frame_buffer + * @param count_ptr - the pointer to the count + * @return JVMTI_ERROR_NONE - a successfully added notification
+ * JVMTI_ERROR_ILLEGAL_ARGUMENT - bad arguments*/ jvmtiError (*interpreter_ti_getStackTrace) (jvmtiEnv*, class VM_thread*, int, int, jvmtiFrameInfo*, int *); + +/** + * Returns frame count. + * + * @param jvmtiEnv - the pointer to the jvmti environment + * @param thread - the pointer to the thread + * @param count_ptr[out] - the pointer to the count + * @return JVMTI_ERROR_NONE - a successfully added notification*/ jvmtiError (*interpreter_ti_get_frame_count) ( jvmtiEnv*, class VM_thread*, int *); + +/** + * Sets the value of 32 bit local variable. + * + * @param jvmtiEnv - the pointer to the jvmti environment + * @param thread - the pointer to the thread + * @param depth - the pointer to the depth + * @param slot - the pointer to the slot + * @param value_ptr - the pointer to the value + * @return JVMTI_ERROR_NONE - a successfully added notification
+ * JVMTI_ERROR_NO_MORE_FRAMES - depth is too large
+ * JVMTI_ERROR_OPAQUE_FRAME - no frame
+ * JVMTI_ERROR_INVALID_SLOT - a bad slot
+ * JVMTI_ERROR_TYPE_MISMATCH - an invalid variable type*/ jvmtiError (*interpreter_ti_setLocal32) ( jvmtiEnv*, class VM_thread*, int, int, int); + +/** + * Sets the value of 64 bit local variable. + * + * @param jvmtiEnv - the pointer to the jvmti environment + * @param thread - the pointer to the thread + * @param depth - the pointer to the depth + * @param slot - the pointer to the slot + * @param value_ptr - the pointer to the value + * @return JVMTI_ERROR_NONE - a successfully added notification
+ * JVMTI_ERROR_NO_MORE_FRAMES - depth is too large
+ * JVMTI_ERROR_OPAQUE_FRAME - no frame
+ * JVMTI_ERROR_INVALID_SLOT - a bad slot
+ * JVMTI_ERROR_TYPE_MISMATCH - an invalid variable type
*/ jvmtiError (*interpreter_ti_setLocal64) ( jvmtiEnv*, class VM_thread*, int, int, int64); + +/** + * Sets the value of the Object type local variable. + * + * @param jvmtiEnv - the pointer to the jvmti environment + * @param thread - the pointer to the thread + * @param depth - the pointer to the depth + * @param slot - the pointer to the slot + * @param value_ptr - the pointer to the value + * @return JVMTI_ERROR_NONE - a successfully added notification
+ * JVMTI_ERROR_NO_MORE_FRAMES - depth is too large
+ * JVMTI_ERROR_OPAQUE_FRAME - no frame
+ * JVMTI_ERROR_INVALID_SLOT - a bad slot
+ * JVMTI_ERROR_TYPE_MISMATCH - an invalid variable type*/ jvmtiError (*interpreter_ti_setObject) ( jvmtiEnv*, class VM_thread*, int, int, struct _jobject *); + +/** + * Returns the interrupted method native bit. + * + * @param thread - the pointer to the thread + * @return The interrupted method native bit.*/ unsigned int (*interpreter_st_get_interrupted_method_native_bit) (class VM_thread *); +/** @defgroup group1 Open Interfaces + * Open interfaces.*/ +/*@{*/ - // Open interfaces part begins - - /** - * The function is called when global TI event state is changed. This means - * that atleast one of jvmtiEnv's enabled the event or the event was - * disabled in all enviroments. - * - * @param event_type - jvmti to enable / disable - * @param enable - enable or disable the events in exe. - */ +/** + * The function is called when the global TI event state is changed. This means + * that at least one of jvmtiEnv's enabled the event or the event was + * disabled in all environments. + * + * @param event_type - jvmti to enable/disable + * @param enable - enable or disable the events in exe*/ void (*interpreter_ti_set_notification_mode)(jvmtiEvent event_type, bool enable); - /** - * Set breakpoint in place identified by method and location. - * No more then one breakpoint will be set at any specific place. Handling - * for multiple jvmti environments is done by jvmti framework. - * - * @return Bytecode has been replaced by instrumentation. - */ +/** + * Sets the breakpoint in the place identified by the method and location. + * No more than one breakpoint will be set at any specific place. Handling + * for multiple jvmti environments is done by the jvmti framework. + * + * @return The bytecode has been replaced by instrumentation.*/ jbyte (*interpreter_ti_set_breakpoint)(jmethodID method, jlocation location); - /** - * Clear breakpoint in place identified by method and location. - * Replaced bytecode (returned by interpreter_ti_set_breakpoint(..)) - * is also passed as a parameter. - */ +/** + * Clears the breakpoint in the place identified by the method and location. + * Replaced the bytecode, returned by interpreter_ti_set_breakpoint(..), + * is also passed as a parameter.*/ void (*interpreter_ti_clear_breakpoint)(jmethodID method, jlocation location, jbyte saved); - /** - * Set callback to notify JVMTI about frame pop event. - * - * @return JVMTI_ERROR_NONE - successfully added notification
- * JVMTI_ERROR_OPAQUE_FRAME - frame is native
- * JVMTI_ERROR_NO_MORE_FRAMES - depth too large
- */ +/** + * Sets a callback to notify JVMTI about the frame-pop event. + * + * @return JVMTI_ERROR_NONE - a successfully added notification
+ * JVMTI_ERROR_OPAQUE_FRAME - the frame is native
+ * JVMTI_ERROR_NO_MORE_FRAMES - depth is too large*/ jvmtiError (*interpreter_ti_notify_frame_pop) (jvmtiEnv*, VM_thread *thread, int depth); +/** + * Pops the frame. + * + * @param jvmtiEnv - the pointer to the jvmti environment + * @param thread - the pointer to the thread + * @return JVMTI_ERROR_NONE - a successfully added notification
+ * JVMTI_ERROR_OPAQUE_FRAME - no frame*/ jvmtiError (*interpreter_ti_pop_frame) (jvmtiEnv*, VM_thread *thread); +/** + * Dumps the stack. + * + * @param thread - the pointer to the thread*/ void (*stack_dump) (VM_thread*); } Interpreter; +/*@}*/ + +/** + * Returns the interpreter table. + * + * @return The interpreter table.*/ VMEXPORT Interpreter *interpreter_table(); #ifdef BUILDING_VM extern Interpreter interpreter; + +/** + * Returns TRUE if interpreter table. + * + * @return TRUE on success.*/ extern bool interpreter_enabled(); #endif Index: include/interpreter_imports.h =================================================================== --- include/interpreter_imports.h (revision 521647) +++ include/interpreter_imports.h (working copy) @@ -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.1.2.1.4.3 $ - */ + */ + +/** + * @file + * Import Interfaces used by the interpreter. In the current DRLVM implementation the interpreter import locking, exceptions handling, JVMTI and JNI functionality. + */ + #ifndef _INTERPRETER_IMPORTS_H_ #define _INTERPRETER_IMPORTS_H_ @@ -27,18 +33,66 @@ struct ManagedObject; typedef struct ManagedObject ManagedObject; + +/** + * Gains ownership over a monitor. + * The current thread blocks, if the specified monitor is owned by another thread. + * + * @param[in] obj - the monitor object where the monitor is located*/ VMEXPORT void vm_monitor_enter_wrapper(ManagedObject *obj); + +/** + * Releases ownership over a monitor. + * + * @param[in] obj - the monitor object where the monitor is located*/ VMEXPORT void vm_monitor_exit_wrapper(ManagedObject *obj); + +/** + * Calls the class_throw_linking_error function that throws + * a linking error. + * + * @param[in] ch - the class handle + * @param[in] cp_index - the index in the constant pool + * @param[in] opcode - the opcode of bytecodes*/ VMEXPORT void class_throw_linking_error_for_interpreter(Class_Handle ch, unsigned cp_index, unsigned opcode); +/** + * Returns the JNI environment. + * + * @return The JNI environment associated with this thread.*/ VMEXPORT JNIEnv * get_jni_native_intf(); +/** + * A callback function for interpreter breakpoint processing. + * + * @param[in] method - the method ID + * @param[in] loc - the location*/ VMEXPORT jbyte jvmti_process_interpreter_breakpoint_event(jmethodID method, jlocation loc); + +/** + * Enables single-step event processing. + * + * @param[in] method - the method ID + * @param[in] location - the location*/ VMEXPORT void jvmti_process_single_step_event(jmethodID method, jlocation location); +/** + * Enables frame-pop event processing. + * + * @param[in] env - the jvmti environment + * @param[in] method - the method ID + * @param[in] was_popped_by_exception - if the frame was popped by exception*/ VMEXPORT void jvmti_process_frame_pop_event(jvmtiEnv *env, jmethodID method, jboolean was_popped_by_exception); + +/** + * Looks for a method in native libraries of a class loader. + * + * @param[in] method - a searching native-method structure + * @return The pointer to found a native function. + * @note The function raises UnsatisfiedLinkError with a method name + * in an exception message, if the specified method is not found.*/ VMEXPORT GenericFunctionPointer classloader_find_native(const Method_Handle method); #endif /* _INTERPRETER_IMPORTS_H_ */