4185N/A * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 0N/A * published by the Free Software Foundation. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1472N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A// The RedefineClasses() API is used to change the definition of one or 0N/A// more classes. While the API supports redefining more than one class 0N/A// in a single call, in general, the API is discussed in the context of 0N/A// changing the definition of a single current class to a single new 0N/A// class. For clarity, the current class is will always be called 0N/A// "the_class" and the new class will always be called "scratch_class". 0N/A// The name "the_class" is used because there is only one structure 0N/A// that represents a specific class; redefinition does not replace the 0N/A// structure, but instead replaces parts of the structure. The name 0N/A// "scratch_class" is used because the structure that represents the 0N/A// new definition of a specific class is simply used to carry around 0N/A// the parts of the new definition until they are used to replace the 0N/A// appropriate parts in the_class. Once redefinition of a class is 0N/A// complete, scratch_class is thrown away. 0N/A// Implementation Overview: 0N/A// The RedefineClasses() API is mostly a wrapper around the VM op that 0N/A// does the real work. The work is split in varying degrees between 0N/A// doit_prologue(), doit() and doit_epilogue(). 0N/A// 1) doit_prologue() is called by the JavaThread on the way to a 0N/A// safepoint. It does parameter verification and loads scratch_class 0N/A// - parsing the incoming class definition using the_class' class 0N/A// loader and security context 0N/A// - linking scratch_class 0N/A// - merging constant pools and rewriting bytecodes as needed 0N/A// for the merged constant pool 0N/A// - verifying the bytecodes in scratch_class 0N/A// - setting up the constant pool cache and rewriting bytecodes 0N/A// as needed to use the cache 0N/A// - finally, scratch_class is compared to the_class to verify 0N/A// that it is a valid replacement class 0N/A// - if everything is good, then scratch_class is saved in an 0N/A// instance field in the VM operation for the doit() call 0N/A// Note: A JavaThread must do the above work. 0N/A// 2) doit() is called by the VMThread during a safepoint. It installs 0N/A// the new class definition(s) which involves: 0N/A// - retrieving the scratch_class from the instance field in the 0N/A// - house keeping (flushing breakpoints and caches, deoptimizing 0N/A// dependent compiled code) 0N/A// - replacing parts in the_class with parts from scratch_class 0N/A// - adding weak reference(s) to track the obsolete but interesting 0N/A// parts of the_class 0N/A// - adjusting constant pool caches and vtables in other classes 0N/A// that refer to methods in the_class. These adjustments use the 0N/A// SystemDictionary::classes_do() facility which only allows 0N/A// a helper method to be specified. The interesting parameters 0N/A// that we would like to pass to the helper method are saved in 0N/A// static global fields in the VM operation. 0N/A// - telling the SystemDictionary to notice our changes 0N/A// Note: the above work must be done by the VMThread to be safe. 0N/A// 3) doit_epilogue() is called by the JavaThread after the VM op 0N/A// is finished and the safepoint is done. It simply cleans up 0N/A// memory allocated in doit_prologue() and used in doit(). 0N/A// Constant Pool Details: 0N/A// When the_class is redefined, we cannot just replace the constant 0N/A// pool in the_class with the constant pool from scratch_class because 0N/A// that could confuse obsolete methods that may still be running. 0N/A// Instead, the constant pool from the_class, old_cp, is merged with 0N/A// the constant pool from scratch_class, scratch_cp. The resulting 0N/A// constant pool, merge_cp, replaces old_cp in the_class. 0N/A// The key part of any merging algorithm is the entry comparison 0N/A// function so we have to know the types of entries in a constant pool 0N/A// in order to merge two of them together. Constant pools can contain 0N/A// up to 12 different kinds of entries; the JVM_CONSTANT_Unicode entry 0N/A// is not presently used so we only have to worry about the other 11 0N/A// entry types. For the purposes of constant pool merging, it is 0N/A// helpful to know that the 11 entry types fall into 3 different 0N/A// subtypes: "direct", "indirect" and "double-indirect". 0N/A// Direct CP entries contain data and do not contain references to 0N/A// other CP entries. The following are direct CP entries: 0N/A// JVM_CONSTANT_{Double,Float,Integer,Long,Utf8} 0N/A// Indirect CP entries contain 1 or 2 references to a direct CP entry 0N/A// and no other data. The following are indirect CP entries: 0N/A// JVM_CONSTANT_{Class,NameAndType,String} 0N/A// Double-indirect CP entries contain two references to indirect CP 0N/A// entries and no other data. The following are double-indirect CP 0N/A// JVM_CONSTANT_{Fieldref,InterfaceMethodref,Methodref} 0N/A// When comparing entries between two constant pools, the entry types 0N/A// are compared first and if they match, then further comparisons are 0N/A// made depending on the entry subtype. Comparing direct CP entries is 0N/A// simply a matter of comparing the data associated with each entry. 0N/A// Comparing both indirect and double-indirect CP entries requires 0N/A// Fortunately, the recursive combinations are limited because indirect 0N/A// CP entries can only refer to direct CP entries and double-indirect 0N/A// CP entries can only refer to indirect CP entries. The following is 0N/A// an example illustration of the deepest set of indirections needed to 0N/A// access the data associated with a JVM_CONSTANT_Fieldref entry: 0N/A// JVM_CONSTANT_Fieldref { 0N/A// class_index => JVM_CONSTANT_Class { 0N/A// name_index => JVM_CONSTANT_Utf8 { 0N/A// name_and_type_index => JVM_CONSTANT_NameAndType { 0N/A// name_index => JVM_CONSTANT_Utf8 { 0N/A// descriptor_index => JVM_CONSTANT_Utf8 { 0N/A// The above illustration is not a data structure definition for any 0N/A// computer language. The curly braces ('{' and '}') are meant to 0N/A// delimit the context of the "fields" in the CP entry types shown. 0N/A// Each indirection from the JVM_CONSTANT_Fieldref entry is shown via 0N/A// "=>", e.g., the class_index is used to indirectly reference a 0N/A// JVM_CONSTANT_Class entry where the name_index is used to indirectly 0N/A// reference a JVM_CONSTANT_Utf8 entry which contains the interesting 0N/A// <data-1>. In order to understand a JVM_CONSTANT_Fieldref entry, we 0N/A// have to do a total of 5 indirections just to get to the CP entries 0N/A// that contain the interesting pieces of data and then we have to 0N/A// fetch the three pieces of data. This means we have to do a total of 0N/A// (5 + 3) * 2 == 16 dereferences to compare two JVM_CONSTANT_Fieldref 0N/A// Here is the indirection, data and dereference count for each entry 0N/A// JVM_CONSTANT_Class 1 indir, 1 data, 2 derefs 0N/A// JVM_CONSTANT_Double 0 indir, 1 data, 1 deref 0N/A// JVM_CONSTANT_Fieldref 2 indir, 3 data, 8 derefs 0N/A// JVM_CONSTANT_Float 0 indir, 1 data, 1 deref 0N/A// JVM_CONSTANT_Integer 0 indir, 1 data, 1 deref 0N/A// JVM_CONSTANT_InterfaceMethodref 2 indir, 3 data, 8 derefs 0N/A// JVM_CONSTANT_Long 0 indir, 1 data, 1 deref 0N/A// JVM_CONSTANT_Methodref 2 indir, 3 data, 8 derefs 0N/A// JVM_CONSTANT_NameAndType 1 indir, 2 data, 4 derefs 0N/A// JVM_CONSTANT_String 1 indir, 1 data, 2 derefs 0N/A// JVM_CONSTANT_Utf8 0 indir, 1 data, 1 deref 0N/A// So different subtypes of CP entries require different amounts of 0N/A// work for a proper comparison. 0N/A// Now that we've talked about the different entry types and how to 0N/A// compare them we need to get back to merging. This is not a merge in 0N/A// the "sort -u" sense or even in the "sort" sense. When we merge two 0N/A// constant pools, we copy all the entries from old_cp to merge_cp, 0N/A// preserving entry order. Next we append all the unique entries from 0N/A// scratch_cp to merge_cp and we track the index changes from the 0N/A// location in scratch_cp to the possibly new location in merge_cp. 0N/A// When we are done, any obsolete code that is still running that 0N/A// uses old_cp should not be able to observe any difference if it 0N/A// were to use merge_cp. As for the new code in scratch_class, it is 0N/A// modified to use the appropriate index values in merge_cp before it 0N/A// is used to replace the code in the_class. 0N/A// There is one small complication in copying the entries from old_cp 0N/A// to merge_cp. Two of the CP entry types are special in that they are 0N/A// lazily resolved. Before explaining the copying complication, we need 0N/A// to digress into CP entry resolution. 0N/A// JVM_CONSTANT_Class and JVM_CONSTANT_String entries are present in 0N/A// the class file, but are not stored in memory as such until they are 0N/A// resolved. The entries are not resolved unless they are used because 0N/A// resolution is expensive. During class file parsing the entries are 0N/A// initially stored in memory as JVM_CONSTANT_ClassIndex and 0N/A// JVM_CONSTANT_StringIndex entries. These special CP entry types 0N/A// indicate that the JVM_CONSTANT_Class and JVM_CONSTANT_String entries 0N/A// have been parsed, but the index values in the entries have not been 0N/A// validated. After the entire constant pool has been parsed, the index 0N/A// values can be validated and then the entries are converted into 0N/A// JVM_CONSTANT_UnresolvedClass and JVM_CONSTANT_UnresolvedString 0N/A// entries. During this conversion process, the UTF8 values that are 0N/A// indirectly referenced by the JVM_CONSTANT_ClassIndex and 2062N/A// JVM_CONSTANT_StringIndex entries are changed into Symbol*s and the 2062N/A// entries are modified to refer to the Symbol*s. This optimization 0N/A// eliminates one level of indirection for those two CP entry types and 0N/A// gets the entries ready for verification. During class file parsing 0N/A// it is also possible for JVM_CONSTANT_UnresolvedString entries to be 0N/A// resolved into JVM_CONSTANT_String entries. Verification expects to 0N/A// find JVM_CONSTANT_UnresolvedClass and either JVM_CONSTANT_String or 0N/A// JVM_CONSTANT_UnresolvedString entries and not JVM_CONSTANT_Class 0N/A// Now we can get back to the copying complication. When we copy 0N/A// entries from old_cp to merge_cp, we have to revert any 0N/A// JVM_CONSTANT_Class entries to JVM_CONSTANT_UnresolvedClass entries 0N/A// or verification will fail. 0N/A// It is important to explicitly state that the merging algorithm 0N/A// effectively unresolves JVM_CONSTANT_Class entries that were in the 0N/A// old_cp when they are changed into JVM_CONSTANT_UnresolvedClass 0N/A// entries in the merge_cp. This is done both to make verification 0N/A// happy and to avoid adding more brittleness between RedefineClasses 0N/A// and the constant pool cache. By allowing the constant pool cache 0N/A// implementation to (re)resolve JVM_CONSTANT_UnresolvedClass entries 0N/A// into JVM_CONSTANT_Class entries, we avoid having to embed knowledge 0N/A// about those algorithms in RedefineClasses. 0N/A// Appending unique entries from scratch_cp to merge_cp is straight 0N/A// forward for direct CP entries and most indirect CP entries. For the 0N/A// indirect CP entry type JVM_CONSTANT_NameAndType and for the double- 0N/A// indirect CP entry types, the presence of more than one piece of 0N/A// interesting data makes appending the entries more complicated. 0N/A// For the JVM_CONSTANT_{Double,Float,Integer,Long,Utf8} entry types, 0N/A// the entry is simply copied from scratch_cp to the end of merge_cp. 0N/A// If the index in scratch_cp is different than the destination index 0N/A// in merge_cp, then the change in index value is tracked. 0N/A// Note: the above discussion for the direct CP entries also applies 0N/A// to the JVM_CONSTANT_Unresolved{Class,String} entry types. 0N/A// For the JVM_CONSTANT_{Class,String} entry types, since there is only 0N/A// one data element at the end of the recursion, we know that we have 0N/A// either one or two unique entries. If the JVM_CONSTANT_Utf8 entry is 0N/A// unique then it is appended to merge_cp before the current entry. 0N/A// If the JVM_CONSTANT_Utf8 entry is not unique, then the current entry 0N/A// is updated to refer to the duplicate entry in merge_cp before it is 0N/A// appended to merge_cp. Again, any changes in index values are tracked 0N/A// Note: the above discussion for JVM_CONSTANT_{Class,String} entry 0N/A// types is theoretical. Since those entry types have already been 0N/A// optimized into JVM_CONSTANT_Unresolved{Class,String} entry types, 0N/A// they are handled as direct CP entries. 0N/A// For the JVM_CONSTANT_NameAndType entry type, since there are two 0N/A// data elements at the end of the recursions, we know that we have 0N/A// between one and three unique entries. Any unique JVM_CONSTANT_Utf8 0N/A// entries are appended to merge_cp before the current entry. For any 0N/A// JVM_CONSTANT_Utf8 entries that are not unique, the current entry is 0N/A// updated to refer to the duplicate entry in merge_cp before it is 0N/A// appended to merge_cp. Again, any changes in index values are tracked 0N/A// For the JVM_CONSTANT_{Fieldref,InterfaceMethodref,Methodref} entry 0N/A// types, since there are two indirect CP entries and three data 0N/A// elements at the end of the recursions, we know that we have between 0N/A// one and six unique entries. See the JVM_CONSTANT_Fieldref diagram 0N/A// above for an example of all six entries. The uniqueness algorithm 0N/A// for the JVM_CONSTANT_Class and JVM_CONSTANT_NameAndType entries is 0N/A// covered above. Any unique entries are appended to merge_cp before 0N/A// the current entry. For any entries that are not unique, the current 0N/A// entry is updated to refer to the duplicate entry in merge_cp before 0N/A// it is appended to merge_cp. Again, any changes in index values are 0N/A// tracked as needed. 0N/A// Details for other parts of RedefineClasses need to be written. 0N/A// This is a placeholder section. 0N/A// Open Issues (in no particular order): 0N/A// - How do we serialize the RedefineClasses() API without deadlocking? 0N/A// - SystemDictionary::parse_stream() was called with a NULL protection 0N/A// domain since the initial version. This has been changed to pass 0N/A// the_class->protection_domain(). This change has been tested with 0N/A// all NSK tests and nothing broke, but what will adding it now break 0N/A// in ways that we don't test? 0N/A// - GenerateOopMap::rewrite_load_or_store() has a comment in its 0N/A// (indirect) use of the Relocator class that the max instruction 0N/A// size is 4 bytes. goto_w and jsr_w are 5 bytes and wide/iinc is 0N/A// 6 bytes. Perhaps Relocator only needs a 4 byte buffer to do 0N/A// what it does to the bytecodes. More investigation is needed. 0N/A// - java.lang.Object methods can be called on arrays. This is 0N/A// implemented via the arrayKlassOop vtable which we don't 0N/A// then the new version of the method will not be called for array 0N/A// - How do we know if redefine_single_class() and the guts of 0N/A// instanceKlass are out of sync? I don't think this can be 0N/A// automated, but we should probably order the work in 0N/A// redefine_single_class() to match the order of field 0N/A// definitions in instanceKlass. We also need to add some 0N/A// comments about keeping things in sync. 0N/A// - set_new_constant_pool() is huge and we should consider refactoring 0N/A// it into smaller chunks of work. 0N/A// - The exception table update code in set_new_constant_pool() defines 0N/A// const values that are also defined in a local context elsewhere. 0N/A// The same literal values are also used in elsewhere. We need to 0N/A// coordinate a cleanup of these constants with Runtime. 0N/A // These static fields are needed by SystemDictionary::classes_do() 0N/A // facility and the adjust_cpool_cache_and_vtable() helper: 0N/A // The instance fields are used to pass information from 0N/A // doit_prologue() to doit() and doit_epilogue(). 0N/A // This operation is used by both RedefineClasses and 0N/A // RetransformClasses. Indicate which. 0N/A // _index_map_count is just an optimization for knowing if 0N/A // _index_map_p contains any entries. 0N/A // ptr to _class_count scratch_classes 0N/A // Performance measurement support. These timers do not cover all 0N/A // the work done for JVM/TI RedefineClasses() but they do cover 0N/A // the heavy lifting. 0N/A // These routines are roughly in call order unless otherwise noted. 0N/A // Load the caller's new class definition(s) into _scratch_classes. 0N/A // Constant pool merging work is done here as needed. Also calls 0N/A // compare_and_normalize_class_versions() to verify the class 0N/A // Verify that the caller provided class definition(s) that meet 0N/A // the restrictions of RedefineClasses. Normalize the order of 0N/A // overloaded methods as needed. 0N/A // Swap annotations[i] with annotations[j] 0N/A // Used by compare_and_normalize_class_versions() when normalizing 0N/A // overloaded methods or changing idnum as when adding or deleting methods. 0N/A // Figure out which new methods match old methods in name and signature, 0N/A // which methods have been added, and which are no longer present 0N/A // Change jmethodIDs to point to the new methods 0N/A // In addition to marking methods as obsolete, this routine 0N/A // records which methods are EMCP (Equivalent Module Constant 0N/A // Pool) in the emcp_methods BitMap and returns the number of 0N/A // EMCP methods via emcp_method_count_p. This information is 0N/A // used when information about the previous version of the_class 0N/A // is squirreled away. 0N/A // Unevolving classes may point to methods of the_class directly 0N/A // from their constant pool caches, itables, and/or vtables. We 0N/A // use the SystemDictionary::classes_do() facility and this helper 0N/A // to fix up these pointers. 0N/A // Install the redefinition of a class 0N/A // Increment the classRedefinedCount field in the specific instanceKlass 0N/A // and in all direct and indirect subclasses. 0N/A // Support for constant pool merging (these routines are in alpha 0N/A // Modifiable test must be shared between IsModifiableClass query 0N/A // and redefine implementation 1879N/A#
endif // SHARE_VM_PRIMS_JVMTIREDEFINECLASSES_HPP