1 /* debug.h -- Describe generic debugging information.
2 Copyright (C) 1995 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 a NULL terminated
196 array of names and the associated values. */
197 boolean (*enum_type
) PARAMS ((PTR
, const char **, bfd_signed_vma
*));
199 /* Pop the top type on the type stack, and push a pointer to that
200 type onto the type stack. */
201 boolean (*pointer_type
) PARAMS ((PTR
));
203 /* Pop the top type on the type stack, and push a function returning
204 that type onto the type stack. */
205 boolean (*function_type
) PARAMS ((PTR
));
207 /* Pop the top type on the type stack, and push a reference to that
208 type onto the type stack. */
209 boolean (*reference_type
) PARAMS ((PTR
));
211 /* Pop the top type on the type stack, and push a range of that type
212 with the given lower and upper bounds onto the type stack. */
213 boolean (*range_type
) PARAMS ((PTR
, bfd_signed_vma
, bfd_signed_vma
));
215 /* Push an array type onto the type stack. The top type on the type
216 stack is the range, and the next type on the type stack is the
217 element type. These should be popped before the array type is
218 pushed. The arguments are the lower bound, the upper bound, and
219 whether the array is a string. */
220 boolean (*array_type
) PARAMS ((PTR
, bfd_signed_vma
, bfd_signed_vma
,
223 /* Pop the top type on the type stack, and push a set of that type
224 onto the type stack. The argument indicates whether this set is
226 boolean (*set_type
) PARAMS ((PTR
, boolean
));
228 /* Push an offset type onto the type stack. The top type on the
229 type stack is the target type, and the next type on the type
230 stack is the base type. These should be popped before the offset
232 boolean (*offset_type
) PARAMS ((PTR
));
234 /* Push a method type onto the type stack. If the second argument
235 is true, the top type on the stack is the class to which the
236 method belongs; otherwise, the class must be determined by the
237 class to which the method is attached. The third argument is the
238 number of argument types; these are pushed onto the type stack in
239 reverse order (the first type popped is the last argument to the
240 method). An argument type of -1 means that no argument in
241 formation is available. The next type on the type stack below
242 the domain and the argument types is the return type of the
243 method. All these types must be poppsed, and then the method
244 type must be pushed. */
245 boolean (*method_type
) PARAMS ((PTR
, boolean
, int));
247 /* Pop the top type off the type stack, and push a const qualified
248 version of that type onto the type stack. */
249 boolean (*const_type
) PARAMS ((PTR
));
251 /* Pop the top type off the type stack, and push a volatile
252 qualified version of that type onto the type stack. */
253 boolean (*volatile_type
) PARAMS ((PTR
));
255 /* Start building a struct. This is followed by calls to the
256 struct_field function, and finished by a call to the
257 end_struct_type function. The boolean argument is true for a
258 struct, false for a union. The unsigned int argument is the
260 boolean (*start_struct_type
) PARAMS ((PTR
, boolean
, unsigned int));
262 /* Add a field to the struct type currently being built. The type
263 of the field should be popped off the type stack. The arguments
264 are the name, the bit position, the bit size (may be zero if the
265 field is not packed), and the visibility. */
266 boolean (*struct_field
) PARAMS ((PTR
, const char *, bfd_vma
, bfd_vma
,
267 enum debug_visibility
));
269 /* Finish building a struct, and push it onto the type stack. */
270 boolean (*end_struct_type
) PARAMS ((PTR
));
272 /* Start building a class. This is followed by calls to several
273 functions: struct_field, class_static_member, class_baseclass,
274 class_start_method, class_method_variant,
275 class_static_method_variant, and class_end_method. The class is
276 finished by a call to end_class_type. The boolean argument is
277 true for a struct, false for a union. The next argument is the
278 size. The next argument is true if there is a virtual function
279 table; if there is, the next argument is true if the virtual
280 function table can be found in the type itself, and is false if
281 the type of the object holding the virtual function table should
282 be popped from the type stack. */
283 boolean (*start_class_type
) PARAMS ((PTR
, boolean
, unsigned int,
286 /* Add a static member to the class currently being built. The
287 arguments are the field name, the physical name, and the
289 boolean (*class_static_member
) PARAMS ((PTR
, const char *, const char *,
290 enum debug_visibility
));
292 /* Add a baseclass to the class currently being built. The type of
293 the baseclass must be popped off the type stack. The arguments
294 are the bit position, whether the class is virtual, and the
296 boolean (*class_baseclass
) PARAMS ((PTR
, bfd_vma
, boolean
,
297 enum debug_visibility
));
299 /* Start adding a method to the class currently being built. This
300 is followed by calls to class_method_variant and
301 class_static_method_variant to describe different variants of the
302 method which take different arguments. The method is finished
303 with a call to class_end_method. The argument is the method
305 boolean (*class_start_method
) PARAMS ((PTR
, const char *));
307 /* Describe a variant to the class method currently being built.
308 The type of the variant must be popped off the type stack. The
309 second argument is a string which is either the physical name of
310 the function or describes the argument types; see the comment for
311 debug_make_method variant. The following arguments are the
312 visibility, whether the variant is const, whether the variant is
313 volatile, the offset in the virtual function table, and whether
314 the context is on the type stack (below the variant type). */
315 boolean (*class_method_variant
) PARAMS ((PTR
, const char *,
316 enum debug_visibility
,
320 /* Describe a static variant to the class method currently being
321 built. The arguments are the same as for class_method_variant,
322 except that the last two arguments are omitted. */
323 boolean (*class_static_method_variant
) PARAMS ((PTR
, const char *,
324 enum debug_visibility
,
327 /* Finish describing a class method. */
328 boolean (*class_end_method
) PARAMS ((PTR
));
330 /* Finish describing a class, and push it onto the type stack. */
331 boolean (*end_class_type
) PARAMS ((PTR
));
333 /* Push a type on the stack which was given a name by an earlier
335 boolean (*typedef_type
) PARAMS ((PTR
, const char *));
337 /* Push a type on the stack which was given a name by an earlier
339 boolean (*tag_type
) PARAMS ((PTR
, const char *, enum debug_type_kind
));
341 /* Pop the type stack, and typedef it to the given name. */
342 boolean (*typdef
) PARAMS ((PTR
, const char *));
344 /* Pop the type stack, and declare it as a tagged struct or union or
346 boolean (*tag
) PARAMS ((PTR
, const char *));
348 /* This is called to record a named integer constant. */
349 boolean (*int_constant
) PARAMS ((PTR
, const char *, bfd_vma
));
351 /* This is called to record a named floating point constant. */
352 boolean (*float_constant
) PARAMS ((PTR
, const char *, double));
354 /* This is called to record a typed integer constant. The type is
355 popped off the type stack. */
356 boolean (*typed_constant
) PARAMS ((PTR
, const char *, bfd_vma
));
358 /* This is called to record a variable. The type is popped off the
360 boolean (*variable
) PARAMS ((PTR
, const char *, enum debug_var_kind
,
363 /* Start writing out a function. The return type must be popped off
364 the stack. The boolean is true if the function is global. This
365 is followed by calls to function_parameter, followed by block
367 boolean (*start_function
) PARAMS ((PTR
, const char *, boolean
));
369 /* Record a function parameter for the current function. The type
370 must be popped off the stack. */
371 boolean (*function_parameter
) PARAMS ((PTR
, const char *,
372 enum debug_parm_kind
, bfd_vma
));
374 /* Start writing out a block. There is at least one top level block
375 per function. Blocks may be nested. The argument is the
376 starting address of the block. */
377 boolean (*start_block
) PARAMS ((PTR
, bfd_vma
));
379 /* Record line number information for the current block. */
380 boolean (*lineno
) PARAMS ((PTR
, const char *, unsigned long, bfd_vma
));
382 /* Finish writing out a block. The argument is the ending address
384 boolean (*end_block
) PARAMS ((PTR
, bfd_vma
));
386 /* Finish writing out a function. */
387 boolean (*end_function
) PARAMS ((PTR
));
390 /* Exported functions. */
392 /* The first argument to most of these functions is a handle. This
393 handle is returned by the debug_init function. The purpose of the
394 handle is to permit the debugging routines to not use static
395 variables, and hence to be reentrant. This would be useful for a
396 program which wanted to handle two executables simultaneously. */
398 /* Return a debugging handle. */
400 extern PTR debug_init
PARAMS ((void));
402 /* Set the source filename. This implicitly starts a new compilation
405 extern boolean debug_set_filename
PARAMS ((PTR
, const char *));
407 /* Append a string to the source filename. */
409 extern boolean debug_append_filename
PARAMS ((PTR
, const char *));
411 /* Change source files to the given file name. This is used for
412 include files in a single compilation unit. */
414 extern boolean debug_start_source
PARAMS ((PTR
, const char *));
416 /* Record a function definition. This implicitly starts a function
417 block. The debug_type argument is the type of the return value.
418 The boolean indicates whether the function is globally visible.
419 The bfd_vma is the address of the start of the function. Currently
420 the parameter types are specified by calls to
421 debug_record_parameter. */
423 extern boolean debug_record_function
424 PARAMS ((PTR
, const char *, debug_type
, boolean
, bfd_vma
));
426 /* Record a parameter for the current function. */
428 extern boolean debug_record_parameter
429 PARAMS ((PTR
, const char *, debug_type
, enum debug_parm_kind
, bfd_vma
));
431 /* End a function definition. The argument is the address where the
434 extern boolean debug_end_function
PARAMS ((PTR
, bfd_vma
));
436 /* Start a block in a function. All local information will be
437 recorded in this block, until the matching call to debug_end_block.
438 debug_start_block and debug_end_block may be nested. The argument
439 is the address at which this block starts. */
441 extern boolean debug_start_block
PARAMS ((PTR
, bfd_vma
));
443 /* Finish a block in a function. This matches the call to
444 debug_start_block. The argument is the address at which this block
447 extern boolean debug_end_block
PARAMS ((PTR
, bfd_vma
));
449 /* Associate a line number in the current source file and function
450 with a given address. */
452 extern boolean debug_record_line
PARAMS ((PTR
, unsigned long, bfd_vma
));
454 /* Start a named common block. This is a block of variables that may
457 extern boolean debug_start_common_block
PARAMS ((PTR
, const char *));
459 /* End a named common block. */
461 extern boolean debug_end_common_block
PARAMS ((PTR
, const char *));
463 /* Record a named integer constant. */
465 extern boolean debug_record_int_const
PARAMS ((PTR
, const char *, bfd_vma
));
467 /* Record a named floating point constant. */
469 extern boolean debug_record_float_const
PARAMS ((PTR
, const char *, double));
471 /* Record a typed constant with an integral value. */
473 extern boolean debug_record_typed_const
474 PARAMS ((PTR
, const char *, debug_type
, bfd_vma
));
476 /* Record a label. */
478 extern boolean debug_record_label
479 PARAMS ((PTR
, const char *, debug_type
, bfd_vma
));
481 /* Record a variable. */
483 extern boolean debug_record_variable
484 PARAMS ((PTR
, const char *, debug_type
, enum debug_var_kind
, bfd_vma
));
486 /* Make an indirect type. The first argument is a pointer to the
487 location where the real type will be placed. The second argument
488 is the type tag, if there is one; this may be NULL; the only
489 purpose of this argument is so that debug_get_type_name can return
490 something useful. This function may be used when a type is
491 referenced before it is defined. */
493 extern debug_type debug_make_indirect_type
494 PARAMS ((PTR
, debug_type
*, const char *));
496 /* Make a void type. */
498 extern debug_type debug_make_void_type
PARAMS ((PTR
));
500 /* Make an integer type of a given size. The boolean argument is true
501 if the integer is unsigned. */
503 extern debug_type debug_make_int_type
PARAMS ((PTR
, unsigned int, boolean
));
505 /* Make a floating point type of a given size. FIXME: On some
506 platforms, like an Alpha, you probably need to be able to specify
509 extern debug_type debug_make_float_type
PARAMS ((PTR
, unsigned int));
511 /* Make a boolean type of a given size. */
513 extern debug_type debug_make_bool_type
PARAMS ((PTR
, unsigned int));
515 /* Make a complex type of a given size. */
517 extern debug_type debug_make_complex_type
PARAMS ((PTR
, unsigned int));
519 /* Make a structure type. The second argument is true for a struct,
520 false for a union. The third argument is the size of the struct.
521 The fourth argument is a NULL terminated array of fields. */
523 extern debug_type debug_make_struct_type
524 PARAMS ((PTR
, boolean
, bfd_vma
, debug_field
*));
526 /* Make an object type. The first three arguments after the handle
527 are the same as for debug_make_struct_type. The next arguments are
528 a NULL terminated array of base classes, a NULL terminated array of
529 methods, the type of the object holding the virtual function table
530 if it is not this object, and a boolean which is true if this
531 object has its own virtual function table. */
533 extern debug_type debug_make_object_type
534 PARAMS ((PTR
, boolean
, bfd_vma
, debug_field
*, debug_baseclass
*,
535 debug_method
*, debug_type
, boolean
));
537 /* Make an enumeration type. The arguments are a null terminated
538 array of strings, and an array of corresponding values. */
540 extern debug_type debug_make_enum_type
541 PARAMS ((PTR
, const char **, bfd_signed_vma
*));
543 /* Make a pointer to a given type. */
545 extern debug_type debug_make_pointer_type
546 PARAMS ((PTR
, debug_type
));
548 /* Make a function returning a given type. FIXME: We should be able
549 to record the parameter types. */
551 extern debug_type debug_make_function_type
PARAMS ((PTR
, debug_type
));
553 /* Make a reference to a given type. */
555 extern debug_type debug_make_reference_type
PARAMS ((PTR
, debug_type
));
557 /* Make a range of a given type from a lower to an upper bound. */
559 extern debug_type debug_make_range_type
560 PARAMS ((PTR
, debug_type
, bfd_signed_vma
, bfd_signed_vma
));
562 /* Make an array type. The second argument is the type of an element
563 of the array. The third argument is the type of a range of the
564 array. The fourth and fifth argument are the lower and upper
565 bounds, respectively (if the bounds are not known, lower should be
566 0 and upper should be -1). The sixth argument is true if this
567 array is actually a string, as in C. */
569 extern debug_type debug_make_array_type
570 PARAMS ((PTR
, debug_type
, debug_type
, bfd_signed_vma
, bfd_signed_vma
,
573 /* Make a set of a given type. For example, a Pascal set type. The
574 boolean argument is true if this set is actually a bitstring, as in
577 extern debug_type debug_make_set_type
PARAMS ((PTR
, debug_type
, boolean
));
579 /* Make a type for a pointer which is relative to an object. The
580 second argument is the type of the object to which the pointer is
581 relative. The third argument is the type that the pointer points
584 extern debug_type debug_make_offset_type
585 PARAMS ((PTR
, debug_type
, debug_type
));
587 /* Make a type for a method function. The second argument is the
588 return type, the third argument is the domain, and the fourth
589 argument is a NULL terminated array of argument types. The domain
590 and the argument array may be NULL, in which case this is a stub
591 method and that information is not available. Stabs debugging uses
592 this, and gets the argument types from the mangled name. */
594 extern debug_type debug_make_method_type
595 PARAMS ((PTR
, debug_type
, debug_type
, debug_type
*));
597 /* Make a const qualified version of a given type. */
599 extern debug_type debug_make_const_type
PARAMS ((PTR
, debug_type
));
601 /* Make a volatile qualified version of a given type. */
603 extern debug_type debug_make_volatile_type
PARAMS ((PTR
, debug_type
));
605 /* Make an undefined tagged type. For example, a struct which has
606 been mentioned, but not defined. */
608 extern debug_type debug_make_undefined_tagged_type
609 PARAMS ((PTR
, const char *, enum debug_type_kind
));
611 /* Make a base class for an object. The second argument is the base
612 class type. The third argument is the bit position of this base
613 class in the object (always 0 unless doing multiple inheritance).
614 The fourth argument is whether this is a virtual class. The fifth
615 argument is the visibility of the base class. */
617 extern debug_baseclass debug_make_baseclass
618 PARAMS ((PTR
, debug_type
, bfd_vma
, boolean
, enum debug_visibility
));
620 /* Make a field for a struct. The second argument is the name. The
621 third argument is the type of the field. The fourth argument is
622 the bit position of the field. The fifth argument is the size of
623 the field (it may be zero). The sixth argument is the visibility
626 extern debug_field debug_make_field
627 PARAMS ((PTR
, const char *, debug_type
, bfd_vma
, bfd_vma
,
628 enum debug_visibility
));
630 /* Make a static member of an object. The second argument is the
631 name. The third argument is the type of the member. The fourth
632 argument is the physical name of the member (i.e., the name as a
633 global variable). The fifth argument is the visibility of the
636 extern debug_field debug_make_static_member
637 PARAMS ((PTR
, const char *, debug_type
, const char *,
638 enum debug_visibility
));
640 /* Make a method. The second argument is the name, and the third
641 argument is a NULL terminated array of method variants. Each
642 method variant is a method with this name but with different
645 extern debug_method debug_make_method
646 PARAMS ((PTR
, const char *, debug_method_variant
*));
648 /* Make a method variant. The second argument is either the physical
649 name of the function, or the encoded argument types, depending upon
650 whether the third argument specifies the argument types or not.
651 The third argument is the type of the function. The fourth
652 argument is the visibility. The fifth argument is whether this is
653 a const function. The sixth argument is whether this is a volatile
654 function. The seventh argument is the offset in the virtual
655 function table, if any. The eighth argument is the virtual
656 function context. FIXME: Are the const and volatile arguments
657 necessary? Could we just use debug_make_const_type? The handling
658 of the second argument is biased toward the way that stabs works. */
660 extern debug_method_variant debug_make_method_variant
661 PARAMS ((PTR
, const char *, debug_type
, enum debug_visibility
, boolean
,
662 boolean
, bfd_vma
, debug_type
));
664 /* Make a static method argument. The arguments are the same as for
665 debug_make_method_variant, except that the last two are omitted
666 since a static method can not also be virtual. */
668 extern debug_method_variant debug_make_static_method_variant
669 PARAMS ((PTR
, const char *, debug_type
, enum debug_visibility
, boolean
,
672 /* Name a type. This returns a new type with an attached name. */
674 extern debug_type debug_name_type
PARAMS ((PTR
, const char *, debug_type
));
676 /* Give a tag to a type, such as a struct or union. This returns a
677 new type with an attached tag. */
679 extern debug_type debug_tag_type
PARAMS ((PTR
, const char *, debug_type
));
681 /* Record the size of a given type. */
683 extern boolean debug_record_type_size
PARAMS ((PTR
, debug_type
, unsigned int));
685 /* Find a tagged type. */
687 extern debug_type debug_find_tagged_type
688 PARAMS ((PTR
, const char *, enum debug_type_kind
));
690 /* Get the name of a type. */
692 extern const char *debug_get_type_name
PARAMS ((PTR
, debug_type
));
694 /* Write out the recorded debugging information. This takes a set of
695 function pointers which are called to do the actual writing. The
696 first PTR is the debugging handle. The second PTR is a handle
697 which is passed to the functions. */
699 extern boolean debug_write
PARAMS ((PTR
, const struct debug_write_fns
*, PTR
));