dwdoc.gml

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

calculation: former second stack entry modulo the former top of the
stack.
:DT.DW_LOC_MUL
:DD.It pops the top two stack values, multiplies them together, and
pushes the result.
:DT.DW_LOC_NE
:DD.Pop two entries from stack, push 0 if they are equal; push 1 otherwise.
:DT.DW_LOC_NEG
:DD.It pops the top value and pushes its negation.
:DT.DW_LOC_NOP
:DD.A placeholder; has no side-effects.
:DT.DW_LOC_NOT
:DD.It pops the top value and pushes its logical complement.
:DT.DW_LOC_OR
:DD.It pops the top two stack entries, performs the logical OR
operation on them, and pushes the result.
:DT.DW_LOC_OVER
:DD.It duplicates the entry currently second in the stack at the top of
the stack.
:DT.DW_LOC_PLUS
:DD.It pops the top two stack entries, and pushes their sum.
:DT.DW_LOC_ROT
:DD.It rotates the first three stack entries.
The entry at the top of the stack becomes the third entry, the second
entry becomes the top, and the third entry becomes the second.
:DT.DW_LOC_SHL
:DD.It pops the top two stack entries, shifts the former second entry
left by the number of bits specified by the former top of the stack,
and pushes the result.
:DT.DW_LOC_SHR
:DD.It pops the top two stack entries, shifts the former second entry
right (logically) by the number of bits specified by the former top of
the stack, and pushes the result.
:DT.DW_LOC_SHRA
:DD.It pops the top two stack entries, shifts the former second entry
right (arithmetically) by the number of bits specified by the former
top of the stack, and pushes the result.
:DT.DW_LOC_SWAP
:DD.It swaps the top two stack entries.
:DT.DW_LOC_XDEREF
:DD.It provides an extended dereference mechanism.
The entry at the top of the stack is treated as an address.
The second stack entry is treated as an "address space identifier" for
those architectures that support multiple address spaces.
The top two stack elements are popped, a data item is retrieved through
an implementation-defined address calculation and pushed as the new
stack top.
The size of data retrieved is an addressing unit.
:DT.DW_LOC_XOR
:DD.It pops the top two stack entries, performs the logical
EXCLUSIVE-OR operation on them, and pushes the result.
:eDL.

:H2.void DWENTRY DWLocOp( dw_client cli, dw_loc_id loc, dw_optype op, ... );
:p.Performs one of the following operations:
:DL tsize=24 break.
:DTHD.Operation
:DDHD.Description
:DT.DW_LOC_BRA
:DD.It is followed by a dw_loc_label operand.
This operation pops the top stack entry, if the value is not zero, then
jump to the label.
:DT.DW_LOC_BREG
:DD.Followed by two operands, the first is a register, and the second
is an dw_sconst to add to the value in the register.  The result is pushed
onto the stack.
:DT.DW_LOC_FBREG
:DD.Takes one dw_sconst parameter which is added to the value calculated
by the frame_base_loc parameter to the current subroutine, then pushed
on the stack.
:DT.DW_LOC_PICK
:DD.It is followed by a uint operand which is an index.
The stack entry with the specified index (0 through 255, inclusive; 0
means the top) is pushed on the stack.
:DT.DW_LOC_PLUS_UCONST
:DD.It is followed an dw_sconst operand.
It pops the top stack entry, adds it to the operand and pushes the
result.
:DT.DW_LOC_SKIP
:DD.It is followed by a dw_loc_label operand.  Control is transferred
immediately to this label.
:eDL.

:H2.dw_loc_handle DWENTRY DWLocFini( dw_client cli, dw_loc_id loc );
:P.Ends the location expression for a symbol, and returns a handle that
may be passed to other DW routines.

:H2.dw_list_id DWENTRY DWListInit( dw_client cli );
:P.First function called to create a location list for a symbol.

:H2.void DWENTRY DWListEntry( dw_client cli, dw_list_id id, dw_sym_handle beg, dw_sym_handle end, dw_loc_handle loc );
:P.Define an entry in the location list.
:DL.
:DTHD.Parameter
:DDHD.Description
:DT.beg
:DD.A beginning address.
This address is relative to the base address of the compilation unit
referencing this location list.
It marks the beginning of the range over which the location is valid.
:DT.end
:DD.A ending address.
This address is relative to the base address of the compilation unit
referencing this location list.
It marks the first address past the end of the range over which the
location is valid.
Overlapping ranges are possible and are interpreted to mean that the
value may be found in one of many places during the overlap.
A CLIReloc for
:hp2.DW_W_LABEL:ehp2. will be made for each dw_sym_handle.
:DT.loc
:DD.A location expression describing the location of the object over
the range specified by the beginning and end addresses.
:eDL.

:H2.dw_loc_handle DWENTRY DWListFini( dw_client cli, dw_list_id );
:P.Finishes the creation of the location list.

:H2.void DWENTRY DWLocTrash( dw_client cli, dw_loc_handle loc );
:P.Frees the memory associated with the location expression or list loc.
A location expression/list can be created and
used over and over again until it is
freed by calling this function.

:H0.Typing Information
:p.Unless otherwise noted, calls to these functions emit debugging
information immediately.  The DWARF format requires that debugging
information appear in the same order as it does in the source code.
So, for example, a structure's fields must be created in the same
order that they appear in the source program.
:P.Some of the following functions have common parameters.  Here is the
documentation for these common parameters:
:DL.
:DTHD.Parameter
:DDHD.Description
:DT.char *name
:DD.A null-terminated type name.  i.e., "struct foobar {}" has the name
foobar.  If this parm is NULL then no name is emitted.
:DT.dw_addr_offset start_scope
:DD.This is the offset from the low_pc value for the enclosing block that
the declaration occurs at.  This is most commonly 0.
:DT.uint flags
:DD.Some routines have additional flags available here; but unless otherwise
noted, the following are always available:
:DL.
:DTHD.Flag
:DDHD.Description
:DT.DW_DECLARATION
:DD.The object is a declaration, not a definition
:DT.DW_FLAG_PRIVATE
:DD.The object has the C++ private attribute.
:DT.DW_FLAG_PROTECTED
:DD.The object has the C++ protected attribute.
:DT.DW_FLAG_PUBLIC
:DD.The object has the C++ public attribute.
:EDL.
:EDL.

:H2.dw_handle DWENTRY DWFundamental( dw_client cli, char * name, unsigned fund_idx, unsigned size );
:p.Get a handle for a fundamental type.  fund_idx is one of the following:
:sl.
:LI.DW_FT_ADDRESS
:LI.DW_FT_BOOLEAN
:LI.DW_FT_COMPLEX_FLOAT
:LI.DW_FT_FLOAT
:LI.DW_FT_SIGNED
:LI.DW_FT_SIGNED_CHAR
:LI.DW_FT_UNSIGNED
:LI.DW_FT_UNSIGNED_CHAR
:esl.
:P.For convenience, DW_FT_MIN, and DW_FT_MAX are defined.  A valid
fundamental type is in the range DW_FT_MIN <= ft < DW_FT_MAX.  The DW
library will always return the same handle when called with the same
fundamental type (so the client does not need to save fundamental
type handles).
:DL.
:DTHD.Parameters
:DDHD.Description
:DT.name
:DD.The name of the type being defined.
:DT.size
:DD.The size in bytes of the type being defined.
:eDL.

:H2.dw_handle DWENTRY DWModifier( dw_client cli, dw_handle base_type, uint modifiers );
:P.Specifies a modifier to a type.
:HP2.base_type:eHP2. is the base type to be modified with the modifier
:HP2.modifier:eHP2..
The available modifiers are:
:DL tsize=20.
:DTHD.Modifier Constant
:DDHD.Description
:DT.DW_MOD_CONSTANT
:DD.The object is a constant
:DT.DW_MOD_VOLATILE
:DD.The object is volatile.
:DT.DW_MOD_NEAR
:DD.The object is a near object.
:DT.DW_MOD_FAR
:DD.The object is a far object.
:DT.DW_MOD_HUGE
:DD.The object is a huge object.
:DT.DW_MOD_FAR16
:DD.The object is a far16 object.
:eDL.

:H2.dw_handle DWENTRY DWTypedef( dw_client cli, dw_handle base_type, const char *name, dw_addr_offset start_scope, uint flags );
:P.This function gives a name to a type.  The :hp2.name:ehp2. must not be NULL.
The flag value :hp2.DW_FLAG_DECLARATION:ehp2. is not allowed.

:H2.dw_handle DWENTRY DWPointer( dw_client cli, dw_handle base_type, uint flags );
:P.Declares a pointer type.
:DL.
:DTHD.Parameter
:DDHD.Description
:DT.base_type
:DD.The pointed-at type.
:DT.flags
:DD.Only the following flags are available:
:DL.
:DTHD.Flags
:DDHD.Description
:DT.DW_FLAG_REFERENCE
:DD.Declare a pointer that is dereferenced automatically.
:DT.DW_PTR_TYPE_NORMAL
:dd.A normal pointer (i.e. a model dependant pointer).
:DT.DW_PTR_TYPE_NEAR16
:dd.A near 16-bit pointer.
:DT.DW_PTR_TYPE_FAR16
:dd.A far 16-bit pointer.
:DT.DW_PTR_TYPE_HUGE
:dd.A huge 16-bit pointer.
:DT.DW_PTR_TYPE_NEAR32
:dd.A near 32-bit pointer.
:DT.DW_PTR_TYPE_FAR32
:dd.A far 32-bit pointer.
:eDL.
:eDL.

:H2.dw_handle DWENTRY DWString( dw_client cli, dw_loc_handle string_length, dw_size_t byte_size, const char *name, dw_addr_offset start_scope, uint flags );
:P.Declares a type to be a block of characters.
:DL.
:DTHD.Parameter
:DDHD.Description
:DT.string_length
:DD.If this parameter is non-NULL then it is a location expression that
the debugger executes to get the address where the length of the string
is stored in the program.  In this case the :hp2.byte_size:ehp2.
parameter describes the number of bytes to be retrieved at the location
calculated.  If :hp2.byte_size:ehp2. is 0, then the debugger will
use :hp2.sizeof( long ):ehp2..
:DT.byte_size
:DD.If :hp2.string_length:ehp2. is NULL then this parameter is the number
of bytes in the string.  Otherwise see :hp2.string_length:ehp2..
:eDL.

:H2.dw_handle DWENTRY DWMemberPointer( dw_client cli, dw_handle containing_struct, dw_loc_handle use_location, dw_handle base_type, const char *name, unsigned flags );
:P.Declares a C++ pointer type to a data or function member of a class
or structure.
:DL.
:DTHD.Parameter
:DDHD.Description
:DT.containing_struct
:DD.A handle to the class or struct to whose members objects of this type
may point.
:DT.use_location
:DD.This refers to the location expression which describes how to get
to the member it points to from the beginning of the entire class.
It expects the base address of the structure/class object to be on the
stack before the debugger starts to execute the location description.
:DT.base_type
:DD.The type of the member to which this object may point to.
:eDL.

:H1.Array Types

:H2.dw_handle DWENTRY DWBeginArray( dw_client cli, dw_handle elt_type, uint stride_size, const char *name, dw_addr_offset scope, uint flags );
:P.Begin the declaration of an array. This function call must be followed by
calls to :hp2.DWArrayDimension:ehp2. and :hp2.DWEndArray:ehp2..
:DL.
:DTHD.Parameter
:DDHD.Description
:DT.elt_type
:DD.Handle for the type of the elements of this array.
:DT.stride_size
:DD.If this value is non-zero then it indicates the number of bits of
each element of the array.  (Useful if the number of bits used to store
an element in the array is different from the number of bits used to
store an individual element of type :hp2.elt_type:ehp2..);
:eDL.

:H2.void DWENTRY DWArrayDimension( dw_client cli, const dw_dim_info *info );
:P.Add a dimension to the previously started array.  This function must
be called for each dimension in the order that the dimensions appear in
the source program.  :hp2.info:ehp2. points to an instance of the following
structure:
:XMP.
:SF font=4.
typedef struct {
    dw_handle	index_type;
    dw_uconst	lo_data;
    dw_uconst	hi_data;
} dw_dim_info;
:eSF.
:eXMP.
:DL.
:DTHD.Field
:DDHD.Description
:DT.hi_bound_fmt
:DD.This is similar to :hp2.lo_bound_fmt:ehp2. but describes the
high bound of this dimension.
:DT.index_type
:DD.This is the handle of the type of the indicies for this dimension.
:DT.lo_data
:DD.The low bound of the array.
:DT.hi_data
:DD.The upper bound of the array.
:eDL.

:H2.void DWENTRY DWEndArray( dw_client cli, dw_handle array_hdl, dw_handle elt_type, uint stride_size, const char *name, dw_addr_offset scope, uint flags );
:P.This finishes the writing of the record to describe the array
A sufficient number of calls to :hp2.DWArrayDimension:ehp2. must have been
made before :hp2.DWEndArray:ehp2. is called.

:H1.Structure Types

:H2.dw_handle DWENTRY DWStruct( dw_client cli, uint kind );
:P.Create a handle for a structure type that will be defined later.
This handle can be used for other DW routines even before
:hp2.DWBeginStruct:ehp2. has been called.
:DL.
:DTHD.Kind
:DDHD.Description
:DT.DW_ST_CLASS
:DD.A C++ class type.
:DT.DW_ST_STRUCT
:DD.A structure type.
:DT.DW_ST_UNION
:DD.A union type.
:eDL.

:h2.void DWENTRY DWBeginStruct( dw_client cli, dw_handle struct_hdl, dw_size_t size, const char *name, dw_addr_offset scope, uint flags );
:p.Begin the declaration of the structure reserved by a call to
:hp2.DWStruct:ehp2..  This function begins a nesting of the debugging
information.  Subsequent calls, up to the corresponding
:hp2.DWEndStruct:ehp2. call, to the DW library become children
of this structure. i.e., this function marks the beginning of the
scope of the structure definition.
:dl.
:dthd.Parameter
:ddhd.Description
:dt.struct_hdl
:dd.A dw_handle returned by a call to :hp2.DWStruct:ehp2..
:dt.size
:dd.If this is non-zero it indicates the number of bytes required to
hold an element of this structure including any padding bytes.
:edl.

:h2.void DWENTRY DWAddFriend( dw_client cli, dw_handle friend );
:p.Add :hp2.friend:ehp2. as a friend to the current structure.

:h2.dw_handle DWENTRY DWAddInheritance( dw_client cli, dw_handle ancestor, dw_loc_handle loc, uint flags );
:p.Indicate the the current structure inherits from another structure.
:dl.
:dthd.Parameter
:ddhd.Description
:dt.ancestor
:dd.The handle of the ancestor to be inherited.
:dt.loc
:dd.A location expression that describes the location of the beginning
of the data members contributed to the entire class by the ancestor
relative to the beginning of the address of the data members of the
entire class.
:dt.flags
:dd.In addition to the common values of :hp2.flags:ehp2., the flag
:hp2.DW_FLAG_VIRTUAL:ehp2. may be supplied to indicate that the
inheritance serves as a virtual base class.
As well, the flag :hp2.DW_FLAG_DECLARATION:ehp2. is not allowed here.