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