1 | /* |
2 | Copyright (C) 2005-2019 Intel Corporation |
3 | |
4 | SPDX-License-Identifier: GPL-2.0-only OR BSD-3-Clause |
5 | */ |
6 | |
7 | #ifndef __JITPROFILING_H__ |
8 | #define __JITPROFILING_H__ |
9 | |
10 | /** |
11 | * @brief JIT Profiling APIs |
12 | * |
13 | * The JIT Profiling API is used to report information about just-in-time |
14 | * generated code that can be used by performance tools. The user inserts |
15 | * calls in the code generator to report information before JIT-compiled |
16 | * code goes to execution. This information is collected at runtime and used |
17 | * by tools like Intel(R) VTune(TM) Amplifier to display performance metrics |
18 | * associated with JIT-compiled code. |
19 | * |
20 | * These APIs can be used to\n |
21 | * - **Profile trace-based and method-based JIT-compiled |
22 | * code**. Some examples of environments that you can profile with these APIs: |
23 | * dynamic JIT compilation of JavaScript code traces, JIT execution in OpenCL(TM) |
24 | * software technology, Java/.NET managed execution environments, and custom |
25 | * ISV JIT engines. |
26 | * @code |
27 | * #include <jitprofiling.h> |
28 | * |
29 | * if (iJIT_IsProfilingActive != iJIT_SAMPLING_ON) { |
30 | * return; |
31 | * } |
32 | * |
33 | * iJIT_Method_Load jmethod = {0}; |
34 | * jmethod.method_id = iJIT_GetNewMethodID(); |
35 | * jmethod.method_name = "method_name"; |
36 | * jmethod.class_file_name = "class_name"; |
37 | * jmethod.source_file_name = "source_file_name"; |
38 | * jmethod.method_load_address = code_addr; |
39 | * jmethod.method_size = code_size; |
40 | * |
41 | * iJIT_NotifyEvent(iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED, (void*)&jmethod); |
42 | * iJIT_NotifyEvent(iJVM_EVENT_TYPE_SHUTDOWN, NULL); |
43 | * @endcode |
44 | * |
45 | * * Expected behavior: |
46 | * * If any iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED event overwrites an |
47 | * already reported method, then such a method becomes invalid and its |
48 | * memory region is treated as unloaded. VTune Amplifier displays the metrics |
49 | * collected by the method until it is overwritten. |
50 | * * If supplied line number information contains multiple source lines for |
51 | * the same assembly instruction (code location), then VTune Amplifier picks up |
52 | * the first line number. |
53 | * * Dynamically generated code can be associated with a module name. |
54 | * Use the iJIT_Method_Load_V2 structure.\n |
55 | * Clarification of some cases: |
56 | * * If you register a function with the same method ID multiple times, |
57 | * specifying different module names, then the VTune Amplifier picks up |
58 | * the module name registered first. If you want to distinguish the same |
59 | * function between different JIT engines, supply different method IDs for |
60 | * each function. Other symbolic information (for example, source file) |
61 | * can be identical. |
62 | * |
63 | * - **Analyze split functions** (multiple joint or disjoint code regions |
64 | * belonging to the same function) **including re-JIT** |
65 | * with potential overlapping of code regions in time, which is common in |
66 | * resource-limited environments. |
67 | * @code |
68 | * #include <jitprofiling.h> |
69 | * |
70 | * unsigned int method_id = iJIT_GetNewMethodID(); |
71 | * |
72 | * iJIT_Method_Load a = {0}; |
73 | * a.method_id = method_id; |
74 | * a.method_load_address = 0x100; |
75 | * a.method_size = 0x20; |
76 | * |
77 | * iJIT_Method_Load b = {0}; |
78 | * b.method_id = method_id; |
79 | * b.method_load_address = 0x200; |
80 | * b.method_size = 0x30; |
81 | * |
82 | * iJIT_NotifyEvent(iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED, (void*)&a); |
83 | * iJIT_NotifyEvent(iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED, (void*)&b); |
84 | * @endcode |
85 | * |
86 | * * Expected behaviour: |
87 | * * If a iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED event overwrites an |
88 | * already reported method, then such a method becomes invalid and |
89 | * its memory region is treated as unloaded. |
90 | * * All code regions reported with the same method ID are considered as |
91 | * belonging to the same method. Symbolic information (method name, |
92 | * source file name) will be taken from the first notification, and all |
93 | * subsequent notifications with the same method ID will be processed |
94 | * only for line number table information. So, the VTune Amplifier will map |
95 | * samples to a source line using the line number table from the current |
96 | * notification while taking the source file name from the very first one.\n |
97 | * Clarification of some cases:\n |
98 | * * If you register a second code region with a different source file |
99 | * name and the same method ID, then this information will be saved and |
100 | * will not be considered as an extension of the first code region, but |
101 | * VTune Amplifier will use the source file of the first code region and map |
102 | * performance metrics incorrectly. |
103 | * * If you register a second code region with the same source file as |
104 | * for the first region and the same method ID, then the source file will be |
105 | * discarded but VTune Amplifier will map metrics to the source file correctly. |
106 | * * If you register a second code region with a null source file and |
107 | * the same method ID, then provided line number info will be associated |
108 | * with the source file of the first code region. |
109 | * |
110 | * - **Explore inline functions** including multi-level hierarchy of |
111 | * nested inline methods which shows how performance metrics are distributed through them. |
112 | * @code |
113 | * #include <jitprofiling.h> |
114 | * |
115 | * // method_id parent_id |
116 | * // [-- c --] 3000 2000 |
117 | * // [---- d -----] 2001 1000 |
118 | * // [---- b ----] 2000 1000 |
119 | * // [------------ a ----------------] 1000 n/a |
120 | * |
121 | * iJIT_Method_Load a = {0}; |
122 | * a.method_id = 1000; |
123 | * |
124 | * iJIT_Method_Inline_Load b = {0}; |
125 | * b.method_id = 2000; |
126 | * b.parent_method_id = 1000; |
127 | * |
128 | * iJIT_Method_Inline_Load c = {0}; |
129 | * c.method_id = 3000; |
130 | * c.parent_method_id = 2000; |
131 | * |
132 | * iJIT_Method_Inline_Load d = {0}; |
133 | * d.method_id = 2001; |
134 | * d.parent_method_id = 1000; |
135 | * |
136 | * iJIT_NotifyEvent(iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED, (void*)&a); |
137 | * iJIT_NotifyEvent(iJVM_EVENT_TYPE_METHOD_INLINE_LOAD_FINISHED, (void*)&b); |
138 | * iJIT_NotifyEvent(iJVM_EVENT_TYPE_METHOD_INLINE_LOAD_FINISHED, (void*)&c); |
139 | * iJIT_NotifyEvent(iJVM_EVENT_TYPE_METHOD_INLINE_LOAD_FINISHED, (void*)&d); |
140 | * @endcode |
141 | * |
142 | * * Requirements: |
143 | * * Each inline (iJIT_Method_Inline_Load) method should be associated |
144 | * with two method IDs: one for itself; one for its immediate parent. |
145 | * * Address regions of inline methods of the same parent method cannot |
146 | * overlap each other. |
147 | * * Execution of the parent method must not be started until it and all |
148 | * its inline methods are reported. |
149 | * * Expected behaviour: |
150 | * * In case of nested inline methods an order of |
151 | * iJVM_EVENT_TYPE_METHOD_INLINE_LOAD_FINISHED events is not important. |
152 | * * If any event overwrites either inline method or top parent method, |
153 | * then the parent, including inline methods, becomes invalid and its memory |
154 | * region is treated as unloaded. |
155 | * |
156 | * **Life time of allocated data**\n |
157 | * The client sends an event notification to the agent with event-specific |
158 | * data, which is a structure. The pointers in the structure refer to memory |
159 | * allocated by the client, which responsible for releasing it. The pointers are |
160 | * used by the iJIT_NotifyEvent method to copy client's data in a trace file, |
161 | * and they are not used after the iJIT_NotifyEvent method returns. |
162 | */ |
163 | |
164 | /** |
165 | * @defgroup jitapi JIT Profiling |
166 | * @ingroup internal |
167 | * @{ |
168 | */ |
169 | |
170 | /** |
171 | * @brief Enumerator for the types of notifications |
172 | */ |
173 | typedef enum iJIT_jvm_event |
174 | { |
175 | iJVM_EVENT_TYPE_SHUTDOWN = 2, /**<\brief Send this to shutdown the agent. |
176 | * Use NULL for event data. */ |
177 | |
178 | iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED = 13, /**<\brief Send when dynamic code is |
179 | * JIT compiled and loaded into |
180 | * memory by the JIT engine, but |
181 | * before the code is executed. |
182 | * Use iJIT_Method_Load as event |
183 | * data. */ |
184 | /** @cond exclude_from_documentation */ |
185 | iJVM_EVENT_TYPE_METHOD_UNLOAD_START, /**<\brief Send when compiled dynamic |
186 | * code is being unloaded from memory. |
187 | * Use iJIT_Method_Load as event data.*/ |
188 | /** @endcond */ |
189 | |
190 | iJVM_EVENT_TYPE_METHOD_UPDATE, /**<\brief Send to provide new content for |
191 | * a previously reported dynamic code. |
192 | * The previous content will be invalidated |
193 | * starting from the time of the notification. |
194 | * Use iJIT_Method_Load as event data but |
195 | * required fields are following: |
196 | * - method_id identify the code to update. |
197 | * - method_load_address specify start address |
198 | * within identified code range |
199 | * where update should be started. |
200 | * - method_size specify length of updated code |
201 | * range. */ |
202 | |
203 | |
204 | iJVM_EVENT_TYPE_METHOD_INLINE_LOAD_FINISHED, /**<\brief Send when an inline dynamic |
205 | * code is JIT compiled and loaded |
206 | * into memory by the JIT engine, |
207 | * but before the parent code region |
208 | * starts executing. |
209 | * Use iJIT_Method_Inline_Load as event data.*/ |
210 | |
211 | /** @cond exclude_from_documentation */ |
212 | iJVM_EVENT_TYPE_METHOD_UPDATE_V2, |
213 | /** @endcond */ |
214 | |
215 | iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED_V2 = 21, /**<\brief Send when a dynamic code is |
216 | * JIT compiled and loaded into |
217 | * memory by the JIT engine, but |
218 | * before the code is executed. |
219 | * Use iJIT_Method_Load_V2 as event data. */ |
220 | |
221 | iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED_V3 /**<\brief Send when a dynamic code is |
222 | * JIT compiled and loaded into |
223 | * memory by the JIT engine, but |
224 | * before the code is executed. |
225 | * Use iJIT_Method_Load_V3 as event data. */ |
226 | } iJIT_JVM_EVENT; |
227 | |
228 | /** |
229 | * @brief Enumerator for the agent's mode |
230 | */ |
231 | typedef enum _iJIT_IsProfilingActiveFlags |
232 | { |
233 | iJIT_NOTHING_RUNNING = 0x0000, /**<\brief The agent is not running; |
234 | * iJIT_NotifyEvent calls will |
235 | * not be processed. */ |
236 | iJIT_SAMPLING_ON = 0x0001, /**<\brief The agent is running and |
237 | * ready to process notifications. */ |
238 | } iJIT_IsProfilingActiveFlags; |
239 | |
240 | /** |
241 | * @brief Description of a single entry in the line number information of a code region. |
242 | * @details A table of line number entries gives information about how the reported code region |
243 | * is mapped to source file. |
244 | * Intel(R) VTune(TM) Amplifier uses line number information to attribute |
245 | * the samples (virtual address) to a line number. \n |
246 | * It is acceptable to report different code addresses for the same source line: |
247 | * @code |
248 | * Offset LineNumber |
249 | * 1 2 |
250 | * 12 4 |
251 | * 15 2 |
252 | * 18 1 |
253 | * 21 30 |
254 | * |
255 | * VTune Amplifier constructs the following table using the client data |
256 | * |
257 | * Code subrange Line number |
258 | * 0-1 2 |
259 | * 1-12 4 |
260 | * 12-15 2 |
261 | * 15-18 1 |
262 | * 18-21 30 |
263 | * @endcode |
264 | */ |
265 | typedef struct _LineNumberInfo |
266 | { |
267 | unsigned int Offset; /**<\brief Offset from the begining of the code region. */ |
268 | unsigned int LineNumber; /**<\brief Matching source line number offset (from beginning of source file). */ |
269 | |
270 | } *pLineNumberInfo, LineNumberInfo; |
271 | |
272 | /** |
273 | * @brief Enumerator for the code architecture. |
274 | */ |
275 | typedef enum _iJIT_CodeArchitecture |
276 | { |
277 | iJIT_CA_NATIVE = 0, /**<\brief Native to the process architecture that is calling it. */ |
278 | |
279 | iJIT_CA_32, /**<\brief 32-bit machine code. */ |
280 | |
281 | iJIT_CA_64 /**<\brief 64-bit machine code. */ |
282 | |
283 | } iJIT_CodeArchitecture; |
284 | |
285 | #pragma pack(push, 8) |
286 | |
287 | /** |
288 | * @brief Description of a JIT-compiled method |
289 | * @details When you use the iJIT_Method_Load structure to describe |
290 | * the JIT compiled method, use iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED |
291 | * as an event type to report it. |
292 | */ |
293 | typedef struct _iJIT_Method_Load |
294 | { |
295 | unsigned int method_id; /**<\brief Unique method ID. Cannot be 0. |
296 | * You must either use the API function |
297 | * iJIT_GetNewMethodID to get a valid and unique |
298 | * method ID, or else manage ID uniqueness |
299 | * and correct range by yourself.\n |
300 | * You must use the same method ID for all code |
301 | * regions of the same method, otherwise different |
302 | * method IDs specify different methods. */ |
303 | |
304 | char* method_name; /**<\brief The name of the method. It can be optionally |
305 | * prefixed with its class name and appended with |
306 | * its complete signature. Can't be NULL. */ |
307 | |
308 | void* method_load_address; /**<\brief The start virtual address of the method code |
309 | * region. If NULL, data provided with |
310 | * event are not accepted. */ |
311 | |
312 | unsigned int method_size; /**<\brief The code size of the method in memory. |
313 | * If 0, then data provided with the event are not |
314 | * accepted. */ |
315 | |
316 | unsigned int line_number_size; /**<\brief The number of entries in the line number |
317 | * table.0 if none. */ |
318 | |
319 | pLineNumberInfo line_number_table; /**<\brief Pointer to the line numbers info |
320 | * array. Can be NULL if |
321 | * line_number_size is 0. See |
322 | * LineNumberInfo Structure for a |
323 | * description of a single entry in |
324 | * the line number info array */ |
325 | |
326 | unsigned int class_id; /**<\brief This field is obsolete. */ |
327 | |
328 | char* class_file_name; /**<\brief Class name. Can be NULL.*/ |
329 | |
330 | char* source_file_name; /**<\brief Source file name. Can be NULL.*/ |
331 | |
332 | } *piJIT_Method_Load, iJIT_Method_Load; |
333 | |
334 | /** |
335 | * @brief Description of a JIT-compiled method |
336 | * @details When you use the iJIT_Method_Load_V2 structure to describe |
337 | * the JIT compiled method, use iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED_V2 |
338 | * as an event type to report it. |
339 | */ |
340 | typedef struct _iJIT_Method_Load_V2 |
341 | { |
342 | unsigned int method_id; /**<\brief Unique method ID. Cannot be 0. |
343 | * You must either use the API function |
344 | * iJIT_GetNewMethodID to get a valid and unique |
345 | * method ID, or else manage ID uniqueness |
346 | * and correct range by yourself.\n |
347 | * You must use the same method ID for all code |
348 | * regions of the same method, otherwise different |
349 | * method IDs specify different methods. */ |
350 | |
351 | char* method_name; /**<\brief The name of the method. It can be optionally |
352 | * prefixed with its class name and appended with |
353 | * its complete signature. Can't be NULL. */ |
354 | |
355 | void* method_load_address; /**<\brief The start virtual address of the method code |
356 | * region. If NULL, then data provided with the |
357 | * event are not accepted. */ |
358 | |
359 | unsigned int method_size; /**<\brief The code size of the method in memory. |
360 | * If 0, then data provided with the event are not |
361 | * accepted. */ |
362 | |
363 | unsigned int line_number_size; /**<\brief The number of entries in the line number |
364 | * table. 0 if none. */ |
365 | |
366 | pLineNumberInfo line_number_table; /**<\brief Pointer to the line numbers info |
367 | * array. Can be NULL if |
368 | * line_number_size is 0. See |
369 | * LineNumberInfo Structure for a |
370 | * description of a single entry in |
371 | * the line number info array. */ |
372 | |
373 | char* class_file_name; /**<\brief Class name. Can be NULL. */ |
374 | |
375 | char* source_file_name; /**<\brief Source file name. Can be NULL. */ |
376 | |
377 | char* module_name; /**<\brief Module name. Can be NULL. |
378 | The module name can be useful for distinguishing among |
379 | different JIT engines. VTune Amplifier will display |
380 | reported methods grouped by specific module. */ |
381 | |
382 | } *piJIT_Method_Load_V2, iJIT_Method_Load_V2; |
383 | |
384 | /** |
385 | * @brief Description of a JIT-compiled method |
386 | * @details The iJIT_Method_Load_V3 structure is the same as iJIT_Method_Load_V2 |
387 | * with a newly introduced 'arch' field that specifies architecture of the code region. |
388 | * When you use the iJIT_Method_Load_V3 structure to describe |
389 | * the JIT compiled method, use iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED_V3 |
390 | * as an event type to report it. |
391 | */ |
392 | typedef struct _iJIT_Method_Load_V3 |
393 | { |
394 | unsigned int method_id; /**<\brief Unique method ID. Cannot be 0. |
395 | * You must either use the API function |
396 | * iJIT_GetNewMethodID to get a valid and unique |
397 | * method ID, or manage ID uniqueness |
398 | * and correct range by yourself.\n |
399 | * You must use the same method ID for all code |
400 | * regions of the same method, otherwise they are |
401 | * treated as regions of different methods. */ |
402 | |
403 | char* method_name; /**<\brief The name of the method. It can be optionally |
404 | * prefixed with its class name and appended with |
405 | * its complete signature. Cannot be NULL. */ |
406 | |
407 | void* method_load_address; /**<\brief The start virtual address of the method code |
408 | * region. If NULL, then data provided with the |
409 | * event are not accepted. */ |
410 | |
411 | unsigned int method_size; /**<\brief The code size of the method in memory. |
412 | * If 0, then data provided with the event are not |
413 | * accepted. */ |
414 | |
415 | unsigned int line_number_size; /**<\brief The number of entries in the line number |
416 | * table. 0 if none. */ |
417 | |
418 | pLineNumberInfo line_number_table; /**<\brief Pointer to the line numbers info |
419 | * array. Can be NULL if |
420 | * line_number_size is 0. See |
421 | * LineNumberInfo Structure for a |
422 | * description of a single entry in |
423 | * the line number info array. */ |
424 | |
425 | char* class_file_name; /**<\brief Class name. Can be NULL. */ |
426 | |
427 | char* source_file_name; /**<\brief Source file name. Can be NULL. */ |
428 | |
429 | char* module_name; /**<\brief Module name. Can be NULL. |
430 | * The module name can be useful for distinguishing among |
431 | * different JIT engines. VTune Amplifier will display |
432 | * reported methods grouped by specific module. */ |
433 | |
434 | iJIT_CodeArchitecture module_arch; /**<\brief Architecture of the method's code region. |
435 | * By default, it is the same as the process |
436 | * architecture that is calling it. |
437 | * For example, you can use it if your 32-bit JIT |
438 | * engine generates 64-bit code. |
439 | * |
440 | * If JIT engine reports both 32-bit and 64-bit types |
441 | * of methods then VTune Amplifier splits the methods |
442 | * with the same module name but with different |
443 | * architectures in two different modules. VTune Amplifier |
444 | * modifies the original name provided with a 64-bit method |
445 | * version by ending it with '(64)' */ |
446 | |
447 | } *piJIT_Method_Load_V3, iJIT_Method_Load_V3; |
448 | |
449 | /** |
450 | * @brief Description of an inline JIT-compiled method |
451 | * @details When you use the_iJIT_Method_Inline_Load structure to describe |
452 | * the JIT compiled method, use iJVM_EVENT_TYPE_METHOD_INLINE_LOAD_FINISHED |
453 | * as an event type to report it. |
454 | */ |
455 | typedef struct _iJIT_Method_Inline_Load |
456 | { |
457 | unsigned int method_id; /**<\brief Unique method ID. Cannot be 0. |
458 | * You must either use the API function |
459 | * iJIT_GetNewMethodID to get a valid and unique |
460 | * method ID, or else manage ID uniqueness |
461 | * and correct range by yourself. */ |
462 | |
463 | unsigned int parent_method_id; /**<\brief Unique immediate parent's method ID. |
464 | * Cannot be 0. |
465 | * You must either use the API function |
466 | * iJIT_GetNewMethodID to get a valid and unique |
467 | * method ID, or else manage ID uniqueness |
468 | * and correct range by yourself. */ |
469 | |
470 | char* method_name; /**<\brief The name of the method. It can be optionally |
471 | * prefixed with its class name and appended with |
472 | * its complete signature. Can't be NULL. */ |
473 | |
474 | void* method_load_address; /** <\brief The virtual address on which the method |
475 | * is inlined. If NULL, then data provided with |
476 | * the event are not accepted. */ |
477 | |
478 | unsigned int method_size; /**<\brief The code size of the method in memory. |
479 | * If 0, then data provided with the event are not |
480 | * accepted. */ |
481 | |
482 | unsigned int line_number_size; /**<\brief The number of entries in the line number |
483 | * table. 0 if none. */ |
484 | |
485 | pLineNumberInfo line_number_table; /**<\brief Pointer to the line numbers info |
486 | * array. Can be NULL if |
487 | * line_number_size is 0. See |
488 | * LineNumberInfo Structure for a |
489 | * description of a single entry in |
490 | * the line number info array */ |
491 | |
492 | char* class_file_name; /**<\brief Class name. Can be NULL.*/ |
493 | |
494 | char* source_file_name; /**<\brief Source file name. Can be NULL.*/ |
495 | |
496 | } *piJIT_Method_Inline_Load, iJIT_Method_Inline_Load; |
497 | |
498 | /** @cond exclude_from_documentation */ |
499 | /** |
500 | * @brief Description of a segment type |
501 | * @details Use the segment type to specify a type of data supplied |
502 | * with the iJVM_EVENT_TYPE_METHOD_UPDATE_V2 event to be applied to |
503 | * a certain code trace. |
504 | */ |
505 | typedef enum _iJIT_SegmentType |
506 | { |
507 | iJIT_CT_UNKNOWN = 0, |
508 | |
509 | iJIT_CT_CODE, /**<\brief Executable code. */ |
510 | |
511 | iJIT_CT_DATA, /**<\brief Data (not executable code). |
512 | * VTune Amplifier uses the format string |
513 | * (see iJIT_Method_Update) to represent |
514 | * this data in the VTune Amplifier GUI */ |
515 | |
516 | iJIT_CT_KEEP, /**<\brief Use the previous markup for the trace. |
517 | * Can be used for the following |
518 | * iJVM_EVENT_TYPE_METHOD_UPDATE_V2 events, |
519 | * if the type of the previously reported segment |
520 | * type is the same. */ |
521 | iJIT_CT_EOF |
522 | } iJIT_SegmentType; |
523 | |
524 | /** |
525 | * @brief Description of a dynamic update of the content within JIT-compiled method |
526 | * @details The JIT engine may generate the methods that are updated at runtime |
527 | * partially by mixed (data + executable code) content. When you use the iJIT_Method_Update |
528 | * structure to describe the update of the content within a JIT-compiled method, |
529 | * use iJVM_EVENT_TYPE_METHOD_UPDATE_V2 as an event type to report it. |
530 | * |
531 | * On the first Update event, VTune Amplifier copies the original code range reported by |
532 | * the iJVM_EVENT_TYPE_METHOD_LOAD event, then modifies it with the supplied bytes and |
533 | * adds the modified range to the original method. For next update events, VTune Amplifier |
534 | * does the same but it uses the latest modified version of a code region for update. |
535 | * Eventually, VTune Amplifier GUI displays multiple code ranges for the method reported by |
536 | * the iJVM_EVENT_TYPE_METHOD_LOAD event. |
537 | * Notes: |
538 | * - Multiple update events with different types for the same trace are allowed |
539 | * but they must be reported for the same code ranges. |
540 | * Example, |
541 | * @code |
542 | * [-- data---] Allowed |
543 | * [-- code --] Allowed |
544 | * [code] Ignored |
545 | * [-- data---] Allowed |
546 | * [-- code --] Allowed |
547 | * [------------ trace ---------] |
548 | * @endcode |
549 | * - The types of previously reported events can be changed but they must be reported |
550 | * for the same code ranges. |
551 | * Example, |
552 | * @code |
553 | * [-- data---] Allowed |
554 | * [-- code --] Allowed |
555 | * [-- data---] Allowed |
556 | * [-- code --] Allowed |
557 | * [------------ trace ---------] |
558 | * @endcode |
559 | */ |
560 | |
561 | typedef struct _iJIT_Method_Update |
562 | { |
563 | void* load_address; /**<\brief Start address of the update within a method */ |
564 | |
565 | unsigned int size; /**<\brief The update size */ |
566 | |
567 | iJIT_SegmentType type; /**<\brief Type of the update */ |
568 | |
569 | const char* data_format; /**<\brief C string that contains a format string |
570 | * that follows the same specifications as format in printf. |
571 | * The format string is used for iJIT_CT_CODE only |
572 | * and cannot be NULL. |
573 | * Format can be changed on the fly. */ |
574 | } *piJIT_Method_Update, iJIT_Method_Update; |
575 | |
576 | /** @endcond */ |
577 | |
578 | #pragma pack(pop) |
579 | |
580 | /** @cond exclude_from_documentation */ |
581 | #ifdef __cplusplus |
582 | extern "C" { |
583 | #endif /* __cplusplus */ |
584 | |
585 | #ifndef JITAPI_CDECL |
586 | # if defined WIN32 || defined _WIN32 |
587 | # define JITAPI_CDECL __cdecl |
588 | # else /* defined WIN32 || defined _WIN32 */ |
589 | # if defined _M_IX86 || defined __i386__ |
590 | # define JITAPI_CDECL __attribute__ ((cdecl)) |
591 | # else /* _M_IX86 || __i386__ */ |
592 | # define JITAPI_CDECL /* actual only on x86_64 platform */ |
593 | # endif /* _M_IX86 || __i386__ */ |
594 | # endif /* defined WIN32 || defined _WIN32 */ |
595 | #endif /* JITAPI_CDECL */ |
596 | |
597 | #define JITAPI JITAPI_CDECL |
598 | /** @endcond */ |
599 | |
600 | /** |
601 | * @brief Generates a new unique method ID. |
602 | * |
603 | * You must use this API to obtain unique and valid method IDs for methods or |
604 | * traces reported to the agent if you don't have your own mechanism to generate |
605 | * unique method IDs. |
606 | * |
607 | * @return a new unique method ID. When out of unique method IDs, this API |
608 | * returns 0, which is not an accepted value. |
609 | */ |
610 | unsigned int JITAPI iJIT_GetNewMethodID(void); |
611 | |
612 | /** |
613 | * @brief Returns the current mode of the agent. |
614 | * |
615 | * @return iJIT_SAMPLING_ON, indicating that agent is running, or |
616 | * iJIT_NOTHING_RUNNING if no agent is running. |
617 | */ |
618 | iJIT_IsProfilingActiveFlags JITAPI iJIT_IsProfilingActive(void); |
619 | |
620 | /** |
621 | * @brief Reports infomation about JIT-compiled code to the agent. |
622 | * |
623 | * The reported information is used to attribute samples obtained from any |
624 | * Intel(R) VTune(TM) Amplifier collector. This API needs to be called |
625 | * after JIT compilation and before the first entry into the JIT-compiled |
626 | * code. |
627 | * |
628 | * @param[in] event_type - type of the data sent to the agent |
629 | * @param[in] EventSpecificData - pointer to event-specific data |
630 | * |
631 | * @returns 1 on success, otherwise 0. |
632 | */ |
633 | int JITAPI iJIT_NotifyEvent(iJIT_JVM_EVENT event_type, void *EventSpecificData); |
634 | |
635 | #ifdef __cplusplus |
636 | } |
637 | #endif /* __cplusplus */ |
638 | /** @endcond */ |
639 | |
640 | /** @} jitapi group */ |
641 | |
642 | #endif /* __JITPROFILING_H__ */ |
643 | |