dbg.gml

来自「开放源码的编译器open watcom 1.6.0版的源代码」· GML 代码 · 共 1,197 行 · 第 1/4 页

.chap Introduction
This document describes the object and executable file structures
used by the &company Debugger to provide symbolic information about a program.
This information is subject to change.
:P
Note that version 4.0 of the &company debugger supports the DWARF and 
Codeview symbolic debugging information formats in addition to the format
described in this document. For the purposes of discussion, this format
will be known as the "WATCOM" format. It is anticipated that DWARF will
become the primary format used by &company compilers and support for
generating the WATCOM format will be removed from later versions of 
the compilers.
:P.
Before reading this document you should understand the Intel 8086 Object
Module Format (OMF). This format is described in the Intel document
:CIT.
8086 Relocatable Object Module Formats
:eCIT.
and also the October 1985 issue of
:CIT.
PC Tech Journal:eCIT..
:P.
Responsibility for the Intel/Microsoft OMF specification has been taken over
by the Tools Interface Standards (TIS) Committee. The TIS standards
(including the OMF spec) may be obtained by phoning the Intel literature
center at 1-800-548-4725 and asking for order number 241597.
:P.
This document is for the &company Debugger version 4.0 (or above.)
.chap Object file structures
The compiler is responsible for placing extra information into
the object file in order to provide symbolic information for the &company Debugger. There
are three classes of information, each of which may be present or absent
from the file individually. These classes are line number, type and
local symbol information.
:P.
For the &company C compiler, line number information
is provided when the "/d1" switch is used and all three classes are provided
when the "/d2" switch is used.
.section Version number and source language identification
Since there may be different versions of the type and local symbol
information, and there may be multiple front-ends a special OMF COMENT record
is placed in the object file. It has the following form:
:XMP.
	comment_class = 0xfe
	'D'
	major_version_number (char)
	minor_version_number (char)
	source_language (string)
:eXMP.
:PC.
The :F.comment_class:eF. of 0xfe indicates a linker directive comment.
The character 'D' informs the linker that this record is providing debugging
information. The :F.major_version_number:eF. is changed whenever there
is a modification made to the types or local symbol classes that is not
upwardly compatible with previous versions. The :F.minor_version_number:eF.
increments by one whenever a change is made to those classes that is
upwardly compatible with previous versions. The :F.source_language:eF. field
is a string which determines what language that the file was compiled
from.
:P
If the debugging comment record is not present, the local and type segments
(described later) are not in WATCOM format and should be omitted from the
resulting executable file's debugging information.
The current major version is one, and the current minor version is three.
.section Line number information
Line number information is provided by standard Intel OMF LINNUM records.
A kludge has been added that allows for line numbers to refer to more
than one source file. See the section on the "Special Line Number Table"
in the executable structures portion of the document for more details.
.section Location information
A type or symbol definition may contain a location field. This field is of
variable length and identifies the memory (or register) location of the
symbol in question. A location field may consist of a single entry, or
a list of entries. Each entry describes an operation of a stack machine.
The value of the location field is the top entry of the stack after all
the operations have been performed. To tell whether a field is a single
entry or a list, the first byte is examined. If the value of the byte
is greater than 0x80, then the field consists of a list of entries, and
the length in bytes of the list is the value of the first byte minus
0x80. If the first byte is less than 0x80, the byte is the first byte
of a single entry field.
The top nibble of the first byte in each entry
is a general location class while the low nibble specifies
the sub-class.
:XMP.
BP_OFFSET   (value 0x1?)
    BYTE    (value 0x10) offset_byte
    WORD    (value 0x11) offset_word
    DWORD   (value 0x12) offset_dword

CONST	    (value 0x2?)
    ADDR286 (value 0x20) memory_location_32_pointer
    ADDR386 (value 0x21) memory_location_48_pointer
    INT_1   (value 0x22) const_byte
    INT_2   (value 0x23) const_word
    INT_4   (value 0x24) const_dword

MULTI_REG   (value 0x3?)
    Low nibble is number of register bytes that follow - 1.
    The registers are specified low order register first.

REG	    (value 0x4?)
    Low nibble is low nibble of the appropriate register value.
    This may only be used for the first 16 registers.

IND_REG     (value 0x5?)
    CALLOC_NEAR (value 0x50) register_byte
    CALLOC_FAR	(value 0x51) register_byte, register_byte
    RALLOC_NEAR (value 0x52) register_byte
    RALLOC_FAR	(value 0x53) register_byte, register_byte

OPERATOR     (value 0x6?)
    IND_2	(value 0x60)
    IND_4	(value 0x61)
    IND_ADDR286 (value 0x62)
    IND_ADDR386 (value 0x63)
    ZEB         (value 0x64)
    ZEW         (value 0x65)
    MK_FP	(value 0x66)
    POP         (value 0x67)
    XCHG	(value 0x68) stack_byte
    ADD         (value 0x69)
    DUP         (value 0x6a)
    NOP         (value 0x6b)


Here is the list of register numbers:
 0-AL,	1-AH,  2-BL,  3-BH,  4-CL,  5-CH,  6-DL,  7-DH
 8-AX,	9-BX, 10-CX, 11-DX, 12-SI, 13-DI, 14-BP, 15-SP
16-CS, 17-SS, 18-DS, 19-ES
20-ST0, 21-ST1, 22-ST2, 23-ST3, 24-ST4, 25-ST5, 26-ST6, 27-ST7
28-EAX, 29-EBX, 30-ECX, 31-EDX, 32-ESI, 33-EDI, 34-EBP, 35-ESP
36-FS,	37-GS
:eXMP.
:PC.
CONST pushes a single constant value onto the expression stack. INT_1 and
INT_2 constant values are sign-extended to four bytes before being pushed.
:P.
The OPERATOR class performs a variety of operations on the expression
stack.
:DL.
:DT.IND_2
:DD.Pick up two bytes at the location specified by the top entry of the
stack, sign-extend to four bytes and replace top of stack with the result.
:DT.IND_4
:DD.Replace the top of stack with the contents of the four bytes at the
location specified by the top of stack.
:DT.IND_ADDR286
:DD.Replace the top of stack with the contents of the four bytes, treated
as a far pointer, at the location specified by the top of stack.
:DT.IND_ADDR386
:DD.Replace the top of stack with the contents of the six bytes, treated
as a far pointer, at the location specified by the top of stack.
:DT.ZEB
:DD.Zero extend the top of stack from a byte to a dword (clear the high
three bytes).
:DT.ZEW
:DD.Zero extend the top of stack from a word to a dword.
:DT.MK_FP
:DD.Remove the top two entries from the stack, use the top of stack as
an offset and the next element as a segment to form a far pointer and
push that back onto the stack.
:DT.POP
:DD.Remove the top entry from the stack.
:DT.XCHG
:DD.Exchange the top of stack with the entry specified by :F.stack_byte:eF..
"XCHG 1" would exchange the top of stack with the next highest entry.
:DT.ADD
:DD.Remove the top two entries from the stack, add them together and push
the result.
:DT.DUP
:DD.Duplicate the value at the top of the stack.
:DT.NOP
:DD.Perform no operation.
:eDL.
:P.
REG and MULTI_REG push the 'lvalue' of the register. If they are the
only entry then the symbol exists in the specified register. To access
the value of the register, you must indirect it.
:P.
BP_OFFSET locations are for variables on the stack. The values given
are offsets from the BP register for 286 programs and from the EBP register
for 386 programs. A BP_OFFSET could also be expressed with the following
series of operations:
:XMP.
	MULTI_REG(1) SS
	IND_2 
	MULTI_REG(1) EBP
	IND_4
	MK_FP
	INT_1 offset_byte
	ADD
:eXMP.
:P.
The IND_REG location type is used for structured return values.
The register or register pair is used to point at the memory location
where the structure is returned.
CALLOC means that the calling procedure is responsible for allocating
the return area and passing a pointer to it as a parameter in the specified
registers.
RALLOC means that the called routine allocated the area and returns
a pointer to it in the given registers.
.section Typing information
The &company Debugger typing information is contained in a special segment in the
object file. The segment name is "$$TYPES" and the segment class is
"DEBTYP".
To allow greater flexibility in demand loading the typing information and
also let it exceed 60K for a single module, each object file may have
multiple $$TYPES segments. Each segment is identified by an entry in
the demand link table (described in the executable file structures section).
No individual segment may exceed 60K and no individual type record may be
split across a segment boundry. Also, any type which is described by
multiple records (structures, enums, procedures) may not be split across
a segment boundry. Since each segment is loaded as a whole by the
debugger when demand loading, increasing the segment size requires larger
amounts of contiguous memory be present in the system. Decreasing the
size of the individual segments reduces memory requirements, but increases
debugger lookup time since it has to traverse more internal structures.
The current code generator starts a new type segment when the current one
exceeds 16K.
The segments are considered to be
a stream of variable length definitions, with each definition being
preceded by a length byte.
A number of the definitions contain indices
of some form. These indices are standard Intel format, with 0 meaning no index,
1 to 127 is represented in one byte, 128 to 32767 in high byte/low byte
form with the top bit on in the high byte. Definitions are given index numbers
by the order in which they appear in the module, with the first being
index one. Character strings representing names are always placed at the
end of a definition so that their length can be calculated by subtracting
the name's start point from the length of the record. They are not
preceded by a length byte or followed by a zero byte.
:P
The first byte identifies the kind of the type definition that follows.
The top nibble of the byte is used to indicate the general class of the
type definition (there are eight of these). The low order nibble is used
to qualify the general type class and uniquely identify the definition
type.
.beglevel
.section TYPE_NAME (value 0x1?)
This definition is used to give names to types. There are three
sub-classes.
:XMP.
SCALAR    (value 0x10) scalar_type_byte, name
SCOPE     (value 0x11) name
NAME      (value 0x12) scope_index, type_index, name
CUE_TABLE (value 0x13) table_offset_dword
EOF       (value 0x14)
:eXMP.
:P.
SCALAR is used to give a name to a basic scalar type. It can also be
used to give a type index to a scalar type without a name by specifying
the null name. The :F.scalar_type_byte:eF. informs the &company Debugger what sort of
scalar item
is being given a name. It has the following form:
:XMP.
BIT: 7 6 5 4 3 2 1 0
     | |   | |	   |
     | |   | +-----+--- size in bytes - 1
     | +---+----------- class (000 - integer)
     |			      (001 - unsigned)
     |			      (010 - float)
     |			      (011 - void (size=0))
     |			      (100 - complex)
     +----------------- unused
:eXMP.
:PC.
To create an unnamed scalar type, for use in other definitions, just
use a zero length name. 
:NOTE.
BASIC would have been a better name for this, since complex is not a
scalar type, but the name was chosen before complex support was added.
:P.
SCOPE is used to restrict the scope of other type names. A restricted
scope type name must be preceded by its appropriate scope name in order
for the &company Debugger to recognize it as a type name. This is useful for declaring
C structure, union, and enum tag names. You declare SCOPE names of "struct",
"union", and "enum" and then place the appropriate value in the
:F.scope_index:eF. field of the NAME record when declaring the tag.
:P.
NAME gives an arbitrary type a name. The field, :F.scope_index:eF., is
either zero, which indicates an unrestricted type name, or is the type
index of a SCOPE definition, which means that the type name must be preceded
by the given scope name in order to be recognized.
:P.
The next two records are kludges to allow OMF line numbers to refer to
more than one source file.
See the section of on the "Special Line Number Table"
in the executable structure for more details.
:P.
CUE_TABLE is followed by :F.table_offset_dword:eF. which gives the offset
in bytes from the begining of the typing information for a module to the
special line number table. If this record is present, it must be in
the first $$TYPES segment for the module and preferably as close to
the begining of the segment as possible.
:P.
EOF marks the end of the typing information for the module and the
begining of the special line number table.
.section ARRAY (value 0x2?)
This definition is used to define an array type. There are 6 sub-classes.