1 ;;;; structures used for recording debugger information
3 ;;;; This software is part of the SBCL system. See the README file for
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.
19 ;;;; We represent the place where some value is stored with a SC-OFFSET,
20 ;;;; which is the SC number and offset encoded as an integer.
22 (defconstant sc-offset-scn-byte (byte 5 0))
23 (defconstant sc-offset-offset-byte (byte 22 5))
24 (def!type sc-offset () '(unsigned-byte 27))
26 (defmacro make-sc-offset (scn offset)
27 `(dpb ,scn sc-offset-scn-byte
28 (dpb ,offset sc-offset-offset-byte 0)))
30 (defmacro sc-offset-scn (sco) `(ldb sc-offset-scn-byte ,sco))
31 (defmacro sc-offset-offset (sco) `(ldb sc-offset-offset-byte ,sco))
33 ;;;; flags for compiled debug variables
35 ;;; FIXME: old CMU CL representation follows:
36 ;;; Compiled debug variables are in a packed binary representation in the
37 ;;; DEBUG-FUNCTION-VARIABLES:
38 ;;; single byte of boolean flags:
42 ;;; has distinct save location
43 ;;; has ID (name not unique in this fun)
44 ;;; minimal debug-info argument (name generated as ARG-0, ...)
45 ;;; deleted: placeholder for unused minimal argument
46 ;;; [name length in bytes (as var-length integer), if not minimal]
47 ;;; [...name bytes..., if not minimal]
48 ;;; [if packaged, var-length integer that is package name length]
49 ;;; ...package name bytes...]
50 ;;; [If has ID, ID as var-length integer]
51 ;;; SC-Offset of primary location (as var-length integer)
52 ;;; [If has save SC, SC-Offset of save location (as var-length integer)]
54 ;;; FIXME: The first two are no longer used in SBCL.
55 ;;;(defconstant compiled-debug-var-uninterned #b00000001)
56 ;;;(defconstant compiled-debug-var-packaged #b00000010)
57 (defconstant compiled-debug-var-environment-live #b00000100)
58 (defconstant compiled-debug-var-save-loc-p #b00001000)
59 (defconstant compiled-debug-var-id-p #b00010000)
60 (defconstant compiled-debug-var-minimal-p #b00100000)
61 (defconstant compiled-debug-var-deleted-p #b01000000)
63 ;;;; compiled debug blocks
65 ;;;; Compiled debug blocks are in a packed binary representation in the
66 ;;;; DEBUG-FUNCTION-BLOCKS:
67 ;;;; number of successors + bit flags (single byte)
69 ;;;; ...ordinal number of each successor in the function's blocks vector...
70 ;;;; number of locations in this block
71 ;;;; kind of first location (single byte)
72 ;;;; delta from previous PC (or from 0 if first location in function.)
73 ;;;; [offset of first top-level form, if no function TLF-NUMBER]
74 ;;;; form number of first source form
75 ;;;; first live mask (length in bytes determined by number of VARIABLES)
76 ;;;; ...more <kind, delta, top-level form offset, form-number, live-set>
79 (defconstant compiled-debug-block-nsucc-byte (byte 2 0))
80 (defconstant compiled-debug-block-elsewhere-p #b00000100)
82 (defconstant compiled-code-location-kind-byte (byte 3 0))
83 (defconstant compiled-code-location-kinds
84 '#(:unknown-return :known-return :internal-error :non-local-exit
85 :block-start :call-site :single-value-return :non-local-entry))
87 ;;;; DEBUG-FUNCTION objects
89 (def!struct (debug-function (:constructor nil)))
91 (def!struct (compiled-debug-function (:include debug-function)
92 #-sb-xc-host (:pure t))
93 ;; The name of this function. If from a DEFUN, etc., then this is the
94 ;; function name, otherwise it is a descriptive string.
95 (name (required-argument) :type (or simple-string cons symbol))
96 ;; The kind of function (same as FUNCTIONAL-KIND):
97 (kind nil :type (member nil :optional :external :top-level :cleanup))
98 ;; a description of variable locations for this function, in alphabetical
99 ;; order by name; or NIL if no information is available
101 ;; The variable entries are alphabetically ordered. This ordering is used in
102 ;; lifetime info to refer to variables: the first entry is 0, the second
103 ;; entry is 1, etc. Variable numbers are *not* the byte index at which the
104 ;; representation of the location starts.
107 ;; * a FLAGS value, which is a FIXNUM with various
108 ;; COMPILED-DEBUG-FUNCTION-FOO bits set
109 ;; * the symbol which names this variable, unless debug info is minimal
110 ;; * the variable ID, when it has one
111 ;; * SC-offset of primary location, if it has one
112 ;; * SC-offset of save location, if it has one
113 (variables nil :type (or simple-vector null))
114 ;; A vector of the packed binary representation of the COMPILED-DEBUG-BLOCKs
115 ;; in this function, in the order that the blocks were emitted. The first
116 ;; block is the start of the function. This slot may be NIL to save space.
118 ;; FIXME: The "packed binary representation" description in the comment
119 ;; above is the same as the description of the old representation of
120 ;; VARIABLES which doesn't work properly in SBCL (because it doesn't
121 ;; transform correctly under package renaming). Check whether this slot's
122 ;; data might have the same problem that that slot's data did.
123 (blocks nil :type (or (simple-array (unsigned-byte 8) (*)) null))
124 ;; If all code locations in this function are in the same top-level form,
125 ;; then this is the number of that form, otherwise NIL. If NIL, then each
126 ;; code location represented in the BLOCKS specifies the TLF number.
127 (tlf-number nil :type (or index null))
128 ;; A vector describing the variables that the argument values are stored in
129 ;; within this function. The locations are represented by the ordinal number
130 ;; of the entry in the VARIABLES slot value. The locations are in the order
131 ;; that the arguments are actually passed in, but special marker symbols can
132 ;; be interspersed to indicate the original call syntax:
135 ;; There was an argument to the function in this position, but it was
136 ;; deleted due to lack of references. The value cannot be recovered.
139 ;; The following location is the supplied-p value for the preceding
140 ;; keyword or optional.
143 ;; Indicates that following unqualified args are optionals, not required.
146 ;; The following location holds the list of rest args.
149 ;; The following two locations are the more arg context and count.
151 ;; <any other symbol>
152 ;; The following location is the value of the keyword argument with the
155 ;; This may be NIL to save space. If no symbols are present, then this will
156 ;; be represented with an I-vector with sufficiently large element type. If
157 ;; this is :MINIMAL, then this means that the VARIABLES are all required
158 ;; arguments, and are in the order they appear in the VARIABLES vector. In
159 ;; other words, :MINIMAL stands in for a vector where every element holds its
161 (arguments nil :type (or (simple-array * (*)) (member :minimal nil)))
162 ;; There are three alternatives for this slot:
165 ;; A vector of SC-OFFSETS describing the return locations. The
166 ;; vector element type is chosen to hold the largest element.
169 ;; The function returns using the standard unknown-values convention.
172 ;; The function returns using the fixed-values convention, but
173 ;; in order to save space, we elected not to store a vector.
174 (returns :fixed :type (or (simple-array * (*)) (member :standard :fixed)))
175 ;; SC-Offsets describing where the return PC and return FP are kept.
176 (return-pc (required-argument) :type sc-offset)
177 (old-fp (required-argument) :type sc-offset)
178 ;; SC-Offset for the number stack FP in this function, or NIL if no NFP
180 (nfp nil :type (or sc-offset null))
181 ;; The earliest PC in this function at which the environment is properly
182 ;; initialized (arguments moved from passing locations, etc.)
183 (start-pc (required-argument) :type index)
184 ;; The start of elsewhere code for this function (if any.)
185 (elsewhere-pc (required-argument) :type index))
187 ;;;; minimal debug function
189 ;;; The minimal debug info format compactly represents debug-info for some
190 ;;; cases where the other debug info (variables, blocks) is small enough so
191 ;;; that the per-function overhead becomes relatively large. The minimal
192 ;;; debug-info format can represent any function at level 0, and any fixed-arg
193 ;;; function at level 1.
195 ;;; In the minimal format, the debug functions and function map are packed into
196 ;;; a single byte-vector which is placed in the
197 ;;; COMPILED-DEBUG-INFO-FUNCTION-MAP. Because of this, all functions in a
198 ;;; component must be representable in minimal format for any function to
199 ;;; actually be dumped in minimal format. The vector is a sequence of records
201 ;;; name representation + kind + return convention (single byte)
202 ;;; bit flags (single byte)
203 ;;; setf, nfp, variables
204 ;;; [package name length (as var-length int), if name is packaged]
205 ;;; [...package name bytes, if name is packaged]
206 ;;; [name length (as var-length int), if there is a name]
207 ;;; [...name bytes, if there is a name]
208 ;;; [variables length (as var-length int), if variables flag]
209 ;;; [...bytes holding variable descriptions]
210 ;;; If variables are dumped (level 1), then the variables are all
211 ;;; arguments (in order) with the minimal-arg bit set.
212 ;;; [If returns is specified, then the number of return values]
213 ;;; [...sequence of var-length ints holding sc-offsets of the return
214 ;;; value locations, if fixed return values are specified.]
215 ;;; return-pc location sc-offset (as var-length int)
216 ;;; old-fp location sc-offset (as var-length int)
217 ;;; [nfp location sc-offset (as var-length int), if nfp flag]
218 ;;; code-start-pc (as a var-length int)
219 ;;; This field implicitly encodes start of this function's code in the
220 ;;; function map, as a delta from the previous function's code start.
221 ;;; If the first function in the component, then this is the delta from
222 ;;; 0 (i.e. the absolute offset.)
223 ;;; start-pc (as a var-length int)
224 ;;; This encodes the environment start PC as an offset from the
227 ;;; This encodes the elsewhere code start for this function, as a delta
228 ;;; from the previous function's elsewhere code start. (i.e. the
229 ;;; encoding is the same as for code-start-pc.)
232 ### For functions with XEPs, name could be represented more simply and
233 compactly as some sort of info about with how to find the function-entry that
234 this is a function for. Actually, you really hardly need any info. You can
235 just chain through the functions in the component until you find the right one.
236 Well, I guess you need to at least know which function is an XEP for the real
237 function (which would be useful info anyway).
240 ;;; Following are definitions of bit-fields in the first byte of the minimal
242 (defconstant minimal-debug-function-name-symbol 0)
243 (defconstant minimal-debug-function-name-packaged 1)
244 (defconstant minimal-debug-function-name-uninterned 2)
245 (defconstant minimal-debug-function-name-component 3)
246 (defconstant minimal-debug-function-name-style-byte (byte 2 0))
247 (defconstant minimal-debug-function-kind-byte (byte 3 2))
248 (defconstant minimal-debug-function-kinds
249 '#(nil :optional :external :top-level :cleanup))
250 (defconstant minimal-debug-function-returns-standard 0)
251 (defconstant minimal-debug-function-returns-specified 1)
252 (defconstant minimal-debug-function-returns-fixed 2)
253 (defconstant minimal-debug-function-returns-byte (byte 2 5))
255 ;;; The following are bit-flags in the second byte of the minimal debug
258 ;;; If true, wrap (SETF ...) around the name.
259 (defconstant minimal-debug-function-setf-bit (ash 1 0))
261 ;;; If true, there is a NFP.
262 (defconstant minimal-debug-function-nfp-bit (ash 1 1))
264 ;;; If true, variables (hence arguments) have been dumped.
265 (defconstant minimal-debug-function-variables-bit (ash 1 2))
269 (def!struct (debug-source #-sb-xc-host (:pure t))
270 ;; This slot indicates where the definition came from:
271 ;; :File - from a file (Compile-File)
272 ;; :Lisp - from Lisp (Compile)
273 (from (required-argument) :type (member :file :lisp))
274 ;; If :File, the file name, if :Lisp or :Stream, then a vector of the
275 ;; top-level forms. When from COMPILE, form 0 is #'(LAMBDA ...).
277 ;; File comment for this file, if any.
278 (comment nil :type (or simple-string null))
279 ;; The universal time that the source was written, or NIL if unavailable.
280 (created nil :type (or unsigned-byte null))
281 ;; The universal time that the source was compiled.
282 (compiled (required-argument) :type unsigned-byte)
283 ;; The source path root number of the first form read from this source (i.e.
284 ;; the total number of forms converted previously in this compilation.)
285 (source-root 0 :type index)
286 ;; The file-positions of each truly top-level form read from this file (if
287 ;; applicable). The vector element type will be chosen to hold the largest
288 ;; element. May be null to save space.
289 (start-positions nil :type (or (simple-array * (*)) null))
290 ;; If from :LISP, this is the function whose source is form 0.
293 ;;;; DEBUG-INFO structures
295 (def!struct debug-info
296 ;; Some string describing something about the code in this component.
297 (name (required-argument) :type simple-string)
298 ;; A list of DEBUG-SOURCE structures describing where the code for this
299 ;; component came from, in the order that they were read.
301 ;; *** NOTE: the offset of this slot is wired into the fasl dumper so that it
302 ;; *** can backpatch the source info when compilation is complete.
303 (source nil :type list))
305 (def!struct (compiled-debug-info
306 (:include debug-info)
307 #-sb-xc-host (:pure t))
308 ;; a simple-vector of alternating DEBUG-FUNCTION objects and fixnum PCs,
309 ;; used to map PCs to functions, so that we can figure out what function we
310 ;; were running in. Each function is valid between the PC before it
311 ;; (inclusive) and the PC after it (exclusive). The PCs are in sorted order,
312 ;; to allow binary search. We omit the first and last PC, since their values
313 ;; are 0 and the length of the code vector.
315 ;; KLUDGE: PC's can't always be represented by FIXNUMs, unless we're always
316 ;; careful to put our code in low memory. Is that how it works? Would this
317 ;; break if we used a more general memory map? -- WHN 20000120
318 (function-map (required-argument) :type simple-vector :read-only t))