| blob | 72bf64a03b7de6a29dabdb6392fabb19346c5b3a |
1 ;;;; structures used for recording debugger information
3 ;;;; This software is part of the SBCL system. See the README file for
4 ;;;; more information.
5 ;;;;
6 ;;;; This software is derived from the CMU CL system, which was
7 ;;;; written at Carnegie Mellon University and released into the
8 ;;;; public domain. The software is in the public domain and is
9 ;;;; provided with absolutely no warranty. See the COPYING and CREDITS
10 ;;;; files for more information.
13 \f
14 ;;;; flags for compiled debug variables
16 ;;; FIXME: old CMU CL representation follows:
17 ;;; Compiled debug variables are in a packed binary representation in the
18 ;;; DEBUG-FUN-VARS:
19 ;;; single byte of boolean flags:
20 ;;; uninterned name
21 ;;; packaged name
22 ;;; environment-live
23 ;;; has distinct save location
24 ;;; has ID (name not unique in this fun)
25 ;;; minimal debug-info argument (name generated as ARG-0, ...)
26 ;;; deleted: placeholder for unused minimal argument
27 ;;; [name length in bytes (as var-length integer), if not minimal]
28 ;;; [...name bytes..., if not minimal]
29 ;;; [if packaged, var-length integer that is package name length]
30 ;;; ...package name bytes...]
31 ;;; [If has ID, ID as var-length integer]
32 ;;; SC-Offset of primary location (as var-length integer)
33 ;;; [If has save SC, SC-OFFSET of save location (as var-length integer)]
43 \f
44 ;;;; compiled debug blocks
45 ;;;;
46 ;;;; Compiled debug blocks are in a packed binary representation in the
47 ;;;; DEBUG-FUN-BLOCKS:
48 ;;;; number of locations in this block
49 ;;;; kind of first location (single byte)
50 ;;;; delta from previous PC (or from 0 if first location in function.)
51 ;;;; [offset of first top level form, if no function TLF-NUMBER]
52 ;;;; form number of first source form
53 ;;;; first live mask (length in bytes determined by number of VARIABLES)
54 ;;;; ...more <kind, delta, top level form offset, form-number, live-set>
55 ;;;; tuples...
61 \f
62 ;;;; DEBUG-FUN objects
68 ;; KLUDGE: Courtesy of more than a decade of, ah, organic growth in
69 ;; CMU CL, there are two distinct -- but coupled -- mechanisms to
70 ;; finding the name of a function. The slot here is one mechanism
71 ;; (used in CMU CL to look up names in the debugger, e.g. in
72 ;; BACKTRACE). The other mechanism is the NAME slot in function
73 ;; primitive objects (used in CMU CL to look up names elsewhere,
74 ;; e.g. in CL:FUNCTION-LAMBDA-EXPRESSION and in CL:DESCRIBE).
75 ;;
76 ;; They're coupled by the way that DEBUG-FUN objects are looked up.
77 ;; A list of DEBUG-FUN objects is maintained for each COMPONENT. To
78 ;; figure out which DEBUG-FUN object corresponds to your FUNCTION
79 ;; object, you compare the name values of each. -- WHN 2001-12-20
81 ;; The kind of function (same as FUNCTIONAL-KIND):
83 ;; a description of variable locations for this function, in alphabetical
84 ;; order by name; or NIL if no information is available
85 ;;
86 ;; The variable entries are alphabetically ordered. This ordering is
87 ;; used in lifetime info to refer to variables: the first entry is
88 ;; 0, the second entry is 1, etc. Variable numbers are *not* the
89 ;; byte index at which the representation of the location starts.
90 ;;
91 ;; Each entry is:
92 ;; * a FLAGS value, which is a FIXNUM with various
93 ;; COMPILED-DEBUG-FUN-FOO bits set
94 ;; * the symbol which names this variable, unless debug info
95 ;; is minimal
96 ;; * the variable ID, when it has one
97 ;; * SC-offset of primary location, if it has one
98 ;; * SC-offset of save location, if it has one
100 ;; a vector of the packed binary representation of the
101 ;; COMPILED-DEBUG-BLOCKs in this function, in the order that the
102 ;; blocks were emitted. The first block is the start of the
103 ;; function. This slot may be NIL to save space.
104 ;;
105 ;; FIXME: The "packed binary representation" description in the
106 ;; comment above is the same as the description of the old
107 ;; representation of VARIABLES which doesn't work properly in SBCL
108 ;; (because it doesn't transform correctly under package renaming).
109 ;; Check whether this slot's data might have the same problem that
110 ;; that slot's data did.
112 ;; If all code locations in this function are in the same top level
113 ;; form, then this is the number of that form, otherwise NIL. If
114 ;; NIL, then each code location represented in the BLOCKS specifies
115 ;; the TLF number.
118 ;; a vector describing the variables that the argument values are
119 ;; stored in within this function. The locations are represented by
120 ;; the ordinal number of the entry in the VARIABLES slot value. The
121 ;; locations are in the order that the arguments are actually passed
122 ;; in, but special marker symbols can be interspersed to indicate
123 ;; the original call syntax:
124 ;;
125 ;; DELETED
126 ;; There was an argument to the function in this position, but it was
127 ;; deleted due to lack of references. The value cannot be recovered.
128 ;;
129 ;; SUPPLIED-P
130 ;; The following location is the supplied-p value for the preceding
131 ;; keyword or optional.
132 ;;
133 ;; OPTIONAL-ARGS
134 ;; Indicates that following unqualified args are optionals, not required.
135 ;;
136 ;; REST-ARG
137 ;; The following location holds the list of rest args.
138 ;;
139 ;; MORE-ARG
140 ;; The following two locations are the more arg context and count.
141 ;;
142 ;; <any other symbol>
143 ;; The following location is the value of the &KEY argument with the
144 ;; specified name.
145 ;;
146 ;; This may be NIL to save space. If no symbols are present, then
147 ;; this will be represented with an I-vector with sufficiently large
148 ;; element type. If this is :MINIMAL, then this means that the
149 ;; VARIABLES are all required arguments, and are in the order they
150 ;; appear in the VARIABLES vector. In other words, :MINIMAL stands
151 ;; in for a vector where every element holds its index.
153 ;; There are three alternatives for this slot:
154 ;;
155 ;; a VECTOR
156 ;; A vector of SC-OFFSETS describing the return locations. The
157 ;; vector element type is chosen to hold the largest element.
158 ;;
159 ;; :STANDARD
160 ;; The function returns using the standard unknown-values convention.
161 ;;
162 ;; :FIXED
163 ;; The function returns using the fixed-values convention, but
164 ;; in order to save space, we elected not to store a vector.
166 ;; SC-OFFSETs describing where the return PC and return FP are kept.
167 #!-fp-and-pc-standard-save
169 #!-fp-and-pc-standard-save
171 ;; SC-OFFSET for the number stack FP in this function, or NIL if no
172 ;; NFP allocated.
174 ;; The earliest PC in this function at which the environment is properly
175 ;; initialized (arguments moved from passing locations, etc.)
177 ;; The start of elsewhere code for this function (if any.)
180 #!+unwind-to-frame-and-call-vop
182 \f
183 ;;;; minimal debug function
185 ;;; The minimal debug info format compactly represents debug-info for some
186 ;;; cases where the other debug info (variables, blocks) is small enough so
187 ;;; that the per-function overhead becomes relatively large. The minimal
188 ;;; debug-info format can represent any function at level 0, and any fixed-arg
189 ;;; function at level 1.
190 ;;;
191 ;;; In the minimal format, the debug functions and function map are
192 ;;; packed into a single byte-vector which is placed in the
193 ;;; COMPILED-DEBUG-INFO-FUN-MAP. Because of this, all functions in a
194 ;;; component must be representable in minimal format for any function
195 ;;; to actually be dumped in minimal format. The vector is a sequence
196 ;;; of records in this format:
197 ;;; name representation + kind + return convention (single byte)
198 ;;; bit flags (single byte)
199 ;;; setf, nfp, variables
200 ;;; [package name length (as var-length int), if name is packaged]
201 ;;; [...package name bytes, if name is packaged]
202 ;;; [name length (as var-length int), if there is a name]
203 ;;; [...name bytes, if there is a name]
204 ;;; [variables length (as var-length int), if variables flag]
205 ;;; [...bytes holding variable descriptions]
206 ;;; If variables are dumped (level 1), then the variables are all
207 ;;; arguments (in order) with the minimal-arg bit set.
208 ;;; [If returns is specified, then the number of return values]
209 ;;; [...sequence of var-length ints holding sc-offsets of the return
210 ;;; value locations, if fixed return values are specified.]
211 ;;; return-pc location sc-offset (as var-length int)
212 ;;; old-fp location sc-offset (as var-length int)
213 ;;; [nfp location sc-offset (as var-length int), if nfp flag]
214 ;;; code-start-pc (as a var-length int)
215 ;;; This field implicitly encodes start of this function's code in the
216 ;;; function map, as a delta from the previous function's code start.
217 ;;; If the first function in the component, then this is the delta from
218 ;;; 0 (i.e. the absolute offset.)
219 ;;; start-pc (as a var-length int)
220 ;;; This encodes the environment start PC as an offset from the
221 ;;; code-start PC.
222 ;;; elsewhere-pc
223 ;;; This encodes the elsewhere code start for this function, as a delta
224 ;;; from the previous function's elsewhere code start. (i.e. the
225 ;;; encoding is the same as for code-start-pc.)
227 ;;; ### For functions with XEPs, name could be represented more simply
228 ;;; and compactly as some sort of info about with how to find the
229 ;;; function entry that this is a function for. Actually, you really
230 ;;; hardly need any info. You can just chain through the functions in
231 ;;; the component until you find the right one. Well, I guess you need
232 ;;; to at least know which function is an XEP for the real function
233 ;;; (which would be useful info anyway).
234 \f
235 ;;;; DEBUG SOURCE
237 ;;; There is one per compiled file and one per function compiled at
238 ;;; toplevel or loaded from source.
240 ;; (This is one of those structures where IWBNI we had multiple
241 ;; inheritance. The first four slots describe compilation of a
242 ;; file, the fifth and sixth compilation of a form processed by
243 ;; EVAL, and the seventh and eigth all compilation units; and these
244 ;; are orthogonal concerns that can combine independently.)
246 ;; When the DEBUG-SOURCE describes a file, the file's namestring.
247 ;; Otherwise, NIL.
249 ;; the universal time that the source was written, or NIL if
250 ;; unavailable
252 ;; the source path root number of the first form read from this
253 ;; source (i.e. the total number of forms converted previously in
254 ;; this compilation). (Note: this will always be 0 so long as the
255 ;; SOURCE-INFO structure has exactly one FILE-INFO.)
257 ;; The FILE-POSITIONs of the truly top level forms read from this
258 ;; file (if applicable). The vector element type will be chosen to
259 ;; hold the largest element.
262 ;; For functions processed by EVAL (including EVAL-WHEN and LOAD on
263 ;; a source file), the source form.
265 ;; This is the function whose source is the form.
268 ;; the universal time that the source was compiled
270 ;; Additional information from (WITH-COMPILATION-UNIT (:SOURCE-PLIST ...))
272 \f
273 ;;;; DEBUG-INFO structures
276 ;; Some string describing something about the code in this component.
278 ;; A DEBUG-SOURCE structure describing where the code for this
279 ;; component came from, in the order that forms were read.
292 ;; a SIMPLE-VECTOR of alternating DEBUG-FUN objects and fixnum
293 ;; PCs, used to map PCs to functions, so that we can figure out what
294 ;; function we were running in. Each function is valid between the
295 ;; PC before it (inclusive) and the PC after it (exclusive). The PCs
296 ;; are in sorted order, to allow binary search. We omit the first
297 ;; and last PC, since their values are 0 and the length of the code
298 ;; vector.
299 ;;
300 ;; KLUDGE: PC's can't always be represented by FIXNUMs, unless we're
301 ;; always careful to put our code in low memory. Is that how it
302 ;; works? Would this break if we used a more general memory map? --
303 ;; WHN 20000120