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