[prev in list] [next in list] [prev in thread] [next in thread]
List: oprofile-commits
Subject: [oprof-cvs] CVS: oprofile/doc oprofile.xml,1.164.2.4,1.164.2.5
From: Maynard Johnson <maynardj () users ! sourceforge ! net>
Date: 2007-12-17 21:53:46
Message-ID: E1J4NuE-0004fQ-P9 () sc8-pr-cvs3 ! sourceforge ! net
[Download RAW message or body]
Update of /cvsroot/oprofile/oprofile/doc
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv17836/doc
Modified Files:
Tag: JIT_SUPPORT
oprofile.xml
Log Message:
Add documentation on JIT API; improve JIT developer doc
Index: oprofile.xml
===================================================================
RCS file: /cvsroot/oprofile/oprofile/doc/oprofile.xml,v
retrieving revision 1.164.2.4
retrieving revision 1.164.2.5
diff -u -p -d -r1.164.2.4 -r1.164.2.5
--- oprofile.xml 10 Dec 2007 23:40:47 -0000 1.164.2.4
+++ oprofile.xml 17 Dec 2007 21:53:44 -0000 1.164.2.5
@@ -2142,23 +2142,22 @@ Show version.
<para>
Below is an example of a profile report of a Java application that has been
instrumented with the provided agent library.
-<!-- FIXME-JIT: re-run the test app with new code that does mangling; then fix the
-the opreport output -->
<screen>
$ opreport -l /usr/lib/jvm/jre-1.5.0-ibm/bin/java
CPU: Core Solo / Duo, speed 2167 MHz (estimated)
Counted CPU_CLK_UNHALTED events (Unhalted clock cycles) with a unit mask of 0x00 \
(Unhalted core cycles) count 100000 samples % image name \
symbol name
-281 59.9147 [vdso] (tgid:9723 range:0x760000-0x761000) (no symbols)
-76 16.2047 9723.jo java/lang/StringBuilder/append˜3
-31 6.6098 9723.jo java/lang/Integer/getChars˜1
-31 6.6098 9723.jo java/lang/StringBuilder/append˜1
-24 5.1173 9723.jo TestApp01/main˜3
-14 2.9851 9723.jo java/lang/StringBuilder/toString˜1
-5 1.0661 9723.jo \
java/lang/StringBuilder/<init>˜1
-3 0.6397 9723.jo java/lang/String/length˜1
-3 0.6397 java .plt
-1 0.2132 java ibmFindJVMDLL
+186020 50.0523 no-vmlinux no-vmlinux (no symbols)
+34333 9.2380 7635.jo java void test.f1()
+19022 5.1182 libc-2.5.so libc-2.5.so \
_IO_file_xsputn@@GLIBC_2.1 +18762 5.0483 libc-2.5.so libc-2.5.so \
vfprintf +16408 4.4149 7635.jo java void \
test$HelloThread.run() +16250 4.3724 7635.jo java \
void test$test_1.f2(int) +15303 4.1176 7635.jo java \
void test.f2(int, int) +13252 3.5657 7635.jo java \
void test.f2(int) +5165 1.3897 7635.jo java \
void test.f4() +955 0.2570 7635.jo java \
void test$HelloThread.run()~ +
</screen>
</para>
<note><para>
@@ -2169,15 +2168,17 @@ samples % image name
but other JVMs do not.
</para></note>
<para>
- The JIT support agent for Java generates symbols to include the class
- and method signature.
+ As you can see in the opreport output, the JIT support agent for Java
+ generates symbols to include the class and method signature.
A symbol with the suffix ˜<n> (e.g.
- <code>java.lang.String test.run_test()˜1</code>) means that this is
+ <code>void test$HelloThread.run()˜1</code>) means that this is
the <n>th occurrence of the identical name. This happens if a method is \
re-JITed. A symbol with the suffix %<n>, means that the address space of this \
symbol was reused during the sample session (see <xref linkend="overlapping-symbols" \
/>). The value <n> is the percentage of time that this symbol/code was present \
in
- relation to the total lifetime of all overlapping other symbols.
+ relation to the total lifetime of all overlapping other symbols. A symbol of the \
form + <code><return_val> <class_name>$<method_sig></code> denotes \
an + inner class.
</para>
</sect1>
@@ -2824,30 +2825,141 @@ and <ulink url="http://developer.amd.com
</para>
</sect1>
<sect1 id="jit-interface">
-<title>JIT support interface</title>
+<title>Implementing JIT support for a new virtual machine</title>
<para>
- The JIT support infrastructure for OProfile defines the following interface
- in <filename><oprofile-install-dir>/include/libopagent.h</filename>:
+ The JIT support API for OProfile is defined
+ in <filename><oprofile-install-dir>/include/libopagent.h</filename>.
+ Some parts of the API are mandatory for an agent library to implement; other
+ parts are optional. The mandatory functions to implement are shown below.
</para>
<screen>
-/** This function must be called by agents before any other function */
-int op_open_agent();
+op_agent_t op_open_agent(void);
-/** Frees all resources and close open file handles */
-void op_close_agent();
+void op_close_agent(op_agent_t hdl);
-/** Signal the dynamic generation of native code from a JIT */
-int op_write_native_code(
- char const * symbol_name,
- const void * code,
- const unsigned int code_size);
+int op_write_native_code(op_agent_t hdl, char const * symbol_name,
+ const void * code, const unsigned int code_size);
+</screen>
-/** Signal the invalidation of native code from a JIT */
-int op_unload_native_code(
- const void * code);
+ <para>
+ To implement this part of the API, your library should perform the
+ following steps:
+ <orderedlist>
+ <listitem>Implement a function to set up initial communication with the VM.
+ Once communication to the VM is established, your agent library should call
+ <code>op_op_agent()</code> and cache the returned op_agent_t handle for use in
+ future calls.</listitem>
+ <listitem>Perform any necessary steps to register with the VM to be notified \
of + compiled code load events. Registration must include a callback function you
+ will implement in the library to handle the compiled code load events.</listitem>
+ <listitem>The callback function mentioned above must obtain all required
+ information from the VM to pass to libopagent via \
<code>op_write_native_code()</code>.</listitem> + <listitem>When disconnecting \
from the VM, your library should call + <code>op_agent_close()</code>.</listitem>
+ </orderedlist>
+ </para>
+
+ <para>The functions below are optional, depending on the kinds of information your \
VM + can provide to your agent library.
+<screen>
+int op_unload_native_code(op_agent_t hdl, const void * code);
+
+int op_write_debug_line_info(op_agent_t hdl, void const * code,
+ size_t nr_entry,
+ struct debug_line_info const * compile_map);
+</screen>
+ </para>
+</sect1>
+<sect1 id="jit-api">
+<title>The JIT support API</title>
+ <para>
+ This section describes the JIT support API in detail.
+ </para>
+<screen>
+typedef void * op_agent_t;
+
+/**
+ * This function must be called by agents before any other function.
+ * Creates and opens a JIT dump file in /var/lib/oprofile/jitdump
+ * using the naming convention <process_id>.dump.
+ *
+ * Returns a valid op_agent_t handle or NULL. If NULL is returned, errno
+ * is set to indicate the nature of the error.
+ **/
+op_agent_t op_open_agent(void);
+
+/**
+ * Frees all resources and closes open file handles.
+ *
+ * hdl: Handle returned from an earlier call to op_open_agent()
+ *
+ * Returns 0 on success; -1 otherwise. If -1 is returned, errno is
+ * set to indicate the nature of the error.
+ **/
+int op_close_agent(op_agent_t hdl);
+
+/**
+ * Signal the dynamic generation of native code from a virtual machine.
+ * Writes a JIT dump record to the open JIT dump file using
+ * the passed information.
+ *
+ * hdl: Handle returned from an earlier call to op_open_agent()
+ * symbol_name: The name of the symbol being dynamically compiled.
+ * This name can (and should) contain all necessary
+ * information to disambiguate it from symbols of the
+ * same name; e.g., class, method signature.
+ * code: Pointer to the location of the compiled code.
+ * code_size: Size of the compiled code.
+ *
+ * Returns 0 on success; -1 otherwise. If -1 is returned, errno is
+ * set to indicate the nature of the error.
+ **/
+int op_write_native_code(op_agent_t hdl, char const * symbol_name,
+ void const * code, const unsigned int code_size);
+
+
+struct debug_line_info {
+ unsigned long vma;
+ unsigned int lineno;
+ /* The filename format is unspecified, absolute path, relative etc. */
+ char const * filename;
+};
+/**
+ * Add debug line information to a piece of code. An op_write_native_code()
+ * with the same code pointer should have occurred before this call. It's not
+ * necessary to provide one lineno information entry per machine instruction;
+ * the array can contain hole.
+ *
+ * hdl: Handle returned from an earlier call to op_open_agent()
+ * code: Pointer to the location of the code with debug info
+ * nr_entry: Number of entries in compile_map
+ * compile_map: Array of struct debug_line_info. See the JVMTI agent
+ * library implementation for an example of what information
+ * should be retrieved from a VM to fill out this data structure.
+ *
+ * Returns 0 on success; -1 otherwise. If -1 is returned, errno is
+ * set to indicate the nature of the error.
+ **/
+int op_write_debug_line_info(op_agent_t hdl, void const * code,
+ size_t nr_entry,
+ struct debug_line_info const * compile_map);
+
+/**
+ * Signal the invalidation of native code from a virtual machine.
+ *
+ * hdl: Handle returned from an earlier call to op_open_agent()
+ * code: Pointer to the location of the compile code being unloaded.
+ * An op_write_native_code() with the same code pointer should
+ * have occurred before this call.
+ *
+ * Returns 0 on success; -1 otherwise. If -1 is returned, errno is
+ * set to indicate the nature of the error.
+ **/
+int op_unload_native_code(op_agent_t hdl, void const * code);
</screen>
</sect1>
+
</chapter>
<chapter id="ack">
-------------------------------------------------------------------------
SF.Net email is sponsored by:
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services
for just about anything Open Source.
http://ad.doubleclick.net/clk;164216239;13503038;w?http://sf.net/marketplace
_______________________________________________
Oprofile-commits mailing list
Oprofile-commits@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oprofile-commits
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic