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}
40 \node(zcircs) at (-1, 5 ) [circ] {(s)};
41 \node(zlinkb) at ( 0, 1.5) [link] {To compilation unit~~(b)};
42 \node(zsectpub) at ( 0, 0.0) [sect] {\begin{tabular}{c}
46 \draw[thick,angle 90-] (zcircs) -- (zsectinf);
47 \draw[thick,-to reversed] (zlinka) -- (zsectara);
48 \draw[thick,angle 90-] (zsectinf) -- (zlinka);
49 \draw[thick,-angle 90] (zlinkb) -- (zsectinf);
50 \draw[thick,to reversed-] (zsectpub) -- (zlinkb);
52 % The second column, similarly
54 \node(zsectfra) at (5, 15.0) [sect] {\dotdebugframe};
55 \node(zlinkc) at (5, 13.5) [link] {To abbreviations~~(c)};
56 \node(zlinkd) at (5, 12.1) [link] {\DWFORMstrp{}~~(d)};
57 \node(zlinke) at (5, 10.4) [link] {\begin{tabular}{c}
58 \DWATstroffsetsbase \\
59 \DWFORMstrx{}~~~~~~~~~(e) \\
61 \node(zlinkf) at (5, 8.4) [link] {\begin{tabular}{c}
62 \DWOPcallref{}~~~~~(f) \\
65 \node(zlinki) at (5, 6.7) [link] {\DWATmacros{}~~(g)};
66 \node(zlinkj) at (5, 5.4) [link] {\DWATstmtlist{}~~(h)};
67 \node(zlinkh) at (5, 3.9) [link] {\begin{tabular}{c}
68 \DWATranges{}~~~~(i) \\
71 \node(zlinkg) at (5, 2.4) [link] {\DWATlocation{}, etc.~~(j)};
72 \node(zlinkk) at (5, 0.5) [link] {\begin{tabular}(c)
79 % Links between first and second columns
81 \draw[thick,to reversed-] (zsectinf) -- (zlinkc.west);
82 \draw[thick,to reversed-] (zsectinf) -- (zlinkd.west);
83 \draw[thick,to reversed-] (zsectinf) -- (zlinke.west);
84 \draw[<->,thick] (zsectinf) -- (zlinkf.west);
85 \draw[thick,to reversed-] (zsectinf) -- (zlinkg.west);
86 \draw[thick,to reversed-] (zsectinf) -- (zlinkh.west);
87 \draw[thick,to reversed-] (zsectinf) -- (zlinki.west);
88 \draw[thick,to reversed-] (zsectinf) -- (zlinkj.west);
89 \draw[thick,to reversed-] (zsectinf) -- (zlinkk.north west);
93 \node(zsectabb) at (10, 15.00) [sect] {\dotdebugabbrev};
94 \node(zsectstr) at (10, 13.75) [sect] {\dotdebugstr};
95 \node(zlinkl) at (10, 12.50) [link] {To strings~~(l)};
96 \node(zsectstx) at (10, 11.25) [sect] {\dotdebugstroffsets};
97 \node(zlinkm) at (10, 9.50) [link] {\begin{tabular}{c}
98 \DWMACROdefineindirectx \\
99 \DWMACROundefindirectx \\
102 \node(zsectmac) at (10, 7.80) [sect] {\dotdebugmacro};
103 \node(zlinkn) at (10, 6.40) [link] {\begin{tabular}{c}
104 macroinfo header~~~~~~(n)\\
107 \node(zsectlin) at (10, 5.00) [sect] {\dotdebugline};
108 \node(zsectran) at (10, 3.85) [sect] {\dotdebugranges};
109 \node(zsectloc) at (10, 2.70) [sect] {\dotdebugloc{}};
110 \node(zlinko) at (10, 1.20) [link] {\begin{tabular}{c}
114 \node(zsectadx) at (10, -0.25) [sect] {\dotdebugaddr{}};
116 \draw[thick,to reversed-] (zsectstx) -- (zlinkl);
117 \draw[thick,-angle 90] (zlinkl) -- (zsectstr);
118 \draw[thick,to reversed-] (zsectmac) -- (zlinkm);
119 \draw[thick,-angle 90] (zlinkm) -- (zsectstx);
120 \draw[thick,to reversed-] (zsectmac) -- (zlinkn);
121 \draw[thick,-angle 90] (zlinkn) -- (zsectlin);
122 \draw[thick,to reversed-] (zsectloc) -- (zlinko);
123 \draw[thick,-angle 90] (zlinko) -- (zsectadx);
125 % Links between second and third colums
127 \draw[thick,-angle 90] (zlinkc.east) -- (zsectabb.west);
128 \draw[thick,-angle 90] (zlinkd.east) -- (zsectstr.west);
129 \draw[thick,-angle 90] (zlinke.east) -- (zsectstx.west);
130 \draw[thick,-angle 90] (zlinkg.east) -- (zsectloc.west);
131 \draw[thick,-angle 90] (zlinkh.east) -- (zsectran.west);
132 \draw[thick,-angle 90] (zlinki.east) -- (zsectmac.west);
133 \draw[thick,-angle 90] (zlinkj.east) -- (zsectlin.west);
134 \draw[thick,-angle 90] (zlinkk.east) -- (zsectadx.west);
138 \node(zlinky) at (15.6, 10.5) [link] {\begin{tabular}{c}
139 \DWMACROdefineindirect \\
140 \DWMACROundefindirect \\
143 \node(zlinkz) at (15.6, 6.4) [link] {\begin{tabular}{c}
144 \DWMACROtransparentinclude \\
147 \node(zlinkx) at (15.6, 3.8) [link] {\DWFORMlinestrp~(r)};
148 \node(zsectlns) at (15.6, 2.0) [sect] {\dotdebuglinestr};
149 \node(zcircsp) at (15.6, 0.5) [circ] {(s)'};
151 \draw[thick,to reversed-] (zsectmac.east) -- (zlinky);
152 \draw[thick,-angle 90] (zlinky) -- (zsectstr.east);
153 \draw[<->,thick] (zsectmac.east) -- (zlinkz);
154 \draw[thick,to reversed-] (zsectlin.east) -- (zlinkx);
155 \draw[thick,-angle 90] (zlinkx) -- (zsectlns);
156 \draw[thick,-angle 90] (zcircsp) -- (zsectlns);
160 \caption{Debug section relationships}
161 \label{fig:debugsectionrelationships}
167 \textbf{Notes for Figure \ref{fig:debugsectionrelationships}}
170 \itembfnl{(a) \dotdebugaranges{} to \dotdebuginfo}
171 The \texttt{debug\_info\_offset} value in
173 the offset in the \dotdebuginfo{} section of the
174 corresponding compilation unit header (not the compilation
178 \itembfnl{(b) \dotdebugnames{} to \dotdebuginfo}
179 The \texttt{debug\_info\_offset} value in the header is the offset in the
180 \dotdebuginfo{} section of the
181 corresponding compilation unit header (not
182 the compilation unit entry).
185 \itembfnl{(c) \dotdebuginfo{} to \dotdebugabbrev}
186 The \texttt{debug\_abbrev\_offset} value in the header is the offset in the
188 section of the abbreviations for that compilation unit.
191 \itembfnl{(d) \dotdebuginfo{} to \dotdebugstr}
192 Attribute values of class string may have form
194 value is the offset in the \dotdebugstr{}
195 section of the corresponding string.
198 \itembfnl{(e) \dotdebuginfo{} to \dotdebugstroffsets}
199 The value of the \DWATstroffsetsbase{} attribute in a
200 \DWTAGcompileunit{}, \DWTAGtypeunit{} or \DWTAGpartialunit{}
201 DIE is the offset in the
202 \dotdebugstroffsets{} section of the
203 \addtoindex{string offsets table}
205 In addition, attribute values of class string may have form
206 \DWFORMstrx, whose value is an index into the
207 string offsets table.
210 \itembfnl{(f) \dotdebuginfo{} to \dotdebuginfo}
211 The operand of the \DWOPcallref{}
212 DWARF expression operator is the
213 offset of a debugging information entry in the
214 \dotdebuginfo{} section of another compilation.
215 Similarly for attribute operands that use
219 \itembfnl{(g) \dotdebuginfo{} to \dotdebugmacro}
220 An attribute value of class
221 \livelink{chap:classmacptr}{macptr} (specifically form
222 \DWFORMsecoffset) is an
224 \dotdebugmacro{} section
225 of the beginning of the macro information for the referencing unit.
228 \itembfnl{(h) \dotdebuginfo{} to \dotdebugline}
229 An attribute value of class
230 \livelink{chap:classlineptr}{lineptr} (specifically form
233 \dotdebugline{} section of the
234 beginning of the line number information for the referencing unit.
238 \itembfnl{(i) \dotdebuginfo{} to \dotdebugranges}
239 An attribute value of class \livelink{chap:classrangelistptr}{rangelistptr}
242 is an offset within the \dotdebugranges{} section of
246 \itembfnl{(j) \dotdebuginfo{} to \dotdebugloc}
247 An attribute value of class \livelink{chap:classloclistptr}{loclistptr}
250 is an offset within the \dotdebugloc{}
252 \addtoindex{location list}.
255 \itembfnl{(k) \dotdebuginfo{} to \dotdebugaddr}
256 The value of the \DWATaddrbase{} attribute in the
257 \DWTAGcompileunit{} or \DWTAGpartialunit{} DIE is the
258 offset in the \dotdebugaddr{} section of the machine
259 addresses for that unit.
260 \DWFORMaddrx, \DWOPaddrx{} and \DWOPconstx{} contain
261 indices relative to that offset.
264 \itembfnl{(l) \dotdebugstroffsets{} to \dotdebugstr}
265 Entries in the string offsets table
266 are offsets to the corresponding string text in the
267 \dotdebugstr{} section.
270 \itembfnl{(m) \dotdebugmacro{} to \dotdebugstroffsets}
271 The second operand of a
272 \DWMACROdefineindirectx{} or \DWMACROundefindirectx{}
273 macro information entry is an index
274 into the string offset table in the
275 \dotdebugstroffsets{} section.
278 \itembfnl{(n) \dotdebugmacro{} to \dotdebugline}
279 The second operand of
280 \DWMACROstartfile{} refers to a file entry in the
281 \dotdebugline{} section relative to the start
282 of that section given in the macro information header.
285 \itembfnl{(o) \dotdebugloc{} to \dotdebugaddr}
286 \DWOPaddrx{} and \DWOPconstx{} operators that occur in the
287 \dotdebugloc{} section refer indirectly to the
288 \dotdebugaddr{} section by way of the
289 \DWATaddrbase{} attribute in the associated \dotdebuginfo{}
293 \itembfnl{(p) \dotdebugmacro{} to \dotdebugstr}
294 The second operand of a
295 \DWMACROdefineindirect{} or \DWMACROundefindirect{} macro information
296 entry is an index into the string table in the
297 \dotdebugstr{} section.
301 \itembfnl{(q) \dotdebugmacro{} to \dotdebugmacro}
303 \DWMACROtransparentinclude{} macro information
304 entry is an offset into another part of the
305 \dotdebugmacro{} section to the header for the
306 sequence to be transparently included.
310 \itembfnl{(r) \dotdebugline{} to \dotdebuglinestr}
311 The value of a \DWFORMlinestrp{} form refers to a
312 string section specific to the line number table.
313 This form can be used in a \dotdebugline{} section
314 (as well as in a \dotdebuginfo{} section).
317 \itembfnl{(s) \dotdebuginfo{} to \dotdebuglinestr}
318 The value of a \DWFORMlinestrp{} form refers to a
319 string section specific to the line number table.
320 This form can be used in a \dotdebuginfo{} section
321 (as well as in a \dotdebugline{} section).\footnote{
322 The circled (s) connects to the circled
323 (s)' via hyperspace (a wormhole).}
333 [sect/.style={rectangle, rounded corners=10pt, draw, fill=blue!15,
334 inner sep=.2cm, minimum width=4.0cm},
335 link/.style={rectangle, draw,
336 inner sep=.2cm, minimum width=4.5cm}]
338 \fill[yellow!50] (7.5,-1) -- (7.5,14.5) -- (19,14.5) -- (19,-1) -- cycle;
340 \node(ysectabb) at ( 5, 13.5) [sect] {\dotdebugabbrev};
341 \node(ysectadd) at ( 2, 12.0) [sect] {\dotdebugaddr};
342 \node(ysectara) at ( 0, 10.5) [sect] {\dotdebugaranges};
343 \node(ysectfra) at ( 0, 9.0) [sect] {\dotdebugframe};
344 \node(ysectlin) at ( 0, 7.5) [sect] {\dotdebugline};
345 \node(ysectlis) at ( 0, 6.0) [sect] {\dotdebuglinestr};
346 \node(ysectnam) at ( 0, 4.5) [sect] {\dotdebugnames};
347 \node(ysectran) at ( 0, 3.0) [sect] {\dotdebugranges};
348 \node(ysectstr) at ( 2, 1.5) [sect] {\dotdebugstr};
349 \node(ysectsto) at ( 5, 0.0) [sect] {\dotdebugstroffsets};
351 \node(ysectinf) at ( 5, 7) [sect] {\begin{tabular}{c}
356 \node(ysectinfdwo) at (10.5,7) [sect] {\begin{tabular}{c}
363 \node(ysectabbdwo) at (10.5, 13.5) [sect] {\dotdebugabbrevdwo};
364 \node(ysectlindwo) at (16.0, 7.5) [sect] {\dotdebuglinedwo};
365 \node(ysectlocdwo) at (16.0, 11.0) [sect] {\dotdebuglocdwo};
366 \node(ysectmacdwo) at (16.0, 4.5) [sect] {\dotdebugmacrodwo};
367 \node(ysectstrdwo) at (13.0, 2.0) [sect] {\dotdebugstrdwo};
368 \node(ysectstodwo) at (10.5, 0.0) [sect] {\dotdebugstroffsetsdwo};
370 \draw[thick,-angle 90] (ysectinf) -- (ysectabb) node[midway, right] {(c)};
371 \draw[thick,-angle 90] (ysectinf) -- (ysectadd) node[midway, right] {(k)};
372 \draw[thick,-angle 90] (ysectara.east) -- (ysectinf) node[midway, left] {(a)};
373 \draw[thick,-angle 90] (ysectinf) -- (ysectlin) node[midway, above] {(h)};
374 \draw[thick,-angle 90] (ysectlin) -- (ysectlis) node[midway, right] {(l)};
375 \draw[thick,-angle 90] (ysectnam.east) -- (ysectinf) node[midway, left] {(b)};
376 \draw[thick,-angle 90] (ysectinf) -- (ysectran.east) node[left, near end] {(i)};
377 \draw[thick,-angle 90] (ysectinf) -- (ysectstr) node[midway, right] {(d)};
378 \draw[thick,-angle 90] (ysectinf) -- (ysectsto) node[midway, right] {(e)};
379 \draw[thick,-angle 90] (ysectsto) -- (ysectstr) node[midway, right] {(l)};
381 \draw[dashed, thick,-angle 90] (ysectinf) .. controls (7.5, 12) ..(ysectinfdwo)
382 node[midway, above] {(did)};
384 \draw[thick,-angle 90] (ysectinfdwo) -- (ysectabbdwo) node[midway, right] {(co)};
385 \draw[thick,-angle 90] (ysectinfdwo) -- (ysectlindwo) node[midway, above] {(ho)};
386 \draw[thick,-angle 90] (ysectinfdwo) -- (ysectlocdwo.west) node[midway, below] {(jo)};
387 \draw[thick,-angle 90] (ysectinfdwo) -- (ysectmacdwo.west) node[near end, above] {(go)};
388 \draw[thick,-angle 90] (ysectinfdwo) -- (ysectstrdwo) node[midway, right] {(do)};
389 \draw[thick,-angle 90] (ysectinfdwo) -- (ysectstodwo) node[midway, left] {(eo)};
391 \draw[thick,-angle 90] (ysectstodwo) -- (ysectstrdwo) node[near end, below] {(lo)};
392 \draw[thick,-angle 90] (ysectmacdwo) -- (ysectstrdwo) node[midway, left] {(po)};
393 \draw[thick,-angle 90] (ysectmacdwo) .. controls (16.5, 1) .. (ysectstodwo.east)
394 node[near start, left] {(mo)};
395 \draw[thick,-angle 90] (ysectlindwo.east) .. controls (19,4) and (18, 0) .. (ysectstodwo.east)
396 node[very near start, left] {(lmo)};
398 \draw (0, 14) node {\begin{tabular}{l} Skeleton DWARF \\ in executable \end{tabular}};
399 \draw (17, 14) node {\begin{tabular}{r} Split DWARF \\ in separate object \end{tabular}};
402 \caption{Split DWARF section relationships}
403 \label{fig:splitdwarfsectionrelationships}
409 \textbf{Notes for Figure \ref{fig:splitdwarfsectionrelationships}}
412 \itembfnl{(a) \dotdebugaranges{} to \dotdebuginfo}
413 The \texttt{debug\_info\_offset} field in the header is the
414 offset in the \dotdebuginfo{} section of the corresponding
415 compilation unit header of the skeleton \dotdebuginfo{} section
416 (not the compilation unit entry). The \DWATdwoid{} and
417 \DWATdwoname{} attributes in the \dotdebuginfo{} skeleton
418 connect the ranges to the full compilation unit in \dotdebuginfodwo.
420 \itembfnl{(b) \dotdebugnames{} to \dotdebuginfo}
421 The \dotdebugnames{} section offsets lists provide an offset
422 for the skeleton compilation unit and eight
423 byte signatures for the type units that appear only in the
424 \dotdebuginfodwo. The DIE offsets for these
425 compilation units and type units refer to the DIEs in the
426 \dotdebuginfodwo{} section for the respective
427 compilation unit and type units.
429 \itembfnl{(c) \dotdebuginfo{} skeleton to \dotdebugabbrev}
430 The \texttt{debug\_abbrev\_offset} value in the header is
431 the offset in the \dotdebugabbrev{} section of the
432 abbreviations for that compilation unit skeleton.
434 \itembfnl{(co) \dotdebuginfodwo{} to \dotdebugabbrevdwo}
435 The \texttt{debug\_abbrev\_offset} value in the header
436 is the offset in the \dotdebugabbrevdwo{} section of the
437 abbreviations for that compilation unit.
439 \itembfnl{(d) \dotdebuginfo{} to \dotdebugstr}
440 Attribute values of class string may have form \DWFORMstrp,
441 whose value is an offset in the
442 \dotdebugstr{} section of the corresponding string.
444 \itembfnl{(did) \dotdebuginfo{} to \dotdebuginfodwo}
445 The \DWATdwoname{} and \DWATdwoid{} are the file name
446 and hash which identify the file with
447 the \texttt{.dwo} data. Both \dotdebuginfo{} and
448 \dotdebuginfodwo{} compilation units should contain
449 \DWATdwoid{} so the two can be matched. \DWATdwoname{}
450 is only needed in the \dotdebuginfo{}
451 skeleton compilation unit.
453 \itembfnl{(do) \dotdebuginfodwo{} to \dotdebugstrdwo}
454 Attribute values of class string may have form
455 \DWFORMstrp, whose value is an offset in the
456 \dotdebugstrdwo{} section of the corresponding string.
458 \itembfnl{(e) \dotdebuginfo{} to \dotdebugstroffsets}
459 Attribute values of class string may have form
460 \DWFORMstrx, whose value is an index into the
461 \dotdebugstroffsets{} section for the corresponding string.
464 \itembfnl{(eo)\dotdebuginfodwo{} to \dotdebugstroffsetsdwo}
465 Attribute values of class string may have form
466 \DWFORMstrx, whose value is an index into the
467 \dotdebugstroffsetsdwo{} section for the corresponding string.
469 \itembfnl{(fo) \dotdebuginfodwo{} to \dotdebuginfodwo}
470 The operand of the \DWOPcallref{} DWARF expression
471 operator is the offset of a debugging
472 information entry in the \dotdebuginfodwo{} section of
473 another compilation unit. Similarly for attribute
474 operands that use \DWFORMrefaddr.
475 See Section \refersec{chap:controlflowoperations}.
477 \itembfnl{(go) \dotdebuginfodwo{} to \dotdebugmacrodwo}
478 An attribute of class \CLASSmacptr{} (specifically \DWATmacros{}
479 with form \DWFORMsecoffset{}) is an offset within the
480 \dotdebugmacrodwo{} section of the beginning of the macro
481 information for the referencing unit.
483 \itembfnl{(h) \dotdebuginfo{} (skeleton) to \dotdebugline}
484 An attribute value of class \CLASSlineptr{} (specifically
485 \DWATstmtlist{} with form \DWFORMsecoffset)
486 is an offset within the \dotdebugline{} section of the
487 beginning of the line number information for the
490 \itembfnl{(ho) \dotdebuginfodwo{} to \dotdebuglinedwo{} (skeleton)}
491 An attribute value of class \CLASSlineptr{} (specifically
492 \DWATstmtlist{} with form \DWFORMsecoffset)
493 is an offset within the \dotdebuglinedwo{} section of the
494 beginning of the line number header information
495 for the referencing unit (the line table details are not in
496 \dotdebuglinedwo{} but the line header with its list
497 of file names is present).
499 \itembfnl{(i) \dotdebuginfo{} to \dotdebugranges}
500 An attribute value of class \CLASSrangelistptr{}
501 (specifically \DWATranges{} with form
502 \DWFORMsecoffset) is an offset within the \dotdebugranges{}
503 section of a range list.
505 \itembfnl{(jo) \dotdebuginfodwo{} to \dotdebuglocdwo}
506 An attribute value of class \CLASSloclistptr{} (specifically
507 \DWATdatamemberlocation,
514 \DWATuselocation{} or
515 \DWATvtableelemlocation{}
516 with form \DWFORMsecoffset) is an offset within the
517 \dotdebuglocdwo{} section of a location list. The format of
518 \dotdebuglocdwo{} location list entries is slightly different
519 than that in \dotdebugloc.
520 See Section \refersec{chap:locationlistsinsplitobjectfiles} for details.
523 \itembfnl{(k) \dotdebuginfo{} to \dotdebugaddr}
524 The value of the \DWATaddrbase{} attribute in the
525 \DWTAGcompileunit, \DWTAGpartialunit{} or \DWTAGtypeunit{} DIE
526 is the offset in the \dotdebugaddr{} section of the machine
527 addresses for that unit.
528 \DWFORMaddrx, \DWOPaddrx{} and \DWOPconstx{} contain indices
529 relative to that offset.