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