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 In the figures, a section is shown as a shaded oval with the
10 name of the section inside. References from one section to
11 another are shown by an arrow. In the first figure, the arrow
12 is annotated with an unshaded box which contains an indication
13 of the construct (such as an attribute or form) that encodes
14 the reference. In the second figure, this box is left out
15 for reasons of space in favor of a label annotation that is
16 explained in the subsequent notes.
18 \section{Normal DWARF Section Relationships}
19 Figure \referfol{fig:debugsectionrelationships} illustrates
20 the DWARF section relations without split DWARF object files
21 involved. Similarly, it does not show the
22 relationships between the main debugging sections of an executable
23 or sharable file and a related \addtoindex{supplementary object file}.
25 \section{Split DWARF Section Relationships}
26 Figure \ref{fig:splitdwarfsectionrelationships} illustrates
27 the DWARF section relationships for \splitDWARFobjectfile{s}.
28 However, it does not show the
29 relationships between the main debugging sections of an executable
30 or shareable file and a related \addtoindex{supplementary object file}.
36 [sect/.style={rectangle, rounded corners=10pt, draw, fill=blue!15,
37 inner sep=.2cm, minimum width=4.0cm},
38 link/.style={rectangle, draw,
39 inner sep=.2cm, minimum width=4.5cm},
40 circ/.style={circle, draw, fill=yellow!25,
43 % The first (leftmost) column, first sections, then links, from top to bottom
45 \node(zsectara) at ( 0, 15.0) [sect] {\dotdebugaranges};
46 \node(zlinka) at ( 0, 13.5) [link] {To compilation unit~~(a)};
47 \node(zsectinf) at ( 0, 7.5) [sect] {\begin{tabular}{c}
52 \node(zcircs) at (-1.8,4.0) [circ] {\textit{A}};
53 \node(zlinkb) at ( 0, 1.5) [link] {To compilation unit~~(b)};
54 \node(zsectpub) at ( 0,-0.25) [sect] {\begin{tabular}{c}
58 \draw[thin,triangle 45-] (zcircs) -- (zsectinf);
59 \draw[thin,-to reversed] (zlinka) -- (zsectara);
60 \draw[thin,triangle 45-] (zsectinf) -- (zlinka);
61 \draw[thin,-triangle 45] (zlinkb) -- (zsectinf);
62 \draw[thin,to reversed-] (zsectpub) -- (zlinkb);
64 % The second column, similarly
66 \node(zsectfra) at (5, 15.0) [sect] {\dotdebugframe};
67 \node(zlinkc) at (5, 13.5) [link] {To abbreviations~~(c)};
68 \node(zlinkd) at (5, 12.1) [link] {\DWFORMstrp{}~~(d)};
69 \node(zlinke) at (5, 10.4) [link] {\begin{tabular}{c}
70 \DWATstroffsetsbase \\
71 \DWFORMstrx{}~~~~~~~~~(e) \\
73 \node(zlinkf) at (5, 8.4) [link] {\begin{tabular}{c}
74 \DWOPcallref{}~~~~~(f) \\
77 \node(zlinki) at (5, 6.7) [link] {\DWATmacros{}~~(g)};
78 \node(zlinkj) at (5, 5.4) [link] {\DWATstmtlist{}~~(h)};
79 \node(zlinkh) at (5, 3.9) [link] {\begin{tabular}{c}
80 \DWATranges{}~~~~(i) \\
83 \node(zlinkg) at (5, 2.4) [link] {\DWATlocation{}, etc.~~(j)};
84 \node(zlinkk) at (5, 0.5) [link] {\begin{tabular}(c)
91 % Links between first and second columns
93 \draw[thin,to reversed-] (zsectinf) -- (zlinkc.west);
94 \draw[thin,to reversed-] (zsectinf) -- (zlinkd.west);
95 \draw[thin,to reversed-] (zsectinf) -- (zlinke.west);
96 \draw[thin, triangle 45-triangle 45] (zsectinf) -- (zlinkf.west);
97 \draw[thin,to reversed-] (zsectinf) -- (zlinkg.west);
98 \draw[thin,to reversed-] (zsectinf) -- (zlinkh.west);
99 \draw[thin,to reversed-] (zsectinf) -- (zlinki.west);
100 \draw[thin,to reversed-] (zsectinf) -- (zlinkj.west);
101 \draw[thin,to reversed-] (zsectinf) -- (zlinkk.north west);
105 \node(zsectabb) at (10, 15.00) [sect] {\dotdebugabbrev};
106 \node(zsectstr) at (10, 13.75) [sect] {\dotdebugstr};
107 \node(zlinkl) at (10, 12.50) [link] {To strings~~(l)};
108 \node(zsectstx) at (10, 11.25) [sect] {\dotdebugstroffsets};
109 \node(zlinkm) at (10, 9.50) [link] {\begin{tabular}{c}
110 \DWMACROdefinestrx \\
114 \node(zsectmac) at (10, 7.80) [sect] {\dotdebugmacro};
115 \node(zlinkn) at (10, 6.40) [link] {\begin{tabular}{c}
116 macroinfo header~~~~~~(n)\\
119 \node(zsectlin) at (10, 5.00) [sect] {\dotdebugline};
120 \node(zsectran) at (10, 3.85) [sect] {\dotdebugrnglists};
121 \node(zsectloc) at (10, 2.70) [sect] {\dotdebugloclists{}};
122 \node(zlinko) at (10, 1.20) [link] {\begin{tabular}{c}
126 \node(zsectadx) at (10, -0.25) [sect] {\dotdebugaddr{}};
128 \draw[thin,to reversed-] (zsectstx) -- (zlinkl);
129 \draw[thin,-triangle 45] (zlinkl) -- (zsectstr);
130 \draw[thin,to reversed-] (zsectmac) -- (zlinkm);
131 \draw[thin,-triangle 45] (zlinkm) -- (zsectstx);
132 \draw[thin,to reversed-] (zsectmac) -- (zlinkn);
133 \draw[thin,-triangle 45] (zlinkn) -- (zsectlin);
134 \draw[thin,to reversed-] (zsectloc) -- (zlinko);
135 \draw[thin,-triangle 45] (zlinko) -- (zsectadx);
137 % Links between second and third colums
139 \draw[thin,-triangle 45] (zlinkc.east) -- (zsectabb.west);
140 \draw[thin,-triangle 45] (zlinkd.east) -- (zsectstr.west);
141 \draw[thin,-triangle 45] (zlinke.east) -- (zsectstx.west);
142 \draw[thin,-triangle 45] (zlinkg.east) -- (zsectloc.west);
143 \draw[thin,-triangle 45] (zlinkh.east) -- (zsectran.west);
144 \draw[thin,-triangle 45] (zlinki.east) -- (zsectmac.west);
145 \draw[thin,-triangle 45] (zlinkj.east) -- (zsectlin.west);
146 \draw[thin,-triangle 45] (zlinkk.east) -- (zsectadx.west);
150 \node(zlinky) at (15.6, 10.5) [link] {\begin{tabular}{c}
151 \DWMACROdefinestrp \\
155 \node(zlinkz) at (15.6, 6.4) [link] {\begin{tabular}{c}
159 \node(zcircsp) at (17.4, 4.0) [circ] {\textit{A}};
160 \node(zlinkx) at (15.6, 2.0) [link] {\DWFORMlinestrp~(r, s)};
161 \node(zsectlns) at (15.6,-0.25) [sect] {\dotdebuglinestr};
164 \draw[thin,to reversed-] (zsectmac.east) -- (zlinky);
165 \draw[thin,-triangle 45] (zlinky) -- (zsectstr.east);
166 \draw[triangle 45-triangle 45] (zsectmac.east) -- (zlinkz);
167 \draw[thin,to reversed-] (zcircsp) -- (zlinkx);
168 \draw[thin,to reversed-] (zsectlin.east) -- (zlinkx);
169 \draw[thin,-triangle 45] (zlinkx) -- (zsectlns);
173 \caption{Debug section relationships}
174 \label{fig:debugsectionrelationships}
180 \textbf{Notes for Figure \ref{fig:debugsectionrelationships}}
183 \itembfnl{(a) \dotdebugaranges{} to \dotdebuginfo}
184 The \texttt{debug\_info\_offset} value in
186 the offset in the \dotdebuginfo{} section of the
187 corresponding compilation unit header (not the compilation
191 \itembfnl{(b) \dotdebugnames{} to \dotdebuginfo}
192 The list of compilation units following the header contains the offsets in the
193 \dotdebuginfo{} section of the
194 corresponding compilation unit headers (not
195 the compilation unit entries).
198 \itembfnl{(c) \dotdebuginfo{} to \dotdebugabbrev}
199 The \HFNdebugabbrevoffset{} value in the header is the offset in the
201 section of the abbreviations for that compilation unit.
204 \itembfnl{(d) \dotdebuginfo{} to \dotdebugstr}
205 Attribute values of class string may have form
207 value is the offset in the \dotdebugstr{}
208 section of the corresponding string.
211 \itembfnl{(e) \dotdebuginfo{} to \dotdebugstroffsets}
212 The value of the \DWATstroffsetsbase{} attribute in a
213 \DWTAGcompileunit{}, \DWTAGtypeunit{} or \DWTAGpartialunit{}
214 DIE is the offset in the
215 \dotdebugstroffsets{} section of the
216 \addtoindex{string offsets table}
218 In addition, attribute values of class string may have form
219 \DWFORMstrx, whose value is an index into the
220 string offsets table.
223 \itembfnl{(f) \dotdebuginfo{} to \dotdebuginfo}
224 The operand of the \DWOPcallref{}
225 DWARF expression operator is the
226 offset of a debugging information entry in the
227 \dotdebuginfo{} section of another compilation.
228 Similarly for attribute operands that use
232 \itembfnl{(g) \dotdebuginfo{} to \dotdebugmacro}
233 An attribute value of class
234 \livelink{chap:classmacptr}{macptr} (specifically form
235 \DWFORMsecoffset) is an
237 \dotdebugmacro{} section
238 of the beginning of the macro information for the referencing unit.
241 \itembfnl{(h) \dotdebuginfo{} to \dotdebugline}
242 An attribute value of class
243 \livelink{chap:classlineptr}{lineptr} (specifically form
246 \dotdebugline{} section of the
247 beginning of the line number information for the referencing unit.
252 \itembfnl{(i) \dotdebuginfo{} to \dotdebugrnglists}
253 An attribute value of class \CLASSrnglist{}
254 (specifically form \DWFORMrnglistx{} or \DWFORMsecoffset)
255 is an index or offset within the \dotdebugrnglists{}
257 section of a \addtoindex{range list}.
261 \itembfnl{(j) \dotdebuginfo{} to \dotdebugloclists}
262 An attribute value of class \CLASSloclist{}
263 (specifically form \DWFORMloclistx or \DWFORMsecoffset)
264 is an index or offset within the \dotdebugloclists{}
266 section of a \addtoindex{location list}.
269 \itembfnl{(k) \dotdebuginfo{} to \dotdebugaddr}
270 The value of the \DWATaddrbase{} attribute in the
271 \DWTAGcompileunit{} or \DWTAGpartialunit{} DIE is the
272 offset in the \dotdebugaddr{} section of the machine
273 addresses for that unit.
274 \DWFORMaddrx, \DWOPaddrx{} and \DWOPconstx{} contain
275 indices relative to that offset.
278 \itembfnl{(l) \dotdebugstroffsets{} to \dotdebugstr}
279 Entries in the string offsets table
280 are offsets to the corresponding string text in the
281 \dotdebugstr{} section.
284 \itembfnl{(m) \dotdebugmacro{} to \dotdebugstroffsets}
285 The second operand of a
286 \DWMACROdefinestrx{} or \DWMACROundefstrx{}
287 macro information entry is an index
288 into the string offset table in the
289 \dotdebugstroffsets{} section.
292 \itembfnl{(n) \dotdebugmacro{} to \dotdebugline}
293 The second operand of
294 \DWMACROstartfile{} refers to a file entry in the
295 \dotdebugline{} section relative to the start
296 of that section given in the macro information header.
299 \itembfnl{(o) \dotdebugloclists{} to \dotdebugaddr}
300 \DWOPaddrx{} and \DWOPconstx{} operators that occur in the
301 \dotdebugloclists{} section refer indirectly to the
302 \dotdebugaddr{} section by way of the
303 \DWATaddrbase{} attribute in the associated \dotdebuginfo{}
307 \itembfnl{(p) \dotdebugmacro{} to \dotdebugstr}
308 The second operand of a
309 \DWMACROdefinestrp{} or \DWMACROundefstrp{} macro information
310 entry is an index into the string table in the
311 \dotdebugstr{} section.
315 \itembfnl{(q) \dotdebugmacro{} to \dotdebugmacro}
317 \DWMACROimport{} macro information
318 entry is an offset into another part of the
319 \dotdebugmacro{} section to the header for the
320 sequence to be replicated.
324 \itembfnl{(r) \dotdebugline{} to \dotdebuglinestr}
325 The value of a \DWFORMlinestrp{} form refers to a
326 string section specific to the line number table.
327 This form can be used in a \dotdebugline{} section
328 (as well as in a \dotdebuginfo{} section).
331 \itembfnl{(s) \dotdebuginfo{} to \dotdebuglinestr}
332 The value of a \DWFORMlinestrp{} form refers to a
333 string section specific to the line number table.
334 This form can be used in a \dotdebuginfo{} section
335 (as well as in a \dotdebugline{} section).\footnote{
336 The circled (s) connects to the circled
337 (s)' via hyperspace (a wormhole).}
347 [sect/.style={rectangle, rounded corners=10pt, draw, fill=blue!15,
348 inner sep=.2cm, minimum width=4.0cm},
349 link/.style={rectangle, draw,
350 inner sep=.2cm, minimum width=4.5cm}]
352 \fill[yellow!25] (7.5,-1) -- (7.5,14.5) -- (19,14.5) -- (19,-1) -- cycle;
356 \node(ysectabb) at ( 5, 13.5) [sect] {\dotdebugabbrev};
357 \node(ysectadd) at ( 2, 12.0) [sect] {\dotdebugaddr};
358 \node(ysectara) at ( 0, 10.5) [sect] {\dotdebugaranges};
359 \node(ysectfra) at ( 0, 9.0) [sect] {\dotdebugframe};
360 \node(ysectlin) at ( 0, 7.5) [sect] {\dotdebugline};
361 \node(ysectlis) at ( 0, 5.7) [sect] {\dotdebuglinestr};
362 \node(ysectnam) at ( 0, 4.0) [sect] {\dotdebugnames};
363 \node(ysectstr) at ( 2, 2.0) [sect] {\dotdebugstr};
364 \node(ysectsto) at ( 5, 0.0) [sect] {\dotdebugstroffsets};
366 \node(ysectinf) at ( 5, 7) [sect] {\begin{tabular}{c}
373 \node(ysectinfdwo) at (10.5,7) [sect] {\begin{tabular}{c}
380 \node(ysectabbdwo) at (10.5, 13.5) [sect] {\dotdebugabbrevdwo};
381 \node(ysectlocdwo) at (14.0, 11.5) [sect] {\dotdebugloclistsdwo};
382 \node(ysectrandwo) at (15.8, 9.5) [sect] {\dotdebugrnglistsdwo};
383 \node(ysectlindwo) at (16.0, 7.0) [sect] {\dotdebuglinedwo};
384 \node(ysectmacdwo) at (16.0, 4.5) [sect] {\dotdebugmacrodwo};
385 \node(ysectstrdwo) at (13.5, 2.0) [sect] {\dotdebugstrdwo};
386 \node(ysectstodwo) at (10.5, 0.0) [sect] {\dotdebugstroffsetsdwo};
388 \draw[thin,-triangle 45] (ysectinf) -- (ysectabb) node[midway, right] {(c)};
389 \draw[thin,-triangle 45] (ysectinf) -- (ysectadd) node[midway, right] {(k)};
390 \draw[thin,-triangle 45] (ysectara.east) -- (ysectinf) node[midway, left] {(a)};
391 \draw[thin,-triangle 45] (ysectinf) -- (ysectlin.east) node[midway, above] {(h)};
392 \draw[thin,-triangle 45] (ysectlin) -- (ysectlis) node[midway, right] {(l)};
393 \draw[thin,-triangle 45] (ysectnam.east) -- (ysectinf) node[midway, left] {(b)};
394 \draw[thin,-triangle 45] (ysectinf) -- (ysectstr) node[midway, right] {(d)};
395 \draw[thin,-triangle 45] (ysectinf) -- (ysectsto) node[midway, right] {(e)};
396 \draw[thin,-triangle 45] (ysectsto) -- (ysectstr) node[midway, right] {(l)};
398 \draw[dashed, thick,-triangle 45] (ysectinf) .. controls (7.5, 11) ..(ysectinfdwo)
399 node[midway, above] {(did)};
401 \draw[thin,-triangle 45] (ysectinfdwo) -- (ysectabbdwo) node[midway, left] {(co)};
402 \draw[thin,-triangle 45] (ysectinfdwo) -- (ysectlindwo.west) node[midway, above] {(ho)};
403 \draw[thin,-triangle 45] (ysectinfdwo) -- (ysectrandwo.west) node[midway, above] {(io)};
404 \draw[thin,-triangle 45] (ysectinfdwo) -- (ysectlocdwo.west) node[midway, right] {(jo)};
405 \draw[thin,-triangle 45] (ysectinfdwo) -- (ysectmacdwo.west) node[midway, above] {(go)};
406 \draw[thin,-triangle 45] (ysectinfdwo) -- (ysectstrdwo) node[midway, right] {(do)};
407 \draw[thin,-triangle 45] (ysectinfdwo) -- (ysectstodwo) node[midway, left] {(eo)};
409 \draw[thin,-triangle 45] (ysectstodwo) -- (ysectstrdwo) node[near end, below] {(lo)};
410 \draw[thin,-triangle 45] (ysectmacdwo) -- (ysectstrdwo) node[midway, left] {(po)};
411 \draw[thin,-triangle 45] (ysectmacdwo) .. controls (16.2, 1) .. (ysectstodwo.east)
412 node[very near start, right] {(mo)};
413 \draw[thin,-triangle 45] (ysectlindwo.east) .. controls (19,4) and (18, 0) .. (ysectstodwo.east)
414 node[very near start, left] {(lmo)};
416 \draw (0, 14) node {\begin{tabular}{l} Skeleton DWARF \\ in executable \end{tabular}};
417 \draw (17, 14) node {\begin{tabular}{r} Split DWARF \\ in separate object \end{tabular}};
420 \caption{Split DWARF section relationships}
421 \label{fig:splitdwarfsectionrelationships}
427 \textbf{Notes for Figure \ref{fig:splitdwarfsectionrelationships}}
430 \itembfnl{(a) \dotdebugaranges{} to \dotdebuginfo}
431 The \texttt{debug\_info\_offset} field in the header is the
432 offset in the \dotdebuginfo{} section of the corresponding
433 compilation unit header of the skeleton \dotdebuginfo{} section
434 (not the compilation unit entry). The \DWATdwoname{} attribute
435 in the \dotdebuginfo{} skeleton connects
436 the ranges to the full compilation unit in \dotdebuginfodwo.
438 \itembfnl{(b) \dotdebugnames{} to \dotdebuginfo}
439 The \dotdebugnames{} section offsets lists provide an offset
440 for the skeleton compilation unit and eight
441 byte signatures for the type units that appear only in the
442 \dotdebuginfodwo. The DIE offsets for these
443 compilation units and type units refer to the DIEs in the
444 \dotdebuginfodwo{} section for the respective
445 compilation unit and type units.
447 \itembfnl{(c) \dotdebuginfo{} skeleton to \dotdebugabbrev}
448 The \HFNdebugabbrevoffset{} value in the header is
449 the offset in the \dotdebugabbrev{} section of the
450 abbreviations for that compilation unit skeleton.
452 \itembfnl{(co) \dotdebuginfodwo{} to \dotdebugabbrevdwo}
453 The \HFNdebugabbrevoffset{} value in the header
454 is the offset in the \dotdebugabbrevdwo{} section of the
455 abbreviations for that compilation unit.
457 \itembfnl{(d) \dotdebuginfo{} to \dotdebugstr}
458 Attribute values of class string may have form \DWFORMstrp,
459 whose value is an offset in the
460 \dotdebugstr{} section of the corresponding string.
462 \itembfnl{(did) \dotdebuginfo{} to \dotdebuginfodwo}
464 attribute in a skeleton unit identifies the file containing
465 the corresponding \texttt{.dwo} (split) data.
467 \itembfnl{(do) \dotdebuginfodwo{} to \dotdebugstrdwo}
468 Attribute values of class string may have form
469 \DWFORMstrp, whose value is an offset in the
470 \dotdebugstrdwo{} section of the corresponding string.
472 \itembfnl{(e) \dotdebuginfo{} to \dotdebugstroffsets}
473 Attribute values of class string may have form
474 \DWFORMstrx, whose value is an index into the
475 \dotdebugstroffsets{} section for the corresponding string.
478 \itembfnl{(eo)\dotdebuginfodwo{} to \dotdebugstroffsetsdwo}
479 Attribute values of class string may have form
480 \DWFORMstrx, whose value is an index into the
481 \dotdebugstroffsetsdwo{} section for the corresponding string.
483 \itembfnl{(fo) \dotdebuginfodwo{} to \dotdebuginfodwo}
484 The operand of the \DWOPcallref{} DWARF expression
485 operator is the offset of a debugging
486 information entry in the \dotdebuginfodwo{} section of
487 another compilation unit. Similarly for attribute
488 operands that use \DWFORMrefaddr.
489 See Section \refersec{chap:controlflowoperations}.
491 \itembfnl{(go) \dotdebuginfodwo{} to \dotdebugmacrodwo}
492 An attribute of class \CLASSmacptr{} (specifically \DWATmacros{}
493 with form \DWFORMsecoffset{}) is an offset within the
494 \dotdebugmacrodwo{} section of the beginning of the macro
495 information for the referencing unit.
497 \itembfnl{(h) \dotdebuginfo{} (skeleton) to \dotdebugline}
498 An attribute value of class \CLASSlineptr{} (specifically
499 \DWATstmtlist{} with form \DWFORMsecoffset)
500 is an offset within the \dotdebugline{} section of the
501 beginning of the line number information for the
504 \itembfnl{(ho) \dotdebuginfodwo{} to \dotdebuglinedwo{} (skeleton)}
505 An attribute value of class \CLASSlineptr{} (specifically
506 \DWATstmtlist{} with form \DWFORMsecoffset)
507 is an offset within the \dotdebuglinedwo{} section of the
508 beginning of the line number header information
509 for the referencing unit (the line table details are not in
510 \dotdebuglinedwo{} but the line header with its list
511 of file names is present).
514 \itembfnl{(io) \dotdebuginfodwo{} to \dotdebugrnglistsdwo}
515 An attribute value of class \CLASSrnglist{} (specifically
516 \DWATranges{} with form \DWFORMrnglistx{} or \DWFORMsecoffset)
517 is an index or offset within the \dotdebugrnglistsdwo{}
518 section of a \addtoindex{range list}.
519 The format of \dotdebugrnglistsdwo{} location list entries
520 is restricted to a subset of those in \dotdebugrnglists.
521 See Section \refersec{chap:noncontiguousaddressranges} for details.
524 \itembfnl{(jo) \dotdebuginfodwo{} to \dotdebugloclistsdwo}
525 An attribute value of class
527 \CLASSloclist{} (specifically with form \DWFORMloclistx
529 is an index or offset within the \dotdebugloclistsdwo{}
530 section of a \addtoindex{location list.}
531 The format of \dotdebugloclistsdwo{} location list entries
532 is restricted to a subset of those in \dotdebugloclists.
534 See Section \refersec{chap:locationlists} for details.
537 \itembfnl{(k) \dotdebuginfo{} to \dotdebugaddr}
538 The value of the \DWATaddrbase{} attribute in the
539 \DWTAGcompileunit, \DWTAGpartialunit{} or \DWTAGtypeunit{} DIE
540 is the offset in the \dotdebugaddr{} section of the machine
541 addresses for that unit.
542 \DWFORMaddrx, \DWOPaddrx{} and \DWOPconstx{} contain indices
543 relative to that offset.