3f2d37fa3830ceabc3287e1e4b3b3f90f42936f0
[dwarf-doc.git] / dwarf5 / latexdoc / debugsectionrelationships.tex
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 diagram and associated notes on the following pages.
8
9 \begin{figure}[H]
10 \begin{tikzpicture}
11     [sect/.style={rectangle, rounded corners=10pt, draw, fill=blue!10, inner sep=.2cm, minimum width=4.5cm},
12          link/.style={rectangle,                       draw,               inner sep=.2cm, minimum width=5.0cm}]
13
14 % The left column, first sections, then links, from top to bottom
15 %
16 \node(zsectara) at ( 0, 10.) [sect] {\dotdebugaranges};
17 \node(zlinka)   at ( 0, 8.0) [link] {To compilation unit (a)};
18 \node(zsectinf) at ( 0, 5.0) [sect] {\begin{tabular}{c} \dotdebuginfo \\ \dotdebugtypes \end{tabular}};
19 \node(zlinkb)   at ( 0, 2.0) [link] {To compilation unit (b)};
20 \node(zsectpub) at ( 0, 0.0) [sect] {\begin{tabular}{c} \dotdebugpubnames \\ \dotdebugpubtypes \end{tabular}};
21
22 \draw[thick,-to reversed]               (zlinka) -- (zsectara);
23 \draw[thick,angle 90-]                  (zsectinf) -- (zlinka);
24 \draw[thick,-angle 90]                  (zlinkb) -- (zsectinf);
25 \draw[thick,to reversed-]               (zsectpub) -- (zlinkb);
26
27 % The middle column, similarly
28 %
29 \node(zsectfra) at (6, 10.) [sect] {\dotdebugframe};
30 \node(zlinkc)   at (6,  8.) [link] {To abbreviations (c)};
31 \node(zlinkd)   at (6,  7.) [link] {\DWFORMstrp{} (d)};
32 \node(zlinke)   at (6,  6.) [link] {\DWOPcallref{} (e)};
33 \node(zlinkf)   at (6,  5.) [link] {\DWATlocation{}, etc. (f)};
34 \node(zlinkg)   at (6,  4.) [link] {\DWATranges{} (g)};
35 \node(zlinkh)   at (6,  3.) [link] {\DWATmacroinfo{} (h)};
36 \node(zlinki)   at (6,  2.) [link] {\DWATstmtlist{} (i)};
37
38 % Links between left and center
39 %
40 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkc.west);
41 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkd.west);
42 \draw[thick,angle 90-]                          (zsectinf) -- (zlinke.west);
43 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkf.west);
44 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkg.west);
45 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkh.west);
46 \draw[thick,to reversed-]                       (zsectinf) -- (zlinki.west);
47
48 % The right column
49 %
50 \node(zsectabb) at (12, 10) [sect] {\dotdebugabbrev};
51 \node(zsectstr) at (12,  8) [sect] {\dotdebugstr};
52 \node(zsectloc) at (12,  6) [sect] {\dotdebugloc};
53 \node(zsectran) at (12,  4) [sect] {\dotdebugranges};
54 \node(zsectmac) at (12,  2) [sect] {\dotdebugmacinfo};
55 \node(zsectlin) at (12,  0) [sect] {\dotdebugline};
56
57 % Links between center and right
58 %
59 \draw[thick,-angle 90]          (zlinkc.east) -- (zsectabb.west);
60 \draw[thick,-angle 90]          (zlinkd.east) -- (zsectstr.west);
61 \draw[thick,-to reversed]       (zlinke.east) -- (zsectloc.west);
62 \draw[thick,-angle 90]          (zlinkf.east) -- (zsectloc.south west);
63 \draw[thick,-angle 90]          (zlinkg.east) -- (zsectran.west);
64 \draw[thick,-angle 90]          (zlinkh.east) -- (zsectmac.west);
65 \draw[thick,-angle 90]          (zlinki.east) -- (zsectlin.west);
66
67 \end{tikzpicture}
68 \vspace{5mm}
69 \caption{Debug section relationships}
70 \label{fig:debugsectionrelationships}
71 \end{figure}
72
73 \clearpage
74 \begin{center}
75    \textbf{Notes}
76 \end{center}
77 \begin{enumerate}[(a)]  
78 \item  \dotdebugaranges{}  \\
79 The debug\_info\_offset value in
80 the header is
81 the offset in the \dotdebuginfo{} section of the
82 corresponding compilation unit header (not the compilation
83 unit entry).
84
85 %b
86 \item \dotdebugpubnames{} and \dotdebugpubtypes{} \\
87 The debug\_info\_offset value in the header is the offset in the
88 \dotdebuginfo{} section of the 
89 corresponding compilation unit header (not
90 the compilation unit entry). Each pubname/pubtype has the offset (within
91 the corresponding compilation unit) of the applicable debugging
92 information entry.
93
94 %c
95 \item \dotdebuginfo{} and \dotdebugtypes{} \\
96 The debug\_abbrev\_offset value in the header is the offset in the
97 \dotdebugabbrev{} 
98 section of the abbreviations for that compilation unit.
99
100 %d
101 \item  \dotdebuginfo{} and \dotdebugtypes{} \\
102 Attribute values of class string may have form 
103 \livelink{chap:DWFORMstrp}{DW\_FORM\_strp}, whose
104 value is the offset in the \dotdebugstr{}
105 section of the corresponding string.
106
107 %e
108 \item \dotdebugloc{} \\
109 The operand of the \livelink{chap:DWOPcallref}{DW\_OP\_call\_ref} 
110 DWARF expression operator is the
111 offset of a debugging information entry in the 
112 \dotdebuginfo{} section.
113
114 %f
115 \item \dotdebuginfo{} \\
116 An attribute value of class \livelink{chap:loclistptr}{loclistptr} 
117 (specifically form
118 \livelink{chap:DWFORMsecoffset}{DW\_FORM\_sec\_offset}) 
119 is an offset within the \dotdebugloc{} 
120 section of a
121 \addtoindex{location list}.
122
123 %g
124 \item \dotdebuginfo{} \\
125 An attribute value of class \livelink{chap:rangelistptr}{rangelistptr} 
126 (specifically form
127 \livelink{chap:DWFORMsecoffset}{DW\_FORM\_sec\_offset}) 
128 is an offset within the \dotdebugranges{} section of
129 a range list.
130
131 %h
132 \item \dotdebuginfo{} \\
133 An attribute value of class 
134 \livelink{chap:macptr}{macptr} (specifically form
135 \livelink{chap:DWFORMsecoffset}{DW\_FORM\_sec\_offset}) is an 
136 offset within the 
137 \dotdebugmacinfo{} section
138 of the beginning of the macro information for the referencing unit.
139
140 %i
141 \item \dotdebuginfo{} \\
142 An attribute value of class 
143 \livelink{chap:lineptr}{lineptr} (specifically form
144 \livelink{chap:DWFORMsecoffset}{DW\_FORM\_sec\_offset}) 
145 is an offset in the 
146 \dotdebugline{} section of the
147 beginning of the line number information for the referencing unit.
148 \end{enumerate}