1 \chapter{Debug Section Relationships (Informative)}
2 \label{app:debugsectionrelationshipsinformative}
3 DWARF information is organized into multiple program sections,
4 each of which holds a particular kind of information. In some
5 cases, information in one section refers to information in one
6 or more of the others. These relationships are illustrated by
7 the diagrams and associated notes on the following pages.
9 \section{Normal DWARF Section Relationships}
10 Figure \referfol{fig:debugsectionrelationships} illustrates
11 the DWARF section relations without split DWARF object files
12 involved. Similarly, it does not show the
13 relationships between the main debugging sections of an executable
14 or sharable file and a related \addtoindex{supplementary object file}.
16 \section{Split DWARF Section Relationships}
17 Figure \ref{fig:splitdwarfsectionrelationships} illustrates
18 the DWARF section relationships for \splitDWARFobjectfile{s}.
19 However, it does not show the
20 relationships between the main debugging sections of an executable
21 or shareable file and a related \addtoindex{supplementary object file}.
27 [sect/.style={rectangle, rounded corners=10pt, draw, fill=blue!15,
28 inner sep=.2cm, minimum width=4.0cm},
29 link/.style={rectangle, draw,
30 inner sep=.2cm, minimum width=4.5cm},
31 circ/.style={circle, draw, minimum size=0.5cm}]
33 % The first (leftmost) column, first sections, then links, from top to bottom
35 \node(zsectara) at ( 0, 15.0) [sect] {\dotdebugaranges};
36 \node(zlinka) at ( 0, 13.5) [link] {To compilation unit~~(a)};
37 \node(zsectinf) at ( 0, 7.5) [sect] {\begin{tabular}{c}
42 \node(zcircs) at (-1, 5 ) [circ] {(s)};
43 \node(zlinkb) at ( 0, 1.5) [link] {To compilation unit~~(b)};
44 \node(zsectpub) at ( 0, 0.0) [sect] {\begin{tabular}{c}
48 \draw[thick,angle 90-] (zcircs) -- (zsectinf);
49 \draw[thick,-to reversed] (zlinka) -- (zsectara);
50 \draw[thick,angle 90-] (zsectinf) -- (zlinka);
51 \draw[thick,-angle 90] (zlinkb) -- (zsectinf);
52 \draw[thick,to reversed-] (zsectpub) -- (zlinkb);
54 % The second column, similarly
56 \node(zsectfra) at (5, 15.0) [sect] {\dotdebugframe};
57 \node(zlinkc) at (5, 13.5) [link] {To abbreviations~~(c)};
58 \node(zlinkd) at (5, 12.1) [link] {\DWFORMstrp{}~~(d)};
59 \node(zlinke) at (5, 10.4) [link] {\begin{tabular}{c}
60 \DWATstroffsetsbase \\
61 \DWFORMstrx{}~~~~~~~~~(e) \\
63 \node(zlinkf) at (5, 8.4) [link] {\begin{tabular}{c}
64 \DWOPcallref{}~~~~~(f) \\
67 \node(zlinki) at (5, 6.7) [link] {\DWATmacros{}~~(g)};
68 \node(zlinkj) at (5, 5.4) [link] {\DWATstmtlist{}~~(h)};
69 \node(zlinkh) at (5, 3.9) [link] {\begin{tabular}{c}
70 \DWATranges{}~~~~(i) \\
73 \node(zlinkg) at (5, 2.4) [link] {\DWATlocation{}, etc.~~(j)};
74 \node(zlinkk) at (5, 0.5) [link] {\begin{tabular}(c)
81 % Links between first and second columns
83 \draw[thick,to reversed-] (zsectinf) -- (zlinkc.west);
84 \draw[thick,to reversed-] (zsectinf) -- (zlinkd.west);
85 \draw[thick,to reversed-] (zsectinf) -- (zlinke.west);
86 \draw[<->,thick] (zsectinf) -- (zlinkf.west);
87 \draw[thick,to reversed-] (zsectinf) -- (zlinkg.west);
88 \draw[thick,to reversed-] (zsectinf) -- (zlinkh.west);
89 \draw[thick,to reversed-] (zsectinf) -- (zlinki.west);
90 \draw[thick,to reversed-] (zsectinf) -- (zlinkj.west);
91 \draw[thick,to reversed-] (zsectinf) -- (zlinkk.north west);
95 \node(zsectabb) at (10, 15.00) [sect] {\dotdebugabbrev};
96 \node(zsectstr) at (10, 13.75) [sect] {\dotdebugstr};
97 \node(zlinkl) at (10, 12.50) [link] {To strings~~(l)};
98 \node(zsectstx) at (10, 11.25) [sect] {\dotdebugstroffsets};
99 \node(zlinkm) at (10, 9.50) [link] {\begin{tabular}{c}
100 \DWMACROdefinestrx \\
104 \node(zsectmac) at (10, 7.80) [sect] {\dotdebugmacro};
105 \node(zlinkn) at (10, 6.40) [link] {\begin{tabular}{c}
106 macroinfo header~~~~~~(n)\\
109 \node(zsectlin) at (10, 5.00) [sect] {\dotdebugline};
110 \node(zsectran) at (10, 3.85) [sect] {\dotdebugranges};
111 \node(zsectloc) at (10, 2.70) [sect] {\dotdebugloc{}};
112 \node(zlinko) at (10, 1.20) [link] {\begin{tabular}{c}
116 \node(zsectadx) at (10, -0.25) [sect] {\dotdebugaddr{}};
118 \draw[thick,to reversed-] (zsectstx) -- (zlinkl);
119 \draw[thick,-angle 90] (zlinkl) -- (zsectstr);
120 \draw[thick,to reversed-] (zsectmac) -- (zlinkm);
121 \draw[thick,-angle 90] (zlinkm) -- (zsectstx);
122 \draw[thick,to reversed-] (zsectmac) -- (zlinkn);
123 \draw[thick,-angle 90] (zlinkn) -- (zsectlin);
124 \draw[thick,to reversed-] (zsectloc) -- (zlinko);
125 \draw[thick,-angle 90] (zlinko) -- (zsectadx);
127 % Links between second and third colums
129 \draw[thick,-angle 90] (zlinkc.east) -- (zsectabb.west);
130 \draw[thick,-angle 90] (zlinkd.east) -- (zsectstr.west);
131 \draw[thick,-angle 90] (zlinke.east) -- (zsectstx.west);
132 \draw[thick,-angle 90] (zlinkg.east) -- (zsectloc.west);
133 \draw[thick,-angle 90] (zlinkh.east) -- (zsectran.west);
134 \draw[thick,-angle 90] (zlinki.east) -- (zsectmac.west);
135 \draw[thick,-angle 90] (zlinkj.east) -- (zsectlin.west);
136 \draw[thick,-angle 90] (zlinkk.east) -- (zsectadx.west);
140 \node(zlinky) at (15.6, 10.5) [link] {\begin{tabular}{c}
141 \DWMACROdefinestrp \\
145 \node(zlinkz) at (15.6, 6.4) [link] {\begin{tabular}{c}
149 \node(zlinkx) at (15.6, 3.8) [link] {\DWFORMlinestrp~(r)};
150 \node(zsectlns) at (15.6, 2.0) [sect] {\dotdebuglinestr};
151 \node(zcircsp) at (15.6, 0.5) [circ] {(s)'};
153 \draw[thick,to reversed-] (zsectmac.east) -- (zlinky);
154 \draw[thick,-angle 90] (zlinky) -- (zsectstr.east);
155 \draw[<->,thick] (zsectmac.east) -- (zlinkz);
156 \draw[thick,to reversed-] (zsectlin.east) -- (zlinkx);
157 \draw[thick,-angle 90] (zlinkx) -- (zsectlns);
158 \draw[thick,-angle 90] (zcircsp) -- (zsectlns);
162 \caption{Debug section relationships}
163 \label{fig:debugsectionrelationships}
169 \textbf{Notes for Figure \ref{fig:debugsectionrelationships}}
172 \itembfnl{(a) \dotdebugaranges{} to \dotdebuginfo}
173 The \texttt{debug\_info\_offset} value in
175 the offset in the \dotdebuginfo{} section of the
176 corresponding compilation unit header (not the compilation
180 \itembfnl{(b) \dotdebugnames{} to \dotdebuginfo}
181 The \texttt{debug\_info\_offset} value in the header is the offset in the
182 \dotdebuginfo{} section of the
183 corresponding compilation unit header (not
184 the compilation unit entry).
187 \itembfnl{(c) \dotdebuginfo{} to \dotdebugabbrev}
188 The \HFNdebugabbrevoffset{} value in the header is the offset in the
190 section of the abbreviations for that compilation unit.
193 \itembfnl{(d) \dotdebuginfo{} to \dotdebugstr}
194 Attribute values of class string may have form
196 value is the offset in the \dotdebugstr{}
197 section of the corresponding string.
200 \itembfnl{(e) \dotdebuginfo{} to \dotdebugstroffsets}
201 The value of the \DWATstroffsetsbase{} attribute in a
202 \DWTAGcompileunit{}, \DWTAGtypeunit{} or \DWTAGpartialunit{}
203 DIE is the offset in the
204 \dotdebugstroffsets{} section of the
205 \addtoindex{string offsets table}
207 In addition, attribute values of class string may have form
208 \DWFORMstrx, whose value is an index into the
209 string offsets table.
212 \itembfnl{(f) \dotdebuginfo{} to \dotdebuginfo}
213 The operand of the \DWOPcallref{}
214 DWARF expression operator is the
215 offset of a debugging information entry in the
216 \dotdebuginfo{} section of another compilation.
217 Similarly for attribute operands that use
221 \itembfnl{(g) \dotdebuginfo{} to \dotdebugmacro}
222 An attribute value of class
223 \livelink{chap:classmacptr}{macptr} (specifically form
224 \DWFORMsecoffset) is an
226 \dotdebugmacro{} section
227 of the beginning of the macro information for the referencing unit.
230 \itembfnl{(h) \dotdebuginfo{} to \dotdebugline}
231 An attribute value of class
232 \livelink{chap:classlineptr}{lineptr} (specifically form
235 \dotdebugline{} section of the
236 beginning of the line number information for the referencing unit.
240 \itembfnl{(i) \dotdebuginfo{} to \dotdebugranges}
241 An attribute value of class \livelink{chap:classrangelistptr}{rangelistptr}
244 is an offset within the \dotdebugranges{} section of
248 \itembfnl{(j) \dotdebuginfo{} to \dotdebugloc}
249 An attribute value of class \livelink{chap:classloclistptr}{loclistptr}
252 is an offset within the \dotdebugloc{}
254 \addtoindex{location list}.
257 \itembfnl{(k) \dotdebuginfo{} to \dotdebugaddr}
258 The value of the \DWATaddrbase{} attribute in the
259 \DWTAGcompileunit{} or \DWTAGpartialunit{} DIE is the
260 offset in the \dotdebugaddr{} section of the machine
261 addresses for that unit.
262 \DWFORMaddrx, \DWOPaddrx{} and \DWOPconstx{} contain
263 indices relative to that offset.
266 \itembfnl{(l) \dotdebugstroffsets{} to \dotdebugstr}
267 Entries in the string offsets table
268 are offsets to the corresponding string text in the
269 \dotdebugstr{} section.
272 \itembfnl{(m) \dotdebugmacro{} to \dotdebugstroffsets}
273 The second operand of a
274 \DWMACROdefinestrx{} or \DWMACROundefstrx{}
275 macro information entry is an index
276 into the string offset table in the
277 \dotdebugstroffsets{} section.
280 \itembfnl{(n) \dotdebugmacro{} to \dotdebugline}
281 The second operand of
282 \DWMACROstartfile{} refers to a file entry in the
283 \dotdebugline{} section relative to the start
284 of that section given in the macro information header.
287 \itembfnl{(o) \dotdebugloc{} to \dotdebugaddr}
288 \DWOPaddrx{} and \DWOPconstx{} operators that occur in the
289 \dotdebugloc{} section refer indirectly to the
290 \dotdebugaddr{} section by way of the
291 \DWATaddrbase{} attribute in the associated \dotdebuginfo{}
295 \itembfnl{(p) \dotdebugmacro{} to \dotdebugstr}
296 The second operand of a
297 \DWMACROdefinestrp{} or \DWMACROundefstrp{} macro information
298 entry is an index into the string table in the
299 \dotdebugstr{} section.
303 \itembfnl{(q) \dotdebugmacro{} to \dotdebugmacro}
305 \DWMACROimport{} macro information
306 entry is an offset into another part of the
307 \dotdebugmacro{} section to the header for the
308 sequence to be replicated.
312 \itembfnl{(r) \dotdebugline{} to \dotdebuglinestr}
313 The value of a \DWFORMlinestrp{} form refers to a
314 string section specific to the line number table.
315 This form can be used in a \dotdebugline{} section
316 (as well as in a \dotdebuginfo{} section).
319 \itembfnl{(s) \dotdebuginfo{} to \dotdebuglinestr}
320 The value of a \DWFORMlinestrp{} form refers to a
321 string section specific to the line number table.
322 This form can be used in a \dotdebuginfo{} section
323 (as well as in a \dotdebugline{} section).\footnote{
324 The circled (s) connects to the circled
325 (s)' via hyperspace (a wormhole).}
335 [sect/.style={rectangle, rounded corners=10pt, draw, fill=blue!15,
336 inner sep=.2cm, minimum width=4.0cm},
337 link/.style={rectangle, draw,
338 inner sep=.2cm, minimum width=4.5cm}]
340 \fill[yellow!50] (7.5,-1) -- (7.5,14.5) -- (19,14.5) -- (19,-1) -- cycle;
342 \node(ysectabb) at ( 5, 13.5) [sect] {\dotdebugabbrev};
343 \node(ysectadd) at ( 2, 12.0) [sect] {\dotdebugaddr};
344 \node(ysectara) at ( 0, 10.5) [sect] {\dotdebugaranges};
345 \node(ysectfra) at ( 0, 9.0) [sect] {\dotdebugframe};
346 \node(ysectlin) at ( 0, 7.5) [sect] {\dotdebugline};
347 \node(ysectlis) at ( 0, 6.0) [sect] {\dotdebuglinestr};
348 \node(ysectnam) at ( 0, 4.5) [sect] {\dotdebugnames};
349 \node(ysectran) at ( 0, 3.0) [sect] {\dotdebugranges};
350 \node(ysectstr) at ( 2, 1.5) [sect] {\dotdebugstr};
351 \node(ysectsto) at ( 5, 0.0) [sect] {\dotdebugstroffsets};
353 \node(ysectinf) at ( 5, 7) [sect] {\begin{tabular}{c}
360 \node(ysectinfdwo) at (10.5,7) [sect] {\begin{tabular}{c}
367 \node(ysectabbdwo) at (10.5, 13.5) [sect] {\dotdebugabbrevdwo};
368 \node(ysectlindwo) at (16.0, 7.5) [sect] {\dotdebuglinedwo};
369 \node(ysectlocdwo) at (16.0, 11.0) [sect] {\dotdebuglocdwo};
370 \node(ysectmacdwo) at (16.0, 4.5) [sect] {\dotdebugmacrodwo};
371 \node(ysectstrdwo) at (13.0, 2.0) [sect] {\dotdebugstrdwo};
372 \node(ysectstodwo) at (10.5, 0.0) [sect] {\dotdebugstroffsetsdwo};
374 \draw[thick,-angle 90] (ysectinf) -- (ysectabb) node[midway, right] {(c)};
375 \draw[thick,-angle 90] (ysectinf) -- (ysectadd) node[midway, right] {(k)};
376 \draw[thick,-angle 90] (ysectara.east) -- (ysectinf) node[midway, left] {(a)};
377 \draw[thick,-angle 90] (ysectinf) -- (ysectlin.east) node[midway, above] {(h)};
378 \draw[thick,-angle 90] (ysectlin) -- (ysectlis) node[midway, right] {(l)};
379 \draw[thick,-angle 90] (ysectnam.east) -- (ysectinf) node[midway, left] {(b)};
380 \draw[thick,-angle 90] (ysectinf) -- (ysectran.east) node[left, near end] {(i)};
381 \draw[thick,-angle 90] (ysectinf) -- (ysectstr) node[midway, right] {(d)};
382 \draw[thick,-angle 90] (ysectinf) -- (ysectsto) node[midway, right] {(e)};
383 \draw[thick,-angle 90] (ysectsto) -- (ysectstr) node[midway, right] {(l)};
385 \draw[dashed, thick,-angle 90] (ysectinf) .. controls (7.5, 12) ..(ysectinfdwo)
386 node[midway, above] {(did)};
388 \draw[thick,-angle 90] (ysectinfdwo) -- (ysectabbdwo) node[midway, right] {(co)};
389 \draw[thick,-angle 90] (ysectinfdwo) -- (ysectlindwo.west) node[midway, above] {(ho)};
390 \draw[thick,-angle 90] (ysectinfdwo) -- (ysectlocdwo.west) node[midway, below] {(jo)};
391 \draw[thick,-angle 90] (ysectinfdwo) -- (ysectmacdwo.west) node[near end, above] {(go)};
392 \draw[thick,-angle 90] (ysectinfdwo) -- (ysectstrdwo) node[midway, right] {(do)};
393 \draw[thick,-angle 90] (ysectinfdwo) -- (ysectstodwo) node[midway, left] {(eo)};
395 \draw[thick,-angle 90] (ysectstodwo) -- (ysectstrdwo) node[near end, below] {(lo)};
396 \draw[thick,-angle 90] (ysectmacdwo) -- (ysectstrdwo) node[midway, left] {(po)};
397 \draw[thick,-angle 90] (ysectmacdwo) .. controls (16.5, 1) .. (ysectstodwo.east)
398 node[near start, left] {(mo)};
399 \draw[thick,-angle 90] (ysectlindwo.east) .. controls (19,4) and (18, 0) .. (ysectstodwo.east)
400 node[very near start, left] {(lmo)};
402 \draw (0, 14) node {\begin{tabular}{l} Skeleton DWARF \\ in executable \end{tabular}};
403 \draw (17, 14) node {\begin{tabular}{r} Split DWARF \\ in separate object \end{tabular}};
406 \caption{Split DWARF section relationships}
407 \label{fig:splitdwarfsectionrelationships}
413 \textbf{Notes for Figure \ref{fig:splitdwarfsectionrelationships}}
416 \itembfnl{(a) \dotdebugaranges{} to \dotdebuginfo}
417 The \texttt{debug\_info\_offset} field in the header is the
418 offset in the \dotdebuginfo{} section of the corresponding
419 compilation unit header of the skeleton \dotdebuginfo{} section
420 (not the compilation unit entry). The \DWATdwoid{} and
421 \DWATdwoname{} attributes in the \dotdebuginfo{} skeleton
422 connect the ranges to the full compilation unit in \dotdebuginfodwo.
424 \itembfnl{(b) \dotdebugnames{} to \dotdebuginfo}
425 The \dotdebugnames{} section offsets lists provide an offset
426 for the skeleton compilation unit and eight
427 byte signatures for the type units that appear only in the
428 \dotdebuginfodwo. The DIE offsets for these
429 compilation units and type units refer to the DIEs in the
430 \dotdebuginfodwo{} section for the respective
431 compilation unit and type units.
433 \itembfnl{(c) \dotdebuginfo{} skeleton to \dotdebugabbrev}
434 The \HFNdebugabbrevoffset{} value in the header is
435 the offset in the \dotdebugabbrev{} section of the
436 abbreviations for that compilation unit skeleton.
438 \itembfnl{(co) \dotdebuginfodwo{} to \dotdebugabbrevdwo}
439 The \HFNdebugabbrevoffset{} value in the header
440 is the offset in the \dotdebugabbrevdwo{} section of the
441 abbreviations for that compilation unit.
443 \itembfnl{(d) \dotdebuginfo{} to \dotdebugstr}
444 Attribute values of class string may have form \DWFORMstrp,
445 whose value is an offset in the
446 \dotdebugstr{} section of the corresponding string.
448 \itembfnl{(did) \dotdebuginfo{} to \dotdebuginfodwo}
449 The \DWATdwoname{} and \DWATdwoid{} are the file name
450 and hash which identify the file with
451 the \texttt{.dwo} data. Both \dotdebuginfo{} and
452 \dotdebuginfodwo{} compilation units should contain
453 \DWATdwoid{} so the two can be matched. \DWATdwoname{}
454 is only needed in the \dotdebuginfo{}
455 skeleton compilation unit.
457 \itembfnl{(do) \dotdebuginfodwo{} to \dotdebugstrdwo}
458 Attribute values of class string may have form
459 \DWFORMstrp, whose value is an offset in the
460 \dotdebugstrdwo{} section of the corresponding string.
462 \itembfnl{(e) \dotdebuginfo{} to \dotdebugstroffsets}
463 Attribute values of class string may have form
464 \DWFORMstrx, whose value is an index into the
465 \dotdebugstroffsets{} section for the corresponding string.
468 \itembfnl{(eo)\dotdebuginfodwo{} to \dotdebugstroffsetsdwo}
469 Attribute values of class string may have form
470 \DWFORMstrx, whose value is an index into the
471 \dotdebugstroffsetsdwo{} section for the corresponding string.
473 \itembfnl{(fo) \dotdebuginfodwo{} to \dotdebuginfodwo}
474 The operand of the \DWOPcallref{} DWARF expression
475 operator is the offset of a debugging
476 information entry in the \dotdebuginfodwo{} section of
477 another compilation unit. Similarly for attribute
478 operands that use \DWFORMrefaddr.
479 See Section \refersec{chap:controlflowoperations}.
481 \itembfnl{(go) \dotdebuginfodwo{} to \dotdebugmacrodwo}
482 An attribute of class \CLASSmacptr{} (specifically \DWATmacros{}
483 with form \DWFORMsecoffset{}) is an offset within the
484 \dotdebugmacrodwo{} section of the beginning of the macro
485 information for the referencing unit.
487 \itembfnl{(h) \dotdebuginfo{} (skeleton) to \dotdebugline}
488 An attribute value of class \CLASSlineptr{} (specifically
489 \DWATstmtlist{} with form \DWFORMsecoffset)
490 is an offset within the \dotdebugline{} section of the
491 beginning of the line number information for the
494 \itembfnl{(ho) \dotdebuginfodwo{} to \dotdebuglinedwo{} (skeleton)}
495 An attribute value of class \CLASSlineptr{} (specifically
496 \DWATstmtlist{} with form \DWFORMsecoffset)
497 is an offset within the \dotdebuglinedwo{} section of the
498 beginning of the line number header information
499 for the referencing unit (the line table details are not in
500 \dotdebuglinedwo{} but the line header with its list
501 of file names is present).
503 \itembfnl{(i) \dotdebuginfo{} to \dotdebugranges}
504 An attribute value of class \CLASSrangelistptr{}
505 (specifically \DWATranges{} with form
506 \DWFORMsecoffset) is an offset within the \dotdebugranges{}
507 section of a range list.
509 \itembfnl{(jo) \dotdebuginfodwo{} to \dotdebuglocdwo}
510 An attribute value of class \CLASSloclistptr{} (specifically
511 \DWATdatamemberlocation,
518 \DWATuselocation{} or
519 \DWATvtableelemlocation{}
520 with form \DWFORMsecoffset) is an offset within the
521 \dotdebuglocdwo{} section of a location list. The format of
522 \dotdebuglocdwo{} location list entries is slightly different
523 than that in \dotdebugloc.
524 See Section \refersec{chap:locationlistsinsplitobjectfiles} for details.
527 \itembfnl{(k) \dotdebuginfo{} to \dotdebugaddr}
528 The value of the \DWATaddrbase{} attribute in the
529 \DWTAGcompileunit, \DWTAGpartialunit{} or \DWTAGtypeunit{} DIE
530 is the offset in the \dotdebugaddr{} section of the machine
531 addresses for that unit.
532 \DWFORMaddrx, \DWOPaddrx{} and \DWOPconstx{} contain indices
533 relative to that offset.