0.7.13.7:
[sbcl.git] / src / code / debug-info.lisp
1 ;;;; structures used for recording debugger information
2
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.
11
12 (in-package "SB!C")
13 \f
14 ;;;; SC-OFFSETs
15 ;;;;
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.
18
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))
22
23 (defmacro make-sc-offset (scn offset)
24   `(dpb ,scn sc-offset-scn-byte
25         (dpb ,offset sc-offset-offset-byte 0)))
26
27 (defmacro sc-offset-scn (sco) `(ldb sc-offset-scn-byte ,sco))
28 (defmacro sc-offset-offset (sco) `(ldb sc-offset-offset-byte ,sco))
29 \f
30 ;;;; flags for compiled debug variables
31
32 ;;; FIXME: old CMU CL representation follows:
33 ;;;    Compiled debug variables are in a packed binary representation in the
34 ;;; DEBUG-FUN-VARS:
35 ;;;    single byte of boolean flags:
36 ;;;     uninterned name
37 ;;;        packaged name
38 ;;;     environment-live
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)]
50
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 (def!constant compiled-debug-var-environment-live       #b00000100)
55 (def!constant compiled-debug-var-save-loc-p             #b00001000)
56 (def!constant compiled-debug-var-id-p                   #b00010000)
57 (def!constant compiled-debug-var-minimal-p              #b00100000)
58 (def!constant compiled-debug-var-deleted-p              #b01000000)
59 \f
60 ;;;; compiled debug blocks
61 ;;;;
62 ;;;;    Compiled debug blocks are in a packed binary representation in the
63 ;;;; DEBUG-FUN-BLOCKS:
64 ;;;;    number of successors + bit flags (single byte)
65 ;;;;    elsewhere-p
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>
74 ;;;;       tuples...
75
76 (defconstant-eqx compiled-debug-block-nsucc-byte (byte 2 0) #'equalp)
77 (def!constant compiled-debug-block-elsewhere-p #b00000100)
78
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))
83 \f
84 ;;;; DEBUG-FUN objects
85
86 (def!struct (debug-fun (:constructor nil)))
87
88 (def!struct (compiled-debug-fun (:include debug-fun)
89                                 #-sb-xc-host (:pure t))
90   ;; KLUDGE: Courtesy of more than a decade of, ah, organic growth in
91   ;; CMU CL, there are two distinct -- but coupled -- mechanisms to
92   ;; finding the name of a function. The slot here is one mechanism
93   ;; (used in CMU CL to look up names in the debugger, e.g. in
94   ;; BACKTRACE). The other mechanism is the the NAME slot in function
95   ;; primitive objects (used in CMU CL to look up names elsewhere,
96   ;; e.g. in CL:FUNCTION-LAMBDA-EXPRESSION and in CL:DESCRIBE).
97   ;;
98   ;; They're coupled by the way that DEBUG-FUN objects are looked up.
99   ;; A list of DEBUG-FUN objects is maintained for each COMPONENT. To
100   ;; figure out which DEBUG-FUN object corresponds to your FUNCTION
101   ;; object, you compare the name values of each. -- WHN 2001-12-20
102   (name (missing-arg) :type (or simple-string cons symbol))
103   ;; The kind of function (same as FUNCTIONAL-KIND):
104   (kind nil :type (member nil :optional :external :toplevel :cleanup))
105   ;; a description of variable locations for this function, in alphabetical
106   ;; order by name; or NIL if no information is available
107   ;;
108   ;; The variable entries are alphabetically ordered. This ordering is
109   ;; used in lifetime info to refer to variables: the first entry is
110   ;; 0, the second entry is 1, etc. Variable numbers are *not* the
111   ;; byte index at which the representation of the location starts.
112   ;;
113   ;; Each entry is:
114   ;;   * a FLAGS value, which is a FIXNUM with various
115   ;;     COMPILED-DEBUG-FUN-FOO bits set
116   ;;   * the symbol which names this variable, unless debug info
117   ;;     is minimal
118   ;;   * the variable ID, when it has one
119   ;;   * SC-offset of primary location, if it has one
120   ;;   * SC-offset of save location, if it has one
121   (vars nil :type (or simple-vector null))
122   ;; a vector of the packed binary representation of the
123   ;; COMPILED-DEBUG-BLOCKs in this function, in the order that the
124   ;; blocks were emitted. The first block is the start of the
125   ;; function. This slot may be NIL to save space.
126   ;;
127   ;; FIXME: The "packed binary representation" description in the
128   ;; comment above is the same as the description of the old
129   ;; representation of VARIABLES which doesn't work properly in SBCL
130   ;; (because it doesn't transform correctly under package renaming).
131   ;; Check whether this slot's data might have the same problem that
132   ;; that slot's data did.
133   (blocks nil :type (or (simple-array (unsigned-byte 8) (*)) null))
134   ;; If all code locations in this function are in the same top level
135   ;; form, then this is the number of that form, otherwise NIL. If
136   ;; NIL, then each code location represented in the BLOCKS specifies
137   ;; the TLF number.
138   (tlf-number nil :type (or index null))
139   ;; a vector describing the variables that the argument values are
140   ;; stored in within this function. The locations are represented by
141   ;; the ordinal number of the entry in the VARIABLES slot value. The
142   ;; locations are in the order that the arguments are actually passed
143   ;; in, but special marker symbols can be interspersed to indicate
144   ;; the original call syntax:
145   ;;
146   ;; DELETED
147   ;;    There was an argument to the function in this position, but it was
148   ;;    deleted due to lack of references. The value cannot be recovered.
149   ;;
150   ;; SUPPLIED-P
151   ;;    The following location is the supplied-p value for the preceding
152   ;;    keyword or optional.
153   ;;
154   ;; OPTIONAL-ARGS
155   ;;    Indicates that following unqualified args are optionals, not required.
156   ;;
157   ;; REST-ARG
158   ;;    The following location holds the list of rest args.
159   ;;
160   ;; MORE-ARG
161   ;;    The following two locations are the more arg context and count.
162   ;;
163   ;; <any other symbol>
164   ;;    The following location is the value of the &KEY argument with the
165   ;;    specified name.
166   ;;
167   ;; This may be NIL to save space. If no symbols are present, then
168   ;; this will be represented with an I-vector with sufficiently large
169   ;; element type. If this is :MINIMAL, then this means that the
170   ;; VARIABLES are all required arguments, and are in the order they
171   ;; appear in the VARIABLES vector. In other words, :MINIMAL stands
172   ;; in for a vector where every element holds its index.
173   (arguments nil :type (or (simple-array * (*)) (member :minimal nil)))
174   ;; There are three alternatives for this slot:
175   ;;
176   ;; a VECTOR
177   ;;    A vector of SC-OFFSETS describing the return locations. The
178   ;;    vector element type is chosen to hold the largest element.
179   ;;
180   ;; :STANDARD
181   ;;    The function returns using the standard unknown-values convention.
182   ;;
183   ;; :FIXED
184   ;;    The function returns using the fixed-values convention, but
185   ;;    in order to save space, we elected not to store a vector.
186   (returns :fixed :type (or (simple-array * (*)) (member :standard :fixed)))
187   ;; SC-OFFSETs describing where the return PC and return FP are kept.
188   (return-pc (missing-arg) :type sc-offset)
189   (old-fp (missing-arg) :type sc-offset)
190   ;; SC-OFFSET for the number stack FP in this function, or NIL if no
191   ;; NFP allocated.
192   (nfp nil :type (or sc-offset null))
193   ;; The earliest PC in this function at which the environment is properly
194   ;; initialized (arguments moved from passing locations, etc.)
195   (start-pc (missing-arg) :type index)
196   ;; The start of elsewhere code for this function (if any.)
197   (elsewhere-pc (missing-arg) :type index))
198 \f
199 ;;;; minimal debug function
200
201 ;;; The minimal debug info format compactly represents debug-info for some
202 ;;; cases where the other debug info (variables, blocks) is small enough so
203 ;;; that the per-function overhead becomes relatively large. The minimal
204 ;;; debug-info format can represent any function at level 0, and any fixed-arg
205 ;;; function at level 1.
206 ;;;
207 ;;; In the minimal format, the debug functions and function map are
208 ;;; packed into a single byte-vector which is placed in the
209 ;;; COMPILED-DEBUG-INFO-FUN-MAP. Because of this, all functions in a
210 ;;; component must be representable in minimal format for any function
211 ;;; to actually be dumped in minimal format. The vector is a sequence
212 ;;; of records in this format:
213 ;;;    name representation + kind + return convention (single byte)
214 ;;;    bit flags (single byte)
215 ;;;     setf, nfp, variables
216 ;;;    [package name length (as var-length int), if name is packaged]
217 ;;;    [...package name bytes, if name is packaged]
218 ;;;    [name length (as var-length int), if there is a name]
219 ;;;    [...name bytes, if there is a name]
220 ;;;    [variables length (as var-length int), if variables flag]
221 ;;;    [...bytes holding variable descriptions]
222 ;;;     If variables are dumped (level 1), then the variables are all
223 ;;;     arguments (in order) with the minimal-arg bit set.
224 ;;;    [If returns is specified, then the number of return values]
225 ;;;    [...sequence of var-length ints holding sc-offsets of the return
226 ;;;     value locations, if fixed return values are specified.]
227 ;;;    return-pc location sc-offset (as var-length int)
228 ;;;    old-fp location sc-offset (as var-length int)
229 ;;;    [nfp location sc-offset (as var-length int), if nfp flag]
230 ;;;    code-start-pc (as a var-length int)
231 ;;;     This field implicitly encodes start of this function's code in the
232 ;;;     function map, as a delta from the previous function's code start.
233 ;;;     If the first function in the component, then this is the delta from
234 ;;;     0 (i.e. the absolute offset.)
235 ;;;    start-pc (as a var-length int)
236 ;;;     This encodes the environment start PC as an offset from the
237 ;;;     code-start PC.
238 ;;;    elsewhere-pc
239 ;;;     This encodes the elsewhere code start for this function, as a delta
240 ;;;     from the previous function's elsewhere code start. (i.e. the
241 ;;;     encoding is the same as for code-start-pc.)
242
243 ;;; ### For functions with XEPs, name could be represented more simply
244 ;;; and compactly as some sort of info about with how to find the
245 ;;; function entry that this is a function for. Actually, you really
246 ;;; hardly need any info. You can just chain through the functions in
247 ;;; the component until you find the right one. Well, I guess you need
248 ;;; to at least know which function is an XEP for the real function
249 ;;; (which would be useful info anyway).
250 \f
251 ;;;; debug source
252
253 (def!struct (debug-source #-sb-xc-host (:pure t))
254   ;; This slot indicates where the definition came from:
255   ;;    :FILE - from a file (i.e. COMPILE-FILE)
256   ;;    :LISP - from Lisp (i.e. COMPILE)
257   (from (missing-arg) :type (member :file :lisp))
258   ;; If :FILE, the file name, if :LISP or :STREAM, then a vector of
259   ;; the top level forms. When from COMPILE, form 0 is #'(LAMBDA ...).
260   (name nil)
261   ;; the universal time that the source was written, or NIL if
262   ;; unavailable
263   (created nil :type (or unsigned-byte null))
264   ;; the universal time that the source was compiled
265   (compiled (missing-arg) :type unsigned-byte)
266   ;; the source path root number of the first form read from this
267   ;; source (i.e. the total number of forms converted previously in
268   ;; this compilation)
269   (source-root 0 :type index)
270   ;; The FILE-POSITIONs of the truly top level forms read from this
271   ;; file (if applicable). The vector element type will be chosen to
272   ;; hold the largest element. May be null to save space, or if
273   ;; :DEBUG-SOURCE-FORM is :LISP.
274   (start-positions nil :type (or (simple-array * (*)) null))
275   ;; If from :LISP, this is the function whose source is form 0.
276   (info nil))
277 \f
278 ;;;; DEBUG-INFO structures
279
280 (def!struct debug-info
281   ;; Some string describing something about the code in this component.
282   (name (missing-arg) :type simple-string)
283   ;; A list of DEBUG-SOURCE structures describing where the code for this
284   ;; component came from, in the order that they were read.
285   ;;
286   ;; KLUDGE: comment from CMU CL:
287   ;;   *** NOTE: the offset of this slot is wired into the fasl dumper 
288   ;;   *** so that it can backpatch the source info when compilation
289   ;;   *** is complete.
290   (source nil :type list))
291
292 (def!struct (compiled-debug-info
293              (:include debug-info)
294              #-sb-xc-host (:pure t))
295   ;; a SIMPLE-VECTOR of alternating DEBUG-FUN objects and fixnum
296   ;; PCs, used to map PCs to functions, so that we can figure out what
297   ;; function we were running in. Each function is valid between the
298   ;; PC before it (inclusive) and the PC after it (exclusive). The PCs
299   ;; are in sorted order, to allow binary search. We omit the first
300   ;; and last PC, since their values are 0 and the length of the code
301   ;; vector.
302   ;;
303   ;; KLUDGE: PC's can't always be represented by FIXNUMs, unless we're
304   ;; always careful to put our code in low memory. Is that how it
305   ;; works? Would this break if we used a more general memory map? --
306   ;; WHN 20000120
307   (fun-map (missing-arg) :type simple-vector :read-only t))