README
1Copyright (c) 2003, 2018, Oracle and/or its affiliates. All rights reserved.
2DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3
4This code is free software; you can redistribute it and/or modify it
5under the terms of the GNU General Public License version 2 only, as
6published by the Free Software Foundation.
7
8This code is distributed in the hope that it will be useful, but WITHOUT
9ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
11version 2 for more details (a copy is included in the LICENSE file that
12accompanied this code).
13
14You should have received a copy of the GNU General Public License version
152 along with this work; if not, write to the Free Software Foundation,
16Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
17
18Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
19or visit www.oracle.com if you need additional information or have any
20questions.
21
22---------------------------------------------------------------------------------
23
24This directory contains source files of testbase_nsk JVMTI framework,
25which 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
42jvmti_tools.h
43
44Provides functions and macroses for invocation of JVMTI functions
45and checking JVMTI errors:
46
47 NSK_JVMTI_VERIFY(call)
48 NSK_JVMTI_VERIFY_NEGATIVE(call)
49 NSK_JVMTI_VERIFY_CODE(code, action)
50
51Also 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
120Typical example of usage of the NSK_JVMTI_VERIFY macro
121for 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
128or 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
138JVMTITools.h
139
140Provides set of functions which convert JVMTI binary data to
141a 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
153Injector.h
154
155Provides class file format constants and the function which inject some
156profiling 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---------------------------------------------------------------------------------
162