diff options
Diffstat (limited to 'gdb/doc/gdbint.texinfo')
| -rw-r--r-- | gdb/doc/gdbint.texinfo | 470 |
1 files changed, 277 insertions, 193 deletions
diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index 3ed887b36df..a474015783b 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -8,7 +8,7 @@ @ifinfo This file documents the internals of the GNU debugger @value{GDBN}. -Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,2002,2003 +Copyright 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc. Contributed by Cygnus Solutions. Written by John Gilmore. Second Edition by Stan Shebs. @@ -38,7 +38,7 @@ Free Documentation License''. @page @tex \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ -\xdef\manvers{\$Revision: 1.161 $} % For use in headers, footers too +\xdef\manvers{\$Revision: 1.161.2.1 $} % For use in headers, footers too {\parskip=0pt \hfill Cygnus Solutions\par \hfill \manvers\par @@ -48,7 +48,7 @@ Free Documentation License''. @vskip 0pt plus 1filll Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001, - 2002, 2003 Free Software Foundation, Inc. + 2002, 2003, 2004 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or @@ -480,13 +480,6 @@ two macros can use them for their internal purposes. If the inferior has some watchpoint that triggered, return the address associated with that watchpoint. Otherwise, return zero. -@findex DECR_PC_AFTER_HW_BREAK -@item DECR_PC_AFTER_HW_BREAK -If defined, @value{GDBN} decrements the program counter by the value -of @code{DECR_PC_AFTER_HW_BREAK} after a hardware break-point. This -overrides the value of @code{DECR_PC_AFTER_BREAK} when a breakpoint -that breaks is a hardware-assisted breakpoint. - @findex HAVE_STEPPABLE_WATCHPOINT @item HAVE_STEPPABLE_WATCHPOINT If defined to a non-zero value, it is not necessary to disable a @@ -2245,12 +2238,6 @@ This macro is used as the argument to @code{lseek} (or, most commonly, @code{bfd_seek}). FIXME, should be replaced by SEEK_SET instead, which is the POSIX equivalent. -@item MMAP_BASE_ADDRESS -When using HAVE_MMAP, the first mapping should go at this address. - -@item MMAP_INCREMENT -when using HAVE_MMAP, this is the increment between mappings. - @item NORETURN If defined, this should be one or more tokens, such as @code{volatile}, that can be used in both the declaration and definition of functions to @@ -2264,37 +2251,6 @@ of functions to indicate that they never return. The default is already set correctly if compiling with GCC. This will almost never need to be defined. -@item USE_MMALLOC -@findex mmalloc -@value{GDBN} will use the @code{mmalloc} library for memory allocation -for symbol reading if this symbol is defined. Be careful defining it -since there are systems on which @code{mmalloc} does not work for some -reason. One example is the DECstation, where its RPC library can't -cope with our redefinition of @code{malloc} to call @code{mmalloc}. -When defining @code{USE_MMALLOC}, you will also have to set -@code{MMALLOC} in the Makefile, to point to the @code{mmalloc} library. This -define is set when you configure with @samp{--with-mmalloc}. - -@item NO_MMCHECK -@findex mmcheck -Define this if you are using @code{mmalloc}, but don't want the overhead -of checking the heap with @code{mmcheck}. Note that on some systems, -the C runtime makes calls to @code{malloc} prior to calling @code{main}, and if -@code{free} is ever called with these pointers after calling -@code{mmcheck} to enable checking, a memory corruption abort is certain -to occur. These systems can still use @code{mmalloc}, but must define -@code{NO_MMCHECK}. - -@item MMCHECK_FORCE -Define this to 1 if the C runtime allocates memory prior to -@code{mmcheck} being called, but that memory is never freed so we don't -have to worry about it triggering a memory corruption abort. The -default is 0, which means that @code{mmcheck} will only install the heap -checking functions if there has not yet been any memory allocation -calls, and if it fails to install the functions, @value{GDBN} will issue a -warning. This is currently defined if you configure using -@samp{--with-mmalloc}. - @item NO_SIGINTERRUPT @findex siginterrupt Define this to indicate that @code{siginterrupt} is not available. @@ -2505,7 +2461,7 @@ However, architectures with smaller word sizes are often cramped for address space, so they may choose a pointer representation that breaks this identity, and allows a larger code address space. -For example, the Mitsubishi D10V is a 16-bit VLIW processor whose +For example, the Renesas D10V is a 16-bit VLIW processor whose instructions are 32 bits long@footnote{Some D10V instructions are actually pairs of 16-bit sub-instructions. However, since you can't jump into the middle of such a pair, code addresses can only refer to @@ -2766,19 +2722,19 @@ You should not use @code{REGISTER_CONVERT_TO_VIRTUAL} for a register unless this macro returns a non-zero value for that register. @end deftypefn -@deftypefn {Target Macro} int REGISTER_RAW_SIZE (int @var{reg}) +@deftypefn {Target Macro} int DEPRECATED_REGISTER_RAW_SIZE (int @var{reg}) The size of register number @var{reg}'s raw value. This is the number of bytes the register will occupy in @code{registers}, or in a @value{GDBN} remote protocol packet. @end deftypefn -@deftypefn {Target Macro} int REGISTER_VIRTUAL_SIZE (int @var{reg}) +@deftypefn {Target Macro} int DEPRECATED_REGISTER_VIRTUAL_SIZE (int @var{reg}) The size of register number @var{reg}'s value, in its virtual format. This is the size a @code{struct value}'s buffer will have, holding that register's value. @end deftypefn -@deftypefn {Target Macro} struct type *REGISTER_VIRTUAL_TYPE (int @var{reg}) +@deftypefn {Target Macro} struct type *DEPRECATED_REGISTER_VIRTUAL_TYPE (int @var{reg}) This is the type of the virtual representation of register number @var{reg}. Note that there is no need for a macro giving a type for the register's raw form; once the register's value has been obtained, @value{GDBN} @@ -2787,7 +2743,7 @@ always uses the virtual form. @deftypefn {Target Macro} void REGISTER_CONVERT_TO_VIRTUAL (int @var{reg}, struct type *@var{type}, char *@var{from}, char *@var{to}) Convert the value of register number @var{reg} to @var{type}, which -should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer +should always be @code{DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer at @var{from} holds the register's value in raw format; the macro should convert the value to virtual format, and place it at @var{to}. @@ -2802,7 +2758,7 @@ value. @deftypefn {Target Macro} void REGISTER_CONVERT_TO_RAW (struct type *@var{type}, int @var{reg}, char *@var{from}, char *@var{to}) Convert the value of register number @var{reg} to @var{type}, which -should always be @code{REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer +should always be @code{DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg})}. The buffer at @var{from} holds the register's value in raw format; the macro should convert the value to virtual format, and place it at @var{to}. @@ -3052,6 +3008,39 @@ custom breakpoint insertion and removal routines if @code{BREAKPOINT_FROM_PC} needs to read the target's memory for some reason. +@item ADJUST_BREAKPOINT_ADDRESS (@var{address}) +@findex ADJUST_BREAKPOINT_ADDRESS +@cindex breakpoint address adjusted +Given an address at which a breakpoint is desired, return a breakpoint +address adjusted to account for architectural constraints on +breakpoint placement. This method is not needed by most targets. + +The FR-V target (see @file{frv-tdep.c}) requires this method. +The FR-V is a VLIW architecture in which a number of RISC-like +instructions are grouped (packed) together into an aggregate +instruction or instruction bundle. When the processor executes +one of these bundles, the component instructions are executed +in parallel. + +In the course of optimization, the compiler may group instructions +from distinct source statements into the same bundle. The line number +information associated with one of the latter statements will likely +refer to some instruction other than the first one in the bundle. So, +if the user attempts to place a breakpoint on one of these latter +statements, @value{GDBN} must be careful to @emph{not} place the break +instruction on any instruction other than the first one in the bundle. +(Remember though that the instructions within a bundle execute +in parallel, so the @emph{first} instruction is the instruction +at the lowest address and has nothing to do with execution order.) + +The FR-V's @code{ADJUST_BREAKPOINT_ADDRESS} method will adjust a +breakpoint's address by scanning backwards for the beginning of +the bundle, returning the address of the bundle. + +Since the adjustment of a breakpoint may significantly alter a user's +expectation, @value{GDBN} prints a warning when an adjusted breakpoint +is initially set and each time that that breakpoint is hit. + @item DEPRECATED_CALL_DUMMY_WORDS @findex DEPRECATED_CALL_DUMMY_WORDS Pointer to an array of @code{LONGEST} words of data containing @@ -3088,12 +3077,6 @@ See the file @file{inferior.h}. This method has been replaced by @code{push_dummy_code} (@pxref{push_dummy_code}). -@item DEPRECATED_CALL_DUMMY_STACK_ADJUST -@findex DEPRECATED_CALL_DUMMY_STACK_ADJUST -Stack adjustment needed when performing an inferior function call. This -function is no longer needed. @xref{push_dummy_call}, which can handle -all alignment directly. - @item CANNOT_FETCH_REGISTER (@var{regno}) @findex CANNOT_FETCH_REGISTER A C expression that should be nonzero if @var{regno} cannot be fetched @@ -3128,10 +3111,6 @@ Define this to be the amount by which to decrement the PC after the program encounters a breakpoint. This is often the number of bytes in @code{BREAKPOINT}, though not always. For most targets this value will be 0. -@item DECR_PC_AFTER_HW_BREAK -@findex DECR_PC_AFTER_HW_BREAK -Similarly, for hardware breakpoints. - @item DISABLE_UNSETTABLE_BREAK (@var{addr}) @findex DISABLE_UNSETTABLE_BREAK If defined, this should evaluate to 1 if @var{addr} is in a shared @@ -3186,17 +3165,21 @@ Define this to extract a function's return value of type @var{type} from the raw register state @var{regbuf} and copy that, in virtual format, into @var{valbuf}. -@item EXTRACT_STRUCT_VALUE_ADDRESS(@var{regbuf}) -@findex EXTRACT_STRUCT_VALUE_ADDRESS +This method has been deprecated in favour of @code{gdbarch_return_value} +(@pxref{gdbarch_return_value}). + +@item DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS(@var{regbuf}) +@findex DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS +@anchor{DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS} When defined, extract from the array @var{regbuf} (containing the raw register state) the @code{CORE_ADDR} at which a function should return its structure value. -If not defined, @code{EXTRACT_RETURN_VALUE} is used. +@xref{gdbarch_return_value}. -@item EXTRACT_STRUCT_VALUE_ADDRESS_P() -@findex EXTRACT_STRUCT_VALUE_ADDRESS_P -Predicate for @code{EXTRACT_STRUCT_VALUE_ADDRESS}. +@item DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS_P() +@findex DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS_P +Predicate for @code{DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS}. @item DEPRECATED_FP_REGNUM @findex DEPRECATED_FP_REGNUM @@ -3206,8 +3189,8 @@ macro to be the number (greater than or equal to zero) of that register. This should only need to be defined if @code{DEPRECATED_TARGET_READ_FP} is not defined. -@item FRAMELESS_FUNCTION_INVOCATION(@var{fi}) -@findex FRAMELESS_FUNCTION_INVOCATION +@item DEPRECATED_FRAMELESS_FUNCTION_INVOCATION(@var{fi}) +@findex DEPRECATED_FRAMELESS_FUNCTION_INVOCATION Define this to an expression that returns 1 if the function invocation represented by @var{fi} does not have a stack frame associated with it. Otherwise return 0. @@ -3382,9 +3365,9 @@ pointer. It examines the current state of the machine as needed. Define this if you need to supply your own definition for the function @code{DEPRECATED_GET_SAVED_REGISTER}. -@item IBM6000_TARGET -@findex IBM6000_TARGET -Shows that we are configured for an IBM RS/6000 target. This +@item DEPRECATED_IBM6000_TARGET +@findex DEPRECATED_IBM6000_TARGET +Shows that we are configured for an IBM RS/6000 system. This conditional should be eliminated (FIXME) and replaced by feature-specific macros. It was introduced in a haste and we are repenting at leisure. @@ -3483,11 +3466,6 @@ method like @code{INTEGER_TO_ADDRESS} certainly makes it possible for @xref{Target Architecture Definition, , Pointers Are Not Always Addresses}. -@item NEED_TEXT_START_END -@findex NEED_TEXT_START_END -Define this if @value{GDBN} should determine the start and end addresses of the -text section. (Seems dubious.) - @item NO_HIF_SUPPORT @findex NO_HIF_SUPPORT (Specific to the a29k.) @@ -3510,8 +3488,8 @@ Convert the raw contents of register @var{regnum} into a value of type @var{type}. @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}. -@item REGISTER_RAW_SIZE (@var{reg}) -@findex REGISTER_RAW_SIZE +@item DEPRECATED_REGISTER_RAW_SIZE (@var{reg}) +@findex DEPRECATED_REGISTER_RAW_SIZE Return the raw size of @var{reg}; defaults to the size of the register's virtual type. @xref{Target Architecture Definition, , Raw and Virtual Register Representations}. @@ -3538,14 +3516,14 @@ floating-point. @samp{float_reggroup}. Any register with a valid name. @end table -@item REGISTER_VIRTUAL_SIZE (@var{reg}) -@findex REGISTER_VIRTUAL_SIZE +@item DEPRECATED_REGISTER_VIRTUAL_SIZE (@var{reg}) +@findex DEPRECATED_REGISTER_VIRTUAL_SIZE Return the virtual size of @var{reg}; defaults to the size of the register's virtual type. Return the virtual size of @var{reg}. @xref{Target Architecture Definition, , Raw and Virtual Register Representations}. -@item REGISTER_VIRTUAL_TYPE (@var{reg}) +@item DEPRECATED_REGISTER_VIRTUAL_TYPE (@var{reg}) @findex REGISTER_VIRTUAL_TYPE Return the virtual type of @var{reg}. @xref{Target Architecture Definition, , Raw and Virtual Register Representations}. @@ -3553,7 +3531,7 @@ Return the virtual type of @var{reg}. @item struct type *register_type (@var{gdbarch}, @var{reg}) @findex register_type If defined, return the type of register @var{reg}. This function -superseeds @code{REGISTER_VIRTUAL_TYPE}. @xref{Target Architecture +superseeds @code{DEPRECATED_REGISTER_VIRTUAL_TYPE}. @xref{Target Architecture Definition, , Raw and Virtual Register Representations}. @item REGISTER_CONVERT_TO_VIRTUAL(@var{reg}, @var{type}, @var{from}, @var{to}) @@ -3568,6 +3546,12 @@ Convert the value of register @var{reg} from its virtual form to its raw form. @xref{Target Architecture Definition, , Raw and Virtual Register Representations}. +@item const struct regset *regset_from_core_section (struct gdbarch * @var{gdbarch}, const char * @var{sect_name}, size_t @var{sect_size}) +@findex regset_from_core_section +Return the appropriate register set for a core file section with name +@var{sect_name} and size @var{sect_size}. + + @item RETURN_VALUE_ON_STACK(@var{type}) @findex RETURN_VALUE_ON_STACK @cindex returning structures by value @@ -3677,15 +3661,21 @@ be the number (greater than or equal to zero) of that register. This should only need to be defined if @code{TARGET_READ_PC} and @code{TARGET_WRITE_PC} are not defined. -@item NPC_REGNUM -@findex NPC_REGNUM -The number of the ``next program counter'' register, if defined. - @item PARM_BOUNDARY @findex PARM_BOUNDARY If non-zero, round arguments to a boundary of this many bits before pushing them on the stack. +@item stabs_argument_has_addr (@var{gdbarch}, @var{type}) +@findex stabs_argument_has_addr +@findex DEPRECATED_REG_STRUCT_HAS_ADDR +@anchor{stabs_argument_has_addr} Define this to return nonzero if a +function argument of type @var{type} is passed by reference instead of +value. + +This method replaces @code{DEPRECATED_REG_STRUCT_HAS_ADDR} +(@pxref{DEPRECATED_REG_STRUCT_HAS_ADDR}). + @item PROCESS_LINENUMBER_HOOK @findex PROCESS_LINENUMBER_HOOK A hook defined for XCOFF reading. @@ -3735,7 +3725,6 @@ reserved for that breakpoint, and @var{real_pc} set to @var{funaddr}. This method replaces @code{DEPRECATED_CALL_DUMMY_WORDS}, @code{DEPRECATED_SIZEOF_CALL_DUMMY_WORDS}, @code{CALL_DUMMY}, @code{CALL_DUMMY_LOCATION}, @code{DEPRECATED_REGISTER_SIZE}, -@code{GDB_TARGET_IS_HPPA}, @code{DEPRECATED_CALL_DUMMY_BREAKPOINT_OFFSET}, and @code{DEPRECATED_FIX_CALL_DUMMY}. @@ -3756,14 +3745,13 @@ register buffer at run-time. Return the name of register @var{i} as a string. May return @code{NULL} or @code{NUL} to indicate that register @var{i} is not valid. -@item REGISTER_NAMES -@findex REGISTER_NAMES -Deprecated in favor of @code{REGISTER_NAME}. - @item DEPRECATED_REG_STRUCT_HAS_ADDR (@var{gcc_p}, @var{type}) @findex DEPRECATED_REG_STRUCT_HAS_ADDR -Define this to return 1 if the given type will be passed by pointer -rather than directly. +@anchor{DEPRECATED_REG_STRUCT_HAS_ADDR}Define this to return 1 if the +given type will be passed by pointer rather than directly. + +This method has been replaced by @code{stabs_argument_has_addr} +(@pxref{stabs_argument_has_addr}). @item SAVE_DUMMY_FRAME_TOS (@var{sp}) @findex SAVE_DUMMY_FRAME_TOS @@ -3778,6 +3766,48 @@ allocated on the stack. @xref{unwind_dummy_id}. Define this to convert sdb register numbers into @value{GDBN} regnums. If not defined, no conversion will be done. +@item enum return_value_convention gdbarch_return_value (struct gdbarch *@var{gdbarch}, struct type *@var{valtype}, struct regcache *@var{regcache}, void *@var{readbuf}, const void *@var{writebuf}) +@findex gdbarch_return_value +@anchor{gdbarch_return_value} Given a function with a return-value of +type @var{rettype}, return which return-value convention that function +would use. + +@value{GDBN} currently recognizes two function return-value conventions: +@code{RETURN_VALUE_REGISTER_CONVENTION} where the return value is found +in registers; and @code{RETURN_VALUE_STRUCT_CONVENTION} where the return +value is found in memory and the address of that memory location is +passed in as the function's first parameter. + +If the register convention is being used, and @var{writebuf} is +non-@code{NULL}, also copy the return-value in @var{writebuf} into +@var{regcache}. + +If the register convention is being used, and @var{readbuf} is +non-@code{NULL}, also copy the return value from @var{regcache} into +@var{readbuf} (@var{regcache} contains a copy of the registers from the +just returned function). + +@xref{DEPRECATED_EXTRACT_STRUCT_VALUE_ADDRESS}, for a description of how +return-values that use the struct convention are handled. + +@emph{Maintainer note: This method replaces separate predicate, extract, +store methods. By having only one method, the logic needed to determine +the return-value convention need only be implemented in one place. If +@value{GDBN} were written in an @sc{oo} language, this method would +instead return an object that knew how to perform the register +return-value extract and store.} + +@emph{Maintainer note: This method does not take a @var{gcc_p} +parameter, and such a parameter should not be added. If an architecture +that requires per-compiler or per-function information be identified, +then the replacement of @var{rettype} with @code{struct value} +@var{function} should be persued.} + +@emph{Maintainer note: The @var{regcache} parameter limits this methods +to the inner most frame. While replacing @var{regcache} with a +@code{struct frame_info} @var{frame} parameter would remove that +limitation there has yet to be a demonstrated need for such a change.} + @item SKIP_PERMANENT_BREAKPOINT @findex SKIP_PERMANENT_BREAKPOINT Advance the inferior's PC past a permanent breakpoint. @value{GDBN} normally @@ -3836,6 +3866,9 @@ A C expression that writes the function return value, found in @var{valbuf}, into the @var{regcache}. @var{type} is the type of the value that is to be returned. +This method has been deprecated in favour of @code{gdbarch_return_value} +(@pxref{gdbarch_return_value}). + @item SUN_FIXED_LBRAC_BUG @findex SUN_FIXED_LBRAC_BUG (Used only for Sun-3 and Sun-4 targets.) @@ -3909,6 +3942,7 @@ Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}. @findex TARGET_READ_PC @itemx TARGET_WRITE_PC (@var{val}, @var{pid}) @findex TARGET_WRITE_PC +@anchor{TARGET_WRITE_PC} @itemx TARGET_READ_SP @findex TARGET_READ_SP @itemx TARGET_READ_FP @@ -3970,6 +4004,9 @@ being considered is known to have been compiled by GCC; this is helpful for systems where GCC is known to use different calling convention than other compilers. +This method has been deprecated in favour of @code{gdbarch_return_value} +(@pxref{gdbarch_return_value}). + @item VALUE_TO_REGISTER(@var{type}, @var{regnum}, @var{from}, @var{to}) @findex VALUE_TO_REGISTER Convert a value of type @var{type} into the raw contents of register @@ -4634,6 +4671,66 @@ library because it's also used in binutils, for @file{objdump}). @section mmalloc @section libiberty +@cindex @code{libiberty} library + +The @code{libiberty} library provides a set of functions and features +that integrate and improve on functionality found in modern operating +systems. Broadly speaking, such features can be divided into three +groups: supplemental functions (functions that may be missing in some +environments and operating systems), replacement functions (providing +a uniform and easier to use interface for commonly used standard +functions), and extensions (which provide additional functionality +beyond standard functions). + +@value{GDBN} uses various features provided by the @code{libiberty} +library, for instance the C@t{++} demangler, the @acronym{IEEE} +floating format support functions, the input options parser +@samp{getopt}, the @samp{obstack} extension, and other functions. + +@subsection @code{obstacks} in @value{GDBN} +@cindex @code{obstacks} + +The obstack mechanism provides a convenient way to allocate and free +chunks of memory. Each obstack is a pool of memory that is managed +like a stack. Objects (of any nature, size and alignment) are +allocated and freed in a @acronym{LIFO} fashion on an obstack (see +@code{libiberty}'s documenatation for a more detailed explanation of +@code{obstacks}). + +The most noticeable use of the @code{obstacks} in @value{GDBN} is in +object files. There is an obstack associated with each internal +representation of an object file. Lots of things get allocated on +these @code{obstacks}: dictionary entries, blocks, blockvectors, +symbols, minimal symbols, types, vectors of fundamental types, class +fields of types, object files section lists, object files section +offets lists, line tables, symbol tables, partial symbol tables, +string tables, symbol table private data, macros tables, debug +information sections and entries, import and export lists (som), +unwind information (hppa), dwarf2 location expressions data. Plus +various strings such as directory names strings, debug format strings, +names of types. + +An essential and convenient property of all data on @code{obstacks} is +that memory for it gets allocated (with @code{obstack_alloc}) at +various times during a debugging sesssion, but it is released all at +once using the @code{obstack_free} function. The @code{obstack_free} +function takes a pointer to where in the stack it must start the +deletion from (much like the cleanup chains have a pointer to where to +start the cleanups). Because of the stack like structure of the +@code{obstacks}, this allows to free only a top portion of the +obstack. There are a few instances in @value{GDBN} where such thing +happens. Calls to @code{obstack_free} are done after some local data +is allocated to the obstack. Only the local data is deleted from the +obstack. Of course this assumes that nothing between the +@code{obstack_alloc} and the @code{obstack_free} allocates anything +else on the same obstack. For this reason it is best and safest to +use temporary @code{obstacks}. + +Releasing the whole obstack is also not safe per se. It is safe only +under the condition that we know the @code{obstacks} memory is no +longer needed. In @value{GDBN} we get rid of the @code{obstacks} only +when we get rid of the whole objfile(s), for instance upon reading a +new symbol file. @section gnu-regex @cindex regular expressions library @@ -4774,138 +4871,104 @@ functions, since they might never return to your code (they @cindex multi-arch data @cindex data-pointer, per-architecture/per-module -The multi-arch framework includes a mechanism for adding module specific -per-architecture data-pointers to the @code{struct gdbarch} architecture -object. +The multi-arch framework includes a mechanism for adding module +specific per-architecture data-pointers to the @code{struct gdbarch} +architecture object. -A module registers one or more per-architecture data-pointers using the -function @code{register_gdbarch_data}: +A module registers one or more per-architecture data-pointers using: -@deftypefun struct gdbarch_data *register_gdbarch_data (gdbarch_data_init_ftype *@var{init}, gdbarch_data_free_ftype *@var{free}) +@deftypefun struct gdbarch_data *gdbarch_data_register_pre_init (gdbarch_data_pre_init_ftype *@var{pre_init}) +@var{pre_init} is used to, on-demand, allocate an initial value for a +per-architecture data-pointer using the architecture's obstack (passed +in as a parameter). Since @var{pre_init} can be called during +architecture creation, it is not parameterized with the architecture. +and must not call modules that use per-architecture data. +@end deftypefun -The @var{init} function is used to obtain an initial value for a -per-architecture data-pointer. The function is called, after the -architecture has been created, when the data-pointer is still -uninitialized (@code{NULL}) and its value has been requested via a call -to @code{gdbarch_data}. A data-pointer can also be initialize -explicitly using @code{set_gdbarch_data}. +@deftypefun struct gdbarch_data *gdbarch_data_register_post_init (gdbarch_data_post_init_ftype *@var{post_init}) +@var{post_init} is used to obtain an initial value for a +per-architecture data-pointer @emph{after}. Since @var{post_init} is +always called after architecture creation, it both receives the fully +initialized architecture and is free to call modules that use +per-architecture data (care needs to be taken to ensure that those +other modules do not try to call back to this module as that will +create in cycles in the initialization call graph). +@end deftypefun -The @var{free} function is called when a data-pointer needs to be -destroyed. This occurs when either the corresponding @code{struct -gdbarch} object is being destroyed or when @code{set_gdbarch_data} is -overriding a non-@code{NULL} data-pointer value. +These functions return a @code{struct gdbarch_data} that is used to +identify the per-architecture data-pointer added for that module. -The function @code{register_gdbarch_data} returns a @code{struct -gdbarch_data} that is used to identify the data-pointer that was added -to the module. +The per-architecture data-pointer is accessed using the function: +@deftypefun void *gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{data_handle}) +Given the architecture @var{arch} and module data handle +@var{data_handle} (returned by @code{gdbarch_data_register_pre_init} +or @code{gdbarch_data_register_post_init}), this function returns the +current value of the per-architecture data-pointer. If the data +pointer is @code{NULL}, it is first initialized by calling the +corresponding @var{pre_init} or @var{post_init} method. @end deftypefun -A typical module has @code{init} and @code{free} functions of the form: +The examples below assume the following definitions: @smallexample +struct nozel @{ int total; @}; static struct gdbarch_data *nozel_handle; -static void * -nozel_init (struct gdbarch *gdbarch) -@{ - struct nozel *data = XMALLOC (struct nozel); - @dots{} - return data; -@} -@dots{} -static void -nozel_free (struct gdbarch *gdbarch, void *data) -@{ - xfree (data); -@} @end smallexample -Since uninitialized (@code{NULL}) data-pointers are initialized -on-demand, an @code{init} function is free to call other modules that -use data-pointers. Those modules data-pointers will be initialized as -needed. Care should be taken to ensure that the @code{init} call graph -does not contain cycles. +A module can extend the architecture vector, adding additional +per-architecture data, using the @var{pre_init} method. The module's +per-architecture data is then initialized during architecture +creation. -The data-pointer is registered with the call: +In the below, the module's per-architecture @emph{nozel} is added. An +architecture can specify its nozel by calling @code{set_gdbarch_nozel} +from @code{gdbarch_init}. @smallexample -void -_initialize_nozel (void) +static void * +nozel_pre_init (struct obstack *obstack) @{ - nozel_handle = register_gdbarch_data (nozel_init, nozel_free); -@dots{} + struct nozel *data = OBSTACK_ZALLOC (obstack, struct nozel); + return data; +@} @end smallexample -The per-architecture data-pointer is accessed using the function: - -@deftypefun void *gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{data_handle}) -Given the architecture @var{arch} and module data handle -@var{data_handle} (returned by @code{register_gdbarch_data}, this -function returns the current value of the per-architecture data-pointer. -@end deftypefun - -The non-@code{NULL} data-pointer returned by @code{gdbarch_data} should -be saved in a local variable and then used directly: - @smallexample -int -nozel_total (struct gdbarch *gdbarch) +extern void +set_gdbarch_nozel (struct gdbarch *gdbarch, int total) @{ - int total; struct nozel *data = gdbarch_data (gdbarch, nozel_handle); - @dots{} - return total; + data->total = nozel; @} @end smallexample -It is also possible to directly initialize the data-pointer using: +A module can on-demand create architecture dependant data structures +using @code{post_init}. -@deftypefun void set_gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *handle, void *@var{pointer}) -Update the data-pointer corresponding to @var{handle} with the value of -@var{pointer}. If the previous data-pointer value is non-NULL, then it -is freed using data-pointers @var{free} function. -@end deftypefun - -This function is used by modules that require a mechanism for explicitly -setting the per-architecture data-pointer during architecture creation: +In the below, the nozel's total is computed on-demand by +@code{nozel_post_init} using information obtained from the +architecture. @smallexample -/* Called during architecture creation. */ -extern void -set_gdbarch_nozel (struct gdbarch *gdbarch, - int total) -@{ - struct nozel *data = XMALLOC (struct nozel); - @dots{} - set_gdbarch_data (gdbarch, nozel_handle, nozel); -@} -@end smallexample - -@smallexample -/* Default, called when nozel not set by set_gdbarch_nozel(). */ static void * -nozel_init (struct gdbarch *gdbarch) +nozel_post_init (struct gdbarch *gdbarch) @{ - struct nozel *default_nozel = XMALLOC (struc nozel); - @dots{} - return default_nozel; + struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel); + nozel->total = gdbarch@dots{} (gdbarch); + return data; @} @end smallexample @smallexample -void -_initialize_nozel (void) +extern int +nozel_total (struct gdbarch *gdbarch) @{ - nozel_handle = register_gdbarch_data (nozel_init, NULL); - @dots{} + struct nozel *data = gdbarch_data (gdbarch, nozel_handle); + return data->total; +@} @end smallexample -@noindent -Note that an @code{init} function still needs to be registered. It is -used to initialize the data-pointer when the architecture creation phase -fail to set an initial value. - - @section Wrapping Output Lines @cindex line wrap in output @@ -5033,6 +5096,25 @@ This warning includes uses of the assignment operator within an @item -Wpointer-arith @item -Wuninitialized + +@item -Wunused-label +This warning has the additional benefit of detecting the absence of the +@code{case} reserved word in a switch statement: +@smallexample +enum @{ FD_SCHEDULED, NOTHING_SCHEDULED @} sched; +@dots{} +switch (sched) + @{ + case FD_SCHEDULED: + @dots{}; + break; + NOTHING_SCHEDULED: + @dots{}; + break; + @} +@end smallexample + +@item -Wunused-function @end table @emph{Pragmatics: Due to the way that @value{GDBN} is implemented most @@ -6376,12 +6458,12 @@ intelligibility. This is the base testsuite. The tests in it should apply to all configurations of @value{GDBN} (but generic native-only tests may live here). The test programs should be in the subset of C that is valid K&R, -ANSI/ISO, and C++ (@code{#ifdef}s are allowed if necessary, for instance +ANSI/ISO, and C@t{++} (@code{#ifdef}s are allowed if necessary, for instance for prototypes). @item gdb.@var{lang} Language-specific tests for any language @var{lang} besides C. Examples are -@file{gdb.c++} and @file{gdb.java}. +@file{gdb.cp} and @file{gdb.java}. @item gdb.@var{platform} Non-portable tests. The tests are specific to a specific configuration @@ -6632,7 +6714,9 @@ is so old that it has never been converted to use BFD. Now that's old! @end table @include observer.texi +@raisesections @include fdl.texi +@lowersections @node Index @unnumbered Index |