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