1 /* debug.h -- Describe generic debugging information.
2 Copyright (C) 1995, 1996 Free Software Foundation, Inc.
3 Written by Ian Lance Taylor <ian@cygnus.com>.
5 This file is part of GNU Binutils.
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 2 of the License, or
10 (at your option) any later version.
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with this program; if not, write to the Free Software
19 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
25 /* This header file describes a generic debugging information format.
26 We may eventually have readers which convert different formats into
27 this generic format, and writers which write it out. The initial
28 impetus for this was writing a convertor from stabs to HP IEEE-695
31 /* Different kinds of types. */
35 /* Indirect via a pointer. */
53 /* Union class (can this really happen?). */
54 DEBUG_KIND_UNION_CLASS,
55 /* Enumeration type. */
73 /* Const qualified type. */
75 /* Volatile qualified type. */
83 /* Different kinds of variables. */
87 /* A global variable. */
89 /* A static variable. */
91 /* A local static variable. */
93 /* A local variable. */
95 /* A register variable. */
99 /* Different kinds of function parameters. */
103 /* A stack based parameter. */
105 /* A register parameter. */
107 /* A stack based reference parameter. */
108 DEBUG_PARM_REFERENCE,
109 /* A register reference parameter. */
113 /* Different kinds of visibility. */
115 enum debug_visibility
117 /* A public field (e.g., a field in a C struct). */
118 DEBUG_VISIBILITY_PUBLIC,
119 /* A protected field. */
120 DEBUG_VISIBILITY_PROTECTED,
121 /* A private field. */
122 DEBUG_VISIBILITY_PRIVATE,
123 /* A field which should be ignored. */
124 DEBUG_VISIBILITY_IGNORE
129 typedef struct debug_type *debug_type;
131 #define DEBUG_TYPE_NULL ((debug_type) NULL)
133 /* A field in a struct or union. */
135 typedef struct debug_field *debug_field;
137 #define DEBUG_FIELD_NULL ((debug_field) NULL)
139 /* A base class for an object. */
141 typedef struct debug_baseclass *debug_baseclass;
143 #define DEBUG_BASECLASS_NULL ((debug_baseclass) NULL)
145 /* A method of an object. */
147 typedef struct debug_method *debug_method;
149 #define DEBUG_METHOD_NULL ((debug_method) NULL)
151 /* The arguments to a method function of an object. These indicate
152 which method to run. */
154 typedef struct debug_method_variant *debug_method_variant;
156 #define DEBUG_METHOD_VARIANT_NULL ((debug_method_variant) NULL)
158 /* This structure is passed to debug_write. It holds function
159 pointers that debug_write will call based on the accumulated
160 debugging information. */
162 struct debug_write_fns
164 /* This is called at the start of each new compilation unit with the
165 name of the main file in the new unit. */
166 boolean (*start_compilation_unit) PARAMS ((PTR, const char *));
168 /* This is called at the start of each source file within a
169 compilation unit, before outputting any global information for
170 that file. The argument is the name of the file. */
171 boolean (*start_source) PARAMS ((PTR, const char *));
173 /* Each writer must keep a stack of types. */
175 /* Push an empty type onto the type stack. This type can appear if
176 there is a reference to a type which is never defined. */
177 boolean (*empty_type) PARAMS ((PTR));
179 /* Push a void type onto the type stack. */
180 boolean (*void_type) PARAMS ((PTR));
182 /* Push an integer type onto the type stack, given the size and
183 whether it is unsigned. */
184 boolean (*int_type) PARAMS ((PTR, unsigned int, boolean));
186 /* Push a floating type onto the type stack, given the size. */
187 boolean (*float_type) PARAMS ((PTR, unsigned int));
189 /* Push a complex type onto the type stack, given the size. */
190 boolean (*complex_type) PARAMS ((PTR, unsigned int));
192 /* Push a boolean type onto the type stack, given the size. */
193 boolean (*bool_type) PARAMS ((PTR, unsigned int));
195 /* Push an enum type onto the type stack, given the tag, a NULL
196 terminated array of names and the associated values. If there is
197 no tag, the tag argument will be NULL. If this is an undefined
198 enum, the names and values arguments will be NULL. */
199 boolean (*enum_type) PARAMS ((PTR, const char *, const char **,
202 /* Pop the top type on the type stack, and push a pointer to that
203 type onto the type stack. */
204 boolean (*pointer_type) PARAMS ((PTR));
206 /* Pop the top type on the type stack, and push a function returning
207 that type onto the type stack. */
208 boolean (*function_type) PARAMS ((PTR));
210 /* Pop the top type on the type stack, and push a reference to that
211 type onto the type stack. */
212 boolean (*reference_type) PARAMS ((PTR));
214 /* Pop the top type on the type stack, and push a range of that type
215 with the given lower and upper bounds onto the type stack. */
216 boolean (*range_type) PARAMS ((PTR, bfd_signed_vma, bfd_signed_vma));
218 /* Push an array type onto the type stack. The top type on the type
219 stack is the range, and the next type on the type stack is the
220 element type. These should be popped before the array type is
221 pushed. The arguments are the lower bound, the upper bound, and
222 whether the array is a string. */
223 boolean (*array_type) PARAMS ((PTR, bfd_signed_vma, bfd_signed_vma,
226 /* Pop the top type on the type stack, and push a set of that type
227 onto the type stack. The argument indicates whether this set is
229 boolean (*set_type) PARAMS ((PTR, boolean));
231 /* Push an offset type onto the type stack. The top type on the
232 type stack is the target type, and the next type on the type
233 stack is the base type. These should be popped before the offset
235 boolean (*offset_type) PARAMS ((PTR));
237 /* Push a method type onto the type stack. If the second argument
238 is true, the top type on the stack is the class to which the
239 method belongs; otherwise, the class must be determined by the
240 class to which the method is attached. The third argument is the
241 number of argument types; these are pushed onto the type stack in
242 reverse order (the first type popped is the last argument to the
243 method). An argument type of -1 means that no argument in
244 formation is available. The next type on the type stack below
245 the domain and the argument types is the return type of the
246 method. All these types must be popped, and then the method type
248 boolean (*method_type) PARAMS ((PTR, boolean, int));
250 /* Pop the top type off the type stack, and push a const qualified
251 version of that type onto the type stack. */
252 boolean (*const_type) PARAMS ((PTR));
254 /* Pop the top type off the type stack, and push a volatile
255 qualified version of that type onto the type stack. */
256 boolean (*volatile_type) PARAMS ((PTR));
258 /* Start building a struct. This is followed by calls to the
259 struct_field function, and finished by a call to the
260 end_struct_type function. The second argument is the tag; this
261 will be NULL if there isn't one. The boolean argument is true
262 for a struct, false for a union. The unsigned int argument is
263 the size. If this is an undefined struct or union, the size will
264 be 0 and struct_field will not be called before end_struct_type
266 boolean (*start_struct_type) PARAMS ((PTR, const char *, boolean,
269 /* Add a field to the struct type currently being built. The type
270 of the field should be popped off the type stack. The arguments
271 are the name, the bit position, the bit size (may be zero if the
272 field is not packed), and the visibility. */
273 boolean (*struct_field) PARAMS ((PTR, const char *, bfd_vma, bfd_vma,
274 enum debug_visibility));
276 /* Finish building a struct, and push it onto the type stack. */
277 boolean (*end_struct_type) PARAMS ((PTR));
279 /* Start building a class. This is followed by calls to several
280 functions: struct_field, class_static_member, class_baseclass,
281 class_start_method, class_method_variant,
282 class_static_method_variant, and class_end_method. The class is
283 finished by a call to end_class_type. The second argument is the
284 tag; this will be NULL if there isn't one. The boolean argument
285 is true for a struct, false for a union. The next argument is
286 the size. The next argument is true if there is a virtual
287 function table; if there is, the next argument is true if the
288 virtual function table can be found in the type itself, and is
289 false if the type of the object holding the virtual function
290 table should be popped from the type stack. */
291 boolean (*start_class_type) PARAMS ((PTR, const char *, boolean,
292 unsigned int, boolean, boolean));
294 /* Add a static member to the class currently being built. The
295 arguments are the field name, the physical name, and the
296 visibility. The type must be popped off the type stack. */
297 boolean (*class_static_member) PARAMS ((PTR, const char *, const char *,
298 enum debug_visibility));
300 /* Add a baseclass to the class currently being built. The type of
301 the baseclass must be popped off the type stack. The arguments
302 are the bit position, whether the class is virtual, and the
304 boolean (*class_baseclass) PARAMS ((PTR, bfd_vma, boolean,
305 enum debug_visibility));
307 /* Start adding a method to the class currently being built. This
308 is followed by calls to class_method_variant and
309 class_static_method_variant to describe different variants of the
310 method which take different arguments. The method is finished
311 with a call to class_end_method. The argument is the method
313 boolean (*class_start_method) PARAMS ((PTR, const char *));
315 /* Describe a variant to the class method currently being built.
316 The type of the variant must be popped off the type stack. The
317 second argument is a string which is either the physical name of
318 the function or describes the argument types; see the comment for
319 debug_make_method variant. The following arguments are the
320 visibility, whether the variant is const, whether the variant is
321 volatile, the offset in the virtual function table, and whether
322 the context is on the type stack (below the variant type). */
323 boolean (*class_method_variant) PARAMS ((PTR, const char *,
324 enum debug_visibility,
328 /* Describe a static variant to the class method currently being
329 built. The arguments are the same as for class_method_variant,
330 except that the last two arguments are omitted. The type of the
331 variant must be popped off the type stack. */
332 boolean (*class_static_method_variant) PARAMS ((PTR, const char *,
333 enum debug_visibility,
336 /* Finish describing a class method. */
337 boolean (*class_end_method) PARAMS ((PTR));
339 /* Finish describing a class, and push it onto the type stack. */
340 boolean (*end_class_type) PARAMS ((PTR));
342 /* Push a type on the stack which was given a name by an earlier
344 boolean (*typedef_type) PARAMS ((PTR, const char *));
346 /* Push a type on the stack which was given a name by an earlier
348 boolean (*tag_type) PARAMS ((PTR, const char *, enum debug_type_kind));
350 /* Pop the type stack, and typedef it to the given name. */
351 boolean (*typdef) PARAMS ((PTR, const char *));
353 /* Pop the type stack, and declare it as a tagged struct or union or
354 enum or whatever. The tag passed down here is redundant, since
355 was also passed when enum_type, start_struct_type, or
356 start_class_type was called. */
357 boolean (*tag) PARAMS ((PTR, const char *));
359 /* This is called to record a named integer constant. */
360 boolean (*int_constant) PARAMS ((PTR, const char *, bfd_vma));
362 /* This is called to record a named floating point constant. */
363 boolean (*float_constant) PARAMS ((PTR, const char *, double));
365 /* This is called to record a typed integer constant. The type is
366 popped off the type stack. */
367 boolean (*typed_constant) PARAMS ((PTR, const char *, bfd_vma));
369 /* This is called to record a variable. The type is popped off the
371 boolean (*variable) PARAMS ((PTR, const char *, enum debug_var_kind,
374 /* Start writing out a function. The return type must be popped off
375 the stack. The boolean is true if the function is global. This
376 is followed by calls to function_parameter, followed by block
378 boolean (*start_function) PARAMS ((PTR, const char *, boolean));
380 /* Record a function parameter for the current function. The type
381 must be popped off the stack. */
382 boolean (*function_parameter) PARAMS ((PTR, const char *,
383 enum debug_parm_kind, bfd_vma));
385 /* Start writing out a block. There is at least one top level block
386 per function. Blocks may be nested. The argument is the
387 starting address of the block. */
388 boolean (*start_block) PARAMS ((PTR, bfd_vma));
390 /* Finish writing out a block. The argument is the ending address
392 boolean (*end_block) PARAMS ((PTR, bfd_vma));
394 /* Finish writing out a function. */
395 boolean (*end_function) PARAMS ((PTR));
397 /* Record line number information for the current compilation unit. */
398 boolean (*lineno) PARAMS ((PTR, const char *, unsigned long, bfd_vma));
401 /* Exported functions. */
403 /* The first argument to most of these functions is a handle. This
404 handle is returned by the debug_init function. The purpose of the
405 handle is to permit the debugging routines to not use static
406 variables, and hence to be reentrant. This would be useful for a
407 program which wanted to handle two executables simultaneously. */
409 /* Return a debugging handle. */
411 extern PTR debug_init PARAMS ((void));
413 /* Set the source filename. This implicitly starts a new compilation
416 extern boolean debug_set_filename PARAMS ((PTR, const char *));
418 /* Append a string to the source filename. */
420 extern boolean debug_append_filename PARAMS ((PTR, const char *));
422 /* Change source files to the given file name. This is used for
423 include files in a single compilation unit. */
425 extern boolean debug_start_source PARAMS ((PTR, const char *));
427 /* Record a function definition. This implicitly starts a function
428 block. The debug_type argument is the type of the return value.
429 The boolean indicates whether the function is globally visible.
430 The bfd_vma is the address of the start of the function. Currently
431 the parameter types are specified by calls to
432 debug_record_parameter. */
434 extern boolean debug_record_function
435 PARAMS ((PTR, const char *, debug_type, boolean, bfd_vma));
437 /* Record a parameter for the current function. */
439 extern boolean debug_record_parameter
440 PARAMS ((PTR, const char *, debug_type, enum debug_parm_kind, bfd_vma));
442 /* End a function definition. The argument is the address where the
445 extern boolean debug_end_function PARAMS ((PTR, bfd_vma));
447 /* Start a block in a function. All local information will be
448 recorded in this block, until the matching call to debug_end_block.
449 debug_start_block and debug_end_block may be nested. The argument
450 is the address at which this block starts. */
452 extern boolean debug_start_block PARAMS ((PTR, bfd_vma));
454 /* Finish a block in a function. This matches the call to
455 debug_start_block. The argument is the address at which this block
458 extern boolean debug_end_block PARAMS ((PTR, bfd_vma));
460 /* Associate a line number in the current source file with a given
463 extern boolean debug_record_line PARAMS ((PTR, unsigned long, bfd_vma));
465 /* Start a named common block. This is a block of variables that may
468 extern boolean debug_start_common_block PARAMS ((PTR, const char *));
470 /* End a named common block. */
472 extern boolean debug_end_common_block PARAMS ((PTR, const char *));
474 /* Record a named integer constant. */
476 extern boolean debug_record_int_const PARAMS ((PTR, const char *, bfd_vma));
478 /* Record a named floating point constant. */
480 extern boolean debug_record_float_const PARAMS ((PTR, const char *, double));
482 /* Record a typed constant with an integral value. */
484 extern boolean debug_record_typed_const
485 PARAMS ((PTR, const char *, debug_type, bfd_vma));
487 /* Record a label. */
489 extern boolean debug_record_label
490 PARAMS ((PTR, const char *, debug_type, bfd_vma));
492 /* Record a variable. */
494 extern boolean debug_record_variable
495 PARAMS ((PTR, const char *, debug_type, enum debug_var_kind, bfd_vma));
497 /* Make an indirect type. The first argument is a pointer to the
498 location where the real type will be placed. The second argument
499 is the type tag, if there is one; this may be NULL; the only
500 purpose of this argument is so that debug_get_type_name can return
501 something useful. This function may be used when a type is
502 referenced before it is defined. */
504 extern debug_type debug_make_indirect_type
505 PARAMS ((PTR, debug_type *, const char *));
507 /* Make a void type. */
509 extern debug_type debug_make_void_type PARAMS ((PTR));
511 /* Make an integer type of a given size. The boolean argument is true
512 if the integer is unsigned. */
514 extern debug_type debug_make_int_type PARAMS ((PTR, unsigned int, boolean));
516 /* Make a floating point type of a given size. FIXME: On some
517 platforms, like an Alpha, you probably need to be able to specify
520 extern debug_type debug_make_float_type PARAMS ((PTR, unsigned int));
522 /* Make a boolean type of a given size. */
524 extern debug_type debug_make_bool_type PARAMS ((PTR, unsigned int));
526 /* Make a complex type of a given size. */
528 extern debug_type debug_make_complex_type PARAMS ((PTR, unsigned int));
530 /* Make a structure type. The second argument is true for a struct,
531 false for a union. The third argument is the size of the struct.
532 The fourth argument is a NULL terminated array of fields. */
534 extern debug_type debug_make_struct_type
535 PARAMS ((PTR, boolean, bfd_vma, debug_field *));
537 /* Make an object type. The first three arguments after the handle
538 are the same as for debug_make_struct_type. The next arguments are
539 a NULL terminated array of base classes, a NULL terminated array of
540 methods, the type of the object holding the virtual function table
541 if it is not this object, and a boolean which is true if this
542 object has its own virtual function table. */
544 extern debug_type debug_make_object_type
545 PARAMS ((PTR, boolean, bfd_vma, debug_field *, debug_baseclass *,
546 debug_method *, debug_type, boolean));
548 /* Make an enumeration type. The arguments are a null terminated
549 array of strings, and an array of corresponding values. */
551 extern debug_type debug_make_enum_type
552 PARAMS ((PTR, const char **, bfd_signed_vma *));
554 /* Make a pointer to a given type. */
556 extern debug_type debug_make_pointer_type
557 PARAMS ((PTR, debug_type));
559 /* Make a function returning a given type. FIXME: We should be able
560 to record the parameter types. */
562 extern debug_type debug_make_function_type PARAMS ((PTR, debug_type));
564 /* Make a reference to a given type. */
566 extern debug_type debug_make_reference_type PARAMS ((PTR, debug_type));
568 /* Make a range of a given type from a lower to an upper bound. */
570 extern debug_type debug_make_range_type
571 PARAMS ((PTR, debug_type, bfd_signed_vma, bfd_signed_vma));
573 /* Make an array type. The second argument is the type of an element
574 of the array. The third argument is the type of a range of the
575 array. The fourth and fifth argument are the lower and upper
576 bounds, respectively (if the bounds are not known, lower should be
577 0 and upper should be -1). The sixth argument is true if this
578 array is actually a string, as in C. */
580 extern debug_type debug_make_array_type
581 PARAMS ((PTR, debug_type, debug_type, bfd_signed_vma, bfd_signed_vma,
584 /* Make a set of a given type. For example, a Pascal set type. The
585 boolean argument is true if this set is actually a bitstring, as in
588 extern debug_type debug_make_set_type PARAMS ((PTR, debug_type, boolean));
590 /* Make a type for a pointer which is relative to an object. The
591 second argument is the type of the object to which the pointer is
592 relative. The third argument is the type that the pointer points
595 extern debug_type debug_make_offset_type
596 PARAMS ((PTR, debug_type, debug_type));
598 /* Make a type for a method function. The second argument is the
599 return type, the third argument is the domain, and the fourth
600 argument is a NULL terminated array of argument types. The domain
601 and the argument array may be NULL, in which case this is a stub
602 method and that information is not available. Stabs debugging uses
603 this, and gets the argument types from the mangled name. */
605 extern debug_type debug_make_method_type
606 PARAMS ((PTR, debug_type, debug_type, debug_type *));
608 /* Make a const qualified version of a given type. */
610 extern debug_type debug_make_const_type PARAMS ((PTR, debug_type));
612 /* Make a volatile qualified version of a given type. */
614 extern debug_type debug_make_volatile_type PARAMS ((PTR, debug_type));
616 /* Make an undefined tagged type. For example, a struct which has
617 been mentioned, but not defined. */
619 extern debug_type debug_make_undefined_tagged_type
620 PARAMS ((PTR, const char *, enum debug_type_kind));
622 /* Make a base class for an object. The second argument is the base
623 class type. The third argument is the bit position of this base
624 class in the object (always 0 unless doing multiple inheritance).
625 The fourth argument is whether this is a virtual class. The fifth
626 argument is the visibility of the base class. */
628 extern debug_baseclass debug_make_baseclass
629 PARAMS ((PTR, debug_type, bfd_vma, boolean, enum debug_visibility));
631 /* Make a field for a struct. The second argument is the name. The
632 third argument is the type of the field. The fourth argument is
633 the bit position of the field. The fifth argument is the size of
634 the field (it may be zero). The sixth argument is the visibility
637 extern debug_field debug_make_field
638 PARAMS ((PTR, const char *, debug_type, bfd_vma, bfd_vma,
639 enum debug_visibility));
641 /* Make a static member of an object. The second argument is the
642 name. The third argument is the type of the member. The fourth
643 argument is the physical name of the member (i.e., the name as a
644 global variable). The fifth argument is the visibility of the
647 extern debug_field debug_make_static_member
648 PARAMS ((PTR, const char *, debug_type, const char *,
649 enum debug_visibility));
651 /* Make a method. The second argument is the name, and the third
652 argument is a NULL terminated array of method variants. Each
653 method variant is a method with this name but with different
656 extern debug_method debug_make_method
657 PARAMS ((PTR, const char *, debug_method_variant *));
659 /* Make a method variant. The second argument is either the physical
660 name of the function, or the encoded argument types, depending upon
661 whether the third argument specifies the argument types or not.
662 The third argument is the type of the function. The fourth
663 argument is the visibility. The fifth argument is whether this is
664 a const function. The sixth argument is whether this is a volatile
665 function. The seventh argument is the offset in the virtual
666 function table, if any. The eighth argument is the virtual
667 function context. FIXME: Are the const and volatile arguments
668 necessary? Could we just use debug_make_const_type? The handling
669 of the second argument is biased toward the way that stabs works. */
671 extern debug_method_variant debug_make_method_variant
672 PARAMS ((PTR, const char *, debug_type, enum debug_visibility, boolean,
673 boolean, bfd_vma, debug_type));
675 /* Make a static method argument. The arguments are the same as for
676 debug_make_method_variant, except that the last two are omitted
677 since a static method can not also be virtual. */
679 extern debug_method_variant debug_make_static_method_variant
680 PARAMS ((PTR, const char *, debug_type, enum debug_visibility, boolean,
683 /* Name a type. This returns a new type with an attached name. */
685 extern debug_type debug_name_type PARAMS ((PTR, const char *, debug_type));
687 /* Give a tag to a type, such as a struct or union. This returns a
688 new type with an attached tag. */
690 extern debug_type debug_tag_type PARAMS ((PTR, const char *, debug_type));
692 /* Record the size of a given type. */
694 extern boolean debug_record_type_size PARAMS ((PTR, debug_type, unsigned int));
696 /* Find a tagged type. */
698 extern debug_type debug_find_tagged_type
699 PARAMS ((PTR, const char *, enum debug_type_kind));
701 /* Get the name of a type. */
703 extern const char *debug_get_type_name PARAMS ((PTR, debug_type));
705 /* Write out the recorded debugging information. This takes a set of
706 function pointers which are called to do the actual writing. The
707 first PTR is the debugging handle. The second PTR is a handle
708 which is passed to the functions. */
710 extern boolean debug_write PARAMS ((PTR, const struct debug_write_fns *, PTR));