This is the first pass of incorporating review commments from the
[dwarf-doc.git] / dwarf5 / latexdoc / debugsectionrelationships.tex
1 \chapter{Debug Section Relationships (Informative)}
2 \label{app:debugsectionrelationshipsinformative}
3 %
4 DWARF information is organized into multiple program sections, 
5 each of which holds a particular kind of information. In some 
6 cases, information in one section refers to information in one 
7 or more of the others. These relationships are illustrated by 
8 the diagram and associated notes on the following pages.
9
10 \begin{figure}[h]
11 % picture gets width and height of the picture drawn
12 % so latex knows how big it is (latex does not calculate
13 % the space you need to make it fit, you do).
14 \begin{picture}(320,300)
15 % Footnotesize keeps the text small-size so it fits
16 % in the boxes and ellipses
17 \footnotesize
18 % Thicklines makes the lines more visible.
19 \Thicklines
20   \put(5,208) { \addtoindex{.debug\_aranges} }
21   \put(40,210) { \ellipse{80}{30}}
22   \put(180,208) { \addtoindex{.debug\_frame} }
23   \put(210,210) { \ellipse{80}{30}}
24   \put(347,208) { \addtoindex{.debug\_abbrev} }
25   \put(380,210) { \ellipse{80}{30}}
26
27   \drawline[1](40,195)(40,181)
28   \put(-10,165){\framebox(110,15){To compilation unit (a)} }
29   \drawline[1](40,165)(40,151)(37,158) 
30   \put(352,168) { \addtoindex{.debug\_str} }
31   \put(380,170) {\ellipse{80}{30}}
32
33   \put(10,133) { \addtoindex{.debug\_info} }
34   \put(10,123) { \addtoindex{.debug\_types} }
35   \put(40,130) {\ellipse{80}{40}}
36
37
38   \put(350,128) { \addtoindex{.debug\_loc} }
39   \put(380,130) {\ellipse{80}{30}}
40
41   \put(345,88) { \addtoindex{.debug\_ranges} }
42   \put(380,90) {\ellipse{80}{30}}
43
44   \drawline[1](75,141)(160,170)
45   \put(160,165){\framebox(110,15){To abbreviations (c)} }
46   \drawline[1](271,176)(345,205)(335,197)
47
48   \put(76,138){\line(6, 1){83}}
49   \put(160,140){\framebox(110,15){\livelink{chap:DWFORMstrp}{DW\-\_FORM\-\_strp} (d)} }
50   \drawline[1](271,150)(341,168)(332,162)
51
52   \drawline[1](160,125)(80,130)(90,134)
53   \put(160,115){\framebox(110,15){\livelink{chap:DWOPcallref}{DW\-\_OP\-\_call\-\_ref}(e)} }
54   \drawline[1](271,125)(340,128) 
55
56   \drawline[1](79,128)(160,100)
57   \put(160,90){\framebox(110,15){\livelink{chap:DWATlocation}{DW\-\_AT\-\_location} etc (f)} }
58   \drawline[1](271,100)(341,125)(332,118)
59
60   \drawline(79,125)(160,75)
61   \put(160,65){\framebox(110,15){\livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} (g)} }
62   \drawline(271,75)(340,90)(332,85)
63
64   \drawline[1](77,121)(160,46)
65   \put(160,40){\framebox(110,15){\livelink{chap:DWATmacroinfo}{DW\-\_AT\-\_macro\-\_info} (h)} }
66   \drawline[1](271,46)(343,53)(332,49)
67
68   \drawline[1](71, 116)(160,20)
69   \put(160,15){\framebox(110,15){\livelink{chap:DWATstmtlist}{DW\-\_AT\-\_stmt\-\_list} (i)} }
70   \drawline[1](271,20)(343,10)(332,8)
71
72   \drawline[1](40,70)(40,110)(37,103)
73   \put(-10,55){\framebox(110,15){To compilation unit (b)} }
74   \drawline[1](40,35)(40,54)
75
76   \put(0,16) { \addtoindex{.debug\_pubnames} }
77   \put(0,6) { \addtoindex{.debug\_pubtypes} } 
78   \put(40, 15) { \ellipse{100}{40}}
79
80
81   \put(345,48) { \addtoindex{.debug\_macinfo} }
82   \put(380,50) { \ellipse{80}{30}}
83
84   \put(350,8) { \addtoindex{.debug\_line} }
85   \put(380,10) { \ellipse{80}{30}}
86
87 \end{picture}
88 \caption{Debug section relationships}
89 \label{fig:debugsectionrelationships}
90 \end{figure}
91
92 \clearpage
93 \begin{center}
94    \textbf{Notes}
95 \end{center}
96 \begin{enumerate}[(a)]  
97 \item  \addtoindex{.debug\_aranges}  \\
98 The debug\_info\_offset value in
99 the header is
100 the offset in the \addtoindex{.debug\_info} section of the
101 corresponding compilation unit header (not the compilation
102 unit entry).
103
104 %b
105 \item \addtoindex{.debug\_pubnames} and \addtoindex{.debug\_pubtypes} \\
106 The debug\_info\_offset value in the header is the offset in the
107 \addtoindex{.debug\_info} section of the 
108 corresponding compilation unit header (not
109 the compilation unit entry). Each pubname/pubtype has the offset (within
110 the corresponding compilation unit) of the applicable debugging
111 information entry.
112
113 %c
114 \item \addtoindex{.debug\_info} and \addtoindex{.debug\_types} \\
115 The debug\_abbrev\_offset value in the header is the offset in the
116 \addtoindex{.debug\_abbrev} 
117 section of the abbreviations for that compilation unit.
118
119 %d
120 \item  \addtoindex{.debug\_info} and \addtoindex{.debug\_types} \\
121 Attribute values of class string may have form 
122 \livelink{chap:DWFORMstrp}{DW\-\_FORM\-\_strp}, whose
123 value is the offset in the \addtoindex{.debug\_str}
124 section of the corresponding string.
125
126 %e
127 \item \addtoindex{.debug\_loc} \\
128 The operand of the \livelink{chap:DWOPcallref}{DW\-\_OP\-\_call\-\_ref} 
129 DWARF expression operator is the
130 offset of a debugging information entry in the 
131 \addtoindex{.debug\_info} section.
132
133 %f
134 \item \addtoindex{.debug\_info} \\
135 An attribute value of class \livelink{chap:loclistptr}{loclistptr} 
136 (specifically form
137 \livelink{chap:DWFORMsecoffset}{DW\-\_FORM\-\_sec\-\_offset}) 
138 is an offset within the \addtoindex{.debug\_loc} 
139 section of a
140 \addtoindex{location list}.
141
142 %g
143 \item \addtoindex{.debug\_info} \\
144 An attribute value of class \livelink{chap:rangelistptr}{rangelistptr} 
145 (specifically form
146 \livelink{chap:DWFORMsecoffset}{DW\-\_FORM\-\_sec\-\_offset}) 
147 is an offset within the \addtoindex{.debug\_ranges} section of
148 a range list.
149
150 %h
151 \item \addtoindex{.debug\_info} \\
152 An attribute value of class 
153 \livelink{chap:macptr}{macptr} (specifically form
154 \livelink{chap:DWFORMsecoffset}{DW\-\_FORM\-\_sec\-\_offset}) is an 
155 offset within the 
156 \addtoindex{.debug\_macinfo} section
157 of the beginning of the macro information for the referencing unit.
158
159 %i
160 \item \addtoindex{.debug\_info} \\
161 An attribute value of class 
162 \livelink{chap:lineptr}{lineptr} (specifically form
163 \livelink{chap:DWFORMsecoffset}{DW\-\_FORM\-\_sec\-\_offset}) 
164 is an offset in the 
165 \addtoindex{.debug\_line} section of the
166 beginning of the line number information for the referencing unit.
167 \end{enumerate}