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
  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