1fbae16f3ff874d3f36339da691f6d32f18db975
[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 \textit{This diagram does not distinguish between the normal
10 and split object section pairs (for example, \dotdebuginfo{} 
11 versus \dotdebuginfodwo).}
12
13 \begin{figure}[H]
14 \begin{tikzpicture}
15     [sect/.style={rectangle, rounded corners=10pt, draw, fill=blue!10, inner sep=.2cm, minimum width=4.5cm},
16          link/.style={rectangle,                       draw,               inner sep=.2cm, minimum width=5.0cm}]
17
18 % The left column, first sections, then links, from top to bottom
19 %
20 \node(zsectara) at ( 0, 16.) [sect] {\dotdebugaranges};
21 \node(zlinka)   at ( 0, 14.) [link] {To compilation unit (a)};
22 \node(zsectinf) at ( 0, 8.0) [sect] {\begin{tabular}{c} 
23                                                                          \dotdebuginfo 
24                                                                          \end{tabular}};
25 \node(zlinkb)   at ( 0, 2.0) [link] {To compilation unit (b)};
26 \node(zsectpub) at ( 0, 0.0) [sect] {\begin{tabular}{c} 
27                                                                          \dotdebugpubnames \\ 
28                                                                          \dotdebugpubtypes 
29                                                                          \end{tabular}};
30
31 \draw[thick,-to reversed]               (zlinka) -- (zsectara);
32 \draw[thick,angle 90-]                  (zsectinf) -- (zlinka);
33 \draw[thick,-angle 90]                  (zlinkb) -- (zsectinf);
34 \draw[thick,to reversed-]               (zsectpub) -- (zlinkb);
35
36 % The middle column, similarly
37 %
38 \node(zsectfra) at (6, 16.)   [sect] {\dotdebugframe};
39 \node(zlinkc)   at (6, 14.5)  [link] {To abbreviations (c)};
40 \node(zlinkd)   at (6, 13.25) [link] {\DWFORMstrp{} (d)};
41 \node(zlinke)   at (6, 11.5)  [link] {\begin{tabular}{c}
42                                                                           \DWATstroffsetsbase, \\
43                                                                           \DWFORMstrx{} (e)
44                                                                           \end{tabular}};
45 \node(zlinkf)   at (6, 9.5)   [link] {\begin{tabular}{c}
46                                                                           \DWOPcallref{} (f) \\
47                                                                           \DWFORMrefaddr
48                                                                           \end{tabular}};
49 \node(zlinkg)   at (6,  8.)   [link] {\DWATlocation{}, etc. (g)};
50 \node(zlinkh)   at (6,  6.5) [link] {\DWATranges{} (h)};
51 \node(zlinki)   at (6,  5.0)  [link] {\DWATmacroinfo{} (i)};
52 \node(zlinkj)   at (6,  3.5)  [link] {\DWATstmtlist{} (j)};
53 \node(zlinkk)   at (6,  1.)   [link] {\begin{tabular}(c)
54                                                                           \DWATaddrbase,    \\
55                                                                           \DWFORMaddrx, (k) \\
56                                                                           \DWOPaddrx, \\
57                                                                           \DWOPconstx
58                                                                           \end{tabular}};
59
60 % Links between left and center
61 %
62 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkc.west);
63 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkd.west);
64 \draw[thick,to reversed-]                       (zsectinf) -- (zlinke.west);
65 \draw[<->,thick]                                        (zsectinf) -- (zlinkf.west);
66 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkg.west);
67 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkh.west);
68 \draw[thick,to reversed-]                       (zsectinf) -- (zlinki.west);
69 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkj.west);
70 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkk.north west);
71
72 % The right column
73 %
74 \node(zsectabb) at (12, 16) [sect] {\dotdebugabbrev};
75 \node(zsectstr) at (12, 14) [sect] {\dotdebugstr};
76 \node(zlinkl)   at (12, 12) [link] {To strings (l)};
77 \node(zsectstx) at (12, 10) [sect] {\dotdebugstroffsets};
78 \node(zsectloc) at (12,  8) [sect] {\dotdebugloc{} (m)};
79 \node(zsectran) at (12,  6) [sect] {\dotdebugranges};
80 \node(zsectmac) at (12,  4) [sect] {\dotdebugmacinfo};
81 \node(zsectlin) at (12,  2) [sect] {\dotdebugline};
82 \node(zsectadx) at (12,  0) [sect] {\dotdebugaddr{} (m)};
83
84 \draw[thick,to reversed-]               (zsectstx) -- (zlinkl);
85 \draw[thick,-angle 90]                  (zlinkl) -- (zsectstr);
86
87 % Links between center and right
88 %
89 \draw[thick,-angle 90]          (zlinkc.east) -- (zsectabb.west);
90 \draw[thick,-angle 90]          (zlinkd.east) -- (zsectstr.west);
91 \draw[thick,-angle 90]          (zlinke.east) -- (zsectstx.west);
92 \draw[thick,-angle 90]          (zlinkg.east) -- (zsectloc.west);
93 \draw[thick,-angle 90]          (zlinkh.east) -- (zsectran.west);
94 \draw[thick,-angle 90]          (zlinki.east) -- (zsectmac.west);
95 \draw[thick,-angle 90]          (zlinkj.east) -- (zsectlin.west);
96 \draw[thick,-angle 90]          (zlinkk.east) -- (zsectadx.west);
97
98 \end{tikzpicture}
99 \vspace{5mm}
100 \caption{Debug section relationships}
101 \label{fig:debugsectionrelationships}
102 \end{figure}
103
104 \clearpage
105 \begin{center}
106    \textbf{Notes}
107 \end{center}
108 \begin{enumerate}[(a)]  
109 \item  \dotdebugaranges{} to \dotdebuginfo \\
110 The \texttt{debug\_info\_offset} value in
111 the header is
112 the offset in the \dotdebuginfo{} section of the
113 corresponding compilation unit header (not the compilation
114 unit entry).
115
116 %b
117 \item \dotdebugpubnames{} and \dotdebugpubtypes{} to \dotdebuginfo \\
118 The \texttt{debug\_info\_offset} value in the header is the offset in the
119 \dotdebuginfo{} section of the 
120 corresponding compilation unit header (not
121 the compilation unit entry). Each pubname/pubtype unit has the offset (within
122 the corresponding compilation unit) of the applicable debugging
123 information entry.
124
125 %c
126 \item \dotdebuginfo{} to \dotdebugabbrev \\
127 The \texttt{debug\_abbrev\_offset} value in the header is the offset in the
128 \dotdebugabbrev{} 
129 section of the abbreviations for that compilation unit.
130
131 %d
132 \item  \dotdebuginfo{} to \dotdebugstr \\
133 Attribute values of class string may have form 
134 \DWFORMstrp, whose
135 value is the offset in the \dotdebugstr{}
136 section of the corresponding string.
137
138 %e
139 \item \dotdebugstroffsets{} to \dotdebugstroffsets \\
140 The value of the \DWATstroffsetsbase{} attribute in a
141 compilation, partial or type unit DIE is the offset in the
142 \dotdebugstroffsets{} section of the 
143 \addtoindex{string offsets table}
144 for that unit.
145 In addition, attribute values of class string may have form 
146 \DWFORMstrx, whose value is an index into the
147 string offsets table.
148
149 %f
150 \item \dotdebuginfo{} to \dotdebuginfo \\
151 The operand of the \DWOPcallref{} 
152 DWARF expression operator is the
153 offset of a debugging information entry in the 
154 \dotdebuginfo{} section of another compilation.
155 Similarly for attribute operands that have use
156 \DWFORMrefaddr.
157
158 %g
159 \item \dotdebuginfo{} to \dotdebugloc \\
160 An attribute value of class \livelink{chap:classloclistptr}{loclistptr} 
161 (specifically form
162 \DWFORMsecoffset) 
163 is an offset within the \dotdebugloc{} 
164 section of a
165 \addtoindex{location list}.
166
167 %h
168 \item \dotdebuginfo{} to \dotdebugranges \\
169 An attribute value of class \livelink{chap:classrangelistptr}{rangelistptr} 
170 (specifically form
171 \DWFORMsecoffset) 
172 is an offset within the \dotdebugranges{} section of
173 a range list.
174
175 %i
176 \needlines{5}
177 \item \dotdebuginfo{} to \dotdebugmacinfo \\
178 An attribute value of class 
179 \livelink{chap:classmacptr}{macptr} (specifically form
180 \DWFORMsecoffset) is an 
181 offset within the 
182 \dotdebugmacinfo{} section
183 of the beginning of the macro information for the referencing unit.
184
185 %j
186 \item \dotdebuginfo{} to \dotdebugline \\
187 An attribute value of class 
188 \livelink{chap:classlineptr}{lineptr} (specifically form
189 \DWFORMsecoffset) 
190 is an offset in the 
191 \dotdebugline{} section of the
192 beginning of the line number information for the referencing unit.
193
194 %k
195 \item \dotdebuginfo{} to \dotdebugaddr \\
196 The value of the \DWATaddrbase{} attribute in the
197 \DWTAGcompileunit{}, \DWTAGtypeunit{} or \DWTAGpartialunit{} DIE is the
198 offset in the \dotdebugaddr{} section of the machine
199 addresses for that unit.
200 \DWFORMaddrx, \DWOPaddrx{} and \DWOPconstx{} contain
201 indices relative to that offset.
202
203 %l
204 \item \dotdebugstroffsets{} to \dotdebugstr \\
205 Entries in the string offsets table
206 are offsets to the corresponding string text in the 
207 \dotdebugstr{} section.
208
209 %m
210 \item \dotdebugloc{} to \dotdebugaddr \\
211 \DWOPaddrx{} and \DWOPconstx{} operators that occur in the 
212 \dotdebugloc{} section refer indirectly to the 
213 \dotdebugaddr{} section by way of the 
214 \DWATaddrbase{} attribute in the associated \dotdebuginfo{} 
215 section. 
216 \end{enumerate}