dwdoc.gml

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

:edl.

:h2.dw_handle DWENTRY DWAddField( dw_client cli, dw_handle field_hdl, dw_loc_handle loc, const char *name, uint flags );
:p.Add a data member to a structure.
:dl.
:dthd.Parameter
:ddhd.Description
:dt.field_hdl
:dd.The dw_handle of the type of this field.
:dt.loc
:dd.A location expression which expects the base address of the structure
to be pushed on the stack and calculates the base address of this field.
If the structure is a union type, then this parameter may be NULL.  If
this is a static data member of a class then this parameter may be NULL
if the actual definition of the parameter is outside the class.
:dt.flags
:dd.The additional flag :hp2.DW_FLAG_STATIC:ehp2. may be used to indicate
a static structure member.
:edl.

:h2.dw_handle DWENTRY DWAddBitField( dw_client cli, dw_handle field_hdl, dw_loc_handle loc, dw_size_t byte_size, uint bit_offset, uint bit_size, const char *name, uint flags );
:p.Add a bitfield member to a structure.
:dl.
:dthd.Parameter
:ddhd.Description
:dt.field_hdl
:dd.the dw_handle of the type of this field.
:dt.loc
:dd.A location expression which expects the base address of the structure
most closely containing the bit field to be pushed and the stack, and
which calculates the base address of this field.
:dt.byte_size
:dd.This field must be the non-zero byte size of the unit of storage
containing the bit-field.  This is required only if the storage
required cannot be determined by the type of the bit-field (i.e.,
padding bytes).  If the size can be determined by the type of the
bit-field, then this value may be 0.
:dt.bit_offset
:dd.The number of bits to the left of the leftmost (most significant);
bit of the bit field value.
:dt.bit_size
:dd.The number of bits occupied by this bit-field value.
:edl.

:H2.void DWENTRY DWEndStruct( dw_client cli );
:p.End the current structure.  Client must ensure proper Begin/End
matching.

:H1.Enumeration Types

:H2.dw_handle DWENTRY DWBeginEnumeration( dw_client cli, dw_size_t byte_size, const char *name, dw_addr_offset scope, uint flags );
:P.Begin the definition of an enumerated type.	:hp2.byte_size:ehp2. is
the number of bytes required to hold an instance of this enumeration.
This call must be followed by calls to :hp2.DWAddConstant:ehp2. and
:hp2.DWEndEnumeration:ehp2..  No other DW calls may be made before
the call to :hp2.DWEndEnumeration:ehp2..  The DWARF standard requires
that the constants be defined in :hp1.reverse:ehp1. order to which they
appear in the source program.

:h2.void DWENTRY DWAddConstant( dw_client cli, dw_uconst value, const char *name );
:p.Add the constant :hp2.value:ehp2. (that is :hp2.byte_size:ehp2. bytes
large as determined by the parameter to :hp2.DWBeginEnumeration:ehp2.);
with the name :hp2.name:ehp2. to the current enumeration.

:h2.void DWENTRY DWEndEnumeration( dw_client cli );
:p.Finish the current enumeration.


:h1.Subroutine Type Declarations
:p.These function calls deal with declarations of subroutines.	That is,
their prototypes, or for use in creating function pointers.
:h2.dw_handle DWENTRY DWBeginSubroutineType( dw_client cli, dw_handle return_type, const char *name, dw_addr_offset scope, uint flags );
:p.Begin the nested declaration of the subroutine type.  All calls
to the DW library after this, until :hp2.DWEndSubroutineType:ehp2.
are in the scope of the declaration of the subroutine type.  (i.e.,
if it's a prototyped C function, then declarations before
:hp2.DWEndSubroutineType:ehp2. are similar to declarations
inside the prototype.)	Parameters for this type are declared using
the entries :hp2.DWAddParmToSubroutineType:ehp2. and
:hp2.DWAddEllipsisToSubroutineType:ehp2..
:dl.
:dthd.Parameter
:ddhd.Description
:dt.return_type
:dd.If the function is void, this parameter must be NULL.  Otherwise
it is a handle for the return type of the subroutine.
:dt.flags
:dd.In addition to the standard flags, :hp2.DW_FLAG_PROTOTYPED:ehp2.
indicates that the declaration of the subroutine type was prototyped
in the source code.  As well, the "address class" set of flags used in
:hp2.DWPointer:ehp2. are also allowed here (e.g. :hp2.DW_TYPE_FAR16:ehp2. etc.)
:edl.

:h2.void DWENTRY DWEndSubroutineType( dw_client cli );
:p.The client must ensure that proper Begin/End matching is done.

:h1.Lexical Blocks
:h2.dw_handle DWENTRY DWBeginLexicalBlock( dw_client cli, dw_loc_handle segment, const char *name );
:p.Begin a new lexical scope.  :hp2.name:ehp2. may be NULL indicating
an un-named scope.  Two CLIReloc calls will made, one for
:hp2.DW_W_LOW_PC:ehp2. and one for :hp2.DW_W_HIGH_PC:ehp2. which
indicate the first byte of the scope, and the first byte beyond the end
of the scope.  :hp2.segment:ehp2. if non-null is an expression that
evaluates to the segment this block is in.

:h2.void DWENTRY DWEndLexicalBlock( dw_client cli );
:p.End a lexical scope.  As usual, the client must ensure that
Begin/End pairs match.

:h1.Common Blocks
:h2.dw_handle DWENTRY DWBeginCommonBlock( dw_client cli, dw_loc_handle loc, dw_loc_handle segment, const char *name, unsigned flag );
:p.Begin the declarations for the common block named :hp2.name:ehp2. and
located at :hp2.loc:ehp2..  :hp2.segment:ehp2. if non-null indicates which
segment the common block is in.  The only flag that is valid for the
:hp2.flag:ehp2. parameter is :hp2.DW_FLAG_DECLARATION:ehp2..

:h2.void DWENTRY DWEndCommonBlock( dw_client cli );
:p.End of declarations for the common block.

:h2.dw_handle DWENTRY DWIncludeCommonBlock( dw_client cli, dw_handle common_block );
:p.Used in the subroutine scope that references the common block.

:h1.Subroutines
:h2.dw_handle DWENTRY DWBeginInlineSubroutine( dw_client cli, dw_handle out_of_line, dw_loc_handle ret_addr, dw_loc_handle segment );
:p.Begin a definition of a particular instance of an inlined
subroutine.  :hp2.out_of_line:ehp2. is a handle to the "out of line"
instance of the subroutine (i.e., a handle from a :hp2.DWBeginSubroutine:ehp2.
call that had the DW_FLAG_OUT_OF_LINE flag).  Each instance of the
inlined subroutine must have it's own copies of entries describing
parameters to that subroutine and it's local variables.
:hp2.ret_addr:ehp2. gives the location of the return address (if any).
:hp2.segment:ehp2. if non-null indicates which segment the expansion
occurs in.

:h2.dw_handle DWENTRY DWBeginSubroutine( dw_client cli, dw_call_type call_type, dw_handle return_type, dw_loc_handle return_addr_loc, dw_loc_handle frame_base_loc, dw_loc_handle structure_loc, dw_handle member_hdl, dw_loc_handle segment, const char *name, dw_addr_offset start_scope, uint flags );
:p.Begin a declaration/definition of a subroutine or entry point.
This begins a nesting of the debugging information, and must be
followed by calls to :hp2.DWFormalParameter:ehp2. et al to declare
the parameters, types, and variables for this subroutine.  Unless
:hp2.DW_FLAG_DECLARATION:ehp2. is set, this will require a
:hp2.DW_W_LOW_PC:ehp2. and/or a :hp2.DW_W_HIGH_PC:ehp2..
:dl.
:dthd.Parameter
:ddhd.Description
:dt.call_type
:dd.Not currently used, but should be one of:
:sl.
:li.DW_SB_NEAR_CALL
:li.DW_SB_FAR_CALL
:li.DW_SB_FAR16_CALL
:esl.
:dt.return_type
:dd.Handle for the return type.  Must be NULL for void-type subroutines.
:dt.return_addr_loc
:dd.If non-NULL then this is a location expression that calculates the
address of memory that stores the return address.
:dt.frame_base_loc
:dd.If non-NULL then this is a location expression that describes the
"frame base" for the subroutine or entry point.  (If the frame base
changes during the subroutine, it might be desirable
for local variables to be calculated from the frame base, and then
use a location list for the frame base.);
:dt.structure_loc
:dd.For member functions of structure types, this calculates the
address of the slot for the function within the virtual function table
for the enclosing class or structure.
:dt.member_hdl
:dd.If this is a definition of a member function occuring outside the body
of the structure type, then this is the handle for the type definition
of the structure.
:dt.segment
:dd.If non-null then this is a location expression that evaluates to the
segment for this subprogram.
:edl.
:p.The following additional flags are available:
:dl.
:dt.flag
:dd.description
:dt.DW_FLAG_PROTOTYPED
:dd.The function was declared with ANSI-C style prototyping, as opposed
to K&R-C style parameter lists.
:dt.DW_FLAG_ARTIFICIAL
:dd.The function was created by the compiler (i.e. not explicitly declared in
any of the user's source files)
:dt.DW_FLAG_VIRTUAL
:dd.This is a virtual subroutine.
:dt.DW_FLAG_PURE_VIRTUAL
:dd.This is a pure virtual subroutine.
:dt.DW_FLAG_MAIN
:dd.For Fortran PROGRAM-type subroutines.
:dt.DW_SUB_STATIC
:dd.A file static subroutine or function.  Also used for a static
member function, and for nested subroutine declarations.
:dt.DW_SUB_ENTRY
:dd.A FORTRAN Entry point.  DW requires only a DW_W_LOW_PC for this
type of function.
:dt.DW_FLAG_WAS_INLINED
:dd.The function was generated inline by the compiler.
:dt.DW_FLAG_DECLARED_INLINED
:dd.The function was declared inline by the user.
:edl.

:h2.void DWENTRY DWEndSubroutine( dw_client cli );
:p.End the current nesting of :hp2.DWBeginSubroutine:ehp2. or
:hp2.DWBeginInlineSubroutine:ehp2..

:h2.dw_handle DWENTRY DWFormalParameter( dw_client cli, dw_handle parm_type, dw_loc_handle parm_loc, dw_loc_handle segment, const char *name, uint default_value_type, ... );
:p.Declare a formal parameter to the current function.
:dl.
:dt.parm_type
:dd.The type of the parameter.
:dt.parm_loc
:dd.A location description that yields the address of the parameter.
May be NULL indicating unknown address.
:dt.segment
:dd.A location expression that yields the segment of the parameter.
May be NULL indicating the default segment.
:dt.default_value_type
:dd.One of the following:
:dl.
:dt.DW_DEFAULT_NONE
:dd.There is no default value for this parameter.
:dt.DW_DEFAULT_FUNCTION
:dd.The default value for this parameter is returned by a function
with no args, that is specified by a CLIReloc for DW_W_DEFAULT_FUNCTION.
:dt.DW_DEFAULT_STRING
:dd.The default value is a null-terminated string that is specified
as an extra parameter to this :hp2.DWFormalParameter:ehp2..
:dt.DW_DEFAULT_BLOCK
:dd.The default value is a constant block of data that is specified
by extra "const void *" and "dw_size_t"  parameters to
:hp2.DWFormalParameter:ehp2..
:edl.
:dt....
:dd.Extra parameters depend on the :hp2.default_value_type:ehp2..
:edl.

:h2.dw_handle DWENTRY DWEllipsis( dw_client cli );
:p.Indicate that the current subroutine has unspecified parameters.
Used for "..." in C.

:h2.dw_handle DWENTRY DWLabel( dw_client cli, dw_loc_handle segment, const char *name, dw_addr_offset start_scope );
:p.Declare a label inside a subroutine.  :hp2.start_scope:ehp2. will
usually be 0, but is here for future compatibility.  A CLIReloc for
:hp2.DW_W_LABEL:ehp2. will be made.  :hp2.segment:ehp2. if non-null
indicates which segment the label belongs to.

:h2.dw_handle DWENTRY DWVariable( dw_client cli, dw_handle type, dw_loc_handle loc, dw_handle member_of, dw_loc_handle segment, const char *name, dw_addr_offset start_scope, uint flags );
:p.Declare a variable.
:dl.
:dt.type
:dd.The type of this variable.
:dt.loc
:dd.A location expression yielding the address of this variable.
:dt.member_of
:dd.If this is the definition of a static data member then this
is the handle to the structure type.  Otherwise this is NULL.
:dt.segment
:dd.If this is non-null then it evaluates to the segment the variable
is in.
:dt.flags
:dd.If :hp2.DW_FLAG_GLOBAL:ehp2. is set then this is a global
variable.  Otherwise it is a local variable.  File static variables
in C and C++ are considered local variables.
If :hp2.DW_FLAG_ARTIFICIAL:ehp2. is set then this is a variable that has
been created by the compiler.
:edl.

:h2.dw_handle DWENTRY DWConstant( dw_client cli, dw_handle type, const void *value, dw_size_t len, dw_handle member_of, const char *name, dw_addr_offset start_scope, uint flags );
:p.Declare a named constant.
:dl.
:dt.type
:dd.The type of this constant.
:dt.value
:dd.Pointer to the value for this constant.
:dt.len
:dd.The length of this constant.  If len is 0, then value is considered
to be a null-terminated string.
:dt.member_of
:dd.If this is the definition of a constant member of a structure type,
then this is the handle to the structure type.	Otherwise it is NULL.
:edl.

:h2.void DWENTRY DWAddress( dw_client cli, uint_32 len );
:p.DWARF builds a table of all the addresses attributed to a compilation
unit.  The client calls this function to add addresses to this table.
:hp2.len:ehp2. is the length of this address range.  The base of the
address range is filled in by a CLIReloc for :hp2.DW_W_ARANGE_ADDR:ehp2..

:h2.void DWENTRY DWPubname( dw_client cli, dw_handle hdl, const char *name );
:p.These are used to speed up the debugger.  This should be called for any
name that has global scope.  :hp2.hdl:ehp2. is the handle for the debugging
entry that declares/defines the :hp2.name:ehp2..

:H0.Required Client Routines
:p.The debugging information has several sections indicated by the
following enumerated type:
:DL tsize=22.
:DTHD.Constant
:DDHD.Description
:DT.DW_DEBUG_INFO
:DD.This section is called :SF font=4..debug_info:eSF., which stores
all the debugging information entries.
:DT.DW_DEBUG_PUBNAMES
:DD.This section is called :SF font=4..debug_pubnames:eSF., which
stores a table consisting of object name information that is used in
lookup by Name.
:DT.DW_DEBUG_ARANGES
:DD.This section is called :SF font=4..debug_aranges:eSF., which stores
a table consisting of object address information that is used in lookup
by Address.
:DT.DW_DEBUG_LINE
:DD.This section is called :SF font=4..debug_line:eSF., which stores
the line number information generated for the compilation units.
:DT.DW_DEBUG_LOC
:DD.This section is called :SF font=4..debug_loc:eSF., which stores the
location lists information.
:DT.DW_DEBUG_ABBREV
:DD.This section is called :SF font=4..debug_abbrev:eSF., which stores
abbreviation declarations.
:DT.DW_DEBUG_MACINFO
:DD.This section is called :SF font=4..debug_macinfo:eSF., which stores
macro information.
:DT.DW_DEBUG_REF
:DD.This section is called :SF font=4..WATCOM_references:eSF., which
contains information about the symbols of every instructions in the
source files.
:DT.DW_DEBUG_MAX
:DD.Defined for convenience; it is the number of sections.
:eDL.

:H1.Performance Considerations
:p.The DW library does it's best to try and group CLIWrite operations
together into one larger CLIWrite, and to try and avoid using CLISeek.
But the library does not go out of it's way to provide this massaging
of output.  The client should attempt to buffer the data itself.  CLISeek
is most often called on the DW_DEBUG_INFO, and the
DW_DEBUG_LOC sections.	The other sections may have one CLISeek performed
at the DWFini stage, and the seek will be to the zero offset.  The
client might wish to optimize performance for only the DW_DEBUG_INFO
and the DW_DEBUG_LOC sections.

:H2.void CLISeek( uint section, long offset, uint mode );
:P.Repositions the pointer in :hp2.section:ehp2. so that subsequent
output occurs at the new pointer.
:DL.
:dthd.Mode
:ddhd.Description
:dt.DW_SEEK_SET
:dd.The position is set to the absolute location :hp2.offset:ehp2..
:dt.DW_SEEK_CUR
:dd.:hp2.offset:ehp2. is added to the current position.
:dt.DW_SEEK_END
:dd.The position is set to :hp2.offset:ehp2. bytes from the current end
of :hp2.section:ehp2.
:edl.

:h2.long CLITell( uint section );
:P.Return the offset of the next byte to be written to the section.

:h2.void CLIReloc( uint section, uint reloc_type, ... );
:p.Even when writing BROWSER information, relocations such as DW_W_LOC_PC
may be asked for.  This is because the DWARF format requires the presence
of certain fields to indicate something specific about a record.  For
example, if a subroutine record doesn't have a low pc then it is assumed
to be a declaration of the subroutine rather than a definition.
:dl.
:dt.section
:dd.The section to write a relocation entry to.
:dt.reloc_type
:dd.The type of the relocation, as follows:
:DL.
:dt.DW_W_LOW_PC
:dd.Emit a dw_targ_addr.
Used by various entry points to get the low pc address of an object.
:dt.DW_W_HIGH_PC
:dd.Emit a dw_targ_addr.
Used by various entry points to get the high pc address of an object.