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 NSK_JVMTI_VERIFY and NSK_CPP_STUB macroses
121for invocation of JVMTI functions:
122
123    // jvmti->GetVersion(jvmti, &version)
124    if (!NSK_JVMTI_VERIFY(
125            NSK_CPP_STUB2(GetVersion, jvmti, &version) != NULL)) {
126        return JNI_ERR;
127    }
128
129or with saving error code:
130
131    // err = jvmti->GetVersion(jvmti, &version)
132    if (!NSK_JVMTI_VERIFY(err =
133            NSK_CPP_STUB2(GetVersion, jvmti, &version))) {
134        return err;
135    }
136        functions: nsk_jvmti_*
137
138---------------------------------------------------------------------------------
139
140JVMTITools.h
141
142Provides set of functions which convert JVMTI binary data to
143a null-terminated character string:
144
145
146    const char* TranslateEvent(jvmtiEvent event_type);
147    const char* TranslateState(jint flags);
148    const char* TranslateError(jvmtiError err);
149    const char* TranslatePhase(jvmtiPhase phase);
150    const char* TranslateRootKind(jvmtiHeapRootKind root);
151    const char* TranslateObjectRefKind(jvmtiObjectReferenceKind ref);
152
153---------------------------------------------------------------------------------
154
155Injector.h
156
157Provides class file format constants and the function which inject some
158profiling bytecodes into Java class files:
159
160    int Inject(const u1* old_bytes, const jint old_length,
161               u1** new_bytes, jint* new_length, int bci_mode);
162
163---------------------------------------------------------------------------------
164