dbg.gml

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

:XMP.
BYTE_INDEX     (value 0x20) high_bound_byte, base_type_index
WORD_INDEX     (value 0x21) high_bound_word, base_type_index
LONG_INDEX     (value 0x22) high_bound_dword, base_type_index
TYPE_INDEX     (value 0x23) index_type_index, base_type_index
DESC_INDEX     (value 0x24) scalar_type_byte, scalar_type_byte,
				bounds_32_pointer, base_type_index
DESC_INDEX_386 (value 0x25) scalar_type_byte, scalar_type_byte,
				bounds_48_pointer, base_type_index
:eXMP.
:P.
BYTE_INDEX, WORD_INDEX, LONG_INDEX are all used to describe a restricted
form of array. If one of these forms is used then the index type is an
integer with the low bound of the array being zero and the high
bound being whatever is specified.
:P.
The DESC_INDEX form is used when the array bounds are not known at
compile time. The :F.bounds_32_pointer:eF. is a far pointer to a structure
in memory. The type and size of the first field is given by the first
:F.scalar_type_byte:eF. and indicates the lower bound for the index. The
second field's type and size is given by the second :F.scalar_type_byte:eF. .
This field gives the number of elements in the array.
:P.
The DESC_INDEX_386 is the same as DESC_INDEX except that a 48-bit far pointer
is used to locate the structure in memory.
.section SUBRANGE (value 0x3?)
This definition is used to define a subrange type. There are 3
sub-classes.
:XMP.
BYTE_RANGE (value 0x30) lo_bnd_byte, hi_bnd_byte, base_type_index
WORD_RANGE (value 0x31) lo_bnd_word, hi_bnd_word, base_type_index
LONG_RANGE (value 0x32) lo_bnd_dword, hi_bnd_dword, base_type_index
:eXMP.
:P.
If the base type is unsigned then the low and high bounds should be
interpreted as containing unsigned quantities, otherwise they contain
integers. However, the decision to use the byte, word, or long form of
the definition is always made considering the high and low bounds as
signed numbers.
.section POINTER (value 0x4?)
This definition is used to define a pointer type. There are 10
sub-classes.
:XMP.
NEAR		(value 0x40) base_type_index [,base_locator]
FAR		(value 0x41) base_type_index
HUGE		(value 0x42) base_type_index
NEAR_DEREF	(value 0x43) base_type_index [,base_locator]
FAR_DEREF	(value 0x44) base_type_index
HUGE_DEREF	(value 0x45) base_type_index
NEAR386 	(value 0x46) base_type_index [,base_locator]
FAR386		(value 0x47) base_type_index
NEAR386_DEFREF	(value 0x48) base_type_index [,base_locator]
FAR386_DEREF	(value 0x49) base_type_index
:eXMP.
:P.
When a symbol is one of the *_DEREF types, the &company Debugger will automatically
dereference the pointer. This "hidden" indirection may be used to define
reference parameter types, or other indirectly located symbols. The *_DEREF
types have now been superceeded by location expressions. They should no
longer be generated. The NEAR* pointer types all have an optional
:F.base_locator:eF. field. The debugger can tell if this field is present
by examining the length of the debug type entry at the begining of the
record and seeing if there are additional bytes after the
:F.base_type_index:eF. field. If there are more bytes, the
:F.base_locator:eF. is a location expression whose result is an address,
the value of which is the base selector and offset value
when indirecting through the pointer (based pointers). The contents of
the based pointer variable are added to result of the location expression
to form the true resulting address after an indirection.
The address of the pointer variable being indirected through is pushed
on the stack before the location expression is evaluated (needed for
self-based pointers).
If the :F.base_locator:eF. field is not present, the debugger will use
the default near segment and a zero offset.

.section ENUMERATED (value 0x5?)
This definition is used to define an enumerated type. There are 4
sub-classes.
:XMP.
LIST	   (value 0x50) #consts_word, scalar_type_byte
CONST_BYTE (value 0x51) value_byte, name
CONST_WORD (value 0x52) value_word, name
CONST_LONG (value 0x53) value_dword, name
:eXMP.
:P.
LIST is used to inform the &company Debugger of the number of constants in the enumerated
type and the scalar type used to store them in memory. It will be
followed immediately by all the constant definitions for the enumerated
type. See TYPE_NAME for a description of the :F.scalar_type_byte:eF..
:P.
CONST_BYTE, CONST_WORD, and CONST_LONG define the individual constant
values for an enumerated type. The type of the constant is provided by
the preceeding LIST definition. The decision to use the byte, word, or
long form of the definition is made always by considering the value as
a signed number. The CONST_* definition records are not counted when
determining type index values.
:P.
The LIST record and its associated CONST_* records must all be contained
in the same $$TYPES segment.
.section STRUCTURE (value 0x6?)
This definition is used to define a structure type. There are 10
sub-classes.
:XMP.
LIST	   (value 0x60) #fields_word [,size_dword]
FIELD_BYTE (value 0x61) offset_byte, type_index, name
FIELD_WORD (value 0x62) offset_word, type_index, name
FIELD_LONG (value 0x63) offset_dword, type_index, name
BIT_BYTE   (value 0x64) offset_byte, start_bit_byte, bit_size_byte,
			type_index, name
BIT_WORD   (value 0x65) offset_word, start_bit_byte, bit_size_byte,
			type_index, name
BIT_LONG   (value 0x66) offset_dword, start_bit_byte, bit_size_byte,
			type_index, name
FIELD_CLASS (v    0x67) attrib_byte, field_locator, type_index, name
BIT_CLASS  (value 0x68) attrib_byte, field_locator, start_bit_byte,
			bit_size_byte, type_index, name
INHERIT_CLASS (v  0x69) adjust_locator, ancestor_type_index
:eXMP.
:P.
LIST is used to introduce a structure definition. It is followed
immediately by all the field definitions that make up the structure.
The optional :F.size_dword:eF. gives the size of the structure in bytes.
If it is not present, the debugger calculates the size of the structure
based on field offsets and sizes.
:P.
FIELD_BYTE, FIELD_WORD, FIELD_LONG, and FIELD_CLASS define a single field
entry in a structure defintion.
:P.
BIT_BYTE, BIT_WORD, BIT_LONG, and BIT_CLASS define a bit field in a structure.
:The FIELD_CLASS and BIT_CLASS records are used for defining fields in a
C++ class. The :F.attrib_byte:eF. contain a set of bits describing attributes
of the field:
:XMP.
BIT: 7 6 5 4 3 2 1 0
     |     | | | | |
     |     | | | | +--- internal
     |	   | | | +----- public
     |	   | | +------- protected
     |	   | +--------- private
     +-----+----------- unused
:eXMP.
:PC.
An internal field is one that is generated for compiler support. It is
not normally displayed to the user. The other bits have their usual C++
meanings.
:P.
The :F.field_locator:eF. is a location expression describing how to
calculate the field address. Before begining to evaluate the expression,
the debugger will implicitly push the base address of the class instance
onto the stack. The following is an example of the location expression used
to calculate an ordinary field at offset 10 from the start of the class:
:XMP.
	INT_1	10
	ADD
:eXMP.
:P.
The INHERIT_CLASS record indicates that a particular class should inherit
all the fields specified by :F.ancestor_type_index:eF.. This field must
point at either a STRUCTURE LIST record or a TYPE NAME that eventually
resolves to a STRUCTURE LIST. The :F.adjust_locator:eF. is a location
expression that tells the debugger how to adjust the field offset expressions
in the inherited class to their proper values for a class of this instance.
:P.
The FIELD_*, BIT_*, and INHERIT_CLASS records are not counted when
determining type index values.
:P.
A C union, or Pascal variant record is described by having a number of fields
all beginning at the same offset. The &company Debugger will display the fields in the
reverse order that the records define them. This means that ordinarily,
the records should be sorted by descending offsets and bit positions.
:P.
The LIST record and it's associated field descriptions must all be contained
in the same $$TYPES segment.
.section PROCEDURE (value 0x7?)
This definition is used to define a procedure type. There are 4
sub-classes.
:XMP.
NEAR	  (value 0x70) ret_type_index, #parms_byte {,parm_type_index}
FAR	  (value 0x71) ret_type_index, #parms_byte {,parm_type_index}
NEAR386   (value 0x72) ret_type_index, #parms_byte {,parm_type_index}
FAR386	  (value 0x73) ret_type_index, #parms_byte {,parm_type_index}
EXT_PARMS (value 0x74) {,parm_type_index}
:eXMP.
:P.
The EXT_PARMS sub-class is used when there are too many parameter
types to fit into one PROCEDURE record. This condition can be recognized
when the #parms_byte indicates there are more parameter types than
fit into the record according to the length field at the beginning.
In this case the remaining parameter types are continued in the record
immediately following, which will always be of type EXT_PARMS. The EXT_PARMS
record must be contained in the same $$TYPES segment as the preceeding
procedure record.
.section CHARACTER_BLOCK (value 0x8?)
Items of type CHARACTER_BLOCK are length delimited strings. There are 4
sub-classes.
:XMP.
CHAR_BYTE    (value 0x80) length_byte
CHAR_WORD    (value 0x81) length_word
CHAR_LONG    (value 0x82) length_dword
CHAR_IND     (value 0x83) scalar_type_byte, length_32_pointer
CHAR_IND_386 (value 0x84) scalar_type_byte, length_48_pointer
CHAR_IND_LOC (value 0x85) scalar_type_byte, address_locator
:eXMP.
:PC.
The CHAR_BYTE, CHAR_WORD, and CHAR_LONG forms are used when the length
of the character string is known at compile time. Even though the length
given is an unsigned quantity, the decision on which form to use is made
by considering the value to be signed. The CHAR_IND form is used when the
length of the string is determined at run time. The :F.length_32_pointer:eF.
gives the far address of a location containing the length of the string. The
size of this location is given by the :F.scalar_type_byte:eF.. The
CHAR_IND_386 form is the same as CHAR_IND except that the location of the length
is given by a 48-bit far pointer.
The CHAR_IND_LOC form is the same as CHAR_IND except that the address of
the length is given by a location expression.
.endlevel
.section Local symbol information
The &company Debugger local symbol information is contained in a special segment in the
object file. The segment name is "$$SYMBOLS" and the segment class is
"DEBSYM".
The segment is 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.
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 symbol definition that follows.
The top nibble of the byte is used to indicate the general class of the
symbol definition. The low order nibble is used
to qualify the general definition class.
:P.
Symbol definitions are used to provide the &company Debugger with the location and
scoping of source language local symbols. There are two general classes
of symbol definition, one for variables and one for code.
.beglevel
.section VARIABLE (value 0x1?)
This definition is used to define the location of a data symbol.
There are 4 sub-classes.
:XMP.
MODULE	  (value 0x10) memory_location_32_pointer, type_index, name
LOCAL	  (value 0x11) address_locator, type_index, name
MODULE386 (value 0x12) memory_location_48_pointer, type_index, name
MODULE_LOC (v    0x13) address_locator, type_index, name
:eXMP.
:P.
MODULE defines either an exported, domestic, or imported
variable in the module.
It is not necessary to generate symbol information for an imported variable
since the &company Debugger will look for local symbol information in the module which defines
the variable if required.
:P.
LOCAL defines a symbol that is local to a code block or procedure. The
defining block is the first one previous to this definition. Local symbols
only "exist" for the purpose of the &company Debugger lookups when the program is
executing in a block which defines the symbol.
.section CODE (value 0x2?)
This definition is used to define an object in the code. There are 6
sub-classes.
:XMP.
BLOCK	     (value 0x20) start_offset_word, size_word,
			    parent_block_offset
NEAR_RTN     (value 0x21) <BLOCK>, pro_size_byte, epi_size_byte,
			    ret_addr_offset_word, type_index,
			    return_val_loc, #parms_byte
			    {,parm_location}, name
FAR_RTN      (value 0x22) <BLOCK>, pro_size_byte, epi_size_byte,
			    ret_addr_offset_word, type_index,
			    return_val_loc, #parms_byte
			    {,parm_location}, name
BLOCK_386    (value 0x23) start_offset_dword, size_dword,
			    parent_block_offset
NEAR_RTN_386 (value 0x24) <BLOCK_386>, pro_size_byte, epi_size_byte,
			    ret_addr_offset_dword, type_index,
			    return_val_loc, #parms_byte
			    {,parm_location}, name
FAR_RTN_386  (value 0x25) <BLOCK_386>, pro_size_byte, epi_size_byte,
			    ret_addr_offset_dword, type_index,
			    return_val_loc, #parms_byte
			    {,parm_location}, name
MEMBER_SCOPE (value 0x26) parent_block_offset, class_type_index
			    [obj_ptr_type_byte, object_loc]
:eXMP.
:P.
BLOCK is used to indicate a block of code that contains local symbol
definitions. The field :F.parent_block_offset:eF. is used to tell the &company Debugger
the next
block to search for a symbol definition if it is not found in this block.
The field is set to zero if there is no parent block.
:P
NEAR_RTN and FAR_RTN are used to specify a routine definition.
Notice that the first part
is identical to a code block definition. The :F.ret_addr_offset_word:eF.
is the
offset from BP (or EBP) that the return address is located on the stack. The
:F.#parms_byte:eF. and :F.parm_location:eF.'s following are only