dwdoc.gml

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

:PSC proc='rita'.
**RTA**wgmlstd.rta
:ePSC.
:LAYOUT.
:HEADING
threshold = 3
:eLAYOUT.
:GDOC.
:FRONTM.
:TITLEP.
:TITLE.SPECIFICATION FOR THE DWARF WRITING LIBRARY
:TITLE.Draft #6
:DATE.
:eTITLEP.
:BODY.
:H0.Debugging Information
:p.The include file "dw.h" should be included to access the DW library.

:H1.Data Types
:p.The following types are defined in "dwcnf.h" and may be redefined
if the entire library is to be recompiled.  ("dw.h" automatically
includes "dwcnf.h".);
:DL.
:DTHD.Type
:DDHD.Description
:DT.dw_sym_handle
:DD.Has a client defined meaning; the DW library will pass these
back to the client in :hp2.CLIRelocs:ehp2. for :hp2.DW_W_STATIC:ehp2.,
and :hp2.DW_W_SEGMENT:ehp2..
:DT.dw_targ_addr
:DD.The contents of :hp2.dw_targ_addr:ehp2. is unimportant to the
DW library; it is only used for :hp2.sizeof( dw_targ_addr ):ehp2..
A :hp2.dw_targ_addr:ehp2. is the type that will be emitted for
relocations to run-time addresses.
:DT.dw_targ_seg
:DD.This is the size of the quantity that :hp2.DW_W_SEGMENT:ehp2. emits.
:DT.dw_addr_offset
:DD.The type used for offsets from some base address.
For example, the :hp2.start_scope:ehp2. parameter to typing routines,
or the :hp2.addr:ehp2. parameter to line number information.
The code assumes this is an unsigned integer type.
:DT.dw_addr_delta
:DD.An integer type that can hold the largest possible
difference between the :hp2.addr:ehp2. parameter for two subsequent
calls to :hp2.DWLineNum:ehp2..
:DT.dw_linenum
:DD.A line number.  It must be an unsigned integer type.
:DT.dw_linenum_delta
:DD.dw_linenum_delta is a type that can hold the largest possible
difference between two adjacent line
numbers passed to :hp2.DWLineNum:ehp2. or :hp2.DWReference:ehp2..
:DT.dw_column
:DD.A column number.  It must be an unsigned integer type.
:DT.dw_column_delta
:DD.dw_column_delta is a type that can hold the largest possible
difference between two adjacent column numbers
passed to :hp2.DWReference:ehp2..
:DT.dw_size_t
:DD.Used for sizes of various things such as block constants
(i.e. for DWAddConstant) and the :hp2.size:ehp2. parameter to
:hp2.CLIWrite:ehp2..
:DT.dw_uconst
:DD.An unsigned integer type that can hold the largest possible
unsigned integer constant.
:DT.dw_sconst
:DD.A signed integer type that can hold the largest possible
signed integer constant.
:edl.

:H1.Initialization and Finalization

:P.In the following functions, unless specified otherwise all strings
are assumed to be null-terminated.
:P.The DW library does not assume that a pointer passed to it is valid
beyond the function call used to pass it.
For example, you can pass the address of an auto-buffer that contains a
string.
:P.All names passed to the DW library should be unmangled.
:P.The :HP2.cli:eHP2. parameter required for all DW functions except
:HP2.DWInit:eHP2. is assumed to be a valid value returned by a call to
:HP2.DWInit:eHP2..
:P.Currently DWENTRY is defined to be nothing.
It was created in case there is ever a need to put the DW library into
a DLL.
:H2.dw_client DWENTRY DWInit( dw_init_info *info );
:P.Initialization for a compilation unit.
Return an unique client id.  This function will call client functions
passed to it, so any client function initialization must be done before
the call to DWInit.
:XMP.
:SF font=4.
typedef struct {
    void		(*reloc)( uint, uint, ... );
    void		(*write)( uint, const void *, dw_size_t );
    void		(*seek)( uint, long, uint );
    long		(*tell)( uint );
    void *		(*alloc)( size_t );
    void		(*free)( void * );
} dw_funcs;

typedef struct {
    dw_lang		language;
    uint_8		compiler_options;
    const char *	producer_name;
    jmp_buf		exception_handler;
    dw_funcs		funcs;
} dw_init_info;
:eSF.
:eXMP.
:DL.
:DTHD.Member
:DDHD.Description
:DT.language
:DD.Language used.
:DL tsize=24.
:DTHD.Constant
:DDHD.Language
:DT.DWLANG_C
:DD.ISO/ANSI C
:DT.DWLANG_CPP
:DD.C++
:DT.DWLANG_FORTRAN
:DD.FORTRAN77
:eDL.
:DT.compile_options
:DD.Compilation option, which is a combination of bits:
:DL tsize=20.
:DTHD.Bit
:DDHD.Description
:DT.DW_CM_BROWSER
:DD.The library generates the debugging information for the class
browser.
:DT.DW_CM_DEBUGGER
:DD.The library generates the debugging information for the debugger.
:DT.DW_CM_UPPER
:DD.For FORTRAN - The compiler converts all identifier names to upper
case.
:DT.DW_CM_LOWER
:DD.For FORTRAN - The compiler converts all identifier names to lower
case.
:eDL.
:DT.producer
:DD.A string that identifies the compiler.
:DT.exception_handler
:DD.If the library ends up in a situation which it can't handle (can
we say
bug ;-) ) this jmp_buf will be called with a non-zero value.
This is a fatal exit, and the client should not call any of the DW
functions.  (FIXME: The library is currently not very good at cleaning
up memory in these situations.);
:DT.funcs
:DD.These functions are described in a later section.
The initialization routines may call any of them; so any initialization
necessary for these routines must be done before DWInit is called.
:eDL.
:P.The details of the above functions are discussed in Part 3.

:H2.void DWENTRY DWFini( dw_client cli );
:P.Finalize the debugging information generator.  This routine must be
called last.  It frees any structures that the DW library required, and
flushes all the debugging information.

:H2.dw_handle DWENTRY DWBeginCompileUnit( dw_client cli, const char *source_filename, const char *directory, dw_loc_handle segment, const unsigned offset_size );
:P.This function is called some time after :hp2.DWInit:ehp2..
The only other DW functions that can be called in between are those
dealing with location expressions.
:DL.
:DTHD.Parameter
:DDHD.Definition
:DT.source_filename
:DD.Name of the source file.
:DT.directory
:DD.Compilation directory.
:DT.segment
:DD.A location expression who's result is the code segment portion
of the low_pc and high_pc.
:DT.offset_size
:DD.The size in bytes of the offset portion of an address in this compile unit
:eDL.
:P.The following CLIRelocs will be required:
:sL.
:LI.DW_W_HIGH_PC
:LI.DW_W_LOW_PC
:LI.DW_W_SECTION_POS
:LI.DW_W_UNIT_SIZE
:eSL.

:H2.void DWENTRY DWEndCompilationUnit( dw_client cli );
:P.This function pairs up with :hp2.DWBeginCompilationUnit:ehp2..
After this, until the next :hp2.DWBeginCompilationUnit:ehp2., the
only valid calls are those made to location expression routines
(or :hp2.DWFini:ehp2.).

:H0.Ordering Considerations
:p.In general the DW routines are called in an order that matches the
order of the declarations during the source program.  The sole exception
to this are the Macro information routines.  Since it is possible to
have a separate preprocessor pass, the library assumes that these
routines can be called before any of the other routines.  That is
why the macro routines have a separate mechanism for specifying
file and line number.

:H0.Macro Information
:H2.void DWENTRY DWMacStartFile( dw_client cli, dw_linenum line, const char *name );
:p.Subsequent DWMac calls refer to the named file.

:H2.void DWENTRY DWMacEndFile( dw_client cli );
:p.End the current included file.

:H2.dw_macro DWENTRY DWMacDef( dw_client cli, dw_linenum line, const char *name );
:P.Defines a macro.
:HP2.name:eHP2. is the name of the macro.
A :HP2.dw_macro:eHP2. is returned and must be used in a subsequent call
to :HP2.DWMacFini:eHP2. (and possibly :HP2.DWMacParam:eHP2.).

:H2.void DWENTRY DWMacParam( dw_client cli, dw_macro mac, const char *name );
:P.Adds a parameter to the macro definition :HP2.mac:eHP2..
:HP2.name:eHP2. is the name of the parameter with no leading or
trailing white-space.
The order of parameters must be the same as they appear in the source
program.

:H2.void DWENTRY DWMacFini( dw_client cli, dw_macro mac, const char *def );
:P.Finishes the macro definition :HP2.mac:eHP2..
:HP2.def:eHP2. is the definition string.

:H2.void DWENTRY DWMacUnDef( dw_client cli, dw_linenum line, const char *name );
:P.Undefines the macro named :HP2.name:eHP2..

:H2.void DWENTRY DWMacUse( dw_client cli, dw_linenum line, const char *name );
:p.Indicate where the macro named :hp2.name:ehp2. is used.

:H0.File and Line-Number Management

:H2.void DWENTRY DWSetFile( dw_client cli, const char *file );
:P.Specifies the current file.
The default is for the source_filename parameter from the dw_init_info
to be the current file.

:H2.void DWLineNum( dw_client cli, uint info, dw_linenum line, uint col, dw_addr_offset addr );
:P.Sets the current source line number and machine address.
The line numbers information of all instructions, not just
declarations, are stored by this routine.
Note that all source line numbers are relative to the beginning of
their corresponding source file.
So the line number of the first line of an included file is one.
:DL.
:DTHD.Parameter
:DDHD.Definition
:DT.info
:DD.The information about the line, which is established by the
combination of the following bits:
:DL tsize=20.
:DTHD.Bit
:DDHD.Description
:DT.DW_LN_DEFAULT
:DD.There is no special information about the line.
:DT.DW_LN_STMT
:DD.The line is the beginning of a statement.
:DT.DW_LN_BLK
:DD.The line is the beginning of a block.
:eDL.
:DT.line
:DD.Source line number, numbered beginning with one on the first line
of the file.
:DT.col
:DD.Source column number, which begins at 1.
:DT.addr
:DD.Address of instruction relative to the beginning of the compilation
unit.  If it is at all possible the client should call :hp2.DWLineNum:ehp2.
with increasing addrs.	The line parameter does not have to be
increasing.  The size of the emitted line number information is smaller
if increasing addrs are used.  (There is also an implementation
limitation that the maximum decrease of addr between two calls is 32768.);
:eDL.

:H2.void DWENTRY DWDeclFile( dw_client cli, const char *name );
:p.Subsequent declarations are from the file named :hp2.name:ehp2..

:H2.void DWENTRY DWDeclPos( dw_client cli, dw_linenum line, dw_column column );
:p.The next declaration occurs at the indicated line and column in the
source file set by the last call to :hp2.DWDeclFile:ehp2..  Note that
the position is only used for the immediate next declaration.  If there
are multiple declarations on the same line, then multiple calls should
be made.

:H2.void DWENTRY DWReference( dw_client cli, dw_linenum line, dw_column column, dw_handle dependant );
:P.Indicate that in the source code there is a reference to the dependant.
This reference is attributed to the current scope of debugging information.
(i.e., if it is done inside a structure, then the structure is considered
to be the "referencer").

:H0.Location Expression Routines
:P.Many functions require a :HP2.dw_loc_handle:eHP2..
These are handles for expressions that the debugger will evaluate.
A :HP2.dw_loc_handle:eHP2. can be either a single expression, or a list
of expressions created by :HP2.DWListFini:eHP2..  The BROWSER is only
interested in whether a location expression is present or not; so
when creating BROWSER output the client may create an empty location
expression and use that wherever appropriate.
:P.The expressions are evaluated on a stack machine, with operations
described later.
In some cases the stack will be initially empty, in other cases (such
as when calculating the address of a structure field) some base address
will be on the stack.
:P.A location expression is limited to roughly 64K.  Since each op-code
is a single byte, this shouldn't pose much of a limitation (famous
last words).  The destination of the branch instructions
:hp2.DW_LOC_BRA:ehp2. and :hp2.DW_LOC_SKIP:ehp2. must be within
32K of the current instruction.  (This is a limitation of the DWARF
format, not a limitation of the DW library.);

:H2.dw_loc_id DWENTRY DWLocInit( dw_client cli );
:P.First function called to create a location expression for a symbol.
An unique :HP2.dw_loc_id:eHP2. is returned to the front end.

:H2.dw_loc_label DWENTRY DWLocNewLabel( dw_client cli, dw_loc_id loc );
:P.Create a label for the location expression being built in :hp2.loc:ehp2..
This label can be used for forward or backward references by
:hp2.DW_LOC_SKIP:ehp2. and :hp2.DW_LOC_BRA:ehp2..

:H2.void DWENTRY DWLocSetLabel( dw_client cli, dw_loc_id loc, dw_loc_label label );
:P.Give the label :hp2.label:ehp2. the address of the next operation
emitted into the location expression :hp2.loc:ehp2..

:H2.void DWENTRY DWLocReg( dw_client cli, dw_loc_id loc, uint reg );
:P.This 'operation' informs the debugger that the value it seeks is in
the register named by :HP2.reg:eHP2..
FIXME: need to define the possible values of :HP2.reg:eHP2..

:H2.void DWENTRY DWLocStatic( dw_client cli, dw_loc_id loc, dw_sym_handle sym );
:P.This operation pushes the address of :hp2.sym:ehp2. on the stack.

:H2.void DWENTRY DWLocSegment( dw_client cli, dw_loc_id loc, dw_sym_handle sym );
:P.This operation pushes the segment of the address
of :hp2.sym:ehp2. on the stack.

:H2.void DWENTRY DWLocConstU( dw_client cli, dw_loc_id loc, dw_uconst value );
:P.Pushes an atom which is has an unsigned constant value :HP2.value:eHP2..

:H2.void DWENTRY DWLocConstS( dw_client cli, dw_loc_id loc, dw_sconst value );
:P.Pushes an atom which is has a signed constant value :HP2.value:eHP2..

:H2.void DWENTRY DWLocOp0( dw_client cli, dw_loc_id loc, dw_optype op );
:p.Performs one of the operations listed below.
:DL tsize=24 break.
:DTHD.Operation
:DDHD.Description
:DT.DW_LOC_ABS
:DD.It pops the top stack entry and pushes its absolute value.
:DT.DW_LOC_AND
:DD.It pops the top two stack values, performs the logical AND
operation on the two, and pushes the result.
:DT.DW_LOC_DEREF
:DD.It pops the top stack entry and treats it as an address.
The value retrieved from that address is pushed.
The size of data retrieved from the dereferenced address is an
addressing unit.
:DT.DW_LOC_DIV
:DD.It pops the top two stack values, divides the former second entry
by the former top of the stack using signed division, and pushes the
result.
:DT.DW_LOC_DROP
:DD.It pops the value at the top of the stack.
:DT.DW_LOC_DUP
:DD.It duplicates the value at the top of the stack.
:DT.DW_LOC_EQ
:DD.Pop two entries from stack, push 1 if they are equal; push 0 otherwise.
:DT.DW_LOC_GE, DW_LOC_GT, DW_LOC_LE, DW_LOC_LT
:DD.These operation pop the top two stack values, compare the former
top of stack from the former second entry, and pushes 1 onto stack if
the comparison is true, 0 if it is false.
The comparisons are signed comparison.
:DT.DW_LOC_MINUS
:DD.It pops the top two stack values, subtracts the former top of the
stack from the former second entry, and pushes the result.
:DT.DW_LOC_MOD
:DD.It pops the top two stack values, and pushes the result of the