libopagent/opagent.h

   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 #include <stdint.h>
  33
  34
  35 #if defined(__cplusplus)
  36 extern "C" {
  37 #endif
  38
  39 struct debug_line_info {
  40         unsigned long vma;
  41         unsigned int lineno;
  42         /* The filename format is unspecified, absolute path, relative etc. */
  43         char const * filename;
  44 };
  45
  46 typedef void * op_agent_t;
  47
  48 /**
  49  * This function must be called by agents before any other function.
  50  * Creates and opens a JIT dump file in /tmp/.oprofile/jitdump
  51  * using the naming convention <process_id>.dump.
  52  *
  53  * Returns a valid op_agent_t handle or NULL.  If NULL is returned, errno
  54  * is set to indicate the nature of the error.
  55  **/
  56 op_agent_t op_open_agent(void);
  57
  58 /**
  59  * Frees all resources and closes open file handles.
  60  *
  61  * hdl:         Handle returned from an earlier call to op_open_agent()
  62  *
  63  * Returns 0 on success; -1 otherwise.  If -1 is returned, errno is
  64  * set to indicate the nature of the error.
  65  **/
  66 int op_close_agent(op_agent_t hdl);
  67
  68 /**
  69  * Signal the dynamic generation of native code from a virtual machine.
  70  * Writes a JIT dump record to the open JIT dump file using
  71  * the passed information.
  72  *
  73  * hdl:         Handle returned from an earlier call to op_open_agent()
  74  * symbol_name: The name of the symbol being dynamically compiled.
  75  *              This name can (and should) contain all necessary
  76  *              information to disambiguate it from symbols of the
  77  *              same name; e.g., class, method signature.
  78  * vma:         The virtual memory address of the executable code.
  79  * code:        Pointer to the location of the compiled code.
  80  *              Theoretically, this may be a different location from
  81  *              that given by the vma argument.  For some JIT compilers,
  82  *              obtaining the code may be impractical.  For this (or any other)
  83  *              reason, the agent can choose to pass NULL for this paraemter.
  84  *              If NULL is passed, no code will be copied into the JIT dump
  85  *              file.
  86  * code_size:   Size of the compiled code.
  87  *
  88  * Returns 0 on success; -1 otherwise.  If -1 is returned, errno is
  89  * set to indicate the nature of the error.
  90  **/
  91 int op_write_native_code(op_agent_t hdl, char const * symbol_name,
  92                          uint64_t vma, void const * code,
  93                          const unsigned int code_size);
  94
  95 /**
  96  * Add debug line information to a piece of code. An op_write_native_code()
  97  * with the same code pointer should have occurred before this call. It's not
  98  * necessary to provide one lineno information entry per machine instruction;
  99  * the array can contain hole.
 100  *
 101  * hdl:         Handle returned from an earlier call to op_open_agent()
 102  * code:        Pointer to the location of the code with debug info
 103  * nr_entry:    Number of entries in compile_map
 104  * compile_map: Array of struct debug_line_info.  See the JVMTI agent
 105  *              library implementation for an example of what information
 106  *              should be retrieved from a VM to fill out this data structure.
 107  *
 108  * Returns 0 on success; -1 otherwise.  If -1 is returned, errno is
 109  * set to indicate the nature of the error.
 110  **/
 111 int op_write_debug_line_info(op_agent_t hdl, void const * code,
 112                              size_t nr_entry,
 113                              struct debug_line_info const * compile_map);
 114
 115 /**
 116  * Signal the invalidation of native code from a virtual machine.
 117  *
 118  * hdl:         Handle returned from an earlier call to op_open_agent()
 119  * vma:         The virtual memory address of the compiled code being unloaded.
 120  *              An op_write_native_code() with the same vma should have
 121  *              occurred before this call.
 122  *
 123  * Returns 0 on success; -1 otherwise.  If -1 is returned, errno is
 124  * set to indicate the nature of the error.
 125  **/
 126 int op_unload_native_code(op_agent_t hdl, uint64_t vma);
 127
 128 /**
 129  * Returns the major version number of the libopagent library that will be used.
 130  **/
 131 int op_major_version(void);
 132
 133 /**
 134  * Returns the minor version number of the libopagent library that will be used.
 135  **/
 136 int op_minor_version(void);
 137
 138 /* idea how to post additional information for a piece of code.
 139    we use the code address as reference
 140 int op_write_loader_name(const void* code_addr, char const * loader_name);
 141 */
 142
 143 #if defined(__cplusplus)
 144 }
 145 #endif
 146
 147 #endif