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\textit{[1,2,3,4]}{}~(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)
86 \DWFORMaddrx\textit{[1,2,3,4]}{} \\
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
222 \DWFORMstrxXNor, whose value is an index into the
223 string offsets table.
226 \itembfnl{(f) \dotdebuginfo{} to \dotdebuginfo}
227 The operand of the \DWOPcallref{}
228 DWARF expression operator is the
229 offset of a debugging information entry in the
230 \dotdebuginfo{} section of another compilation.
231 Similarly for attribute operands that use
235 \itembfnl{(g) \dotdebuginfo{} to \dotdebugmacro}
236 An attribute value of class
237 \livelink{chap:classmacptr}{macptr} (specifically form
238 \DWFORMsecoffset) is an
240 \dotdebugmacro{} section
241 of the beginning of the macro information for the referencing unit.
244 \itembfnl{(h) \dotdebuginfo{} to \dotdebugline}
245 An attribute value of class
246 \livelink{chap:classlineptr}{lineptr} (specifically form
249 \dotdebugline{} section of the
250 beginning of the line number information for the referencing unit.
254 \itembfnl{(i) \dotdebuginfo{} to \dotdebugrnglists}
255 An attribute value of class \CLASSrnglist{}
256 (specifically form \DWFORMrnglistx{} or \DWFORMsecoffset)
257 is an index or offset within the \dotdebugrnglists{}
258 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{}
265 section of a \addtoindex{location list}.
268 \itembfnl{(k) \dotdebuginfo{} to \dotdebugaddr}
269 The value of the \DWATaddrbase{} attribute in the
270 \DWTAGcompileunit{} or \DWTAGpartialunit{} DIE is the
271 offset in the \dotdebugaddr{} section of the machine
272 addresses for that unit.
273 \DWFORMaddrxXN, \DWOPaddrx{} and \DWOPconstx{} contain
274 indices relative to that offset.
277 \itembfnl{(l) \dotdebugstroffsets{} to \dotdebugstr}
278 Entries in the string offsets table
279 are offsets to the corresponding string text in the
280 \dotdebugstr{} section.
283 \itembfnl{(m) \dotdebugmacro{} to \dotdebugstroffsets}
284 The second operand of a
285 \DWMACROdefinestrx{} or \DWMACROundefstrx{}
286 macro information entry is an index
287 into the string offset table in the
288 \dotdebugstroffsets{} section.
291 \itembfnl{(n) \dotdebugmacro{} to \dotdebugline}
292 The second operand of
293 \DWMACROstartfile{} refers to a file entry in the
294 \dotdebugline{} section relative to the start
295 of that section given in the macro information header.
298 \itembfnl{(o) \dotdebugloclists{} to \dotdebugaddr}
299 \DWOPaddrx{} and \DWOPconstx{} operators that occur in the
300 \dotdebugloclists{} section refer indirectly to the
301 \dotdebugaddr{} section by way of the
302 \DWATaddrbase{} attribute in the associated \dotdebuginfo{}
306 \itembfnl{(p) \dotdebugmacro{} to \dotdebugstr}
307 The second operand of a
308 \DWMACROdefinestrp{} or \DWMACROundefstrp{} macro information
309 entry is an index into the string table in the
310 \dotdebugstr{} section.
314 \itembfnl{(q) \dotdebugmacro{} to \dotdebugmacro}
316 \DWMACROimport{} macro information
317 entry is an offset into another part of the
318 \dotdebugmacro{} section to the header for the
319 sequence to be replicated.
323 \itembfnl{(r) \dotdebugline{} to \dotdebuglinestr}
324 The value of a \DWFORMlinestrp{} form refers to a
325 string section specific to the line number table.
326 This form can be used in a \dotdebugline{} section
327 (as well as in a \dotdebuginfo{} section).
330 \itembfnl{(s) \dotdebuginfo{} to \dotdebuglinestr}
331 The value of a \DWFORMlinestrp{} form refers to a
332 string section specific to the line number table.
333 This form can be used in a \dotdebuginfo{} section
334 (as well as in a \dotdebugline{} section).\footnote{
335 The circled (s) connects to the circled
336 (s)' via hyperspace (a wormhole).}
346 [sect/.style={rectangle, rounded corners=10pt, draw, fill=blue!15,
347 inner sep=.2cm, minimum width=4.0cm},
348 link/.style={rectangle, draw,
349 inner sep=.2cm, minimum width=4.5cm}]
351 \fill[yellow!25] (7.5,-1) -- (7.5,14.5) -- (19,14.5) -- (19,-1) -- cycle;
355 \node(ysectabb) at ( 5, 13.5) [sect] {\dotdebugabbrev};
356 \node(ysectadd) at ( 2, 12.0) [sect] {\dotdebugaddr};
357 \node(ysectara) at ( 0, 10.5) [sect] {\dotdebugaranges};
358 \node(ysectfra) at ( 0, 9.0) [sect] {\dotdebugframe};
359 \node(ysectlin) at ( 0, 7.5) [sect] {\dotdebugline};
360 \node(ysectlis) at ( 0, 5.7) [sect] {\dotdebuglinestr};
361 \node(ysectnam) at ( 0, 4.0) [sect] {\dotdebugnames};
362 \node(ysectstr) at ( 2, 2.0) [sect] {\dotdebugstr};
363 \node(ysectsto) at ( 5, 0.0) [sect] {\dotdebugstroffsets};
365 \node(ysectinf) at ( 5, 7) [sect] {\begin{tabular}{c}
372 \node(ysectinfdwo) at (10.5,7) [sect] {\begin{tabular}{c}
379 \node(ysectabbdwo) at (10.5, 13.5) [sect] {\dotdebugabbrevdwo};
380 \node(ysectlocdwo) at (14.0, 11.5) [sect] {\dotdebugloclistsdwo};
381 \node(ysectrandwo) at (15.8, 9.5) [sect] {\dotdebugrnglistsdwo};
382 \node(ysectlindwo) at (16.0, 7.0) [sect] {\dotdebuglinedwo};
383 \node(ysectmacdwo) at (16.0, 4.5) [sect] {\dotdebugmacrodwo};
384 \node(ysectstrdwo) at (13.5, 2.0) [sect] {\dotdebugstrdwo};
385 \node(ysectstodwo) at (10.5, 0.0) [sect] {\dotdebugstroffsetsdwo};
387 \draw[thin,-triangle 45] (ysectinf) -- (ysectabb) node[midway, right] {(c)};
388 \draw[thin,-triangle 45] (ysectinf) -- (ysectadd) node[midway, right] {(k)};
389 \draw[thin,-triangle 45] (ysectara.east) -- (ysectinf) node[midway, left] {(a)};
390 \draw[thin,-triangle 45] (ysectinf) -- (ysectlin.east) node[midway, above] {(h)};
391 \draw[thin,-triangle 45] (ysectlin) -- (ysectlis) node[midway, right] {(l)};
392 \draw[thin,-triangle 45] (ysectnam.east) -- (ysectinf) node[midway, left] {(b)};
393 \draw[thin,-triangle 45] (ysectinf) -- (ysectstr) node[midway, right] {(d)};
394 \draw[thin,-triangle 45] (ysectinf) -- (ysectsto) node[midway, right] {(e)};
395 \draw[thin,-triangle 45] (ysectsto) -- (ysectstr) node[midway, right] {(l)};
397 \draw[dashed, thick,-triangle 45] (ysectinf) .. controls (7.5, 11) ..(ysectinfdwo)
398 node[midway, above] {(did)};
400 \draw[thin,-triangle 45] (ysectinfdwo) -- (ysectabbdwo) node[midway, left] {(co)};
401 \draw[thin,-triangle 45] (ysectinfdwo) -- (ysectlindwo.west) node[midway, above] {(ho)};
402 \draw[thin,-triangle 45] (ysectinfdwo) -- (ysectrandwo.west) node[midway, above] {(io)};
403 \draw[thin,-triangle 45] (ysectinfdwo) -- (ysectlocdwo.west) node[midway, right] {(jo)};
404 \draw[thin,-triangle 45] (ysectinfdwo) -- (ysectmacdwo.west) node[midway, above] {(go)};
405 \draw[thin,-triangle 45] (ysectinfdwo) -- (ysectstrdwo) node[midway, right] {(do)};
406 \draw[thin,-triangle 45] (ysectinfdwo) -- (ysectstodwo) node[midway, left] {(eo)};
408 \draw[thin,-triangle 45] (ysectstodwo) -- (ysectstrdwo) node[near end, below] {(lo)};
409 \draw[thin,-triangle 45] (ysectmacdwo) -- (ysectstrdwo) node[midway, left] {(po)};
410 \draw[thin,-triangle 45] (ysectmacdwo) .. controls (16.2, 1) .. (ysectstodwo.east)
411 node[very near start, right] {(mo)};
412 \draw[thin,-triangle 45] (ysectlindwo.east) .. controls (19,4) and (18, 0) .. (ysectstodwo.east)
413 node[very near start, left] {(lmo)};
415 \draw (0, 14) node {\begin{tabular}{l} Skeleton DWARF \\ in executable \end{tabular}};
416 \draw (17, 14) node {\begin{tabular}{r} Split DWARF \\ in separate object \end{tabular}};
419 \caption{Split DWARF section relationships}
420 \label{fig:splitdwarfsectionrelationships}
426 \textbf{Notes for Figure \ref{fig:splitdwarfsectionrelationships}}
429 \itembfnl{(a) \dotdebugaranges{} to \dotdebuginfo}
430 The \texttt{debug\_info\_offset} field in the header is the
431 offset in the \dotdebuginfo{} section of the corresponding
432 compilation unit header of the skeleton \dotdebuginfo{} section
433 (not the compilation unit entry). The \DWATdwoname{} attribute
434 in the \dotdebuginfo{} skeleton connects
435 the ranges to the full compilation unit in \dotdebuginfodwo.
437 \itembfnl{(b) \dotdebugnames{} to \dotdebuginfo}
438 The \dotdebugnames{} section offsets lists provide an offset
439 for the skeleton compilation unit and eight
440 byte signatures for the type units that appear only in the
441 \dotdebuginfodwo. The DIE offsets for these
442 compilation units and type units refer to the DIEs in the
443 \dotdebuginfodwo{} section for the respective
444 compilation unit and type units.
446 \itembfnl{(c) \dotdebuginfo{} skeleton to \dotdebugabbrev}
447 The \HFNdebugabbrevoffset{} value in the header is
448 the offset in the \dotdebugabbrev{} section of the
449 abbreviations for that compilation unit skeleton.
451 \itembfnl{(co) \dotdebuginfodwo{} to \dotdebugabbrevdwo}
452 The \HFNdebugabbrevoffset{} value in the header
453 is the offset in the \dotdebugabbrevdwo{} section of the
454 abbreviations for that compilation unit.
456 \itembfnl{(d) \dotdebuginfo{} to \dotdebugstr}
457 Attribute values of class string may have form \DWFORMstrp,
458 whose value is an offset in the
459 \dotdebugstr{} section of the corresponding string.
461 \itembfnl{(did) \dotdebuginfo{} to \dotdebuginfodwo}
463 attribute in a skeleton unit identifies the file containing
464 the corresponding \texttt{.dwo} (split) data.
466 \itembfnl{(do) \dotdebuginfodwo{} to \dotdebugstrdwo}
467 Attribute values of class string may have form
468 \DWFORMstrp, whose value is an offset in the
469 \dotdebugstrdwo{} section of the corresponding string.
471 \itembfnl{(e) \dotdebuginfo{} to \dotdebugstroffsets}
472 Attribute values of class string may have
476 \DWFORMstrxXNor, whose value is an index into the
477 \dotdebugstroffsets{} section for the corresponding string.
480 \itembfnl{(eo)\dotdebuginfodwo{} to \dotdebugstroffsetsdwo}
481 Attribute values of class string may have
485 \DWFORMstrxXNor, whose value is an index into the
486 \dotdebugstroffsetsdwo{} section for the corresponding string.
488 \itembfnl{(fo) \dotdebuginfodwo{} to \dotdebuginfodwo}
489 The operand of the \DWOPcallref{} DWARF expression
490 operator is the offset of a debugging
491 information entry in the \dotdebuginfodwo{} section of
492 another compilation unit. Similarly for attribute
493 operands that use \DWFORMrefaddr.
494 See Section \refersec{chap:controlflowoperations}.
496 \itembfnl{(go) \dotdebuginfodwo{} to \dotdebugmacrodwo}
497 An attribute of class \CLASSmacptr{} (specifically \DWATmacros{}
498 with form \DWFORMsecoffset{}) is an offset within the
499 \dotdebugmacrodwo{} section of the beginning of the macro
500 information for the referencing unit.
502 \itembfnl{(h) \dotdebuginfo{} (skeleton) to \dotdebugline}
503 An attribute value of class \CLASSlineptr{} (specifically
504 \DWATstmtlist{} with form \DWFORMsecoffset)
505 is an offset within the \dotdebugline{} section of the
506 beginning of the line number information for the
509 \itembfnl{(ho) \dotdebuginfodwo{} to \dotdebuglinedwo{} (skeleton)}
510 An attribute value of class \CLASSlineptr{} (specifically
511 \DWATstmtlist{} with form \DWFORMsecoffset)
512 is an offset within the \dotdebuglinedwo{} section of the
513 beginning of the line number header information
514 for the referencing unit (the line table details are not in
515 \dotdebuglinedwo{} but the line header with its list
516 of file names is present).
518 \itembfnl{(io) \dotdebuginfodwo{} to \dotdebugrnglistsdwo}
519 An attribute value of class \CLASSrnglist{} (specifically
520 \DWATranges{} with form \DWFORMrnglistx{} or \DWFORMsecoffset)
521 is an index or offset within the \dotdebugrnglistsdwo{}
522 section of a \addtoindex{range list}.
523 The format of \dotdebugrnglistsdwo{} location list entries
524 is restricted to a subset of those in \dotdebugrnglists.
525 See Section \refersec{chap:noncontiguousaddressranges} for details.
527 \itembfnl{(jo) \dotdebuginfodwo{} to \dotdebugloclistsdwo}
528 An attribute value of class
529 \CLASSloclist{} (specifically with form \DWFORMloclistx{}
531 is an index or offset within the \dotdebugloclistsdwo{}
532 section of a \addtoindex{location list.}
533 The format of \dotdebugloclistsdwo{} location list entries
534 is restricted to a subset of those in \dotdebugloclists.
535 See Section \refersec{chap:locationlists} for details.
538 \itembfnl{(k) \dotdebuginfo{} to \dotdebugaddr}
539 The value of the \DWATaddrbase{} attribute in the
540 \DWTAGcompileunit, \DWTAGpartialunit{} or \DWTAGtypeunit{} DIE
541 is the offset in the \dotdebugaddr{} section of the machine
542 addresses for that unit.
543 \DWFORMaddrxXN, \DWOPaddrx{} and \DWOPconstx{} contain indices
544 relative to that offset.