dwarf5/latexdoc/examples.tex

   1 \chapter{Examples (Informative)}
   2 \label{app:examplesinformative}
   3
   4 The following sections provide examples that illustrate
   5 various aspects of the DWARF debugging information format.
   6
   7
   8 \section{General Description Examples}
   9 \label{app:generaldescriptionexamples}
  10
  11
  12 \subsection{Compilation Units and Abbreviations Table Example}
  13 \label{app:compilationunitsandabbreviationstableexample}
  14
  15 Figure \refersec{fig:compilationunitsandabbreviationstable}
  16 depicts the relationship of the abbreviations tables contained
  17 \addtoindexx{abbreviations table!example}
  18 \addtoindexx{\texttt{.debug\_abbrev}!example}
  19 \addtoindexx{\texttt{.debug\_info}!example}
  20 in the \dotdebugabbrev{}
  21 section to the information contained in
  22 the \dotdebuginfo{}
  23 section. Values are given in symbolic form,
  24 where possible.
  25
  26 The figure corresponds to the following two trivial source files:
  27
  28 File myfile.c
  29 \begin{nlnlisting}
  30 typedef char* POINTER;
  31 \end{nlnlisting}
  32 File myfile2.c
  33 \begin{nlnlisting}
  34 typedef char* strp;
  35 \end{nlnlisting}
  36
  37 % Ensures we get the following float out before we go on.
  38 \clearpage
  39 %%%
  40 %%% Be VERY careful about editing this figure! Both vertical
  41 %%% and horizontal spacing are critical to achieving the
  42 %%% desired effect. But this is very fragile!
  43 %%%
  44 \begin{figure}[ht]
  45 %\centering
  46 %\setlength{\linewidth}{1.1\linewidth}
  47 \begin{minipage}[t]{0.03\linewidth}
  48 \flushright
  49 \scriptsize
  50 % Note: alltt is used to step down the needed number of lines to the labels
  51 \begin{alltt}
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72 \textit{e1:}
  73
  74
  75
  76
  77 \textit{e2:}
  78 \end{alltt}
  79 \end{minipage}
  80 %
  81 \begin{minipage}[t]{0.38\linewidth}
  82 \centering
  83 Compilation Unit \#1: \dotdebuginfo{}
  84 \begin{framed}
  85 \scriptsize
  86 \begin{alltt}
  87 \textit{length}
  88 4
  89 \textit{a1 (abbreviations table offset)}
  90 4
  91 \vspace{0.01cm}
  92 \hrule
  93 1
  94 "myfile.c"
  95 "Best Compiler Corp, V1.3"
  96 "/home/mydir/src"
  97 \DWLANGCeightynine
  98 0x0
  99 0x55
 100 \DWFORMsecoffset
 101 0x0
 102 \vspace{0.01cm}
 103 \hrule
 104 2
 105 "char"
 106 \DWATEunsignedchar
 107 1
 108 \vspace{0.01cm}
 109 \hrule
 110 3
 111 \textit{e1  (debug info offset)}
 112 \vspace{0.01cm}
 113 \hrule
 114 4
 115 "POINTER"
 116 \textit{e2  (debug info offset)}
 117 \hrule
 118 \vspace{0.01cm}
 119 0
 120 \end{alltt}
 121 %
 122 %
 123 \end{framed}
 124 Compilation Unit \#2: \dotdebuginfo{}
 125 \begin{framed}
 126 \scriptsize
 127 \begin{alltt}
 128 \textit{length}
 129 4
 130 \textit{a1 (abbreviations table offset)}
 131 4
 132 \vspace{0.01cm}
 133 \hrule
 134 ...
 135 \vspace{0.01cm}
 136 \hrule
 137 4
 138 "strp"
 139 \textit{e2  (debug info offset)}
 140 \vspace{0.01cm}
 141 \hrule
 142 ...
 143 \end{alltt}
 144 %
 145 %
 146 \end{framed}
 147 \end{minipage}
 148 \hfill
 149 % Place the label for the abbreviation table
 150 \begin{minipage}[t]{0.03\linewidth}
 151 \flushright
 152 \scriptsize
 153 % Note: alltt is used to step down the needed number of lines to the label
 154 \begin{alltt}
 155
 156
 157
 158
 159
 160 \textit{a1:}
 161 \end{alltt}
 162 \end{minipage}
 163 %
 164 \begin{minipage}[t]{0.41\linewidth}
 165 \centering
 166 Abbreviation Table: \dotdebugabbrev{}
 167 \begin{framed}
 168 \scriptsize
 169 \begin{alltt}\vspace{0.06cm}
 170 1
 171 \DWTAGcompileunit
 172 \DWCHILDRENyes
 173 \DWATname       \DWFORMstring
 174 \DWATproducer   \DWFORMstring
 175 \DWATcompdir   \DWFORMstring
 176 \DWATlanguage   \DWFORMdataone
 177 \DWATlowpc     \DWFORMaddr
 178 \DWAThighpc    \DWFORMdataone
 179 \DWATstmtlist  \DWFORMindirect
 180 0
 181 \vspace{0.01cm}
 182 \hrule
 183 2
 184 \DWTAGbasetype
 185 \DWCHILDRENno
 186 \DWATname       \DWFORMstring
 187 \DWATencoding   \DWFORMdataone
 188 \DWATbytesize  \DWFORMdataone
 189 0
 190 \vspace{0.01cm}
 191 \hrule
 192 3
 193 \DWTAGpointertype
 194 \DWCHILDRENno
 195 \DWATtype       \DWFORMreffour
 196 0
 197 \vspace{0.01cm}
 198 \hrule
 199 4
 200 \DWTAGtypedef
 201 \DWCHILDRENno
 202 \DWATname      \DWFORMstring
 203 \DWATtype      \DWFORMrefaddr
 204 0
 205 \vspace{0.01cm}
 206 \hrule
 207 0
 208 \end{alltt}
 209 \end{framed}
 210 \end{minipage}
 211
 212 \vspace{0.2cm}
 213 \caption{Compilation units and abbreviations table} \label{fig:compilationunitsandabbreviationstable}
 214 \end{figure}
 215
 216 % Ensures we get the above float out before we go on.
 217 \clearpage
 218
 219 \subsection{DWARF Stack Operation Examples}
 220 \label{app:dwarfstackoperationexamples}
 221 \textit {The
 222 \addtoindexx{DWARF expression!examples}
 223 stack operations defined in
 224 Section \refersec{chap:stackoperations}.
 225 are fairly conventional, but the following
 226 examples illustrate their behavior graphically.}
 227
 228 \begin{longtable}[c]{rrcrr}
 229 \multicolumn{2}{c}{Before} & Operation & \multicolumn{2}{c}{After} \\
 230 \hline
 231 \endhead
 232 \endfoot
 233 0& 17& \DWOPdup{} &0 &17 \\*
 234 1&   29& &  1 & 17 \\*
 235 2& 1000 & & 2 & 29\\*
 236 & & &         3&1000\\
 237
 238 & & & & \\
 239 0 & 17 & \DWOPdrop{} & 0 & 29 \\*
 240 1 &29  &            & 1 & 1000 \\*
 241 2 &1000& & &          \\
 242
 243 & & & & \\
 244 0 & 17 & \DWOPpick, 2 & 0 & 1000 \\*
 245 1 & 29 & & 1&17 \\*
 246 2 &1000& &2&29 \\*
 247   &    & &3&1000 \\
 248
 249 & & & & \\
 250 0&17& \DWOPover&0&29 \\*
 251 1&29& &  1&17 \\*
 252 2&1000 & & 2&29\\*
 253  &     & & 3&1000 \\
 254
 255 & & & & \\
 256 0&17& \DWOPswap{} &0&29 \\*
 257 1&29& &  1&17 \\*
 258 2&1000 & & 2&1000 \\
 259
 260 & & & & \\
 261 0&17&\DWOProt{} & 0 &29 \\*
 262 1&29 & & 1 & 1000 \\*
 263 2& 1000 & &  2 & 17 \\
 264 \end{longtable}
 265
 266 \subsection{DWARF Location Description Examples}
 267 \label{app:dwarflocationdescriptionexamples}
 268
 269 Following are examples of DWARF operations used to form location descriptions:
 270
 271 \newcommand{\descriptionitemnl}[1]
 272         {\vspace{0.3\baselineskip}\item[#1]\mbox{}\\\vspace{0.5\baselineskip}}
 273
 274
 275 \begin{description}
 276 \descriptionitemnl{\DWOPregthree}
 277 The value is in register 3.
 278
 279 \descriptionitemnl{\DWOPregx{} 54}
 280 The value is in register 54.
 281
 282 \descriptionitemnl{\DWOPaddr{} 0x80d0045c}
 283 The value of a static variable is at machine address 0x80d0045c.
 284
 285 \descriptionitemnl{\DWOPbregeleven{} 44}
 286 Add 44 to the value in register 11 to get the address of an automatic
 287 variable instance.
 288
 289 \needlines{4}
 290 \descriptionitemnl{\DWOPfbreg{} -50}
 291 Given a \DWATframebase{} value of
 292 \doublequote{\DWOPbregthirtyone{} 64,} this example
 293 computes the address of a local variable that is -50 bytes from a
 294 logical frame pointer that is computed by adding 64 to the current
 295 stack pointer (register 31).
 296
 297 \descriptionitemnl{\DWOPbregx{} 54 32 \DWOPderef}
 298 A call-by-reference parameter whose address is in the word 32 bytes
 299 from where register 54 points.
 300
 301 \descriptionitemnl{\DWOPplusuconst{} 4}
 302 A structure member is four bytes from the start of the structure
 303 instance. The base address is assumed to be already on the stack.
 304
 305 \descriptionitemnl{\DWOPregthree{} \DWOPpiece{} 4 \DWOPregten{} \DWOPpiece{} 2}
 306 A variable whose first four bytes reside in register 3 and whose next
 307 two bytes reside in register 10.
 308
 309 \needlines{4}
 310 \descriptionitemnl{\DWOPregzero{} \DWOPpiece{} 4 \DWOPpiece{} 4 \DWOPfbreg{} -12 \DWOPpiece{} 4 }
 311 \vspace{-2\parsep}
 312 A twelve byte value whose first four bytes reside in register zero,
 313 whose middle four bytes are unavailable (perhaps due to optimization),
 314 and whose last four bytes are in memory, 12 bytes before the frame
 315 base.
 316
 317 \descriptionitemnl{\DWOPbregone{} 0 \DWOPbregtwo{} 0 \DWOPplus{} \DWOPstackvalue{} }
 318 Add the contents of r1 and r2 to compute a value. This value is the
 319 \doublequote{contents} of an otherwise anonymous location.
 320
 321 \needlines{4}
 322 \descriptionitemnl{\DWOPlitone{} \DWOPstackvalue{} \DWOPpiece{} 4 \DWOPbregthree{} 0 \DWOPbregfour{} 0}
 323 \vspace{-3\parsep}\descriptionitemnl{
 324 \hspace{0.5cm}\DWOPplus{} \DWOPstackvalue{} \DWOPpiece{} 4 }
 325 The object value is found in an anonymous (virtual) location whose
 326 value consists of two parts, given in memory address order: the 4 byte
 327 value 1 followed by the four byte value computed from the sum of the
 328 contents of r3 and r4.
 329
 330 \bb
 331 \descriptionitemnl{\DWOPentryvalue{} 2 \DWOPbregone{} 0 }
 332 The value register 1 contained upon entering the current subprogram is
 333 pushed on the stack.
 334 \eb
 335
 336 \descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregone{} }
 337 \bb
 338 Same as the previous example
 339 (push the value register 1 contained upon entering the current subprogram)
 340 but use the more compact register location description.
 341 \eb
 342
 343 \bb
 344 \descriptionitemnl{\DWOPentryvalue{} 2 \DWOPbregone{} 0 \DWOPstackvalue }
 345 \eb
 346 The value register 1 contained upon entering the current subprogram is
 347 pushed on the stack. This value is the
 348 \doublequote{contents} of an otherwise anonymous location.
 349
 350 \bb
 351 \descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregone{} \DWOPstackvalue }
 352 Same as the previous example (push the value register 1 contained
 353 upon entering the current subprogram) but use the more compact
 354 register location description.
 355 \eb
 356
 357 \needlines{6}
 358 \descriptionitemnl{\DWOPentryvalue{} 3 \DWOPbregfour{} 16 \DWOPderef{} \DWOPstackvalue }
 359 Add 16 to the value register 4 had upon entering the current subprogram
 360 to form an address and then push the value of the memory location at that address.
 361 This value is the \doublequote{contents} of an otherwise anonymous location.
 362
 363 \descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregfive{} \DWOPplusuconst{} 16 }
 364 The address of the memory location is calculated by adding 16 to the value
 365 contained in register 5 upon entering the current subprogram.
 366
 367 \textit{Note that unlike the previous \DWOPentryvalue{} examples, this one does not end
 368 with \DWOPstackvalue.{}}
 369
 370 \bb
 371 \descriptionitemnl{\DWOPregzero{} \DWOPbitpiece{} 1 31 \DWOPbitpiece{} 7 0 \DWOPregone{} }
 372 \vspace{-1\parsep}\descriptionitemnl{
 373 \hspace{0.5cm}\DWOPpiece{} 1 }
 374 A variable whose first bit resides in the 31st bit of register 0, whose next
 375 seven bits are undefined and whose second byte resides in register 1.
 376 \eb
 377 \end{description}
 378
 379 %\clearpage
 380 \section{Aggregate Examples}
 381 \label{app:aggregateexamples}
 382
 383 The following examples illustrate how to represent some of
 384 the more complicated forms of array and record aggregates
 385 using DWARF.
 386
 387 \subsection{Fortran Simple Array Example}
 388 \label{app:fortranarrayexample}
 389 Consider the \addtoindex{Fortran array}\addtoindexx{Fortran 90} source fragment in
 390 \addtoindexx{array type entry!examples}
 391 Figure \referfol{fig:fortranarrayexamplesourcefragment}.
 392
 393 \begin{figure}[ht]
 394 \begin{nlnlisting}
 395         TYPE array_ptr
 396         REAL :: myvar
 397         REAL, DIMENSION (:), POINTER :: ap
 398         END TYPE array_ptr
 399         TYPE(array_ptr), ALLOCATABLE, DIMENSION(:) :: arrayvar
 400         ALLOCATE(arrayvar(20))
 401         DO I = 1, 20
 402             ALLOCATE(arrayvar(i)%ap(i+10))
 403         END DO
 404 \end{nlnlisting}
 405 \caption{Fortran array example: source fragment}
 406 \label{fig:fortranarrayexamplesourcefragment}
 407 \end{figure}
 408
 409 For allocatable and pointer arrays, it is essentially required
 410 by the\addtoindex{Fortran array} semantics that each array
 411 consist of two parts, which we here call 1) the
 412 descriptor\addtoindexx{descriptor!array}\addtoindexx{array!descriptor for}
 413 and 2) the raw
 414 data. (A descriptor has often been called a dope vector in
 415 other contexts, although it is often a structure of some kind
 416 rather than a simple vector.) Because there are two parts,
 417 and because the lifetime of the descriptor is necessarily
 418 longer than and includes that of the raw data, there must be
 419 an address somewhere in the descriptor that points to the
 420 raw data when, in fact, there is some (that is, when
 421 the \doublequote{variable} is allocated or associated).
 422
 423 For concreteness, suppose that a descriptor looks something
 424 like the C structure in
 425 Figure \refersec{fig:fortranarrayexampledescriptorrepresentation}.
 426 Note, however, that it is
 427 a property of the design that 1) a debugger needs no builtin
 428 knowledge of this structure and 2) there does not need to
 429 be an explicit representation of this structure in the DWARF
 430 input to the debugger.
 431
 432 \begin{figure}[ht]
 433 \begin{nlnlisting}
 434 struct desc {
 435     long el_len;       // Element length
 436     void * base;       // Address of raw data
 437     int ptr_assoc : 1; // Pointer is associated flag
 438     int ptr_alloc : 1; // Pointer is allocated flag
 439     int num_dims  : 6; // Number of dimensions
 440     struct dims_str {  // For each dimension...
 441         long low_bound;
 442         long upper_bound;
 443         long stride;
 444     } dims[63];
 445 };
 446 \end{nlnlisting}
 447 \caption{Fortran array example: descriptor representation}
 448 \label{fig:fortranarrayexampledescriptorrepresentation}
 449 \end{figure}
 450
 451
 452 In practice, of course, a \doublequote{real} descriptor will have
 453 dimension substructures only for as many dimensions as are
 454 specified in the \texttt{num\_dims} component. Let us use the notation
 455 \texttt{desc\textless n\textgreater}
 456 to indicate a specialization of the \texttt{desc} struct in
 457 which \texttt{n} is the bound for the \texttt{dims} component as well as the
 458 contents of the \texttt{num\_dims} component.
 459
 460 Because the arrays considered here come in two parts, it is
 461 necessary to distinguish the parts carefully. In particular,
 462 the \doublequote{address of the variable} or equivalently, the \doublequote{base
 463 address of the object} \emph{always} refers to the descriptor. For
 464 arrays that do not come in two parts, an implementation can
 465 provide a descriptor anyway, thereby giving it two parts. (This
 466 may be convenient for general runtime support unrelated to
 467 debugging.) In this case the above vocabulary applies as
 468 stated. Alternatively, an implementation can do without a
 469 descriptor, in which case the \doublequote{address of the variable,}
 470 or equivalently the \doublequote{base address of the object}, refers
 471 to the \doublequote{raw data} (the real data, the only thing around
 472 that can be the object).
 473
 474 If an object has a descriptor, then the DWARF type for that
 475 object will have a
 476 \DWATdatalocation{}
 477 attribute. If an object
 478 does not have a descriptor, then usually the DWARF type for the
 479 object will not have a
 480 \DWATdatalocation{} attribute.
 481 (See the following
 482 \addtoindex{Ada} example for a case where the type for an object without
 483 a descriptor does have a
 484 \DWATdatalocation{} attribute. In
 485 that case the object doubles as its own descriptor.)
 486
 487 \needlines{6}
 488 The \addtoindex{Fortran} derived type \texttt{array\_ptr} can now be re-described
 489 in C-like terms that expose some of the representation as in
 490 \par % Needed to end paragraph before listing so that it gets a line number
 491 \begin{nlnlisting}
 492 struct array_ptr {
 493     float myvar;
 494     desc<1> ap;
 495 };
 496 \end{nlnlisting}
 497
 498 Similarly for variable \texttt{arrayvar}:
 499 \par % Needed to end paragraph before listing so that it gets a line number
 500 \begin{nlnlisting}
 501 desc<1> arrayvar;
 502 \end{nlnlisting}
 503
 504 \textit{
 505 Recall that \texttt{desc\textless 1\textgreater}
 506 indicates the 1\dash dimensional version of \texttt{desc}.
 507 }
 508
 509 Finally, the following notation is useful:
 510 \begin{enumerate}[1. ]
 511 \item  sizeof(type): size in bytes of entities of the given type
 512 \item offset(type, comp): offset in bytes of the comp component
 513 within an entity of the given type
 514 \end{enumerate}
 515
 516 The DWARF description is shown
 517 \addtoindexx{Fortran 90}
 518 in Figure \refersec{fig:fortranarrayexampledwarfdescription}.
 519
 520 \begin{figure}[ht]
 521 \figurepart{1}{2}
 522 \begin{dwflisting}
 523 \begin{alltt}
 524 ! Description for type of 'ap'
 525 !
 526 1\$: \DWTAGarraytype
 527         ! No name, default (Fortran) ordering, default stride
 528         \DWATtype(reference to REAL)
 529         \DWATassociated(expression=    ! Test 'ptr\_assoc' \nolink{flag}
 530             \DWOPpushobjectaddress
 531             \DWOPlitn                ! where n == offset(ptr\_assoc)
 532             \DWOPplus
 533             \DWOPderef
 534             \DWOPlitone                  ! mask for 'ptr\_assoc' \nolink{flag}
 535             \DWOPand)
 536         \DWATdatalocation(expression= ! Get raw data address
 537             \DWOPpushobjectaddress
 538             \DWOPlitn                ! where n == offset(base)
 539             \DWOPplus
 540             \DWOPderef)                ! Type of index of array 'ap'
 541 2\$:     \DWTAGsubrangetype
 542             ! No name, default stride
 543             \DWATtype(reference to INTEGER)
 544             \DWATlowerbound(expression=
 545                 \DWOPpushobjectaddress
 546                 \DWOPlitn             ! where n ==
 547                                          !   offset(desc, dims) +
 548                                          !   offset(dims\_str, lower\_bound)
 549                 \DWOPplus
 550                 \DWOPderef)
 551             \DWATupperbound(expression=
 552                 \DWOPpushobjectaddress
 553                 \DWOPlitn            ! where n ==
 554                                         !   offset(desc, dims) +
 555                                         !   offset(dims\_str, upper\_bound)
 556                 \DWOPplus
 557                 \DWOPderef)
 558             !  Note: for the m'th dimension, the second operator becomes
 559             !  \DWOPlitn where
 560             !       n == offset(desc, dims)          +
 561             !                (m-1)*sizeof(dims\_str)  +
 562             !                 offset(dims\_str, [lower|upper]\_bound)
 563             !  That is, the expression does not get longer for each successive
 564             !  dimension (other than to express the larger offsets involved).
 565 \end{alltt}
 566 \end{dwflisting}
 567 \caption{Fortran array example: DWARF description}
 568 \label{fig:fortranarrayexampledwarfdescription}
 569 \end{figure}
 570
 571 \begin{figure}
 572 \figurepart{2}{2}
 573 \begin{dwflisting}
 574 \begin{alltt}
 575 3\$: \DWTAGstructuretype
 576         \DWATname("array\_ptr")
 577         \DWATbytesize(constant sizeof(REAL) + sizeof(desc<1>))
 578 4\$:     \DWTAGmember
 579             \DWATname("myvar")
 580             \DWATtype(reference to REAL)
 581             \DWATdatamemberlocation(constant 0)
 582 5\$:     \DWTAGmember
 583             \DWATname("ap");
 584             \DWATtype(reference to 1\$)
 585             \DWATdatamemberlocation(constant sizeof(REAL))
 586 6\$: \DWTAGarraytype
 587         ! No name, default (Fortran) ordering, default stride
 588         \DWATtype(reference to 3\$)
 589         \DWATallocated(expression=       ! Test 'ptr\_alloc' \nolink{flag}
 590             \DWOPpushobjectaddress
 591             \DWOPlitn                  ! where n == offset(ptr\_alloc)
 592             \DWOPplus
 593             \DWOPderef
 594             \DWOPlittwo                    ! Mask for 'ptr\_alloc' \nolink{flag}
 595             \DWOPand)
 596         \DWATdatalocation(expression=   ! Get raw data address
 597             \DWOPpushobjectaddress
 598             \DWOPlitn                  ! where n == offset(base)
 599             \DWOPplus
 600             \DWOPderef)
 601 7\$:     \DWTAGsubrangetype
 602             ! No name, default stride
 603             \DWATtype(reference to INTEGER)
 604             \DWATlowerbound(expression=
 605                 \DWOPpushobjectaddress
 606                 \DWOPlitn              ! where n == ...
 607                 \DWOPplus
 608                 \DWOPderef)
 609             \DWATupperbound(expression=
 610                 \DWOPpushobjectaddress
 611                 \DWOPlitn              ! where n == ...
 612                 \DWOPplus
 613                 \DWOPderef)
 614 8\$: \DWTAGvariable
 615         \DWATname("arrayvar")
 616         \DWATtype(reference to 6\$)
 617         \DWATlocation(expression=
 618             ...as appropriate...)       ! Assume static allocation
 619 \end{alltt}
 620 \end{dwflisting}
 621 \begin{center}
 622 \vspace{3mm}
 623 Figure~\ref{fig:fortranarrayexampledwarfdescription}: Fortran array example: DWARF description \textit{(concluded)}
 624 \end{center}
 625 \end{figure}
 626
 627 Suppose
 628 \addtoindexx{Fortran array example}
 629 the program is stopped immediately following completion
 630 of the do loop. Suppose further that the user enters the
 631 following debug command:
 632 \par % Needed to end paragraph before listing so that it gets a line number
 633 \vspace{2mm}
 634 \begin{nlnlisting}
 635 debug> print arrayvar(5)%ap(2)
 636 \end{nlnlisting}
 637
 638 Interpretation of this expression proceeds as follows:
 639 \begin{enumerate}[1. ]
 640
 641 \item Lookup name \texttt{arrayvar}. We find that it is a variable,
 642 whose type is given by the unnamed type at 6\$. Notice that
 643 the type is an array type.
 644
 645
 646 \item Find the 5$^{th}$ element of that array object. To do array
 647 indexing requires several pieces of information:
 648 \begin{enumerate}[a) ]
 649
 650 \item  the address of the array data
 651
 652 \item the lower bounds of the array \\
 653 % Using plain [] here gives trouble.
 654 \lbrack To check that 5 is within bounds would require the upper
 655 bound too, but we will skip that for this example. \rbrack
 656
 657 \item the stride
 658
 659 \end{enumerate}
 660
 661 For a), check for a
 662 \DWATdatalocation{} attribute.
 663 Since there is one, go execute the expression, whose result is
 664 the address needed. The object address used in this case
 665 is the object we are working on, namely the variable named
 666 \texttt{arrayvar}, whose address was found in step 1. (Had there been
 667 no \DWATdatalocation{} attribute, the desired address would
 668 be the same as the address from step 1.)
 669
 670 For b), for each dimension of the array (only one
 671 in this case), go interpret the usual lower bound
 672 attribute. Again this is an expression, which again begins
 673 with \DWOPpushobjectaddress. This object is
 674 \textbf{still} \texttt{arrayvar},
 675 from step 1, because we have not begun to actually perform
 676 any indexing yet.
 677
 678 For c), the default stride applies. Since there is no
 679 \DWATbytestride{} attribute, use the size of the array element
 680 type, which is the size of type \texttt{array\_ptr} (at 3\$).
 681
 682 \clearpage
 683
 684 Having acquired all the necessary data, perform the indexing
 685 operation in the usual manner--which has nothing to do with
 686 any of the attributes involved up to now. Those just provide
 687 the actual values used in the indexing step.
 688
 689 The result is an object within the memory that was dynamically
 690 allocated for \texttt{arrayvar}.
 691
 692 \item  Find the \texttt{ap} component of the object just identified,
 693 whose type is \texttt{array\_ptr}.
 694
 695 This is a conventional record component lookup and
 696 interpretation. It happens that the \texttt{ap} component in this case
 697 begins at offset 4 from the beginning of the containing object.
 698 Component \texttt{ap} has the unnamed array type defined at 1\$ in the
 699 symbol table.
 700
 701 \item  Find the second element of the array object found in step 3.
 702 To do array indexing requires
 703 several pieces of information:
 704 \begin{enumerate}[a) ]
 705 \item  the address of the array storage
 706
 707 \item  the lower bounds of the array \\
 708 % Using plain [] here gives trouble.
 709 \lbrack To check that 2 is within bounds we would require the upper
 710 bound too, but we will skip that for this example \rbrack
 711
 712 \item  the stride
 713
 714 \end{enumerate}
 715 \end{enumerate}
 716
 717 This is just like step 2), so the details are omitted. Recall
 718 that because the DWARF type 1\$ has a \DWATdatalocation,
 719 the address that results from step 4) is that of a
 720 descriptor, and that address is the address pushed by the
 721 \DWOPpushobjectaddress{} operations in 1\$ and 2\$.
 722
 723 Note: we happen to be accessing a pointer array here instead
 724 of an allocatable array; but because there is a common
 725 underlying representation, the mechanics are the same. There
 726 could be completely different descriptor arrangements and the
 727 mechanics would still be the same---only the stack machines
 728 would be different.
 729
 730 %\needlines{8}
 731 \subsection{Fortran Coarray Examples}
 732 \label{app:Fortrancoarrayexamples}
 733
 734 \subsubsection{Fortran Scalar Coarray Example}
 735 The \addtoindex{Fortran} scalar coarray example
 736 \addtoindexx{coarray!example}\addtoindexx{scalar coarray|see{coarray}}
 737 in Figure \refersec{fig:Fortranscalarcoarraysourcefragment} can be described as
 738 illustrated in Figure \refersec{fig:FortranscalarcoarrayDWARFdescription}.
 739
 740 \begin{figure}[!ht]
 741 \begin{nlnlisting}
 742         INTEGER x[*]
 743 \end{nlnlisting}
 744 \caption{Fortran scalar coarray: source fragment}
 745 \label{fig:Fortranscalarcoarraysourcefragment}
 746 \end{figure}
 747
 748 \begin{figure}[!ht]
 749 \begin{dwflisting}
 750 \begin{alltt}
 751 10\$:  \DWTAGcoarraytype
 752           \DWATtype(reference to INTEGER)
 753           \DWTAGsubrangetype                ! Note omitted upper bound
 754           \DWATlowerbound(constant 1)       ! Can be omitted (default is 1)
 755
 756 11\$:  \DWTAGvariable
 757           \DWATname("x")
 758           \DWATtype(reference to coarray type at 10\$)
 759 \end{alltt}
 760 \end{dwflisting}
 761 \caption{Fortran scalar coarray: DWARF description}
 762 \label{fig:FortranscalarcoarrayDWARFdescription}
 763 \end{figure}
 764
 765 \subsubsection{Fortran Array Coarray Example}
 766 The \addtoindex{Fortran} (simple) array coarray example
 767 \addtoindexx{coarray!example}\addtoindexx{array coarray|see{coarray}}
 768 in Figure \refersec{fig:Fortranarraycoarraysourcefragment} can be described as
 769 illustrated in Figure \refersec{fig:FortranarraycoarrayDWARFdescription}.
 770
 771 \begin{figure}[ht]
 772 \begin{nlnlisting}
 773         INTEGER x(10)[*]
 774 \end{nlnlisting}
 775 \caption{Fortran array coarray: source fragment}
 776 \label{fig:Fortranarraycoarraysourcefragment}
 777 \end{figure}
 778
 779 \begin{figure}[ht]
 780 \begin{dwflisting}
 781 \begin{alltt}
 782 10\$:  \DWTAGarraytype
 783           \DWATordering(\DWORDcolmajor)
 784           \DWATtype(reference to INTEGER)
 785 11\$:      \DWTAGsubrangetype
 786             ! \textit{DW\_AT\_lower\_bound(constant 1)}   ! Omitted (default is 1)
 787               \DWATupperbound(constant 10)
 788
 789 12\$:  \DWTAGcoarraytype
 790           \DWATtype(reference to array type at 10\$)
 791 13\$:      \DWTAGsubrangetype                ! Note omitted upper \& lower bounds
 792
 793 14$:  \DWTAGvariable
 794           \DWATname("x")
 795           \DWATtype(reference to coarray type at 12\$)
 796 \end{alltt}
 797 \end{dwflisting}
 798 \caption{Fortran array coarray: DWARF description}
 799 \label{fig:FortranarraycoarrayDWARFdescription}
 800 \end{figure}
 801
 802 \needlines{6}
 803 \subsubsection{Fortran Multidimensional Coarray Example}
 804 The \addtoindex{Fortran} multidimensional coarray of a multidimensional array example
 805 \addtoindexx{coarray!example}\addtoindexx{array coarray|see{coarray}}
 806 in Figure \refersec{fig:Fortranmultidimensionalcoarraysourcefragment} can be described as
 807 illustrated in Figure \referfol{fig:FortranmultidimensionalcoarrayDWARFdescription}.
 808
 809 \begin{figure}[ht]
 810 \begin{nlnlisting}
 811         INTEGER x(10,11,12)[2,3,*]
 812 \end{nlnlisting}
 813 \caption{Fortran multidimensional coarray: source fragment}
 814 \label{fig:Fortranmultidimensionalcoarraysourcefragment}
 815 \end{figure}
 816
 817 \begin{figure}[ht]
 818 \begin{dwflisting}
 819 \begin{alltt}
 820
 821 10\$:  \DWTAGarraytype                ! Note omitted lower bounds (default to 1)
 822           \DWATordering(\DWORDcolmajor)
 823           \DWATtype(reference to INTEGER)
 824 11\$:      \DWTAGsubrangetype
 825               \DWATupperbound(constant 10)
 826 12\$:      \DWTAGsubrangetype
 827               \DWATupperbound(constant 11)
 828 13\$:      \DWTAGsubrangetype
 829               \DWATupperbound(constant 12)
 830
 831 14\$:  \DWTAGcoarraytype              ! Note omitted lower bounds (default to 1)
 832           \DWATtype(reference to array_type at 10\$)
 833 15\$:      \DWTAGsubrangetype
 834               \DWATupperbound(constant 2)
 835 16\$:      \DWTAGsubrangetype
 836               \DWATupperbound(constant 3)
 837 17\$:      \DWTAGsubrangetype         ! Note omitted upper (\& lower) bound
 838
 839 18\$:  \DWTAGvariable
 840           \DWATname("x")
 841           \DWATtype(reference to coarray type at 14\$)
 842
 843 \end{alltt}
 844 \end{dwflisting}
 845 \caption{Fortran multidimensional coarray: DWARF description}
 846 \label{fig:FortranmultidimensionalcoarrayDWARFdescription}
 847 \end{figure}
 848
 849
 850 \clearpage
 851 \subsection{Fortran 2008 Assumed-rank Array Example}
 852 \label{app:assumedrankexample}
 853 \addtoindexx{array!assumed-rank}
 854 Consider the example in Figure~\ref{fig:assumedrankdecl}, which shows
 855 an assumed-rank array in Fortran~2008 with
 856 supplement~29113:\footnote{Technical Specification ISO/IEC TS
 857   29113:2012 \emph{Further Interoperability of Fortran with C}}
 858
 859 \begin{figure}[!ht]
 860 \begin{nlnlisting}
 861   SUBROUTINE Foo(x)
 862     REAL :: x(..)
 863
 864     ! x has n dimensions
 865
 866   END SUBROUTINE
 867 \end{nlnlisting}
 868 \caption{Declaration of a Fortran 2008 assumed-rank array}
 869 \label{fig:assumedrankdecl}
 870 \end{figure}
 871
 872 Let's assume the Fortran compiler used an array descriptor that
 873 (in \addtoindex{C}) looks
 874 like the one shown in Figure~\ref{fig:arraydesc}.
 875
 876 \begin{figure}[!ht]
 877 \begin{nlnlisting}
 878   struct array_descriptor {
 879     void *base_addr;
 880     int rank;
 881     struct dim dims[];
 882   }
 883
 884   struct dim {
 885      int lower_bound;
 886      int upper_bound;
 887      int stride;
 888      int flags;
 889   }
 890 \end{nlnlisting}
 891 \caption{One of many possible layouts for an array descriptor}
 892 \label{fig:arraydesc}
 893 \end{figure}
 894
 895 The DWARF type for the array \emph{x} can be described as shown in
 896 Figure~\refersec{fig:assumedrankdwarf}.
 897
 898 \begin{figure}[!ht]
 899 \begin{dwflisting}
 900 \begin{alltt}
 901 10\$:  \DWTAGarraytype
 902           \DWATtype(reference to real)
 903           \DWATrank(expression=
 904               \DWOPpushobjectaddress
 905               \DWOPlitn                        ! offset of rank in descriptor
 906               \DWOPplus
 907               \DWOPderef)
 908           \DWATdatalocation(expression=
 909               \DWOPpushobjectaddress
 910               \DWOPlitn                        ! offset of data in descriptor
 911               \DWOPplus
 912               \DWOPderef)
 913 11\$:     \DWTAGgenericsubrange
 914               \DWATtype(reference to integer)
 915               \DWATlowerbound(expression=
 916               !   Looks up the lower bound of dimension i.
 917               !   Operation                       ! Stack effect
 918               !   (implicit)                      ! i
 919                   \DWOPlitn                    ! i sizeof(dim)
 920                   \DWOPmul                       ! dim[i]
 921                   \DWOPlitn                    ! dim[i] offsetof(dim)
 922                   \DWOPplus                      ! dim[i]+offset
 923                   \DWOPpushobjectaddress       ! dim[i]+offsetof(dim) objptr
 924                   \DWOPplus                      ! objptr.dim[i]
 925                   \DWOPlitn                    ! objptr.dim[i] offsetof(lb)
 926                   \DWOPplus                      ! objptr.dim[i].lowerbound
 927                   \DWOPderef)                    ! *objptr.dim[i].lowerbound
 928               \DWATupperbound(expression=
 929               !   Looks up the upper bound of dimension i.
 930                   \DWOPlitn                    ! sizeof(dim)
 931                   \DWOPmul
 932                   \DWOPlitn                    ! offsetof(dim)
 933                   \DWOPplus
 934                   \DWOPpushobjectaddress
 935                   \DWOPplus
 936                   \DWOPlitn                    ! offset of upperbound in dim
 937                   \DWOPplus
 938                   \DWOPderef)
 939               \DWATbytestride(expression=
 940               !   Looks up the byte stride of dimension i.
 941                   ...
 942               !   (analogous to \DWATupperboundNAME)
 943                   )
 944 \end{alltt}
 945 \end{dwflisting}
 946 \caption{Sample DWARF for the array descriptor in Figure~\ref{fig:arraydesc}}
 947 \label{fig:assumedrankdwarf}
 948 \end{figure}
 949
 950 The layout of the array descriptor is not specified by the Fortran
 951 standard unless the array is explicitly marked as \addtoindex{C-interoperable}. To
 952 get the bounds of an assumed-rank array, the expressions in the
 953 \DWTAGgenericsubrange{}
 954 entry need to be evaluated for each of the
 955 \DWATrank{} dimensions as shown by the pseudocode in
 956 Figure~\refersec{fig:assumedrankdwarfparser}.
 957
 958 \begin{figure}[!ht]
 959 \begin{nlnlisting}
 960     typedef struct {
 961         int lower, upper, stride;
 962     } dims_t;
 963
 964     typedef struct {
 965         int rank;
 966     struct dims_t *dims;
 967     } array_t;
 968
 969     array_t get_dynamic_array_dims(DW_TAG_array a) {
 970       array_t result;
 971
 972       // Evaluate the DW_AT_rank expression to get the
 973       //    number of dimensions.
 974       dwarf_stack_t stack;
 975       dwarf_eval(stack, a.rank_expr);
 976       result.rank = dwarf_pop(stack);
 977       result.dims = new dims_t[rank];
 978
 979       // Iterate over all dimensions and find their bounds.
 980       for (int i = 0; i < result.rank; i++) {
 981         // Evaluate the generic subrange's DW_AT_lower
 982         //    expression for dimension i.
 983         dwarf_push(stack, i);
 984         assert( stack.size == 1 );
 985         dwarf_eval(stack, a.generic_subrange.lower_expr);
 986         result.dims[i].lower = dwarf_pop(stack);
 987         assert( stack.size == 0 );
 988
 989         dwarf_push(stack, i);
 990         dwarf_eval(stack, a.generic_subrange.upper_expr);
 991         result.dims[i].upper = dwarf_pop(stack);
 992
 993         dwarf_push(stack, i);
 994         dwarf_eval(stack, a.generic_subrange.byte_stride_expr);
 995         result.dims[i].stride = dwarf_pop(stack);
 996       }
 997       return result;
 998     }
 999 \end{nlnlisting}
1000 \caption{How to interpret the DWARF from Figure~\ref{fig:assumedrankdwarf}}
1001 \label{fig:assumedrankdwarfparser}
1002 \end{figure}
1003
1004
1005 \clearpage
1006 \subsection{Fortran Dynamic Type Example}
1007 \label{app:fortrandynamictypeexample}
1008 Consider the \addtoindex{Fortran 90} example of dynamic properties in
1009 Figure \refersec{fig:fortrandynamictypeexamplesource}.
1010 This can be represented in DWARF as illustrated in
1011 Figure \refersec{fig:fortrandynamictypeexampledwarfdescription}.
1012 Note that unnamed dynamic types are used to avoid replicating
1013 the full description of the underlying type \texttt{dt} that is shared by
1014 several variables.
1015
1016 \begin{figure}[ht]
1017 \begin{nlnlisting}
1018         PROGRAM Sample
1019
1020         TYPE :: dt (l)
1021             INTEGER, LEN :: l
1022             INTEGER :: arr(l)
1023         END TYPE
1024
1025         INTEGER :: n = 4
1026         CONTAINS
1027
1028         SUBROUTINE S()
1029             TYPE (dt(n))               :: t1
1030             TYPE (dt(n)), pointer      :: t2
1031             TYPE (dt(n)), allocatable  :: t3, t4
1032         END SUBROUTINE
1033
1034         END Sample
1035 \end{nlnlisting}
1036 \caption{Fortran dynamic type example: source}
1037 \label{fig:fortrandynamictypeexamplesource}
1038 \end{figure}
1039
1040 \begin{figure}[ht]
1041 \begin{dwflisting}
1042 \begin{alltt}
1043 11$:    \DWTAGstructuretype
1044             \DWATname("dt")
1045             \DWTAGmember
1046                 ...
1047                         ...
1048
1049 13$:    \DWTAGdynamictype             ! plain version
1050             \DWATdatalocation (dwarf expression to locate raw data)
1051             \DWATtype (11$)
1052
1053 14$:    \DWTAGdynamictype             ! 'pointer' version
1054             \DWATdatalocation (dwarf expression to locate raw data)
1055             \DWATassociated (dwarf expression to test if associated)
1056             \DWATtype (11$)
1057
1058 15$:    \DWTAGdynamictype             ! 'allocatable' version
1059             \DWATdatalocation (dwarf expression to locate raw data)
1060             \DWATallocated (dwarf expression to test is allocated)
1061             \DWATtype (11$)
1062
1063 16$:    \DWTAGvariable
1064             \DWATname ("t1")
1065             \DWATtype (13$)
1066             \DWATlocation (dwarf expression to locate descriptor)
1067 17$:    \DWTAGvariable
1068             \DWATname ("t2")
1069             \DWATtype (14$)
1070             \DWATlocation (dwarf expression to locate descriptor)
1071 18$:    \DWTAGvariable
1072             \DWATname ("t3")
1073             \DWATtype (15$)
1074             \DWATlocation (dwarf expression to locate descriptor)
1075 19$:    \DWTAGvariable
1076             \DWATname ("t4")
1077             \DWATtype (15$)
1078             \DWATlocation (dwarf expression to locate descriptor)
1079 \end{alltt}
1080 \end{dwflisting}
1081 \caption{Fortran dynamic type example: DWARF description}
1082 \label{fig:fortrandynamictypeexampledwarfdescription}
1083 \end{figure}
1084
1085 \clearpage
1086 \subsection{C/C++ Anonymous Structure Example}
1087 \label{app:ccxxanonymousstructureexample}
1088 \addtoindexx{anonymous structure}
1089 An example of a \addtoindex{C}/\addtoindex{C++} structure is shown in
1090 Figure \ref{fig:anonymousstructureexamplesourcefragment}.
1091 For this source, the DWARF description in
1092 Figure \ref{fig:anonymousstructureexampledwarfdescription}
1093 is appropriate. In this example, \texttt{b} is referenced as if it
1094 were defined in the enclosing structure \texttt{foo}.
1095
1096 \begin{figure}[ht]
1097 \begin{nlnlisting}
1098 struct foo {
1099     int a;
1100     struct {
1101         int b;
1102     };
1103 } x;
1104
1105 void bar(void)
1106 {
1107     struct foo t;
1108     t.a = 1;
1109     t.b = 2;
1110 }
1111
1112 \end{nlnlisting}
1113 \caption{Anonymous structure example: source fragment}
1114 \label{fig:anonymousstructureexamplesourcefragment}
1115 \end{figure}
1116
1117 \begin{figure}[ht]
1118 \begin{dwflisting}
1119 \begin{alltt}
1120 1$:   \DWTAGstructuretype
1121           \DWATname("foo")
1122 2$:       \DWTAGmember
1123               \DWATname("a")
1124 3$:       \DWTAGstructuretype
1125               \DWATexportsymbols
1126 4$:           \DWTAGmember
1127                   \DWATname("b")
1128 \end{alltt}
1129 \end{dwflisting}
1130 \caption{Anonymous structure example: DWARF description}
1131 \label{fig:anonymousstructureexampledwarfdescription}
1132 \end{figure}
1133
1134 \subsection{Ada Example}
1135 \label{app:adaexample}
1136 Figure \refersec{fig:adaexamplesourcefragment}
1137 illustrates two kinds of \addtoindex{Ada}
1138 parameterized array, one embedded in a record.
1139
1140 \begin{figure}[ht]
1141 \begin{nlnlisting}
1142 M : INTEGER := <exp>;
1143 VEC1 : array (1..M) of INTEGER;
1144 subtype TEENY is INTEGER range 1..100;
1145 type ARR is array (INTEGER range <>) of INTEGER;
1146 type REC2(N : TEENY := 100) is record
1147     VEC2 : ARR(1..N);
1148 end record;
1149
1150 OBJ2B : REC2;
1151 \end{nlnlisting}
1152 \caption{Ada example: source fragment}
1153 \label{fig:adaexamplesourcefragment}
1154 \end{figure}
1155
1156 \texttt{VEC1} illustrates an (unnamed) array type where the upper bound
1157 of the first and only dimension is determined at runtime.
1158 \addtoindex{Ada}
1159 semantics require that the value of an array bound is fixed at
1160 the time the array type is elaborated (where \textit{elaboration} refers
1161 to the runtime executable aspects of type processing). For
1162 the purposes of this example, we assume that there are no
1163 other assignments to \texttt{M} so that it safe for the \texttt{REC1} type
1164 description to refer directly to that variable (rather than
1165 a compiler-generated copy).
1166
1167 \texttt{REC2} illustrates another array type (the unnamed type of
1168 component \texttt{VEC2}) where the upper bound of the first and only
1169 bound is also determined at runtime. In this case, the upper
1170 bound is contained in a discriminant of the containing record
1171 type. (A \textit{discriminant} is a component of a record whose value
1172 cannot be changed independently of the rest of the record
1173 because that value is potentially used in the specification
1174 of other components of the record.)
1175
1176 The DWARF description is shown in
1177 Figure \refersec{fig:adaexampledwarfdescription}.
1178
1179
1180 Interesting aspects about this example are:
1181 \begin{enumerate}[1. ]
1182 \item The array \texttt{VEC2} is \doublequote{immediately} contained within structure
1183 \texttt{REC2} (there is no intermediate descriptor or indirection),
1184 which is reflected in the absence of a \DWATdatalocation{}
1185 attribute on the array type at 28\$.
1186
1187 \item One of the bounds of \texttt{VEC2} is nonetheless dynamic and part of
1188 the same containing record. It is described as a reference to
1189 a member, and the location of the upper bound is determined
1190 as for any member. That is, the location is determined using
1191 an address calculation relative to the base of the containing
1192 object.
1193
1194 A consumer must notice that the referenced bound is a
1195 member of the same containing object and implicitly push the
1196 base address of the containing object just as for accessing
1197 a data member generally.
1198
1199 \item The lack of a subtype concept in DWARF means that DWARF types
1200 serve the role of subtypes and must replicate information from
1201 the parent type. For this reason, DWARF for
1202 the unconstrained array type \texttt{ARR} is not needed for the purposes
1203 of this example and therefore is not shown.
1204 \end{enumerate}
1205
1206 \begin{figure}[p]
1207 \begin{dwflisting}
1208 \begin{alltt}
1209 11\$:  \DWTAGvariable
1210           \DWATname("M")
1211           \DWATtype(reference to INTEGER)
1212 12\$:  \DWTAGarraytype
1213           ! No name, default (\addtoindex{Ada}) order, default stride
1214           \DWATtype(reference to INTEGER)
1215 13\$:      \DWTAGsubrangetype
1216               \DWATtype(reference to INTEGER)
1217               \DWATlowerbound(constant 1)
1218               \DWATupperbound(reference to variable M at 11\$)
1219 14\$:  \DWTAGvariable
1220           \DWATname("VEC1")
1221           \DWATtype(reference to array type at 12\$)
1222       . . .
1223 21\$:  \DWTAGsubrangetype
1224           \DWATname("TEENY")
1225           \DWATtype(reference to INTEGER)
1226           \DWATlowerbound(constant 1)
1227           \DWATupperbound(constant 100)
1228       . . .
1229 26\$:  \DWTAGstructuretype
1230           \DWATname("REC2")
1231 27\$:      \DWTAGmember
1232               \DWATname("N")
1233               \DWATtype(reference to subtype TEENY at 21\$)
1234               \DWATdatamemberlocation(constant 0)
1235 28\$:      \DWTAGarraytype
1236               ! No name, default (\addtoindex{Ada}) order, default stride
1237               ! Default data location
1238               \DWATtype(reference to INTEGER)
1239 29\$:          \DWTAGsubrangetype
1240                   \DWATtype(reference to subrange TEENY at 21\$)
1241                   \DWATlowerbound(constant 1)
1242                   \DWATupperbound(reference to member N at 27\$)
1243 30\$:      \DWTAGmember
1244               \DWATname("VEC2")
1245               \DWATtype(reference to array "subtype" at 28\$)
1246               \DWATdatamemberlocation(machine=
1247                   \DWOPlitn                ! where n == offset(REC2, VEC2)
1248                   \DWOPplus)
1249       . . .
1250 41\$:  \DWTAGvariable
1251           \DWATname("OBJ2B")
1252           \DWATtype(reference to REC2 at 26\$)
1253           \DWATlocation(...as appropriate...)
1254 \end{alltt}
1255 \end{dwflisting}
1256 \caption{Ada example: DWARF description}
1257 \label{fig:adaexampledwarfdescription}
1258 \end{figure}
1259
1260 \clearpage
1261
1262 \subsection{Pascal Example}
1263 \label{app:pascalexample}
1264 The Pascal \addtoindexx{Pascal example} source in
1265 Figure \referfol{fig:packedrecordexamplesourcefragment}
1266 is used to illustrate the representation of packed unaligned
1267 \addtoindex{bit fields}.
1268
1269 \begin{figure}[ht]
1270 \begin{nlnlisting}
1271 TYPE T : PACKED RECORD                  { bit size is 2   }
1272          F5 : BOOLEAN;                  { bit offset is 0 }
1273          F6 : BOOLEAN;                  { bit offset is 1 }
1274          END;
1275 VAR V :  PACKED RECORD
1276          F1 : BOOLEAN;                  { bit offset is 0 }
1277          F2 : PACKED RECORD             { bit offset is 1 }
1278               F3 : INTEGER;             { bit offset is 0 in F2,
1279                                           1 in V }
1280               END;
1281          F4 : PACKED ARRAY [0..1] OF T; { bit offset is 33 }
1282          F7 : T;                        { bit offset is 37 }
1283          END;
1284 \end{nlnlisting}
1285 \caption{Packed record example: source fragment}
1286 \label{fig:packedrecordexamplesourcefragment}
1287 \end{figure}
1288
1289 The DWARF representation in
1290 Figure \refersec{fig:packedrecordexampledwarfdescription}
1291 is appropriate.
1292 \DWTAGpackedtype{} entries could be added to
1293 better represent the source, but these do not otherwise affect
1294 the example and are omitted for clarity. Note that this same
1295 representation applies to both typical big- and
1296 little-endian
1297 architectures using the conventions described in
1298 Section \refersec{chap:datamemberentries}.
1299
1300 \begin{figure}[ht]
1301 \figurepart{1}{2}
1302 \begin{dwflisting}
1303 \begin{alltt}
1304 10\$:  \DWTAGbasetype
1305           \DWATname("BOOLEAN")
1306               ...
1307 11\$:  \DWTAGbasetype
1308           \DWATname("INTEGER")
1309               ...
1310 20\$:  \DWTAGstructuretype
1311           \DWATname("T")
1312           \DWATbitsize(2)
1313           \DWTAGmember
1314               \DWATname("F5")
1315               \DWATtype(reference to 10$)
1316               \DWATdatabitoffset(0)        ! may be omitted
1317               \DWATbitsize(1)
1318 \end{alltt}
1319 \end{dwflisting}
1320 \caption{Packed record example: DWARF description}
1321 \label{fig:packedrecordexampledwarfdescription}
1322 \end{figure}
1323
1324 \begin{figure}[ht]
1325 \figurepart{2}{2}
1326 \begin{dwflisting}
1327 \begin{alltt}
1328           \DWTAGmember
1329               \DWATname("F6")
1330               \DWATtype(reference to 10$)
1331               \DWATdatabitoffset(1)
1332               \DWATbitsize(1)
1333 21\$:  \DWTAGstructuretype                  ! anonymous type for F2
1334           \DWTAGmember
1335               \DWATname("F3")
1336               \DWATtype(reference to 11\$)
1337 22\$:  \DWTAGarraytype                      ! anonymous type for F4
1338           \DWATtype(reference to 20\$)
1339           \DWTAGsubrangetype
1340               \DWATtype(reference to 11\$)
1341               \DWATlowerbound(0)
1342               \DWATupperbound(1)
1343           \DWATbitstride(2)
1344           \DWATbitsize(4) \addtoindexx{bit size attribute}
1345 23\$:  \DWTAGstructuretype                  ! anonymous type for V
1346           \DWATbitsize(39) \addtoindexx{bit size attribute}
1347           \DWTAGmember
1348               \DWATname("F1")
1349               \DWATtype(reference to 10\$)
1350               \DWATdatabitoffset(0)        ! may be omitted
1351               \DWATbitsize(1) ! may be omitted
1352           \DWTAGmember
1353               \DWATname("F2")
1354               \DWATtype(reference to 21\$)
1355               \DWATdatabitoffset(1)
1356               \DWATbitsize(32) ! may be omitted
1357           \DWTAGmember
1358               \DWATname("F4")
1359               \DWATtype(reference to 22\$)
1360               \DWATdatabitoffset(33)
1361               \DWATbitsize(4) ! may be omitted
1362           \DWTAGmember
1363               \DWATname("F7")
1364               \DWATtype(reference to 20\$)    ! type T
1365               \DWATdatabitoffset(37)
1366               \DWATbitsize(2) \addtoindexx{bit size attribute}              ! may be omitted
1367        \DWTAGvariable
1368           \DWATname("V")
1369           \DWATtype(reference to 23\$)
1370           \DWATlocation(...)
1371           ...
1372 \end{alltt}
1373 \end{dwflisting}
1374 \begin{center}
1375 \vspace{3mm}
1376 Figure~\ref{fig:packedrecordexampledwarfdescription}: Packed record example: DWARF description \textit{(concluded)}
1377 \end{center}
1378 \end{figure}
1379
1380 \clearpage
1381 \subsection{C/C++ Bit-Field Examples}
1382 \label{app:ccppbitfieldexamples}
1383 \textit{Bit fields\addtoindexx{bit fields} in \addtoindex{C}
1384 and \addtoindex{C++} typically require the use of the
1385 \DWATdatabitoffset{}\addtoindexx{data bit offset}
1386 and \DWATbitsize{}\addtoindexx{data bit size} attributes.}
1387
1388 \needlines{6}
1389 \textit{This Standard uses the following bit numbering and direction
1390 conventions in examples. These conventions are for illustrative
1391 purposes and other conventions may apply on particular
1392 architectures.}
1393 \begin{itemize}
1394 \item \textit{For big-endian architectures, bit offsets are
1395 counted from high-order to low-order bits within a byte (or
1396 larger storage unit); in this case, the bit offset identifies
1397 the high-order bit of the object.}
1398
1399 \item \textit{For little-endian architectures, bit offsets are
1400 counted from low-order to high-order bits within a byte (or
1401 larger storage unit); in this case, the bit offset identifies
1402 the low-order bit of the object.}
1403 \end{itemize}
1404
1405 \textit{In either case, the bit so identified is defined as the
1406 \addtoindexx{beginning of an object}
1407 beginning of the object.}
1408
1409 \needlines{5}
1410 This section illustrates one possible representation of the
1411 following \addtoindex{C} structure definition in both big-
1412 and little-endian \byteorder{s}:
1413 \par % Needed to end paragraph before listing so that it gets a line number
1414 \begin{nlnlisting}
1415 struct S {
1416     int j:5;
1417     int k:6;
1418     int m:5;
1419     int n:8;
1420 };
1421 \end{nlnlisting}
1422
1423 Figures \ref{fig:bigendiandatabitoffsets} and
1424 \refersec{fig:littleendiandatabitoffsets}
1425 show the structure layout
1426 and data bit offsets for example big- and little-endian
1427 architectures, respectively. Both diagrams show a structure
1428 that begins at address A and whose size is four bytes. Also,
1429 high order bits are to the left and low order bits are to
1430 the right.
1431
1432 \begin{figure}[ht]
1433 \begin{dwflisting}
1434 \begin{verbatim}
1435
1436     j:0
1437     k:5
1438     m:11
1439     n:16
1440
1441     Addresses increase ->
1442     |       A       |     A + 1     |    A + 2      |    A + 3      |
1443
1444     Data bit offsets increase ->
1445     +---------------+---------------+---------------+---------------+
1446     |0     4|5         10|11      15|16           23|24           31|
1447     |   j   |     k      | m        |        n      |       <pad>   |
1448     |       |            |          |               |               |
1449     +---------------------------------------------------------------+
1450
1451 \end{verbatim}
1452 \end{dwflisting}
1453 \caption{Big-endian data bit offsets}
1454 \label{fig:bigendiandatabitoffsets}
1455 \end{figure}
1456
1457 \begin{figure}[ht]
1458 \begin{dwflisting}
1459 \begin{verbatim}
1460
1461     j:0
1462     k:5
1463     m:11
1464     n:16
1465                                                <- Addresses increase
1466     |     A + 3     |     A + 2     |    A + 1      |       A       |
1467
1468                                         <-  Data bit offsets increase
1469     +---------------+---------------+---------------+---------------+
1470     |31           24|23           16|15     11|10       5|4        0|
1471     |     <pad>     |        n      |    m    |    k     |     j    |
1472     |               |               |         |          |          |
1473     +---------------------------------------------------------------+
1474
1475 \end{verbatim}
1476 \end{dwflisting}
1477 \caption{Little-endian data bit offsets}
1478 \label{fig:littleendiandatabitoffsets}
1479 \end{figure}
1480
1481 \needlines{4}
1482 Note that data member bit offsets in this example are the
1483 same for both big- and little-endian architectures even
1484 though the fields are allocated in different directions
1485 (high-order to low-order versus low-order to high-order);
1486 the bit naming conventions for memory and/or registers of
1487 the target architecture may or may not make this seem natural.
1488
1489 \clearpage
1490 \section{Namespace Examples}
1491 \label{app:namespaceexamples}
1492
1493 The \addtoindex{C++} example in
1494 Figure \refersec{fig:namespaceexample1sourcefragment}
1495 is used
1496 \addtoindexx{namespace (C++)!example}
1497 to illustrate the representation of namespaces.
1498 The DWARF representation in
1499 Figure \refersec{fig:namespaceexample1dwarfdescription}
1500 is appropriate.
1501
1502 \begin{figure}[ht]
1503 \begin{nlnlisting}
1504 namespace {
1505     int i;
1506 }
1507 namespace A {
1508     namespace B {
1509         int j;
1510         int   myfunc (int a);
1511         float myfunc (float f) { return f - 2.0; }
1512         int   myfunc2(int a)   { return a + 2; }
1513     }
1514 }
1515 namespace Y {
1516     using A::B::j;         // (1) using declaration
1517     int foo;
1518 }
1519 using A::B::j;             // (2) using declaration
1520 namespace Foo = A::B;      // (3) namespace alias
1521 using Foo::myfunc;         // (4) using declaration
1522 using namespace Foo;       // (5) using directive
1523 namespace A {
1524     namespace B {
1525         using namespace Y; // (6) using directive
1526         int k;
1527     }
1528 }
1529 int Foo::myfunc(int a)
1530 {
1531     i = 3;
1532     j = 4;
1533     return myfunc2(3) + j + i + a + 2;
1534 }
1535 \end{nlnlisting}
1536 \caption{Namespace example \#1: source fragment}
1537 \label{fig:namespaceexample1sourcefragment}
1538 \end{figure}
1539
1540
1541 \begin{figure}[p]
1542 \figurepart{1}{2}
1543 \begin{dwflisting}
1544 \begin{alltt}
1545
1546 1\$:   \DWTAGbasetype
1547           \DWATname("int")
1548           ...
1549 2\$:   \DWTAGbasetype
1550           \DWATname("float")
1551           ...
1552 6\$:   \DWTAGnamespace
1553           ! no \DWATname attribute
1554           \DWATexportsymbols              ! Implied by C++, but can be explicit
1555           \DWTAGvariable
1556               \DWATname("i")
1557               \DWATtype(reference to 1\$)
1558               \DWATlocation ...
1559               ...
1560 10\$:  \DWTAGnamespace
1561           \DWATname("A")
1562 20\$:      \DWTAGnamespace
1563               \DWATname("B")
1564 30\$:          \DWTAGvariable
1565                   \DWATname("j")
1566                   \DWATtype(reference to 1\$)
1567                   \DWATlocation ...
1568                   ...
1569 34\$:          \DWTAGsubprogram
1570                   \DWATname("myfunc")
1571                   \DWATtype(reference to 1\$)
1572                   ...
1573 36\$:          \DWTAGsubprogram
1574                   \DWATname("myfunc")
1575                   \DWATtype(reference to 2\$)
1576                   ...
1577 38\$:          \DWTAGsubprogram
1578                   \DWATname("myfunc2")
1579                   \DWATlowpc ...
1580                   \DWAThighpc ...
1581                   \DWATtype(reference to 1\$)
1582                   ...
1583 \end{alltt}
1584 \end{dwflisting}
1585 \caption{Namespace example \#1: DWARF description}
1586 \label{fig:namespaceexample1dwarfdescription}
1587 \end{figure}
1588
1589 \begin{figure}
1590 \figurepart{2}{2}
1591 \begin{dwflisting}
1592 \begin{alltt}
1593 40\$:  \DWTAGnamespace
1594           \DWATname("Y")
1595           \DWTAGimporteddeclaration            ! (1) using-declaration
1596               \DWATimport(reference to 30\$)
1597           \DWTAGvariable
1598               \DWATname("foo")
1599               \DWATtype(reference to 1\$)
1600               \DWATlocation ...
1601               ...
1602       \DWTAGimporteddeclaration                ! (2) using declaration
1603           \DWATimport(reference to 30\$)
1604       \DWTAGimporteddeclaration                ! (3) namespace alias
1605           \DWATname("Foo")
1606           \DWATimport(reference to 20\$)
1607       \DWTAGimporteddeclaration                ! (4) using declaration
1608           \DWATimport(reference to 34\$)         !     - part 1
1609       \DWTAGimporteddeclaration                ! (4) using declaration
1610           \DWATimport(reference to 36\$)         !     - part 2
1611       \DWTAGimportedmodule                     ! (5) using directive
1612           \DWATimport(reference to 20\$)
1613       \DWTAGnamespace
1614           \DWATextension(reference to 10\$)
1615           \DWTAGnamespace
1616               \DWATextension(reference to 20\$)
1617               \DWTAGimportedmodule             ! (6) using directive
1618                   \DWATimport(reference to 40\$)
1619               \DWTAGvariable
1620                   \DWATname("k")
1621                   \DWATtype(reference to 1\$)
1622                   \DWATlocation ...
1623                   ...
1624 60\$:  \DWTAGsubprogram
1625           \DWATspecification(reference to 34\$)
1626           \DWATlowpc ...
1627           \DWAThighpc ...
1628           ...
1629 \end{alltt}
1630 \end{dwflisting}
1631 \begin{center}
1632 \vspace{3mm}
1633 Figure~\ref{fig:namespaceexample1dwarfdescription}: Namespace example \#1: DWARF description \textit{(concluded)}
1634 \end{center}
1635 \end{figure}
1636
1637 \clearpage
1638 As a further namespace example, consider the inlined namespace shown in
1639 Figure \refersec{fig:namespaceexample2sourcefragment}. For this source,
1640 the DWARF description in Figure \ref{fig:namespaceexample2dwarfdescription}
1641 is appropriate. In this example, \texttt{a} may be referenced either as a member of
1642 the fully qualified namespace \texttt{A::B}, or as if it were defined
1643 in the enclosing namespace, \texttt{A}.
1644
1645 \begin{figure}[ht]
1646 \begin{nlnlisting}
1647 namespace A {
1648     inline namespace B {   // (1) inline namespace
1649         int a;
1650     }
1651 }
1652
1653 void foo (void)
1654 {
1655     using A::B::a;
1656     a = 1;
1657 }
1658
1659 void bar (void)
1660 {
1661     using A::a;
1662     a = 2;
1663 }
1664 \end{nlnlisting}
1665 \caption{Namespace example \#2: source fragment}
1666 \label{fig:namespaceexample2sourcefragment}
1667 \end{figure}
1668
1669 \begin{figure}[ht]
1670 \begin{dwflisting}
1671 \begin{alltt}
1672 1$:   \DWTAGnamespace
1673           \DWATname("A")
1674 2$:       \DWTAGnamespace
1675               \DWATname("B")
1676               \DWATexportsymbols
1677 3$:           \DWTAGvariable
1678                   \DWATname("a")
1679 \end{alltt}
1680 \end{dwflisting}
1681 \caption{Namespace example \#2: DWARF description}
1682 \label{fig:namespaceexample2dwarfdescription}
1683 \end{figure}
1684
1685 \clearpage
1686 \section{Member Function Examples}
1687 \label{app:memberfunctionexample}
1688 \addtoindexx{member function example}
1689 Consider the member function example fragment in
1690 Figure \refersec{fig:memberfunctionexamplesourcefragment}.
1691 The DWARF representation in
1692 Figure \refersec{fig:memberfunctionexampledwarfdescription}
1693 is appropriate.
1694
1695 \begin{figure}[ht]
1696 \begin{nlnlisting}
1697 class A
1698 {
1699     void func1(int x1);
1700     void func2() const;
1701     static void func3(int x3);
1702 };
1703 void A::func1(int x) {}
1704 \end{nlnlisting}
1705 \caption{Member function example: source fragment}
1706 \label{fig:memberfunctionexamplesourcefragment}
1707 \end{figure}
1708
1709 \begin{figure}[ht]
1710 \figurepart{1}{2}
1711 \begin{dwflisting}
1712 \begin{alltt}
1713
1714 2\$: \DWTAGbasetype
1715         \DWATname("int")
1716         ...
1717 3\$: \DWTAGclasstype
1718         \DWATname("A")
1719         ...
1720 4\$:     \DWTAGpointertype
1721             \DWATtype(reference to 3\$)
1722             ...
1723 5\$:     \DWTAGconsttype
1724             \DWATtype(reference to 3\$)
1725             ...
1726 6\$:     \DWTAGpointertype
1727             \DWATtype(reference to 5\$)
1728             ...
1729
1730 7\$:     \DWTAGsubprogram
1731             \DWATdeclaration
1732             \DWATname("func1")
1733             \DWATobjectpointer(reference to 8\$) \addtoindexx{object pointer attribute}
1734                 ! References a formal parameter in this
1735                 ! member function
1736             ...
1737
1738 \end{alltt}
1739 \end{dwflisting}
1740 \caption{Member function example: DWARF description}
1741 \label{fig:memberfunctionexampledwarfdescription}
1742 \end{figure}
1743
1744 \begin{figure}[p]
1745 \figurepart{2}{2}
1746 \begin{dwflisting}
1747 \begin{alltt}
1748
1749 8\$:         \DWTAGformalparameter
1750                 \DWATartificial(true)
1751                 \DWATname("this")
1752                 \DWATtype(reference to 4\$)
1753                     ! Makes type of 'this' as 'A*' =>
1754                     ! func1 has not been marked const
1755                     ! or volatile
1756                 \DWATlocation ...
1757                 ...
1758 9\$:         \DWTAGformalparameter
1759                 \DWATname(x1)
1760                 \DWATtype(reference to 2\$)
1761                 ...
1762 10\$:    \DWTAGsubprogram
1763             \DWATdeclaration
1764             \DWATname("func2")
1765             \DWATobjectpointer(reference to 11\$) \addtoindexx{object pointer attribute}
1766             ! References a formal parameter in this
1767             ! member function
1768             ...
1769 11\$:        \DWTAGformalparameter
1770                 \DWATartificial(true)
1771                 \DWATname("this")
1772                 \DWATtype(reference to 6\$)
1773                 ! Makes type of 'this' as 'A const*' =>
1774                 !     func2 marked as const
1775                 \DWATlocation ...
1776                 ...
1777 12\$:    \DWTAGsubprogram
1778             \DWATdeclaration
1779             \DWATname("func3")
1780             ...
1781                 ! No object pointer reference formal parameter
1782                 ! implies func3 is static
1783 13\$:        \DWTAGformalparameter
1784                 \DWATname(x3)
1785                 \DWATtype(reference to 2\$)
1786                 ...
1787
1788 \end{alltt}
1789 \end{dwflisting}
1790 \begin{center}
1791 \vspace{3mm}
1792 Figure~\ref{fig:memberfunctionexampledwarfdescription}: Member function example: DWARF description \textit{(concluded)}
1793 \end{center}
1794 \end{figure}
1795
1796 \clearpage
1797 As a further example illustrating \&- and \&\&-qualification
1798 of member functions,
1799 consider the member function example fragment in
1800 Figure \refersec{fig:memberfunctionrefqualexamplesourcefragment}.
1801 The DWARF representation in
1802 Figure \refersec{fig:memberfunctionrefqualexampledwarfdescription}
1803 is appropriate.
1804
1805 \begin{figure}[ht]
1806 \begin{nlnlisting}
1807 class A {
1808 public:
1809     void f() const &&;
1810 };
1811
1812 void g() {
1813     A a;
1814     // The type of pointer is "void (A::*)() const &&".
1815     auto pointer_to_member_function = &A::f;
1816 }
1817 \end{nlnlisting}
1818 \caption{Reference- and rvalue-reference-qualification example: source \mbox{fragment}}
1819 \label{fig:memberfunctionrefqualexamplesourcefragment}
1820 \end{figure}
1821
1822 \begin{figure}[ht]
1823 %\figurepart{1}{2}
1824 \begin{dwflisting}
1825 \begin{alltt}
1826
1827 100$:   \DWTAGclasstype
1828             \DWATname("A")
1829             \DWTAGsubprogram
1830                 \DWATname("f")
1831                 \DWATrvaluereference(0x01)
1832                 \DWTAGformalparameter
1833                     \DWATtype({ref to 200$})     ! to const A*
1834                     \DWATartificial(0x01)
1835
1836 200$:   ! const A*
1837         \DWTAGpointertype
1838             \DWATtype({ref to 300$})             ! to const A
1839
1840 300$:   ! const A
1841         \DWTAGconsttype
1842             \DWATtype({ref to 100$})             ! to class A
1843
1844 400$:   ! mfptr
1845         \DWTAGptrtomembertype
1846             \DWATtype({ref to 500$})             ! to functype
1847             \DWATcontainingtype({ref to 100$})  ! to class A
1848
1849 500$:   ! functype
1850         \DWTAGsubroutinetype
1851             \DWATrvaluereference(0x01)
1852             \DWTAGformalparameter
1853                 \DWATtype({ref to 200$})         ! to const A*
1854                 \DWATartificial(0x01)
1855
1856 600$:   \DWTAGsubprogram
1857             \DWATname("g")
1858             \DWTAGvariable
1859                 \DWATname("a")
1860                 \DWATtype({ref to 100$})         ! to class A
1861             \DWTAGvariable
1862                 \DWATname("pointer_to_member_function")
1863                 \DWATtype({ref to 400$})
1864
1865 \end{alltt}
1866 \end{dwflisting}
1867 % The extra ~ at the end of the following caption is present to get the entry in the
1868 % List of Figures to wrap the page number properly (to align the numbers)...
1869 \caption{Reference- and rvalue-reference-qualification example: DWARF \mbox{description} ~}
1870 \label{fig:memberfunctionrefqualexampledwarfdescription}
1871 \end{figure}
1872
1873
1874 \clearpage
1875 \section{Line Number Examples}
1876 \label{app:linenumberexamples}
1877
1878 \subsection{Line Number Header Example}
1879 \label{app:linenumberheaderexample}
1880
1881 The information found in a \DWARFVersionIV{} line number
1882 header can be encoded in a \DWARFVersionV{} header
1883 as shown in Figure \refersec{fig:preV5LNCTusingV5}.
1884
1885 \begin{figure}[ht]
1886 \begin{dwflisting}
1887 \begin{alltt}
1888   Field           Field Name                      Value(s)
1889   Number
1890      1    \textit{Same as in Version 4}            ...
1891      2    version                         5
1892      3    \textit{Not present in Version 4}        -
1893      4    \textit{Not present in Version 4}        -
1894    5-12   \textit{Same as in Version 4}            ...
1895     13    \HFNdirectoryentryformatcount{}    1
1896     14    \HFNdirectoryentryformat{}          \DWLNCTpath, \DWFORMstring
1897     15    \HFNdirectoriescount{}               <n>
1898     16    \HFNdirectories{}                     <n>*<null terminated string>
1899     17    \HFNfilenameentryformatcount{}    4
1900     18    \HFNfilenameentryformat{}          \DWLNCTpath, \DWFORMstring,
1901                                           \DWLNCTdirectoryindex, \DWFORMudata,
1902                                           \DWLNCTtimestamp, \DWFORMudata,
1903                                           \DWLNCTsize, \DWFORMudata
1904     19    \HFNfilenamescount{}                <m>
1905     20    \HFNfilenames{}                      <m>*\{<null terminated string>, <index>,
1906                                                <timestamp>, <size>\}
1907 \end{alltt}
1908 \end{dwflisting}
1909 \begin{centering}
1910 \caption{Pre-\DWARFVersionV{} line number program header information \mbox{encoded} using \DWARFVersionV}
1911 \label{fig:preV5LNCTusingV5}
1912 \end{centering}
1913 \end{figure}
1914
1915 \subsection{Line Number Special Opcode Example}
1916 \label{app:linenumberspecialopcodeexample}
1917 Suppose the line number header includes the following
1918 (header fields not needed are not shown):
1919 \begin{center}
1920 \begin{nolinenumbersenv}
1921 \begin{tabular}{lr}
1922     \addttindex{opcode\_base} & 13 \\
1923     \addttindex{line\_base}   & -3 \\
1924     \addttindex{line\_range}  & 12 \\
1925     \addttindex{minimum\_instruction\_length} &          1 \\
1926     \addttindex{maximum\_operations\_per\_instruction} & 1 \\
1927 \end{tabular}
1928 \end{nolinenumbersenv}
1929 \end{center}
1930 This means that
1931 we can use a special opcode whenever two successive rows in
1932 the matrix have source line numbers differing by any value
1933 within the range \mbox{[-3, 8]} and (because of the limited number
1934 of opcodes available) when the difference between addresses
1935 is within the range [0, 20].
1936 The resulting opcode mapping is shown in
1937 Figure \refersec{fig:examplelinenumberspecialopcodemapping}.
1938
1939 Note in the bottom row of the figure that not all line advances are
1940 available for the maximum \addtoindex{operation advance}.
1941
1942 \begin{figure}[ht]
1943 \begin{alltt}
1944                         Line Advance
1945    Operation
1946      Advance    -3  -2  -1   0   1   2   3   4   5   6   7   8
1947    ---------   -----------------------------------------------
1948            0    13  14  15  16  17  18  19  20  21  22  23  24
1949            1    25  26  27  28  29  30  31  32  33  34  35  36
1950            2    37  38  39  40  41  42  43  44  45  46  47  48
1951            3    49  50  51  52  53  54  55  56  57  58  59  60
1952            4    61  62  63  64  65  66  67  68  69  70  71  72
1953            5    73  74  75  76  77  78  79  80  81  82  83  84
1954            6    85  86  87  88  89  90  91  92  93  94  95  96
1955            7    97  98  99 100 101 102 103 104 105 106 107 108
1956            8   109 110 111 112 113 114 115 116 117 118 119 120
1957            9   121 122 123 124 125 126 127 128 129 130 131 132
1958           10   133 134 135 136 137 138 139 140 141 142 143 144
1959           11   145 146 147 148 149 150 151 152 153 154 155 156
1960           12   157 158 159 160 161 162 163 164 165 166 167 168
1961           13   169 170 171 172 173 174 175 176 177 178 179 180
1962           14   181 182 183 184 185 186 187 188 189 190 191 192
1963           15   193 194 195 196 197 198 199 200 201 202 203 204
1964           16   205 206 207 208 209 210 211 212 213 214 215 216
1965           17   217 218 219 220 221 222 223 224 225 226 227 228
1966           18   229 230 231 232 233 234 235 236 237 238 239 240
1967           19   241 242 243 244 245 246 247 248 249 250 251 252
1968           20   253 254 255
1969
1970 \end{alltt}
1971 \caption{Example line number special opcode mapping}
1972 \label{fig:examplelinenumberspecialopcodemapping}
1973 \end{figure}
1974
1975 There is no requirement that the expression
1976 255 - \addttindex{line\_base} + 1 be an integral multiple of
1977 \addttindex{line\_range}.
1978
1979
1980 \clearpage
1981 \subsection{Line Number Program Example}
1982 \label{app:linenumberprogramexample}
1983
1984 Consider the simple source file and the resulting machine
1985 code for the Intel 8086 processor in
1986 Figure \refersec{fig:linenumberprogramexamplemachinecode}.
1987
1988 \begin{figure}[ht]
1989 \begin{nlnlisting}
1990 1: int
1991 2: main()
1992     0x239: push pb
1993     0x23a: mov bp,sp
1994 3: {
1995 4: printf("Omit needless words\n");
1996     0x23c: mov ax,0xaa
1997     0x23f: push ax
1998     0x240: call _printf
1999     0x243: pop cx
2000 5: exit(0);
2001     0x244: xor ax,ax
2002     0x246: push ax
2003     0x247: call _exit
2004     0x24a: pop cx
2005 6: }
2006     0x24b: pop bp
2007     0x24c: ret
2008 7: 0x24d:
2009 \end{nlnlisting}
2010 \caption{Line number program example: machine code}
2011 \label{fig:linenumberprogramexamplemachinecode}
2012 \end{figure}
2013
2014 Suppose the line number program header includes the
2015 same values and resulting encoding illustrated in the
2016 previous Section \refersec{app:linenumberspecialopcodeexample}.
2017
2018 Table \refersec{tab:linenumberprogramexampleoneencoding}
2019 shows one encoding of the line number program, which occupies
2020 12 bytes.
2021
2022 \newpage
2023 \begin{centering}
2024 \setlength{\extrarowheight}{0.1cm}
2025 \begin{longtable}{l|l|l}
2026   \caption{Line number program example: one \mbox{encoding}}
2027   \label{tab:linenumberprogramexampleoneencoding} \\
2028   \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
2029 \endfirsthead
2030   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
2031 \endhead
2032   \hline \emph{Continued on next page}
2033 \endfoot
2034   \hline
2035 \endlastfoot
2036 \DWLNSadvancepc&LEB128(0x239)&0x2, 0xb9, 0x04 \\
2037 SPECIAL\dag~(2, 0)& & 0x12~~(18$_{10}$)  \\
2038 SPECIAL\dag~(2, 3)& & 0x36~~(54$_{10}$) \\
2039 SPECIAL\dag~(1, 8)& & 0x71~~(113$_{10}$) \\
2040 SPECIAL\dag~(1, 7)& & 0x65~~(101$_{10}$) \\
2041 \DWLNSadvancepc&LEB128(2)&0x2, 0x2 \\
2042 \DWLNEendsequence{} &&0x0, 0x1, 0x1 \\
2043 \end{longtable}
2044 \end{centering}
2045 \dag~The opcode notation SPECIAL(\textit{m},\textit{n}) indicates
2046 the special opcode generated for a line advance of \textit{m}
2047 and an operation advance of \textit{n})
2048
2049 Table \refersec{tab:linenumberprogramexamplealternateencoding}
2050 shows an alternate
2051 encoding of the same program using
2052 standard opcodes to advance
2053 the program counter;
2054 this encoding occupies 22 bytes.
2055
2056 \begin{centering}
2057 \setlength{\extrarowheight}{0.1cm}
2058 \begin{longtable}{l|l|l}
2059   \caption{Line number program example: alternate encoding}
2060   \label{tab:linenumberprogramexamplealternateencoding} \\
2061   \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
2062 \endfirsthead
2063   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
2064 \endhead
2065   \hline \emph{Continued on next page}
2066 \endfoot
2067   \hline
2068 \endlastfoot
2069 \DWLNSfixedadvancepc&0x239&0x9, 0x39, 0x2        \\
2070 SPECIAL\ddag~(2, 0) && 0x12~~(18$_{10}$)        \\
2071 \DWLNSfixedadvancepc&0x3&0x9, 0x3, 0x0        \\
2072 SPECIAL\ddag~(2, 0) && 0x12~~(18$_{10}$)        \\
2073 \DWLNSfixedadvancepc&0x8&0x9, 0x8, 0x0        \\
2074 SPECIAL\ddag~(1, 0) && 0x11~~(17$_{10}$)        \\
2075 \DWLNSfixedadvancepc&0x7&0x9, 0x7, 0x0        \\
2076 SPECIAL\ddag~(1, 0) && 0x11~~(17$_{10}$)        \\
2077 \DWLNSfixedadvancepc&0x2&0x9, 0x2, 0x0        \\
2078 \DWLNEendsequence&&0x0, 0x1, 0x1        \\
2079 \end{longtable}
2080 \end{centering}
2081 \ddag~SPECIAL is defined the same as in the preceding Table
2082 \ref{tab:linenumberprogramexampleoneencoding}.
2083 \needlines{6}
2084 \section{Call Frame Information Example}
2085 \label{app:callframeinformationexample}
2086
2087 The following example uses a hypothetical RISC machine in
2088 the style of the Motorola 88000.
2089 \begin{itemize}
2090 \item Memory is byte addressed.
2091
2092 \item Instructions are all 4 bytes each and word aligned.
2093
2094 \item Instruction operands are typically of the form:
2095 \begin{alltt}
2096     <destination.reg>, <source.reg>, <constant>
2097 \end{alltt}
2098
2099 \item The address for the load and store instructions is computed
2100 by adding the contents of the
2101 source register with the constant.
2102
2103 \item There are eight 4-byte registers:
2104 \par
2105 \begin{nolinenumbersenv}
2106 \begin{tabular}{p{5mm}l}
2107    & R0 always 0 \\
2108    & R1 holds return address on call \\
2109    & R2-R3 temp registers (not preserved on call) \\
2110    & R4-R6 preserved on call \\
2111    & R7 stack pointer \\
2112 \end{tabular}
2113 \end{nolinenumbersenv}
2114
2115 \item  The stack grows in the negative direction.
2116
2117 \item The architectural ABI committee specifies that the
2118 stack pointer (R7) is the same as the CFA
2119
2120 \end{itemize}
2121
2122 Figure \referfol{fig:callframeinformationexamplemachinecodefragments}
2123 shows two code fragments from a subroutine called
2124 foo that uses a frame pointer (in addition to the stack
2125 pointer). The first column values are byte addresses.
2126 % The \space is so we get a space after >
2127 \textless fs\textgreater\ denotes the stack frame size in bytes, namely 12.
2128
2129
2130 \begin{figure}[ht]
2131 \begin{nlnlisting}
2132        ;; start prologue
2133 foo    sub   R7, R7, <fs>        ; Allocate frame
2134 foo+4  store R1, R7, (<fs>-4)    ; Save the return address
2135 foo+8  store R6, R7, (<fs>-8)    ; Save R6
2136 foo+12 add   R6, R7, 0           ; R6 is now the Frame ptr
2137 foo+16 store R4, R6, (<fs>-12)   ; Save a preserved reg
2138        ;; This subroutine does not change R5
2139        ...
2140        ;; Start epilogue (R7 is returned to entry value)
2141 foo+64 load  R4, R6, (<fs>-12)   ; Restore R4
2142 foo+68 load  R6, R7, (<fs>-8)    ; Restore R6
2143 foo+72 load  R1, R7, (<fs>-4)    ; Restore return address
2144 foo+76 add   R7, R7, <fs>        ; Deallocate frame
2145 foo+80 jump  R1                  ; Return
2146 foo+84
2147 \end{nlnlisting}
2148 \caption{Call frame information example: machine code fragments}
2149 \label{fig:callframeinformationexamplemachinecodefragments}
2150 \end{figure}
2151
2152
2153 An abstract table
2154 (see Section \refersec{chap:structureofcallframeinformation})
2155 for the foo subroutine is shown in
2156 Table \referfol{tab:callframeinformationexampleconceptualmatrix}.
2157 Corresponding fragments from the
2158 \dotdebugframe{} section are shown in
2159 Table \refersec{tab:callframeinformationexamplecommoninformationentryencoding}.
2160
2161 The following notations apply in
2162 Table \refersec{tab:callframeinformationexampleconceptualmatrix}:
2163 \par
2164 \begin{nolinenumbersenv}
2165 \begin{tabular}{p{5mm}l}
2166 &1.  R8 is the return address \\
2167 &2.  s = same\_value rule \\
2168 &3.  u = undefined rule \\
2169 &4.  rN = register(N) rule \\
2170 &5.  cN = offset(N) rule \\
2171 &6.  a = architectural rule \\
2172 \end{tabular}
2173 \end{nolinenumbersenv}
2174
2175 \begin{centering}
2176 \setlength{\extrarowheight}{0.1cm}
2177 \begin{longtable}{l|llllllllll}
2178   \caption{Call frame information example: conceptual matrix}
2179   \label{tab:callframeinformationexampleconceptualmatrix} \\
2180   \hline \bfseries Location & \bfseries CFA & \bfseries R0 & \bfseries R1 & \bfseries R2 & \bfseries R3 & \bfseries R4 & \bfseries R5 & \bfseries R6 & \bfseries R7 & \bfseries R8 \\ \hline
2181 \endfirsthead
2182   \bfseries Location &\bfseries CFA &\bfseries R0 & \bfseries R1 & \bfseries R2 &\bfseries R3 &\bfseries R4 &\bfseries R5 &\bfseries R6 &\bfseries R7 &\bfseries R8\\ \hline
2183 \endhead
2184   \hline \emph{Continued on next page}
2185 \endfoot
2186   \hline
2187 \endlastfoot
2188 foo&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
2189 foo+4&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
2190 foo+8&[R7]+fs&s&u&u&u&s&s&s&a&c-4 \\
2191 foo+12&[R7]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
2192 foo+16&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
2193 foo+20&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
2194 ...&&&&&&&&&& \\
2195 foo+64&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
2196 foo+68&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4  \\
2197 foo+72&[R7]+fs&s&u&u&u&s&s&s&a&c-4  \\
2198 foo+76&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
2199 foo+80&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
2200 \end{longtable}
2201 \end{centering}
2202
2203 \clearpage      % ?????
2204
2205 \begin{centering}
2206 \setlength{\extrarowheight}{0.1cm}
2207 \begin{longtable}{l|ll}
2208   \caption{Call frame information example: common information entry encoding}
2209   \label{tab:callframeinformationexamplecommoninformationentryencoding}
2210   \\
2211   \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
2212 \endfirsthead
2213   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
2214 \endhead
2215   \hline \emph{Continued on next page}
2216 \endfoot
2217   \hline
2218 \endlastfoot
2219 cie&36&length    \\
2220 cie+4&\xffffffff&CIE\_id    \\
2221 cie+8&4&version    \\
2222 cie+9&0&augmentation     \\
2223 cie+10&4&address size    \\
2224 cie+11&0&segment size    \\
2225 cie+12&4&code\_alignment\_factor, \textless caf \textgreater    \\
2226 cie+13&-4&data\_alignment\_factor, \textless daf \textgreater    \\
2227 cie+14&8&R8 is the return addr.    \\
2228 cie+15&\DWCFAdefcfa{} (7, 0)&CFA = [R7]+0    \\
2229 cie+18&\DWCFAsamevalue{} (0)&R0 not modified (=0)    \\
2230 cie+20&\DWCFAundefined{} (1)&R1 scratch    \\
2231 cie+22&\DWCFAundefined{} (2)&R2 scratch    \\
2232 cie+24&\DWCFAundefined{} (3)&R3 scratch    \\
2233 cie+26&\DWCFAsamevalue{} (4)&R4 preserve    \\
2234 cie+28&\DWCFAsamevalue{} (5)&R5 preserve    \\
2235 cie+30&\DWCFAsamevalue{} (6)&R6 preserve    \\
2236 cie+32&\DWCFAsamevalue{} (7)&R7 preserve    \\
2237 cie+34&\DWCFAregister{} (8, 1)&R8 is in R1    \\
2238 cie+37&\DWCFAnop{} &padding    \\
2239 cie+38&\DWCFAnop{} &padding \\
2240 cie+39& \DWCFAnop&padding  \\
2241 cie+40 &&  \\
2242 \end{longtable}
2243 \end{centering}
2244
2245 \bbeb
2246
2247 \needlines{10}
2248 \begin{centering}
2249 \setlength{\extrarowheight}{0.1cm}
2250 \begin{longtable}{l|ll}
2251   \caption{Call frame information example: frame description entry encoding}
2252   \label{tab:callframeinformationexampleframedescriptionentryencoding} \\
2253   \hline \bfseries Address &\bfseries Value &\bfseries Comment\dag \\ \hline
2254 \endfirsthead
2255   \bfseries Address &\bfseries Value &\bfseries Comment\dag \\ \hline
2256 \endhead
2257   \hline \emph{Continued on next page}
2258 \endfoot
2259   \hline
2260 \endlastfoot
2261 fde&40&length \\
2262 fde+4&cie&CIE\_ptr \\
2263 fde+8&foo&initial\_location \\
2264 fde+12&84&address\_range \\
2265 fde+16&\DWCFAadvanceloc(1)&instructions \\
2266 fde+17&\DWCFAdefcfaoffset(12)& \textless fs\textgreater \\
2267 fde+19&\DWCFAadvanceloc(1)&4/\textless caf\textgreater \\
2268 fde+20&\DWCFAoffset(8,1)&-4/\textless daf\textgreater (2nd parameter) \\
2269 fde+22&\DWCFAadvanceloc(1)& \\
2270 fde+23&\DWCFAoffset(6,2)&-8/\textless daf\textgreater (2nd parameter)  \\
2271 fde+25&\DWCFAadvanceloc(1) & \\
2272 fde+26&\DWCFAdefcfaregister(6) & \\
2273 fde+28&\DWCFAadvanceloc(1) & \\
2274 fde+29&\DWCFAoffset(4,3)&-12/\textless daf\textgreater (2nd parameter) \\
2275 fde+31&\DWCFAadvanceloc(12)&44/\textless caf\textgreater \\
2276 fde+32&\DWCFArestore(4)& \\
2277 fde+33&\DWCFAadvanceloc(1) & \\
2278 fde+34&\DWCFArestore(6) & \\
2279 fde+35&\DWCFAdefcfaregister(7)  & \\
2280 fde+37&\DWCFAadvanceloc(1) & \\
2281 fde+38&\DWCFArestore(8) &\\
2282 fde+39&\DWCFAadvanceloc(1) &\\
2283 fde+40&\DWCFAdefcfaoffset(0)  &\\
2284 fde+42&\DWCFAnop&padding \\
2285 fde+43&\DWCFAnop&padding \\
2286 fde+44 && \\
2287 \end{longtable}
2288 \bb
2289 \dag The following notations apply:
2290 \texttt{<fs> =} frame size,
2291 \texttt{<caf> =} code alignment factor, and
2292 \texttt{<daf> =} data alignment factor.
2293 \eb
2294 \end{centering}
2295
2296 \needlines{6}
2297 \section{Inlining Examples}
2298 \label{app:inliningexamples}
2299 The pseudo\dash source in
2300 Figure \referfol{fig:inliningexamplespseudosourcefragment}
2301 is used to illustrate the
2302 \addtoindexx{inlined subprogram call!examples}
2303 use of DWARF to describe inlined subroutine calls. This
2304 example involves a nested subprogram \texttt{INNER} that makes uplevel
2305 references to the formal parameter and local variable of the
2306 containing subprogram \texttt{OUTER}.
2307
2308 \begin{figure}[ht]
2309 \begin{nlnlisting}
2310 inline procedure OUTER (OUTER_FORMAL : integer) =
2311     begin
2312     OUTER_LOCAL : integer;
2313     procedure INNER (INNER_FORMAL : integer) =
2314         begin
2315         INNER_LOCAL : integer;
2316         print(INNER_FORMAL + OUTER_LOCAL);
2317         end;
2318     INNER(OUTER_LOCAL);
2319     ...
2320     INNER(31);
2321     end;
2322 ! Call OUTER
2323 !
2324 OUTER(7);
2325 \end{nlnlisting}
2326 \caption{Inlining examples: pseudo-source fragmment}
2327 \label{fig:inliningexamplespseudosourcefragment}
2328 \end{figure}
2329
2330
2331 There are several approaches that a compiler might take to
2332 inlining for this sort of example. This presentation considers
2333 three such approaches, all of which involve inline expansion
2334 of subprogram \texttt{OUTER}. (If \texttt{OUTER} is not inlined, the inlining
2335 reduces to a simpler single level subset of the two level
2336 approaches considered here.)
2337
2338 The approaches are:
2339 \begin{enumerate}[1. ]
2340 \item  Inline both \texttt{OUTER} and \texttt{INNER} in all cases
2341
2342 \item Inline \texttt{OUTER}, multiple \texttt{INNER}s \\
2343 Treat \texttt{INNER} as a non-inlinable part of \texttt{OUTER}, compile and
2344 call a distinct normal version of \texttt{INNER} defined within each
2345 inlining of \texttt{OUTER}.
2346
2347 \item Inline \texttt{OUTER}, one \texttt{INNER} \\
2348 Compile \texttt{INNER} as a single normal subprogram which is called
2349 from every inlining of \texttt{OUTER}.
2350 \end{enumerate}
2351
2352 This discussion does not consider why a compiler might choose
2353 one of these approaches; it considers only how to describe
2354 the result.
2355
2356 In the examples that follow in this section, the debugging
2357 information entries are given mnemonic labels of the following
2358 form
2359 \begin{verbatim}
2360     <io>.<ac>.<n>.<s>
2361 \end{verbatim}
2362 where
2363 \begin{description}
2364 \item[\textless io\textgreater]
2365 is either \texttt{INNER} or \texttt{OUTER} to indicate to which
2366 subprogram the debugging information entry applies,
2367 \item[\textless ac\textgreater]
2368 is either AI or CI to indicate \doublequote{abstract instance} or
2369 \doublequote{concrete instance} respectively,
2370 \item[\textless n\textgreater]
2371 is the number of the
2372 alternative being considered, and
2373 \item[\textless s\textgreater]
2374 is a sequence number that
2375 distinguishes the individual entries.
2376 \end{description}
2377 There is no implication
2378 that symbolic labels, nor any particular naming convention,
2379 are required in actual use.
2380
2381 For conciseness, declaration coordinates and call coordinates are omitted.
2382
2383 \subsection{Alternative \#1: inline both OUTER and INNER}
2384 \label{app:inlinebothouterandinner}
2385
2386 A suitable abstract instance for an alternative where both
2387 \texttt{OUTER} and \texttt{INNER} are always inlined is shown in
2388 Figure \refersec{fig:inliningexample1abstractinstance}.
2389
2390 Notice in
2391 Figure \ref{fig:inliningexample1abstractinstance}
2392 that the debugging information entry for
2393 \texttt{INNER} (labelled \texttt{INNER.AI.1.1\$}) is nested in (is a child of)
2394 that for \texttt{OUTER} (labelled \texttt{OUTER.AI.1.1\$}). Nonetheless, the
2395 abstract instance tree for \texttt{INNER} is considered to be separate
2396 and distinct from that for \texttt{OUTER}.
2397
2398 The call of \texttt{OUTER} shown in
2399 Figure \refersec{fig:inliningexamplespseudosourcefragment}
2400 might be described as
2401 shown in
2402 Figure \refersec{fig:inliningexample1concreteinstance}.
2403
2404
2405 \begin{figure}[p]
2406 \begin{dwflisting}
2407 \begin{alltt}
2408     ! Abstract instance for OUTER
2409     ! \addtoindexx{abstract instance!example}
2410 OUTER.AI.1.1\$:
2411     \DWTAGsubprogram
2412         \DWATname("OUTER")
2413         \DWATinline(\DWINLdeclaredinlined)
2414         ! No low/high PCs
2415 OUTER.AI.1.2\$:
2416         \DWTAGformalparameter
2417             \DWATname("OUTER\_FORMAL")
2418             \DWATtype(reference to integer)
2419             ! No location
2420 OUTER.AI.1.3\$:
2421         \DWTAGvariable
2422             \DWATname("OUTER\_LOCAL")
2423             \DWATtype(reference to integer)
2424             ! No location
2425         !
2426         ! Abstract instance for INNER
2427         !
2428 INNER.AI.1.1\$:
2429         \DWTAGsubprogram
2430             \DWATname("INNER")
2431             \DWATinline(\DWINLdeclaredinlined)
2432             ! No low/high PCs
2433 INNER.AI.1.2\$:
2434             \DWTAGformalparameter
2435                 \DWATname("INNER\_FORMAL")
2436                 \DWATtype(reference to integer)
2437                 ! No location
2438 INNER.AI.1.3\$:
2439             \DWTAGvariable
2440                 \DWATname("INNER\_LOCAL")
2441                 \DWATtype(reference to integer)
2442                 ! No location
2443             ...
2444             0
2445         ! No \DWTAGinlinedsubroutine (concrete instance)
2446         ! for INNER corresponding to calls of INNER
2447         ...
2448         0
2449 \end{alltt}
2450 \end{dwflisting}
2451 \caption{Inlining example \#1: abstract instance}
2452 \label{fig:inliningexample1abstractinstance}
2453 \end{figure}
2454
2455 \begin{figure}[p]
2456 \begin{dwflisting}
2457 \begin{alltt}
2458 ! Concrete instance for call "OUTER(7)"
2459 ! \addtoindexx{concrete instance!example}
2460 OUTER.CI.1.1\$:
2461     \DWTAGinlinedsubroutine
2462         ! No name
2463         \DWATabstractorigin(reference to OUTER.AI.1.1\$)
2464         \DWATlowpc(...)
2465         \DWAThighpc(...)
2466 OUTER.CI.1.2\$:
2467         \DWTAGformalparameter
2468             ! No name
2469             \DWATabstractorigin(reference to OUTER.AI.1.2\$)
2470             \DWATconstvalue(7)
2471 OUTER.CI.1.3\$:
2472         \DWTAGvariable
2473             ! No name
2474             \DWATabstractorigin(reference to OUTER.AI.1.3\$)
2475             \DWATlocation(...)
2476         !
2477         ! No \DWTAGsubprogram (abstract instance) for INNER
2478         !
2479         ! Concrete instance for call INNER(OUTER\_LOCAL)
2480         !
2481 INNER.CI.1.1\$:
2482         \DWTAGinlinedsubroutine
2483             ! No name
2484             \DWATabstractorigin(reference to INNER.AI.1.1\$)
2485             \DWATlowpc(...)
2486             \DWAThighpc(...)
2487             \DWATstaticlink(...)
2488 INNER.CI.1.2\$:
2489             \DWTAGformalparameter
2490                 ! No name
2491                 \DWATabstractorigin(reference to INNER.AI.1.2\$)
2492                 \DWATlocation(...)
2493 INNER.CI.1.3\$:
2494             \DWTAGvariable
2495                 ! No name
2496                 \DWATabstractorigin(reference to INNER.AI.1.3\$)
2497                 \DWATlocation(...)
2498             ...
2499             0
2500         ! Another concrete instance of INNER within OUTER
2501         ! for the call "INNER(31)"
2502         ...
2503         0
2504 \end{alltt}
2505 \end{dwflisting}
2506 \caption{Inlining example \#1: concrete instance}
2507 \label{fig:inliningexample1concreteinstance}
2508 \end{figure}
2509
2510 \subsection{Alternative \#2: Inline OUTER, multiple INNERs}
2511 \label{app:inlineoutermultiipleinners}
2512
2513
2514 In the second alternative we assume that subprogram \texttt{INNER}
2515 is not inlinable for some reason, but subprogram \texttt{OUTER} is
2516 inlinable.
2517 \addtoindexx{concrete instance!example}
2518 Each concrete inlined instance of \texttt{OUTER} has its
2519 own normal instance of \texttt{INNER}.
2520 The abstract instance for \texttt{OUTER},
2521 \addtoindexx{abstract instance!example}
2522 which includes \texttt{INNER}, is shown in
2523 Figure \refersec{fig:inliningexample2abstractinstance}.
2524
2525 Note that the debugging information in
2526 Figure \ref{fig:inliningexample2abstractinstance}
2527 differs from that in
2528 Figure \refersec{fig:inliningexample1abstractinstance}
2529 in that \texttt{INNER} lacks a
2530 \DWATinline{} attribute
2531 and therefore is not a distinct abstract instance. \texttt{INNER}
2532 is merely an out\dash of\dash line routine that is part of \texttt{OUTER}\textquoteright s
2533 abstract instance. This is reflected in the Figure by
2534 \addtoindexx{abstract instance!example}
2535 the fact that the labels for \texttt{INNER} use the substring \texttt{OUTER}
2536 instead of \texttt{INNER}.
2537
2538 A resulting
2539 \addtoindexx{concrete instance!example}
2540 concrete inlined instance of \texttt{OUTER} is shown in
2541 Figure \refersec{fig:inliningexample2concreteinstance}.
2542
2543 Notice in
2544 Figure \ref{fig:inliningexample2concreteinstance}
2545 that \texttt{OUTER} is expanded as a concrete
2546 \addtoindexx{concrete instance!example}
2547 inlined instance, and that \texttt{INNER} is nested within it as a
2548 concrete out\dash of\dash line subprogram. Because \texttt{INNER} is cloned
2549 for each inline expansion of \texttt{OUTER}, only the invariant
2550 attributes of \texttt{INNER}
2551 (for example, \DWATname) are specified
2552 in the abstract instance of \texttt{OUTER}, and the low\dash level,
2553 \addtoindexx{abstract instance!example}
2554 instance\dash specific attributes of \texttt{INNER} (for example,
2555 \DWATlowpc) are specified in
2556 each concrete instance of \texttt{OUTER}.
2557 \addtoindexx{concrete instance!example}
2558
2559 The several calls of \texttt{INNER} within \texttt{OUTER} are compiled as normal
2560 calls to the instance of \texttt{INNER} that is specific to the same
2561 instance of \texttt{OUTER} that contains the calls.
2562
2563 \begin{figure}[t]
2564 \begin{dwflisting}
2565 \begin{alltt}
2566     ! Abstract instance for OUTER
2567     ! \addtoindex{abstract instance}
2568 OUTER.AI.2.1\$:
2569     \DWTAGsubprogram
2570         \DWATname("OUTER")
2571         \DWATinline(\DWINLdeclaredinlined)
2572         ! No low/high PCs
2573 OUTER.AI.2.2\$:
2574         \DWTAGformalparameter
2575             \DWATname("OUTER\_FORMAL")
2576             \DWATtype(reference to integer)
2577             ! No location
2578 OUTER.AI.2.3\$:
2579         \DWTAGvariable
2580             \DWATname("OUTER\_LOCAL")
2581             \DWATtype(reference to integer)
2582             ! No location
2583         !
2584         ! Nested out-of-line INNER subprogram
2585         !
2586 OUTER.AI.2.4\$:
2587         \DWTAGsubprogram
2588             \DWATname("INNER")
2589             ! No \DWATinline
2590             ! No low/high PCs, frame\_base, etc.
2591 OUTER.AI.2.5\$:
2592             \DWTAGformalparameter
2593                 \DWATname("INNER\_FORMAL")
2594                 \DWATtype(reference to integer)
2595                 ! No location
2596 OUTER.AI.2.6\$:
2597             \DWTAGvariable
2598                 \DWATname("INNER\_LOCAL")
2599                 \DWATtype(reference to integer)
2600                 ! No location
2601             ...
2602             0
2603         ...
2604         0
2605 \end{alltt}
2606 \end{dwflisting}
2607 \caption{Inlining example \#2: abstract instance}
2608 \label{fig:inliningexample2abstractinstance}
2609 \end{figure}
2610
2611 \begin{figure}[t]
2612 \begin{dwflisting}
2613 \begin{alltt}
2614
2615     ! Concrete instance for call "OUTER(7)"
2616     !
2617 OUTER.CI.2.1\$:
2618     \DWTAGinlinedsubroutine
2619         ! No name
2620         \DWATabstractorigin(reference to OUTER.AI.2.1\$)
2621         \DWATlowpc(...)
2622         \DWAThighpc(...)
2623 OUTER.CI.2.2\$:
2624         \DWTAGformalparameter
2625             ! No name
2626             \DWATabstractorigin(reference to OUTER.AI.2.2\$)
2627             \DWATlocation(...)
2628 OUTER.CI.2.3\$:
2629         \DWTAGvariable
2630             ! No name
2631             \DWATabstractorigin(reference to OUTER.AI.2.3\$)
2632             \DWATlocation(...)
2633         !
2634         ! Nested out-of-line INNER subprogram
2635         !
2636 OUTER.CI.2.4\$:
2637         \DWTAGsubprogram
2638             ! No name
2639             \DWATabstractorigin(reference to OUTER.AI.2.4\$)
2640             \DWATlowpc(...)
2641             \DWAThighpc(...)
2642             \DWATframebase(...)
2643             \DWATstaticlink(...)
2644 OUTER.CI.2.5\$:
2645             \DWTAGformalparameter
2646                 ! No name
2647                 \DWATabstractorigin(reference to OUTER.AI.2.5\$)
2648                 \DWATlocation(...)
2649 OUTER.CI.2.6\$:
2650             \DWTAGvariable
2651                 ! No name
2652                 \DWATabstractorigin(reference to OUTER.AT.2.6\$)
2653                 \DWATlocation(...)
2654             ...
2655             0
2656         ...
2657         0
2658 \end{alltt}
2659 \end{dwflisting}
2660 \caption{Inlining example \#2: concrete instance}
2661 \label{fig:inliningexample2concreteinstance}
2662 \end{figure}
2663
2664 \subsection{Alternative \#3: inline OUTER, one normal INNER}
2665 \label{app:inlineouteronenormalinner}
2666
2667 In the third approach, one normal subprogram for \texttt{INNER} is
2668 compiled which is called from all concrete inlined instances of
2669 \addtoindexx{concrete instance!example}
2670 \addtoindexx{abstract instance!example}
2671 \texttt{OUTER}. The abstract instance for \texttt{OUTER} is shown in
2672 Figure \refersec{fig:inliningexample3abstractinstance}.
2673
2674 The most distinctive aspect of that Figure is that subprogram
2675 \texttt{INNER} exists only within the abstract instance of \texttt{OUTER},
2676 and not in \texttt{OUTER}\textquoteright s concrete instance. In the abstract
2677 \addtoindexx{concrete instance!example}
2678 \addtoindexx{abstract instance!example}
2679 instance of \texttt{OUTER}, the description of \texttt{INNER} has the full
2680 complement of attributes that would be expected for a
2681 normal subprogram.
2682 While attributes such as
2683 \DWATlowpc,
2684 \DWAThighpc,
2685 \DWATlocation,
2686 and so on, typically are omitted
2687 \addtoindexx{high PC attribute}
2688 from
2689 \addtoindexx{low PC attribute}
2690 an
2691 \addtoindexx{location attribute}
2692 abstract instance because they are not invariant across
2693 instances of the containing abstract instance, in this case
2694 those same attributes are included precisely because they are
2695 invariant -- there is only one subprogram \texttt{INNER} to be described
2696 and every description is the same.
2697
2698 A concrete inlined instance of \texttt{OUTER} is illustrated in
2699 Figure \refersec{fig:inliningexample3concreteinstance}.
2700
2701 Notice in
2702 Figure \ref{fig:inliningexample3concreteinstance}
2703 that there is no DWARF representation for
2704 \texttt{INNER} at all; the representation of \texttt{INNER} does not vary across
2705 instances of \texttt{OUTER} and the abstract instance of \texttt{OUTER} includes
2706 the complete description of \texttt{INNER}, so that the description of
2707 \texttt{INNER} may be (and for reasons of space efficiency, should be)
2708 omitted from each
2709 \addtoindexx{concrete instance!example}
2710 concrete instance of \texttt{OUTER}.
2711
2712 There is one aspect of this approach that is problematical from
2713 the DWARF perspective. The single compiled instance of \texttt{INNER}
2714 is assumed to access up\dash level variables of \texttt{OUTER}; however,
2715 those variables may well occur at varying positions within
2716 the frames that contain the
2717 \addtoindexx{concrete instance!example}
2718 concrete inlined instances. A
2719 compiler might implement this in several ways, including the
2720 use of additional compiler-generated parameters that provide
2721 reference parameters for the up\dash level variables, or a
2722 compiler-generated static link like parameter that points to the group
2723 of up\dash level entities, among other possibilities. In either of
2724 these cases, the DWARF description for the location attribute
2725 of each uplevel variable needs to be different if accessed
2726 from within \texttt{INNER} compared to when accessed from within the
2727 instances of \texttt{OUTER}. An implementation is likely to require
2728 vendor\dash specific DWARF attributes and/or debugging information
2729 entries to describe such cases.
2730
2731 Note that in \addtoindex{C++}, a member function of a class defined within
2732 a function definition does not require any vendor\dash specific
2733 extensions because the \addtoindex{C++} language disallows access to
2734 entities that would give rise to this problem. (Neither \texttt{extern}
2735 variables nor \texttt{static} members require any form of static link
2736 for accessing purposes.)
2737
2738 \begin{figure}[t]
2739 \begin{dwflisting}
2740 \begin{alltt}
2741     ! Abstract instance for OUTER
2742     ! \addtoindexx{abstract instance!example}
2743 OUTER.AI.3.1\$:
2744     \DWTAGsubprogram
2745         \DWATname("OUTER")
2746         \DWATinline(\DWINLdeclaredinlined)
2747         ! No low/high PCs
2748 OUTER.AI.3.2\$:
2749         \DWTAGformalparameter
2750             \DWATname("OUTER\_FORMAL")
2751             \DWATtype(reference to integer)
2752             ! No location
2753 OUTER.AI.3.3\$:
2754         \DWTAGvariable
2755             \DWATname("OUTER\_LOCAL")
2756             \DWATtype(reference to integer)
2757             ! No location
2758         !
2759         ! Normal INNER
2760         !
2761 OUTER.AI.3.4\$:
2762         \DWTAGsubprogram
2763             \DWATname("INNER")
2764             \DWATlowpc(...)
2765             \DWAThighpc(...)
2766             \DWATframebase(...)
2767             \DWATstaticlink(...)
2768 OUTER.AI.3.5\$:
2769             \DWTAGformalparameter
2770                 \DWATname("INNER\_FORMAL")
2771                 \DWATtype(reference to integer)
2772                 \DWATlocation(...)
2773 OUTER.AI.3.6\$:
2774             \DWTAGvariable
2775                 \DWATname("INNER\_LOCAL")
2776                 \DWATtype(reference to integer)
2777                 \DWATlocation(...)
2778             ...
2779             0
2780         ...
2781         0
2782 \end{alltt}
2783 \end{dwflisting}
2784 \caption{Inlining example \#3: abstract instance}
2785 \label{fig:inliningexample3abstractinstance}
2786 \end{figure}
2787
2788 \clearpage
2789 \begin{figure}[t]
2790 \begin{dwflisting}
2791 \begin{alltt}
2792     ! Concrete instance for call "OUTER(7)"
2793     ! \addtoindexx{concrete instance!example}
2794 OUTER.CI.3.1\$:
2795     \DWTAGinlinedsubroutine
2796         ! No name
2797         \DWATabstractorigin(reference to OUTER.AI.3.1\$)
2798         \DWATlowpc(...)
2799         \DWAThighpc(...)
2800         \DWATframebase(...)
2801 OUTER.CI.3.2\$:
2802         \DWTAGformalparameter
2803             ! No name
2804             \DWATabstractorigin(reference to OUTER.AI.3.2\$)
2805             ! No type
2806             \DWATlocation(...)
2807 OUTER.CI.3.3\$:
2808         \DWTAGvariable
2809             ! No name
2810             \DWATabstractorigin(reference to OUTER.AI.3.3\$)
2811             ! No type
2812             \DWATlocation(...)
2813         ! No \DWTAGsubprogram for "INNER"
2814         ...
2815         0
2816 \end{alltt}
2817 \end{dwflisting}
2818 \caption{Inlining example \#3: concrete instance}
2819 \label{fig:inliningexample3concreteinstance}
2820 \end{figure}
2821
2822 \vspace*{0.4\baselineskip}
2823 \section{Constant Expression Example}
2824 \label{app:constantexpressionexample}
2825 \addtoindex{C++} generalizes the notion of constant expressions to include
2826 constant expression user-defined literals and functions.
2827 The constant declarations in Figure \refersec{fig:constantexpressionscsource}
2828 can be represented as illustrated in
2829 Figure \refersec{fig:constantexpressionsdwarfdescription}.
2830
2831 \begin{figure}[ht]
2832 \begin{nlnlisting}
2833 constexpr double mass = 9.8;
2834 constexpr int square (int x) { return x * x; }
2835 float arr[square(9)]; // square() called and inlined
2836 \end{nlnlisting}
2837 \caption{Constant expressions: C++ source} \label{fig:constantexpressionscsource}
2838 \end{figure}
2839
2840 \begin{figure}[!ht]
2841 \begin{dwflisting}
2842 \begin{alltt}
2843         ! For variable mass
2844         !
2845 1\$:     \DWTAGconsttype
2846             \DWATtype(reference to "double")
2847 2\$:     \DWTAGvariable
2848             \DWATname("mass")
2849             \DWATtype(reference to 1\$)
2850             \DWATconstexpr(true)
2851             \DWATconstvalue(9.8)
2852         ! Abstract instance for square
2853         !
2854 10\$:    \DWTAGsubprogram
2855             \DWATname("square")
2856             \DWATtype(reference to "int")
2857             \DWATinline(\DWINLinlined)
2858 11\$:        \DWTAGformalparameter
2859                 \DWATname("x")
2860                 \DWATtype(reference to "int")
2861         ! Concrete instance for square(9)
2862         ! \addtoindexx{concrete instance!example}
2863 20\$:    \DWTAGinlinedsubroutine
2864             \DWATabstractorigin(reference to 10\$)
2865             \DWATconstexpr(present)
2866             \DWATconstvalue(81)
2867             \DWTAGformalparameter
2868                 \DWATabstractorigin(reference to 11\$)
2869                 \DWATconstvalue(9)
2870         ! Anonymous array type for arr
2871         !
2872 30\$:    \DWTAGarraytype
2873             \DWATtype(reference to "float")
2874             \DWATbytesize(324) ! 81*4
2875             \DWTAGsubrangetype
2876                 \DWATtype(reference to "int")
2877                 \DWATupperbound(reference to 20\$)
2878         ! Variable arr
2879         !
2880 40\$:    \DWTAGvariable
2881             \DWATname("arr")
2882             \DWATtype(reference to 30\$)
2883 \end{alltt}
2884 \end{dwflisting}
2885 \caption{Constant expressions: DWARF description}
2886 \label{fig:constantexpressionsdwarfdescription}
2887 \end{figure}
2888
2889 \clearpage
2890 \section{Unicode Character Example}
2891 \label{app:unicodecharacterexample}
2892 \addtoindexx{Unicode|see {\textit{also} UTF-8}}
2893 The \addtoindex{Unicode} character encodings in
2894 Figure \refersec{fig:unicodecharacterexamplesource}
2895 can be described in DWARF as illustrated in
2896 Figure \refersec{fig:unicodecharacterexampledwarfdescription}.
2897
2898 \begin{figure}[!ht]
2899 \begin{nlnlisting}
2900 // C++ source
2901 //
2902 char16_t chr_a = u'h';
2903 char32_t chr_b = U'h';
2904 \end{nlnlisting}
2905 \caption{Unicode character example: source}
2906 \label{fig:unicodecharacterexamplesource}
2907 \end{figure}
2908
2909 \begin{figure}[ht]
2910 \begin{dwflisting}
2911 \begin{alltt}
2912
2913 ! DWARF description
2914 !
2915 1\$: \DWTAGbasetype
2916         \DWATname("char16\_t")
2917         \DWATencoding(\DWATEUTF)
2918         \DWATbytesize(2)
2919 2\$: \DWTAGbasetype
2920         \DWATname("char32\_t")
2921         \DWATencoding(\DWATEUTF)
2922         \DWATbytesize(4)
2923 3\$: \DWTAGvariable
2924         \DWATname("chr\_a")
2925         \DWATtype(reference to 1\$)
2926 4\$: \DWTAGvariable
2927         \DWATname("chr\_b")
2928         \DWATtype(reference to 2\$)
2929 \end{alltt}
2930 \end{dwflisting}
2931 \caption{Unicode character example: DWARF description}
2932 \label{fig:unicodecharacterexampledwarfdescription}
2933 \end{figure}
2934
2935 \clearpage
2936 \section{Type-Safe Enumeration Example}
2937 \label{app:typesafeenumerationexample}
2938
2939 The \addtoindex{C++} type\dash safe enumerations in
2940 \addtoindexx{type-safe enumeration}
2941 Figure \refersec{fig:ctypesafeenumerationexamplesource}
2942 can be described in DWARF as illustrated in
2943 Figure \refersec{fig:ctypesafeenumerationexampledwarf}.
2944
2945 \begin{figure}[ht]
2946 \begin{nlnlisting}
2947 // C++ source
2948 //
2949 enum class E { E1, E2=100 };
2950 E e1;
2951 \end{nlnlisting}
2952 \caption{Type-safe enumeration example: source}
2953 \label{fig:ctypesafeenumerationexamplesource}
2954 \end{figure}
2955
2956 \begin{figure}[ht]
2957 \begin{dwflisting}
2958 \begin{alltt}
2959 ! DWARF description
2960 !
2961 11\$:  \DWTAGenumerationtype
2962           \DWATname("E")
2963           \DWATtype(reference to "int")
2964           \DWATenumclass(present)
2965 12\$:      \DWTAGenumerator
2966               \DWATname("E1")
2967               \DWATconstvalue(0)
2968 13\$:      \DWTAGenumerator
2969               \DWATname("E2")
2970               \DWATconstvalue(100)
2971 14\$:  \DWTAGvariable
2972           \DWATname("e1")
2973           \DWATtype(reference to 11\$)
2974 \end{alltt}
2975 \end{dwflisting}
2976 \caption{Type-safe enumeration example: DWARF description}
2977 \label{fig:ctypesafeenumerationexampledwarf}
2978 \end{figure}
2979
2980
2981 \clearpage
2982 \section{Template Examples}
2983 \label{app:templateexample}
2984
2985 The \addtoindex{C++} template example in
2986 Figure \refersec{fig:ctemplateexample1source}
2987 can be described in DWARF as illustrated in
2988 Figure \refersec{fig:ctemplateexample1dwarf}.
2989
2990 \begin{figure}[ht]
2991 \begin{nlnlisting}
2992 // C++ source
2993 //
2994 template<class T>
2995 struct wrapper {
2996     T comp;
2997 };
2998 wrapper<int> obj;
2999 \end{nlnlisting}
3000 \caption{C++ template example \#1: source}
3001 \label{fig:ctemplateexample1source}
3002 \end{figure}
3003
3004 \begin{figure}[ht]
3005 \begin{dwflisting}
3006 \begin{alltt}
3007 ! DWARF description
3008 !
3009 11\$:  \DWTAGstructuretype
3010           \DWATname("wrapper")
3011 12\$:      \DWTAGtemplatetypeparameter
3012               \DWATname("T")
3013               \DWATtype(reference to "int")
3014 13\$:      \DWTAGmember
3015               \DWATname("comp")
3016               \DWATtype(reference to 12\$)
3017 14\$:  \DWTAGvariable
3018           \DWATname("obj")
3019           \DWATtype(reference to 11\$)
3020 \end{alltt}
3021 \end{dwflisting}
3022 \caption{C++ template example \#1: DWARF description}
3023 \label{fig:ctemplateexample1dwarf}
3024 \end{figure}
3025
3026 The actual type of the component \texttt{comp} is \texttt{int}, but in the DWARF
3027 the type references the
3028 \DWTAGtemplatetypeparameter{}
3029 for \texttt{T}, which in turn references \texttt{int}. This implies that in the
3030 original template comp was of type \texttt{T} and that was replaced
3031 with \texttt{int} in the instance.
3032
3033 \needlines{10}
3034 There exist situations where it is
3035 not possible for the DWARF to imply anything about the nature
3036 of the original template.
3037 Consider the \addtoindex{C++} template source in
3038 Figure \refersec{fig:ctemplateexample2source}
3039 and the DWARF that can describe it in
3040 Figure \refersec{fig:ctemplateexample2dwarf}.
3041
3042 \begin{figure}[!ht]
3043 \begin{nlnlisting}
3044 // C++ source
3045 //
3046     template<class T>
3047     struct wrapper {
3048         T comp;
3049     };
3050     template<class U>
3051     void consume(wrapper<U> formal)
3052     {
3053         ...
3054     }
3055     wrapper<int> obj;
3056     consume(obj);
3057 \end{nlnlisting}
3058 \caption{C++ template example \#2: source}
3059 \label{fig:ctemplateexample2source}
3060 \end{figure}
3061
3062 \begin{figure}[ht]
3063 \begin{dwflisting}
3064 \begin{alltt}
3065 ! DWARF description
3066 !
3067 11\$:  \DWTAGstructuretype
3068           \DWATname("wrapper")
3069 12\$:      \DWTAGtemplatetypeparameter
3070               \DWATname("T")
3071               \DWATtype(reference to "int")
3072 13\$:      \DWTAGmember
3073               \DWATname("comp")
3074               \DWATtype(reference to 12\$)
3075 14\$:  \DWTAGvariable
3076           \DWATname("obj")
3077           \DWATtype(reference to 11\$)
3078 21\$:  \DWTAGsubprogram
3079           \DWATname("consume")
3080 22\$:      \DWTAGtemplatetypeparameter
3081               \DWATname("U")
3082               \DWATtype(reference to "int")
3083 23\$:      \DWTAGformalparameter
3084               \DWATname("formal")
3085               \DWATtype(reference to 11\$)
3086 \end{alltt}
3087 \end{dwflisting}
3088 \caption{C++ template example \#2: DWARF description}
3089 \label{fig:ctemplateexample2dwarf}
3090 \end{figure}
3091
3092 In the \DWTAGsubprogram{}
3093 entry for the instance of consume, \texttt{U} is described as \texttt{int}.
3094 The type of formal is \texttt{wrapper\textless U\textgreater} in
3095 the source. DWARF only represents instantiations of templates;
3096 there is no entry which represents \texttt{wrapper\textless U\textgreater}
3097 which is neither
3098 a template parameter nor a template instantiation. The type
3099 of formal is described as \texttt{wrapper\textless int\textgreater},
3100 the instantiation of \texttt{wrapper\textless U\textgreater},
3101 in the \DWATtype{} attribute at
3102 23\$.
3103 There is no
3104 description of the relationship between template type parameter
3105 \texttt{T} at 12\$ and \texttt{U} at 22\$ which was used to instantiate
3106 \texttt{wrapper\textless U\textgreater}.
3107
3108 A consequence of this is that the DWARF information would
3109 not distinguish between the existing example and one where
3110 the formal parameter of \texttt{consume} were declared in the source to be
3111 \texttt{wrapper\textless int\textgreater}.
3112
3113
3114 \section{Template Alias Examples}
3115 \label{app:templatealiasexample}
3116
3117 The \addtoindex{C++} template alias shown in
3118 Figure \refersec{fig:ctemplatealiasexample1source}
3119 can be described in DWARF as illustrated
3120 \addtoindexx{template alias example} in
3121 Figure \refersec{fig:ctemplatealiasexample1dwarf}.
3122
3123 \begin{figure}[ht]
3124 \begin{nlnlisting}
3125 // C++ source, template alias example 1
3126 //
3127 template<typename T, typename U>
3128 struct Alpha {
3129     T tango;
3130     U uniform;
3131 };
3132 template<typename V> using Beta = Alpha<V,V>;
3133 Beta<long> b;
3134 \end{nlnlisting}
3135 \caption{C++ template alias example \#1: source}
3136 \label{fig:ctemplatealiasexample1source}
3137 \end{figure}
3138
3139 \clearpage
3140 \begin{figure}[ht]
3141 \addtoindexx{template alias example 1}
3142 \begin{dwflisting}
3143 \begin{alltt}
3144 ! DWARF representation for variable 'b'
3145 !
3146 20\$:  \DWTAGstructuretype
3147           \DWATname("Alpha")
3148 21\$:      \DWTAGtemplatetypeparameter
3149               \DWATname("T")
3150               \DWATtype(reference to "long")
3151 22\$:      \DWTAGtemplatetypeparameter
3152               \DWATname("U")
3153               \DWATtype(reference to "long")
3154 23\$:      \DWTAGmember
3155               \DWATname("tango")
3156               \DWATtype(reference to 21\$)
3157 24\$:      \DWTAGmember
3158               \DWATname("uniform")
3159               \DWATtype(reference to 22\$)
3160 25\$:  \DWTAGtemplatealias
3161           \DWATname("Beta")
3162           \DWATtype(reference to 20\$)
3163 26\$:      \DWTAGtemplatetypeparameter
3164               \DWATname("V")
3165               \DWATtype(reference to "long")
3166 27\$:  \DWTAGvariable
3167           \DWATname("b")
3168           \DWATtype(reference to 25\$)
3169 \end{alltt}
3170 \end{dwflisting}
3171 \caption{C++ template alias example \#1: DWARF description}
3172 \label{fig:ctemplatealiasexample1dwarf}
3173 \end{figure}
3174
3175 \vspace*{0.7\baselineskip}
3176 Similarly, the \addtoindex{C++} template alias shown in
3177 Figure \refersec{fig:ctemplatealiasexample2source}
3178 can be described in DWARF as illustrated
3179 \addtoindexx{template alias example} in
3180 Figure \refersec{fig:ctemplatealiasexample2dwarf}.
3181
3182 \begin{figure}[ht]
3183 \begin{nlnlisting}
3184 // C++ source, template alias example 2
3185 //
3186 template<class TX> struct X { };
3187 template<class TY> struct Y { };
3188 template<class T> using Z = Y<T>;
3189 X<Y<int>> y;
3190 X<Z<int>> z;
3191 \end{nlnlisting}
3192 \caption{C++ template alias example \#2: source}
3193 \label{fig:ctemplatealiasexample2source}
3194 \end{figure}
3195
3196 \begin{figure}[ht]
3197 \addtoindexx{template alias example 2}
3198 \begin{dwflisting}
3199 \begin{alltt}
3200 ! DWARF representation for X<Y<int>>
3201 !
3202 30\$:  \DWTAGstructuretype
3203           \DWATname("Y")
3204 31\$:      \DWTAGtemplatetypeparameter
3205               \DWATname("TY")
3206               \DWATtype(reference to "int")
3207 32\$:  \DWTAGstructuretype
3208           \DWATname("X")
3209 33\$:      \DWTAGtemplatetypeparameter
3210               \DWATname("TX")
3211               \DWATtype(reference to 30\$)
3212 !
3213 ! DWARF representation for X<Z<int>>
3214 !
3215 40\$:  \DWTAGtemplatealias
3216           \DWATname("Z")
3217           \DWATtype(reference to 30\$)
3218 41\$:      \DWTAGtemplatetypeparameter
3219               \DWATname("T")
3220               \DWATtype(reference to "int")
3221 42\$:  \DWTAGstructuretype
3222           \DWATname("X")
3223 43\$:      \DWTAGtemplatetypeparameter
3224               \DWATname("TX")
3225               \DWATtype(reference to 40\$)
3226 !
3227 ! Note that 32\$ and 42\$ are actually the same type
3228 !
3229 50\$:  \DWTAGvariable
3230           \DWATname("y")
3231           \DWATtype(reference to \$32)
3232 51\$:  \DWTAGvariable
3233           \DWATname("z")
3234           \DWATtype(reference to \$42)
3235 \end{alltt}
3236 \end{dwflisting}
3237 \caption{C++ template alias example \#2: DWARF description}
3238 \label{fig:ctemplatealiasexample2dwarf}
3239 \end{figure}
3240
3241 \clearpage
3242 \section{Implicit Pointer Examples}
3243 \label{app:implicitpointerexamples}
3244 If the compiler determines that the value of an object is
3245 constant (either throughout the program, or within a specific
3246 range), it may choose to materialize that constant only when
3247 used, rather than store it in memory or in a register. The
3248 \DWOPimplicitvalue{} operation can be used to describe such a
3249 value. Sometimes, the value may not be constant, but still can be
3250 easily rematerialized when needed. A DWARF expression terminating
3251 in \DWOPstackvalue{} can be used for this case. The compiler may
3252 also eliminate a pointer value where the target of the pointer
3253 resides in memory, and the \DWOPstackvalue{} operator may be used
3254 to rematerialize that pointer value. In other cases, the compiler
3255 will eliminate a pointer to an object that itself needs to be
3256 materialized. Since the location of such an object cannot be
3257 represented as a memory address, a DWARF expression cannot give
3258 either the location or the actual value or a pointer variable
3259 that would refer to that object. The \DWOPimplicitpointer{}
3260 operation can be used to describe the pointer, and the debugging
3261 information entry to which its first operand refers describes the
3262 value of the dereferenced object. A DWARF consumer will not be
3263 able to show the location or the value of the pointer variable,
3264 but it will be able to show the value of the dereferenced
3265 pointer.
3266
3267 Consider the \addtoindex{C} source shown in
3268 Figure \refersec{fig:cimplicitpointerexample1source}.
3269 Assume that the function \texttt{foo} is not inlined,
3270 that the argument x is passed in register 5, and that the
3271 function \texttt{foo} is optimized by the compiler into just
3272 an increment of the volatile variable \texttt{v}. Given these
3273 assumptions a possible DWARF description is shown in
3274 Figure \refersec{fig:cimplicitpointerexample1dwarf}.
3275
3276 \begin{figure}[ht]
3277 \begin{nlnlisting}
3278 struct S { short a; char b, c; };
3279 volatile int v;
3280 void foo (int x)
3281 {
3282     struct S s = { x, x + 2, x + 3 };
3283     char *p = &s.b;
3284     s.a++;
3285     v++;
3286 }
3287 int main ()
3288 {
3289     foo (v+1);
3290     return 0;
3291 }
3292 \end{nlnlisting}
3293 \caption{C implicit pointer example \#1: source}
3294 \label{fig:cimplicitpointerexample1source}
3295 \end{figure}
3296
3297 \begin{figure}[ht]
3298 \addtoindexx{implicit pointer example}
3299 \begin{dwflisting}
3300 \begin{alltt}
3301 1\$:   \DWTAGstructuretype
3302           \DWATname("S")
3303           \DWATbytesize(4)
3304 10\$:      \DWTAGmember
3305               \DWATname("a")
3306               \DWATtype(reference to "short int")
3307               \DWATdatamemberlocation(constant 0)
3308 11\$:      \DWTAGmember
3309               \DWATname("b")
3310               \DWATtype(reference to "char")
3311               \DWATdatamemberlocation(constant 2)
3312 12\$:      \DWTAGmember
3313               \DWATname("c")
3314               \DWATtype(reference to "char")
3315               \DWATdatamemberlocation(constant 3)
3316 2\$:   \DWTAGsubprogram
3317           \DWATname("foo")
3318 20\$:      \DWTAGformalparameter
3319               \DWATname("x")
3320               \DWATtype(reference to "int")
3321               \DWATlocation(\DWOPregfive)
3322 21\$:      \DWTAGvariable
3323               \DWATname("s")
3324               \DWATtype(reference to S at 1\$)
3325               \DWATlocation(expression=
3326                   \DWOPbregfive(1) \DWOPstackvalue \DWOPpiece(2)
3327                   \DWOPbregfive(2) \DWOPstackvalue \DWOPpiece(1)
3328                   \DWOPbregfive(3) \DWOPstackvalue \DWOPpiece(1))
3329 22\$:      \DWTAGvariable
3330               \DWATname("p")
3331               \DWATtype(reference to "char *")
3332               \DWATlocation(expression=
3333                   \DWOPimplicitpointer(reference to 21\$, 2))
3334 \end{alltt}
3335 \end{dwflisting}
3336 \caption{C implicit pointer example \#1: DWARF description}
3337 \label{fig:cimplicitpointerexample1dwarf}
3338 \end{figure}
3339
3340 In Figure \refersec{fig:cimplicitpointerexample1dwarf},
3341 even though variables \texttt{s} and \texttt{p} are both optimized
3342 away completely, this DWARF description still allows a debugger to
3343 print the value of the variable \texttt{s}, namely \texttt{(2, 3, 4)}.
3344 Similarly, because the variable \texttt{s} does not live in
3345 memory, there is nothing to print for the value of \texttt{p}, but the
3346 debugger should still be able to show that \texttt{p[0]} is 3,
3347 \texttt{p[1]} is 4, \texttt{p[-1]} is 0 and \texttt{p[-2]} is 2.
3348
3349 \needlines{6}
3350 As a further example, consider the C source
3351 shown in Figure \refersec{fig:cimplicitpointerexample2source}. Make
3352 the following assumptions about how the code is compiled:
3353 \begin{itemize}
3354 \item The function \texttt{foo} is inlined
3355 into function \texttt{main}
3356 \item The body of the main function is optimized to just
3357 three blocks of instructions which each increment the volatile
3358 variable \texttt{v}, followed by a block of instructions to return 0 from
3359 the function
3360 \item Label \texttt{label0} is at the start of the main
3361 function, \texttt{label1} follows the first \texttt{v++} block,
3362 \texttt{label2} follows the second \texttt{v++} block and
3363 \texttt{label3} is at the end of the main function
3364 \item Variable \texttt{b} is optimized away completely, as it isn't used
3365 \item The string literal \texttt{"opq"} is optimized away as well
3366 \end{itemize}
3367 Given these assumptions a possible DWARF description is shown in
3368 Figure \refersec{fig:cimplicitpointerexample2dwarf}.
3369
3370 \begin{figure}[ht]
3371 \begin{dwflisting}
3372 \begin{alltt}
3373
3374 static const char *b = "opq";
3375 volatile int v;
3376 static inline void foo (int *p)
3377 \{
3378     (*p)++;
3379     v++;
3380     p++;
3381     (*p)++;
3382     v++;
3383 \}
3384
3385 int main ()
3386 \{
3387 label0:
3388     int a[2] = { 1, 2 };
3389     v++;
3390 label1:
3391     foo (a);
3392 label2:
3393     return a[0] + a[1] - 5;
3394 label3:
3395 \}
3396
3397 \end{alltt}
3398 \end{dwflisting}
3399 \caption{C implicit pointer example \#2: source}
3400 \label{fig:cimplicitpointerexample2source}
3401 \end{figure}
3402
3403 \begin{figure}[ht]
3404 \addtoindexx{implicit pointer example}
3405 \begin{dwflisting}
3406 \begin{alltt}
3407 1\$:   \DWTAGvariable
3408           \DWATname("b")
3409           \DWATtype(reference to "const char *")
3410           \DWATlocation(expression=
3411               \DWOPimplicitpointer(reference to 2$, 0))
3412 2\$:   \DWTAGdwarfprocedure
3413           \DWATlocation(expression=
3414               \DWOPimplicitvalue(4, \{'o', 'p', 'q', '\textbackslash{}0'\}))
3415 3\$:   \DWTAGsubprogram
3416           \DWATname("foo")
3417           \DWATinline(\DWINLdeclaredinlined)
3418 30\$:      \DWTAGformalparameter
3419               \DWATname("p")
3420               \DWATtype(reference to "int *")
3421 4\$:   \DWTAGsubprogram
3422           \DWATname("main")
3423 40\$:           \DWTAGvariable
3424               \DWATname("a")
3425               \DWATtype(reference to "int[2]")
3426               \DWATlocation(location list 98$)
3427 41\$:      \DWTAGinlinedsubroutine
3428               \DWATabstractorigin(reference to 3$)
3429 42\$:          \DWTAGformalparameter
3430                   \DWATabstractorigin(reference to 30$)
3431                   \DWATlocation(location list 99$)
3432
3433 ! .debug_loclists section
3434 98\$:  \DWLLEstartend[<label0 in main> .. <label1 in main>)
3435           \DWOPlitone \DWOPstackvalue \DWOPpiece(4)
3436           \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
3437       \DWLLEstartend[<label1 in main> .. <label2 in main>)
3438           \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
3439           \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
3440       \DWLLEstartend[<label2 in main> .. <label3 in main>)
3441           \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
3442           \DWOPlitthree \DWOPstackvalue \DWOPpiece(4)
3443       \DWLLEendoflist
3444 99\$:  \DWLLEstartend[<label1 in main> .. <label2 in main>)
3445           \DWOPimplicitpointer(reference to 40\$, 0)
3446       \DWLLEstartend[<label2 in main> .. <label3 in main>)
3447           \DWOPimplicitpointer(reference to 40\$, 4)
3448       \DWLLEendoflist
3449 \end{alltt}
3450 \end{dwflisting}
3451 \caption{C implicit pointer example \#2: DWARF description}
3452 \label{fig:cimplicitpointerexample2dwarf}
3453 \end{figure}
3454
3455 \clearpage
3456 \section{String Type Examples}
3457 \label{app:stringtypeexamples}
3458 Consider the \addtoindex{Fortran 2003} string type example source in
3459 Figure \referfol{fig:stringtypeexamplesource}. The DWARF representation in
3460 Figure \refersec{fig:stringtypeexampledwarf} is appropriate.
3461
3462 \begin{figure}[ht]
3463 \addtoindexx{ISO 10646 character set standard}
3464 \begin{nlnlisting}
3465         program character_kind
3466             use iso_fortran_env
3467             implicit none
3468             integer, parameter :: ascii =
3469                 selected_char_kind ("ascii")
3470             integer, parameter :: ucs4  =
3471                 selected_char_kind ('ISO_10646')
3472             character(kind=ascii, len=26) :: alphabet
3473             character(kind=ucs4,  len=30) :: hello_world
3474             character (len=*), parameter :: all_digits="0123456789"
3475
3476             alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
3477             hello_world = ucs4_'Hello World and Ni Hao -- ' &
3478                           // char (int (z'4F60'), ucs4)     &
3479                           // char (int (z'597D'), ucs4)
3480
3481             write (*,*) alphabet
3482             write (*,*) all_digits
3483
3484             open (output_unit, encoding='UTF-8')
3485             write (*,*) trim (hello_world)
3486         end program character_kind
3487 \end{nlnlisting}
3488 \caption{String type example: source}
3489 \label{fig:stringtypeexamplesource}
3490 \end{figure}
3491
3492 \begin{figure}[ht]
3493 \begin{dwflisting}
3494 \begin{alltt}
3495
3496 1\$: \DWTAGbasetype
3497         \DWATencoding (\DWATEASCII)
3498
3499 2\$: \DWTAGbasetype
3500         \DWATencoding (\DWATEUCS)
3501         \DWATbytesize (4)
3502
3503 3\$: \DWTAGstringtype
3504         \DWATbytesize (10)
3505
3506 4\$: \DWTAGconsttype
3507         \DWATtype (reference to 3\$)
3508
3509 5\$: \DWTAGstringtype
3510         \DWATtype (1\$)
3511         \DWATstringlength ( ... )
3512         \DWATstringlengthbytesize ( ... )
3513         \DWATdatalocation ( ... )
3514
3515 6\$: \DWTAGstringtype
3516         \DWATtype (2\$)
3517         \DWATstringlength ( ... )
3518         \DWATstringlengthbytesize ( ... )
3519         \DWATdatalocation ( ... )
3520
3521 7\$: \DWTAGvariable
3522         \DWATname (alphabet)
3523         \DWATtype (5\$)
3524         \DWATlocation ( ... )
3525
3526 8\$: \DWTAGconstant
3527         \DWATname (all\_digits)
3528         \DWATtype (4\$)
3529         \DWATconstvalue ( ... )
3530
3531 9\$: \DWTAGvariable
3532         \DWATname (hello\_world)
3533         \DWATtype (6\$)
3534         \DWATlocation ( ... )
3535
3536 \end{alltt}
3537 \end{dwflisting}
3538 \caption{String type example: DWARF representation}
3539 \label{fig:stringtypeexampledwarf}
3540 \end{figure}
3541
3542 \clearpage
3543 \section{Call Site Examples}
3544 \label{app:callsiteexamples}
3545 The following examples use a hypothetical machine which:
3546 \begin{itemize}
3547 \item
3548 Passes the first argument in register 0, the second in register 1, and the third in register 2.
3549 \item
3550 Keeps the stack pointer is register 3.
3551 \item
3552 Has one call preserved register 4.
3553 \item
3554 Returns a function value in register 0.
3555 \end{itemize}
3556
3557 \subsection{Call Site Example \#1 (C)}
3558 Consider the \addtoindex{C} source in Figure \referfol{fig:callsiteexample1source}.
3559
3560 \begin{figure}[ht]
3561 \begin{nlnlisting}
3562
3563 extern void fn1 (long int, long int, long int);
3564
3565 long int
3566 fn2 (long int a, long int b, long int c)
3567 {
3568     long int q = 2 * a;
3569     fn1 (5, 6, 7);
3570     return 0;
3571 }
3572
3573 long int
3574 fn3 (long int x, long int (*fn4) (long int *))
3575 {
3576     long int v, w, w2, z;
3577     w = (*fn4) (&w2);
3578     v = (*fn4) (&w2);
3579     z = fn2 (1, v + 1, w);
3580     {
3581         int v1 = v + 4;
3582         z += fn2 (w, v * 2, x);
3583     }
3584     return z;
3585 }
3586 \end{nlnlisting}
3587 \caption{Call Site Example \#1: Source}
3588 \label{fig:callsiteexample1source}
3589 \end{figure}
3590
3591 Possible generated code for this source is shown using a suggestive
3592 pseudo-\linebreak[0]assembly notation in Figure \refersec{fig:callsiteexample1code}.
3593
3594 \begin{figure}[ht]
3595 \begin{nlnlisting}
3596 fn2:
3597 L1:
3598     %reg2 = 7   ! Load the 3rd argument to fn1
3599     %reg1 = 6   ! Load the 2nd argument to fn1
3600     %reg0 = 5   ! Load the 1st argument to fn1
3601 L2:
3602     call fn1
3603     %reg0 = 0   ! Load the return value from the function
3604     return
3605 L3:
3606 fn3:
3607     ! Decrease stack pointer to reserve local stack frame
3608     %reg3 = %reg3 - 32
3609     [%reg3] = %reg4       ! Save the call preserved register to
3610                           !   stack
3611     [%reg3 + 8] = %reg0   ! Preserve the x argument value
3612     [%reg3 + 16] = %reg1  ! Preserve the fn4 argument value
3613     %reg0 = %reg3 + 24    ! Load address of w2 as argument
3614     call %reg1            ! Call fn4 (indirect call)
3615 L6:
3616     %reg2 = [%reg3 + 16]  ! Load the fn4 argument value
3617     [%reg3 + 16] = %reg0  ! Save the result of the first call (w)
3618     %reg0 = %reg3 + 24    ! Load address of w2 as argument
3619     call %reg2            ! Call fn4 (indirect call)
3620 L7:
3621     %reg4 = %reg0         ! Save the result of the second call (v)
3622                           !   into register.
3623     %reg2 = [%reg3 + 16]  ! Load 3rd argument to fn2 (w)
3624     %reg1 = %reg4 + 1     ! Compute 2nd argument to fn2 (v + 1)
3625     %reg0 = 1             ! Load 1st argument to fn2
3626     call fn2
3627 L4:
3628     %reg2 = [%reg3 + 8]   ! Load the 3rd argument to fn2 (x)
3629     [%reg3 + 8] = %reg0   ! Save the result of the 3rd call (z)
3630     %reg0 = [%reg3 + 16]  ! Load the 1st argument to fn2 (w)
3631     %reg1 = %reg4 + %reg4 ! Compute the 2nd argument to fn2 (v * 2)
3632     call fn2
3633 L5:
3634     %reg2 = [%reg3 + 8]   ! Load the value of z from the stack
3635     %reg0 = %reg0 + %reg2 ! Add result from the 4th call to it
3636 L8:
3637     %reg4 = [%reg3]       ! Restore original value of call preserved
3638                           !   register
3639     %reg3 = %reg3 + 32    ! Leave stack frame
3640     return
3641 \end{nlnlisting}
3642 \caption{Call Site Example \#1: Code}
3643 \label{fig:callsiteexample1code}
3644 \end{figure}
3645
3646 \clearpage
3647 The location list for variable \texttt{a} in function \texttt{fn2}
3648 might look like the following
3649 (where the notation \doublequote{\textit{Range} [\texttt{m .. n)}}
3650 specifies the range of addresses from \texttt{m} through but not
3651 including \texttt{n} over which the following
3652 location description applies):
3653
3654 \nolinenumbers
3655 \begin{dwflisting}
3656 \begin{alltt}
3657
3658     ! Before the assignment to register 0, the argument a is live in register 0
3659     !
3660     \textit{Range} [L1 .. L2)
3661         \DWOPregzero
3662
3663     ! Afterwards, it is not. The value can perhaps be looked up in the caller
3664     !
3665     \textit{Range} [L2 .. L3)
3666         \DWOPentryvalue 1 \DWOPregzero \DWOPstackvalue
3667     \textit{End-of-list}
3668
3669 \end{alltt}
3670 \end{dwflisting}
3671
3672 \vspace*{0.7\baselineskip}
3673 \condlinenumbers
3674 Similarly, the variable \texttt{q} in \texttt{fn2} then might have this location list:
3675 \par\nolinenumbers
3676 \begin{dwflisting}
3677 \begin{alltt}
3678
3679     ! Before the assignment to register 0, the value of q can be computed as
3680     ! two times the contents of register 0
3681     !
3682     \textit{Range} [L1 .. L2)
3683         \DWOPlittwo \DWOPbregzero 0 \DWOPmul \DWOPstackvalue
3684
3685     ! Afterwards. it is not. It can be computed from the original value of
3686     ! the first parameter, multiplied by two
3687     !
3688     \textit{Range} [L2 .. L3)
3689         \DWOPlittwo \DWOPentryvalue 1 \DWOPregzero \DWOPmul \DWOPstackvalue
3690     \textit{End-of-list}
3691
3692 \end{alltt}
3693 \end{dwflisting}
3694
3695 \vspace*{0.7\baselineskip}
3696 \condlinenumbers
3697 Variables \texttt{b} and \texttt{c} each have a location list similar to
3698 that for variable \texttt{a},
3699 except for a different label between the two ranges and they
3700 use \DWOPregone{} and \DWOPregtwo{}, respectively, instead of \DWOPregzero.
3701
3702
3703 The call sites for all the calls in function \texttt{fn3} are children of the
3704 \DWTAGsubprogram{} entry for \texttt{fn3} (or of its \DWTAGlexicalblock{} entry
3705 if there is any for the whole function).
3706 This is shown in Figure \refersec{fig:callsiteexample1dwarf}.
3707
3708 \begin{figure}[ht]
3709 \figurepart{1}{2}
3710 \begin{dwflisting}
3711 \begin{alltt}
3712     \DWTAGcallsite
3713         \DWATcallreturnpc(L6) ! First indirect call to (*fn4) in fn3.
3714         ! The address of the call is preserved across the call in memory at
3715         ! stack pointer + 16 bytes.
3716         \DWATcalltarget(\DWOPbregthree{} 16 \DWOPderef)
3717         \DWTAGcallsiteparameter
3718             \DWATlocation(\DWOPregzero)
3719             ! Value of the first parameter is equal to stack pointer + 24 bytes.
3720             \DWATcallvalue(\DWOPbregthree{} 24)
3721     \DWTAGcallsite
3722         \DWATcallreturnpc(L7) ! Second indirect call to (*fn4) in fn3.
3723         ! The address of the call is not preserved across the call anywhere, but
3724         ! could be perhaps looked up in fn3's caller.
3725         \DWATcalltarget(\DWOPentryvalue{} 1 \DWOPregone)
3726         \DWTAGcallsiteparameter
3727             \DWATlocation(\DWOPregzero)
3728             \DWATcallvalue(\DWOPbregthree{} 24)
3729     \DWTAGcallsite
3730         \DWATcallreturnpc(L4) ! 3rd call in fn3, direct call to fn2
3731         \DWATcallorigin(reference to fn2 DW_TAG_subprogram)
3732         \DWTAGcallsiteparameter
3733             \DWATcallparameter(reference to formal parameter a in subprogram fn2)
3734             \DWATlocation(\DWOPregzero)
3735             ! First parameter to fn2 is constant 1
3736             \DWATcallvalue(\DWOPlitone)
3737         \DWTAGcallsiteparameter
3738             \DWATcallparameter(reference to formal parameter b in subprogram fn2)
3739             \DWATlocation(\DWOPregone)
3740             ! Second parameter to fn2 can be computed as the value of the call
3741             !   preserved register 4 in the fn3 function plus one
3742             \DWATcallvalue(\DWOPbregfour{} 1)
3743         \DWTAGcallsiteparameter
3744             \DWATcallparameter(reference to formal parameter c in subprogram fn2)
3745             \DWATlocation(\DWOPregtwo)
3746             ! Third parameter's value is preserved in memory at fn3's stack pointer
3747             !   plus 16 bytes
3748             \DWATcallvalue(\DWOPbregthree{} 16 \DWOPderef)
3749 \end{alltt}
3750 \end{dwflisting}
3751 \caption{Call site example \#1: DWARF encoding}
3752 \label{fig:callsiteexample1dwarf}
3753 \end{figure}
3754
3755 \begin{figure}
3756 \figurepart{2}{2}
3757 \begin{dwflisting}
3758 \begin{alltt}
3759 \DWTAGlexicalblock
3760     \DWATlowpc(L4)
3761     \DWAThighpc(L8)
3762     \DWTAGvariable
3763         \DWATname("v1")
3764         \DWATtype(reference to int)
3765         ! Value of the v1 variable can be computed as value of register 4 plus 4
3766         \DWATlocation(\DWOPbregfour{} 4 \DWOPstackvalue)
3767     \DWTAGcallsite
3768         \DWATcallreturnpc(L5) ! 4th call in fn3, direct call to fn2
3769         \DWATcalltarget(reference to subprogram fn2)
3770         \DWTAGcallsiteparameter
3771             \DWATcallparameter(reference to formal parameter a in subprogram fn2)
3772             \DWATlocation(\DWOPregzero)
3773             ! Value of the 1st argument is preserved in memory at fn3's stack
3774             !   pointer + 16 bytes.
3775             \DWATcallvalue(\DWOPbregthree{} 16 \DWOPderef)
3776         \DWTAGcallsiteparameter
3777             \DWATcallparameter(reference to formal parameter b in subprogram fn2)
3778             \DWATlocation(\DWOPregone)
3779             ! Value of the 2nd argument can be computed using the preserved
3780             !   register 4 multiplied by 2
3781             \DWATcallvalue(\DWOPlittwo{} \DWOPregfour{} 0 \DWOPmul)
3782         \DWTAGcallsiteparameter
3783             \DWATcallparameter(reference to formal parameter c in subprogram fn2)
3784             \DWATlocation(\DWOPregtwo)
3785             ! Value of the 3rd argument is not preserved, but could be perhaps
3786             ! computed from the value passed fn3's caller.
3787             \DWATcallvalue(\DWOPentryvalue{} 1 \DWOPregzero)
3788 \end{alltt}
3789 \end{dwflisting}
3790 \begin{center}
3791 \vspace{3mm}
3792 Figure~\ref{fig:callsiteexample1dwarf} Call site example \#1: DWARF encoding \textit{(concluded)}
3793 \end{center}
3794 \end{figure}
3795
3796 \clearpage
3797 \subsection{Call Site Example \#2 (Fortran)}
3798 Consider the \addtoindex{Fortran} source in
3799 Figure \refersec{fig:callsiteexample2source}
3800 which is used to illustrate how Fortran's \doublequote{pass by reference}
3801 parameters can be handled.
3802
3803 \begin{figure}[ht]
3804 \begin{nlnlisting}
3805 subroutine fn4 (n)
3806     integer :: n, x
3807     x = n
3808     n = n / 2
3809     call fn6
3810 end subroutine
3811 subroutine fn5 (n)
3812     interface fn4
3813         subroutine fn4 (n)
3814             integer :: n
3815         end subroutine
3816     end interface fn4
3817     integer :: n, x
3818     call fn4 (n)
3819     x = 5
3820     call fn4 (x)
3821 end subroutine fn5
3822 \end{nlnlisting}
3823 \caption{Call site example \#2: source}
3824 \label{fig:callsiteexample2source}
3825 \end{figure}
3826
3827 \clearpage
3828 Possible generated code for this source is shown using a suggestive
3829 pseudo-\linebreak[0]assembly notation in Figure \refersec{fig:callsiteexample2code}.
3830 \par % Needed to end paragraph before listing so that it gets a line number
3831 \begin{figure}[ht]
3832 \begin{nlnlisting}
3833
3834 fn4:
3835     %reg2 = [%reg0]   ! Load value of n (passed by reference)
3836     %reg2 = %reg2 / 2 ! Divide by 2
3837     [%reg0] = %reg2   ! Update value of n
3838     call fn6          ! Call some other function
3839     return
3840
3841 fn5:
3842     %reg3 = %reg3 - 8 ! Decrease stack pointer to create stack frame
3843     call fn4          ! Call fn4 with the same argument by reference
3844                       !   as fn5 has been called with
3845 L9:
3846     [%reg3] = 5       ! Pass value of 5 by reference to fn4
3847     %reg0 = %reg3     ! Put address of the value 5 on the stack
3848                       !   into 1st argument register
3849     call fn4
3850 L10:
3851     %reg3 = %reg3 + 8 ! Leave stack frame
3852     return
3853
3854 \end{nlnlisting}
3855 \caption{Call site example \#2: code}
3856 \label{fig:callsiteexample2code}
3857 \end{figure}
3858
3859 The location description for variable \texttt{x} in function
3860 \texttt{fn4} might be:
3861 \par % Needed to end paragraph before listing so that it gets a line number
3862 \begin{nlnlisting}
3863     DW_OP_entry_value 4 DW_OP_breg0 0 DW_OP_deref_size 4 DW_OP_stack_value
3864 \end{nlnlisting}
3865
3866 The call sites in (just) function \texttt{fn5} might be as shown in
3867 Figure \refersec{fig:callsiteexample2dwarf}.
3868
3869 \begin{figure}[ht]
3870 \begin{dwflisting}
3871 \begin{alltt}
3872
3873 \DWTAGcallsite
3874     \DWATcallreturnpc(L9)                       ! First call to fn4
3875     \DWATcallorigin(reference to subprogram fn4)
3876     \DWTAGcallsiteparameter
3877         \DWATcallparameter(reference to formal parameter n in subprogram fn4)
3878         \DWATlocation(\DWOPregzero)
3879         ! The value of register 0 at the time of the call can be perhaps
3880         !   looked up in fn5's caller
3881         \DWATcallvalue(\DWOPentryvalue{} 1 \DWOPregzero)
3882         ! DW_AT_call_data_location(DW_OP_push_object_address) ! left out, implicit
3883         ! And the actual value of the parameter can be also perhaps looked up in
3884         ! fn5's caller
3885         \DWATcalldatavalue(\DWOPentryvalue{} 4 \DWOPbregzero{} 0 \DWOPderefsize 4)
3886
3887 \DWTAGcallsite
3888     \DWATcallreturnpc(L10)                      ! Second call to fn4
3889     \DWATcallorigin(reference to subprogram fn4)
3890     \DWTAGcallsiteparameter
3891         \DWATcallparameter(reference to formal parameter n in subprogram fn4)
3892         \DWATlocation(\DWOPregzero)
3893         ! The value of register 0 at the time of the call is equal to the stack
3894         ! pointer value in fn5
3895         \DWATcallvalue(\DWOPbregthree{} 0)
3896         ! DW_AT_call_data_location(DW_OP_push_object_address) ! left out, implicit
3897         ! And the value passed by reference is constant 5
3898         \DWATcalldatavalue(\DWOPlitfive)
3899
3900 \end{alltt}
3901 \end{dwflisting}
3902 \caption{Call site example \#2: DWARF encoding}
3903 \label{fig:callsiteexample2dwarf}
3904 \end{figure}
3905
3906
3907 \clearpage
3908 \section{Macro Example}
3909 \label{macroexample}
3910 Consider the \addtoindex{C} source in Figure
3911 \referfol{ref:macroexamplesource} which is used to illustrate the
3912 DWARF encoding of macro information (see Section \refersec{chap:macroinformation}).
3913
3914 \begin{figure}[ht]
3915 \textit{File a.c}
3916 \begin{nlnlisting}
3917 #include "a.h"
3918 #define FUNCTION_LIKE_MACRO(x) 4+x
3919 #include "b.h"
3920 \end{nlnlisting}
3921 \vspace{7mm}
3922 \textit{File a.h}
3923 \begin{nlnlisting}
3924 #define LONGER_MACRO 1
3925 #define B 2
3926 #include "b.h"
3927 #define B 3
3928 \end{nlnlisting}
3929 \vspace{7mm}
3930 \textit{File b.h}
3931 \begin{nlnlisting}
3932 #undef B
3933 #define D 3
3934 #define FUNCTION_LIKE_MACRO(x) 4+x
3935 \end{nlnlisting}
3936 \caption{Macro example: source}
3937 \label{ref:macroexamplesource}
3938 \end{figure}
3939
3940 Two possible encodings are shown. The first, in
3941 Figure \refersec{fig:macroexamplesimpledwarfencoding}, is perhaps the simplest
3942 possible encoding. It includes all macro information from the
3943 main source file (\texttt{a.c}) as well as its two included files
3944 (\texttt{a.h} and \texttt{b.h}) in a single macro unit. Further,
3945 all strings are included as immediate operands of the macro
3946 operators (that is, there is no string pooling). The size
3947 of the macro unit is 160 bytes.
3948
3949 The second encoding, in
3950 Figure \refersec{fig:macroexampledsharablewarfencoding},
3951 saves space in two ways:
3952 \begin{enumerate}[1. ]
3953 \item Longer strings are pooled by storing them in the
3954 \dotdebugstr{} section where they can be referenced more than
3955 once.
3956
3957 \item Macro information entries contained in included files
3958 are represented as separate macro units which are then
3959 imported for each \texttt{\#include} directive.
3960
3961 \end{enumerate}
3962 The combined size of the three macro units and their referenced
3963 strings is 129 bytes.
3964
3965 \begin{figure}
3966 \begin{dwflisting}
3967 \begin{alltt}
3968
3969 ! *** Section \dotdebugmacro{} contents
3970 ! Macro unit for "a.c"
3971 0$h:    Version:        5
3972         Flags:          2
3973             \HFNoffsetsizeflag: 0           ! 4-byte offsets
3974             \HFNdebuglineoffsetflag: 1     ! Line number offset present
3975             \HFNopcodeoperandstableflag: 0 ! No extensions
3976         Offset in \dotdebugline{} section: 0  ! Line number offset
3977 0$m:    \DWMACROstartfile, 0, 0     ! Implicit Line: 0, File: 0 "a.c"
3978         \DWMACROstartfile, 1, 1     ! #include Line: 1, File: 1 "a.h"
3979         \DWMACROdefine, 1, "LONGER\_MACRO 1"
3980                                       ! #define Line: 1, String: "LONGER\_MACRO 1"
3981         \DWMACROdefine, 2, "B 2"     ! #define Line: 2, String: "B 2"
3982         \DWMACROstartfile, 3, 2     ! #include Line: 3, File: 2 "b.h"
3983         \DWMACROundef, 1, "B"        ! #undef Line: 1, String: "b"
3984         \DWMACROdefine 2, "D 3"      ! #define Line: 2, String: "D 3"
3985         \DWMACROdefine, 3, "FUNCTION\_LIKE\_MACRO(x) 4+x"
3986                                       ! #define Line: 3,
3987                                       !   String: "FUNCTION\_LIKE\_MACRO(x) 4+x"
3988         \DWMACROendfile{}             ! End "b.h" -> back to "a.h"
3989         \DWMACROdefine, 4, "B 3"     ! #define Line: 4, String: "B 3"
3990         \DWMACROendfile{}             ! End "a.h" -> back to "a.c"
3991         \DWMACROdefine, 2, "FUNCTION\_LIKE\_MACRO(x) 4+x"
3992                                       ! #define Line: 2,
3993                                       !   String: "FUNCTION\_LIKE\_MACRO(x) 4+x"
3994         \DWMACROstartfile, 3, 2     ! #include Line: 3, File: 2 "b.h"
3995         \DWMACROundef, 1, "B"        ! #undef Line: 1, String: "b"
3996         \DWMACROdefine, 2, "D 3"     ! #define Line: 2, String: "D 3"
3997         \DWMACROdefine, 3, "FUNCTION\_LIKE\_MACRO(x) 4+x"
3998                                       ! #define Line: 3,
3999                                       !   String: "FUNCTION\_LIKE\_MACRO(x) 4+x"
4000         \DWMACROendfile{}             ! End "b.h" -> back to "a.c"
4001         \DWMACROendfile{}             ! End "a.c" -> back to ""
4002         0                             ! End macro unit
4003 \end{alltt}
4004 \end{dwflisting}
4005 \caption{Macro example: simple DWARF encoding}
4006 \label{fig:macroexamplesimpledwarfencoding}
4007 \end{figure}
4008
4009
4010 \begin{figure}
4011 \begin{dwflisting}
4012 \begin{alltt}
4013 ! *** Section \dotdebugmacro{} contents
4014 ! Macro unit for "a.c"
4015 0$h:    Version:        5
4016         Flags:          2
4017             \HFNoffsetsizeflag: 0           ! 4-byte offsets
4018             \HFNdebuglineoffsetflag: 1     ! Line number offset present
4019             \HFNopcodeoperandstableflag: 0 ! No extensions
4020         Offset in \dotdebugline{} section: 0  ! Line number offset
4021 0$m:    \DWMACROstartfile, 0, 0     ! Implicit Line: 0, File: 0 "a.c"
4022         \DWMACROstartfile, 1, 1     ! #include Line: 1, File: 1 "a.h"
4023         \DWMACROimport, i$1h         ! Import unit at i$1h (lines 1-2)
4024         \DWMACROstartfile, 3, 2     ! #include Line: 3, File: 2 "b.h"
4025         \DWMACROimport, i$2h         ! Import unit i$2h (lines all)
4026         \DWMACROendfile{}             ! End "b.h" -> back to "a.h"
4027         \DWMACROdefine, 4, "B 3"     ! #define Line: 4, String: "B 3"
4028         \DWMACROendfile{}             ! End "a.h" -> back to "a.c"
4029         \DWMACROdefine, 2, s$1       ! #define Line: 3,
4030                                       !   String: "FUNCTION\_LIKE\_MACRO(x) 4+x"
4031         \DWMACROstartfile, 3, 2     ! #include Line: 3, File: 2 "b.h"
4032         \DWMACROimport, i$2h         ! Import unit i$2h (lines all)
4033         \DWMACROendfile{}             ! End "b.h" -> back to "a.c"
4034         \DWMACROendfile{}             ! End "a.c" -> back to ""
4035         0                             ! End macro unit
4036 ! Macro unit for "a.h" lines 1-2
4037 i$1h:   Version:        5
4038         Flags:          0
4039             \HFNoffsetsizeflag: 0           ! 4-byte offsets
4040             \HFNdebuglineoffsetflag: 0     ! No line number offset
4041             \HFNopcodeoperandstableflag: 0 ! No extensions
4042 i$1m:   \DWMACROdefinestrp, 1, s$2  ! #define Line: 1, String: "LONGER\_MACRO 1"
4043         \DWMACROdefine, 2, "B 2"     ! #define Line: 2, String: "B 2"
4044         0                             ! End macro unit
4045 ! Macro unit for "b.h"
4046 i$2h:   Version:        5
4047         Flags:          0
4048             \HFNoffsetsizeflag: 0           ! 4-byte offsets
4049             \HFNdebuglineoffsetflag: 0     ! No line number offset
4050             \HFNopcodeoperandstableflag: 0 ! No extensions
4051 i$2m:   \DWMACROundef, 1, "B"        ! #undef Line: 1, String: "B"
4052         \DWMACROdefine, 2, "D 3"     ! #define Line: 2, String: "D 3"
4053         \DWMACROdefinestrp, 3, s$1  ! #define Line: 3,
4054                                       !   String: "FUNCTION\_LIKE\_MACRO(x) 4+x"
4055         0                             ! End macro unit
4056 ! *** Section \dotdebugstr{} contents
4057 s$1:    String: "FUNCTION\_LIKE\_MACRO(x) 4+x"
4058 s$2:    String: "LONGER\_MACRO 1"
4059 \end{alltt}
4060 \end{dwflisting}
4061 \caption{Macro example: sharable DWARF encoding}
4062 \label{fig:macroexampledsharablewarfencoding}
4063 \end{figure}
4064
4065 \needlines{4}
4066 A number of observations are worth mentioning:
4067 \begin{itemize}
4068 \item
4069 Strings that are the same size as a reference or less are
4070 better represented as immediate operands. Strings longer
4071 than twice the size of a reference are better stored in the
4072 string table if there are at least two references.
4073
4074 \item
4075 There is a trade-off between the size of the macro information
4076 of a file and the number of times it is included when evaluating
4077 whether to create a separate macro unit. However, the amount
4078 of overhead (the size of a macro header) needed to represent a
4079 unit as well as the size of the operation to import a macro unit
4080 are both small.
4081
4082 \item
4083 A macro unit need not describe all of the macro information in
4084 a file. For example, in Figure \ref{fig:macroexampledsharablewarfencoding}
4085 the second macro unit (beginning at \texttt{i\$1h}) includes macros
4086 from just the first two lines of file \texttt{a.h}.
4087
4088 \item
4089 An implementation may be able to share macro units across object
4090 files (not shown in this example). To support this, it may be
4091 advantageous to create macro units in cases where they do not
4092 offer an advantage in a single compilation of itself.
4093
4094 \needlines{6}
4095 \item
4096 The header of a macro unit that contains a \DWMACROstartfile{}
4097 operation must include a reference to the compilation line number
4098 header to allow interpretation of the file number operands in
4099 those commands. However, the presence of those offsets complicates
4100 or may preclude sharing across compilations.
4101
4102 \end{itemize}