jitprofiling.h 29 KB

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