harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From var...@apache.org
Subject svn commit: r482152 - in /harmony/enhanced/drlvm/trunk/vm/include/open: ee_em_intf.h em.h em_vm.h
Date Mon, 04 Dec 2006 12:23:56 GMT
Author: varlax
Date: Mon Dec  4 04:23:55 2006
New Revision: 482152

URL: http://svn.apache.org/viewvc?view=rev&rev=482152
Log:
Applied HARMONY-2108 [drlvm][em] Doxygen documentation for public EM interfaces.
Comments only were changed, so just checked compilation.

Modified:
    harmony/enhanced/drlvm/trunk/vm/include/open/ee_em_intf.h
    harmony/enhanced/drlvm/trunk/vm/include/open/em.h
    harmony/enhanced/drlvm/trunk/vm/include/open/em_vm.h

Modified: harmony/enhanced/drlvm/trunk/vm/include/open/ee_em_intf.h
URL: http://svn.apache.org/viewvc/harmony/enhanced/drlvm/trunk/vm/include/open/ee_em_intf.h?view=diff&rev=482152&r1=482151&r2=482152
==============================================================================
--- harmony/enhanced/drlvm/trunk/vm/include/open/ee_em_intf.h (original)
+++ harmony/enhanced/drlvm/trunk/vm/include/open/ee_em_intf.h Mon Dec  4 04:23:55 2006
@@ -21,6 +21,15 @@
 #ifndef _EE_EM_H_
 #define _EE_EM_H_
 
+/**
+ * @file
+ * JIT interface exposed to EM.
+ *
+ * A just-in-time compiler must implement the given functions to
+ * enable EM initialization and de-initialization of JIT compilers or
+ * to enable profile collection or profile usage in JIT.
+ */
+
 #include "open/types.h"
 #include "open/em.h"
 
@@ -29,17 +38,68 @@
 extern "C" {
 #endif
 
-// Called once by EM during JIT initialization
+  /** 
+   * Initializes JIT. 
+   *
+   * 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
+   * @param[in] name  - the persistent JIT name that the compiler uses to separate 
+   *                its configuration settings from the ones of other JITs 
+   */
 JITEXPORT void JIT_init(JIT_Handle jit, const char* name);
 
-// Called once by EM during system shutdown. Optional
+  /**  
+   * De-initializes JIT.
+   *
+   * The given method is called only once per JIT during the system shutdown. 
+   *
+   * @param[in] jit - the handle of JIT to de-initialize
+   *
+   * @note The given method is optional.
+   */
 JITEXPORT void JIT_deinit(JIT_Handle jit);
 
 
-//Optional
+  /**  
+   * Sets the profile access interface to JIT.
+   *
+   * The EM passes the pointer to the profile access interface 
+   * to JIT through the given method.
+   *
+   * @param[in] jit          - the JIT instance to pass the profile access interface to
+   * @param[in] em           - the handle to the EM instance
+   * @param[in] pc_interface - the handle to the profile access interface
+   *
+   * @note The given method is optional. A JIT compiler without profiling
+   *        support does not need this method. 
+   */
 JITEXPORT void JIT_set_profile_access_interface(JIT_Handle jit, EM_Handle em, struct EM_ProfileAccessInterface*
pc_interface);
  
-//Optional
+  /**  
+   * Requests JIT to enable profiling of the specified type.
+   *
+   * EM uses the given method to request JIT to enable profile 
+   * collection or profile usage.
+   * According to the EM request JIT uses or collects the profile defined 
+   * by the <code>role</code> 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
+   *
+   * @return  <code>TRUE</code> if JIT does profiling of the <code>pc</code>
type 
+   *          according the <code>role</code> parameter, <code>FALSE</code>
if profiling is not 
+   *          supported.
+   *
+   * @note The given method is optional. A JIT compiler without profiling
+   *        support does not need this method. 
+   */
 JITEXPORT bool JIT_enable_profiling(JIT_Handle jit, PC_Handle pc, EM_JIT_PC_Role role);
 
 #ifdef __cplusplus

Modified: harmony/enhanced/drlvm/trunk/vm/include/open/em.h
URL: http://svn.apache.org/viewvc/harmony/enhanced/drlvm/trunk/vm/include/open/em.h?view=diff&rev=482152&r1=482151&r2=482152
==============================================================================
--- harmony/enhanced/drlvm/trunk/vm/include/open/em.h (original)
+++ harmony/enhanced/drlvm/trunk/vm/include/open/em.h Mon Dec  4 04:23:55 2006
@@ -21,6 +21,12 @@
 #ifndef _EM_H_
 #define _EM_H_
 
+/**
+ * @file
+ * Data types and handles used in EM interfaces.
+ *
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -28,21 +34,54 @@
 #define OPEN_EM "em"
 #define OPEN_EM_VERSION "1.0"
 
-
+  /**
+   * The handle to the EM instance. 
+   */
 typedef void *EM_Handle;
+  /**
+   * The handle to the JIT instance. 
+   */
 typedef void *JIT_Handle;
+  /** 
+   * The handle to the profile collector instance. 
+   */
 typedef void *PC_Handle;
+  /** 
+   * The handle to the method profile collected by a specific collector. 
+   */
 typedef void *Method_Profile_Handle;
 
-typedef
-enum JIT_Result {
+  /**
+   *  Enumeration of result values can be returned by JIT
+   *  on a method compilation request.
+   */
+typedef enum JIT_Result {
+  /** 
+   * The method compilation has finished successufuly.
+   */
     JIT_SUCCESS,
+  /** 
+   * The method compilation has failed.
+   */
     JIT_FAILURE
 } JIT_Result; //JIT_Result
 
-typedef
-enum EM_JIT_PC_Role {
+  /**
+   *  Enumeration of JIT roles related to profiling.
+   *  EM configures JIT during startup to generate or to 
+   *  use a specific profile collector by providing
+   *  the handle to the profile collector and the role of JIT.
+   */
+typedef enum EM_JIT_PC_Role {
+  /**  
+   * The JIT role is to generate the profile defined 
+   * by the given profile collector type. 
+   */
     EM_JIT_PROFILE_ROLE_GEN=1,
+  /**  
+   * The JIT role is to use the profile defined 
+   * by the given profile collector type.
+   */
     EM_JIT_PROFILE_ROLE_USE=2
 } EM_JIT_PC_Role;
 

Modified: harmony/enhanced/drlvm/trunk/vm/include/open/em_vm.h
URL: http://svn.apache.org/viewvc/harmony/enhanced/drlvm/trunk/vm/include/open/em_vm.h?view=diff&rev=482152&r1=482151&r2=482152
==============================================================================
--- harmony/enhanced/drlvm/trunk/vm/include/open/em_vm.h (original)
+++ harmony/enhanced/drlvm/trunk/vm/include/open/em_vm.h Mon Dec  4 04:23:55 2006
@@ -21,6 +21,14 @@
 #ifndef _EM_VM_H_
 #define _EM_VM_H_
 
+/**
+ * @file
+ * EM interface exposed to VM.
+ *
+ * VM uses the given interface to ask EM to execute and/or compile a method
+ * or to notify EM on profiler thread events.
+ */
+ 
 #include "open/types.h"
 #include "open/em.h"
 #include "jni_types.h"
@@ -29,18 +37,47 @@
 #ifdef __cplusplus
 extern "C" {
 #endif
-
+/// The runtime name of EM_VM interface.
 #   define OPEN_INTF_EM_VM "open.interface.em.vm." OPEN_EM_VERSION
+/// The runtime property name to request if EM needs in profiler thread support.
 #   define OPEN_EM_VM_PROFILER_NEEDS_THREAD_SUPPORT "open.property.em.vm.profiler_needs_thread_support"
+/// The runtime property name to request EM profiler thread timeout.
 #   define OPEN_EM_VM_PROFILER_THREAD_TIMEOUT "open.property.em.vm.profiler_thread_timeout"
 
-
+  /** 
+   * The structure comprises all EM to VM interface methods.
+   */
     struct _OpenEmVm {
 
+  /** 
+   * Requests EM to execute the method.
+   *
+   * VM uses the given method to execute uncompiled methods.
+   * EM is responsible for selecting the appropriate execution engine and 
+   * executing the method using the stub provided by the execution engine.
+   *
+   * @param[in] meth         - the method to execute
+   * @param[in] return_value - the place to store the return value of the method
+   * @param[in] args         - the parameters to be passed to the method
+   */
         void (*ExecuteMethod) (jmethodID meth, jvalue  *return_value, jvalue *args);
 
+  /** 
+   * Requests EM to start the compilation of the method
+   *
+   * VM or JIT method compilation stubs use the given method to 
+   * ask EM to start the method compilation.
+   * EM is responsible for selecting JIT for the given method and passing the 
+   * control under JIT and the specified method to VM.
+   *
+   * @param[in] method_handle - the handle of the method to compile
+   */
         JIT_Result (*CompileMethod) (Method_Handle method_handle);
 
+  /** 
+   * The method is used to callback EM from the profiler thread supported
+   * by VM on time-out.
+   */
         void (*ProfilerThreadTimeout) ();
 
     };



Mime
View raw message