1 /* 2 * Copyright (c) 2001, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. 8 * 9 * This code is distributed in the hope that it will be useful, but WITHOUT 10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 12 * version 2 for more details (a copy is included in the LICENSE file that 13 * accompanied this code). 14 * 15 * You should have received a copy of the GNU General Public License version 16 * 2 along with this work; if not, write to the Free Software Foundation, 17 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 18 * 19 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 20 * or visit www.oracle.com if you need additional information or have any 21 * questions. 22 * 23 */ 24 25 package sun.jvm.hotspot.debugger.win32.coff; 26 27 import java.util.*; 28 29 /** Provides iteration-style access to the symbols in the sstGlobalSym 30 (and possibly other) subsections of the VC++ 5.0 debug 31 information. Clients should walk down these platform-dependent 32 symbols and transform them into the platform-independent 33 interfaces described in the package sun.jvm.hotspot.debugger.csym. */ 34 35 public interface DebugVC50SymbolIterator 36 extends DebugVC50SymbolTypes, DebugVC50SymbolEnums { 37 38 /** Indicates whether this iterator has processed all of the 39 available symbols. */ done()40 public boolean done(); 41 42 /** Go to the next symbol. NOTE that the iterator is pointing at the 43 first symbol initially, so one should use a while (!iter.done()) 44 { ... iter.next(); } construct. 45 46 @throw NoSuchElementException if the iterator is already done 47 and next() is called. */ next()48 public void next() throws NoSuchElementException; 49 50 /** Length of record, in bytes, excluding the length field. */ getLength()51 public short getLength(); 52 53 /** The type enumeration is defined in {@link 54 sun.jvm.hotspot.debugger.win32.coff.DebugVC50SymbolTypes} */ getType()55 public int getType(); 56 57 /** For debugging: returns the file offset of the current symbol. */ getOffset()58 public int getOffset(); 59 60 ///////////////////////// 61 // S_COMPILE accessors // 62 ///////////////////////// 63 64 /** Machine enumeration specifying target processor; see 65 DebugVC50SymbolEnums. */ getCompilerTargetProcessor()66 public byte getCompilerTargetProcessor(); 67 68 /** Compile flags; see DebugVC50SymbolEnums. */ getCompilerFlags()69 public int getCompilerFlags(); 70 71 /** Length-prefixed string specifying language processor version. 72 Language processors can place additional data in version string 73 if desired. */ getComplierVersion()74 public String getComplierVersion(); 75 76 ////////////////////////// 77 // S_REGISTER accessors // 78 ////////////////////////// 79 80 /** Type of the symbol which is in the register */ getRegisterSymbolType()81 public int getRegisterSymbolType(); 82 83 /** Enumerate of the registers in which the symbol is stored. The 84 high and low bytes are treated independently for values split 85 across two registers (i.e., 64-bit values on a 32-bit machine.) */ getRegisterEnum()86 public short getRegisterEnum(); 87 88 /** Length-prefixed name of the symbol stored in the register. */ getRegisterSymbolName()89 public String getRegisterSymbolName(); 90 91 // Note: register tracking elided as it is not implemented in the 92 // Microsoft compilers. 93 94 ////////////////////////// 95 // S_CONSTANT accessors // 96 ////////////////////////// 97 98 /** Type of symbol or containing enum. This record is used to output 99 constants and C enumerations. If used to output an enumeration, 100 then the type index refers to the containing enum. */ getConstantType()101 public int getConstantType(); 102 103 /** Numeric leaf containing the value of the symbol as an int */ getConstantValueAsInt()104 public int getConstantValueAsInt() throws DebugVC50WrongNumericTypeException; 105 106 /** Numeric leaf containing the value of the symbol as a long */ getConstantValueAsLong()107 public long getConstantValueAsLong() throws DebugVC50WrongNumericTypeException; 108 109 /** Numeric leaf containing the value of the symbol as a float */ getConstantValueAsFloat()110 public float getConstantValueAsFloat() throws DebugVC50WrongNumericTypeException; 111 112 /** Numeric leaf containing the value of the symbol as a double */ getConstantValueAsDouble()113 public double getConstantValueAsDouble() throws DebugVC50WrongNumericTypeException; 114 115 /** Length-prefixed name of the symbol */ getConstantName()116 public String getConstantName(); 117 118 ///////////////////// 119 // S_UDT accessors // 120 ///////////////////// 121 122 /** Type of symbol. This specifies a C typedef or user-defined type, 123 such as classes, structures, unions, or enums. */ getUDTType()124 public int getUDTType(); 125 126 /** Length-prefixed name of the user defined type. */ getUDTName()127 public String getUDTName(); 128 129 ///////////////////////// 130 // S_SSEARCH accessors // 131 ///////////////////////// 132 133 // FIXME: Add more documentation and understand what this does 134 135 /** $$SYMBOL offset of the procedure or thunk record for this module 136 that has the lowest offset for the specified segment. */ getSearchSymbolOffset()137 public int getSearchSymbolOffset(); 138 139 /** Segment (PE section) that this Start Search refers to. */ getSearchSegment()140 public short getSearchSegment(); 141 142 ///////////////////// 143 // S_END accessors // 144 ///////////////////// 145 146 // (No accessors) 147 // Closes the scope of the nearest preceding Block Start, Global 148 // Procedure Start, Local Procedure Start, With Start, or Thunk 149 // Start definition. 150 151 ////////////////////// 152 // S_SKIP accessors // 153 ////////////////////// 154 155 // (No accessors) 156 // Use the length field, available in every symbol, to skip over 157 // these records. 158 159 /////////////////////////// 160 // S_CVRESERVE accessors // 161 /////////////////////////// 162 163 // (No accessors) 164 165 ///////////////////////// 166 // S_OBJNAME accessors // 167 ///////////////////////// 168 169 /** Signature used to determine whether changes in precompiled types 170 defined in this module require a recompilation of users of those 171 types. This does not have much meaning given that the algorithm 172 for computing the signature is unspecified. */ getObjectCodeViewSignature()173 public int getObjectCodeViewSignature(); 174 175 /** Length prefixed name of the object file without any path 176 information prepended to the name. */ getObjectName()177 public String getObjectName(); 178 179 //////////////////////// 180 // S_ENDARG accessors // 181 //////////////////////// 182 183 // (No accessors) 184 185 ////////////////////////// 186 // S_COBOLUDT accessors // 187 ////////////////////////// 188 189 // (Elided as they are irrelevant) 190 191 ///////////////////////// 192 // S_MANYREG accessors // 193 ///////////////////////// 194 195 /** Type index of the symbol. This record is used to specify that a 196 symbol is stored in a set of registers. */ getManyRegType()197 public int getManyRegType(); 198 199 /** Count of the register enumerates that follow. */ getManyRegCount()200 public byte getManyRegCount(); 201 202 /** Get the <i>i</i>th register (0..getManyRegCount() - 1). The 203 registers are listed high order register first. */ getManyRegRegister(int i)204 public byte getManyRegRegister(int i); 205 206 /** Name of the symbol. */ getManyRegName()207 public String getManyRegName(); 208 209 //////////////////////// 210 // S_RETURN accessors // 211 //////////////////////// 212 213 /** Logical or of FUNCRET_VARARGS_LEFT_TO_RIGHT_MASK (push varargs 214 left to right if set) and FUNCRET_RETURNEE_STACK_CLEANUP_MASK 215 (returnee cleans up stack if true). */ getReturnFlags()216 public short getReturnFlags(); 217 218 /** Function return style; see constants in {@link 219 sun.jvm.hotspot.debugger.win32.coff.DebugVC50SymbolEnums}. */ getReturnStyle()220 public byte getReturnStyle(); 221 222 /** Get count of registers containing return value; only valid for 223 FUNCRET_IN_REGISTERS return style. */ getReturnRegisterCount()224 public byte getReturnRegisterCount(); 225 226 /** Get <i>i</i>th register (0..getReturnRegisterCount() - 1) 227 containing return value, high order first; only valid for 228 FUNCRET_IN_REGISTERS return style. */ getReturnRegister(int i)229 public byte getReturnRegister(int i); 230 231 /////////////////////////// 232 // S_ENTRYTHIS accessors // 233 /////////////////////////// 234 235 /** Advance this iterator to the symbol (which actually describes 236 the <b>this</b> pointer) contained within the S_ENTRYTHIS 237 symbol. */ advanceToEntryThisSymbol()238 public void advanceToEntryThisSymbol(); 239 240 /////////////////////////////////////////////////////////////////////// 241 // // 242 // // 243 // Symbols for (Intel) 16:32 Segmented and 32-bit Flat Architectures // 244 // // 245 // // 246 /////////////////////////////////////////////////////////////////////// 247 248 ///////////////////////// 249 // S_BPREL32 accessors // 250 ///////////////////////// 251 252 // This symbol specifies symbols that are allocated on the stack for 253 // a procedure. For C/C++, these include the actual parameters to a 254 // function and the local nonstatic variables of functions. 255 256 /** Signed offset relative to BP. If 0, then the symbol was assigned 257 to a register or never instantiated by the optimizer and cannot 258 be evaluated because its location is unknown. */ getBPRelOffset()259 public int getBPRelOffset(); 260 261 /** Type of the symbol. */ getBPRelType()262 public int getBPRelType(); 263 264 /** Length-prefixed name of the symbol. */ getBPRelName()265 public String getBPRelName(); 266 267 /////////////////////////////////////// 268 // S_LDATA32 and S_GDATA32 accessors // 269 /////////////////////////////////////// 270 271 // FIXME: consider documenting this as covering S_PUB32 symbols as 272 // well 273 274 // The formats of S_LDATA32 and S_GDATA32 symbols match; the only 275 // difference is the type tag. 276 // 277 // LDATA32 symbols are used for data that is not exported from a 278 // module. In C/C++, symbols that are declared static are emitted as 279 // Local Data symbols. Symbols that are emitted as Local Data cannot 280 // be moved by CVPACK into the global symbol table for the 281 // executable file. 282 // 283 // GDATA32 records have the same format as the Local Data 16:32 284 // except that the record type is S_GDATA32. For C/C++, symbols that 285 // are not specifically declared static are emitted as Global Data 286 // Symbols and can be compacted by CVPACK into the global symbol 287 // table. 288 289 /** Type index of the symbol. */ getLGDataType()290 public int getLGDataType(); 291 292 /** Offset portion of the symbol address. */ getLGDataOffset()293 public int getLGDataOffset(); 294 295 /** Segment portion of the symbol address. */ getLGDataSegment()296 public short getLGDataSegment(); 297 298 /** Length-prefixed name of symbol. */ getLGDataName()299 public String getLGDataName(); 300 301 /////////////////////// 302 // S_PUB32 accessors // 303 /////////////////////// 304 305 // FIXME: has the same format as the above; consider updating 306 // documentation. No separate accessors provided. 307 308 /////////////////////////////////////// 309 // S_LPROC32 and S_GPROC32 accessors // 310 /////////////////////////////////////// 311 312 // LPROC32 and GPROC32 symbols have the same format, differing only 313 // in the type tag. 314 // 315 // The LPROC32 symbol record defines a local (file static) procedure 316 // definition. For C/C++, functions that are declared static to a 317 // module are emitted as Local Procedure symbols. Functions not 318 // specifically declared static are emitted as Global Procedures. 319 // 320 // GPROC32 records are used for procedures that are not specifically 321 // declared static to a module. The format is the same as the Local 322 // Procedure Start 16:32 symbol. 323 324 /** Creates a new symbol iterator pointing to the symbol opening the 325 enclosing lexical scope of this function (if any); returns null 326 if there is no enclosing scope. */ getLGProcParent()327 public DebugVC50SymbolIterator getLGProcParent(); 328 329 /** Gets the absolute file offset of the parent symbol, or 0 if 330 none. This is useful for constructing and resolving types in a 331 lazy fashion. */ getLGProcParentOffset()332 public int getLGProcParentOffset(); 333 334 /** Creates a new symbol iterator pointing to the block end symbol 335 terminating the lexical scope, or NULL if there is no containing 336 lexical scope. */ getLGProcEnd()337 public DebugVC50SymbolIterator getLGProcEnd(); 338 339 /** Gets the absolute file offset of the end symbol. This is useful 340 for constructing and resolving types in a lazy fashion. */ getLGProcEndOffset()341 public int getLGProcEndOffset(); 342 343 /** Creates a new symbol iterator pointing to the next outermost 344 scope symbol in the segment (if any); returns null if this is 345 the last outermost scope for the current segment. (See the 346 documentation for more information.) */ getLGProcNext()347 public DebugVC50SymbolIterator getLGProcNext(); 348 349 /** Gets the absolute file offset of the next symbol, or 0 if none. 350 This is useful for constructing and resolving types in a lazy 351 fashion. */ getLGProcNextOffset()352 public int getLGProcNextOffset(); 353 354 /** Length in bytes of this procedure. */ getLGProcLength()355 public int getLGProcLength(); 356 357 /** Offset in bytes from the start of the procedure to the point 358 where the stack frame has been set up. Parameter and frame 359 variables can be viewed at this point. */ getLGProcDebugStart()360 public int getLGProcDebugStart(); 361 362 /** Offset in bytes from the start of the procedure to the point 363 where the procedure is ready to return and has calculated its 364 return value, if any. Frame and register variables can still be 365 viewed. */ getLGProcDebugEnd()366 public int getLGProcDebugEnd(); 367 368 /** Type of the procedure type record. */ getLGProcType()369 public int getLGProcType(); 370 371 /** Offset portion of the procedure address. */ getLGProcOffset()372 public int getLGProcOffset(); 373 374 /** Segment portion of the procedure address. */ getLGProcSegment()375 public short getLGProcSegment(); 376 377 /** Value defined by bitwise or of the the PROCFLAGS enumeration in 378 {@link 379 sun.jvm.hotspot.debugger.win32.coff.DebugVC50SymbolEnums}. */ getLGProcFlags()380 public byte getLGProcFlags(); 381 382 /** Length-prefixed name of procedure. */ getLGProcName()383 public String getLGProcName(); 384 385 ///////////////////////// 386 // S_THUNK32 accessors // 387 ///////////////////////// 388 389 // This record is used to specify any piece of code that exists 390 // outside a procedure. It is followed by an End record. The thunk 391 // record is intended for small code fragments. and a two byte 392 // length field is sufficient for its intended purpose. 393 394 /** Creates a new symbol iterator pointing to the symbol opening the 395 enclosing lexical scope of this thunk (if any); returns null if 396 there is no enclosing scope. */ getThunkParent()397 public DebugVC50SymbolIterator getThunkParent(); 398 399 /** Gets the absolute file offset of the parent symbol, or 0 if 400 none. This is useful for constructing and resolving types in a 401 lazy fashion. */ getThunkParentOffset()402 public int getThunkParentOffset(); 403 404 /** Creates a new symbol iterator pointing to the block end symbol 405 terminating the lexical scope, or NULL if there is no containing 406 lexical scope. */ getThunkEnd()407 public DebugVC50SymbolIterator getThunkEnd(); 408 409 /** Gets the absolute file offset of the end symbol. This is useful 410 for constructing and resolving types in a lazy fashion. */ getThunkEndOffset()411 public int getThunkEndOffset(); 412 413 /** Creates a new symbol iterator pointing to the next outermost 414 scope symbol in the segment (if any); returns null if this is 415 the last outermost scope for the current segment. (See the 416 documentation for more information.) */ getThunkNext()417 public DebugVC50SymbolIterator getThunkNext(); 418 419 /** Gets the absolute file offset of the next symbol, or 0 if none. 420 This is useful for constructing and resolving types in a lazy 421 fashion. */ getThunkNextOffset()422 public int getThunkNextOffset(); 423 424 /** Offset portion of the thunk address. */ getThunkOffset()425 public int getThunkOffset(); 426 427 /** Segment portion of the procedure address. */ getThunkSegment()428 public short getThunkSegment(); 429 430 /** Length in bytes of this thunk. */ getThunkLength()431 public short getThunkLength(); 432 433 /** Ordinal specifying the type of thunk; see THUNK enumeration in 434 {@link 435 sun.jvm.hotspot.debugger.win32.coff.DebugVC50SymbolEnums}. */ getThunkType()436 public byte getThunkType(); 437 438 /** Length-prefixed name of thunk. */ getThunkName()439 public String getThunkName(); 440 441 /** Delta to be added to "this" pointer; only valid if thunk type is 442 "adjustor". */ getThunkAdjustorThisDelta()443 public short getThunkAdjustorThisDelta(); 444 445 /** Length-prefixed name of target function; only valid if thunk type is 446 "adjustor". */ getThunkAdjustorTargetName()447 public String getThunkAdjustorTargetName(); 448 449 /** Displacement into the virtual table; only valid if thunk type is 450 "vcall". */ getThunkVCallDisplacement()451 public short getThunkVCallDisplacement(); 452 453 /** Offset of p-code entry point; only valid if thunk type is 454 "pcode". */ getThunkPCodeOffset()455 public int getThunkPCodeOffset(); 456 457 /** Segment of p-code entry point; only valid if thunk type is 458 "pcode". */ getThunkPCodeSegment()459 public short getThunkPCodeSegment(); 460 461 ///////////////////////// 462 // S_BLOCK32 accessors // 463 ///////////////////////// 464 465 // This symbol specifies the start of an inner block of lexically 466 // scoped symbols. The lexical scope is terminated by a matching 467 // S_END symbol. 468 469 /** Creates a new symbol iterator pointing to the symbol opening the 470 enclosing lexical scope of this scope (if any); returns null if 471 there is no enclosing scope. */ getBlockParent()472 public DebugVC50SymbolIterator getBlockParent(); 473 474 /** Gets the absolute file offset of the parent symbol, or 0 if 475 none. This is useful for constructing and resolving types in a 476 lazy fashion. */ getBlockParentOffset()477 public int getBlockParentOffset(); 478 479 /** Creates a new symbol iterator pointing to the block end symbol 480 terminating this scope. */ getBlockEnd()481 public DebugVC50SymbolIterator getBlockEnd(); 482 483 /** Gets the absolute file offset of the end symbol. This is useful 484 for constructing and resolving types in a lazy fashion. */ getBlockEndOffset()485 public int getBlockEndOffset(); 486 487 /** Length in bytes of the scope of this block. */ getBlockLength()488 public int getBlockLength(); 489 490 /** Offset portion of the segmented procedure address. */ getBlockOffset()491 public int getBlockOffset(); 492 493 /** Segment portion of the segmented procedure address. */ getBlockSegment()494 public short getBlockSegment(); 495 496 /** Length-prefixed name of the block. */ getBlockName()497 public String getBlockName(); 498 499 //////////////////////// 500 // S_WITH32 accessors // 501 //////////////////////// 502 503 // FIXME: this is a Pascal construct; ignored for now 504 505 ///////////////////////// 506 // S_LABEL32 accessors // 507 ///////////////////////// 508 509 /** Offset portion of the segmented address of the start of the 510 block. */ getLabelOffset()511 public int getLabelOffset(); 512 513 /** Segment portion of the segmented address of the start of the 514 block. */ getLabelSegment()515 public short getLabelSegment(); 516 517 /** Label flags. These are the same as the PROCFLAGS enumeration. */ getLabelFlags()518 public byte getLabelFlags(); 519 520 /** Length prefixed name of label. */ getLabelName()521 public String getLabelName(); 522 523 //////////////////////////// 524 // S_CEXMODEL32 accessors // 525 //////////////////////////// 526 527 // This record is used to notify the debugger that, starting at the 528 // given code offset and until the address specified by the next 529 // Change Execution Model record, the execution model is of the 530 // specified type. The native execution model is assumed in the 531 // absence of Change Execution Model records. 532 533 /** Offset portion of start of the block where the change occurs. */ getChangeOffset()534 public int getChangeOffset(); 535 536 /** Segment portion of start of the block where the change occurs. */ getChangeSegment()537 public short getChangeSegment(); 538 539 /** The execution model, enumerated in EXMODEL constants in {@link 540 sun.jvm.hotspot.debugger.win32.coff.DebugVC50SymbolEnums}. */ getChangeModel()541 public short getChangeModel(); 542 543 // FIXME: figure out how to deal with variant (or whether it is 544 // necessary) 545 546 //////////////////////////// 547 // S_VFTTABLE32 accessors // 548 //////////////////////////// 549 550 // This record is used to describe the base class path for the 551 // virtual function table descriptor. 552 553 /** The type index of the class at the root of the path. */ getVTableRoot()554 public int getVTableRoot(); 555 556 /** Type index of the record describing the base class path from the 557 root to the leaf class for the virtual function table. */ getVTablePath()558 public int getVTablePath(); 559 560 /** Offset portion of start of the virtual function table. */ getVTableOffset()561 public int getVTableOffset(); 562 563 /** Segment portion of the virtual function table. */ getVTableSegment()564 public short getVTableSegment(); 565 566 ////////////////////////// 567 // S_REGREL32 accessors // 568 ////////////////////////// 569 570 // This symbol specifies symbols that are allocated relative to a 571 // register. 572 573 /** Signed offset relative to register. */ getRegRelOffset()574 public int getRegRelOffset(); 575 576 /** Type of the symbol. */ getRegRelType()577 public int getRegRelType(); 578 579 /** Register enumerates on which the symbol is based. Note that the 580 register field can specify a pair of register such as ES:EBX. */ getRegRelRegister()581 public short getRegRelRegister(); 582 583 /** Length-prefixed name of the symbol. */ getRegRelName()584 public String getRegRelName(); 585 586 /////////////////////////////////////////// 587 // S_LTHREAD32 and S_GTHREAD32 accessors // 588 /////////////////////////////////////////// 589 590 // These symbols are used for data declared with the __thread 591 // storage attribute that is not exported from a module. In C/C++, 592 // __thread symbols that are declared static are emitted as Local 593 // Thread Storage 16:32 symbols. Symbols that are emitted as Local 594 // Thread Storage 16:32 cannot be moved by CVPACK into the global 595 // symbol table for the executable file. __thread symbols that are 596 // not specifically declared static are emitted as Global Thread 597 // Storage 16:32 symbols and can be compacted by CVPACK into the 598 // global symbol table. 599 600 /** Type index. */ getLThreadType()601 public int getLThreadType(); 602 603 /** Offset into thread local storage. */ getLThreadOffset()604 public int getLThreadOffset(); 605 606 /** Segment of thread local storage. */ getLThreadSegment()607 public short getLThreadSegment(); 608 609 /** Length prefixed name. */ getLThreadName()610 public String getLThreadName(); 611 612 // NOTE: accessors for all other kinds of symbols (i.e., MIPS) 613 // elided for now (FIXME) 614 } 615