1 /** 2 * @file opagent.h 3 * Interface to report symbol names and dynamically generated code to Oprofile 4 * 5 * @remark Copyright 2007 OProfile authors 6 * 7 * This library is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU Lesser General Public 9 * License as published by the Free Software Foundation; either 10 * version 2.1 of the License, or (at your option) any later version. 11 * 12 * This library is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Lesser General Public License for more details. 16 * 17 * You should have received a copy of the GNU Lesser General Public 18 * License along with this library; if not, write to the Free Software 19 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 20 * 21 * @author Jens Wilke 22 * @Modifications Daniel Hansel 23 * 24 * Copyright IBM Corporation 2007 25 * 26 */ 27 28 #ifndef _LIB_OPAGENT_H 29 #define _LIB_OPAGENT_H 30 31 #include <sys/types.h> 32 33 #if defined(__cplusplus) 34 extern "C" { 35 #endif 36 37 struct debug_line_info { 38 unsigned long vma; 39 unsigned int lineno; 40 /* The filename format is unspecified, absolute path, relative etc. */ 41 char const * filename; 42 }; 43 44 typedef void * op_agent_t; 45 46 /** 47 * This function must be called by agents before any other function. 48 * Creates and opens a JIT dump file in /var/lib/oprofile/jitdump 49 * using the naming convention <process_id>.dump. 50 * 51 * Returns a valid op_agent_t handle or NULL. If NULL is returned, errno 52 * is set to indicate the nature of the error. 53 **/ 54 op_agent_t op_open_agent(void); 55 56 /** 57 * Frees all resources and closes open file handles. 58 * 59 * hdl: Handle returned from an earlier call to op_open_agent() 60 * 61 * Returns 0 on success; -1 otherwise. If -1 is returned, errno is 62 * set to indicate the nature of the error. 63 **/ 64 int op_close_agent(op_agent_t hdl); 65 66 /** 67 * Signal the dynamic generation of native code from a virtual machine. 68 * Writes a JIT dump record to the open JIT dump file using 69 * the passed information. 70 * 71 * hdl: Handle returned from an earlier call to op_open_agent() 72 * symbol_name: The name of the symbol being dynamically compiled. 73 * This name can (and should) contain all necessary 74 * information to disambiguate it from symbols of the 75 * same name; e.g., class, method signature. 76 * vma: The virtual memory address of the executable code. 77 * code: Pointer to the location of the compiled code. 78 * Theoretically, this may be a different location from 79 * that given by the vma argument. For some JIT compilers, 80 * obtaining the code may be impractical. For this (or any other) 81 * reason, the agent can choose to pass NULL for this paraemter. 82 * If NULL is passed, no code will be copied into the JIT dump 83 * file. 84 * code_size: Size of the compiled code. 85 * 86 * Returns 0 on success; -1 otherwise. If -1 is returned, errno is 87 * set to indicate the nature of the error. 88 **/ 89 int op_write_native_code(op_agent_t hdl, char const * symbol_name, 90 uint64_t vma, void const * code, 91 const unsigned int code_size); 92 93 /** 94 * Add debug line information to a piece of code. An op_write_native_code() 95 * with the same code pointer should have occurred before this call. It's not 96 * necessary to provide one lineno information entry per machine instruction; 97 * the array can contain hole. 98 * 99 * hdl: Handle returned from an earlier call to op_open_agent() 100 * code: Pointer to the location of the code with debug info 101 * nr_entry: Number of entries in compile_map 102 * compile_map: Array of struct debug_line_info. See the JVMTI agent 103 * library implementation for an example of what information 104 * should be retrieved from a VM to fill out this data structure. 105 * 106 * Returns 0 on success; -1 otherwise. If -1 is returned, errno is 107 * set to indicate the nature of the error. 108 **/ 109 int op_write_debug_line_info(op_agent_t hdl, void const * code, 110 size_t nr_entry, 111 struct debug_line_info const * compile_map); 112 113 /** 114 * Signal the invalidation of native code from a virtual machine. 115 * 116 * hdl: Handle returned from an earlier call to op_open_agent() 117 * vma: The virtual memory address of the compiled code being unloaded. 118 * An op_write_native_code() with the same vma should have 119 * occurred before this call. 120 * 121 * Returns 0 on success; -1 otherwise. If -1 is returned, errno is 122 * set to indicate the nature of the error. 123 **/ 124 int op_unload_native_code(op_agent_t hdl, uint64_t vma); 125 126 /** 127 * Returns the major version number of the libopagent library that will be used. 128 **/ 129 int op_major_version(void); 130 131 /** 132 * Returns the minor version number of the libopagent library that will be used. 133 **/ 134 int op_minor_version(void); 135 136 /* idea how to post additional information for a piece of code. 137 we use the code address as reference 138 int op_write_loader_name(const void* code_addr, char const * loader_name); 139 */ 140 141 #if defined(__cplusplus) 142 } 143 #endif 144 145 #endif 146
