1 \chapter{Examples (Informative)}
2 \label{app:examplesinformative}
4 The following sections provide examples that illustrate
5 various aspects of the DWARF debugging information format.
8 \section{General Description Examples}
9 \label{app:generaldescriptionexamples}
12 \subsection{Compilation Units and Abbreviations Table Example}
13 \label{app:compilationunitsandabbreviationstableexample}
15 Figure \refersec{fig:compilationunitsandabbreviationstable}
16 depicts the relationship of the abbreviations tables contained
17 \addtoindexx{abbreviations table!example}
18 \addtoindexx{\texttt{.debug\_abbrev}!example}
19 \addtoindexx{\texttt{.debug\_info}!example}
20 in the \dotdebugabbrev{}
21 section to the information contained in
23 section. Values are given in symbolic form,
26 The figure corresponds to the following two trivial source files:
29 \begin{lstlisting}[numbers=none]
30 typedef char* POINTER;
33 \begin{lstlisting}[numbers=none]
37 % Ensures we get the following float out before we go on.
41 %\setlength{\linewidth}{1.1\linewidth}
42 \begin{minipage}[t]{0.03\linewidth}
45 % Note: alltt is used to step down the needed number of lines to the labels
76 \begin{minipage}[t]{0.38\linewidth}
78 Compilation Unit \#1: \dotdebuginfo{}
84 \textit{a1 (abbreviations table offset)}
90 "Best Compiler Corp, V1.3"
106 \textit{e1 (debug info offset)}
111 \textit{e2 (debug info offset)}
119 Compilation Unit \#2: \dotdebuginfo{}
125 \textit{a1 (abbreviations table offset)}
134 \textit{e2 (debug info offset)}
144 % Place the label for the abbreviation table
145 \begin{minipage}[t]{0.03\linewidth}
148 % Note: alltt is used to step down the needed number of lines to the label
159 \begin{minipage}[t]{0.41\linewidth}
161 Abbreviation Table: \dotdebugabbrev{}
164 \begin{alltt}\vspace{0.06cm}
168 \DWATname \DWFORMstring
169 \DWATproducer \DWFORMstring
170 \DWATcompdir \DWFORMstring
171 \DWATlanguage \DWFORMdataone
172 \DWATlowpc \DWFORMaddr
173 \DWAThighpc \DWFORMdataone
174 \DWATstmtlist \DWFORMindirect
181 \DWATname \DWFORMstring
182 \DWATencoding \DWFORMdataone
183 \DWATbytesize \DWFORMdataone
190 \DWATtype \DWFORMreffour
197 \DWATname \DWFORMstring
198 \DWATtype \DWFORMrefaddr
208 \caption{Compilation units and abbreviations table} \label{fig:compilationunitsandabbreviationstable}
211 % Ensures we get the above float out before we go on.
214 \subsection{DWARF Stack Operation Examples}
215 \label{app:dwarfstackoperationexamples}
217 \addtoindexx{DWARF expression!examples}
218 stack operations defined in
219 Section \refersec{chap:stackoperations}.
220 are fairly conventional, but the following
221 examples illustrate their behavior graphically.}
223 \begin{longtable}[c]{rrcrr}
224 \multicolumn{2}{c}{Before} & Operation & \multicolumn{2}{c}{After} \\
228 0& 17& \DWOPdup{} &0 &17 \\*
230 2& 1000 & & 2 & 29\\*
234 0 & 17 & \DWOPdrop{} & 0 & 29 \\*
235 1 &29 & & 1 & 1000 \\*
239 0 & 17 & \DWOPpick, 2 & 0 & 1000 \\*
245 0&17& \DWOPover&0&29 \\*
251 0&17& \DWOPswap{} &0&29 \\*
256 0&17&\DWOProt{} & 0 &29 \\*
257 1&29 & & 1 & 1000 \\*
258 2& 1000 & & 2 & 17 \\
261 \subsection{DWARF Location Description Examples}
262 \label{app:dwarflocationdescriptionexamples}
264 Following are examples of DWARF operations used to form location descriptions:
266 \newcommand{\descriptionitemnl}[1]
267 {\vspace{0.5\baselineskip}\item[#1]\mbox{}\\\vspace{0.5\baselineskip}}
269 \descriptionitemnl{\DWOPregthree}
270 The value is in register 3.
272 \descriptionitemnl{\DWOPregx{} 54}
273 The value is in register 54.
275 \descriptionitemnl{\DWOPaddr{} 0x80d0045c}
276 The value of a static variable is at machine address 0x80d0045c.
278 \descriptionitemnl{\DWOPbregeleven{} 44}
279 Add 44 to the value in register 11 to get the address of an automatic
283 \descriptionitemnl{\DWOPfbreg{} -50}
284 Given a \DWATframebase{} value of
285 \doublequote{\DWOPbregthirtyone{} 64,} this example
286 computes the address of a local variable that is -50 bytes from a
287 logical frame pointer that is computed by adding 64 to the current
288 stack pointer (register 31).
290 \descriptionitemnl{\DWOPbregx{} 54 32 \DWOPderef}
291 A call-by-reference parameter whose address is in the word 32 bytes
292 from where register 54 points.
294 \descriptionitemnl{\DWOPplusuconst{} 4}
295 A structure member is four bytes from the start of the structure
296 instance. The base address is assumed to be already on the stack.
298 \descriptionitemnl{\DWOPregthree{} \DWOPpiece{} 4 \DWOPregten{} \DWOPpiece{} 2}
299 A variable whose first four bytes reside in register 3 and whose next
300 two bytes reside in register 10.
303 \descriptionitemnl{\DWOPregzero{} \DWOPpiece{} 4 \DWOPpiece{} 4 \DWOPfbreg{} -12 \DWOPpiece{} 4}
304 \vspace{-2\parsep}A twelve byte value whose first four bytes reside in register zero,
305 whose middle four bytes are unavailable (perhaps due to optimization),
306 and whose last four bytes are in memory, 12 bytes before the frame
309 \descriptionitemnl{\DWOPbregone{} 0 \DWOPbregtwo{} 0 \DWOPplus{} \DWOPstackvalue{} }
310 Add the contents of r1 and r2 to compute a value. This value is the
311 \doublequote{contents} of an otherwise anonymous location.
314 \descriptionitemnl{\DWOPlitone{} \DWOPstackvalue{} \DWOPpiece{} 4 \DWOPbregthree{} 0 \DWOPbregfour{} 0}
315 \vspace{-3\parsep}\descriptionitemnl{
316 \hspace{0.5cm}\DWOPplus{} \DWOPstackvalue{} \DWOPpiece{} 4 }
317 The object value is found in an anonymous (virtual) location whose
318 value consists of two parts, given in memory address order: the 4 byte
319 value 1 followed by the four byte value computed from the sum of the
320 contents of r3 and r4.
322 \descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregone{} \DWOPstackvalue }
323 The value register 1 had upon entering the current subprogram.
325 \descriptionitemnl{\DWOPentryvalue{} 2 \DWOPbregone{} 0 \DWOPstackvalue }
326 The value register 1 had upon entering the current subprogram (same as the previous example).
327 %Both of these location descriptions evaluate to the value register 1 had upon
328 %entering the current subprogram.
330 %FIXME: The following gets an undefined control sequence error for reasons unknown...
331 %\descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregthirtyone{} \DWOPregone{} \DWOPadd{} \DWOPstackvalue }
332 %The value register 31 had upon entering the current subprogram
333 %plus the value register 1 currently has.
335 \descriptionitemnl{\DWOPentryvalue{} 3 \DWOPbregfour{} 16 \DWOPderef{} \DWOPstackvalue }
336 %FIXME: similar undefined as just above
337 %\descriptionitemnl{\DWOPentryvalue{} 6 \DWOPentryvalue{} 1 \DWOPregfour{} \DWOPplusuconst{} 16 \DWOPderef{} \DWOPstackvalue }
338 %These two location expressions do the same thing, p
339 Add 16 to the value register 4 had upon entering the current subprogram
340 to form an address and then push the value of the memory location at that address.
345 \section{Aggregate Examples}
346 \label{app:aggregateexamples}
348 The following examples illustrate how to represent some of
349 the more complicated forms of array and record aggregates
352 \subsection{Fortran Simple Array Example}
353 \label{app:fortranarrayexample}
354 Consider the \addtoindex{Fortran array}\addtoindexx{Fortran 90} source fragment in
355 \addtoindexx{array type entry!examples}
356 Figure \referfol{fig:fortranarrayexamplesourcefragment}.
362 real, dimension (:), pointer :: ap
364 type(array_ptr), allocatable, dimension(:) :: arrayvar
365 allocate(arrayvar(20))
367 allocate(arrayvar(i)%ap(i+10))
370 \caption{Fortran array example: source fragment}
371 \label{fig:fortranarrayexamplesourcefragment}
374 For allocatable and pointer arrays, it is essentially required
375 by the \addtoindex{Fortran array} semantics that each array consist of
376 \addtoindexx{descriptor!array}
378 \addtoindexx{array!descriptor for}
379 parts, which we here call 1) the descriptor and 2) the raw
380 data. (A descriptor has often been called a dope vector in
381 other contexts, although it is often a structure of some kind
382 rather than a simple vector.) Because there are two parts,
383 and because the lifetime of the descriptor is necessarily
384 longer than and includes that of the raw data, there must be
385 an address somewhere in the descriptor that points to the
386 raw data when, in fact, there is some (that is, when
387 the \doublequote{variable} is allocated or associated).
389 For concreteness, suppose that a descriptor looks something
390 like the C structure in
391 Figure \refersec{fig:fortranarrayexampledescriptorrepresentation}.
392 Note, however, that it is
393 a property of the design that 1) a debugger needs no builtin
394 knowledge of this structure and 2) there does not need to
395 be an explicit representation of this structure in the DWARF
396 input to the debugger.
401 long el_len; // Element length
402 void * base; // Address of raw data
403 int ptr_assoc : 1; // Pointer is associated flag
404 int ptr_alloc : 1; // Pointer is allocated flag
405 int num_dims : 6; // Number of dimensions
406 struct dims_str { // For each dimension...
413 \caption{Fortran array example: descriptor representation}
414 \label{fig:fortranarrayexampledescriptorrepresentation}
418 In practice, of course, a \doublequote{real} descriptor will have
419 dimension substructures only for as many dimensions as are
420 specified in the \texttt{num\_dims} component. Let us use the notation
421 \texttt{desc\textless n\textgreater}
422 to indicate a specialization of the \texttt{desc} struct in
423 which \texttt{n} is the bound for the \texttt{dims} component as well as the
424 contents of the \texttt{num\_dims} component.
426 Because the arrays considered here come in two parts, it is
427 necessary to distinguish the parts carefully. In particular,
428 the \doublequote{address of the variable} or equivalently, the \doublequote{base
429 address of the object} \emph{always} refers to the descriptor. For
430 arrays that do not come in two parts, an implementation can
431 provide a descriptor anyway, thereby giving it two parts. (This
432 may be convenient for general runtime support unrelated to
433 debugging.) In this case the above vocabulary applies as
434 stated. Alternatively, an implementation can do without a
435 descriptor, in which case the \doublequote{address of the variable,}
436 or equivalently the \doublequote{base address of the object}, refers
437 to the \doublequote{raw data} (the real data, the only thing around
438 that can be the object).
440 If an object has a descriptor, then the DWARF type for that
443 attribute. If an object
444 does not have a descriptor, then usually the DWARF type for the
445 object will not have a
448 \addtoindex{Ada} example for a case where the type for an object without
449 a descriptor does have a
450 \DWATdatalocation{} attribute. In
451 that case the object doubles as its own descriptor.)
453 The \addtoindex{Fortran} derived type \texttt{array\_ptr} can now be redescribed
454 in C\dash like terms that expose some of the representation as in
456 \begin{lstlisting}[numbers=none]
463 Similarly for variable \texttt{arrayvar}:
464 \begin{lstlisting}[numbers=none]
468 (Recall that \texttt{desc\textless 1\textgreater}
469 indicates the 1\dash dimensional version of \texttt{desc}.)
472 Finally, the following notation is useful:
473 \begin{enumerate}[1. ]
474 \item sizeof(type): size in bytes of entities of the given type
475 \item offset(type, comp): offset in bytes of the comp component
476 within an entity of the given type
479 The DWARF description is shown
480 \addtoindexx{Fortran 90}
481 in Figure \refersec{fig:fortranarrayexampledwarfdescription}.
487 ! Description for type of 'ap'
490 ! No name, default (Fortran) ordering, default stride
491 \DWATtype(reference to REAL)
492 \DWATassociated(expression= ! Test 'ptr\_assoc' \nolink{flag}
493 \DWOPpushobjectaddress
494 \DWOPlitn ! where n == offset(ptr\_assoc)
497 \DWOPlitone ! mask for 'ptr\_assoc' \nolink{flag}
499 \DWATdatalocation(expression= ! Get raw data address
500 \DWOPpushobjectaddress
501 \DWOPlitn ! where n == offset(base)
503 \DWOPderef) ! Type of index of array 'ap'
504 2\$: \DWTAGsubrangetype
505 ! No name, default stride
506 \DWATtype(reference to INTEGER)
507 \DWATlowerbound(expression=
508 \DWOPpushobjectaddress
509 \DWOPlitn ! where n ==
510 ! offset(desc, dims) +
511 ! offset(dims\_str, lower\_bound)
514 \DWATupperbound(expression=
515 \DWOPpushobjectaddress
516 \DWOPlitn ! where n ==
517 ! offset(desc, dims) +
518 ! offset(dims\_str, upper\_bound)
521 ! Note: for the m'th dimension, the second operator becomes
523 ! n == offset(desc, dims) +
524 ! (m-1)*sizeof(dims\_str) +
525 ! offset(dims\_str, [lower|upper]\_bound)
526 ! That is, the expression does not get longer for each successive
527 ! dimension (other than to express the larger offsets involved).
530 \caption{Fortran array example: DWARF description}
531 \label{fig:fortranarrayexampledwarfdescription}
538 3\$: \DWTAGstructuretype
539 \DWATname("array\_ptr")
540 \DWATbytesize(constant sizeof(REAL) + sizeof(desc<1>))
543 \DWATtype(reference to REAL)
544 \DWATdatamemberlocation(constant 0)
547 \DWATtype(reference to 1\$)
548 \DWATdatamemberlocation(constant sizeof(REAL))
550 ! No name, default (Fortran) ordering, default stride
551 \DWATtype(reference to 3\$)
552 \DWATallocated(expression= ! Test 'ptr\_alloc' \nolink{flag}
553 \DWOPpushobjectaddress
554 \DWOPlitn ! where n == offset(ptr\_alloc)
557 \DWOPlittwo ! Mask for 'ptr\_alloc' \nolink{flag}
559 \DWATdatalocation(expression= ! Get raw data address
560 \DWOPpushobjectaddress
561 \DWOPlitn ! where n == offset(base)
564 7\$: \DWTAGsubrangetype
565 ! No name, default stride
566 \DWATtype(reference to INTEGER)
567 \DWATlowerbound(expression=
568 \DWOPpushobjectaddress
569 \DWOPlitn ! where n == ...
572 \DWATupperbound(expression=
573 \DWOPpushobjectaddress
574 \DWOPlitn ! where n == ...
578 \DWATname("arrayvar")
579 \DWATtype(reference to 6\$)
580 \DWATlocation(expression=
581 ...as appropriate...) ! Assume static allocation
586 Figure~\ref{fig:fortranarrayexampledwarfdescription}: Fortran array example: DWARF description \textit{(concluded)}
591 \addtoindexx{Fortran array example}
592 the program is stopped immediately following completion
593 of the do loop. Suppose further that the user enters the
594 following debug command:
596 \begin{lstlisting}[numbers=none]
597 debug> print arrayvar(5)%ap(2)
600 Interpretation of this expression proceeds as follows:
601 \begin{enumerate}[1. ]
603 \item Lookup name \texttt{arrayvar}. We find that it is a variable,
604 whose type is given by the unnamed type at 6\$. Notice that
605 the type is an array type.
608 \item Find the 5$^{th}$ element of that array object. To do array
609 indexing requires several pieces of information:
610 \begin{enumerate}[a) ]
612 \item the address of the array data
614 \item the lower bounds of the array \\
615 % Using plain [] here gives trouble.
616 \lbrack To check that 5 is within bounds would require the upper
617 bound too, but we will skip that for this example. \rbrack
624 \DWATdatalocation{} attribute.
625 Since there is one, go execute the expression, whose result is
626 the address needed. The object address used in this case
627 is the object we are working on, namely the variable named
628 \texttt{arrayvar}, whose address was found in step 1. (Had there been
629 no \DWATdatalocation{} attribute, the desired address would
630 be the same as the address from step 1.)
632 For b), for each dimension of the array (only one
633 in this case), go interpret the usual lower bound
634 attribute. Again this is an expression, which again begins
635 with \DWOPpushobjectaddress. This object is
636 \textbf{still} \texttt{arrayvar},
637 from step 1, because we have not begun to actually perform
640 For c), the default stride applies. Since there is no
641 \DWATbytestride{} attribute, use the size of the array element
642 type, which is the size of type \texttt{array\_ptr} (at 3\$).
646 Having acquired all the necessary data, perform the indexing
647 operation in the usual manner--which has nothing to do with
648 any of the attributes involved up to now. Those just provide
649 the actual values used in the indexing step.
651 The result is an object within the memory that was dynamically
652 allocated for \texttt{arrayvar}.
654 \item Find the \texttt{ap} component of the object just identified,
655 whose type is \texttt{array\_ptr}.
657 This is a conventional record component lookup and
658 interpretation. It happens that the \texttt{ap} component in this case
659 begins at offset 4 from the beginning of the containing object.
660 Component \texttt{ap} has the unnamed array type defined at 1\$ in the
663 \item Find the second element of the array object found in step 3. To do array indexing requires
664 several pieces of information:
665 \begin{enumerate}[a) ]
666 \item the address of the array storage
668 \item the lower bounds of the array \\
669 % Using plain [] here gives trouble.
670 \lbrack To check that 2 is within bounds we would require the upper
671 bound too, but we will skip that for this example \rbrack
678 This is just like step 2), so the details are omitted. Recall
679 that because the DWARF type 1\$ has a \DWATdatalocation,
680 the address that results from step 4) is that of a
681 descriptor, and that address is the address pushed by the
682 \DWOPpushobjectaddress{} operations in 1\$ and 2\$.
684 Note: we happen to be accessing a pointer array here instead
685 of an allocatable array; but because there is a common
686 underlying representation, the mechanics are the same. There
687 could be completely different descriptor arrangements and the
688 mechanics would still be the same---only the stack machines
692 \subsection{Fortran Coarray Examples}
693 \label{app:Fortrancoarrayexamples}
695 \subsubsection{Fortran Scalar Coarray Example}
696 The \addtoindex{Fortran} scalar coarray example
697 \addtoindexx{coarray!example}\addtoindexx{scalar coarray|see{coarray}}
698 in Figure \refersec{fig:Fortranscalarcoarraysourcefragment} can be described as
699 illustrated in Figure \refersec{fig:FortranscalarcoarrayDWARFdescription}.
705 \caption{Fortran scalar coarray: source fragment}
706 \label{fig:Fortranscalarcoarraysourcefragment}
712 10\$: \DWTAGcoarraytype
713 \DWATtype(reference to INTEGER)
714 \DWTAGsubrangetype ! Note omitted upper bound
715 \DWATlowerbound(constant 1)
719 \DWATtype(reference to coarray type at 10\$)
722 \caption{Fortran scalar coarray: DWARF description}
723 \label{fig:FortranscalarcoarrayDWARFdescription}
726 \subsubsection{Fortran Array Coarray Example}
727 The \addtoindex{Fortran} (simple) array coarray example
728 \addtoindexx{coarray!example}\addtoindexx{array coarray|see{coarray}}
729 in Figure \refersec{fig:Fortranarraycoarraysourcefragment} can be described as
730 illustrated in Figure \refersec{fig:FortranarraycoarrayDWARFdescription}.
736 \caption{Fortran array coarray: source fragment}
737 \label{fig:Fortranarraycoarraysourcefragment}
743 10\$: \DWTAGarraytype
744 \DWATordering(\DWORDcolmajor)
745 \DWATtype(reference to INTEGER)
746 11\$: \DWTAGsubrangetype
747 \DWATlowerbound(constant 1)
748 \DWATupperbound(constant 10)
750 12\$: \DWTAGcoarraytype
751 \DWATtype(reference to array type at 10\$)
752 13\$: \DWTAGsubrangetype ! Note omitted upper bound
753 \DWATlowerbound(constant 1)
757 \DWATtype(reference to coarray type at 12\$)
760 \caption{Fortran array coarray: DWARF description}
761 \label{fig:FortranarraycoarrayDWARFdescription}
765 \subsubsection{Fortran Multidimensional Coarray Example}
766 The \addtoindex{Fortran} multidimensional coarray of a multidimensional array example
767 \addtoindexx{coarray!example}\addtoindexx{array coarray|see{coarray}}
768 in Figure \refersec{fig:Fortranmultidimensionalcoarraysourcefragment} can be described as
769 illustrated in Figure \referfol{fig:FortranmultidimensionalcoarrayDWARFdescription}.
773 INTEGER X(10,11,12)[2,3,*]
775 \caption{Fortran multidimensional coarray: source fragment}
776 \label{fig:Fortranmultidimensionalcoarraysourcefragment}
782 10\$: \DWTAGarraytype
783 \DWATordering(\DWORDcolmajor)
784 \DWATtype(reference to INTEGER)
785 11\$: \DWTAGsubrangetype
786 \DWATlowerbound(constant 1)
787 \DWATupperbound(constant 10)
788 12\$: \DWTAGsubrangetype
789 \DWATlowerbound(constant 1)
790 \DWATupperbound(constant 11)
791 13\$: \DWTAGsubrangetype
792 \DWATlowerbound(constant 1)
793 \DWATupperbound(constant 12)
795 14\$: \DWTAGcoarraytype
796 \DWATtype(reference to array_type at 10\$)
797 15\$: \DWTAGsubrangetype
798 \DWATlowerbound(constant 1)
799 \DWATupperbound(constant 2)
800 16\$: \DWTAGsubrangetype
801 \DWATlowerbound(constant 1)
802 \DWATupperbound(constant 3)
803 17\$: \DWTAGsubrangetype ! Note omitted upper bound
804 \DWATlowerbound(constant 1)
808 \DWATtype(reference to coarray type at 14\$)
811 \caption{Fortran multidimensional coarray: DWARF description}
812 \label{fig:FortranmultidimensionalcoarrayDWARFdescription}
817 \subsection{Fortran 2008 Assumed-rank Array Example}
818 \label{app:assumedrankexample}
819 \addtoindexx{array!assumed-rank}
820 Consider the example in Figure~\ref{fig:assumedrankdecl}, which shows
821 an assumed-rank array in Fortran~2008 with
822 supplement~29113:\footnote{Technical Specification ISO/IEC TS
823 29113:2012 \emph{Further Interoperability of Fortran with C}}
834 \caption{Declaration of a Fortran 2008 assumed-rank array}
835 \label{fig:assumedrankdecl}
838 Let's assume the Fortran compiler used an array descriptor that
839 (in \addtoindex{C}) looks
840 like the one shown in Figure~\ref{fig:arraydesc}.
844 struct array_descriptor {
857 \caption{One of many possible layouts for an array descriptor}
858 \label{fig:arraydesc}
861 The DWARF type for the array \emph{x} can be described as shown in
862 Figure~\refersec{fig:assumedrankdwarf}.
867 10\$: \DWTAGarraytype
868 \DWATtype(reference to real)
869 \DWATrank(expression=
870 \DWOPpushobjectaddress
871 \DWOPlitn ! offset of rank in descriptor
874 \DWATdatalocation(expression=
875 \DWOPpushobjectaddress
876 \DWOPlitn ! offset of data in descriptor
879 11\$: \DWTAGgenericsubrange
880 \DWATtype(reference to integer)
881 \DWATlowerbound(expression=
882 ! Looks up the lower bound of dimension i.
883 ! Operation ! Stack effect
885 \DWOPlitn ! i sizeof(dim)
887 \DWOPlitn ! dim[i] offsetof(dim)
888 \DWOPplus ! dim[i]+offset
889 \DWOPpushobjectaddress ! dim[i]+offsetof(dim) objptr
890 \DWOPplus ! objptr.dim[i]
891 \DWOPlitn ! objptr.dim[i] offsetof(lb)
892 \DWOPplus ! objptr.dim[i].lowerbound
893 \DWOPderef) ! *objptr.dim[i].lowerbound
894 \DWATupperbound(expression=
895 ! Looks up the upper bound of dimension i.
896 \DWOPlitn ! sizeof(dim)
898 \DWOPlitn ! offsetof(dim)
900 \DWOPpushobjectaddress
902 \DWOPlitn ! offset of upperbound in dim
905 \DWATbytestride(expression=
906 ! Looks up the byte stride of dimension i.
908 ! (analogous to \DWATupperboundNAME)
912 \caption{Sample DWARF for the array descriptor in Figure~\ref{fig:arraydesc}}
913 \label{fig:assumedrankdwarf}
916 The layout of the array descriptor is not specified by the Fortran
917 standard unless the array is explicitly marked as \addtoindex{C-interoperable}. To
918 get the bounds of an assumed-rank array, the expressions in the
919 \DWTAGgenericsubrange{}
920 entry need to be evaluated for each of the
921 \DWATrank{} dimensions as shown by the pseudocode in
922 Figure~\refersec{fig:assumedrankdwarfparser}.
927 int lower, upper, stride;
935 array_t get_dynamic_array_dims(DW_TAG_array a) {
938 // Evaluate the DW_AT_rank expression to get the
939 // number of dimensions.
941 dwarf_eval(stack, a.rank_expr);
942 result.rank = dwarf_pop(stack);
943 result.dims = new dims_t[rank];
945 // Iterate over all dimensions and find their bounds.
946 for (int i = 0; i < result.rank; i++) {
947 // Evaluate the generic subrange's DW_AT_lower
948 // expression for dimension i.
949 dwarf_push(stack, i);
950 assert( stack.size == 1 );
951 dwarf_eval(stack, a.generic_subrange.lower_expr);
952 result.dims[i].lower = dwarf_pop(stack);
953 assert( stack.size == 0 );
955 dwarf_push(stack, i);
956 dwarf_eval(stack, a.generic_subrange.upper_expr);
957 result.dims[i].upper = dwarf_pop(stack);
959 dwarf_push(stack, i);
960 dwarf_eval(stack, a.generic_subrange.byte_stride_expr);
961 result.dims[i].stride = dwarf_pop(stack);
966 \caption{How to interpret the DWARF from Figure~\ref{fig:assumedrankdwarf}}
967 \label{fig:assumedrankdwarfparser}
972 \subsection{Fortran Dynamic Type Example}
973 \label{app:fortrandynamictypeexample}
974 Consider the \addtoindex{Fortran 90} example of dynamic properties in
975 Figure \refersec{fig:fortrandynamictypeexamplesource}.
976 This can be represented in DWARF as illustrated in
977 Figure \refersec{fig:fortrandynamictypeexampledwarfdescription}.
978 Note that unnamed dynamic types are used to avoid replicating
979 the full description of the underlying type \texttt{dt} that is shared by
996 type (dt(n)), pointer :: t2
997 type (dt(n)), allocatable :: t3, t4
1002 \caption{Fortran dynamic type example: source}
1003 \label{fig:fortrandynamictypeexamplesource}
1009 11$: \DWTAGstructuretype
1015 13$: \DWTAGdynamictype ! plain version
1016 \DWATdatalocation (dwarf expression to locate raw data)
1019 14$: \DWTAGdynamictype ! 'pointer' version
1020 \DWATdatalocation (dwarf expression to locate raw data)
1021 \DWATassociated (dwarf expression to test if associated)
1024 15$: \DWTAGdynamictype ! 'allocatable' version
1025 \DWATdatalocation (dwarf expression to locate raw data)
1026 \DWATallocated (dwarf expression to test is allocated)
1032 \DWATlocation (dwarf expression to locate descriptor)
1036 \DWATlocation (dwarf expression to locate descriptor)
1040 \DWATlocation (dwarf expression to locate descriptor)
1044 \DWATlocation (dwarf expression to locate descriptor)
1047 \caption{Fortran dynamic type example: DWARF description}
1048 \label{fig:fortrandynamictypeexampledwarfdescription}
1052 \subsection{C/C++ Anonymous Structure Example}
1053 \label{app:ccxxanonymousstructureexample}
1054 \addtoindexx{anonymous structure}
1055 An example of a \addtoindex{C}/\addtoindex{C++} structure is shown in
1056 Figure \ref{fig:anonymousstructureexamplesourcefragment}.
1057 For this source, the DWARF description in
1058 Figure \ref{fig:anonymousstructureexampledwarfdescription}
1059 is appropriate. In this example, \texttt{b} is referenced as if it
1060 were defined in the enclosing structure \texttt{foo}.
1079 \caption{Anonymous structure example: source fragment}
1080 \label{fig:anonymousstructureexamplesourcefragment}
1086 1$: \DWTAGstructuretype
1090 3$: \DWTAGstructuretype
1096 \caption{Anonymous structure example: DWARF description}
1097 \label{fig:anonymousstructureexampledwarfdescription}
1100 \subsection{Ada Example}
1101 \label{app:adaexample}
1102 Figure \refersec{fig:adaexamplesourcefragment}
1103 illustrates two kinds of \addtoindex{Ada}
1104 parameterized array, one embedded in a record.
1108 M : INTEGER := <exp>;
1109 VEC1 : array (1..M) of INTEGER;
1110 subtype TEENY is INTEGER range 1..100;
1111 type ARR is array (INTEGER range <>) of INTEGER;
1112 type REC2(N : TEENY := 100) is record
1118 \caption{Ada example: source fragment}
1119 \label{fig:adaexamplesourcefragment}
1122 \texttt{VEC1} illustrates an (unnamed) array type where the upper bound
1123 of the first and only dimension is determined at runtime.
1125 semantics require that the value of an array bound is fixed at
1126 the time the array type is elaborated (where \textit{elaboration} refers
1127 to the runtime executable aspects of type processing). For
1128 the purposes of this example, we assume that there are no
1129 other assignments to \texttt{M} so that it safe for the \texttt{REC1} type
1130 description to refer directly to that variable (rather than
1131 a compiler-generated copy).
1133 \texttt{REC2} illustrates another array type (the unnamed type of
1134 component \texttt{VEC2}) where the upper bound of the first and only
1135 bound is also determined at runtime. In this case, the upper
1136 bound is contained in a discriminant of the containing record
1137 type. (A \textit{discriminant} is a component of a record whose value
1138 cannot be changed independently of the rest of the record
1139 because that value is potentially used in the specification
1140 of other components of the record.)
1142 The DWARF description is shown in
1143 Figure \refersec{fig:adaexampledwarfdescription}.
1146 Interesting aspects about this example are:
1147 \begin{enumerate}[1. ]
1148 \item The array \texttt{VEC2} is \doublequote{immediately} contained within structure
1149 \texttt{REC2} (there is no intermediate descriptor or indirection),
1150 which is reflected in the absence of a \DWATdatalocation{}
1151 attribute on the array type at 28\$.
1153 \item One of the bounds of \texttt{VEC2} is nonetheless dynamic and part of
1154 the same containing record. It is described as a reference to
1155 a member, and the location of the upper bound is determined
1156 as for any member. That is, the location is determined using
1157 an address calculation relative to the base of the containing
1160 A consumer must notice that the referenced bound is a
1161 member of the same containing object and implicitly push the
1162 base address of the containing object just as for accessing
1163 a data member generally.
1165 \item The lack of a subtype concept in DWARF means that DWARF types
1166 serve the role of subtypes and must replicate information from
1167 what should be the parent type. For this reason, DWARF for
1168 the unconstrained array type \texttt{ARR} is not needed for the purposes
1169 of this example and therefore is not shown.
1175 11\$: \DWTAGvariable
1177 \DWATtype(reference to INTEGER)
1178 12\$: \DWTAGarraytype
1179 ! No name, default (\addtoindex{Ada}) order, default stride
1180 \DWATtype(reference to INTEGER)
1181 13\$: \DWTAGsubrangetype
1182 \DWATtype(reference to INTEGER)
1183 \DWATlowerbound(constant 1)
1184 \DWATupperbound(reference to variable M at 11\$)
1185 14\$: \DWTAGvariable
1187 \DWATtype(reference to array type at 12\$)
1189 21\$: \DWTAGsubrangetype
1191 \DWATtype(reference to INTEGER)
1192 \DWATlowerbound(constant 1)
1193 \DWATupperbound(constant 100)
1195 26\$: \DWTAGstructuretype
1199 \DWATtype(reference to subtype TEENY at 21\$)
1200 \DWATdatamemberlocation(constant 0)
1201 28\$: \DWTAGarraytype
1202 ! No name, default (\addtoindex{Ada}) order, default stride
1203 ! Default data location
1204 \DWATtype(reference to INTEGER)
1205 29\$: \DWTAGsubrangetype
1206 \DWATtype(reference to subrange TEENY at 21\$)
1207 \DWATlowerbound(constant 1)
1208 \DWATupperbound(reference to member N at 27\$)
1211 \DWATtype(reference to array "subtype" at 28\$)
1212 \DWATdatamemberlocation(machine=
1213 \DWOPlitn ! where n == offset(REC2, VEC2)
1216 41\$: \DWTAGvariable
1218 \DWATtype(reference to REC2 at 26\$)
1219 \DWATlocation(...as appropriate...)
1222 \caption{Ada example: DWARF description}
1223 \label{fig:adaexampledwarfdescription}
1228 \subsection{Pascal Example}
1229 \label{app:pascalexample}
1230 The Pascal \addtoindexx{Pascal example} source in
1231 Figure \referfol{fig:packedrecordexamplesourcefragment}
1232 is used to illustrate the representation of packed unaligned
1233 \addtoindex{bit fields}.
1237 TYPE T : PACKED RECORD ! bit size is 2
1238 F5 : BOOLEAN; ! bit offset is 0
1239 F6 : BOOLEAN; ! bit offset is 1
1241 VAR V : PACKED RECORD
1242 F1 : BOOLEAN; ! bit offset is 0
1243 F2 : PACKED RECORD ! bit offset is 1
1244 F3 : INTEGER; ! bit offset is 0 in F2, 1 in V
1246 F4 : PACKED ARRAY [0..1] OF T; ! bit offset is 33
1247 F7 : T; ! bit offset is 37
1250 \caption{Packed record example: source fragment}
1251 \label{fig:packedrecordexamplesourcefragment}
1254 The DWARF representation in
1255 Figure \refersec{fig:packedrecordexampledwarfdescription}
1257 \DWTAGpackedtype{} entries could be added to
1258 better represent the source, but these do not otherwise affect
1259 the example and are omitted for clarity. Note that this same
1260 representation applies to both typical big\dash \ and
1262 architectures using the conventions described in
1263 Section \refersec{chap:datamemberentries}.
1269 10\$: \DWTAGbasetype
1270 \DWATname("BOOLEAN")
1272 11\$: \DWTAGbasetype
1273 \DWATname("INTEGER")
1275 20\$: \DWTAGstructuretype
1280 \DWATtype(reference to 10$)
1281 \DWATdatabitoffset(0) ! may be omitted
1285 \caption{Packed record example: DWARF description}
1286 \label{fig:packedrecordexampledwarfdescription}
1295 \DWATtype(reference to 10$)
1296 \DWATdatabitoffset(1)
1298 21\$: \DWTAGstructuretype ! anonymous type for F2
1301 \DWATtype(reference to 11\$)
1302 22\$: \DWTAGarraytype ! anonymous type for F4
1303 \DWATtype(reference to 20\$)
1305 \DWATtype(reference to 11\$)
1309 \DWATbitsize(4) \addtoindexx{bit size attribute}
1310 23\$: \DWTAGstructuretype ! anonymous type for V
1311 \DWATbitsize(39) \addtoindexx{bit size attribute}
1314 \DWATtype(reference to 10\$)
1315 \DWATdatabitoffset(0) ! may be omitted
1316 \DWATbitsize(1) ! may be omitted
1319 \DWATtype(reference to 21\$)
1320 \DWATdatabitoffset(1)
1321 \DWATbitsize(32) ! may be omitted
1324 \DWATtype(reference to 22\$)
1325 \DWATdatabitoffset(33)
1326 \DWATbitsize(4) ! may be omitted
1329 \DWATtype(reference to 20\$) ! type T
1330 \DWATdatabitoffset(37)
1331 \DWATbitsize(2) \addtoindexx{bit size attribute} ! may be omitted
1334 \DWATtype(reference to 23\$)
1341 Figure~\ref{fig:packedrecordexampledwarfdescription}: Packed record example: DWARF description \textit{(concluded)}
1346 \subsection{C/C++ Bit-Field Examples}
1347 \label{app:ccppbitfieldexamples}
1348 \textit{Bit fields\addtoindexx{bit fields} in \addtoindex{C}
1349 and \addtoindex{C++} typically require the use of the
1350 \DWATdatabitoffset{}\addtoindexx{data bit offset}
1351 and \DWATbitsize{}\addtoindexx{data bit size} attributes.}
1354 \textit{This Standard uses the following bit numbering and direction
1355 conventions in examples. These conventions are for illustrative
1356 purposes and other conventions may apply on particular
1359 \item \textit{For big\dash endian architectures, bit offsets are
1360 counted from high-order to low\dash order bits within a byte (or
1361 larger storage unit); in this case, the bit offset identifies
1362 the high\dash order bit of the object.}
1364 \item \textit{For little-endian architectures, bit offsets are
1365 counted from low\dash order to high\dash order bits within a byte (or
1366 larger storage unit); in this case, the bit offset identifies
1367 the low\dash order bit of the object.}
1370 \textit{In either case, the bit so identified is defined as the
1371 \addtoindexx{beginning of an object}
1372 beginning of the object.}
1375 This section illustrates one possible representation of the
1376 following \addtoindex{C} structure definition in both big-
1377 and little-endian \byteorder{s}:
1388 Figures \ref{fig:bigendiandatabitoffsets} and
1389 \refersec{fig:littleendiandatabitoffsets}
1390 show the structure layout
1391 and data bit offsets for example big- and little-endian
1392 architectures, respectively. Both diagrams show a structure
1393 that begins at address A and whose size is four bytes. Also,
1394 high order bits are to the left and low order bits are to
1406 Addresses increase ->
1407 | A | A + 1 | A + 2 | A + 3 |
1409 Data bit offsets increase ->
1410 +---------------+---------------+---------------+---------------+
1411 |0 4|5 10|11 15|16 23|24 31|
1412 | j | k | m | n | <pad> |
1414 +---------------------------------------------------------------+
1418 \caption{Big-endian data bit offsets}
1419 \label{fig:bigendiandatabitoffsets}
1430 <- Addresses increase
1431 | A + 3 | A + 2 | A + 1 | A |
1433 <- Data bit offsets increase
1434 +---------------+---------------+---------------+---------------+
1435 |31 24|23 16|15 11|10 5|4 0|
1436 | <pad> | n | m | k | j |
1438 +---------------------------------------------------------------+
1442 \caption{Little-endian data bit offsets}
1443 \label{fig:littleendiandatabitoffsets}
1447 Note that data member bit offsets in this example are the
1448 same for both big\dash\ and little\dash endian architectures even
1449 though the fields are allocated in different directions
1450 (high\dash order to low-order versus low\dash order to high\dash order);
1451 the bit naming conventions for memory and/or registers of
1452 the target architecture may or may not make this seem natural.
1455 \section{Namespace Examples}
1456 \label{app:namespaceexamples}
1458 The \addtoindex{C++} example in
1459 Figure \refersec{fig:namespaceexample1sourcefragment}
1461 \addtoindexx{namespace (C++)!example}
1462 to illustrate the representation of namespaces.
1463 The DWARF representation in
1464 Figure \refersec{fig:namespaceexample1dwarfdescription}
1476 float myfunc (float f) { return f - 2.0; }
1477 int myfunc2(int a) { return a + 2; }
1481 using A::B::j; // (1) using declaration
1484 using A::B::j; // (2) using declaration
1485 namespace Foo = A::B; // (3) namespace alias
1486 using Foo::myfunc; // (4) using declaration
1487 using namespace Foo; // (5) using directive
1490 using namespace Y; // (6) using directive
1494 int Foo::myfunc(int a)
1498 return myfunc2(3) + j + i + a + 2;
1501 \caption{Namespace example \#1: source fragment}
1502 \label{fig:namespaceexample1sourcefragment}
1517 6\$: \DWTAGnamespace
1518 ! no \DWATname attribute
1522 \DWATtype(reference to 1\$)
1525 10\$: \DWTAGnamespace
1527 20\$: \DWTAGnamespace
1529 30\$: \DWTAGvariable
1531 \DWATtype(reference to 1\$)
1534 34\$: \DWTAGsubprogram
1536 \DWATtype(reference to 1\$)
1538 36\$: \DWTAGsubprogram
1540 \DWATtype(reference to 2\$)
1542 38\$: \DWTAGsubprogram
1543 \DWATname("myfunc2")
1546 \DWATtype(reference to 1\$)
1550 \caption{Namespace example \#1: DWARF description}
1551 \label{fig:namespaceexample1dwarfdescription}
1558 40\$: \DWTAGnamespace
1560 \DWTAGimporteddeclaration ! (1) using-declaration
1561 \DWATimport(reference to 30\$)
1564 \DWATtype(reference to 1\$)
1567 \DWTAGimporteddeclaration ! (2) using declaration
1568 \DWATimport(reference to 30\$)
1569 \DWTAGimporteddeclaration ! (3) namespace alias
1571 \DWATimport(reference to 20\$)
1572 \DWTAGimporteddeclaration ! (4) using declaration
1573 \DWATimport(reference to 34\$) ! - part 1
1574 \DWTAGimporteddeclaration ! (4) using declaration
1575 \DWATimport(reference to 36\$) ! - part 2
1576 \DWTAGimportedmodule ! (5) using directive
1577 \DWATimport(reference to 20\$)
1579 \DWATextension(reference to 10\$)
1581 \DWATextension(reference to 20\$)
1582 \DWTAGimportedmodule ! (6) using directive
1583 \DWATimport(reference to 40\$)
1586 \DWATtype(reference to 1\$)
1589 60\$: \DWTAGsubprogram
1590 \DWATspecification(reference to 34\$)
1598 Figure~\ref{fig:namespaceexample1dwarfdescription}: Namespace example \#1: DWARF description \textit{(concluded)}
1603 As a further namespace example, consider the inlined namespace shown in
1604 Figure \refersec{fig:namespaceexample2sourcefragment}. For this source,
1605 the DWARF description in Figure \ref{fig:namespaceexample2dwarfdescription}
1606 is appropriate. In this example, \texttt{a} may be referenced either as a member of
1607 the fully qualified namespace \texttt{A::B}, or as if it were defined
1608 in the enclosing namespace, \texttt{A}.
1613 inline namespace B { // (1) inline namespace
1630 \caption{Namespace example \#2: source fragment}
1631 \label{fig:namespaceexample2sourcefragment}
1646 \caption{Namespace example \#2: DWARF description}
1647 \label{fig:namespaceexample2dwarfdescription}
1651 \section{Member Function Examples}
1652 \label{app:memberfunctionexample}
1653 \addtoindexx{member function example}
1654 Consider the member function example fragment in
1655 Figure \refersec{fig:memberfunctionexamplesourcefragment}.
1656 The DWARF representation in
1657 Figure \refersec{fig:memberfunctionexampledwarfdescription}
1666 static void func3(int x3);
1668 void A::func1(int x) {}
1670 \caption{Member function example: source fragment}
1671 \label{fig:memberfunctionexamplesourcefragment}
1682 3\$: \DWTAGclasstype
1685 4\$: \DWTAGpointertype
1686 \DWATtype(reference to 3\$)
1688 5\$: \DWTAGconsttype
1689 \DWATtype(reference to 3\$)
1691 6\$: \DWTAGpointertype
1692 \DWATtype(reference to 5\$)
1695 7\$: \DWTAGsubprogram
1698 \DWATobjectpointer(reference to 8\$) \addtoindexx{object pointer attribute}
1699 ! References a formal parameter in this
1705 \caption{Member function example: DWARF description}
1706 \label{fig:memberfunctionexampledwarfdescription}
1714 8\$: \DWTAGformalparameter
1715 \DWATartificial(true)
1717 \DWATtype(reference to 4\$)
1718 ! Makes type of 'this' as 'A*' =>
1719 ! func1 has not been marked const
1723 9\$: \DWTAGformalparameter
1725 \DWATtype(reference to 2\$)
1727 10\$: \DWTAGsubprogram
1730 \DWATobjectpointer(reference to 11\$) \addtoindexx{object pointer attribute}
1731 ! References a formal parameter in this
1734 11\$: \DWTAGformalparameter
1735 \DWATartificial(true)
1737 \DWATtype(reference to 6\$)
1738 ! Makes type of 'this' as 'A const*' =>
1739 ! func2 marked as const
1742 12\$: \DWTAGsubprogram
1746 ! No object pointer reference formal parameter
1747 ! implies func3 is static
1748 13\$: \DWTAGformalparameter
1750 \DWATtype(reference to 2\$)
1757 Figure~\ref{fig:memberfunctionexampledwarfdescription}: Member function example: DWARF description \textit{(concluded)}
1762 As a further example illustrating \&- and \&\&-qualification
1763 of member functions,
1764 consider the member function example fragment in
1765 Figure \refersec{fig:memberfunctionrefqualexamplesourcefragment}.
1766 The DWARF representation in
1767 Figure \refersec{fig:memberfunctionrefqualexampledwarfdescription}
1779 // The type of pointer is "void (A::*)() const &&".
1780 auto pointer_to_member_function = &A::f;
1783 \caption{Reference- and rvalue-reference-qualification example: source \mbox{fragment}}
1784 \label{fig:memberfunctionrefqualexamplesourcefragment}
1792 100$: \DWTAGclasstype
1796 \DWATrvaluereference(0x01)
1797 \DWTAGformalparameter
1798 \DWATtype({ref to 200$}) ! to const A*
1799 \DWATartificial(0x01)
1803 \DWATtype({ref to 300$}) ! to const A
1807 \DWATtype({ref to 100$}) ! to class A
1810 \DWTAGptrtomembertype
1811 \DWATtype({ref to 400$}) ! to functype
1812 \DWATcontainingtype({ref to 100$}) ! to class A
1815 \DWTAGsubroutinetype
1816 \DWATrvaluereference(0x01)
1817 \DWTAGformalparameter
1818 \DWATtype({ref to 200$}) ! to const A*
1819 \DWATartificial(0x01)
1821 600$: \DWTAGsubprogram
1825 \DWATtype({ref to 100$}) ! to class A
1827 \DWATname("pointer_to_member_function")
1828 \DWATtype({ref to 300$})
1832 \caption{Reference- and rvalue-reference-qualification example: DWARF \mbox{description}}
1833 \label{fig:memberfunctionrefqualexampledwarfdescription}
1838 \section{Line Number Examples}
1839 \label{app:linenumberexamples}
1841 \subsection{Line Number Header Example}
1842 \label{app:linenumberheaderexample}
1844 The information found in a \DWARFVersionIV{} line number
1845 header can be encoded as shown in
1846 Figure \refersec{fig:preV5LNCTusingV5}.
1851 Field Field Name Value(s)
1853 1 \textit{Same as in Version 4} ...
1855 3 \textit{Not present in Version 4} -
1856 4 \textit{Not present in Version 4} -
1857 5-12 \textit{Same as in Version 4} ...
1858 13 \HFNdirectoryentryformatcount{} 1
1859 14 \HFNdirectoryentryformat{} \DWLNCTpath, \DWFORMstring
1860 15 \HFNdirectoriescount{} <n>
1861 16 \HFNdirectories{} <n>*<null terminated string>
1862 17 \HFNfilenameentryformatcount{} 4
1863 18 \HFNfilenameentryformat{} \DWLNCTpath, \DWFORMstring,
1864 \DWLNCTdirectoryindex, \DWFORMudata,
1865 \DWLNCTtimestamp, \DWFORMudata,
1866 \DWLNCTsize, \DWFORMudata
1867 19 \HFNfilenamescount{} <m>
1868 20 \HFNfilenames{} <m>*\{<null terminated string>, <index>,
1869 <timestamp>, <size>\}
1873 \caption{Pre-\DWARFVersionV{} line number program header information \mbox{encoded} using \DWARFVersionV}
1874 \label{fig:preV5LNCTusingV5}
1878 \subsection{Line Number Special Opcode Example}
1879 \label{app:linenumberspecialopcodeexample}
1880 Suppose that the opcode\_base is 13,
1881 \addttindex{line\_base} is -3,
1882 \addttindex{line\_range} is 12,
1883 \addttindex{minimum\_instruction\_length} is 1
1885 \addttindex{maximum\_operations\_per\_instruction} is 1.
1887 we can use a special opcode whenever two successive rows in
1888 the matrix have source line numbers differing by any value
1889 within the range [-3, 8] and (because of the limited number
1890 of opcodes available) when the difference between addresses
1891 is within the range [0, 20], but not all line advances are
1892 available for the maximum \addtoindex{operation advance} (see below).
1894 The resulting opcode mapping is shown in
1895 Figure \refersec{fig:examplelinenumberspecialopcodemapping}.
1901 Advance -3 -2 -1 0 1 2 3 4 5 6 7 8
1902 --------- -----------------------------------------------
1903 0 13 14 15 16 17 18 19 20 21 22 23 24
1904 1 25 26 27 28 29 30 31 32 33 34 35 36
1905 2 37 38 39 40 41 42 43 44 45 46 47 48
1906 3 49 50 51 52 53 54 55 56 57 58 59 60
1907 4 61 62 63 64 65 66 67 68 69 70 71 72
1908 5 73 74 75 76 77 78 79 80 81 82 83 84
1909 6 85 86 87 88 89 90 91 92 93 94 95 96
1910 7 97 98 99 100 101 102 103 104 105 106 107 108
1911 8 109 110 111 112 113 114 115 116 117 118 119 120
1912 9 121 122 123 124 125 126 127 128 129 130 131 132
1913 10 133 134 135 136 137 138 139 140 141 142 143 144
1914 11 145 146 147 148 149 150 151 152 153 154 155 156
1915 12 157 158 159 160 161 162 163 164 165 166 167 168
1916 13 169 170 171 172 173 174 175 176 177 178 179 180
1917 14 181 182 183 184 185 186 187 188 189 190 191 192
1918 15 193 194 195 196 197 198 199 200 201 202 203 204
1919 16 205 206 207 208 209 210 211 212 213 214 215 216
1920 17 217 218 219 220 221 222 223 224 225 226 227 228
1921 18 229 230 231 232 233 234 235 236 237 238 239 240
1922 19 241 242 243 244 245 246 247 248 249 250 251 252
1926 \caption{Example line number special opcode mapping}
1927 \label{fig:examplelinenumberspecialopcodemapping}
1930 There is no requirement that the expression
1931 255 - \addttindex{line\_base} + 1 be an integral multiple of
1932 \addttindex{line\_range}.
1936 \subsection{Line Number Program Example}
1937 \label{app:linenumberprogramexample}
1939 Consider the simple source file and the resulting machine
1940 code for the Intel 8086 processor in
1941 Figure \refersec{fig:linenumberprogramexamplemachinecode}.
1950 4: printf("Omit needless words\n");
1965 \caption{Line number program example: machine code}
1966 \label{fig:linenumberprogramexamplemachinecode}
1969 Suppose the line number program header includes the following
1970 (header fields not needed
1971 \addttindexx{line\_base}
1973 \addttindexx{line\_range}
1975 \addttindexx{opcode\_base}
1977 \addttindexx{minimum\_instruction\_length}
1981 minimum_instruction_length 1
1982 opcode_base 10 ! Opcodes 10-12 not needed
1988 Table \refersec{tab:linenumberprogramexampleoneencoding}
1989 shows one encoding of the line number program, which occupies
1990 12 bytes (the opcode SPECIAL(\textit{m},\textit{n}) indicates the special opcode
1991 generated for a line increment of \textit{m} and an address increment
1996 \setlength{\extrarowheight}{0.1cm}
1997 \begin{longtable}{l|l|l}
1998 \caption{Line number program example: one \mbox{encoding}}
1999 \label{tab:linenumberprogramexampleoneencoding} \\
2000 \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
2002 \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
2004 \hline \emph{Continued on next page}
2008 \DWLNSadvancepc&LEB128(0x239)&0x2, 0xb9, 0x04 \\
2009 SPECIAL(2, 0)& &0xb \\
2010 SPECIAL(2, 3)& &0x38 \\
2011 SPECIAL(1, 8)& &0x82 \\
2012 SPECIAL(1, 7)& &0x73 \\
2013 \DWLNSadvancepc&LEB128(2)&0x2, 0x2 \\
2014 \DWLNEendsequence{} &&0x0, 0x1, 0x1 \\
2019 Table \refersec{tab:linenumberprogramexamplealternateencoding}
2021 encoding of the same program using
2022 standard opcodes to advance
2023 the program counter;
2024 this encoding occupies 22 bytes.
2027 \setlength{\extrarowheight}{0.1cm}
2028 \begin{longtable}{l|l|l}
2029 \caption{Line number program example: alternate encoding}
2030 \label{tab:linenumberprogramexamplealternateencoding} \\
2031 \hline \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
2033 \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
2035 \hline \emph{Continued on next page}
2039 \DWLNSfixedadvancepc&0x239&0x9, 0x39, 0x2 \\
2040 SPECIAL(2, 0)&& 0xb \\
2041 \DWLNSfixedadvancepc&0x3&0x9, 0x3, 0x0 \\
2042 SPECIAL(2, 0)&&0xb \\
2043 \DWLNSfixedadvancepc&0x8&0x9, 0x8, 0x0 \\
2044 SPECIAL(1, 0)&& 0xa \\
2045 \DWLNSfixedadvancepc&0x7&0x9, 0x7, 0x0 \\
2046 SPECIAL(1, 0) && 0xa \\
2047 \DWLNSfixedadvancepc&0x2&0x9, 0x2, 0x0 \\
2048 \DWLNEendsequence&&0x0, 0x1, 0x1 \\
2053 \section{Call Frame Information Example}
2054 \label{app:callframeinformationexample}
2056 The following example uses a hypothetical RISC machine in
2057 the style of the Motorola 88000.
2059 \item Memory is byte addressed.
2061 \item Instructions are all 4 bytes each and word aligned.
2063 \item Instruction operands are typically of the form:
2065 <destination.reg>, <source.reg>, <constant>
2068 \item The address for the load and store instructions is computed
2069 by adding the contents of the
2070 source register with the constant.
2072 \item There are eight 4-byte registers:
2074 \begin{tabular}{p{5mm}l}
2076 & R1 holds return address on call \\
2077 & R2-R3 temp registers (not preserved on call) \\
2078 & R4-R6 preserved on call \\
2079 & R7 stack pointer \\
2082 \item The stack grows in the negative direction.
2084 \item The architectural ABI committee specifies that the
2085 stack pointer (R7) is the same as the CFA
2089 Figure \referfol{fig:callframeinformationexamplemachinecodefragments}
2090 shows two code fragments from a subroutine called
2091 foo that uses a frame pointer (in addition to the stack
2092 pointer). The first column values are byte addresses.
2093 % The \space is so we get a space after >
2094 \textless fs\textgreater\ denotes the stack frame size in bytes, namely 12.
2100 foo sub R7, R7, <fs> ; Allocate frame
2101 foo+4 store R1, R7, (<fs>-4) ; Save the return address
2102 foo+8 store R6, R7, (<fs>-8) ; Save R6
2103 foo+12 add R6, R7, 0 ; R6 is now the Frame ptr
2104 foo+16 store R4, R6, (<fs>-12) ; Save a preserved reg
2105 ;; This subroutine does not change R5
2107 ;; Start epilogue (R7 is returned to entry value)
2108 foo+64 load R4, R6, (<fs>-12) ; Restore R4
2109 foo+68 load R6, R7, (<fs>-8) ; Restore R6
2110 foo+72 load R1, R7, (<fs>-4) ; Restore return address
2111 foo+76 add R7, R7, <fs> ; Deallocate frame
2112 foo+80 jump R1 ; Return
2115 \caption{Call frame information example: machine code fragments}
2116 \label{fig:callframeinformationexamplemachinecodefragments}
2121 (see Section \refersec{chap:structureofcallframeinformation})
2122 for the foo subroutine is shown in
2123 Table \referfol{tab:callframeinformationexampleconceptualmatrix}.
2124 Corresponding fragments from the
2125 \dotdebugframe{} section are shown in
2126 Table \refersec{tab:callframeinformationexamplecommoninformationentryencoding}.
2128 The following notations apply in
2129 Table \refersec{tab:callframeinformationexampleconceptualmatrix}:
2131 \begin{tabular}{p{5mm}l}
2132 &1. R8 is the return address \\
2133 &2. s = same\_value rule \\
2134 &3. u = undefined rule \\
2135 &4. rN = register(N) rule \\
2136 &5. cN = offset(N) rule \\
2137 &6. a = architectural rule \\
2141 \setlength{\extrarowheight}{0.1cm}
2142 \begin{longtable}{l|llllllllll}
2143 \caption{Call frame information example: conceptual matrix}
2144 \label{tab:callframeinformationexampleconceptualmatrix} \\
2145 \hline \bfseries Location & \bfseries CFA & \bfseries R0 & \bfseries R1 & \bfseries R2 & \bfseries R3 & \bfseries R4 & \bfseries R5 & \bfseries R6 & \bfseries R7 & \bfseries R8 \\ \hline
2147 \bfseries Location &\bfseries CFA &\bfseries R0 & \bfseries R1 & \bfseries R2 &\bfseries R3 &\bfseries R4 &\bfseries R5 &\bfseries R6 &\bfseries R7 &\bfseries R8\\ \hline
2149 \hline \emph{Continued on next page}
2153 foo&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
2154 foo+4&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
2155 foo+8&[R7]+fs&s&u&u&u&s&s&s&a&c-4 \\
2156 foo+12&[R7]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
2157 foo+16&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
2158 foo+20&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
2160 foo+64&[R6]+fs&s&u&u&u&c-12&s&c-8&a&c-4 \\
2161 foo+68&[R6]+fs&s&u&u&u&s&s&c-8&a&c-4 \\
2162 foo+72&[R7]+fs&s&u&u&u&s&s&s&a&c-4 \\
2163 foo+76&[R7]+fs&s&u&u&u&s&s&s&a&r1 \\
2164 foo+80&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
2171 \setlength{\extrarowheight}{0.1cm}
2172 \begin{longtable}{l|ll}
2173 \caption{Call frame information example: common information entry encoding}
2174 \label{tab:callframeinformationexamplecommoninformationentryencoding}
2176 \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
2178 \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
2180 \hline \emph{Continued on next page}
2185 cie+4&\xffffffff&CIE\_id \\
2187 cie+9&0&augmentation \\
2188 cie+10&4&address size \\
2189 cie+11&0&segment size \\
2190 cie+12&4&code\_alignment\_factor, \textless caf \textgreater \\
2191 cie+13&-4&data\_alignment\_factor, \textless daf \textgreater \\
2192 cie+14&8&R8 is the return addr. \\
2193 cie+15&\DWCFAdefcfa{} (7, 0)&CFA = [R7]+0 \\
2194 cie+18&\DWCFAsamevalue{} (0)&R0 not modified (=0) \\
2195 cie+20&\DWCFAundefined{} (1)&R1 scratch \\
2196 cie+22&\DWCFAundefined{} (2)&R2 scratch \\
2197 cie+24&\DWCFAundefined{} (3)&R3 scratch \\
2198 cie+26&\DWCFAsamevalue{} (4)&R4 preserve \\
2199 cie+28&\DWCFAsamevalue{} (5)&R5 preserve \\
2200 cie+30&\DWCFAsamevalue{} (6)&R6 preserve \\
2201 cie+32&\DWCFAsamevalue{} (7)&R7 preserve \\
2202 cie+34&\DWCFAregister{} (8, 1)&R8 is in R1 \\
2203 cie+37&\DWCFAnop{} &padding \\
2204 cie+38&\DWCFAnop{} &padding \\
2205 cie+39& \DWCFAnop&padding \\
2211 The following notations apply in
2212 Table \refersec{tab:callframeinformationexampleframedescriptionentryencoding}:
2214 \begin{tabular}{p{5mm}l}
2215 &\texttt{<fs> =} frame size \\
2216 &\texttt{<caf> =} code alignment factor \\
2217 &\texttt{<daf> =} data alignment factor \\
2222 \setlength{\extrarowheight}{0.1cm}
2223 \begin{longtable}{l|ll}
2224 \caption{Call frame information example: frame description entry encoding}
2225 \label{tab:callframeinformationexampleframedescriptionentryencoding} \\
2226 \hline \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
2228 \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
2230 \hline \emph{Continued on next page}
2235 fde+4&cie&CIE\_ptr \\
2236 fde+8&foo&initial\_location \\
2237 fde+12&84&address\_range \\
2238 fde+16&\DWCFAadvanceloc(1)&instructions \\
2239 fde+17&\DWCFAdefcfaoffset(12)& \textless fs\textgreater \\
2240 fde+19&\DWCFAadvanceloc(1)&4/\textless caf\textgreater \\
2241 fde+20&\DWCFAoffset(8,1)&-4/\textless daf\textgreater (2nd parameter) \\
2242 fde+22&\DWCFAadvanceloc(1)& \\
2243 fde+23&\DWCFAoffset(6,2)&-8/\textless daf\textgreater (2nd parameter) \\
2244 fde+25&\DWCFAadvanceloc(1) & \\
2245 fde+26&\DWCFAdefcfaregister(6) & \\
2246 fde+28&\DWCFAadvanceloc(1) & \\
2247 fde+29&\DWCFAoffset(4,3)&-12/\textless daf\textgreater (2nd parameter) \\
2248 fde+31&\DWCFAadvanceloc(12)&44/\textless caf\textgreater \\
2249 fde+32&\DWCFArestore(4)& \\
2250 fde+33&\DWCFAadvanceloc(1) & \\
2251 fde+34&\DWCFArestore(6) & \\
2252 fde+35&\DWCFAdefcfaregister(7) & \\
2253 fde+37&\DWCFAadvanceloc(1) & \\
2254 fde+38&\DWCFArestore(8) &\\
2255 fde+39&\DWCFAadvanceloc(1) &\\
2256 fde+40&\DWCFAdefcfaoffset(0) &\\
2257 fde+42&\DWCFAnop&padding \\
2258 fde+43&\DWCFAnop&padding \\
2263 \section{Inlining Examples}
2264 \label{app:inliningexamples}
2265 The pseudo\dash source in
2266 Figure \referfol{fig:inliningexamplespseudosourcefragment}
2267 is used to illustrate the
2268 \addtoindexx{inlined subprogram call!examples}
2269 use of DWARF to describe inlined subroutine calls. This
2270 example involves a nested subprogram \texttt{INNER} that makes uplevel
2271 references to the formal parameter and local variable of the
2272 containing subprogram \texttt{OUTER}.
2276 inline procedure OUTER (OUTER_FORMAL : integer) =
2278 OUTER_LOCAL : integer;
2279 procedure INNER (INNER_FORMAL : integer) =
2281 INNER_LOCAL : integer;
2282 print(INNER_FORMAL + OUTER_LOCAL);
2292 \caption{Inlining examples: pseudo-source fragmment}
2293 \label{fig:inliningexamplespseudosourcefragment}
2297 There are several approaches that a compiler might take to
2298 inlining for this sort of example. This presentation considers
2299 three such approaches, all of which involve inline expansion
2300 of subprogram \texttt{OUTER}. (If \texttt{OUTER} is not inlined, the inlining
2301 reduces to a simpler single level subset of the two level
2302 approaches considered here.)
2305 \begin{enumerate}[1. ]
2306 \item Inline both \texttt{OUTER} and \texttt{INNER} in all cases
2308 \item Inline \texttt{OUTER}, multiple \texttt{INNER}s \\
2309 Treat \texttt{INNER} as a non\dash inlinable part of \texttt{OUTER}, compile and
2310 call a distinct normal version of \texttt{INNER} defined within each
2311 inlining of \texttt{OUTER}.
2313 \item Inline \texttt{OUTER}, one \texttt{INNER} \\
2314 Compile \texttt{INNER} as a single normal subprogram which is called
2315 from every inlining of \texttt{OUTER}.
2318 This discussion does not consider why a compiler might choose
2319 one of these approaches; it considers only how to describe
2322 In the examples that follow in this section, the debugging
2323 information entries are given mnemonic labels of the following
2330 \item[\textless io\textgreater]
2331 is either \texttt{INNER} or \texttt{OUTER} to indicate to which
2332 subprogram the debugging information entry applies,
2333 \item[\textless ac\textgreater]
2334 is either AI or CI to indicate \doublequote{abstract instance} or
2335 \doublequote{concrete instance} respectively,
2336 \item[\textless n\textgreater]
2337 is the number of the
2338 alternative being considered, and
2339 \item[\textless s\textgreater]
2340 is a sequence number that
2341 distinguishes the individual entries.
2343 There is no implication
2344 that symbolic labels, nor any particular naming convention,
2345 are required in actual use.
2347 For conciseness, declaration coordinates and call coordinates are omitted.
2349 \subsection{Alternative \#1: inline both OUTER and INNER}
2350 \label{app:inlinebothouterandinner}
2352 A suitable abstract instance for an alternative where both
2353 \texttt{OUTER} and \texttt{INNER} are always inlined is shown in
2354 Figure \refersec{fig:inliningexample1abstractinstance}.
2357 Figure \ref{fig:inliningexample1abstractinstance}
2358 that the debugging information entry for
2359 \texttt{INNER} (labelled \texttt{INNER.AI.1.1}) is nested in (is a child of)
2360 that for \texttt{OUTER} (labelled \texttt{OUTER.AI.1.1}). Nonetheless, the
2361 abstract instance tree for \texttt{INNER} is considered to be separate
2362 and distinct from that for \texttt{OUTER}.
2364 The call of \texttt{OUTER} shown in
2365 Figure \refersec{fig:inliningexamplespseudosourcefragment}
2366 might be described as
2368 Figure \refersec{fig:inliningexample1concreteinstance}.
2374 ! Abstract instance for OUTER
2375 ! \addtoindexx{abstract instance!example}
2379 \DWATinline(\DWINLdeclaredinlined)
2382 \DWTAGformalparameter
2383 \DWATname("OUTER\_FORMAL")
2384 \DWATtype(reference to integer)
2388 \DWATname("OUTER\_LOCAL")
2389 \DWATtype(reference to integer)
2392 ! Abstract instance for INNER
2397 \DWATinline(\DWINLdeclaredinlined)
2400 \DWTAGformalparameter
2401 \DWATname("INNER\_FORMAL")
2402 \DWATtype(reference to integer)
2406 \DWATname("INNER\_LOCAL")
2407 \DWATtype(reference to integer)
2411 ! No \DWTAGinlinedsubroutine (concrete instance)
2412 ! for INNER corresponding to calls of INNER
2417 \caption{Inlining example \#1: abstract instance}
2418 \label{fig:inliningexample1abstractinstance}
2424 ! Concrete instance for call "OUTER(7)"
2425 ! \addtoindexx{concrete instance!example}
2427 \DWTAGinlinedsubroutine
2429 \DWATabstractorigin(reference to OUTER.AI.1.1)
2433 \DWTAGformalparameter
2435 \DWATabstractorigin(reference to OUTER.AI.1.2)
2440 \DWATabstractorigin(reference to OUTER.AI.1.3)
2443 ! No \DWTAGsubprogram (abstract instance) for INNER
2445 ! Concrete instance for call INNER(OUTER\_LOCAL)
2448 \DWTAGinlinedsubroutine
2450 \DWATabstractorigin(reference to INNER.AI.1.1)
2453 \DWATstaticlink(...)
2455 \DWTAGformalparameter
2457 \DWATabstractorigin(reference to INNER.AI.1.2)
2462 \DWATabstractorigin(reference to INNER.AI.1.3)
2466 ! Another concrete instance of INNER within OUTER
2467 ! for the call "INNER(31)"
2472 \caption{Inlining example \#1: concrete instance}
2473 \label{fig:inliningexample1concreteinstance}
2476 \subsection{Alternative \#2: Inline OUTER, multiple INNERs}
2477 \label{app:inlineoutermultiipleinners}
2480 In the second alternative we assume that subprogram \texttt{INNER}
2481 is not inlinable for some reason, but subprogram \texttt{OUTER} is
2483 \addtoindexx{concrete instance!example}
2484 Each concrete inlined instance of \texttt{OUTER} has its
2485 own normal instance of \texttt{INNER}.
2486 The abstract instance for \texttt{OUTER},
2487 \addtoindexx{abstract instance!example}
2488 which includes \texttt{INNER}, is shown in
2489 Figure \refersec{fig:inliningexample2abstractinstance}.
2491 Note that the debugging information in
2492 Figure \ref{fig:inliningexample2abstractinstance}
2493 differs from that in
2494 Figure \refersec{fig:inliningexample1abstractinstance}
2495 in that \texttt{INNER} lacks a
2496 \DWATinline{} attribute
2497 and therefore is not a distinct abstract instance. \texttt{INNER}
2498 is merely an out\dash of\dash line routine that is part of \texttt{OUTER}\textquoteright s
2499 abstract instance. This is reflected in the Figure by
2500 \addtoindexx{abstract instance!example}
2501 the fact that the labels for \texttt{INNER} use the substring \texttt{OUTER}
2502 instead of \texttt{INNER}.
2505 \addtoindexx{concrete instance!example}
2506 concrete inlined instance of \texttt{OUTER} is shown in
2507 Figure \refersec{fig:inliningexample2concreteinstance}.
2510 Figure \ref{fig:inliningexample2concreteinstance}
2511 that \texttt{OUTER} is expanded as a concrete
2512 \addtoindexx{concrete instance!example}
2513 inlined instance, and that \texttt{INNER} is nested within it as a
2514 concrete out\dash of\dash line subprogram. Because \texttt{INNER} is cloned
2515 for each inline expansion of \texttt{OUTER}, only the invariant
2516 attributes of \texttt{INNER}
2517 (for example, \DWATname) are specified
2518 in the abstract instance of \texttt{OUTER}, and the low\dash level,
2519 \addtoindexx{abstract instance!example}
2520 instance\dash specific attributes of \texttt{INNER} (for example,
2521 \DWATlowpc) are specified in
2522 each concrete instance of \texttt{OUTER}.
2523 \addtoindexx{concrete instance!example}
2525 The several calls of \texttt{INNER} within \texttt{OUTER} are compiled as normal
2526 calls to the instance of \texttt{INNER} that is specific to the same
2527 instance of \texttt{OUTER} that contains the calls.
2532 ! Abstract instance for OUTER
2533 ! \addtoindex{abstract instance}
2537 \DWATinline(\DWINLdeclaredinlined)
2540 \DWTAGformalparameter
2541 \DWATname("OUTER\_FORMAL")
2542 \DWATtype(reference to integer)
2546 \DWATname("OUTER\_LOCAL")
2547 \DWATtype(reference to integer)
2550 ! Nested out-of-line INNER subprogram
2556 ! No low/high PCs, frame\_base, etc.
2558 \DWTAGformalparameter
2559 \DWATname("INNER\_FORMAL")
2560 \DWATtype(reference to integer)
2564 \DWATname("INNER\_LOCAL")
2565 \DWATtype(reference to integer)
2573 \caption{Inlining example \#2: abstract instance}
2574 \label{fig:inliningexample2abstractinstance}
2581 ! Concrete instance for call "OUTER(7)"
2584 \DWTAGinlinedsubroutine
2586 \DWATabstractorigin(reference to OUTER.AI.2.1)
2590 \DWTAGformalparameter
2592 \DWATabstractorigin(reference to OUTER.AI.2.2)
2597 \DWATabstractorigin(reference to OUTER.AI.2.3)
2600 ! Nested out-of-line INNER subprogram
2605 \DWATabstractorigin(reference to OUTER.AI.2.4)
2609 \DWATstaticlink(...)
2611 \DWTAGformalparameter
2613 \DWATabstractorigin(reference to OUTER.AI.2.5)
2618 \DWATabstractorigin(reference to OUTER.AT.2.6)
2626 \caption{Inlining example \#2: concrete instance}
2627 \label{fig:inliningexample2concreteinstance}
2630 \subsection{Alternative \#3: inline OUTER, one normal INNER}
2631 \label{app:inlineouteronenormalinner}
2633 In the third approach, one normal subprogram for \texttt{INNER} is
2634 compiled which is called from all concrete inlined instances of
2635 \addtoindexx{concrete instance!example}
2636 \addtoindexx{abstract instance!example}
2637 \texttt{OUTER}. The abstract instance for \texttt{OUTER} is shown in
2638 Figure \refersec{fig:inliningexample3abstractinstance}.
2640 The most distinctive aspect of that Figure is that subprogram
2641 \texttt{INNER} exists only within the abstract instance of \texttt{OUTER},
2642 and not in \texttt{OUTER}\textquoteright s concrete instance. In the abstract
2643 \addtoindexx{concrete instance!example}
2644 \addtoindexx{abstract instance!example}
2645 instance of \texttt{OUTER}, the description of \texttt{INNER} has the full
2646 complement of attributes that would be expected for a
2648 While attributes such as
2652 and so on, typically are omitted
2653 \addtoindexx{high PC attribute}
2655 \addtoindexx{low PC attribute}
2657 \addtoindexx{location attribute}
2658 abstract instance because they are not invariant across
2659 instances of the containing abstract instance, in this case
2660 those same attributes are included precisely because they are
2661 invariant -- there is only one subprogram \texttt{INNER} to be described
2662 and every description is the same.
2664 A concrete inlined instance of \texttt{OUTER} is illustrated in
2665 Figure \refersec{fig:inliningexample3concreteinstance}.
2668 Figure \ref{fig:inliningexample3concreteinstance}
2669 that there is no DWARF representation for
2670 \texttt{INNER} at all; the representation of \texttt{INNER} does not vary across
2671 instances of \texttt{OUTER} and the abstract instance of \texttt{OUTER} includes
2672 the complete description of \texttt{INNER}, so that the description of
2673 \texttt{INNER} may be (and for reasons of space efficiency, should be)
2675 \addtoindexx{concrete instance!example}
2676 concrete instance of \texttt{OUTER}.
2678 There is one aspect of this approach that is problematical from
2679 the DWARF perspective. The single compiled instance of \texttt{INNER}
2680 is assumed to access up\dash level variables of \texttt{OUTER}; however,
2681 those variables may well occur at varying positions within
2682 the frames that contain the
2683 \addtoindexx{concrete instance!example}
2684 concrete inlined instances. A
2685 compiler might implement this in several ways, including the
2686 use of additional compiler-generated parameters that provide
2687 reference parameters for the up\dash level variables, or a
2688 compiler-generated static link like parameter that points to the group
2689 of up\dash level entities, among other possibilities. In either of
2690 these cases, the DWARF description for the location attribute
2691 of each uplevel variable needs to be different if accessed
2692 from within \texttt{INNER} compared to when accessed from within the
2693 instances of \texttt{OUTER}. An implementation is likely to require
2694 vendor\dash specific DWARF attributes and/or debugging information
2695 entries to describe such cases.
2697 Note that in \addtoindex{C++}, a member function of a class defined within
2698 a function definition does not require any vendor\dash specific
2699 extensions because the \addtoindex{C++} language disallows access to
2700 entities that would give rise to this problem. (Neither \texttt{extern}
2701 variables nor \texttt{static} members require any form of static link
2702 for accessing purposes.)
2707 ! Abstract instance for OUTER
2708 ! \addtoindexx{abstract instance!example}
2712 \DWATinline(\DWINLdeclaredinlined)
2715 \DWTAGformalparameter
2716 \DWATname("OUTER\_FORMAL")
2717 \DWATtype(reference to integer)
2721 \DWATname("OUTER\_LOCAL")
2722 \DWATtype(reference to integer)
2733 \DWATstaticlink(...)
2735 \DWTAGformalparameter
2736 \DWATname("INNER\_FORMAL")
2737 \DWATtype(reference to integer)
2741 \DWATname("INNER\_LOCAL")
2742 \DWATtype(reference to integer)
2750 \caption{Inlining example \#3: abstract instance}
2751 \label{fig:inliningexample3abstractinstance}
2757 ! Concrete instance for call "OUTER(7)"
2758 ! \addtoindexx{concrete instance!example}
2760 \DWTAGinlinedsubroutine
2762 \DWATabstractorigin(reference to OUTER.AI.3.1)
2767 \DWTAGformalparameter
2769 \DWATabstractorigin(reference to OUTER.AI.3.2)
2775 \DWATabstractorigin(reference to OUTER.AI.3.3)
2778 ! No \DWTAGsubprogram for "INNER"
2783 \caption{Inlining example \#3: concrete instance}
2784 \label{fig:inliningexample3concreteinstance}
2788 \section{Constant Expression Example}
2789 \label{app:constantexpressionexample}
2790 \addtoindex{C++} generalizes the notion of constant expressions to include
2791 constant expression user-defined literals and functions.
2792 The constant declarations in Figure \refersec{fig:constantexpressionscsource}
2793 can be represented as illustrated in
2794 Figure \refersec{fig:constantexpressionsdwarfdescription}.
2798 \begin{lstlisting}[numbers=none]
2799 constexpr double mass = 9.8;
2800 constexpr int square (int x) { return x * x; }
2801 float arr[square(9)]; // square() called and inlined
2803 \caption{Constant expressions: C++ source} \label{fig:constantexpressionscsource}
2812 1\$: \DWTAGconsttype
2813 \DWATtype(reference to "double")
2816 \DWATtype(reference to 1\$)
2817 \DWATconstexpr(true)
2818 \DWATconstvalue(9.8)
2819 ! Abstract instance for square
2821 10\$: \DWTAGsubprogram
2823 \DWATtype(reference to "int")
2824 \DWATinline(\DWINLinlined)
2825 11\$: \DWTAGformalparameter
2827 \DWATtype(reference to "int")
2828 ! Concrete instance for square(9)
2829 ! \addtoindexx{concrete instance!example}
2830 20\$: \DWTAGinlinedsubroutine
2831 \DWATabstractorigin(reference to 10\$)
2832 \DWATconstexpr(present)
2834 \DWTAGformalparameter
2835 \DWATabstractorigin(reference to 11\$)
2837 ! Anonymous array type for arr
2839 30\$: \DWTAGarraytype
2840 \DWATtype(reference to "float")
2841 \DWATbytesize(324) ! 81*4
2843 \DWATtype(reference to "int")
2844 \DWATupperbound(reference to 20\$)
2847 40\$: \DWTAGvariable
2849 \DWATtype(reference to 30\$)
2852 \caption{Constant expressions: DWARF description}
2853 \label{fig:constantexpressionsdwarfdescription}
2856 \section{Unicode Character Example}
2857 \label{app:unicodecharacterexample}
2858 \addtoindexx{Unicode|see {\textit{also} UTF-8}}
2859 The \addtoindex{Unicode} character encodings in
2860 Figure \refersec{fig:unicodecharacterexamplesource}
2861 can be described in DWARF as illustrated in
2862 Figure \refersec{fig:unicodecharacterexampledwarfdescription}.
2865 \begin{lstlisting}[numbers=none]
2868 char16_t chr_a = u'h';
2869 char32_t chr_b = U'h';
2871 \caption{Unicode character example: source}
2872 \label{fig:unicodecharacterexamplesource}
2882 \DWATname("char16\_t")
2883 \DWATencoding(\DWATEUTF)
2886 \DWATname("char32\_t")
2887 \DWATencoding(\DWATEUTF)
2891 \DWATtype(reference to 1\$)
2894 \DWATtype(reference to 2\$)
2897 \caption{Unicode character example: DWARF description}
2898 \label{fig:unicodecharacterexampledwarfdescription}
2902 \section{Type-Safe Enumeration Example}
2903 \label{app:typesafeenumerationexample}
2905 The \addtoindex{C++} type\dash safe enumerations in
2906 \addtoindexx{type-safe enumeration}
2907 Figure \refersec{fig:ctypesafeenumerationexamplesource}
2908 can be described in DWARF as illustrated in
2909 Figure \refersec{fig:ctypesafeenumerationexampledwarf}.
2911 \clearpage % Get following source and DWARF on same page
2914 \begin{lstlisting}[numbers=none]
2917 enum class E { E1, E2=100 };
2920 \caption{Type-safe enumeration example: source}
2921 \label{fig:ctypesafeenumerationexamplesource}
2929 11\$: \DWTAGenumerationtype
2931 \DWATtype(reference to "int")
2932 \DWATenumclass(present)
2933 12\$: \DWTAGenumerator
2936 13\$: \DWTAGenumerator
2938 \DWATconstvalue(100)
2939 14\$: \DWTAGvariable
2941 \DWATtype(reference to 11\$)
2944 \caption{Type-safe enumeration example: DWARF description}
2945 \label{fig:ctypesafeenumerationexampledwarf}
2950 \section{Template Examples}
2951 \label{app:templateexample}
2953 The \addtoindex{C++} template example in
2954 Figure \refersec{fig:ctemplateexample1source}
2955 can be described in DWARF as illustrated in
2956 Figure \refersec{fig:ctemplateexample1dwarf}.
2968 \caption{C++ template example \#1: source}
2969 \label{fig:ctemplateexample1source}
2977 11\$: \DWTAGstructuretype
2978 \DWATname("wrapper")
2979 12\$: \DWTAGtemplatetypeparameter
2981 \DWATtype(reference to "int")
2984 \DWATtype(reference to 12\$)
2985 14\$: \DWTAGvariable
2987 \DWATtype(reference to 11\$)
2990 \caption{C++ template example \#1: DWARF description}
2991 \label{fig:ctemplateexample1dwarf}
2994 The actual type of the component \texttt{comp} is \texttt{int}, but in the DWARF
2995 the type references the
2996 \DWTAGtemplatetypeparameter{}
2997 for \texttt{T}, which in turn references \texttt{int}. This implies that in the
2998 original template comp was of type \texttt{T} and that was replaced
2999 with \texttt{int} in the instance.
3002 There exist situations where it is
3003 not possible for the DWARF to imply anything about the nature
3004 of the original template.
3005 Consider the \addtoindex{C++} template source in
3006 Figure \refersec{fig:ctemplateexample2source}
3007 and the DWARF that can describe it in
3008 Figure \refersec{fig:ctemplateexample2dwarf}.
3019 void consume(wrapper<U> formal)
3026 \caption{C++ template example \#2: source}
3027 \label{fig:ctemplateexample2source}
3035 11\$: \DWTAGstructuretype
3036 \DWATname("wrapper")
3037 12\$: \DWTAGtemplatetypeparameter
3039 \DWATtype(reference to "int")
3042 \DWATtype(reference to 12\$)
3043 14\$: \DWTAGvariable
3045 \DWATtype(reference to 11\$)
3046 21\$: \DWTAGsubprogram
3047 \DWATname("consume")
3048 22\$: \DWTAGtemplatetypeparameter
3050 \DWATtype(reference to "int")
3051 23\$: \DWTAGformalparameter
3053 \DWATtype(reference to 11\$)
3056 \caption{C++ template example \#2: DWARF description}
3057 \label{fig:ctemplateexample2dwarf}
3060 In the \DWTAGsubprogram{}
3061 entry for the instance of consume, \texttt{U} is described as \texttt{int}.
3062 The type of formal is \texttt{wrapper\textless U\textgreater} in
3063 the source. DWARF only represents instantiations of templates;
3064 there is no entry which represents \texttt{wrapper\textless U\textgreater}
3066 a template parameter nor a template instantiation. The type
3067 of formal is described as \texttt{wrapper\textless int\textgreater},
3068 the instantiation of \texttt{wrapper\textless U\textgreater},
3069 in the \DWATtype{} attribute at
3072 description of the relationship between template type parameter
3073 \texttt{T} at 12\$ and \texttt{U} at 22\$ which was used to instantiate
3074 \texttt{wrapper\textless U\textgreater}.
3076 A consequence of this is that the DWARF information would
3077 not distinguish between the existing example and one where
3078 the formal parameter of \texttt{consume} were declared in the source to be
3079 \texttt{wrapper\textless int\textgreater}.
3082 \section{Template Alias Examples}
3083 \label{app:templatealiasexample}
3085 The \addtoindex{C++} template alias shown in
3086 Figure \refersec{fig:ctemplatealiasexample1source}
3087 can be described in DWARF as illustrated
3088 \addtoindexx{template alias example} in
3089 Figure \refersec{fig:ctemplatealiasexample1dwarf}.
3093 // C++ source, template alias example 1
3095 template<typename T, typename U>
3100 template<typename V> using Beta = Alpha<V,V>;
3103 \caption{C++ template alias example \#1: source}
3104 \label{fig:ctemplatealiasexample1source}
3108 \addtoindexx{template alias example 1}
3111 ! DWARF representation for variable 'b'
3113 20\$: \DWTAGstructuretype
3115 21\$: \DWTAGtemplatetypeparameter
3117 \DWATtype(reference to "long")
3118 22\$: \DWTAGtemplatetypeparameter
3120 \DWATtype(reference to "long")
3123 \DWATtype(reference to 21\$)
3125 \DWATname("uniform")
3126 \DWATtype(reference to 22\$)
3127 25\$: \DWTAGtemplatealias
3129 \DWATtype(reference to 20\$)
3130 26\$: \DWTAGtemplatetypeparameter
3132 \DWATtype(reference to "long")
3133 27\$: \DWTAGvariable
3135 \DWATtype(reference to 25\$)
3138 \caption{C++ template alias example \#1: DWARF description}
3139 \label{fig:ctemplatealiasexample1dwarf}
3142 Similarly, the \addtoindex{C++} template alias shown in
3143 Figure \refersec{fig:ctemplatealiasexample2source}
3144 can be described in DWARF as illustrated
3145 \addtoindexx{template alias example} in
3146 Figure \refersec{fig:ctemplatealiasexample2dwarf}.
3150 // C++ source, template alias example 2
3152 template<class TX> struct X { };
3153 template<class TY> struct Y { };
3154 template<class T> using Z = Y<T>;
3158 \caption{C++ template alias example \#2: source}
3159 \label{fig:ctemplatealiasexample2source}
3163 \addtoindexx{template alias example 2}
3166 ! DWARF representation for X<Y<int>>
3168 30\$: \DWTAGstructuretype
3170 31\$: \DWTAGtemplatetypeparameter
3172 \DWATtype(reference to "int")
3173 32\$: \DWTAGstructuretype
3175 33\$: \DWTAGtemplatetypeparameter
3177 \DWATtype(reference to 30\$)
3179 ! DWARF representation for X<Z<int>>
3181 40\$: \DWTAGtemplatealias
3183 \DWATtype(reference to 30\$)
3184 41\$: \DWTAGtemplatetypeparameter
3186 \DWATtype(reference to "int")
3187 42\$: \DWTAGstructuretype
3189 43\$: \DWTAGtemplatetypeparameter
3191 \DWATtype(reference to 40\$)
3193 ! Note that 32\$ and 42\$ are actually the same type
3195 50\$: \DWTAGvariable
3197 \DWATtype(reference to \$32)
3198 51\$: \DWTAGvariable
3200 \DWATtype(reference to \$42)
3203 \caption{C++ template alias example \#2: DWARF description}
3204 \label{fig:ctemplatealiasexample2dwarf}
3208 \section{Implicit Pointer Examples}
3209 \label{app:implicitpointerexamples}
3210 If the compiler determines that the value of an object is
3211 constant (either throughout the program, or within a specific
3212 range), it may choose to materialize that constant only when
3213 used, rather than store it in memory or in a register. The
3214 \DWOPimplicitvalue{} operation can be used to describe such a
3215 value. Sometimes, the value may not be constant, but still can be
3216 easily rematerialized when needed. A DWARF expression terminating
3217 in \DWOPstackvalue{} can be used for this case. The compiler may
3218 also eliminate a pointer value where the target of the pointer
3219 resides in memory, and the \DWOPstackvalue{} operator may be used
3220 to rematerialize that pointer value. In other cases, the compiler
3221 will eliminate a pointer to an object that itself needs to be
3222 materialized. Since the location of such an object cannot be
3223 represented as a memory address, a DWARF expression cannot give
3224 either the location or the actual value or a pointer variable
3225 that would refer to that object. The \DWOPimplicitpointer{}
3226 operation can be used to describe the pointer, and the debugging
3227 information entry to which its first operand refers describes the
3228 value of the dereferenced object. A DWARF consumer will not be
3229 able to show the location or the value of the pointer variable,
3230 but it will be able to show the value of the dereferenced
3233 Consider the \addtoindex{C} source shown in
3234 Figure \refersec{fig:cimplicitpointerexample1source}.
3235 Assume that the function \texttt{foo} is not inlined,
3236 that the argument x is passed in register 5, and that the
3237 function \texttt{foo} is optimized by the compiler into just
3238 an increment of the volatile variable \texttt{v}. Given these
3239 assumptions a possible DWARF description is shown in
3240 Figure \refersec{fig:cimplicitpointerexample1dwarf}.
3244 struct S { short a; char b, c; };
3248 struct S s = { x, x + 2, x + 3 };
3259 \caption{C implicit pointer example \#1: source}
3260 \label{fig:cimplicitpointerexample1source}
3264 \addtoindexx{implicit pointer example}
3267 1\$: \DWTAGstructuretype
3272 \DWATtype(reference to "short int")
3273 \DWATdatamemberlocation(constant 0)
3276 \DWATtype(reference to "char")
3277 \DWATdatamemberlocation(constant 2)
3280 \DWATtype(reference to "char")
3281 \DWATdatamemberlocation(constant 3)
3282 2\$: \DWTAGsubprogram
3284 20\$: \DWTAGformalparameter
3286 \DWATtype(reference to "int")
3287 \DWATlocation(\DWOPregfive)
3288 21\$: \DWTAGvariable
3290 \DWATlocation(expression=
3291 \DWOPbregfive(1) \DWOPstackvalue \DWOPpiece(2)
3292 \DWOPbregfive(2) \DWOPstackvalue \DWOPpiece(1)
3293 \DWOPbregfive(3) \DWOPstackvalue \DWOPpiece(1))
3294 22\$: \DWTAGvariable
3296 \DWATtype(reference to "char *")
3297 \DWATlocation(expression=
3298 \DWOPimplicitpointer(reference to 21\$, 2))
3301 \caption{C implicit pointer example \#1: DWARF description}
3302 \label{fig:cimplicitpointerexample1dwarf}
3305 In Figure \refersec{fig:cimplicitpointerexample1dwarf},
3306 even though variables \texttt{s} and \texttt{p} are both optimized
3307 away completely, this DWARF description still allows a debugger to
3308 print the value of the variable \texttt{s}, namely \texttt{(2, 3, 4)}.
3309 Similarly, because the variable \texttt{s} does not live in
3310 memory, there is nothing to print for the value of \texttt{p}, but the
3311 debugger should still be able to show that \texttt{p[0]} is 3,
3312 \texttt{p[1]} is 4, \texttt{p[-1]} is 0 and \texttt{p[-2]} is 2.
3315 As a further example, consider the C source
3316 shown in Figure \refersec{fig:cimplicitpointerexample2source}. Make
3317 the following assumptions about how the code is compiled:
3319 \item The function \texttt{foo} is inlined
3320 into function \texttt{main}
3321 \item The body of the main function is optimized to just
3322 three blocks of instructions which each increment the volatile
3323 variable \texttt{v}, followed by a block of instructions to return 0 from
3325 \item Label \texttt{label0} is at the start of the main
3326 function, \texttt{label1} follows the first \texttt{v++} block,
3327 \texttt{label2} follows the second \texttt{v++} block and
3328 \texttt{label3} is at the end of the main function
3329 \item Variable \texttt{b} is optimized away completely, as it isn't used
3330 \item The string literal \texttt{"opq"} is optimized away as well
3332 Given these assumptions a possible DWARF description is shown in
3333 Figure \refersec{fig:cimplicitpointerexample2dwarf}.
3337 static const char *b = "opq";
3339 static inline void foo (int *p)
3349 int a[2] = { 1, 2 };
3352 return a[0] + a[1] - 5;
3355 \caption{C implicit pointer example \#2: source}
3356 \label{fig:cimplicitpointerexample2source}
3360 \addtoindexx{implicit pointer example}
3365 \DWATtype(reference to "const char *")
3366 \DWATlocation(expression=
3367 \DWOPimplicitpointer(reference to 2$, 0))
3368 2\$: \DWTAGdwarfprocedure
3369 \DWATlocation(expression=
3370 \DWOPimplicitvalue(4, \{'o', 'p', 'q', '\slash0'\}))
3371 3\$: \DWTAGsubprogram
3373 \DWATinline(\DWINLdeclaredinlined)
3374 30\$: \DWTAGformalparameter
3376 \DWATtype(reference to "int *")
3377 4\$: \DWTAGsubprogram
3379 40\$: \DWTAGvariable
3381 \DWATtype(reference to "int[2]")
3382 \DWATlocation(location list 98$)
3383 41\$: \DWTAGinlinedsubroutine
3384 \DWATabstractorigin(reference to 3$)
3385 42\$: \DWTAGformalparameter
3386 \DWATabstractorigin(reference to 30$)
3387 \DWATlocation(location list 99$)
3389 ! .debug_loc section
3390 98\$:<label0 in main> .. <label1 in main>
3391 \DWOPlitone \DWOPstackvalue \DWOPpiece(4)
3392 \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
3393 <label1 in main> .. <label2 in main>
3394 \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
3395 \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
3396 <label2 in main> .. <label3 in main>
3397 \DWOPlittwo \DWOPstackvalue \DWOPpiece(4)
3398 \DWOPlitthree \DWOPstackvalue \DWOPpiece(4)
3400 99\$:<label1 in main> .. <label2 in main>
3401 \DWOPimplicitpointer(reference to 40\$, 0)
3402 <label2 in main> .. <label3 in main>
3403 \DWOPimplicitpointer(reference to 40\$, 4)
3407 \caption{C implicit pointer example \#2: DWARF description}
3408 \label{fig:cimplicitpointerexample2dwarf}
3412 \section{String Type Examples}
3413 \label{app:stringtypeexamples}
3414 Consider the \addtoindex{Fortran 2003} string type example source in
3415 Figure \referfol{fig:stringtypeexamplesource}. The DWARF representation in
3416 Figure \refersec{fig:stringtypeexampledwarf} is appropriate.
3419 \addtoindexx{ISO 10646 character set standard}
3421 program character_kind
3424 integer, parameter :: ascii =
3425 selected_char_kind ("ascii")
3426 integer, parameter :: ucs4 =
3427 selected_char_kind ('ISO_10646')
3428 character(kind=ascii, len=26) :: alphabet
3429 character(kind=ucs4, len=30) :: hello_world
3430 character (len=*), parameter :: all_digits="0123456789"
3432 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
3433 hello_world = ucs4_'Hello World and Ni Hao -- ' &
3434 // char (int (z'4F60'), ucs4) &
3435 // char (int (z'597D'), ucs4)
3437 write (*,*) alphabet
3438 write (*,*) all_digits
3440 open (output_unit, encoding='UTF-8')
3441 write (*,*) trim (hello_world)
3442 end program character_kind
3444 \caption{String type example: source}
3445 \label{fig:stringtypeexamplesource}
3453 \DWATencoding (\DWATEASCII)
3456 \DWATencoding (\DWATEUCS)
3459 3\$: \DWTAGstringtype
3462 4\$: \DWTAGconsttype
3463 \DWATtype (reference to 3\$)
3465 5\$: \DWTAGstringtype
3467 \DWATstringlength ( ... )
3468 \DWATstringlengthbytesize ( ... )
3469 \DWATdatalocation ( ... )
3471 6\$: \DWTAGstringtype
3473 \DWATstringlength ( ... )
3474 \DWATstringlengthbytesize ( ... )
3475 \DWATdatalocation ( ... )
3478 \DWATname (alphabet)
3480 \DWATlocation ( ... )
3483 \DWATname (all\_digits)
3485 \DWATconstvalue ( ... )
3488 \DWATname (hello\_world)
3490 \DWATlocation ( ... )
3494 \caption{String type example: DWARF representation}
3495 \label{fig:stringtypeexampledwarf}
3499 \section{Call Site Examples}
3500 \label{app:callsiteexamples}
3501 The following examples use a hypothetical machine which:
3504 Passes the first argument in register 0, the second in register 1, and the third in register 2.
3506 Keeps the stack pointer is register 3.
3508 Has one call preserved register 4.
3510 Returns a function value in register 0.
3513 \subsection{Call Site Example \#1 (C)}
3514 Consider the \addtoindex{C} source in Figure \referfol{fig:callsiteexample1source}.
3519 extern void fn1 (long int, long int, long int);
3522 fn2 (long int a, long int b, long int c)
3530 fn3 (long int x, long int (*fn4) (long int *))
3532 long int v, w, w2, z;
3535 z = fn2 (1, v + 1, w);
3538 z += fn2 (w, v * 2, x);
3543 \caption{Call Site Example \#1: Source}
3544 \label{fig:callsiteexample1source}
3547 Possible generated code for this source is shown using a suggestive
3548 pseudo-\linebreak[0]assembly notation in Figure \refersec{fig:callsiteexample1code}.
3554 %reg2 = 7 ! Load the 3rd argument to fn1
3555 %reg1 = 6 ! Load the 2nd argument to fn1
3556 %reg0 = 5 ! Load the 1st argument to fn1
3559 %reg0 = 0 ! Load the return value from the function
3563 ! Decrease stack pointer to reserve local stack frame
3565 [%reg3] = %reg4 ! Save the call preserved register to
3567 [%reg3 + 8] = %reg0 ! Preserve the x argument value
3568 [%reg3 + 16] = %reg1 ! Preserve the fn4 argument value
3569 %reg0 = %reg3 + 24 ! Load address of w2 as argument
3570 call %reg1 ! Call fn4 (indirect call)
3572 %reg2 = [%reg3 + 16] ! Load the fn4 argument value
3573 [%reg3 + 16] = %reg0 ! Save the result of the first call (w)
3574 %reg0 = %reg3 + 24 ! Load address of w2 as argument
3575 call %reg2 ! Call fn4 (indirect call)
3577 %reg4 = %reg0 ! Save the result of the second call (v)
3579 %reg2 = [%reg3 + 16] ! Load 3rd argument to fn2 (w)
3580 %reg1 = %reg4 + 1 ! Compute 2nd argument to fn2 (v + 1)
3581 %reg0 = 1 ! Load 1st argument to fn2
3584 %reg2 = [%reg3 + 8] ! Load the 3rd argument to fn2 (x)
3585 [%reg3 + 8] = %reg0 ! Save the result of the 3rd call (z)
3586 %reg0 = [%reg3 + 16] ! Load the 1st argument to fn2 (w)
3587 %reg1 = %reg4 + %reg4 ! Compute the 2nd argument to fn2 (v * 2)
3590 %reg2 = [%reg3 + 8] ! Load the value of z from the stack
3591 %reg0 = %reg0 + %reg2 ! Add result from the 4th call to it
3593 %reg4 = [%reg3] ! Restore original value of call preserved
3595 %reg3 = %reg3 + 32 ! Leave stack frame
3598 \caption{Call Site Example \#1: Code}
3599 \label{fig:callsiteexample1code}
3603 The location list for variable \texttt{a} in function \texttt{fn2}
3608 ! Before the call to fn1 the argument a is live in the register 0
3612 ! Afterwards it is not, the call could have clobbered the register,
3613 ! and it is not saved in the fn2 function stack frame either, but
3614 ! perhaps can be looked up in the caller
3616 <L2, L3> DW_OP_entry_value 1 DW_OP_reg0 DW_OP_stack_value
3621 (where the notation \doublequote{\texttt{<m, n>}} specifies the address
3622 range over which the following location description applies).
3624 Similarly, the variable q in fn2 then might have location list:
3627 ! Before the call to fn1 the value of q can be computed as two times
3628 ! the value of register 0
3630 <L1, L2> DW_OP_lit2 DW_OP_breg0 0 DW_OP_mul DW_OP_stack_value
3632 ! Afterwards it can be computed from the original value of the first
3633 ! parameter, multiplied by two
3635 <L2, L3> DW_OP_lit2 DW_OP_entry_value 1 DW_OP_reg0 DW_OP_mul DW_OP_stack_value
3640 Variables \texttt{b} and \texttt{c} each have a location list similar to
3641 that for variable \texttt{a},
3642 except for a different label between the two ranges and they
3643 use \DWOPregone{} and \DWOPregtwo{}, respectively, instead of \DWOPregzero.
3646 The call sites for all the calls in function \texttt{fn3} are children of the
3647 \DWTAGsubprogram{} entry for \texttt{fn3} (or of its \DWTAGlexicalblock{} entry
3648 if there is any for the whole function).
3649 This is shown in Figure \refersec{fig:callsiteexample1dwarf}.
3656 \DWATcallreturnpc(L6) ! First indirect call to (*fn4) in fn3.
3657 ! The address of the call is preserved across the call in memory at
3658 ! stack pointer + 16 bytes.
3659 \DWATcalltarget(\DWOPbregthree{} 16 \DWOPderef)
3660 \DWTAGcallsiteparameter
3661 \DWATlocation(\DWOPregzero)
3662 ! Value of the first parameter is equal to stack pointer + 24 bytes.
3663 \DWATcallvalue(\DWOPbregthree{} 24)
3665 \DWATcallreturnpc(L7) ! Second indirect call to (*fn4) in fn3.
3666 ! The address of the call is not preserved across the call anywhere, but
3667 ! could be perhaps looked up in fn3's caller.
3668 \DWATcalltarget(\DWOPentryvalue{} 1 \DWOPregone)
3669 \DWTAGcallsiteparameter
3670 \DWATlocation(\DWOPregzero)
3671 \DWATcallvalue(\DWOPbregthree{} 24)
3673 \DWATcallreturnpc(L4) ! 3rd call in fn3, direct call to fn2
3674 \DWATcallorigin(reference to fn2 DW_TAG_subprogram)
3675 \DWTAGcallsiteparameter
3676 \DWATcallparameter(reference to formal parameter a in subprogram fn2)
3677 \DWATlocation(\DWOPregzero)
3678 ! First parameter to fn2 is constant 1
3679 \DWATcallvalue(\DWOPlitone)
3680 \DWTAGcallsiteparameter
3681 \DWATcallparameter(reference to formal parameter b in subprogram fn2)
3682 \DWATlocation(\DWOPregone)
3683 ! Second parameter to fn2 can be computed as the value of the call
3684 ! preserved register 4 in the fn3 function plus one
3685 \DWATcallvalue(\DWOPbregfour{} 1)
3686 \DWTAGcallsiteparameter
3687 \DWATcallparameter(reference to formal parameter c in subprogram fn2)
3688 \DWATlocation(\DWOPregtwo)
3689 ! Third parameter's value is preserved in memory at fn3's stack pointer
3691 \DWATcallvalue(\DWOPbregthree{} 16 \DWOPderef)
3694 \caption{Call Site Example \#1: DWARF Encoding}
3695 \label{fig:callsiteexample1dwarf}
3707 \DWATtype(reference to int)
3708 ! Value of the v1 variable can be computed as value of register 4 plus 4
3709 \DWATlocation(\DWOPbregfour{} 4 \DWOPstackvalue)
3711 \DWATcallreturnpc(L5) ! 4th call in fn3, direct call to fn2
3712 \DWATcalltarget(reference to subprogram fn2)
3713 \DWTAGcallsiteparameter