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)
34extern "C" {
35#endif
36
37struct 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
44typedef 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 **/
54op_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 **/
64int 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 **/
89int 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 **/
109int 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 **/
124int 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 **/
129int op_major_version(void);
130
131/**
132 * Returns the minor version number of the libopagent library that will be used.
133 **/
134int 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
138int 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