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