1 Copyright (c) 2003, 2018, Oracle and/or its affiliates. All rights reserved.
2 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3
4 This code is free software; you can redistribute it and/or modify it
5 under the terms of the GNU General Public License version 2 only, as
6 published by the Free Software Foundation.
7
8 This code is distributed in the hope that it will be useful, but WITHOUT
9 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
11 version 2 for more details (a copy is included in the LICENSE file that
12 accompanied this code).
13
14 You should have received a copy of the GNU General Public License version
15 2 along with this work; if not, write to the Free Software Foundation,
16 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
17
18 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
19 or visit www.oracle.com if you need additional information or have any
20 questions.
21
22 ---------------------------------------------------------------------------------
23
24 This directory contains source files of testbase_nsk JVMTI framework,
25 which provides support for JVMTI tests and accessing JVMTI environment.
26
27 Source files:
28 jvmti_tools.h
29 jvmti_tools.c
30 agent_tools.c
31 Injector.h
32 Injector.c
33 JVMTITools.h
34 JVMTITools.c
35
36 Naming conventions:
37 macroses: NSK_JVMTI_*
38 functions: nsk_jvmti_*
39
40 ---------------------------------------------------------------------------------
41
42 jvmti_tools.h
43
44 Provides functions and macroses for invocation of JVMTI functions
45 and checking JVMTI errors:
46
47 NSK_JVMTI_VERIFY(call)
48 NSK_JVMTI_VERIFY_NEGATIVE(call)
49 NSK_JVMTI_VERIFY_CODE(code, action)
50
51 Also provides functions for running JVMTI agent:
52
53 - init agent with options:
54
55 int nsk_jvmti_parseOptions(const char options[]);
56
57 - access agent options
58
59 int nsk_jvmti_getWaitTime();
60 void nsk_jvmti_setWaitTime(int waittime);
61
62 const char* nsk_jvmti_findOptionValue(const char name[]);
63 const char* nsk_jvmti_findOptionStringValue(const char name[], const char* defaultValue);
64 int nsk_jvmti_findOptionIntValue(const char name[], int defaultValue);
65
66 int nsk_jvmti_getOptionsCount();
67 const char* nsk_jvmti_getOptionName(int i);
68 const char* nsk_jvmti_getOptionValue(int i);
69
70 - create JVMTI environment and register agent thread
71
72 jvmtiEnv* nsk_jvmti_createJVMTIEnv(JavaVM* jvm, void* reserved);
73 int nsk_jvmti_setAgentProc(jvmtiStartFunction proc, const void* arg);
74
75 - initialize multiple agent chain via processing of nativeMethodBind event
76
77 int nsk_jvmti_init_MA(jvmtiEventCallbacks* callbacks);
78
79 - access agent thread environment
80
81 jthread nsk_jvmti_getAgentThread();
82 jvmtiEnv* nsk_jvmti_getAgentJVMTIEnv();
83 JNIEnv* nsk_jvmti_getAgentJNIEnv();
84
85 - synchronize agent with debuggee
86
87 int nsk_jvmti_waitForSync(jlong timeout);
88 int nsk_jvmti_resumeSync();
89 void nsk_jvmti_sleep(jlong timeout);
90
91 - provide proper exit status
92
93 void nsk_jvmti_setFailStatus();
94 int nsk_jvmti_isFailStatus();
95 jint nsk_jvmti_getStatus();
96
97 - use locations and breakpoints
98
99 int nsk_jvmti_addLocationCapabilities();
100 int nsk_jvmti_addBreakpointCapabilities();
101
102 jlocation nsk_jvmti_getLineLocation(jclass cls, jmethodID method, int line);
103 jlocation nsk_jvmti_setLineBreakpoint(jclass cls, jmethodID method, int line);
104 jlocation nsk_jvmti_clearLineBreakpoint(jclass cls, jmethodID method, int line);
105
106 - find classes and threads
107
108 jclass nsk_jvmti_classBySignature(const char signature[]);
109 jthread nsk_jvmti_threadByName(const char name[]);
110
111 - events management
112
113 int nsk_jvmti_isOptionalEvent(jvmtiEvent event);
114 int nsk_jvmti_enableEvents(jvmtiEventMode enable, int size,
115 jvmtiEvent list[], jthread thread);
116 void nsk_jvmti_showPossessedCapabilities(jvmtiEnv *jvmti);
117
118 ---------------------------------------------------------------------------------
119
120 Typical example of usage of the NSK_JVMTI_VERIFY macro
121 for invocation of JVMTI functions:
122
123 // jvmti->GetVersion(jvmti, &version)
124 if (!NSK_JVMTI_VERIFY(jvmti->GetVersion(&version) != NULL)) {
125 return JNI_ERR;
126 }
127
128 or with saving error code:
129
130 // err = jvmti->GetVersion(jvmti, &version)
131 if (!NSK_JVMTI_VERIFY(err = jvmti->GetVersion(&version))) {
132 return err;
133 }
134 functions: nsk_jvmti_*
135
136 ---------------------------------------------------------------------------------
137
138 JVMTITools.h
139
140 Provides set of functions which convert JVMTI binary data to
141 a null-terminated character string:
142
143
144 const char* TranslateEvent(jvmtiEvent event_type);
145 const char* TranslateState(jint flags);
146 const char* TranslateError(jvmtiError err);
147 const char* TranslatePhase(jvmtiPhase phase);
148 const char* TranslateRootKind(jvmtiHeapRootKind root);
149 const char* TranslateObjectRefKind(jvmtiObjectReferenceKind ref);
150
151 ---------------------------------------------------------------------------------
152
153 Injector.h
154
155 Provides class file format constants and the function which inject some
156 profiling bytecodes into Java class files:
157
158 int Inject(const u1* old_bytes, const jint old_length,
159 u1** new_bytes, jint* new_length, int bci_mode);
160
161 ---------------------------------------------------------------------------------