Mercurial > hg > graal-jvmci-8
comparison src/share/vm/prims/jvmti.xml @ 12117:f92b82d454fa
8014135: The JVMTI specification does not conform to recent changes in JNI specification
Summary: Added support for statically linked agents
Reviewed-by: sspitsyn, bobv, coleenp
author | bpittore |
---|---|
date | Fri, 23 Aug 2013 20:33:02 -0400 |
parents | 5c89346f2bdd |
children | 8e94527f601e |
comparison
equal
deleted
inserted
replaced
12094:73921c720b94 | 12117:f92b82d454fa |
---|---|
1 <?xml version="1.0" encoding="ISO-8859-1"?> | 1 <?xml version="1.0" encoding="ISO-8859-1"?> |
2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?> | 2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?> |
3 <!-- | 3 <!-- |
4 Copyright (c) 2002, 2012, Oracle and/or its affiliates. All rights reserved. | 4 Copyright (c) 2002, 2013, Oracle and/or its affiliates. All rights reserved. |
5 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | 5 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
6 | 6 |
7 This code is free software; you can redistribute it and/or modify it | 7 This code is free software; you can redistribute it and/or modify it |
8 under the terms of the GNU General Public License version 2 only, as | 8 under the terms of the GNU General Public License version 2 only, as |
9 published by the Free Software Foundation. | 9 published by the Free Software Foundation. |
356 ]> | 356 ]> |
357 | 357 |
358 <specification label="JVM(TM) Tool Interface" | 358 <specification label="JVM(TM) Tool Interface" |
359 majorversion="1" | 359 majorversion="1" |
360 minorversion="2" | 360 minorversion="2" |
361 microversion="2"> | 361 microversion="3"> |
362 <title subtitle="Version"> | 362 <title subtitle="Version"> |
363 <tm>JVM</tm> Tool Interface | 363 <tm>JVM</tm> Tool Interface |
364 </title> | 364 </title> |
365 | 365 |
366 <intro id="whatIs" label="What is the JVM Tool Interface?"> | 366 <intro id="whatIs" label="What is the JVM Tool Interface?"> |
429 platform equivalent of a dynamic library. On the <tm>Windows</tm> operating | 429 platform equivalent of a dynamic library. On the <tm>Windows</tm> operating |
430 system, for example, an agent library is a "Dynamic Linked Library" (DLL). | 430 system, for example, an agent library is a "Dynamic Linked Library" (DLL). |
431 On the <tm>Solaris</tm> Operating Environment, an agent library is a shared | 431 On the <tm>Solaris</tm> Operating Environment, an agent library is a shared |
432 object (<code>.so</code> file). | 432 object (<code>.so</code> file). |
433 <p/> | 433 <p/> |
434 | |
434 An agent may be started at VM startup by specifying the agent library | 435 An agent may be started at VM startup by specifying the agent library |
435 name using a <internallink id="starting">command line option</internallink>. | 436 name using a <internallink id="starting">command line option</internallink>. |
436 Some implementations may support a mechanism to <internallink id="onattach"> | 437 Some implementations may support a mechanism to <internallink id="onattach"> |
437 start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>. | 438 start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>. |
438 The details of how this is initiated are implementation specific. | 439 The details of how this is initiated are implementation specific. |
439 </intro> | 440 </intro> |
441 | |
442 <intro id="entry point" label="Statically Linked Agents (since version 1.2.3)"> | |
443 | |
444 A native JVMTI Agent may be <i>statically linked</i> with the VM. | |
445 The manner in which the library and VM image are combined is | |
446 implementation-dependent. | |
447 An agent L whose image has been combined with the VM is defined as | |
448 <i>statically linked</i> if and only if the agent exports a function | |
449 called Agent_OnLoad_L. | |
450 <p/> | |
451 If a <i>statically linked</i> agent L exports a function called | |
452 Agent_OnLoad_L and a function called Agent_OnLoad, the Agent_OnLoad | |
453 function will be ignored. | |
454 If an agent L is <i>statically linked</i>, an Agent_OnLoad_L | |
455 function will be invoked with the same arguments and expected return | |
456 value as specified for the Agent_OnLoad function. | |
457 An agent L that is <i>statically linked</i> will prohibit an agent of | |
458 the same name from being loaded dynamically. | |
459 <p/> | |
460 The VM will invoke the Agent_OnUnload_L function of the agent, if such | |
461 a function is exported, at the same point during startup as it would | |
462 have called the dynamic entry point Agent_OnUnLoad. | |
463 If a <i>statically linked</i> agent L exports a function called | |
464 Agent_OnUnLoad_L and a function called Agent_OnUnLoad, the Agent_OnUnLoad | |
465 function will be ignored. | |
466 <p/> | |
467 If an agent L is <i>statically linked</i>, an Agent_OnAttach_L function | |
468 will be invoked with the same arguments and expected return value as | |
469 specified for the Agent_OnAttach function. | |
470 If a <i>statically linked</i> agent L exports a function called | |
471 Agent_OnAttach_L and a function called Agent_OnAttach, the Agent_OnAttach | |
472 function will be ignored. | |
473 </intro> | |
440 | 474 |
441 <intro id="starting" label="Agent Command Line Options"> | 475 <intro id="starting" label="Agent Command Line Options"> |
442 The term "command-line option" is used below to | 476 The term "command-line option" is used below to |
443 mean options supplied in the <code>JavaVMInitArgs</code> argument | 477 mean options supplied in the <code>JavaVMInitArgs</code> argument |
444 to the <code>JNI_CreateJavaVM</code> function of the JNI | 478 to the <code>JNI_CreateJavaVM</code> function of the JNI |
453 <dl> | 487 <dl> |
454 <dt><code>-agentlib:</code><i><agent-lib-name></i><code>=</code><i><options></i></dt> | 488 <dt><code>-agentlib:</code><i><agent-lib-name></i><code>=</code><i><options></i></dt> |
455 <dd> | 489 <dd> |
456 The name following <code>-agentlib:</code> is the name of the | 490 The name following <code>-agentlib:</code> is the name of the |
457 library to load. Lookup of the library, both its full name and location, | 491 library to load. Lookup of the library, both its full name and location, |
458 proceeds in a platform-specific manner. | 492 proceeds in a platform-specific manner. |
459 Typically, the <i><agent-lib-name></i> is expanded to an | 493 Typically, the <i><agent-lib-name></i> is expanded to an |
460 operating system specific file name. | 494 operating system specific file name. |
461 The <i><options></i> will be passed to the agent on start-up. | 495 The <i><options></i> will be passed to the agent on start-up. |
462 For example, if the option | 496 For example, if the option |
463 <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to | 497 <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to |
464 load the shared library <code>foo.dll</code> from the system <code>PATH</code> | 498 load the shared library <code>foo.dll</code> from the system <code>PATH</code> |
465 under <tm>Windows</tm> or <code>libfoo.so</code> from the | 499 under <tm>Windows</tm> or <code>libfoo.so</code> from the |
466 <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating environment. | 500 <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating |
501 environment. | |
502 If the agent library is statically linked into the executable | |
503 then no actual loading takes place. | |
504 <p/> | |
467 </dd> | 505 </dd> |
468 <dt><code>-agentpath:</code><i><path-to-agent></i><code>=</code><i><options></i></dt> | 506 <dt><code>-agentpath:</code><i><path-to-agent></i><code>=</code><i><options></i></dt> |
469 <dd> | 507 <dd> |
470 The path following <code>-agentpath:</code> is the absolute path from which | 508 The path following <code>-agentpath:</code> is the absolute path from which |
471 to load the library. | 509 to load the library. |
472 No library name expansion will occur. | 510 No library name expansion will occur. |
473 The <i><options></i> will be passed to the agent on start-up. | 511 The <i><options></i> will be passed to the agent on start-up. |
474 For example, if the option | 512 For example, if the option |
475 <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to | 513 <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to |
476 load the shared library <code>c:\myLibs\foo.dll</code>. | 514 load the shared library <code>c:\myLibs\foo.dll</code>. If the agent |
515 library is statically linked into the executable | |
516 then no actual loading takes place. | |
517 <p/> | |
477 </dd> | 518 </dd> |
478 </dl> | 519 </dl> |
479 The start-up routine <internallink id="onload"><code>Agent_OnLoad</code></internallink> | 520 For a dynamic shared library agent, the start-up routine |
480 in the library will be invoked. | 521 <internallink id="onload"><code>Agent_OnLoad</code></internallink> |
522 in the library will be invoked. If the agent library is statically linked | |
523 into the executable then the system will attempt to invoke the | |
524 <code>Agent_OnLoad_<agent-lib-name></code> entry point where | |
525 <agent-lib-name> is the basename of the | |
526 agent. In the above example <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code>, | |
527 the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine. | |
481 <p/> | 528 <p/> |
482 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code> | 529 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code> |
483 will be searched for JNI native method implementations to facilitate the | 530 will be searched for JNI native method implementations to facilitate the |
484 use of Java programming language code in tools, as is needed for | 531 use of Java programming language code in tools, as is needed for |
485 <internallink id="bci">bytecode instrumentation</internallink>. | 532 <internallink id="bci">bytecode instrumentation</internallink>. |
500 <intro id="startup" label="Agent Start-Up"> | 547 <intro id="startup" label="Agent Start-Up"> |
501 The VM starts each agent by invoking a start-up function. | 548 The VM starts each agent by invoking a start-up function. |
502 If the agent is started in the <code>OnLoad</code> | 549 If the agent is started in the <code>OnLoad</code> |
503 <functionlink id="GetPhase">phase</functionlink> the function | 550 <functionlink id="GetPhase">phase</functionlink> the function |
504 <internallink id="onload"><code>Agent_OnLoad</code></internallink> | 551 <internallink id="onload"><code>Agent_OnLoad</code></internallink> |
505 will be invoked. | 552 or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink> |
553 for statically linked agents will be invoked. | |
506 If the agent is started in the live | 554 If the agent is started in the live |
507 <functionlink id="GetPhase">phase</functionlink> the function | 555 <functionlink id="GetPhase">phase</functionlink> the function |
508 <internallink id="onattach"><code>Agent_OnAttach</code></internallink> | 556 <internallink id="onattach"><code>Agent_OnAttach</code></internallink> |
509 will be invoked. | 557 or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink> |
558 for statically linked agents will be invoked. | |
510 Exactly one call to a start-up function is made per agent. | 559 Exactly one call to a start-up function is made per agent. |
511 </intro> | 560 </intro> |
512 | 561 |
513 <intro id="onload" label="Agent Start-Up (OnLoad phase)"> | 562 <intro id="onload" label="Agent Start-Up (OnLoad phase)"> |
514 If an agent is started during the <code>OnLoad</code> phase then its | 563 If an agent is started during the <code>OnLoad</code> phase then its |
515 agent library must export a start-up function with the following prototype: | 564 agent library must export a start-up function with the following prototype: |
516 <example> | 565 <example> |
517 JNIEXPORT jint JNICALL | 566 JNIEXPORT jint JNICALL |
518 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example> | 567 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example> |
568 Or for a statically linked agent named 'L': | |
569 <example> | |
570 JNIEXPORT jint JNICALL | |
571 Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved)</example> | |
572 | |
519 The VM will start the agent by calling this function. | 573 The VM will start the agent by calling this function. |
520 It will be called early enough in VM initialization that: | 574 It will be called early enough in VM initialization that: |
521 <ul> | 575 <ul> |
522 <li><functionlink id="SetSystemProperty">system properties</functionlink> | 576 <li><functionlink id="SetSystemProperty">system properties</functionlink> |
523 may be set before they have been used in the start-up of the VM</li> | 577 may be set before they have been used in the start-up of the VM</li> |
529 <li>no bytecodes have executed</li> | 583 <li>no bytecodes have executed</li> |
530 <li>no classes have been loaded</li> | 584 <li>no classes have been loaded</li> |
531 <li>no objects have been created</li> | 585 <li>no objects have been created</li> |
532 </ul> | 586 </ul> |
533 <p/> | 587 <p/> |
534 The VM will call the <code>Agent_OnLoad</code> function with | 588 The VM will call the <code>Agent_OnLoad</code> or |
589 <code>Agent_OnLoad_<agent-lib-name></code> function with | |
535 <i><options></i> as the second argument - | 590 <i><options></i> as the second argument - |
536 that is, using the command-line option examples, | 591 that is, using the command-line option examples, |
537 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> | 592 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> |
538 argument of <code>Agent_OnLoad</code>. | 593 argument of <code>Agent_OnLoad</code>. |
539 The <code>options</code> argument is encoded as a | 594 The <code>options</code> argument is encoded as a |
540 <internallink id="mUTF">modified UTF-8</internallink> string. | 595 <internallink id="mUTF">modified UTF-8</internallink> string. |
541 If <i>=<options></i> is not specified, | 596 If <i>=<options></i> is not specified, |
542 a zero length string is passed to <code>options</code>. | 597 a zero length string is passed to <code>options</code>. |
543 The lifespan of the <code>options</code> string is the <code>Agent_OnLoad</code> | 598 The lifespan of the <code>options</code> string is the |
599 <code>Agent_OnLoad</code> or <code>Agent_OnLoad_<agent-lib-name></code> | |
544 call. If needed beyond this time the string or parts of the string must | 600 call. If needed beyond this time the string or parts of the string must |
545 be copied. | 601 be copied. |
546 The period between when <code>Agent_OnLoad</code> is called and when it | 602 The period between when <code>Agent_OnLoad</code> is called and when it |
547 returns is called the <i>OnLoad phase</i>. | 603 returns is called the <i>OnLoad phase</i>. |
548 Since the VM is not initialized during the OnLoad | 604 Since the VM is not initialized during the OnLoad |
568 Early startup is also needed so that agents can control the execution | 624 Early startup is also needed so that agents can control the execution |
569 environment - modifying the file system and system properties to install | 625 environment - modifying the file system and system properties to install |
570 their functionality. | 626 their functionality. |
571 </rationale> | 627 </rationale> |
572 <p/> | 628 <p/> |
573 The return value from <code>Agent_OnLoad</code> is used to indicate an error. | 629 The return value from <code>Agent_OnLoad</code> or |
630 <code>Agent_OnLoad_<agent-lib-name></code> is used to indicate an error. | |
574 Any value other than zero indicates an error and causes termination of the VM. | 631 Any value other than zero indicates an error and causes termination of the VM. |
575 </intro> | 632 </intro> |
576 | 633 |
577 <intro id="onattach" label="Agent Start-Up (Live phase)"> | 634 <intro id="onattach" label="Agent Start-Up (Live phase)"> |
578 A VM may support a mechanism that allows agents to be started in the VM during the live | 635 A VM may support a mechanism that allows agents to be started in the VM during the live |
585 must export a start-up function | 642 must export a start-up function |
586 with the following prototype: | 643 with the following prototype: |
587 <example> | 644 <example> |
588 JNIEXPORT jint JNICALL | 645 JNIEXPORT jint JNICALL |
589 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example> | 646 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example> |
647 Or for a statically linked agent named 'L': | |
648 <example> | |
649 JNIEXPORT jint JNICALL | |
650 Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved)</example> | |
651 | |
590 <p/> | 652 <p/> |
591 The VM will start the agent by calling this function. | 653 The VM will start the agent by calling this function. |
592 It will be called in the context of a thread | 654 It will be called in the context of a thread |
593 that is attached to the VM. The first argument <i><vm></i> is the Java VM. | 655 that is attached to the VM. The first argument <i><vm></i> is the Java VM. |
594 The <i><options></i> argument is the startup options provided to the agent. | 656 The <i><options></i> argument is the startup options provided to the agent. |
595 <i><options></i> is encoded as a <internallink id="mUTF">modified UTF-8 | 657 <i><options></i> is encoded as a <internallink id="mUTF">modified UTF-8 |
596 </internallink> string. | 658 </internallink> string. |
597 If startup options were not provided, a zero length string is passed to | 659 If startup options were not provided, a zero length string is passed to |
598 <code>options</code>. The lifespan of the <code>options</code> string is the | 660 <code>options</code>. The lifespan of the <code>options</code> string is the |
599 <code>Agent_OnAttach</code> call. If needed beyond this time the string or parts of | 661 <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name></code> call. |
600 the string must be copied. | 662 If needed beyond this time the string or parts of the string must be copied. |
601 <p/> | 663 <p/> |
602 Note that some <internallink id="capability">capabilities</internallink> | 664 Note that some <internallink id="capability">capabilities</internallink> |
603 may not be available in the live phase. | 665 may not be available in the live phase. |
604 <p/> | 666 <p/> |
605 The <code>Agent_OnAttach</code> function initializes the agent and returns a value | 667 The <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name |
668 ></code> function initializes the agent and returns a value | |
606 to the VM to indicate if an error occurred. Any value other than zero indicates an error. | 669 to the VM to indicate if an error occurred. Any value other than zero indicates an error. |
607 An error does not cause the VM to terminate. Instead the VM ignores the error, or takes | 670 An error does not cause the VM to terminate. Instead the VM ignores the error, or takes |
608 some implementation specific action -- for example it might print an error to standard error, | 671 some implementation specific action -- for example it might print an error to standard error, |
609 or record the error in a system log. | 672 or record the error in a system log. |
610 </intro> | 673 </intro> |
613 The library may optionally export a | 676 The library may optionally export a |
614 shutdown function with the following prototype: | 677 shutdown function with the following prototype: |
615 <example> | 678 <example> |
616 JNIEXPORT void JNICALL | 679 JNIEXPORT void JNICALL |
617 Agent_OnUnload(JavaVM *vm)</example> | 680 Agent_OnUnload(JavaVM *vm)</example> |
681 Or for a statically linked agent named 'L': | |
682 <example> | |
683 JNIEXPORT void JNICALL | |
684 Agent_OnUnload_L(JavaVM *vm)</example> | |
685 | |
618 This function will be called by the VM when the library is about to be unloaded. | 686 This function will be called by the VM when the library is about to be unloaded. |
619 The library will be unloaded and this function will be called if some platform specific | 687 The library will be unloaded (unless it is statically linked into the |
688 executable) and this function will be called if some platform specific | |
620 mechanism causes the unload (an unload mechanism is not specified in this document) | 689 mechanism causes the unload (an unload mechanism is not specified in this document) |
621 or the library is (in effect) unloaded by the termination of the VM whether through | 690 or the library is (in effect) unloaded by the termination of the VM whether through |
622 normal termination or VM failure, including start-up failure. | 691 normal termination or VM failure, including start-up failure. |
623 Uncontrolled shutdown is, of couse, an exception to this rule. | 692 Uncontrolled shutdown is, of couse, an exception to this rule. |
624 Note the distinction between this function and the | 693 Note the distinction between this function and the |
625 <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event | 694 <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event |
626 to be sent, the VM must have run at least to the point of initialization and a valid | 695 to be sent, the VM must have run at least to the point of initialization and a valid |
627 <jvmti/> environment must exist which has set a callback for VMDeath | 696 <jvmti/> environment must exist which has set a callback for VMDeath |
628 and enabled the event | 697 and enabled the event. |
629 None of these are required for <code>Agent_OnUnload</code> and this function | 698 None of these are required for <code>Agent_OnUnload</code> or |
699 <code>Agent_OnUnload_<agent-lib-name></code> and this function | |
630 is also called if the library is unloaded for other reasons. | 700 is also called if the library is unloaded for other reasons. |
631 In the case that a VM Death event is sent, it will be sent before this | 701 In the case that a VM Death event is sent, it will be sent before this |
632 function is called (assuming this function is called due to VM termination). | 702 function is called (assuming this function is called due to VM termination). |
633 This function can be used to clean-up resources allocated by the agent. | 703 This function can be used to clean-up resources allocated by the agent. |
634 </intro> | 704 </intro> |
10699 Return the current phase of VM execution. | 10769 Return the current phase of VM execution. |
10700 The phases proceed in sequence: | 10770 The phases proceed in sequence: |
10701 <constants id="jvmtiPhase" label="Phases of execution" kind="enum"> | 10771 <constants id="jvmtiPhase" label="Phases of execution" kind="enum"> |
10702 <constant id="JVMTI_PHASE_ONLOAD" num="1"> | 10772 <constant id="JVMTI_PHASE_ONLOAD" num="1"> |
10703 <code>OnLoad</code> phase: while in the | 10773 <code>OnLoad</code> phase: while in the |
10704 <internallink id="onload"><code>Agent_OnLoad</code></internallink> function. | 10774 <internallink id="onload"><code>Agent_OnLoad</code></internallink> |
10775 or, for statically linked agents, the <internallink id="onload"> | |
10776 <code>Agent_OnLoad_<agent-lib-name> | |
10777 </code></internallink> function. | |
10705 </constant> | 10778 </constant> |
10706 <constant id="JVMTI_PHASE_PRIMORDIAL" num="2"> | 10779 <constant id="JVMTI_PHASE_PRIMORDIAL" num="2"> |
10707 Primordial phase: between return from <code>Agent_OnLoad</code> and the | 10780 Primordial phase: between return from <code>Agent_OnLoad</code> |
10781 or <code>Agent_OnLoad_<agent-lib-name></code> and the | |
10708 <code>VMStart</code> event. | 10782 <code>VMStart</code> event. |
10709 </constant> | 10783 </constant> |
10710 <constant id="JVMTI_PHASE_START" num="6"> | 10784 <constant id="JVMTI_PHASE_START" num="6"> |
10711 Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event | 10785 Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event |
10712 is sent and until the <code>VMInit</code> event is sent. | 10786 is sent and until the <code>VMInit</code> event is sent. |
14259 Add ResourceExhaustedEvent. | 14333 Add ResourceExhaustedEvent. |
14260 </change> | 14334 </change> |
14261 <change date="11 October 2012" version="1.2.2"> | 14335 <change date="11 October 2012" version="1.2.2"> |
14262 Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool. | 14336 Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool. |
14263 </change> | 14337 </change> |
14338 <change date="19 June 2013" version="1.2.3"> | |
14339 Added support for statically linked agents. | |
14340 </change> | |
14264 </changehistory> | 14341 </changehistory> |
14265 | 14342 |
14266 </specification> | 14343 </specification> |
14267 <!-- Keep this comment at the end of the file | 14344 <!-- Keep this comment at the end of the file |
14268 Local variables: | 14345 Local variables: |