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