dwdoc.gml

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

:dt.DW_W_STATIC
:dd.Emit a dw_targ_addr.
This relocation has an extra parameter of type dw_sym_handle.
This parameter is the target of the relocation; the offset
of the symbol should be generated.
This is used any time a location expression
involving a :hp2.DWLocStatic:ehp2. is generated.
:dt.DW_W_SEGMENT
:dd.Emit a dw_segment.
This relocation has an extra parameter of type dw_sym_handle.
It indicates that the segment portion of the address of the symbol
should be generated.
This is used any time a location expression
involving a :hp2.DWLocSegment:ehp2. operation is generated.
:dt.DW_W_LABEL
:dd.Emit a dw_targ_addr.
Used by :hp2.DWLabel:ehp2..
:dt.DW_W_SECTION_POS
:dd.Emit a uint_32.
This relocation has an extra parameter of type uint called
:hp2.targ_sect:ehp2..  :hp2.targ_sect:ehp2.
parameter is the number of a section for which the current
offset is the target of the relocation.  The relocation
is emitted into :hp2.section:ehp2..
:dt.DW_W_DEFAULT_FUNCTION
:dd.Emit a dw_targ_addr.
Used by :hp2.DWFormalParameter:ehp2..
:dt.DW_W_ARANGE_ADDR
:dd.Emit a dw_targ_addr.
Used by :hp2.DWAddress:ehp2..
:dt.DW_W_UNIT_SIZE
:dd.Emit an uint_32 that is the number of bytes of code in the current
compilation unit.
:DT.DW_W_MAX
:dd.Defined for convenience.  This enumerated type starts at 0 and
goes to DW_W_MAX.
:eDL.
:edl.

:H2.void CLIWrite( uint section, const void *block, size_t len );
:P.Writes out the debugging information.
:DL.
:DTHD.Parameter
:DDHD.Description
:DT.section
:DD.The section to which the debugging information is written.
:DT.block
:DD.Points to the debugging information block.
:DT.len
:DD.Length of the debugging information block.
:eDL.

:H2.void *CLIAlloc( size_t size );
:P.Allocates a memory block of size :HP2.size:eHP2. for the library and
returns its address.
This function cannot return NULL.

:H2.void CLIFree( void *blk );
:P.Free the block pointed by :HP2.blk:eHP2..

:H0.Examples
:p.:hp2.This section needs a major rewrite.:ehp2.
:P.The example below shows what functions should be called in order to
store the debugging information for this C program.
:P.N.B.
In this example, for all the CLIWrite() calls, only the section id is
accurate.
Also for all DWLineNum() calls, the advances in machine instruction
address are inaccurate.
:xmp.
test.c:
:sf font=4.

1 #include <stdlib.h>

2 int	 a;

3 typedef near char NCHAR;

4 void main();
5 {
6    NCHAR    b;

7    b := 5;
8 }

:esf.
Functions called by the client and the DWARF library:

Client:
:sf font=4.

	cli_id = DWInit( DW_LANG_C89, DW_CM_DEBUGGER, "test.c",
			 "c:\mydir", 0x123, 1, CLILoc, CLIType,
			 CLIName, CLIWrite, CLIAlloc, CLIFree );
:esf.
:exmp.

DWARF Library:

:xmp.
:sf font=4.
	/* Initialize the .debug_line section */
	CLIWrite( DW_DEBUG_LINE, 0, &info, 20, block );

	/* Initialize the .debug_abbrevs section */
	CLIWrite( DW_DEBUG_ABBREVS, 0, &info, 50, block );

	/* Initialize the .debug_pubnames section */
	CLIWrite( DW_DEBUG_PUBNAMES, 0, &info, 50, block );

	/* Initialize the .debug_aranges section */
	CLIWrite( DW_DEBUG_ARANGES, 0, &info, 50, block );

	/* Write all strings to the string table */
	CLIWrite( DW_DEBUG_STR, 0, &info, 17, block );
:esf.
:exmp.

Client:

:xmp.
:sf font=4.
#include <stdlib.h>

	DWLineNum( cli_id, DW_LN_STMT|DW_LN_BLK, 1, 1, 0 );
	DWIncl( id, "stdlib.h" );
	...Function calls for "stdlib.h"...
	DWInclFini( cli_id );

:esf.
:exmp.
DWARF Library:
:xmp.
:sf font=4.

	CLIWrite( DW_DEBUG_LINE, 0, &info, 28, block );
	CLIWrite( DW_DEBUG_INFO, 30, &info, 12, block );

:esf.
:exmp.
Client:

:xmp.
:sf font=4.
int   a;

	DWLineNum( cli_id, DW_LN_STMT, 1, 1, 4 );
	a_dw_handle = DWModSym( cli_id, a_cg_handle, DW_SM_VAR,
			DW_SM_GLO|DW_SM_FILE, DW_SM_NULL );

:esf.
:exmp.
DWARF Library:

:xmp.
:sf font=4.
	name = CLIName( a_cg_handle );
		/* It returns the string "a". */
	type = CLIType( a_cg_handle );
		/* It returns DW_FT_INTEGER. */
	loc = CLILoc( a_cg_handle );
	CLIWrite( DW_DEBUG_LINE, 0, &info, 28, block );
	CLIWrite( DW_DEBUG_INFO, 0, &info, 24, block );
	CLIWrite( DW_DEBUG_PUBNAMES, 0, &info, 12, block );

:esf.
:exmp.
Inside CLILoc():

:xmp.
:sf font=4.
	loc_id = DWLocInt();
	DWLocAtom( cli_id, a_cg_handle, DW_LOC_STATIC );
	/* The actual address will be filled in by the client when
	   the debugging information is written to the object file.*/
	a_loc_hd = DWLocFini( loc_id );
	return a_loc_hd;

:esf.
:exmp.
Client:

:xmp.
:sf font=4.
typedef near char NCHAR;

	DWLineNum( cli_id, DW_LN_STMT, 1, 1, 14 );
	mod_handle = DWMod( cli_id, DW_FT_CHAR, DW_MOD_NEAR );
	nchar_handle = DWModSym( cli_id, nchar_cg_handle,
		DW_SM_TYPEDEF, DW_SM_NULL, DW_SM_NULL );

:esf.
:exmp.
DWARF Library:

:xmp.
:sf font=4.
	name = CLIName( nchar_cg_handle );
		/* It returns the string "NCHAR". */
	type = CLIType( nchar_cg_handle );
		/* It returns mod_handle. */
	CLIWrite( DW_DEBUG_LINE, 0, &info, 20, block );
	CLIWrite( DW_DEBUG_INFO, 0, &info, 24, block );

:esf.
:exmp.
Client:
:xmp.
:sf font=4.

void main();

	DWLineNum( cli_id, DW_LN_DEFAULT, 1, 1, 23 );
	pro_handle = DWBegProc( cli_id, DW_SB_NEAR_CALL, DW_FT_VOID,
			ret_loc_hd, DW_LOC_NULL,
			DW_SB_GLOBAL_SUB|DW_SB_FUNC_PROTOTYPE );

:esf.
:exmp.
In order to get ret_loc_ad:
:xmp.
:sf font=4.

	loc_id = DWLocInit();
	DWLocAtom( cli_id, some_cg_handle, DW_LOC_STATIC );
		/* Assume that the return address of main() is stored
		   in a symbol with some_cg_handle as its handle.
		   The actual address will be filled in by the
		   client when the debugging information is written
		   to the object file.				     */
	ret_loc_ad = DWLocFini( cli_id );

:esf.
:exmp.
DWARF Library:

:xmp.
:sf font=4.
	CLIWrite( DW_DEBUG_LINE, 0, &info, 20, block );

:esf.
:exmp.
Client:

:xmp.
:sf font=4.
{
	DWLineNum( cli_id, DW_LN_BLK, 1, 1, 0 );

:esf.
:exmp.
DWARF Library:

:xmp.
:sf font=4.
	CLIWrite( DW_DEBUG_LINE, 0, &info, 24, block );

:esf.
:exmp.
Client:

:xmp.
:sf font=4.
NCHAR b;

	DWLineNum( cli_id, DW_LN_STMT, 1, 1, 10 );
	b_handle = DWModSym( cli_id, b_cg_handle, DW_SM_VAR,
			DW_SM_NULL, DW_SM_LOC|DW_SM_ROUT );

:esf.
:exmp.
DWARF Library:

:xmp.
:sf font=4.
	loc = CLILoc( b_cg_handle );
	name = CLIName( b_cg_handle );
		/* It returns the string "b". */
	type = CLIType( b_cg_handle );
		/* It returns nchar_handle. */
	CLIWrite( DW_DEBUG_LINE, 0, &info, 20, block );

:esf.
:exmp.
Inside CLILoc():

:xmp.
:sf font=4.
	loc_id = DWLocInt();
	DWLocAtom( cli_id, b_cg_handle, DW_LOC_STACK );
	/* The offset from stack frame base will be filled in by
	   the client when the debugging information is written
	   to the object file.	 */
	b_loc_hd = DWLocFini( loc_id );
	return b_loc_hd;

:esf.
:exmp.
Client:
:xmp.
:sf font=4.

b := 5;
	DWLineNum( cli_id, DW_LN_STMT, 1, 4, 14 );

:esf.
:exmp.
DWARF Library:

:xmp.
:sf font=4.
	CLIWrite( DW_DEBUG_LINE, 0, &info, 24, block );

:esf.
:exmp.
Client:
:xmp.
:sf font=4.

}
	DWLineNum( cli_id, DW_LN_DEFAULT, 1, 1, 4 );
	DWEndProc( cli_id, pro_handle );
	main_handle = DWModSym( cli_id, main_cg_handle, DW_SM_SUB,
			DW_SM_NULL, DW_SM_NULL );

:esf.
:exmp.
DWARF Library:

:xmp.
:sf font=4.
	name = CLIName( main_cg_handle );
		/* It returns the string "main" */
	type = CLIType( main_cg_handle );
		/* It returns pro_handle */
	CLIWrite( DW_DEBUG_LINE, 0, &info, 24, block );
	CLIWrite( DW_DEBUG_INFO, -50, &info, 86, block );
	CLIWrite( DW_DEBUG_REF, 0, &info, 12, block );
	CLIWrite( DW_DEBUG_PUBNAMES, 0, &info, 12, block );
		/* For the global object "main" */

:esf.
:exmp.
Client:
:xmp.
:sf font=4.

	DWFini( cli_id );

:esf.
:exmp.
DWARF Library:

:xmp.
:sf font=4.
	CLIWrite( DW_DEBUG_LINE, 0, &info, 24, block );
	CLIWrite( DW_DEBUG_INFO, -120, &info, 54, block );
:esf.
:exmp.

:H0.Revision History
:DL.
:DTHD.Draft
:DDHD.Description
:DT.Draft 5
:DD.Changed the arguments to a number of the function calls for use with
draft 5 of dwarf.
:DT.Draft 6
:DD.Changed the arguments to a number of the function calls for use with
draft 6 of dwarf.
:edl.

:BACKM.
:eGDOC.