|
1 \." $Revision: 1.12 $ |
|
2 \." $Date: 2002/01/14 23:40:11 $ |
|
3 \." |
|
4 \." |
|
5 \." the following line may be removed if the ff ligature works on your machine |
|
6 .lg 0 |
|
7 \." set up heading formats |
|
8 .ds HF 3 3 3 3 3 2 2 |
|
9 .ds HP +2 +2 +1 +0 +0 |
|
10 .nr Hs 5 |
|
11 .nr Hb 5 |
|
12 \." ============================================== |
|
13 \." Put current date in the following at each rev |
|
14 .ds vE rev 1.20, 4 Sep 2007 |
|
15 \." ============================================== |
|
16 \." ============================================== |
|
17 .ds | | |
|
18 .ds ~ ~ |
|
19 .ds ' ' |
|
20 .if t .ds Cw \&\f(CW |
|
21 .if n .ds Cw \fB |
|
22 .de Cf \" Place every other arg in Cw font, beginning with first |
|
23 .if \\n(.$=1 \&\*(Cw\\$1\fP |
|
24 .if \\n(.$=2 \&\*(Cw\\$1\fP\\$2 |
|
25 .if \\n(.$=3 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP |
|
26 .if \\n(.$=4 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4 |
|
27 .if \\n(.$=5 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP |
|
28 .if \\n(.$=6 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6 |
|
29 .if \\n(.$=7 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP |
|
30 .if \\n(.$=8 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8 |
|
31 .if \\n(.$=9 \&\*(Cw\\$1\fP\\$2\*(Cw\\$3\fP\\$4\*(Cw\\$5\fP\\$6\*(Cw\\$7\fP\\$8\ |
|
32 *(Cw |
|
33 .. |
|
34 .nr Cl 3 |
|
35 .SA 1 |
|
36 .TL |
|
37 A Producer Library Interface to DWARF |
|
38 .AF "" |
|
39 .AU "David Anderson" |
|
40 .PF "'\*(vE '- \\\\nP -''" |
|
41 .AS 1 |
|
42 This document describes an interface to a library of functions |
|
43 to create DWARF debugging information entries and DWARF line number |
|
44 information. It does not make recommendations as to how the functions |
|
45 described in this document should be implemented nor does it |
|
46 suggest possible optimizations. |
|
47 .P |
|
48 The document is oriented to creating DWARF version 2. |
|
49 Support for creating DWARF3 is intended but such support |
|
50 is not yet fully present. |
|
51 .P |
|
52 \*(vE |
|
53 .AE |
|
54 .MT 4 |
|
55 .H 1 "INTRODUCTION" |
|
56 This document describes an interface to \f(CWlibdwarf\fP, a |
|
57 library of functions to provide creation of DWARF debugging information |
|
58 records, DWARF line number information, DWARF address range and |
|
59 pubnames information, weak names information, and DWARF frame description |
|
60 information. |
|
61 |
|
62 |
|
63 .H 2 "Copyright" |
|
64 Copyright 1993-2006 Silicon Graphics, Inc. |
|
65 |
|
66 Copyright 2007 David Anderson. |
|
67 |
|
68 Permission is hereby granted to |
|
69 copy or republish or use any or all of this document without |
|
70 restriction except that when publishing more than a small amount |
|
71 of the document |
|
72 please acknowledge Silicon Graphics, Inc and David Anderson. |
|
73 |
|
74 This document is distributed in the hope that it would be useful, but |
|
75 WITHOUT ANY WARRANTY; without even the implied warranty of |
|
76 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
|
77 .H 2 "Purpose and Scope" |
|
78 The purpose of this document is to propose a library of functions to |
|
79 create DWARF debugging information. Reading (consuming) of such records |
|
80 is discussed in a separate document. |
|
81 |
|
82 The functions in this document have mostly been implemented at |
|
83 Silicon Graphics |
|
84 and are being used by the code generator to provide debugging information. |
|
85 Some functions (and support for some extensions) were provided |
|
86 by Sun Microsystems. |
|
87 |
|
88 .P |
|
89 The focus of this document is the functional interface, |
|
90 and as such, implementation and optimization issues are |
|
91 intentionally ignored. |
|
92 |
|
93 .P |
|
94 Error handling, error codes, and certain \f(CWLibdwarf\fP codes are discussed |
|
95 in the "\fIA Consumer Library Interface to DWARF\fP", which should |
|
96 be read (or at least skimmed) before reading this document. |
|
97 .P |
|
98 However the general style of functions here |
|
99 in the producer librar is rather C-traditional |
|
100 with various types as return values (quite different |
|
101 from the consumer library interfaces). The style |
|
102 generally follows the style of the original DWARF1 reader |
|
103 proposed as an interface to DWARF. |
|
104 When the style of the reader interfaces was changed (1994) in the |
|
105 dwarf reader ( See the "Document History" |
|
106 section of "A Consumer Library Interface to DWARF") |
|
107 the interfaces here were not changed as it seemed like |
|
108 too much of a change for the two applications then using |
|
109 the interface! So this interface remains in the traditional C style |
|
110 of returning various data types with various (somewhat inconsistent) |
|
111 means of indicating failure. |
|
112 |
|
113 .H 2 "Document History" |
|
114 This document originally prominently referenced |
|
115 "UNIX International Programming Languages Special Interest Group " |
|
116 (PLSIG). |
|
117 Both UNIX International and the |
|
118 affiliated Programming Languages Special Interest Group |
|
119 are defunct |
|
120 (UNIX is a registered trademark of UNIX System Laboratories, Inc. |
|
121 in the United States and other countries). |
|
122 Nothing except the general interface style is actually |
|
123 related to anything shown to the PLSIG |
|
124 (this document was open sourced with libdwarf in the mid 1990's). |
|
125 .P |
|
126 See "http://www.dwarfstd.org" for information on current |
|
127 DWARF standards and committee activities. |
|
128 |
|
129 .H 2 "Definitions" |
|
130 DWARF debugging information entries (DIEs) are the segments of information |
|
131 placed in the \f(CW.debug_info\fP and related |
|
132 sections by compilers, assemblers, and linkage |
|
133 editors that, in conjunction with line number entries, are necessary for |
|
134 symbolic source-level debugging. |
|
135 Refer to the document |
|
136 "\fIDWARF Debugging Information Format\fP" from UI PLSIG for a more complete |
|
137 description of these entries. |
|
138 |
|
139 .P |
|
140 This document adopts all the terms and definitions in |
|
141 "\fIDWARF Debugging Information Format\fP" version 2. |
|
142 and the "\fIA Consumer Library Interface to DWARF\fP". |
|
143 |
|
144 .P |
|
145 In addition, this document refers to Elf, the ATT/USL System V |
|
146 Release 4 object format. |
|
147 This is because the library was first developed for that object |
|
148 format. |
|
149 Hopefully the functions defined here can easily be |
|
150 applied to other object formats. |
|
151 |
|
152 .H 2 "Overview" |
|
153 The remaining sections of this document describe a proposed producer |
|
154 (compiler or assembler) interface to \fILibdwarf\fP, first by describing |
|
155 the purpose of additional types defined by the interface, followed by |
|
156 descriptions of the available operations. |
|
157 This document assumes you |
|
158 are thoroughly familiar with the information contained in the |
|
159 \fIDWARF |
|
160 Debugging Information Format\fP document, and |
|
161 "\fIA Consumer Library Interface to DWARF\fP". |
|
162 |
|
163 .P |
|
164 The interface necessarily knows a little bit about the object format |
|
165 (which is assumed to be Elf). We make an attempt to make this knowledge |
|
166 as limited as possible. For example, \fILibdwarf\fP does not do the |
|
167 writing of object data to the disk. The producer program does that. |
|
168 |
|
169 .H 2 "Revision History" |
|
170 .VL 15 |
|
171 .LI "March 1993" |
|
172 Work on dwarf2 sgi producer draft begins |
|
173 .LI "March 1999" |
|
174 Adding a function to allow any number of trips |
|
175 thru the dwarf_get_section_bytes() call. |
|
176 .LI "April 10 1999" |
|
177 Added support for assembler text output of dwarf |
|
178 (as when the output must pass thru an assembler). |
|
179 Revamped internals for better performance and |
|
180 simpler provision for differences in ABI. |
|
181 .LI "Sep 1, 1999" |
|
182 Added support for little- and cross- endian |
|
183 debug info creation. |
|
184 .LI "May 7 2007" |
|
185 This library interface now cleans up, deallocating |
|
186 all memory it uses (the application simply calls |
|
187 dwarf_producer_finish(dbg)). |
|
188 .LE |
|
189 |
|
190 .H 1 "Type Definitions" |
|
191 |
|
192 .H 2 "General Description" |
|
193 The \fIlibdwarf.h\fP |
|
194 header file contains typedefs and preprocessor |
|
195 definitions of types and symbolic names |
|
196 used to reference objects of \fI Libdwarf \fP . |
|
197 The types defined by typedefs contained in \fI libdwarf.h\fP |
|
198 all use the convention of adding \fI Dwarf_ \fP |
|
199 as a prefix to |
|
200 indicate that they refer to objects used by Libdwarf. |
|
201 The prefix \fI Dwarf_P_\fP is used for objects |
|
202 referenced by the \fI Libdwarf\fP |
|
203 Producer when there are similar but distinct |
|
204 objects used by the Consumer. |
|
205 |
|
206 .H 2 "Namespace issues" |
|
207 Application programs should avoid creating names |
|
208 beginning with |
|
209 \f(CWDwarf_\fP |
|
210 \f(CWdwarf_\fP |
|
211 or |
|
212 \f(CWDW_\fP |
|
213 as these are reserved to dwarf and libdwarf. |
|
214 |
|
215 .H 1 "libdwarf and Elf and relocations" |
|
216 Much of the description below presumes that Elf is the object |
|
217 format in use. |
|
218 The library is probably usable with other object formats |
|
219 that allow arbitrary sections to be created. |
|
220 |
|
221 .H 2 "binary or assembler output" |
|
222 With |
|
223 \f(CWDW_DLC_STREAM_RELOCATIONS\fP |
|
224 (see below) |
|
225 it is assumed that the calling app will simply |
|
226 write the streams and relocations directly into |
|
227 an Elf file, without going thru an assembler. |
|
228 |
|
229 With |
|
230 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP |
|
231 the calling app must either |
|
232 A) generate binary relocation streams and write |
|
233 the generated debug information streams and |
|
234 the relocation streams direct to an elf file |
|
235 or |
|
236 B) generate assembler output text for an assembler |
|
237 to read and produce an object file. |
|
238 |
|
239 With case B) the libdwarf-calling application must |
|
240 use the relocation information to change |
|
241 points of each binary stream into references to |
|
242 symbolic names. |
|
243 It is necessary for the assembler to be |
|
244 willing to accept and generate relocations |
|
245 for references from arbitrary byte boundaries. |
|
246 For example: |
|
247 .sp |
|
248 .nf |
|
249 .in +4 |
|
250 .data 0a0bcc #producing 3 bytes of data. |
|
251 .word mylabel #producing a reference |
|
252 .word endlabel - startlable #producing absolute length |
|
253 .in -4 |
|
254 .fi |
|
255 .sp |
|
256 |
|
257 |
|
258 |
|
259 |
|
260 .H 2 "libdwarf relationship to Elf" |
|
261 When the documentation below refers to 'an elf section number' |
|
262 it is really only dependent on getting (via the callback |
|
263 function passed by the caller of |
|
264 \f(CWdwarf_producer_init()\fP) |
|
265 a sequence of integers back (with 1 as the lowest). |
|
266 |
|
267 When the documentation below refers to 'an Elf symbol index' |
|
268 it is really dependent on |
|
269 Elf symbol numbers |
|
270 only if |
|
271 \f(CWDW_DLC_STREAM_RELOCATIONS\fP |
|
272 are being generated (see below). |
|
273 With |
|
274 \f(CWDW_DLC_STREAM_RELOCATIONS\fP |
|
275 the library is generating Elf relocations |
|
276 and the section numbers in binary form so |
|
277 the section numbers and symbol indices must really |
|
278 be Elf (or elf-like) numbers. |
|
279 |
|
280 |
|
281 With |
|
282 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP |
|
283 the values passed as symbol indexes can be any |
|
284 integer set or even pointer set. |
|
285 All that libdwarf assumes is that where values |
|
286 are unique they get unique values. |
|
287 Libdwarf does not generate any kind of symbol table |
|
288 from the numbers and does not check their |
|
289 uniqueness or lack thereof. |
|
290 |
|
291 .H 2 "libdwarf and relocations" |
|
292 With |
|
293 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP |
|
294 libdwarf creates binary streams of debug information |
|
295 and arrays of relocation information describing |
|
296 the necessary relocation. |
|
297 The Elf section numbers and symbol numbers appear |
|
298 nowhere in the binary streams. Such appear |
|
299 only in the relocation information and the passed-back |
|
300 information from calls requesting the relocation information. |
|
301 As a consequence, the 'symbol indices' can be |
|
302 any pointer or integer value as the caller must |
|
303 arrange that the output deal with relocations. |
|
304 |
|
305 With |
|
306 \f(CWDW_DLC_STREAM_RELOCATIONS\fP |
|
307 all the relocations are directly created by libdwarf |
|
308 as binary streams (libdwarf only creates the streams |
|
309 in memory, |
|
310 it does not write them to disk). |
|
311 |
|
312 .H 2 "symbols, addresses, and offsets" |
|
313 The following applies to calls that |
|
314 pass in symbol indices, addresses, and offsets, such |
|
315 as |
|
316 \f(CWdwarf_add_AT_targ_address() \fP |
|
317 \f(CWdwarf_add_arange_b()\fP |
|
318 and |
|
319 \f(CWdwarf_add_frame_fde_b()\fP. |
|
320 |
|
321 With |
|
322 \f(CWDW_DLC_STREAM_RELOCATIONS\fP |
|
323 a passed in address is one of: |
|
324 a) a section offset and the (non-global) symbol index of |
|
325 a section symbol. |
|
326 b) A symbol index (global symbol) and a zero offset. |
|
327 |
|
328 With \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP |
|
329 the same approach can be used, or, instead, |
|
330 a passed in address may be |
|
331 c) a symbol handle and an offset. |
|
332 In this case, since it is up to the calling app to |
|
333 generate binary relocations (if appropriate) |
|
334 or to turn the binary stream into |
|
335 a text stream (for input to an assembler, if appropriate) |
|
336 the application has complete control of the interpretation |
|
337 of the symbol handles. |
|
338 |
|
339 |
|
340 |
|
341 .H 1 "Memory Management" |
|
342 |
|
343 Several of the functions that comprise the \fILibdwarf\fP |
|
344 producer interface dynamically allocate values and some |
|
345 return pointers to those spaces. |
|
346 The dynamically allocated spaces |
|
347 can not be reclaimed (and must |
|
348 not be freed) except by \f(CWdwarf_producer_finish(dbg)\fP. |
|
349 |
|
350 All data for a particular \f(CWDwarf_P_Debug\fP descriptor |
|
351 is separate from the data for any other |
|
352 \f(CWDwarf_P_Debug\fP descriptor in use in the library-calling |
|
353 application. |
|
354 |
|
355 .H 2 "Read-only Properties" |
|
356 All pointers returned by or as a result of a \fILibdwarf\fP call should |
|
357 be assumed to point to read-only memory. |
|
358 Except as defined by this document, the results are undefined for |
|
359 \fILibdwarf\fP clients that attempt to write to a region pointed to by a |
|
360 return value from a \fILibdwarf\fP call. |
|
361 |
|
362 .H 2 "Storage Deallocation" |
|
363 Calling \f(CWdwarf_producer_finish(dbg)\fP frees all the space, and |
|
364 invalidates all pointers returned from \f(CWLibdwarf\fP functions on |
|
365 or descended from \f(CWdbg\fP). |
|
366 |
|
367 .H 1 "Functional Interface" |
|
368 This section describes the functions available in the \fILibdwarf\fP |
|
369 library. Each function description includes its definition, followed |
|
370 by a paragraph describing the function's operation. |
|
371 |
|
372 .P |
|
373 The functions may be categorized into groups: |
|
374 \fIinitialization and termination operations\fP, |
|
375 \fIdebugging information entry creation\fP, |
|
376 \fIElf section callback function\fP, |
|
377 \fIattribute creation\fP, |
|
378 \fIexpression creation\fP, |
|
379 \fIline number creation\fP, |
|
380 \fIfast-access (aranges) creation\fP, |
|
381 \fIfast-access (pubnames) creation\fP, |
|
382 \fIfast-access (weak names) creation\fP, |
|
383 \fImacro information creation\fP, |
|
384 \fIlow level (.debug_frame) creation\fP, |
|
385 and |
|
386 \fIlocation list (.debug_loc) creation\fP. |
|
387 |
|
388 .P |
|
389 The following sections describe these functions. |
|
390 |
|
391 .H 2 "Initialization and Termination Operations" |
|
392 These functions setup \f(CWLibdwarf\fP to accumulate debugging information |
|
393 for an object, usually a compilation-unit, provided by the producer. |
|
394 The actual addition of information is done by functions in the other |
|
395 sections of this document. Once all the information has been added, |
|
396 functions from this section are used to transform the information to |
|
397 appropriate byte streams, and help to write out the byte streams to |
|
398 disk. |
|
399 |
|
400 Typically then, a producer application |
|
401 would create a \f(CWDwarf_P_Debug\fP |
|
402 descriptor to gather debugging information for a particular |
|
403 compilation-unit using \f(CWdwarf_producer_init()\fP. |
|
404 The producer application would |
|
405 use this \f(CWDwarf_P_Debug\fP descriptor to accumulate debugging |
|
406 information for this object using functions from other sections of |
|
407 this document. |
|
408 Once all the information had been added, it would |
|
409 call \f(CWdwarf_transform_to_disk_form()\fP to convert the accumulated |
|
410 information into byte streams in accordance with the \f(CWDWARF\fP |
|
411 standard. |
|
412 The application would then repeatedly call |
|
413 \f(CWdwarf_get_section_bytes()\fP |
|
414 for each of the \f(CW.debug_*\fP created. |
|
415 This gives the producer |
|
416 information about the data bytes to be written to disk. |
|
417 At this point, |
|
418 the producer would release all resource used by \f(CWLibdwarf\fP for |
|
419 this object by calling \f(CWdwarf_producer_finish()\fP. |
|
420 |
|
421 It is also possible to create assembler-input character streams |
|
422 from the byte streams created by this library. |
|
423 This feature requires slightly different interfaces than |
|
424 direct binary output. |
|
425 The details are mentioned in the text. |
|
426 |
|
427 .H 3 "dwarf_producer_init()" |
|
428 |
|
429 .DS |
|
430 \f(CWDwarf_P_Debug dwarf_producer_init( |
|
431 Dwarf_Unsigned flags, |
|
432 Dwarf_Callback_Func func, |
|
433 Dwarf_Handler errhand, |
|
434 Dwarf_Ptr errarg, |
|
435 Dwarf_Error *error) \fP |
|
436 .DE |
|
437 The function \f(CWdwarf_producer_init() \fP returns a new |
|
438 \f(CWDwarf_P_Debug\fP descriptor that can be used to add \f(CWDwarf\fP |
|
439 information to the object. |
|
440 On error it returns \f(CWDW_DLV_BADADDR\fP. |
|
441 \f(CWflags\fP determine whether the target object is 64-bit or 32-bit. |
|
442 \f(CWfunc\fP is a pointer to a function called-back from \f(CWLibdwarf\fP |
|
443 whenever \f(CWLibdwarf\fP needs to create a new object section (as it will |
|
444 for each .debug_* section and related relocation section). |
|
445 \f(CWerrhand\fP |
|
446 is a pointer to a function that will be used for handling errors detected |
|
447 by \f(CWLibdwarf\fP. \f(CWerrarg\fP is the default error argument used |
|
448 by the function pointed to by \f(CWerrhand\fP. |
|
449 .P |
|
450 The \f(CWflags\fP |
|
451 values are as follows: |
|
452 .in +4 |
|
453 \f(CWDW_DLC_WRITE\fP |
|
454 is required. |
|
455 The values |
|
456 \f(CWDW_DLC_READ\fP |
|
457 \f(CWDW_DLC_RDWR\fP |
|
458 are not supported by the producer and must not be passed. |
|
459 |
|
460 If |
|
461 \f(CWDW_DLC_SIZE_64\fP |
|
462 is not OR'd into \f(CWflags\fP |
|
463 then |
|
464 \f(CWDW_DLC_SIZE_32\fP |
|
465 is assumed. |
|
466 Oring in both is an error. |
|
467 |
|
468 If |
|
469 \f(CWDW_DLC_ISA_IA64\fP |
|
470 is not OR'd into \f(CWflags\fP |
|
471 then |
|
472 \f(CWDW_DLC_ISA_MIPS\fP |
|
473 is assumed. |
|
474 Oring in both is an error. |
|
475 |
|
476 If |
|
477 \f(CWDW_DLC_TARGET_BIGENDIAN\fP |
|
478 is not OR'd into \f(CWflags\fP |
|
479 then |
|
480 endianness the same as the host is assumed. |
|
481 |
|
482 If |
|
483 \f(CWDW_DLC_TARGET_LITTLEENDIAN\fP |
|
484 is not OR'd into \f(CWflags\fP |
|
485 then |
|
486 endianness the same as the host is assumed. |
|
487 |
|
488 If both |
|
489 \f(CWDW_DLC_TARGET_LITTLEENDIAN\fP |
|
490 and |
|
491 \f(CWDW_DLC_TARGET_BIGENDIAN\fP |
|
492 are or-d in it is an error. |
|
493 |
|
494 |
|
495 |
|
496 Either one of two output forms is specifiable: |
|
497 \f(CWDW_DLC_STREAM_RELOCATIONS\fP |
|
498 or |
|
499 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP . |
|
500 |
|
501 The default is |
|
502 \f(CWDW_DLC_STREAM_RELOCATIONS\fP . |
|
503 The |
|
504 \f(CWDW_DLC_STREAM_RELOCATIONS\fP |
|
505 are relocations in a binary stream (as used |
|
506 in a MIPS Elf object). |
|
507 |
|
508 The |
|
509 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP |
|
510 are the same relocations but expressed in an |
|
511 array of structures defined by libdwarf, |
|
512 which the caller of the relevant function |
|
513 (see below) must deal with appropriately. |
|
514 This method of expressing relocations allows |
|
515 the producer-application to easily produce |
|
516 assembler text output of debugging information. |
|
517 |
|
518 |
|
519 If |
|
520 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP |
|
521 is OR'd into \f(CWflags\fP |
|
522 then relocations are returned not as streams |
|
523 but thru an array of structures. |
|
524 |
|
525 .in -4 |
|
526 .P |
|
527 The function \f(CWfunc\fP |
|
528 must be provided by the user of this library. |
|
529 Its prototype is: |
|
530 .DS |
|
531 \f(CWtypedef int (*Dwarf_Callback_Func)( |
|
532 char* name, |
|
533 int size, |
|
534 Dwarf_Unsigned type, |
|
535 Dwarf_Unsigned flags, |
|
536 Dwarf_Unsigned link, |
|
537 Dwarf_Unsigned info, |
|
538 int* sect_name_index, |
|
539 int* error) \fP |
|
540 .DE |
|
541 For each section in the object file that \f(CWlibdwarf\fP |
|
542 needs to create, it calls this function once, passing in |
|
543 the section \f(CWname\fP, the section \f(CWtype\fP, |
|
544 the section \f(CWflags\fP, the \f(CWlink\fP field, and |
|
545 the \f(CWinfo\fP field. |
|
546 For an Elf object file these values |
|
547 should be appropriate Elf section header values. |
|
548 For example, for relocation callbacks, the \f(CWlink\fP |
|
549 field is supposed to be set (by the app) to the index |
|
550 of the symtab section (the link field passed thru the |
|
551 callback must be ignored by the app). |
|
552 And, for relocation callbacks, the \f(CWinfo\fP field |
|
553 is passed as the elf section number of the section |
|
554 the relocations apply to. |
|
555 |
|
556 On success |
|
557 the user function should return the Elf section number of the |
|
558 newly created Elf section. |
|
559 .P |
|
560 On success, the function should also set the integer |
|
561 pointed to by \f(CWsect_name_index\fP to the |
|
562 Elf symbol number assigned in the Elf symbol table of the |
|
563 new Elf section. |
|
564 This symbol number is needed with relocations |
|
565 dependent on the relocation of this new section. |
|
566 Because "int *" is not guaranteed to work with elf 'symbols' |
|
567 that are really pointers, |
|
568 It is better to use the |
|
569 \f(CWdwarf_producer_init_b()\fP |
|
570 interface. |
|
571 .P |
|
572 For example, the \f(CW.debug_line\fP section's third |
|
573 data element (in a compilation unit) is the offset from the |
|
574 beginning of the \f(CW.debug_info\fP section of the compilation |
|
575 unit entry for this \f(CW.debug_line\fP set. |
|
576 The relocation entry in \f(CW.rel.debug_line\fP |
|
577 for this offset |
|
578 must have the relocation symbol index of the |
|
579 symbol \f(CW.debug_info\fP returned |
|
580 by the callback of that section-creation through |
|
581 the pointer \f(CWsect_name_index\fP. |
|
582 .P |
|
583 On failure, the function should return -1 and set the \f(CWerror\fP |
|
584 integer to an error code. |
|
585 .P |
|
586 Nothing in libdwarf actually depends on the section index |
|
587 returned being a real Elf section. |
|
588 The Elf section is simply useful for generating relocation |
|
589 records. |
|
590 Similarly, the Elf symbol table index returned thru |
|
591 the \f(CWsect_name_index\fP must simply be an index |
|
592 that can be used in relocations against this section. |
|
593 The application will probably want to note the |
|
594 values passed to this function in some form, even if |
|
595 no Elf file is being produced. |
|
596 |
|
597 .H 3 "dwarf_producer_init_b()" |
|
598 |
|
599 .DS |
|
600 \f(CWDwarf_P_Debug dwarf_producer_init_b( |
|
601 Dwarf_Unsigned flags, |
|
602 Dwarf_Callback_Func_b func, |
|
603 Dwarf_Handler errhand, |
|
604 Dwarf_Ptr errarg, |
|
605 Dwarf_Error *error) \fP |
|
606 .DE |
|
607 The function \f(CWdwarf_producer_init_b() \fP |
|
608 is the same as \f(CWdwarf_producer_init() \fP |
|
609 except that the callback function uses |
|
610 Dwarf_Unsigned rather than int as the |
|
611 type of the symbol-index returned to libdwarf |
|
612 thru the pointer argument (see below). |
|
613 .P |
|
614 The \f(CWflags\fP |
|
615 values are as follows: |
|
616 .in +4 |
|
617 \f(CWDW_DLC_WRITE\fP |
|
618 is required. |
|
619 The values |
|
620 \f(CWDW_DLC_READ\fP |
|
621 \f(CWDW_DLC_RDWR\fP |
|
622 are not supported by the producer and must not be passed. |
|
623 |
|
624 If |
|
625 \f(CWDW_DLC_SIZE_64\fP |
|
626 is not OR'd into \f(CWflags\fP |
|
627 then |
|
628 \f(CWDW_DLC_SIZE_32\fP |
|
629 is assumed. |
|
630 Oring in both is an error. |
|
631 |
|
632 If |
|
633 \f(CWDW_DLC_ISA_IA64\fP |
|
634 is not OR'd into \f(CWflags\fP |
|
635 then |
|
636 \f(CWDW_DLC_ISA_MIPS\fP |
|
637 is assumed. |
|
638 Oring in both is an error. |
|
639 |
|
640 Either one of two output forms are specifiable: |
|
641 \f(CWDW_DLC_STREAM_RELOCATIONS\fP |
|
642 or |
|
643 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP . |
|
644 \f(CWdwarf_producer_init_b() \fP |
|
645 is usable with |
|
646 either output form. |
|
647 |
|
648 Either one of two output forms is specifiable: |
|
649 \f(CWDW_DLC_STREAM_RELOCATIONS\fP |
|
650 or |
|
651 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP . |
|
652 |
|
653 The default is |
|
654 \f(CWDW_DLC_STREAM_RELOCATIONS\fP . |
|
655 The |
|
656 \f(CWDW_DLC_STREAM_RELOCATIONS\fP |
|
657 are relocations in a binary stream (as used |
|
658 in a MIPS Elf object). |
|
659 |
|
660 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP |
|
661 are OR'd into flags |
|
662 to cause |
|
663 the same relocations to be expressed in an |
|
664 array of structures defined by libdwarf, |
|
665 which the caller of the relevant function |
|
666 (see below) must deal with appropriately. |
|
667 This method of expressing relocations allows |
|
668 the producer-application to easily produce |
|
669 assembler text output of debugging information. |
|
670 |
|
671 .in -4 |
|
672 .P |
|
673 The function \f(CWfunc\fP |
|
674 must be provided by the user of this library. |
|
675 Its prototype is: |
|
676 .DS |
|
677 \f(CWtypedef int (*Dwarf_Callback_Func_b)( |
|
678 char* name, |
|
679 int size, |
|
680 Dwarf_Unsigned type, |
|
681 Dwarf_Unsigned flags, |
|
682 Dwarf_Unsigned link, |
|
683 Dwarf_Unsigned info, |
|
684 Dwarf_Unsigned* sect_name_index, |
|
685 int* error) \fP |
|
686 .DE |
|
687 For each section in the object file that \f(CWlibdwarf\fP |
|
688 needs to create, it calls this function once, passing in |
|
689 the section \f(CWname\fP, the section \f(CWtype\fP, |
|
690 the section \f(CWflags\fP, the \f(CWlink\fP field, and |
|
691 the \f(CWinfo\fP field. For an Elf object file these values |
|
692 should be appropriate Elf section header values. |
|
693 For example, for relocation callbacks, the \f(CWlink\fP |
|
694 field is supposed to be set (by the app) to the index |
|
695 of the symtab section (the link field passed thru the |
|
696 callback must be ignored by the app). |
|
697 And, for relocation callbacks, the \f(CWinfo\fP field |
|
698 is passed as the elf section number of the section |
|
699 the relocations apply to. |
|
700 |
|
701 On success |
|
702 the user function should return the Elf section number of the |
|
703 newly created Elf section. |
|
704 .P |
|
705 On success, the function should also set the integer |
|
706 pointed to by \f(CWsect_name_index\fP to the |
|
707 Elf symbol number assigned in the Elf symbol table of the |
|
708 new Elf section. |
|
709 This symbol number is needed with relocations |
|
710 dependent on the relocation of this new section. |
|
711 .P |
|
712 For example, the \f(CW.debug_line\fP section's third |
|
713 data element (in a compilation unit) is the offset from the |
|
714 beginning of the \f(CW.debug_info\fP section of the compilation |
|
715 unit entry for this \f(CW.debug_line\fP set. |
|
716 The relocation entry in \f(CW.rel.debug_line\fP |
|
717 for this offset |
|
718 must have the relocation symbol index of the |
|
719 symbol \f(CW.debug_info\fP returned |
|
720 by the callback of that section-creation through |
|
721 the pointer \f(CWsect_name_index\fP. |
|
722 .P |
|
723 On failure, the function should return -1 and set the \f(CWerror\fP |
|
724 integer to an error code. |
|
725 .P |
|
726 Nothing in libdwarf actually depends on the section index |
|
727 returned being a real Elf section. |
|
728 The Elf section is simply useful for generating relocation |
|
729 records. |
|
730 Similarly, the Elf symbol table index returned thru |
|
731 the \f(CWsect_name_index\fP must simply be an index |
|
732 that can be used in relocations against this section. |
|
733 The application will probably want to note the |
|
734 values passed to this function in some form, even if |
|
735 no Elf file is being produced. |
|
736 |
|
737 Note that the \f(CWDwarf_Callback_Func_b() \fP form |
|
738 passes back the sect_name_index as a Dwarf_Unsigned. |
|
739 This is guaranteed large enough to hold a pointer. |
|
740 (the other functional interfaces have versions with |
|
741 the 'symbol index' as a Dwarf_Unsigned too. See below). |
|
742 |
|
743 If \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP |
|
744 is in use, then the symbol index is simply an arbitrary |
|
745 value (from the point of view of libdwarf) so the |
|
746 caller can put anything in it: |
|
747 a normal elf symbol index, |
|
748 a pointer to a struct (with arbitrary contents) |
|
749 (the caller must cast to/from Dwarf_Unsigned |
|
750 as appropriate), |
|
751 or some other kind of pointer or value. |
|
752 The values show up in the |
|
753 output of \f(CWdwarf_get_relocation_info()\fP |
|
754 (described below) and are not emitted anywhere else. |
|
755 |
|
756 .H 3 "dwarf_transform_to_disk_form()" |
|
757 |
|
758 .DS |
|
759 \f(CWDwarf_Signed dwarf_transform_to_disk_form( |
|
760 Dwarf_P_Debug dbg, |
|
761 Dwarf_Error* error) \fP |
|
762 .DE |
|
763 The function \f(CWdwarf_transform_to_disk_form() \fP does the actual |
|
764 conversion of the \f(CWDwarf\fP information provided so far, to the |
|
765 form that is |
|
766 normally written out as \f(CWElf\fP sections. |
|
767 In other words, |
|
768 once all DWARF information has been passed to \f(CWLibdwarf\fP, call |
|
769 \f(CWdwarf_transform_to_disk_form() \fP to transform all the accumulated |
|
770 data into byte streams. |
|
771 This includes turning relocation information |
|
772 into byte streams (and possibly relocation arrays). |
|
773 This function does not write anything to disk. If |
|
774 successful, it returns a count of the number of \f(CWElf\fP sections |
|
775 ready to be retrieved (and, normally, written to disk). |
|
776 In case of error, it returns |
|
777 \f(CWDW_DLV_NOCOUNT\fP. |
|
778 |
|
779 |
|
780 .H 3 "dwarf_get_section_bytes()" |
|
781 |
|
782 .DS |
|
783 \f(CWDwarf_Ptr dwarf_get_section_bytes( |
|
784 Dwarf_P_Debug dbg, |
|
785 Dwarf_Signed dwarf_section, |
|
786 Dwarf_Signed *elf_section_index, |
|
787 Dwarf_Unsigned *length, |
|
788 Dwarf_Error* error)\fP |
|
789 .DE |
|
790 The function \f(CWdwarf_get_section_bytes() \fP must be called repetitively, |
|
791 with the index \f(CWdwarf_section\fP starting at 0 and continuing for the |
|
792 number of sections |
|
793 returned by \f(CWdwarf_transform_to_disk_form() \fP. |
|
794 It returns \f(CWNULL\fP to indicate that there are no more sections of |
|
795 \f(CWDwarf\fP information. |
|
796 For each non-NULL return, the return value |
|
797 points to \f(CW*length\fP bytes of data that are normally |
|
798 added to the output |
|
799 object in \f(CWElf\fP section \f(CW*elf_section\fP by the producer application. |
|
800 It is illegal to call these in any order other than 0 thru N-1 where |
|
801 N is the number of dwarf sections |
|
802 returned by \f(CWdwarf_transform_to_disk_form() \fP. |
|
803 The \f(CWdwarf_section\fP |
|
804 number is actually ignored: the data is returned as if the |
|
805 caller passed in the correct dwarf_section numbers in the |
|
806 required sequence. |
|
807 The \f(CWerror\fP argument is not used. |
|
808 .P |
|
809 There is no requirement that the section bytes actually |
|
810 be written to an elf file. |
|
811 For example, consider the .debug_info section and its |
|
812 relocation section (the call back function would resulted in |
|
813 assigning 'section' numbers and the link field to tie these |
|
814 together (.rel.debug_info would have a link to .debug_info). |
|
815 One could examine the relocations, split the .debug_info |
|
816 data at relocation boundaries, emit byte streams (in hex) |
|
817 as assembler output, and at each relocation point, |
|
818 emit an assembler directive with a symbol name for the assembler. |
|
819 Examining the relocations is awkward though. |
|
820 It is much better to use \f(CWdwarf_get_section_relocation_info() \fP |
|
821 .P |
|
822 |
|
823 The memory space of the section byte stream is freed |
|
824 by the \f(CWdwarf_producer_finish() \fP call |
|
825 (or would be if the \f(CWdwarf_producer_finish() \fP |
|
826 was actually correct), along |
|
827 with all the other space in use with that Dwarf_P_Debug. |
|
828 |
|
829 .H 3 "dwarf_get_relocation_info_count()" |
|
830 .DS |
|
831 \f(CWint dwarf_get_relocation_info_count( |
|
832 Dwarf_P_Debug dbg, |
|
833 Dwarf_Unsigned *count_of_relocation_sections , |
|
834 int *drd_buffer_version, |
|
835 Dwarf_Error* error)\fP |
|
836 .DE |
|
837 The function \f(CWdwarf_get_relocation_info() \fP |
|
838 returns, thru the pointer \f(CWcount_of_relocation_sections\fP, the |
|
839 number of times that \f(CWdwarf_get_relocation_info() \fP |
|
840 should be called. |
|
841 |
|
842 The function \f(CWdwarf_get_relocation_info() \fP |
|
843 returns DW_DLV_OK if the call was successful (the |
|
844 \f(CWcount_of_relocation_sections\fP is therefore meaningful, |
|
845 though \f(CWcount_of_relocation_sections\fP |
|
846 could be zero). |
|
847 |
|
848 \f(CW*drd_buffer_version\fP |
|
849 is the value 2. |
|
850 If the structure pointed to by |
|
851 the \f(CW*reldata_buffer\fP |
|
852 changes this number will change. |
|
853 The application should verify that the number is |
|
854 the version it understands (that it matches |
|
855 the value of DWARF_DRD_BUFFER_VERSION (from libdwarf.h)). |
|
856 The value 1 version was never used in production |
|
857 MIPS libdwarf (version 1 did exist in source). |
|
858 |
|
859 It returns DW_DLV_NO_ENTRY if |
|
860 \f(CWcount_of_relocation_sections\fP is not meaningful |
|
861 because \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP was not |
|
862 passed in the |
|
863 \f(CWdwarf_producer_init() \fP |
|
864 (or |
|
865 \f(CWdwarf_producer_init_b() \fP ) call. |
|
866 |
|
867 It returns DW_DLV_ERROR if there was an error, |
|
868 in which case |
|
869 \f(CWcount_of_relocation_sections\fP is not meaningful. |
|
870 |
|
871 .H 3 "dwarf_get_relocation_info()" |
|
872 .DS |
|
873 \f(CWint dwarf_get_relocation_info( |
|
874 Dwarf_P_Debug dbg, |
|
875 Dwarf_Signed *elf_section_index, |
|
876 Dwarf_Signed *elf_section_index_link, |
|
877 Dwarf_Unsigned *relocation_buffer_count, |
|
878 Dwarf_Relocation_Data *reldata_buffer, |
|
879 Dwarf_Error* error)\fP |
|
880 .DE |
|
881 |
|
882 The function \f(CWdwarf_get_relocation_info() \fP |
|
883 should normally be called repetitively, |
|
884 for the number of relocation sections that |
|
885 \f(CWdwarf_get_relocation_info_count() \fP |
|
886 indicated exist. |
|
887 |
|
888 It returns \f(CWDW_DLV_OK\fP to indicate that |
|
889 valid values are returned thru the pointer arguments. |
|
890 The \f(CWerror\fP argument is not set. |
|
891 |
|
892 It returns DW_DLV_NO_ENTRY if there are no entries |
|
893 (the count of relocation arrays is zero.). |
|
894 The \f(CWerror\fP argument is not set. |
|
895 |
|
896 It returns \f(CWDW_DLV_ERROR\fP if there is an error. |
|
897 Calling \f(CWdwarf_get_relocation_info() \fP |
|
898 more than the number of times indicated by |
|
899 \f(CWdwarf_get_relocation_info_count() \fP |
|
900 (without an intervening call to |
|
901 \f(CWdwarf_reset_section_bytes() \fP ) |
|
902 results in a return of \f(CWDW_DLV_ERROR\fP once past |
|
903 the valid count. |
|
904 The \f(CWerror\fP argument is set to indicate the error. |
|
905 |
|
906 Now consider the returned-thru-pointer values for |
|
907 \f(CWDW_DLV_OK\fP . |
|
908 |
|
909 \f(CW*elf_section_index\fP |
|
910 is the 'elf section index' of the section implied by |
|
911 this group of relocations. |
|
912 |
|
913 |
|
914 \f(CW*elf_section_index_link\fP |
|
915 is the section index of the section that these |
|
916 relocations apply to. |
|
917 |
|
918 \f(CW*relocation_buffer_count\fP |
|
919 is the number of array entries of relocation information |
|
920 in the array pointed to by |
|
921 \f(CW*reldata_buffer\fP . |
|
922 |
|
923 |
|
924 \f(CW*reldata_buffer\fP |
|
925 points to an array of 'struct Dwarf_Relocation_Data_s' |
|
926 structures. |
|
927 |
|
928 The version 2 array information is as follows: |
|
929 |
|
930 .nf |
|
931 enum Dwarf_Rel_Type {dwarf_drt_none, |
|
932 dwarf_drt_data_reloc, |
|
933 dwarf_drt_segment_rel, |
|
934 dwarf_drt_first_of_length_pair, |
|
935 dwarf_drt_second_of_length_pair |
|
936 }; |
|
937 typedef struct Dwarf_Relocation_Data_s * Dwarf_Relocation_Data; |
|
938 struct Dwarf_Relocation_Data_s { |
|
939 unsigned char drd_type; /* contains Dwarf_Rel_Type */ |
|
940 unsigned char drd_length; /* typically 4 or 8 */ |
|
941 Dwarf_Unsigned drd_offset; /* where the data to reloc is */ |
|
942 Dwarf_Unsigned drd_symbol_index; |
|
943 }; |
|
944 |
|
945 .fi |
|
946 |
|
947 The \f(CWDwarf_Rel_Type\fP enum is encoded (via casts if necessary) |
|
948 into the single unsigned char \f(CWdrd_type\fP field to control |
|
949 the space used for this information (keep the space to 1 byte). |
|
950 |
|
951 The unsigned char \f(CWdrd_length\fP field |
|
952 holds the size in bytes of the field to be relocated. |
|
953 So for elf32 object formats with 32 bit apps, \f(CWdrd_length\fP |
|
954 will be 4. For objects with MIPS -64 contents, |
|
955 \f(CWdrd_length\fP will be 8. |
|
956 For some dwarf 64 bit environments, such as ia64, \f(CWdrd_length\fP |
|
957 is 4 for some relocations (file offsets, for example) |
|
958 and 8 for others (run time |
|
959 addresses, for example). |
|
960 |
|
961 If \f(CWdrd_type\fP is \f(CWdwarf_drt_none\fP, this is an unused slot |
|
962 and it should be ignored. |
|
963 |
|
964 If \f(CWdrd_type\fP is \f(CWdwarf_drt_data_reloc\fP |
|
965 this is an ordinary relocation. |
|
966 The relocation type means either |
|
967 (R_MIPS_64) or (R_MIPS_32) (or the like for |
|
968 the particular ABI. |
|
969 f(CWdrd_length\fP gives the length of the field to be relocated. |
|
970 \f(CWdrd_offset\fP is an offset (of the |
|
971 value to be relocated) in |
|
972 the section this relocation stuff is linked to. |
|
973 \f(CWdrd_symbol_index\fP is the symbol index (if elf symbol |
|
974 indices were provided) or the handle to arbitrary |
|
975 information (if that is what the caller passed in |
|
976 to the relocation-creating dwarf calls) of the symbol |
|
977 that the relocation is relative to. |
|
978 |
|
979 |
|
980 When \f(CWdrd_type\fP is \f(CWdwarf_drt_first_of_length_pair\fP |
|
981 the next data record will be \f(CWdrt_second_of_length_pair\fP |
|
982 and the \f(CWdrd_offset\fP of the two data records will match. |
|
983 The relevant 'offset' in the section this reloc applies to |
|
984 should contain a symbolic pair like |
|
985 .nf |
|
986 .in +4 |
|
987 .word second_symbol - first_symbol |
|
988 .in -4 |
|
989 .fi |
|
990 to generate a length. |
|
991 \f(CWdrd_length\fP gives the length of the field to be relocated. |
|
992 |
|
993 \f(CWdrt_segment_rel\fP means (R_MIPS_SCN_DISP) |
|
994 is the real relocation (R_MIPS_SCN_DISP applies to |
|
995 exception tables and this part may need further work). |
|
996 \f(CWdrd_length\fP gives the length of the field to be relocated. |
|
997 |
|
998 .P |
|
999 The memory space of the section byte stream is freed |
|
1000 by the \f(CWdwarf_producer_finish() \fP call |
|
1001 (or would be if the \f(CWdwarf_producer_finish() \fP |
|
1002 was actually correct), along |
|
1003 with all the other space in use with that Dwarf_P_Debug. |
|
1004 |
|
1005 .H 3 "dwarf_reset_section_bytes()" |
|
1006 |
|
1007 .DS |
|
1008 \f(CWvoid dwarf_reset_section_bytes( |
|
1009 Dwarf_P_Debug dbg |
|
1010 ) \fP |
|
1011 .DE |
|
1012 The function \f(CWdwarf_reset_section_bytes() \fP |
|
1013 is used to reset the internal information so that |
|
1014 \f(CWdwarf_get_section_bytes() \fP will begin (on the next |
|
1015 call) at the initial dwarf section again. |
|
1016 It also resets so that calls to |
|
1017 \f(CWdwarf_get_relocation_info() \fP |
|
1018 will begin again at the initial array of relocation information. |
|
1019 |
|
1020 Some dwarf producers need to be able to run thru |
|
1021 the \f(CWdwarf_get_section_bytes()\fP |
|
1022 and/or |
|
1023 the \f(CWdwarf_get_relocation_info()\fP |
|
1024 calls more than once and this call makes additional |
|
1025 passes possible. |
|
1026 The set of Dwarf_Ptr values returned is identical to the |
|
1027 set returned by the first pass. |
|
1028 It is acceptable to call this before finishing a pass |
|
1029 of \f(CWdwarf_get_section_bytes()\fP |
|
1030 or |
|
1031 \f(CWdwarf_get_relocation_info()\fP |
|
1032 calls. |
|
1033 No errors are possible as this just resets some |
|
1034 internal pointers. |
|
1035 It is unwise to call this before |
|
1036 \f(CWdwarf_transform_to_disk_form() \fP has been called. |
|
1037 .P |
|
1038 |
|
1039 .H 3 "dwarf_producer_finish()" |
|
1040 .DS |
|
1041 \f(CWDwarf_Unsigned dwarf_producer_finish( |
|
1042 Dwarf_P_Debug dbg, |
|
1043 Dwarf_Error* error) \fP |
|
1044 .DE |
|
1045 The function \f(CWdwarf_producer_finish() \fP should be called after all |
|
1046 the bytes of data have been copied somewhere |
|
1047 (normally the bytes are written to disk). |
|
1048 It frees all dynamic space |
|
1049 allocated for \f(CWdbg\fP, include space for the structure pointed to by |
|
1050 \f(CWdbg\fP. |
|
1051 This should not be called till the data have been |
|
1052 copied or written |
|
1053 to disk or are no longer of interest. |
|
1054 It returns non-zero if successful, and \f(CWDW_DLV_NOCOUNT\fP |
|
1055 if there is an error. |
|
1056 |
|
1057 .H 2 "Debugging Information Entry Creation" |
|
1058 The functions in this section add new \f(CWDIE\fPs to the object, |
|
1059 and also the relationships among the \f(CWDIE\fP to be specified |
|
1060 by linking them up as parents, children, left or right siblings |
|
1061 of each other. |
|
1062 In addition, there is a function that marks the |
|
1063 root of the graph thus created. |
|
1064 |
|
1065 .H 3 "dwarf_add_die_to_debug()" |
|
1066 .DS |
|
1067 \f(CWDwarf_Unsigned dwarf_add_die_to_debug( |
|
1068 Dwarf_P_Debug dbg, |
|
1069 Dwarf_P_Die first_die, |
|
1070 Dwarf_Error *error) \fP |
|
1071 .DE |
|
1072 The function \f(CWdwarf_add_die_to_debug() \fP indicates to \f(CWLibdwarf\fP |
|
1073 the root \f(CWDIE\fP of the \f(CWDIE\fP graph that has been built so |
|
1074 far. |
|
1075 It is intended to mark the compilation-unit \f(CWDIE\fP for the |
|
1076 object represented by \f(CWdbg\fP. |
|
1077 The root \f(CWDIE\fP is specified |
|
1078 by \f(CWfirst_die\fP. |
|
1079 |
|
1080 It returns \f(CW0\fP on success, and \f(CWDW_DLV_NOCOUNT\fP on error. |
|
1081 |
|
1082 .H 3 "dwarf_new_die()" |
|
1083 .DS |
|
1084 \f(CWDwarf_P_Die dwarf_new_die( |
|
1085 Dwarf_P_Debug dbg, |
|
1086 Dwarf_Tag new_tag, |
|
1087 Dwarf_P_Die parent, |
|
1088 Dwarf_P_Die child, |
|
1089 Dwarf_P_Die left_sibling, |
|
1090 Dwarf_P_Die right_sibling, |
|
1091 Dwarf_Error *error) \fP |
|
1092 .DE |
|
1093 The function \f(CWdwarf_new_die() \fP creates a new \f(CWDIE\fP with |
|
1094 its parent, child, left sibling, and right sibling \f(CWDIE\fPs |
|
1095 specified by \f(CWparent\fP, \f(CWchild\fP, \f(CWleft_sibling\fP, |
|
1096 and \f(CWright_sibling\fP, respectively. |
|
1097 There is no requirement |
|
1098 that all of these \f(CWDIE\fPs be specified, i.e. any of these |
|
1099 descriptors may be \f(CWNULL\fP. |
|
1100 If none is specified, this will |
|
1101 be an isolated \f(CWDIE\fP. |
|
1102 A \f(CWDIE\fP is |
|
1103 transformed to disk form by \f(CWdwarf_transform_to_disk_form() \fP |
|
1104 only if there is a path from |
|
1105 the \f(CWDIE\fP specified by \f(CWdwarf_add_die_to_debug\fP to it. |
|
1106 This function returns \f(CWDW_DLV_BADADDR\fP on error. |
|
1107 |
|
1108 \f(CWnew_tag\fP is the tag which is given to the new \f(CWDIE\fP. |
|
1109 \f(CWparent\fP, \f(CWchild\fP, \f(CWleft_sibling\fP, and |
|
1110 \f(CWright_sibling\fP are pointers to establish links to existing |
|
1111 \f(CWDIE\fPs. Only one of \f(CWparent\fP, \f(CWchild\fP, |
|
1112 \f(CWleft_sibling\fP, and \f(CWright_sibling\fP may be non-NULL. |
|
1113 If \f(CWparent\fP (\f(CWchild\fP) is given, the \f(CWDIE\fP is |
|
1114 linked into the list after (before) the \f(CWDIE\fP pointed to. |
|
1115 If \f(CWleft_sibling\fP (\f(CWright_sibling\fP) is given, the |
|
1116 \f(CWDIE\fP is linked into the list after (before) the \f(CWDIE\fP |
|
1117 pointed to. |
|
1118 |
|
1119 To add attributes to the new \f(CWDIE\fP, use the \f(CWAttribute Creation\fP |
|
1120 functions defined in the next section. |
|
1121 |
|
1122 .H 3 "dwarf_die_link()" |
|
1123 .DS |
|
1124 \f(CWDwarf_P_Die dwarf_die_link( |
|
1125 Dwarf_P_Die die, |
|
1126 Dwarf_P_Die parent, |
|
1127 Dwarf_P_Die child, |
|
1128 Dwarf_P_Die left-sibling, |
|
1129 Dwarf_P_Die right_sibling, |
|
1130 Dwarf_Error *error) \fP |
|
1131 .DE |
|
1132 The function \f(CWdwarf_die_link() \fP links an existing \f(CWDIE\fP |
|
1133 described by the given \f(CWdie\fP to other existing \f(CWDIE\fPs. |
|
1134 The given \f(CWdie\fP can be linked to a parent \f(CWDIE\fP, a child |
|
1135 \f(CWDIE\fP, a left sibling \f(CWDIE\fP, or a right sibling \f(CWDIE\fP |
|
1136 by specifying non-NULL \f(CWparent\fP, \f(CWchild\fP, \f(CWleft_sibling\fP, |
|
1137 and \f(CWright_sibling\fP \f(CWDwarf_P_Die\fP descriptors. |
|
1138 It returns |
|
1139 the given \f(CWDwarf_P_Die\fP descriptor, \f(CWdie\fP, on success, |
|
1140 and \f(CWDW_DLV_BADADDR\fP on error. |
|
1141 |
|
1142 Only one of \f(CWparent\fP, \f(CWchild\fP, \f(CWleft_sibling\fP, |
|
1143 and \f(CWright_sibling\fP may be non-NULL. |
|
1144 If \f(CWparent\fP |
|
1145 (\f(CWchild\fP) is given, the \f(CWDIE\fP is linked into the list |
|
1146 after (before) the \f(CWDIE\fP pointed to. |
|
1147 If \f(CWleft_sibling\fP |
|
1148 (\f(CWright_sibling\fP) is given, the \f(CWDIE\fP is linked into |
|
1149 the list after (before) the \f(CWDIE\fP pointed to. |
|
1150 Non-NULL links |
|
1151 overwrite the corresponding links the given \f(CWdie\fP may have |
|
1152 had before the call to \f(CWdwarf_die_link() \fP. |
|
1153 |
|
1154 .H 2 "Attribute Creation" |
|
1155 The functions in this section add attributes to a \f(CWDIE\fP. |
|
1156 These functions return a \f(CWDwarf_P_Attribute\fP descriptor |
|
1157 that represents the attribute added to the given \f(CWDIE\fP. |
|
1158 In most cases the return value is only useful to determine if |
|
1159 an error occurred. |
|
1160 |
|
1161 Some of the attributes have values that are relocatable. |
|
1162 They |
|
1163 need a symbol with respect to which the linker will perform |
|
1164 relocation. |
|
1165 This symbol is specified by means of an index into |
|
1166 the Elf symbol table for the object |
|
1167 (of course, the symbol index can be more general than an index). |
|
1168 |
|
1169 .H 3 "dwarf_add_AT_location_expr()" |
|
1170 .DS |
|
1171 \f(CWDwarf_P_Attribute dwarf_add_AT_location_expr( |
|
1172 Dwarf_P_Debug dbg, |
|
1173 Dwarf_P_Die ownerdie, |
|
1174 Dwarf_Half attr, |
|
1175 Dwarf_P_Expr loc_expr, |
|
1176 Dwarf_Error *error) \fP |
|
1177 .DE |
|
1178 The function \f(CWdwarf_add_AT_location_expr() \fP adds the attribute |
|
1179 specified by \f(CWattr\fP to the \f(CWDIE\fP descriptor given by |
|
1180 \f(CWownerdie\fP. The attribute should be one that has a location |
|
1181 expression as its value. The location expression that is the value |
|
1182 is represented by the \f(CWDwarf_P_Expr\fP descriptor \f(CWloc_expr\fP. |
|
1183 It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute |
|
1184 given, on success. On error it returns \f(CWDW_DLV_BADADDR\fP. |
|
1185 |
|
1186 .H 3 "dwarf_add_AT_name()" |
|
1187 .DS |
|
1188 \f(CWDwarf_P_Attribute dwarf_add_AT_name( |
|
1189 Dwarf_P_Die ownerdie, |
|
1190 char *name, |
|
1191 Dwarf_Error *error) \fP |
|
1192 .DE |
|
1193 The function \f(CWdwarf_add_AT_name() \fP adds the string specified |
|
1194 by \f(CWname\fP as the value of the \f(CWDW_AT_name\fP attribute |
|
1195 for the given \f(CWDIE\fP, \f(CWownerdie\fP. It returns the |
|
1196 \f(CWDwarf_P_attribute\fP descriptor for the \f(CWDW_AT_name\fP |
|
1197 attribute on success. On error, it returns \f(CWDW_DLV_BADADDR\fP. |
|
1198 |
|
1199 .H 3 "dwarf_add_AT_comp_dir()" |
|
1200 .DS |
|
1201 \f(CWDwarf_P_Attribute dwarf_add_AT_comp_dir( |
|
1202 Dwarf_P_Die ownerdie, |
|
1203 char *current_working_directory, |
|
1204 Dwarf_Error *error) \fP |
|
1205 .DE |
|
1206 The function \f(CWdwarf_add_AT_comp_dir() \fP adds the string given by |
|
1207 \f(CWcurrent_working_directory\fP as the value of the \f(CWDW_AT_comp_dir\fP |
|
1208 attribute for the \f(CWDIE\fP described by the given \f(CWownerdie\fP. |
|
1209 It returns the \f(CWDwarf_P_Attribute\fP for this attribute on success. |
|
1210 On error, it returns \f(CWDW_DLV_BADADDR\fP. |
|
1211 |
|
1212 .H 3 "dwarf_add_AT_producer()" |
|
1213 .DS |
|
1214 \f(CWDwarf_P_Attribute dwarf_add_AT_producer( |
|
1215 Dwarf_P_Die ownerdie, |
|
1216 char *producer_string, |
|
1217 Dwarf_Error *error) \fP |
|
1218 .DE |
|
1219 The function \f(CWdwarf_add_AT_producer() \fP adds the string given by |
|
1220 \f(CWproducer_string\fP as the value of the \f(CWDW_AT_producer\fP |
|
1221 attribute for the \f(CWDIE\fP given by \f(CWownerdie\fP. It returns |
|
1222 the \f(CWDwarf_P_Attribute\fP descriptor representing this attribute |
|
1223 on success. On error, it returns \f(CWDW_DLV_BADADDR\fP. |
|
1224 |
|
1225 .H 3 "dwarf_add_AT_const_value_signedint()" |
|
1226 .DS |
|
1227 \f(CWDwarf_P_Attribute dwarf_add_AT_const_value_signedint( |
|
1228 Dwarf_P_Die ownerdie, |
|
1229 Dwarf_Signed signed_value, |
|
1230 Dwarf_Error *error) \fP |
|
1231 .DE |
|
1232 The function \f(CWdwarf_add_AT_const_value_signedint() \fP adds the |
|
1233 given \f(CWDwarf_Signed\fP value \f(CWsigned_value\fP as the value |
|
1234 of the \f(CWDW_AT_const_value\fP attribute for the \f(CWDIE\fP |
|
1235 described by the given \f(CWownerdie\fP. It returns the |
|
1236 \f(CWDwarf_P_Attribute\fP descriptor for this attribute on success. |
|
1237 On error, it returns \f(CWDW_DLV_BADADDR\fP. |
|
1238 |
|
1239 .H 3 "dwarf_add_AT_const_value_unsignedint()" |
|
1240 .DS |
|
1241 \f(CWDwarf_P_Attribute dwarf_add_AT_const_value_unsignedint( |
|
1242 Dwarf_P_Die ownerdie, |
|
1243 Dwarf_Unsigned unsigned_value, |
|
1244 Dwarf_Error *error) \fP |
|
1245 .DE |
|
1246 The function \f(CWdwarf_add_AT_const_value_unsignedint() \fP adds the |
|
1247 given \f(CWDwarf_Unsigned\fP value \f(CWunsigned_value\fP as the value |
|
1248 of the \f(CWDW_AT_const_value\fP attribute for the \f(CWDIE\fP described |
|
1249 by the given \f(CWownerdie\fP. It returns the \f(CWDwarf_P_Attribute\fP |
|
1250 descriptor for this attribute on success. On error, it returns |
|
1251 \f(CWDW_DLV_BADADDR\fP. |
|
1252 |
|
1253 .H 3 "dwarf_add_AT_const_value_string()" |
|
1254 .DS |
|
1255 \f(CWDwarf_P_Attribute dwarf_add_AT_const_value_string( |
|
1256 Dwarf_P_Die ownerdie, |
|
1257 char *string_value, |
|
1258 Dwarf_Error *error) \fP |
|
1259 .DE |
|
1260 The function \f(CWdwarf_add_AT_const_value_string() \fP adds the |
|
1261 string value given by \f(CWstring_value\fP as the value of the |
|
1262 \f(CWDW_AT_const_value\fP attribute for the \f(CWDIE\fP described |
|
1263 by the given \f(CWownerdie\fP. It returns the \f(CWDwarf_P_Attribute\fP |
|
1264 descriptor for this attribute on success. On error, it returns |
|
1265 \f(CWDW_DLV_BADADDR\fP. |
|
1266 |
|
1267 .H 3 "dwarf_add_AT_targ_address()" |
|
1268 .DS |
|
1269 \f(CWDwarf_P_Attribute dwarf_add_AT_targ_address( |
|
1270 Dwarf_P_Debug dbg, |
|
1271 Dwarf_P_Die ownerdie, |
|
1272 Dwarf_Half attr, |
|
1273 Dwarf_Unsigned pc_value, |
|
1274 Dwarf_Signed sym_index, |
|
1275 Dwarf_Error *error) \fP |
|
1276 .DE |
|
1277 The function \f(CWdwarf_add_AT_targ_address() \fP adds an attribute that |
|
1278 belongs to the "address" class to the die specified by \f(CWownerdie\fP. |
|
1279 The attribute is specified by \f(CWattr\fP, and the object that the |
|
1280 \f(CWDIE\fP belongs to is specified by \f(CWdbg\fP. The relocatable |
|
1281 address that is the value of the attribute is specified by \f(CWpc_value\fP. |
|
1282 The symbol to be used for relocation is specified by the \f(CWsym_index\fP, |
|
1283 which is the index of the symbol in the Elf symbol table. |
|
1284 |
|
1285 It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute |
|
1286 on success, and \f(CWDW_DLV_BADADDR\fP on error. |
|
1287 |
|
1288 |
|
1289 .H 3 "dwarf_add_AT_targ_address_b()" |
|
1290 .DS |
|
1291 \f(CWDwarf_P_Attribute dwarf_add_AT_targ_address_b( |
|
1292 Dwarf_P_Debug dbg, |
|
1293 Dwarf_P_Die ownerdie, |
|
1294 Dwarf_Half attr, |
|
1295 Dwarf_Unsigned pc_value, |
|
1296 Dwarf_Unsigned sym_index, |
|
1297 Dwarf_Error *error) \fP |
|
1298 .DE |
|
1299 The function \f(CWdwarf_add_AT_targ_address_b() \fP |
|
1300 is identical to \f(CWdwarf_add_AT_targ_address_b() \fP |
|
1301 except that \f(CWsym_index() \fP is guaranteed to |
|
1302 be large enough that it can contain a pointer to |
|
1303 arbitrary data (so the caller can pass in a real elf |
|
1304 symbol index, an arbitrary number, or a pointer |
|
1305 to arbitrary data). |
|
1306 The ability to pass in a pointer thru \f(CWsym_index() \fP |
|
1307 is only usable with |
|
1308 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP. |
|
1309 |
|
1310 The \f(CWpc_value\fP |
|
1311 is put into the section stream output and |
|
1312 the \f(CWsym_index\fP is applied to the relocation |
|
1313 information. |
|
1314 |
|
1315 Do not use this function for attr \f(CWDW_AT_high_pc\fP |
|
1316 if the value to be recorded is an offset (not a pc) |
|
1317 [ use \f(CWdwarf_add_AT_unsigned_const()\fP (for example) |
|
1318 instead]. |
|
1319 |
|
1320 .H 3 "dwarf_add_AT_dataref()" |
|
1321 .DS |
|
1322 \f(CWDwarf_P_Attribute dwarf_add_AT_dataref( |
|
1323 Dwarf_P_Debug dbg, |
|
1324 Dwarf_P_Die ownerdie, |
|
1325 Dwarf_Half attr, |
|
1326 Dwarf_Unsigned pc_value, |
|
1327 Dwarf_Unsigned sym_index, |
|
1328 Dwarf_Error *error) \fP |
|
1329 .DE |
|
1330 This is very similar to \f(CWdwarf_add_AT_targ_address_b() \fP |
|
1331 but results in a different FORM (results in DW_FORM_data4 |
|
1332 or DW_FORM_data8). |
|
1333 |
|
1334 Useful for adding relocatable addresses in location lists. |
|
1335 |
|
1336 \f(CWsym_index() \fP is guaranteed to |
|
1337 be large enough that it can contain a pointer to |
|
1338 arbitrary data (so the caller can pass in a real elf |
|
1339 symbol index, an arbitrary number, or a pointer |
|
1340 to arbitrary data). |
|
1341 The ability to pass in a pointer thru \f(CWsym_index() \fP |
|
1342 is only usable with |
|
1343 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP. |
|
1344 |
|
1345 The \f(CWpc_value\fP |
|
1346 is put into the section stream output and |
|
1347 the \f(CWsym_index\fP is applied to the relocation |
|
1348 information. |
|
1349 |
|
1350 Do not use this function for \f(CWDW_AT_high_pc\fP, use |
|
1351 \f(CWdwarf_add_AT_unsigned_const()\fP [ (for example) |
|
1352 if the value to be recorded is |
|
1353 an offset of \f(CWDW_AT_low_pc\fP] |
|
1354 or \f(CWdwarf_add_AT_targ_address_b()\fP [ if the value |
|
1355 to be recorded is an address]. |
|
1356 |
|
1357 .H 3 "dwarf_add_AT_ref_address()" |
|
1358 .DS |
|
1359 \f(CWDwarf_P_Attribute dwarf_add_AT_ref_address( |
|
1360 Dwarf_P_Debug dbg, |
|
1361 Dwarf_P_Die ownerdie, |
|
1362 Dwarf_Half attr, |
|
1363 Dwarf_Unsigned pc_value, |
|
1364 Dwarf_Unsigned sym_index, |
|
1365 Dwarf_Error *error) \fP |
|
1366 .DE |
|
1367 |
|
1368 This is very similar to \f(CWdwarf_add_AT_targ_address_b() \fP |
|
1369 but results in a different FORM (results in \f(CWDW_FORM_ref_addr\fP |
|
1370 being generated). |
|
1371 |
|
1372 Useful for \f(CWDW_AT_type\fP and \f(CWDW_AT_import\fP attributes. |
|
1373 |
|
1374 \f(CWsym_index() \fP is guaranteed to |
|
1375 be large enough that it can contain a pointer to |
|
1376 arbitrary data (so the caller can pass in a real elf |
|
1377 symbol index, an arbitrary number, or a pointer |
|
1378 to arbitrary data). |
|
1379 The ability to pass in a pointer thru \f(CWsym_index() \fP |
|
1380 is only usable with |
|
1381 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP. |
|
1382 |
|
1383 The \f(CWpc_value\fP |
|
1384 is put into the section stream output and |
|
1385 the \f(CWsym_index\fP is applied to the relocation |
|
1386 information. |
|
1387 |
|
1388 Do not use this function for \f(CWDW_AT_high_pc\fP. |
|
1389 |
|
1390 |
|
1391 .H 3 "dwarf_add_AT_unsigned_const()" |
|
1392 .DS |
|
1393 \f(CWDwarf_P_Attribute dwarf_add_AT_unsigned_const( |
|
1394 Dwarf_P_Debug dbg, |
|
1395 Dwarf_P_Die ownerdie, |
|
1396 Dwarf_Half attr, |
|
1397 Dwarf_Unsigned value, |
|
1398 Dwarf_Error *error) \fP |
|
1399 .DE |
|
1400 The function \f(CWdwarf_add_AT_unsigned_const() \fP adds an attribute |
|
1401 with a \f(CWDwarf_Unsigned\fP value belonging to the "constant" class, |
|
1402 to the \f(CWDIE\fP specified by \f(CWownerdie\fP. The object that |
|
1403 the \f(CWDIE\fP belongs to is specified by \f(CWdbg\fP. The attribute |
|
1404 is specified by \f(CWattr\fP, and its value is specified by \f(CWvalue\fP. |
|
1405 |
|
1406 It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute |
|
1407 on success, and \f(CWDW_DLV_BADADDR\fP on error. |
|
1408 |
|
1409 .H 3 "dwarf_add_AT_signed_const()" |
|
1410 .DS |
|
1411 \f(CWDwarf_P_Attribute dwarf_add_AT_signed_const( |
|
1412 Dwarf_P_Debug dbg, |
|
1413 Dwarf_P_Die ownerdie, |
|
1414 Dwarf_Half attr, |
|
1415 Dwarf_Signed value, |
|
1416 Dwarf_Error *error) \fP |
|
1417 .DE |
|
1418 The function \f(CWdwarf_add_AT_signed_const() \fP adds an attribute |
|
1419 with a \f(CWDwarf_Signed\fP value belonging to the "constant" class, |
|
1420 to the \f(CWDIE\fP specified by \f(CWownerdie\fP. The object that |
|
1421 the \f(CWDIE\fP belongs to is specified by \f(CWdbg\fP. The attribute |
|
1422 is specified by \f(CWattr\fP, and its value is specified by \f(CWvalue\fP. |
|
1423 |
|
1424 It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute |
|
1425 on success, and \f(CWDW_DLV_BADADDR\fP on error. |
|
1426 |
|
1427 .H 3 "dwarf_add_AT_reference()" |
|
1428 .DS |
|
1429 \f(CWDwarf_P_Attribute dwarf_add_AT_reference( |
|
1430 Dwarf_P_Debug dbg, |
|
1431 Dwarf_P_Die ownerdie, |
|
1432 Dwarf_Half attr, |
|
1433 Dwarf_P_Die otherdie, |
|
1434 Dwarf_Error *error)\fP |
|
1435 .DE |
|
1436 The function \f(CWdwarf_add_AT_reference()\fP adds an attribute |
|
1437 with a value that is a reference to another \f(CWDIE\fP in the |
|
1438 same compilation-unit to the \f(CWDIE\fP specified by \f(CWownerdie\fP. |
|
1439 The object that the \f(CWDIE\fP belongs to is specified by \f(CWdbg\fP. |
|
1440 The attribute is specified by \f(CWattr\fP, and the other \f(CWDIE\fP |
|
1441 being referred to is specified by \f(CWotherdie\fP. |
|
1442 |
|
1443 This cannot generate DW_FORM_ref_addr references to |
|
1444 \f(CWDIE\fPs in other compilation units. |
|
1445 |
|
1446 It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute |
|
1447 on success, and \f(CWDW_DLV_BADADDR\fP on error. |
|
1448 |
|
1449 .H 3 "dwarf_add_AT_flag()" |
|
1450 .DS |
|
1451 \f(CWDwarf_P_Attribute dwarf_add_AT_flag( |
|
1452 Dwarf_P_Debug dbg, |
|
1453 Dwarf_P_Die ownerdie, |
|
1454 Dwarf_Half attr, |
|
1455 Dwarf_Small flag, |
|
1456 Dwarf_Error *error)\fP |
|
1457 .DE |
|
1458 The function \f(CWdwarf_add_AT_flag()\fP adds an attribute with |
|
1459 a \f(CWDwarf_Small\fP value belonging to the "flag" class, to the |
|
1460 \f(CWDIE\fP specified by \f(CWownerdie\fP. The object that the |
|
1461 \f(CWDIE\fP belongs to is specified by \f(CWdbg\fP. The attribute |
|
1462 is specified by \f(CWattr\fP, and its value is specified by \f(CWflag\fP. |
|
1463 |
|
1464 It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute |
|
1465 on success, and \f(CWDW_DLV_BADADDR\fP on error. |
|
1466 |
|
1467 .H 3 "dwarf_add_AT_string()" |
|
1468 .DS |
|
1469 \f(CWDwarf_P_Attribute dwarf_add_AT_string( |
|
1470 Dwarf_P_Debug dbg, |
|
1471 Dwarf_P_Die ownerdie, |
|
1472 Dwarf_Half attr, |
|
1473 char *string, |
|
1474 Dwarf_Error *error)\fP |
|
1475 .DE |
|
1476 The function \f(CWdwarf_add_AT_string()\fP adds an attribute with a |
|
1477 value that is a character string to the \f(CWDIE\fP specified by |
|
1478 \f(CWownerdie\fP. The object that the \f(CWDIE\fP belongs to is |
|
1479 specified by \f(CWdbg\fP. The attribute is specified by \f(CWattr\fP, |
|
1480 and its value is pointed to by \f(CWstring\fP. |
|
1481 |
|
1482 It returns the \f(CWDwarf_P_Attribute\fP descriptor for the attribute |
|
1483 on success, and \f(CWDW_DLV_BADADDR\fP on error. |
|
1484 |
|
1485 .H 2 "Expression Creation" |
|
1486 The following functions are used to convert location expressions into |
|
1487 blocks so that attributes with values that are location expressions |
|
1488 can store their values as a \f(CWDW_FORM_blockn\fP value. This is for |
|
1489 both .debug_info and .debug_loc expression blocks. |
|
1490 |
|
1491 To create an expression, first call \f(CWdwarf_new_expr()\fP to get |
|
1492 a \f(CWDwarf_P_Expr\fP descriptor that can be used to build up the |
|
1493 block containing the location expression. Then insert the parts of |
|
1494 the expression in prefix order (exactly the order they would be |
|
1495 interpreted in in an expression interpreter). The bytes of the |
|
1496 expression are then built-up as specified by the user. |
|
1497 |
|
1498 .H 3 "dwarf_new_expr()" |
|
1499 .DS |
|
1500 \f(CWDwarf_Expr dwarf_new_expr( |
|
1501 Dwarf_P_Debug dbg, |
|
1502 Dwarf_Error *error)\fP |
|
1503 .DE |
|
1504 The function \f(CWdwarf_new_expr()\fP creates a new expression area |
|
1505 in which a location expression stream can be created. It returns |
|
1506 a \f(CWDwarf_P_Expr\fP descriptor that can be used to add operators |
|
1507 to build up a location expression. It returns \f(CWNULL\fP on error. |
|
1508 |
|
1509 .H 3 "dwarf_add_expr_gen()" |
|
1510 .DS |
|
1511 \f(CWDwarf_Unsigned dwarf_add_expr_gen( |
|
1512 Dwarf_P_Expr expr, |
|
1513 Dwarf_Small opcode, |
|
1514 Dwarf_Unsigned val1, |
|
1515 Dwarf_Unsigned val2, |
|
1516 Dwarf_Error *error)\fP |
|
1517 .DE |
|
1518 The function \f(CWdwarf_add_expr_gen()\fP takes an operator specified |
|
1519 by \f(CWopcode\fP, along with up to 2 operands specified by \f(CWval1\fP, |
|
1520 and \f(CWval2\fP, converts it into the \f(CWDwarf\fP representation and |
|
1521 appends the bytes to the byte stream being assembled for the location |
|
1522 expression represented by \f(CWexpr\fP. The first operand, if present, |
|
1523 to \f(CWopcode\fP is in \f(CWval1\fP, and the second operand, if present, |
|
1524 is in \f(CWval2\fP. Both the operands may actually be signed or unsigned |
|
1525 depending on \f(CWopcode\fP. It returns the number of bytes in the byte |
|
1526 stream for \f(CWexpr\fP currently generated, i.e. after the addition of |
|
1527 \f(CWopcode\fP. It returns \f(CWDW_DLV_NOCOUNT\fP on error. |
|
1528 |
|
1529 The function \f(CWdwarf_add_expr_gen()\fP works for all opcodes except |
|
1530 those that have a target address as an operand. This is because it does |
|
1531 not set up a relocation record that is needed when target addresses are |
|
1532 involved. |
|
1533 |
|
1534 .H 3 "dwarf_add_expr_addr()" |
|
1535 .DS |
|
1536 \f(CWDwarf_Unsigned dwarf_add_expr_addr( |
|
1537 Dwarf_P_Expr expr, |
|
1538 Dwarf_Unsigned address, |
|
1539 Dwarf_Signed sym_index, |
|
1540 Dwarf_Error *error)\fP |
|
1541 .DE |
|
1542 The function \f(CWdwarf_add_expr_addr()\fP is used to add the |
|
1543 \f(CWDW_OP_addr\fP opcode to the location expression represented |
|
1544 by the given \f(CWDwarf_P_Expr\fP descriptor, \f(CWexpr\fP. The |
|
1545 value of the relocatable address is given by \f(CWaddress\fP. |
|
1546 The symbol to be used for relocation is given by \f(CWsym_index\fP, |
|
1547 which is the index of the symbol in the Elf symbol table. It returns |
|
1548 the number of bytes in the byte stream for \f(CWexpr\fP currently |
|
1549 generated, i.e. after the addition of the \f(CWDW_OP_addr\fP operator. |
|
1550 It returns \f(CWDW_DLV_NOCOUNT\fP on error. |
|
1551 |
|
1552 .H 3 "dwarf_add_expr_addr_b()" |
|
1553 .DS |
|
1554 \f(CWDwarf_Unsigned dwarf_add_expr_addr_b( |
|
1555 Dwarf_P_Expr expr, |
|
1556 Dwarf_Unsigned address, |
|
1557 Dwarf_Unsigned sym_index, |
|
1558 Dwarf_Error *error)\fP |
|
1559 .DE |
|
1560 The function \f(CWdwarf_add_expr_addr_f()\fP is |
|
1561 identical to \f(CWdwarf_add_expr_addr()\fP |
|
1562 except that \f(CWsym_index() \fP is guaranteed to |
|
1563 be large enough that it can contain a pointer to |
|
1564 arbitrary data (so the caller can pass in a real elf |
|
1565 symbol index, an arbitrary number, or a pointer |
|
1566 to arbitrary data). |
|
1567 The ability to pass in a pointer thru \f(CWsym_index() \fP |
|
1568 is only usable with |
|
1569 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP. |
|
1570 |
|
1571 |
|
1572 |
|
1573 .H 3 "dwarf_expr_current_offset()" |
|
1574 .DS |
|
1575 \f(CWDwarf_Unsigned dwarf_expr_current_offset( |
|
1576 Dwarf_P_Expr expr, |
|
1577 Dwarf_Error *error)\fP |
|
1578 .DE |
|
1579 The function \f(CWdwarf_expr_current_offset()\fP returns the number |
|
1580 of bytes currently in the byte stream for the location expression |
|
1581 represented by the given \fCW(Dwarf_P_Expr\fP descriptor, \f(CWexpr\fP. |
|
1582 It returns \f(CWDW_DLV_NOCOUNT\fP on error. |
|
1583 |
|
1584 .H 3 "dwarf_expr_into_block()" |
|
1585 .DS |
|
1586 \f(CWDwarf_Addr dwarf_expr_into_block( |
|
1587 Dwarf_P_Expr expr, |
|
1588 Dwarf_Unsigned *length, |
|
1589 Dwarf_Error *error)\fP |
|
1590 .DE |
|
1591 The function \f(CWdwarf_expr_into_block()\fP returns the address |
|
1592 of the start of the byte stream generated for the location expression |
|
1593 represented by the given \f(CWDwarf_P_Expr\fP descriptor, \f(CWexpr\fP. |
|
1594 The length of the byte stream is returned in the location pointed to |
|
1595 by \f(CWlength\fP. It returns \f(CWDW_DLV_BADADDR\fP on error. |
|
1596 |
|
1597 .H 2 "Line Number Operations" |
|
1598 These are operations on the .debug_line section. |
|
1599 They provide |
|
1600 information about instructions in the program and the source |
|
1601 lines the instruction come from. |
|
1602 Typically, code is generated |
|
1603 in contiguous blocks, which may then be relocated as contiguous |
|
1604 blocks. |
|
1605 To make the provision of relocation information more |
|
1606 efficient, the information is recorded in such a manner that only |
|
1607 the address of the start of the block needs to be relocated. |
|
1608 This is done by providing the address of the first instruction |
|
1609 in a block using the function \f(CWdwarf_lne_set_address()\fP. |
|
1610 Information about the instructions in the block are then added |
|
1611 using the function \f(CWdwarf_add_line_entry()\fP, which specifies |
|
1612 offsets from the address of the first instruction. |
|
1613 The end of |
|
1614 a contiguous block is indicated by calling the function |
|
1615 \f(CWdwarf_lne_end_sequence()\fP. |
|
1616 .P |
|
1617 Line number operations do not support |
|
1618 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP. |
|
1619 |
|
1620 .H 3 "dwarf_add_line_entry()" |
|
1621 .DS |
|
1622 \f(CWDwarf_Unsigned dwarf_add_line_entry( |
|
1623 Dwarf_P_Debug dbg, |
|
1624 Dwarf_Unsigned file_index, |
|
1625 Dwarf_Addr code_offset, |
|
1626 Dwarf_Unsigned lineno, |
|
1627 Dwarf_Signed column_number, |
|
1628 Dwarf_Bool is_source_stmt_begin, |
|
1629 Dwarf_Bool is_basic_block_begin, |
|
1630 Dwarf_Error *error)\fP |
|
1631 .DE |
|
1632 The function \f(CWdwarf_add_line_entry()\fP adds an entry to the |
|
1633 section containing information about source lines. |
|
1634 It specifies |
|
1635 in \f(CWcode_offset\fP, the offset from the address set using |
|
1636 \f(CWdwarfdwarf_lne_set_address()\fP, of the address of the first |
|
1637 instruction in a contiguous block. |
|
1638 The source file that gave rise |
|
1639 to the instruction is specified by \f(CWfile_index\fP, the source |
|
1640 line number is specified by \f(CWlineno\fP, and the source column |
|
1641 number is specified by \f(CWcolumn_number\fP |
|
1642 (column numbers begin at 1) |
|
1643 (if the source column is unknown, specify 0). |
|
1644 \f(CWfile_index\fP |
|
1645 is the index of the source file in a list of source files which is |
|
1646 built up using the function \f(CWdwarf_add_file_decl()\fP. |
|
1647 |
|
1648 \f(CWis_source_stmt_begin\fP is a boolean flag that is true only if |
|
1649 the instruction at \f(CWcode_address\fP is the first instruction in |
|
1650 the sequence generated for the source line at \f(CWlineno\fP. Similarly, |
|
1651 \f(CWis_basic_block_begin\fP is a boolean flag that is true only if |
|
1652 the instruction at \f(CWcode_address\fP is the first instruction of |
|
1653 a basic block. |
|
1654 |
|
1655 It returns \f(CW0\fP on success, and \f(CWDW_DLV_NOCOUNT\fP on error. |
|
1656 |
|
1657 .H 3 "dwarf_lne_set_address()" |
|
1658 .DS |
|
1659 \f(CWDwarf_Unsigned dwarf_lne_set_address( |
|
1660 Dwarf_P_Debug dbg, |
|
1661 Dwarf_Addr offs, |
|
1662 Dwarf_Unsigned symidx, |
|
1663 Dwarf_Error *error)\fP |
|
1664 .DE |
|
1665 The function \f(CWdwarf_lne_set_address()\fP sets the target address |
|
1666 at which a contiguous block of instructions begin. Information about |
|
1667 the instructions in the block is added to .debug_line using calls to |
|
1668 \f(CWdwarfdwarf_add_line_entry()\fP which specifies the offset of each |
|
1669 instruction in the block relative to the start of the block. This is |
|
1670 done so that a single relocation record can be used to obtain the final |
|
1671 target address of every instruction in the block. |
|
1672 |
|
1673 The relocatable address of the start of the block of instructions is |
|
1674 specified by \f(CWoffs\fP. The symbol used to relocate the address |
|
1675 is given by \f(CWsymidx\fP, which is normally the index of the symbol in the |
|
1676 Elf symbol table. |
|
1677 |
|
1678 It returns \f(CW0\fP on success, and \f(CWDW_DLV_NOCOUNT\fP on error. |
|
1679 |
|
1680 .H 3 "dwarf_lne_end_sequence()" |
|
1681 .DS |
|
1682 \f(CWDwarf_Unsigned dwarf_lne_end_sequence( |
|
1683 Dwarf_P_Debug dbg, |
|
1684 Dwarf_Addr address; |
|
1685 Dwarf_Error *error)\fP |
|
1686 .DE |
|
1687 The function \f(CWdwarf_lne_end_sequence()\fP indicates the end of a |
|
1688 contiguous block of instructions. |
|
1689 \f(CWaddress()\fP |
|
1690 should be just higher than the end of the last address in the |
|
1691 sequence of instructions. |
|
1692 block of instructions, a call to \f(CWdwarf_lne_set_address()\fP will |
|
1693 have to be made to set the address of the start of the target address |
|
1694 of the block, followed by calls to \f(CWdwarf_add_line_entry()\fP for |
|
1695 each of the instructions in the block. |
|
1696 |
|
1697 It returns \f(CW0\fP on success, and \f(CWDW_DLV_NOCOUNT\fP on error. |
|
1698 |
|
1699 .H 3 "dwarf_add_directory_decl()" |
|
1700 .DS |
|
1701 \f(CWDwarf_Unsigned dwarf_add_directory_decl( |
|
1702 Dwarf_P_Debug dbg, |
|
1703 char *name, |
|
1704 Dwarf_Error *error)\fP |
|
1705 .DE |
|
1706 The function \f(CWdwarf_add_directory_decl()\fP adds the string |
|
1707 specified by \f(CWname\fP to the list of include directories in |
|
1708 the statement program prologue of the .debug_line section. |
|
1709 The |
|
1710 string should therefore name a directory from which source files |
|
1711 have been used to create the present object. |
|
1712 |
|
1713 It returns the index of the string just added, in the list of include |
|
1714 directories for the object. |
|
1715 This index is then used to refer to this |
|
1716 string. |
|
1717 It returns \f(CWDW_DLV_NOCOUNT\fP on error. |
|
1718 |
|
1719 .H 3 "dwarf_add_file_decl()" |
|
1720 .DS |
|
1721 \f(CWDwarf_Unsigned dwarf_add_file_decl( |
|
1722 Dwarf_P_Debug dbg, |
|
1723 char *name, |
|
1724 Dwarf_Unsigned dir_idx, |
|
1725 Dwarf_Unsigned time_mod, |
|
1726 Dwarf_Unsigned length, |
|
1727 Dwarf_Error *error)\fP |
|
1728 .DE |
|
1729 The function \f(CWdwarf_add_file_decl()\fP adds the name of a source |
|
1730 file that contributed to the present object. |
|
1731 The name of the file is |
|
1732 specified by \f(CWname\fP (which must not be the empty string |
|
1733 or a null pointer, it must point to |
|
1734 a string with length greater than 0). |
|
1735 In case the name is not a fully-qualified |
|
1736 pathname, it is prefixed with the name of the directory specified by |
|
1737 \f(CWdir_idx\fP. |
|
1738 \f(CWdir_idx\fP is the index of the directory to be |
|
1739 prefixed in the list builtup using \f(CWdwarf_add_directory_decl()\fP. |
|
1740 |
|
1741 \f(CWtime_mod\fP gives the time at which the file was last modified, |
|
1742 and \f(CWlength\fP gives the length of the file in bytes. |
|
1743 |
|
1744 It returns the index of the source file in the list built up so far |
|
1745 using this function, on success. This index can then be used to |
|
1746 refer to this source file in calls to \f(CWdwarf_add_line_entry()\fP. |
|
1747 On error, it returns \f(CWDW_DLV_NOCOUNT\fP. |
|
1748 |
|
1749 .H 2 "Fast Access (aranges) Operations" |
|
1750 These functions operate on the .debug_aranges section. |
|
1751 |
|
1752 .H 3 "dwarf_add_arange()" |
|
1753 .DS |
|
1754 \f(CWDwarf_Unsigned dwarf_add_arange( |
|
1755 Dwarf_P_Debug dbg, |
|
1756 Dwarf_Addr begin_address, |
|
1757 Dwarf_Unsigned length, |
|
1758 Dwarf_Signed symbol_index, |
|
1759 Dwarf_Error *error)\fP |
|
1760 .DE |
|
1761 The function \f(CWdwarf_add_arange()\fP adds another address range |
|
1762 to be added to the section |
|
1763 containing address range information, .debug_aranges. |
|
1764 The relocatable start address of the range is |
|
1765 specified by \f(CWbegin_address\fP, and the length of the address |
|
1766 range is specified by \f(CWlength\fP. |
|
1767 The relocatable symbol to be |
|
1768 used to relocate the start of the address range is specified by |
|
1769 \f(CWsymbol_index\fP, which is normally |
|
1770 the index of the symbol in the Elf |
|
1771 symbol table. |
|
1772 |
|
1773 It returns a non-zero value on success, and \f(CW0\fP on error. |
|
1774 |
|
1775 .H 3 "dwarf_add_arange_b()" |
|
1776 .DS |
|
1777 \f(CWDwarf_Unsigned dwarf_add_arange_b( |
|
1778 Dwarf_P_Debug dbg, |
|
1779 Dwarf_Addr begin_address, |
|
1780 Dwarf_Unsigned length, |
|
1781 Dwarf_Unsigned symbol_index, |
|
1782 Dwarf_Unsigned end_symbol_index, |
|
1783 Dwarf_Addr offset_from_end_symbol, |
|
1784 Dwarf_Error *error)\fP |
|
1785 .DE |
|
1786 The function \f(CWdwarf_add_arange_b()\fP adds another address range |
|
1787 to be added to the section containing |
|
1788 address range information, .debug_aranges. |
|
1789 |
|
1790 If |
|
1791 \f(CWend_symbol_index is not zero\fP |
|
1792 we are using two symbols to create a length |
|
1793 (must be \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP to be useful) |
|
1794 .sp |
|
1795 .in +2 |
|
1796 \f(CWbegin_address\fP |
|
1797 is the offset from the symbol specified by |
|
1798 \f(CWsymbol_index\fP . |
|
1799 \f(CWoffset_from_end_symbol\fP |
|
1800 is the offset from the symbol specified by |
|
1801 \f(CWend_symbol_index\fP. |
|
1802 \f(CWlength\fP is ignored. |
|
1803 This begin-end pair will be show up in the |
|
1804 relocation array returned by |
|
1805 \f(CWdwarf_get_relocation_info() \fP |
|
1806 as a |
|
1807 \f(CWdwarf_drt_first_of_length_pair\fP |
|
1808 and |
|
1809 \f(CWdwarf_drt_second_of_length_pair\fP |
|
1810 pair of relocation records. |
|
1811 The consuming application will turn that pair into |
|
1812 something conceptually identical to |
|
1813 .sp |
|
1814 .nf |
|
1815 .in +4 |
|
1816 .word end_symbol + offset_from_end - \\ |
|
1817 ( start_symbol + begin_address) |
|
1818 .in -4 |
|
1819 .fi |
|
1820 .sp |
|
1821 The reason offsets are allowed on the begin and end symbols |
|
1822 is to allow the caller to re-use existing labels |
|
1823 when the labels are available |
|
1824 and the corresponding offset is known |
|
1825 (economizing on the number of labels in use). |
|
1826 The 'offset_from_end - begin_address' |
|
1827 will actually be in the binary stream, not the relocation |
|
1828 record, so the app processing the relocation array |
|
1829 must read that stream value into (for example) |
|
1830 net_offset and actually emit something like |
|
1831 .sp |
|
1832 .nf |
|
1833 .in +4 |
|
1834 .word end_symbol - start_symbol + net_offset |
|
1835 .in -4 |
|
1836 .fi |
|
1837 .sp |
|
1838 .in -2 |
|
1839 |
|
1840 If |
|
1841 \f(CWend_symbol_index\fP is zero |
|
1842 we must be given a length |
|
1843 (either |
|
1844 \f(CWDW_DLC_STREAM_RELOCATIONS\fP |
|
1845 or |
|
1846 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP |
|
1847 ): |
|
1848 .sp |
|
1849 .in +2 |
|
1850 The relocatable start address of the range is |
|
1851 specified by \f(CWbegin_address\fP, and the length of the address |
|
1852 range is specified by \f(CWlength\fP. |
|
1853 The relocatable symbol to be |
|
1854 used to relocate the start of the address range is specified by |
|
1855 \f(CWsymbol_index\fP, which is normally |
|
1856 the index of the symbol in the Elf |
|
1857 symbol table. |
|
1858 The |
|
1859 \f(CWoffset_from_end_symbol\fP |
|
1860 is ignored. |
|
1861 .in -2 |
|
1862 |
|
1863 |
|
1864 It returns a non-zero value on success, and \f(CW0\fP on error. |
|
1865 |
|
1866 |
|
1867 .H 2 "Fast Access (pubnames) Operations" |
|
1868 These functions operate on the .debug_pubnames section. |
|
1869 .sp |
|
1870 .H 3 "dwarf_add_pubname()" |
|
1871 .DS |
|
1872 \f(CWDwarf_Unsigned dwarf_add_pubname( |
|
1873 Dwarf_P_Debug dbg, |
|
1874 Dwarf_P_Die die, |
|
1875 char *pubname_name, |
|
1876 Dwarf_Error *error)\fP |
|
1877 .DE |
|
1878 The function \f(CWdwarf_add_pubname()\fP adds the pubname specified |
|
1879 by \f(CWpubname_name\fP to the section containing pubnames, i.e. |
|
1880 .debug_pubnames. The \f(CWDIE\fP that represents the function |
|
1881 being named is specified by \f(CWdie\fP. |
|
1882 |
|
1883 It returns a non-zero value on success, and \f(CW0\fP on error. |
|
1884 |
|
1885 .H 2 "Fast Access (weak names) Operations" |
|
1886 These functions operate on the .debug_weaknames section. |
|
1887 |
|
1888 .H 3 "dwarf_add_weakname()" |
|
1889 .DS |
|
1890 \f(CWDwarf_Unsigned dwarf_add_weakname( |
|
1891 Dwarf_P_Debug dbg, |
|
1892 Dwarf_P_Die die, |
|
1893 char *weak_name, |
|
1894 Dwarf_Error *error)\fP |
|
1895 .DE |
|
1896 The function \f(CWdwarf_add_weakname()\fP adds the weak name specified |
|
1897 by \f(CWweak_name\fP to the section containing weak names, i.e. |
|
1898 .debug_weaknames. The \f(CWDIE\fP that represents the function |
|
1899 being named is specified by \f(CWdie\fP. |
|
1900 |
|
1901 It returns a non-zero value on success, and \f(CW0\fP on error. |
|
1902 |
|
1903 .H 2 "Static Function Names Operations" |
|
1904 The .debug_funcnames section contains the names of static function |
|
1905 names defined in the object, and also the offsets of the \f(CWDIE\fPs |
|
1906 that represent the definitions of the functions in the .debug_info |
|
1907 section. |
|
1908 |
|
1909 .H 3 "dwarf_add_funcname()" |
|
1910 .DS |
|
1911 \f(CWDwarf_Unsigned dwarf_add_funcname( |
|
1912 Dwarf_P_Debug dbg, |
|
1913 Dwarf_P_Die die, |
|
1914 char *func_name, |
|
1915 Dwarf_Error *error)\fP |
|
1916 .DE |
|
1917 The function \f(CWdwarf_add_funcname()\fP adds the name of a static |
|
1918 function specified by \f(CWfunc_name\fP to the section containing the |
|
1919 names of static functions defined in the object represented by \f(CWdbg\fP. |
|
1920 The \f(CWDIE\fP that represents the definition of the function is |
|
1921 specified by \f(CWdie\fP. |
|
1922 |
|
1923 It returns a non-zero value on success, and \f(CW0\fP on error. |
|
1924 |
|
1925 .H 2 "File-scope User-defined Type Names Operations" |
|
1926 The .debug_typenames section contains the names of file-scope |
|
1927 user-defined types in the given object, and also the offsets |
|
1928 of the \f(CWDIE\fPs that represent the definitions of the types |
|
1929 in the .debug_info section. |
|
1930 |
|
1931 .H 3 "dwarf_add_typename()" |
|
1932 .DS |
|
1933 \f(CWDwarf_Unsigned dwarf_add_typename( |
|
1934 Dwarf_P_Debug dbg, |
|
1935 Dwarf_P_Die die, |
|
1936 char *type_name, |
|
1937 Dwarf_Error *error)\fP |
|
1938 .DE |
|
1939 The function \f(CWdwarf_add_typename()\fP adds the name of a file-scope |
|
1940 user-defined type specified by \f(CWtype_name\fP to the section that |
|
1941 contains the names of file-scope user-defined type. The object that |
|
1942 this section belongs to is specified by \f(CWdbg\fP. The \f(CWDIE\fP |
|
1943 that represents the definition of the type is specified by \f(CWdie\fP. |
|
1944 |
|
1945 It returns a non-zero value on success, and \f(CW0\fP on error. |
|
1946 |
|
1947 .H 2 "File-scope Static Variable Names Operations" |
|
1948 The .debug_varnames section contains the names of file-scope static |
|
1949 variables in the given object, and also the offsets of the \f(CWDIE\fPs |
|
1950 that represent the definition of the variables in the .debug_info |
|
1951 section. |
|
1952 |
|
1953 .H 3 "dwarf_add_varname()" |
|
1954 .DS |
|
1955 \f(CWDwarf_Unsigned dwarf_add_varname( |
|
1956 Dwarf_P_Debug dbg, |
|
1957 Dwarf_P_Die die, |
|
1958 char *var_name, |
|
1959 Dwarf_Error *error)\fP |
|
1960 .DE |
|
1961 The function \f(CWdwarf_add_varname()\fP adds the name of a file-scope |
|
1962 static variable specified by \f(CWvar_name\fP to the section that |
|
1963 contains the names of file-scope static variables defined by the |
|
1964 object represented by \f(CWdbg\fP. The \f(CWDIE\fP that represents |
|
1965 the definition of the static variable is specified by \f(CWdie\fP. |
|
1966 |
|
1967 It returns a non-zero value on success, and \f(CW0\fP on error. |
|
1968 |
|
1969 .H 2 "Macro Information Creation" |
|
1970 All strings passed in by the caller are copied by these |
|
1971 functions, so the space in which the caller provides the strings |
|
1972 may be ephemeral (on the stack, or immediately reused or whatever) |
|
1973 without this causing any difficulty. |
|
1974 |
|
1975 .H 3 "dwarf_def_macro()" |
|
1976 .DS |
|
1977 \f(CWint dwarf_def_macro(Dwarf_P_Debug dbg, |
|
1978 Dwarf_Unsigned lineno, |
|
1979 char *name |
|
1980 char *value, |
|
1981 Dwarf_Error *error);\fP |
|
1982 .DE |
|
1983 Adds a macro definition. |
|
1984 The \f(CWname\fP argument should include the parentheses |
|
1985 and parameter names if this is a function-like macro. |
|
1986 Neither string should contain extraneous whitespace. |
|
1987 \f(CWdwarf_def_macro()\fP adds the mandated space after the |
|
1988 name and before the value in the |
|
1989 output DWARF section(but does not change the |
|
1990 strings pointed to by the arguments). |
|
1991 If this is a definition before any files are read, |
|
1992 \f(CWlineno\fP should be 0. |
|
1993 Returns \f(CWDW_DLV_ERROR\fP |
|
1994 and sets \f(CWerror\fP |
|
1995 if there is an error. |
|
1996 Returns \f(CWDW_DLV_OK\fP if the call was successful. |
|
1997 |
|
1998 |
|
1999 .H 3 "dwarf_undef_macro()" |
|
2000 .DS |
|
2001 \f(CWint dwarf_undef_macro(Dwarf_P_Debug dbg, |
|
2002 Dwarf_Unsigned lineno, |
|
2003 char *name, |
|
2004 Dwarf_Error *error);\fP |
|
2005 .DE |
|
2006 Adds a macro un-definition note. |
|
2007 If this is a definition before any files are read, |
|
2008 \f(CWlineno\fP should be 0. |
|
2009 Returns \f(CWDW_DLV_ERROR\fP |
|
2010 and sets \f(CWerror\fP |
|
2011 if there is an error. |
|
2012 Returns \f(CWDW_DLV_OK\fP if the call was successful. |
|
2013 |
|
2014 |
|
2015 .H 3 "dwarf_start_macro_file()" |
|
2016 .DS |
|
2017 \f(CWint dwarf_start_macro_file(Dwarf_P_Debug dbg, |
|
2018 Dwarf_Unsigned lineno, |
|
2019 Dwarf_Unsigned fileindex, |
|
2020 Dwarf_Error *error);\fP |
|
2021 .DE |
|
2022 \f(CWfileindex\fP is an index in the .debug_line header: |
|
2023 the index of |
|
2024 the file name. |
|
2025 See the function \f(CWdwarf_add_file_decl()\fP. |
|
2026 The \f(CWlineno\fP should be 0 if this file is |
|
2027 the file of the compilation unit source itself |
|
2028 (which, of course, is not a #include in any |
|
2029 file). |
|
2030 Returns \f(CWDW_DLV_ERROR\fP |
|
2031 and sets \f(CWerror\fP |
|
2032 if there is an error. |
|
2033 Returns \f(CWDW_DLV_OK\fP if the call was successful. |
|
2034 |
|
2035 |
|
2036 .H 3 "dwarf_end_macro_file()" |
|
2037 .DS |
|
2038 \f(CWint dwarf_end_macro_file(Dwarf_P_Debug dbg, |
|
2039 Dwarf_Error *error);\fP |
|
2040 .DE |
|
2041 Returns \f(CWDW_DLV_ERROR\fP |
|
2042 and sets \f(CWerror\fP |
|
2043 if there is an error. |
|
2044 Returns \f(CWDW_DLV_OK\fP if the call was successful. |
|
2045 |
|
2046 .H 3 "dwarf_vendor_ext()" |
|
2047 .DS |
|
2048 \f(CWint dwarf_vendor_ext(Dwarf_P_Debug dbg, |
|
2049 Dwarf_Unsigned constant, |
|
2050 char * string, |
|
2051 Dwarf_Error* error); \fP |
|
2052 .DE |
|
2053 The meaning of the \f(CWconstant\fP and the\f(CWstring\fP |
|
2054 in the macro info section |
|
2055 are undefined by DWARF itself, but the string must be |
|
2056 an ordinary null terminated string. |
|
2057 This call is not an extension to DWARF. |
|
2058 It simply enables storing |
|
2059 macro information as specified in the DWARF document. |
|
2060 Returns \f(CWDW_DLV_ERROR\fP |
|
2061 and sets \f(CWerror\fP |
|
2062 if there is an error. |
|
2063 Returns \f(CWDW_DLV_OK\fP if the call was successful. |
|
2064 |
|
2065 |
|
2066 .H 2 "Low Level (.debug_frame) operations" |
|
2067 These functions operate on the .debug_frame section. Refer to |
|
2068 \f(CWlibdwarf.h\fP for the register names and register assignment |
|
2069 mapping. Both of these are necessarily machine dependent. |
|
2070 |
|
2071 .H 3 "dwarf_new_fde()" |
|
2072 .DS |
|
2073 \f(CWDwarf_P_Fde dwarf_new_fde( |
|
2074 Dwarf_P_Debug dbg, |
|
2075 Dwarf_Error *error)\fP |
|
2076 .DE |
|
2077 The function \f(CWdwarf_new_fde()\fP returns a new \f(CWDwarf_P_Fde\fP |
|
2078 descriptor that should be used to build a complete \f(CWFDE\fP. |
|
2079 Subsequent calls to routines that build up the \f(CWFDE\fP should use |
|
2080 the same \f(CWDwarf_P_Fde\fP descriptor. |
|
2081 |
|
2082 It returns a valid \f(CWDwarf_P_Fde\fP descriptor on success, and |
|
2083 \f(CWDW_DLV_BADADDR\fP on error. |
|
2084 |
|
2085 .H 3 "dwarf_add_frame_cie()" |
|
2086 .DS |
|
2087 \f(CWDwarf_Unsigned dwarf_add_frame_cie( |
|
2088 Dwarf_P_Debug dbg, |
|
2089 char *augmenter, |
|
2090 Dwarf_Small code_align, |
|
2091 Dwarf_Small data_align, |
|
2092 Dwarf_Small ret_addr_reg, |
|
2093 Dwarf_Ptr init_bytes, |
|
2094 Dwarf_Unsigned init_bytes_len, |
|
2095 Dwarf_Error *error);\fP |
|
2096 .DE |
|
2097 The function |
|
2098 \f(CWdwarf_add_frame_cie()\fP |
|
2099 creates a \f(CWCIE\fP, |
|
2100 and returns an index to it, that should be used to refer to this |
|
2101 \f(CWCIE\fP. |
|
2102 \f(CWCIE\fPs are used by \f(CWFDE\fPs to setup |
|
2103 initial values for frames. |
|
2104 The augmentation string for the \f(CWCIE\fP |
|
2105 is specified by \f(CWaugmenter\fP. |
|
2106 The code alignment factor, |
|
2107 data alignment factor, and the return address register for the |
|
2108 \f(CWCIE\fP are specified by \f(CWcode_align\fP, \f(CWdata_align\fP, |
|
2109 and \f(CWret_addr_reg\fP respectively. |
|
2110 \f(CWinit_bytes\fP points |
|
2111 to the bytes that represent the instructions for the \f(CWCIE\fP |
|
2112 being created, and \f(CWinit_bytes_len\fP specifies the number |
|
2113 of bytes of instructions. |
|
2114 |
|
2115 There is no convenient way to generate the \f(CWinit_bytes\fP |
|
2116 stream. |
|
2117 One just |
|
2118 has to calculate it by hand or separately |
|
2119 generate something with the |
|
2120 correct sequence and use dwarfdump -v and elfdump -h and some |
|
2121 kind of hex dumper to see the bytes. |
|
2122 This is a serious inconvenience! |
|
2123 |
|
2124 It returns an index to the \f(CWCIE\fP just created on success. |
|
2125 On error it returns \f(CWDW_DLV_NOCOUNT\fP. |
|
2126 |
|
2127 .H 3 "dwarf_add_frame_fde()" |
|
2128 .DS |
|
2129 \f(CWDwarf_Unsigned dwarf_add_frame_fde( |
|
2130 Dwarf_P_Debug dbg, |
|
2131 Dwarf_P_Fde fde, |
|
2132 Dwarf_P_Die die, |
|
2133 Dwarf_Unsigned cie, |
|
2134 Dwarf_Addr virt_addr, |
|
2135 Dwarf_Unsigned code_len, |
|
2136 Dwarf_Unsigned sym_idx, |
|
2137 Dwarf_Error* error)\fP |
|
2138 .DE |
|
2139 The function \f(CWdwarf_add_frame_fde()\fP adds the \f(CWFDE\fP |
|
2140 specified by \f(CWfde\fP to the list of \f(CWFDE\fPs for the |
|
2141 object represented by the given \f(CWdbg\fP. |
|
2142 \f(CWdie\fP specifies |
|
2143 the \f(CWDIE\fP that represents the function whose frame information |
|
2144 is specified by the given \f(CWfde\fP. |
|
2145 \f(CWcie\fP specifies the |
|
2146 index of the \f(CWCIE\fP that should be used to setup the initial |
|
2147 conditions for the given frame. |
|
2148 |
|
2149 |
|
2150 It returns an index to the given \f(CWfde\fP. |
|
2151 |
|
2152 |
|
2153 .H 3 "dwarf_add_frame_fde_b()" |
|
2154 .DS |
|
2155 \f(CWDwarf_Unsigned dwarf_add_frame_fde_b( |
|
2156 Dwarf_P_Debug dbg, |
|
2157 Dwarf_P_Fde fde, |
|
2158 Dwarf_P_Die die, |
|
2159 Dwarf_Unsigned cie, |
|
2160 Dwarf_Addr virt_addr, |
|
2161 Dwarf_Unsigned code_len, |
|
2162 Dwarf_Unsigned sym_idx, |
|
2163 Dwarf_Unsigned sym_idx_of_end, |
|
2164 Dwarf_Addr offset_from_end_sym, |
|
2165 Dwarf_Error* error)\fP |
|
2166 .DE |
|
2167 This function is like |
|
2168 \f(CWdwarf_add_frame_fde()\fP |
|
2169 except that |
|
2170 \f(CWdwarf_add_frame_fde_b()\fP |
|
2171 has new arguments to allow use |
|
2172 with |
|
2173 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP. |
|
2174 |
|
2175 The function \f(CWdwarf_add_frame_fde_b()\fP |
|
2176 adds the |
|
2177 \f(CWFDE\fP |
|
2178 specified by \f(CWfde\fP to the list of \f(CWFDE\fPs for the |
|
2179 object represented by the given \f(CWdbg\fP. |
|
2180 \f(CWdie\fP specifies |
|
2181 the \f(CWDIE\fP that represents the function whose frame information |
|
2182 is specified by the given \f(CWfde\fP. |
|
2183 \f(CWcie\fP specifies the |
|
2184 index of the \f(CWCIE\fP that should be used to setup the initial |
|
2185 conditions for the given frame. |
|
2186 \f(CWvirt_addr\fP represents the |
|
2187 relocatable address at which the code for the given function begins, |
|
2188 and \f(CWsym_idx\fP gives the index of the relocatable symbol to |
|
2189 be used to relocate this address (\f(CWvirt_addr\fP that is). |
|
2190 \f(CWcode_len\fP specifies the size in bytes of the machine instructions |
|
2191 for the given function. |
|
2192 |
|
2193 If \f(CWsym_idx_of_end\fP is zero |
|
2194 (may be |
|
2195 \f(CWDW_DLC_STREAM_RELOCATIONS\fP |
|
2196 or |
|
2197 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP |
|
2198 ): |
|
2199 .sp |
|
2200 .in +2 |
|
2201 \f(CWvirt_addr\fP represents the |
|
2202 relocatable address at which the code for the given function begins, |
|
2203 and \f(CWsym_idx\fP gives the index of the relocatable symbol to |
|
2204 be used to relocate this address (\f(CWvirt_addr\fP that is). |
|
2205 \f(CWcode_len\fP |
|
2206 specifies the size in bytes of the machine instructions |
|
2207 for the given function. |
|
2208 \f(CWsym_idx_of_end\fP |
|
2209 and |
|
2210 \f(CWoffset_from_end_sym\fP |
|
2211 are unused. |
|
2212 .in -2 |
|
2213 .sp |
|
2214 |
|
2215 |
|
2216 If \f(CWsym_idx_of_end\fP is non-zero |
|
2217 (must be \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP to be useful): |
|
2218 .sp |
|
2219 .in +2 |
|
2220 \f(CWvirt_addr\fP |
|
2221 is the offset from the symbol specified by |
|
2222 \f(CWsym_idx\fP . |
|
2223 \f(CWoffset_from_end_sym\fP |
|
2224 is the offset from the symbol specified by |
|
2225 \f(CWsym_idx_of_end\fP. |
|
2226 \f(CWcode_len\fP is ignored. |
|
2227 This begin-end pair will be show up in the |
|
2228 relocation array returned by |
|
2229 \f(CWdwarf_get_relocation_info() \fP |
|
2230 as a |
|
2231 \f(CWdwarf_drt_first_of_length_pair\fP |
|
2232 and |
|
2233 \f(CWdwarf_drt_second_of_length_pair\fP |
|
2234 pair of relocation records. |
|
2235 The consuming application will turn that pair into |
|
2236 something conceptually identical to |
|
2237 .sp |
|
2238 .nf |
|
2239 .in +4 |
|
2240 .word end_symbol + begin - \\ |
|
2241 ( start_symbol + offset_from_end) |
|
2242 .in -4 |
|
2243 .fi |
|
2244 .sp |
|
2245 The reason offsets are allowed on the begin and end symbols |
|
2246 is to allow the caller to re-use existing labels |
|
2247 when the labels are available |
|
2248 and the corresponding offset is known |
|
2249 (economizing on the number of labels in use). |
|
2250 The 'offset_from_end - begin_address' |
|
2251 will actually be in the binary stream, not the relocation |
|
2252 record, so the app processing the relocation array |
|
2253 must read that stream value into (for example) |
|
2254 net_offset and actually emit something like |
|
2255 .sp |
|
2256 .nf |
|
2257 .in +4 |
|
2258 .word end_symbol - start_symbol + net_offset |
|
2259 .in -4 |
|
2260 .fi |
|
2261 .sp |
|
2262 .in -2 |
|
2263 |
|
2264 It returns an index to the given \f(CWfde\fP. |
|
2265 |
|
2266 On error, it returns \f(CWDW_DLV_NOCOUNT\fP. |
|
2267 |
|
2268 .H 3 "dwarf_add_frame_info_b()" |
|
2269 .DS |
|
2270 \f(CWDwarf_Unsigned dwarf_add_frame_info_b( |
|
2271 Dwarf_P_Debug dbg, |
|
2272 Dwarf_P_Fde fde, |
|
2273 Dwarf_P_Die die, |
|
2274 Dwarf_Unsigned cie, |
|
2275 Dwarf_Addr virt_addr, |
|
2276 Dwarf_Unsigned code_len, |
|
2277 Dwarf_Unsigned sym_idx, |
|
2278 Dwarf_Unsigned end_symbol_index, |
|
2279 Dwarf_Addr offset_from_end_symbol, |
|
2280 Dwarf_Signed offset_into_exception_tables, |
|
2281 Dwarf_Unsigned exception_table_symbol, |
|
2282 Dwarf_Error* error)\fP |
|
2283 .DE |
|
2284 The function \f(CWdwarf_add_frame_fde()\fP adds the \f(CWFDE\fP |
|
2285 specified by \f(CWfde\fP to the list of \f(CWFDE\fPs for the |
|
2286 object represented by the given \f(CWdbg\fP. |
|
2287 \f(CWdie\fP specifies |
|
2288 the \f(CWDIE\fP that represents the function whose frame information |
|
2289 is specified by the given \f(CWfde\fP. |
|
2290 \f(CWcie\fP specifies the |
|
2291 index of the \f(CWCIE\fP that should be used to setup the initial |
|
2292 conditions for the given frame. |
|
2293 \f(CWoffset_into_exception_tables\fP specifies the |
|
2294 offset into \f(CW.MIPS.eh_region\fP elf section where the exception tables |
|
2295 for this function begins. |
|
2296 \f(CWexception_table_symbol\fP gives the index of |
|
2297 the relocatable symbol to be used to relocate this offset. |
|
2298 |
|
2299 |
|
2300 If |
|
2301 \f(CWend_symbol_index is not zero\fP |
|
2302 we are using two symbols to create a length |
|
2303 (must be \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP to be useful) |
|
2304 .sp |
|
2305 .in +2 |
|
2306 \f(CWvirt_addr\fP |
|
2307 is the offset from the symbol specified by |
|
2308 \f(CWsym_idx\fP . |
|
2309 \f(CWoffset_from_end_symbol\fP |
|
2310 is the offset from the symbol specified by |
|
2311 \f(CWend_symbol_index\fP. |
|
2312 \f(CWcode_len\fP is ignored. |
|
2313 This begin-end pair will be show up in the |
|
2314 relocation array returned by |
|
2315 \f(CWdwarf_get_relocation_info() \fP |
|
2316 as a |
|
2317 \f(CWdwarf_drt_first_of_length_pair\fP |
|
2318 and |
|
2319 \f(CWdwarf_drt_second_of_length_pair\fP |
|
2320 pair of relocation records. |
|
2321 The consuming application will turn that pair into |
|
2322 something conceptually identical to |
|
2323 .sp |
|
2324 .nf |
|
2325 .in +4 |
|
2326 .word end_symbol + offset_from_end_symbol - \\ |
|
2327 ( start_symbol + virt_addr) |
|
2328 .in -4 |
|
2329 .fi |
|
2330 .sp |
|
2331 The reason offsets are allowed on the begin and end symbols |
|
2332 is to allow the caller to re-use existing labels |
|
2333 when the labels are available |
|
2334 and the corresponding offset is known |
|
2335 (economizing on the number of labels in use). |
|
2336 The 'offset_from_end - begin_address' |
|
2337 will actually be in the binary stream, not the relocation |
|
2338 record, so the app processing the relocation array |
|
2339 must read that stream value into (for example) |
|
2340 net_offset and actually emit something like |
|
2341 .sp |
|
2342 .nf |
|
2343 .in +4 |
|
2344 .word end_symbol - start_symbol + net_offset |
|
2345 .in -4 |
|
2346 .fi |
|
2347 .sp |
|
2348 .in -2 |
|
2349 |
|
2350 If |
|
2351 \f(CWend_symbol_index\fP is zero |
|
2352 we must be given a code_len value |
|
2353 (either |
|
2354 \f(CWDW_DLC_STREAM_RELOCATIONS\fP |
|
2355 or |
|
2356 \f(CWDW_DLC_SYMBOLIC_RELOCATIONS\fP |
|
2357 ): |
|
2358 .sp |
|
2359 .in +2 |
|
2360 The relocatable start address of the range is |
|
2361 specified by \f(CWvirt_addr\fP, and the length of the address |
|
2362 range is specified by \f(CWcode_len\fP. |
|
2363 The relocatable symbol to be |
|
2364 used to relocate the start of the address range is specified by |
|
2365 \f(CWsymbol_index\fP, which is normally |
|
2366 the index of the symbol in the Elf |
|
2367 symbol table. |
|
2368 The |
|
2369 \f(CWoffset_from_end_symbol\fP |
|
2370 is ignored. |
|
2371 .in -2 |
|
2372 |
|
2373 |
|
2374 It returns an index to the given \f(CWfde\fP. |
|
2375 |
|
2376 On error, it returns \f(CWDW_DLV_NOCOUNT\fP. |
|
2377 |
|
2378 |
|
2379 .H 3 "dwarf_add_frame_info()" |
|
2380 |
|
2381 .DS |
|
2382 \f(CWDwarf_Unsigned dwarf_add_frame_info( |
|
2383 Dwarf_P_Debug dbg, |
|
2384 Dwarf_P_Fde fde, |
|
2385 Dwarf_P_Die die, |
|
2386 Dwarf_Unsigned cie, |
|
2387 Dwarf_Addr virt_addr, |
|
2388 Dwarf_Unsigned code_len, |
|
2389 Dwarf_Unsigned sym_idx, |
|
2390 Dwarf_Signed offset_into_exception_tables, |
|
2391 Dwarf_Unsigned exception_table_symbol, |
|
2392 Dwarf_Error* error)\fP |
|
2393 .DE |
|
2394 The function \f(CWdwarf_add_frame_fde()\fP adds the \f(CWFDE\fP |
|
2395 specified by \f(CWfde\fP to the list of \f(CWFDE\fPs for the |
|
2396 object represented by the given \f(CWdbg\fP. \f(CWdie\fP specifies |
|
2397 the \f(CWDIE\fP that represents the function whose frame information |
|
2398 is specified by the given \f(CWfde\fP. \f(CWcie\fP specifies the |
|
2399 index of the \f(CWCIE\fP that should be used to setup the initial |
|
2400 conditions for the given frame. \f(CWvirt_addr\fP represents the |
|
2401 relocatable address at which the code for the given function begins, |
|
2402 and \f(CWsym_idx\fP gives the index of the relocatable symbol to |
|
2403 be used to relocate this address (\f(CWvirt_addr\fP that is). |
|
2404 \f(CWcode_len\fP specifies the size in bytes of the machine instructions |
|
2405 for the given function. \f(CWoffset_into_exception_tables\fP specifies the |
|
2406 offset into \f(CW.MIPS.eh_region\fP elf section where the exception tables |
|
2407 for this function begins. \f(CWexception_table_symbol\fP gives the index of |
|
2408 the relocatable symbol to be used to relocate this offset. |
|
2409 |
|
2410 It returns an index to the given \f(CWfde\fP. |
|
2411 |
|
2412 .H 3 "dwarf_fde_cfa_offset()" |
|
2413 .DS |
|
2414 \f(CWDwarf_P_Fde dwarf_fde_cfa_offset( |
|
2415 Dwarf_P_Fde fde, |
|
2416 Dwarf_Unsigned reg, |
|
2417 Dwarf_Signed offset, |
|
2418 Dwarf_Error *error)\fP |
|
2419 .DE |
|
2420 The function \f(CWdwarf_fde_cfa_offset()\fP appends a \f(CWDW_CFA_offset\fP |
|
2421 operation to the \f(CWFDE\fP, specified by \f(CWfde\fP, being constructed. |
|
2422 The first operand of the \f(CWDW_CFA_offset\fP operation is specified by |
|
2423 \f(CWreg\P. The register specified should not exceed 6 bits. The second |
|
2424 operand of the \f(CWDW_CFA_offset\fP operation is specified by \f(CWoffset\fP. |
|
2425 |
|
2426 It returns the given \f(CWfde\fP on success. |
|
2427 |
|
2428 It returns \f(CWDW_DLV_BADADDR\fP on error. |
|
2429 |
|
2430 .H 3 "dwarf_add_fde_inst()" |
|
2431 .DS |
|
2432 \f(CWDwarf_P_Fde dwarf_add_fde_inst( |
|
2433 Dwarf_P_Fde fde, |
|
2434 Dwarf_Small op, |
|
2435 Dwarf_Unsigned val1, |
|
2436 Dwarf_Unsigned val2, |
|
2437 Dwarf_Error *error)\fP |
|
2438 .DE |
|
2439 The function \f(CWdwarf_add_fde_inst()\fP adds the operation specified |
|
2440 by \f(CWop\fP to the \f(CWFDE\fP specified by \f(CWfde\fP. Upto two |
|
2441 operands can be specified in \f(CWval1\fP, and \f(CWval2\fP. Based on |
|
2442 the operand specified \f(CWLibdwarf\fP decides how many operands are |
|
2443 meaningful for the operand. It also converts the operands to the |
|
2444 appropriate datatypes (they are passed to \f(CWdwarf_add_fde_inst\fP |
|
2445 as \f(CWDwarf_Unsigned\fP). |
|
2446 |
|
2447 It returns the given \f(CWfde\fP on success, and \f(CWDW_DLV_BADADDR\fP |
|
2448 on error. |
|
2449 |
|
2450 .S |
|
2451 .TC 1 1 4 |
|
2452 .CS |