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 \clearpage
  14 \begin{landscape}
  15 \begin{figure}[H]
  16 \scriptsize
  17 \begin{tikzpicture}
  18     [sect/.style={rectangle, rounded corners=10pt, draw, fill=blue!15,
  19         inner sep=.2cm, minimum width=4.0cm},
  20          link/.style={rectangle,                       draw,
  21         inner sep=.2cm, minimum width=4.5cm}]
  22
  23 % The left column, first sections, then links, from top to bottom
  24 %
  25 \node(zsectara) at ( 0, 15.0) [sect] {\dotdebugaranges};
  26 \node(zlinka)   at ( 0, 13.5) [link] {To compilation unit~~(a)};
  27 \node(zsectinf) at ( 0,  7.5) [sect] {\begin{tabular}{c}
  28                                                                          \dotdebuginfo
  29                                                                          \end{tabular}};
  30 \node(zlinkb)   at ( 0,  1.5) [link] {To compilation unit~~(b)};
  31 \node(zsectpub) at ( 0,  0.0) [sect] {\begin{tabular}{c}
  32                                                                          \dotdebugpubnames \\
  33                                                                          \dotdebugpubtypes
  34                                                                          \end{tabular}};
  35
  36 \draw[thick,-to reversed]               (zlinka) -- (zsectara);
  37 \draw[thick,angle 90-]                  (zsectinf) -- (zlinka);
  38 \draw[thick,-angle 90]                  (zlinkb) -- (zsectinf);
  39 \draw[thick,to reversed-]               (zsectpub) -- (zlinkb);
  40
  41 % The middle column, similarly
  42 %
  43 \node(zsectfra) at (5, 15.0)  [sect] {\dotdebugframe};
  44 \node(zlinkc)   at (5, 13.5)  [link] {To abbreviations~~(c)};
  45 \node(zlinkd)   at (5, 12.1)  [link] {\DWFORMstrp{}~~(d)};
  46 \node(zlinke)   at (5, 10.4)  [link] {\begin{tabular}{c}
  47                                                                           \DWATstroffsetsbase \\
  48                                                                           \DWFORMstrx{}~~~~~~~~~(e) \\
  49                                                                           \end{tabular}};
  50 \node(zlinkf)   at (5,  8.4)  [link] {\begin{tabular}{c}
  51                                                                           \DWOPcallref{}~~~~~(f) \\
  52                                                                           \DWFORMrefaddr
  53                                                                           \end{tabular}};
  54 \node(zlinki)   at (5,  6.7)  [link] {\DWATmacros{}~~(g)};
  55 \node(zlinkj)   at (5,  5.4)  [link] {\DWATstmtlist{}~~(h)};
  56 \node(zlinkh)   at (5,  4.1)  [link] {\DWATranges{}~~(i)};
  57 \node(zlinkg)   at (5,  2.8)  [link] {\DWATlocation{}, etc.~~(j)};
  58 \node(zlinkk)   at (5,  0.5)  [link] {\begin{tabular}(c)
  59                                                                           \DWATaddrbase    \\
  60                                                                           \DWFORMaddrx \\
  61                                                                           \DWOPaddrx \\
  62                                                                           \DWOPconstx
  63                                                                           \end{tabular} (k)};
  64
  65 % Links between left and center
  66 %
  67 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkc.west);
  68 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkd.west);
  69 \draw[thick,to reversed-]                       (zsectinf) -- (zlinke.west);
  70 \draw[<->,thick]                                        (zsectinf) -- (zlinkf.west);
  71 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkg.west);
  72 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkh.west);
  73 \draw[thick,to reversed-]                       (zsectinf) -- (zlinki.west);
  74 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkj.west);
  75 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkk.north west);
  76
  77 % The right column
  78 %
  79 \node(zsectabb) at (10, 15.00) [sect] {\dotdebugabbrev};
  80 \node(zsectstr) at (10, 13.75) [sect] {\dotdebugstr};
  81 \node(zlinkl)   at (10, 12.50) [link] {To strings~~(l)};
  82 \node(zsectstx) at (10, 11.25) [sect] {\dotdebugstroffsets};
  83 \node(zlinkm)   at (10,  9.50) [link] {\begin{tabular}{c}
  84                                       \DWMACROdefineindirectx \\
  85                                       \DWMACROundefindirectx \\
  86                                       (m)
  87                                       \end{tabular}};
  88 \node(zsectmac) at (10,  7.80) [sect] {\dotdebugmacro};
  89 \node(zlinkn)   at (10,  6.40) [link] {\begin{tabular}{c}
  90                                       macroinfo header~~~~~~(n)\\
  91                                       \DWMACROstartfile
  92                                       \end{tabular}};
  93 \node(zsectlin) at (10,  5.00) [sect] {\dotdebugline};
  94 \node(zsectran) at (10,  3.85) [sect] {\dotdebugranges};
  95 \node(zsectloc) at (10,  2.70) [sect] {\dotdebugloc{}};
  96 \node(zlinko)   at (10,  1.20) [link] {\begin{tabular}{c}
  97                                        \DWOPaddrx \\
  98                                        \DWOPconstx
  99                                        \end{tabular} (o)};
 100 \node(zsectadx) at (10,  -0.25) [sect] {\dotdebugaddr{}};
 101
 102 \draw[thick,to reversed-]               (zsectstx) -- (zlinkl);
 103 \draw[thick,-angle 90]                  (zlinkl) -- (zsectstr);
 104 \draw[thick,to reversed-]       (zsectmac) -- (zlinkm);
 105 \draw[thick,-angle 90]          (zlinkm) -- (zsectstx);
 106 \draw[thick,to reversed-]       (zsectmac) -- (zlinkn);
 107 \draw[thick,-angle 90]          (zlinkn) -- (zsectlin);
 108 \draw[thick,to reversed-]       (zsectloc) -- (zlinko);
 109 \draw[thick,-angle 90]          (zlinko) -- (zsectadx);
 110
 111 % Links between center and right
 112 %
 113 \draw[thick,-angle 90]          (zlinkc.east) -- (zsectabb.west);
 114 \draw[thick,-angle 90]          (zlinkd.east) -- (zsectstr.west);
 115 \draw[thick,-angle 90]          (zlinke.east) -- (zsectstx.west);
 116 \draw[thick,-angle 90]          (zlinkg.east) -- (zsectloc.west);
 117 \draw[thick,-angle 90]          (zlinkh.east) -- (zsectran.west);
 118 \draw[thick,-angle 90]          (zlinki.east) -- (zsectmac.west);
 119 \draw[thick,-angle 90]          (zlinkj.east) -- (zsectlin.west);
 120 \draw[thick,-angle 90]          (zlinkk.east) -- (zsectadx.west);
 121
 122 \node(zlinky)   at (15.5, 10.5) [link] {\begin{tabular}{c}
 123                                         \DWMACROdefineindirect \\
 124                                         \DWMACROundefindirect \\
 125                                         (p)
 126                                         \end{tabular}};
 127 \node(zlinkz)   at (15.5,  6.0) [link] {\begin{tabular}{c}
 128                                         \DWMACROtransparentinclude \\
 129                                         (q)
 130                                         \end{tabular}};
 131
 132 \draw[thick,to reversed-]       (zsectmac.east) -- (zlinky);
 133 \draw[thick,-angle 90]          (zlinky) -- (zsectstr.east);
 134 \draw[<->,thick]                                (zsectmac.east) -- (zlinkz);
 135
 136 \end{tikzpicture}
 137 \vspace{5mm}
 138 \caption{Debug section relationships}
 139 \label{fig:debugsectionrelationships}
 140 \end{figure}
 141 \end{landscape}
 142
 143 \clearpage
 144 \begin{center}
 145    \textbf{Notes}
 146 \end{center}
 147 \begin{enumerate}[(a)]
 148 \item  \dotdebugaranges{} to \dotdebuginfo \\
 149 The \texttt{debug\_info\_offset} value in
 150 the header is
 151 the offset in the \dotdebuginfo{} section of the
 152 corresponding compilation unit header (not the compilation
 153 unit entry).
 154
 155 %b
 156 \item \dotdebugpubnames{} and \dotdebugpubtypes{} to \dotdebuginfo \\
 157 The \texttt{debug\_info\_offset} value in the header is the offset in the
 158 \dotdebuginfo{} section of the
 159 corresponding compilation unit header (not
 160 the compilation unit entry). Each pubname/pubtype unit has the offset (within
 161 the corresponding compilation unit) of the applicable debugging
 162 information entry.
 163
 164 %c
 165 \item \dotdebuginfo{} to \dotdebugabbrev \\
 166 The \texttt{debug\_abbrev\_offset} value in the header is the offset in the
 167 \dotdebugabbrev{}
 168 section of the abbreviations for that compilation unit.
 169
 170 %d
 171 \item  \dotdebuginfo{} to \dotdebugstr \\
 172 Attribute values of class string may have form
 173 \DWFORMstrp, whose
 174 value is the offset in the \dotdebugstr{}
 175 section of the corresponding string.
 176
 177 %e
 178 \item \dotdebugstroffsets{} to \dotdebugstroffsets \\
 179 The value of the \DWATstroffsetsbase{} attribute in a
 180 compilation, partial or type unit DIE is the offset in the
 181 \dotdebugstroffsets{} section of the
 182 \addtoindex{string offsets table}
 183 for that unit.
 184 In addition, attribute values of class string may have form
 185 \DWFORMstrx, whose value is an index into the
 186 string offsets table.
 187
 188 %f
 189 \item \dotdebuginfo{} to \dotdebuginfo \\
 190 The operand of the \DWOPcallref{}
 191 DWARF expression operator is the
 192 offset of a debugging information entry in the
 193 \dotdebuginfo{} section of another compilation.
 194 Similarly for attribute operands that have use
 195 \DWFORMrefaddr.
 196
 197 %g
 198 \item \dotdebuginfo{} to \dotdebugmacro \\
 199 An attribute value of class
 200 \livelink{chap:classmacptr}{macptr} (specifically form
 201 \DWFORMsecoffset) is an
 202 offset within the
 203 \dotdebugmacro{} section
 204 of the beginning of the macro information for the referencing unit.
 205
 206 %h
 207 \item \dotdebuginfo{} to \dotdebugline \\
 208 An attribute value of class
 209 \livelink{chap:classlineptr}{lineptr} (specifically form
 210 \DWFORMsecoffset)
 211 is an offset in the
 212 \dotdebugline{} section of the
 213 beginning of the line number information for the referencing unit.
 214
 215 %i
 216 \needlines{5}
 217 \item \dotdebuginfo{} to \dotdebugranges \\
 218 An attribute value of class \livelink{chap:classrangelistptr}{rangelistptr}
 219 (specifically form
 220 \DWFORMsecoffset)
 221 is an offset within the \dotdebugranges{} section of
 222 a range list.
 223
 224 %j
 225 \item \dotdebuginfo{} to \dotdebugloc \\
 226 An attribute value of class \livelink{chap:classloclistptr}{loclistptr}
 227 (specifically form
 228 \DWFORMsecoffset)
 229 is an offset within the \dotdebugloc{}
 230 section of a
 231 \addtoindex{location list}.
 232
 233 %k
 234 \item \dotdebuginfo{} to \dotdebugaddr \\
 235 The value of the \DWATaddrbase{} attribute in the
 236 \DWTAGcompileunit{}, \DWTAGtypeunit{} or \DWTAGpartialunit{} DIE is the
 237 offset in the \dotdebugaddr{} section of the machine
 238 addresses for that unit.
 239 \DWFORMaddrx, \DWOPaddrx{} and \DWOPconstx{} contain
 240 indices relative to that offset.
 241
 242 %l
 243 \item \dotdebugstroffsets{} to \dotdebugstr \\
 244 Entries in the string offsets table
 245 are offsets to the corresponding string text in the
 246 \dotdebugstr{} section.
 247
 248 %m
 249 \item \dotdebugmacro{} to \dotdebugstroffsets \\
 250 The second operand of a
 251 \DWMACROdefineindirect macroinfo
 252 entry is an index into the string table in the
 253 \dotdebugstr{} section.
 254
 255
 256 %n
 257 \item \dotdebugmacro to \dotdebugline \\
 258 The second operand of
 259 \DWMACROstartfile{} refers to a file entry in the
 260 \dotdebugline{} section relative to the start
 261 of that section given in the macroinfo header.
 262
 263 %o
 264 \item \dotdebugloc{} to \dotdebugaddr \\
 265 \DWOPaddrx{} and \DWOPconstx{} operators that occur in the
 266 \dotdebugloc{} section refer indirectly to the
 267 \dotdebugaddr{} section by way of the
 268 \DWATaddrbase{} attribute in the associated \dotdebuginfo{}
 269 section.
 270
 271 %p
 272 \item \dotdebugmacro{} to \dotdebugstroffsets \\
 273 The second operand of a
 274 \DWMACROdefineindirectx macroinfo entry is an index
 275 into the string offset table in the
 276 \dotdebugstroffsets{} section.
 277
 278 %q
 279 \item \dotdebugmacro{} to \dotdebugmacro \\
 280 The second operand of a
 281 \DWMACROtransparentinclude{} macroinfo
 282 entry is an offset into another part of the
 283 \dotdebugmacro{} section to the header for the
 284 sequence to be transparently included.
 285
 286
 287 \end{enumerate}