[rfc/rfa] Revsions to gdbint.texinfo

[Andrew Cagney <ac131313 at cygnus dot com>]

Hello,

The attatached patch tries to address the most glaring errors in the GDB 
internals document.  More work is always needed.

Structuring hints are welcome.

It includes a section titled ``Memory Management'' and that, in turn 
mentions alloca().

	Andrew
2001-06-15  Andrew Cagney  <ac131313@redhat.com>

	* gdbint.texinfo (Target Architecture Definition): GDBARCH is a C
	structure and not macros.
	(Host Definition): Document that much of this chapter is obsolete.
	(Target Architecture Definition): Update list of files that make
	up a target architecture.
	(Coding): Update.

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.27
diff -p -r1.27 gdbint.texinfo
*** gdbint.texinfo	2001/05/14 20:24:23	1.27
--- gdbint.texinfo	2001/06/15 07:10:53
*************** distribution!
*** 1886,1891 ****
--- 1886,1896 ----
  
  @chapter Host Definition
  
+ @emph{Maintainer's note: In theory, new targets no longer need to use
+ the host framework described below.  Instead it should be possible to
+ handle everything using autoconf.  Patches eliminating this framework
+ welcome.}
+ 
  With the advent of Autoconf, it's rarely necessary to have host
  definition machinery anymore.
  
*************** Define this to override the defaults of 
*** 2199,2206 ****
  machine-language programs @value{GDBN} can work with, and how it works
  with them.
  
! At present, the target architecture definition consists of a number of C
! macros.
  
  @section Registers and Memory
  
--- 2204,2212 ----
  machine-language programs @value{GDBN} can work with, and how it works
  with them.
  
! The target architecture object is implemented as the C structure
! @code{struct gdbarch *}.  The structure, and its methods, are generated
! using the Bourn shell script @code{gdbarch.sh}.
  
  @section Registers and Memory
  
*************** C@t{++} reference type.
*** 2384,2389 ****
--- 2390,2400 ----
  @cindex register data formats, converting
  @cindex @code{struct value}, converting register contents to
  
+ @emph{Maintainer's note: The way GDB manipulates registers is undergoing
+ significant change.  Many of the macro's and functions refered to in the
+ section below are likely to be made obsolete.  See the file @code{TODO}
+ for more up-to-date information.}
+ 
  Some architectures use one representation for a value when it lives in a
  register, but use a different representation when it lives in memory.
  In @value{GDBN}'s terminology, the @dfn{raw} representation is the one used in
*************** Defaults to @code{1}.
*** 3452,3458 ****
  @section Adding a New Target
  
  @cindex adding a target
! The following files define a target to @value{GDBN}:
  
  @table @file
  @vindex TDEPFILES
--- 3463,3469 ----
  @section Adding a New Target
  
  @cindex adding a target
! The following files add a target to @value{GDBN}:
  
  @table @file
  @vindex TDEPFILES
*************** You can also define @samp{TM_CFLAGS}, @s
*** 3467,3477 ****
  but these are now deprecated, replaced by autoconf, and may go away in
  future versions of @value{GDBN}.
  
- @item gdb/config/@var{arch}/tm-@var{ttt}.h
- (@file{tm.h} is a link to this file, created by @code{configure}).  Contains
- macro definitions about the target machine's registers, stack frame
- format and instructions.
- 
  @item gdb/@var{ttt}-tdep.c
  Contains any miscellaneous code required for this target machine.  On
  some machines it doesn't exist at all.  Sometimes the macros in
--- 3478,3483 ----
*************** as functions here instead, and the macro
*** 3480,3494 ****
  function.  This is vastly preferable, since it is easier to understand
  and debug.
  
  @item gdb/config/@var{arch}/tm-@var{arch}.h
  This often exists to describe the basic layout of the target machine's
  processor chip (registers, stack, etc.).  If used, it is included by
  @file{tm-@var{ttt}.h}.  It can be shared among many targets that use the
  same processor.
  
- @item gdb/@var{arch}-tdep.c
- Similarly, there are often common subroutines that are shared by all
- target machines that use this particular architecture.
  @end table
  
  If you are adding a new operating system for an existing CPU chip, add a
--- 3486,3512 ----
  function.  This is vastly preferable, since it is easier to understand
  and debug.
  
+ @item gdb/@var{arch}-tdep.c, gdb/@var{arch}-tdep.h
+ This often exists to describe the basic layout of the target machine's
+ processor chip (registers, stack, etc.).  If used, it is included by
+ @file{@var{ttt}-tdep.h}.  It can be shared among many targets that use
+ the same processor.
+ 
+ @item gdb/config/@var{arch}/tm-@var{ttt}.h
+ (@file{tm.h} is a link to this file, created by @code{configure}).  Contains
+ macro definitions about the target machine's registers, stack frame
+ format and instructions.
+ 
+ New targets do not need this file and should not create it.
+ 
  @item gdb/config/@var{arch}/tm-@var{arch}.h
  This often exists to describe the basic layout of the target machine's
  processor chip (registers, stack, etc.).  If used, it is included by
  @file{tm-@var{ttt}.h}.  It can be shared among many targets that use the
  same processor.
+ 
+ New targets do not need this file and should not create it.
  
  @end table
  
  If you are adding a new operating system for an existing CPU chip, add a
*************** print warnings are a good example.
*** 4038,4057 ****
  
  @value{GDBN} follows the GNU coding standards, as described in
  @file{etc/standards.texi}.  This file is also available for anonymous
! FTP from GNU archive sites.  @value{GDBN} takes a strict interpretation of the
! standard; in general, when the GNU standard recommends a practice but
! does not require it, @value{GDBN} requires it.
  
  @value{GDBN} follows an additional set of coding standards specific to
  @value{GDBN}, as described in the following sections.
  
  @cindex compiler warnings
! You can configure with @samp{--enable-build-warnings} or
! @samp{--enable-gdb-build-warnings} to get GCC to check on a number of
! these rules.  @value{GDBN} sources ought not to engender any complaints,
! unless they are caused by bogus host systems.  (The exact set of enabled
! warnings is currently @samp{-Wimplicit -Wreturn-type -Wcomment
! -Wtrigraphs -Wformat -Wparentheses -Wpointer-arith -Wuninitialized}.
  
  @subsection Formatting
  
--- 4056,4134 ----
  
  @value{GDBN} follows the GNU coding standards, as described in
  @file{etc/standards.texi}.  This file is also available for anonymous
! FTP from GNU archive sites.  @value{GDBN} takes a strict interpretation
! of the standard; in general, when the GNU standard recommends a practice
! but does not require it, @value{GDBN} requires it.
  
  @value{GDBN} follows an additional set of coding standards specific to
  @value{GDBN}, as described in the following sections.
  
+ 
+ @subsection ISO-C
+ 
+ @value{GDBN} assumes an ISO-C compliant compiler.
+ 
+ @value{GDBN} does not assume an ISO-C or POSIX compliant C library.
+ 
+ 
+ @subsection Memory Management
+ 
+ @value{GDBN} uses the functions @samp{xmalloc()}, @samp{xrealloc()} and
+ @samp{xcalloc()} when allocating memory.  Unlike @samp{malloc()}
+ et.al. these functions do not return when the memory pool is empty.
+ Instead, they unwind the stack using cleanups.  These functions return
+ @code{NULL} when requested to allocate a chunk of memory of size zero.
+ 
+ @emph{Pragmatics: By using these functions, the need to check every
+ memory allocation is removed.  These functions provide portable
+ behavour.}
+ 
+ @value{GDBN} uses the function @code{xfree()} to return memory to the
+ memory pool.  Consistent with ISO-C, this function ignores a request to
+ free a @code{NULL} pointer.
+ 
+ @emph{Pragmatics: On some systems @code{free()} fails when passed a
+ @code{NULL} pointer.}
+ 
+ @value{GDBN} can use the non-portable function for the allocation of
+ small tempoary values (such as strings).
+ 
+ @emph{Pragmatics: This function is very non-portable.  Some systems
+ restrict the memory being allocated to no more than a few kilobytes.}
+ 
+ @value{GDBN} uses the string function @code{xstrdup()} and the print
+ function @code{xasprintf()}.
+ 
+ @emph{Pragmatics: @code{asprintf()} can fail.  Print functions such as
+ @code{sprintf()} are very proned to buffer overflow errors.}
+ 
+ @value{GDBN} must not use the functions @samp{malloc()},
+ @samp{realloc()}, @samp{calloc()}, @samp{free()} and @samp{asprintf()}.
+ 
+ 
+ @subsection Compiler Warnings
  @cindex compiler warnings
! 
! With few exceptions, developers should include the configuration option
! @samp{--enable-gdb-build-warnings=,-Werror} when building @value{GDB}.
! The exceptions are listed in the file @samp{gdb/MAINTAINERS}.
! 
! This option causes @value{GDBN} (when built using GCC) to be compiled
! with a carefully selected list of compiler warning flags.  Any warnings
! from those flags being treated as errors.
!  
! The current list of warning flags includes @samp{-Wimplicit
! -Wreturn-type -Wcomment -Wtrigraphs -Wformat -Wparentheses
! -Wpointer-arith -Wuninitialized}.
! 
! @emph{Pragmatics: Due to the way that @value{GDBN} is implemented most
! functions have unused parameters.  Consequently the warning
! @samp{-Wunused-parameter} is precluded from the list.  The macro
! @samp{ATTRIBUTE_UNUSED} is not used as it leads to false negatives ---
! it is not an error to have @samp{ATTRIBUTE_UNUSED} on a parameter that
! is being used.  The options @samp{-Wall} and @samp{-Wunused} are also
! precluded because they both include @samp{-Wunused-parameter}.}
! 
  
  @subsection Formatting
  
*************** warnings is currently @samp{-Wimplicit -
*** 4059,4078 ****
  The standard GNU recommendations for formatting must be followed
  strictly.
  
! Note that while in a definition, the function's name must be in column
! zero; in a function declaration, the name must be on the same line as
! the return type.
! 
! In addition, there must be a space between a function or macro name and
! the opening parenthesis of its argument list (except for macro
! definitions, as required by C).  There must not be a space after an open
! paren/bracket or before a close paren/bracket.
  
  While additional whitespace is generally helpful for reading, do not use
  more than one blank line to separate blocks, and avoid adding whitespace
! after the end of a program line (as of 1/99, some 600 lines had whitespace
! after the semicolon).  Excess whitespace causes difficulties for
! @code{diff} and @code{patch} utilities.
  
  @subsection Comments
  
--- 4136,4159 ----
  The standard GNU recommendations for formatting must be followed
  strictly.
  
! While in a definition, the function's name must be in column zero; in a
! function declaration, the name must be on the same line as the return
! type.
  
+ @example
+ void foo (void);
+ @end example
+ 
+ There must be a space between a function or macro name and the opening
+ parenthesis of its argument list (except for macro definitions, as
+ required by C).  There must not be a space after an open paren/bracket
+ or before a close paren/bracket.
+ 
  While additional whitespace is generally helpful for reading, do not use
  more than one blank line to separate blocks, and avoid adding whitespace
! after the end of a program line (as of 1/99, some 600 lines had
! whitespace after the semicolon).  Excess whitespace causes difficulties
! for @code{diff} and @code{patch} utilities.
  
  @subsection Comments
  
*************** than will fit, and then somebody will ha
*** 4104,4114 ****
--- 4185,4197 ----
  @subsection C Usage
  
  @cindex C data types
+ 
  Code must not depend on the sizes of C data types, the format of the
  host's floating point numbers, the alignment of anything, or the order
  of evaluation of expressions.
  
  @cindex function usage
+ 
  Use functions freely.  There are only a handful of compute-bound areas
  in @value{GDBN} that might be affected by the overhead of a function
  call, mainly in symbol reading.  Most of @value{GDBN}'s performance is
*************** limited by the target interface (whether
*** 4117,4138 ****
  However, use functions with moderation.  A thousand one-line functions
  are just as hard to understand as a single thousand-line function.
  
! @subsection Function Prototypes
  
  @cindex function prototypes
- Prototypes must be used to @emph{declare} functions, and may be used
- to @emph{define} them.  Prototypes for @value{GDBN} functions must
- include both the argument type and name, with the name matching that
- used in the actual function definition.
  
  All external functions should have a declaration in a header file that
  callers include, except for @code{_initialize_*} functions, which must
  be external so that @file{init.c} construction works, but shouldn't be
  visible to random source files.
  
! All static functions must be declared in a block near the top of the
! source file.
  
  @subsection Clean Design and Portable Implementation
  
  @cindex design
--- 4200,4249 ----
  However, use functions with moderation.  A thousand one-line functions
  are just as hard to understand as a single thousand-line function.
  
! @emph{Macros are bad, M'kay.}
! 
! @cindex types
! 
! Declarations like @samp{struct foo *} should be used in preference to
! declarations like @samp{typedef struct foo {} *foo_ptr}.
  
+ 
+ @subsection Function Prototypes
  @cindex function prototypes
  
+ Prototypes must be used when both @emph{declareing} and @emph{defineing}
+ a function.  Prototypes for @value{GDBN} functions must include both the
+ argument type and name, with the name matching that used in the actual
+ function definition.
+ 
  All external functions should have a declaration in a header file that
  callers include, except for @code{_initialize_*} functions, which must
  be external so that @file{init.c} construction works, but shouldn't be
  visible to random source files.
+ 
+ Where a source file needs a forward declaration of a static function,
+ that declaration must appear in a block near the top of the source file.
+ 
+ 
+ @subsection Internal Error Recovery
+ 
+ @value{GDBN} must not call @samp{abort()}.  Use @samp{internal_error()}.
  
! @value{GDBN} must not call @samp{assert()}.  Use @samp{gdb_assert()}.
  
+ 
+ @subsection File Names
+ 
+ Any file that is used to build @value{GDBN} on either DJGPP or Cygwin
+ must be 8.3 compliant.
+ 
+ When @value{GDBN} has a local version of a system header file (eg
+ @samp{gdb_string.h}) the file name based on the POSIX header prefixed
+ with @samp{gdb_}.
+ 
+ For all other files @samp{-} is used as the separator.
+ 
+ 
  @subsection Clean Design and Portable Implementation
  
  @cindex design
*************** consolidated into @file{infptrace.c}.  @
*** 4302,4309 ****
  with variations between systems the same way any system-independent
  file would (hooks, @code{#if defined}, etc.), and machines which are
  radically different don't need to use @file{infptrace.c} at all.
  
- Don't put debugging @code{printf}s in the code.
  
  @node Porting GDB
  
--- 4413,4424 ----
  with variations between systems the same way any system-independent
  file would (hooks, @code{#if defined}, etc.), and machines which are
  radically different don't need to use @file{infptrace.c} at all.
+ 
+ All debugging code must be controllable using the @samp{set debug
+ <module>} command.  Do not use @samp{printf}s to print trace messages.
+ Use @samp{fprintf_unfiltered(gdb_stdlog, ...}.  Do not use @samp{#ifdef
+ DEBUG}.
  
  
  @node Porting GDB