(gdbint.info) Coding
Info Catalog
(gdbint.info) Support Libraries
(gdbint.info) Top
(gdbint.info) Porting GDB
Coding
******
This chapter covers topics that are lower-level than the major
algorithms of GDB.
Cleanups
========
Cleanups are a structured way to deal with things that need to be
done later. When your code does something (like `malloc' some memory,
or open a file) that needs to be undone later (e.g. free the memory or
close the file), it can make a cleanup. The cleanup will be done at
some future point: when the command is finished, when an error occurs,
or when your code decides it's time to do cleanups.
You can also discard cleanups, that is, throw them away without doing
what they say. This is only done if you ask that it be done.
Syntax:
`struct cleanup *OLD_CHAIN;'
Declare a variable which will hold a cleanup chain handle.
`OLD_CHAIN = make_cleanup (FUNCTION, ARG);'
Make a cleanup which will cause FUNCTION to be called with ARG (a
`char *') later. The result, OLD_CHAIN, is a handle that can be
passed to `do_cleanups' or `discard_cleanups' later. Unless you
are going to call `do_cleanups' or `discard_cleanups' yourself,
you can ignore the result from `make_cleanup'.
`do_cleanups (OLD_CHAIN);'
Perform all cleanups done since `make_cleanup' returned OLD_CHAIN.
E.g.:
make_cleanup (a, 0);
old = make_cleanup (b, 0);
do_cleanups (old);
will call `b()' but will not call `a()'. The cleanup that calls
`a()' will remain in the cleanup chain, and will be done later
unless otherwise discarded.
`discard_cleanups (OLD_CHAIN);'
Same as `do_cleanups' except that it just removes the cleanups from
the chain and does not call the specified functions.
Some functions, e.g. `fputs_filtered()' or `error()', specify that
they "should not be called when cleanups are not in place". This means
that any actions you need to reverse in the case of an error or
interruption must be on the cleanup chain before you call these
functions, since they might never return to your code (they `longjmp'
instead).
Wrapping Output Lines
=====================
Output that goes through `printf_filtered' or `fputs_filtered' or
`fputs_demangled' needs only to have calls to `wrap_here' added in
places that would be good breaking points. The utility routines will
take care of actually wrapping if the line width is exceeded.
The argument to `wrap_here' is an indentation string which is
printed _only_ if the line breaks there. This argument is saved away
and used later. It must remain valid until the next call to
`wrap_here' or until a newline has been printed through the
`*_filtered' functions. Don't pass in a local variable and then return!
It is usually best to call `wrap_here()' after printing a comma or
space. If you call it before printing a space, make sure that your
indentation properly accounts for the leading space that will print if
the line wraps there.
Any function or set of functions that produce filtered output must
finish by printing a newline, to flush the wrap buffer, before switching
to unfiltered ("`printf'") output. Symbol reading routines that print
warnings are a good example.
GDB Coding Standards
====================
GDB follows the GNU coding standards, as described in
`etc/standards.texi'. This file is also available for anonymous FTP
from GNU archive sites. GDB takes a strict interpretation of the
standard; in general, when the GNU standard recommends a practice but
does not require it, GDB requires it.
GDB follows an additional set of coding standards specific to GDB,
as described in the following sections.
You can configure with `--enable-build-warnings' to get GCC to check
on a number of these rules. GDB sources ought not to engender any
complaints, unless they are caused by bogus host systems. (The exact
set of enabled warnings is currently `-Wall -Wpointer-arith
-Wstrict-prototypes -Wmissing-prototypes -Wmissing-declarations'.
Formatting
----------
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 diff and patch.
Comments
--------
The standard GNU requirements on comments must be followed strictly.
Block comments must appear in the following form, with no `/*'- or
'*/'-only lines, and no leading `*':
/* Wait for control to return from inferior to debugger. If inferior
gets a signal, we may decide to start it up again instead of
returning. That is why there is a loop in this function. When
this function actually returns it means the inferior should be left
stopped and GDB should read more commands. */
(Note that this format is encouraged by Emacs; tabbing for a
multi-line comment works correctly, and M-Q fills the block
consistently.)
Put a blank line between the block comments preceding function or
variable definitions, and the definition itself.
In general, put function-body comments on lines by themselves, rather
than trying to fit them into the 20 characters left at the end of a
line, since either the comment or the code will inevitably get longer
than will fit, and then somebody will have to move it anyhow.
C Usage
-------
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.
Use functions freely. There are only a handful of compute-bound
areas in GDB that might be affected by the overhead of a function call,
mainly in symbol reading. Most of GDB's performance is limited by the
target interface (whether serial line or system call).
However, use functions with moderation. A thousand one-line
functions are just as hard to understand as a single thousand-line
function.
Function Prototypes
-------------------
Prototypes must be used to _declare_ functions, and may be used to
_define_ them. Prototypes for GDB 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 `_initialize_*' functions, which must
be external so that `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.
Clean Design
------------
In addition to getting the syntax right, there's the little question
of semantics. Some things are done in certain ways in GDB because long
experience has shown that the more obvious ways caused various kinds of
trouble.
You can't assume the byte order of anything that comes from a target
(including VALUEs, object files, and instructions). Such things must
be byte-swapped using `SWAP_TARGET_AND_HOST' in GDB, or one of the swap
routines defined in `bfd.h', such as `bfd_get_32'.
You can't assume that you know what interface is being used to talk
to the target system. All references to the target must go through the
current `target_ops' vector.
You can't assume that the host and target machines are the same
machine (except in the "native" support modules). In particular, you
can't assume that the target machine's header files will be available
on the host machine. Target code must bring along its own header files
- written from scratch or explicitly donated by their owner, to avoid
copyright problems.
Insertion of new `#ifdef''s will be frowned upon. It's much better
to write the code portably than to conditionalize it for various
systems.
New `#ifdef''s which test for specific compilers or manufacturers or
operating systems are unacceptable. All `#ifdef''s should test for
features. The information about which configurations contain which
features should be segregated into the configuration files. Experience
has proven far too often that a feature unique to one particular system
often creeps into other systems; and that a conditional based on some
predefined macro for your current system will become worthless over
time, as new versions of your system come out that behave differently
with regard to this feature.
Adding code that handles specific architectures, operating systems,
target interfaces, or hosts, is not acceptable in generic code. If a
hook is needed at that point, invent a generic hook and define it for
your configuration, with something like:
#ifdef WRANGLE_SIGNALS
WRANGLE_SIGNALS (signo);
#endif
In your host, target, or native configuration file, as appropriate,
define `WRANGLE_SIGNALS' to do the machine-dependent thing. Take a bit
of care in defining the hook, so that it can be used by other ports in
the future, if they need a hook in the same place.
If the hook is not defined, the code should do whatever "most"
machines want. Using `#ifdef', as above, is the preferred way to do
this, but sometimes that gets convoluted, in which case use
#ifndef SPECIAL_FOO_HANDLING
#define SPECIAL_FOO_HANDLING(pc, sp) (0)
#endif
where the macro is used or in an appropriate header file.
Whether to include a "small" hook, a hook around the exact pieces of
code which are system-dependent, or whether to replace a whole function
with a hook depends on the case. A good example of this dilemma can be
found in `get_saved_register'. All machines that GDB 2.8 ran on just
needed the `FRAME_FIND_SAVED_REGS' hook to find the saved registers.
Then the SPARC and Pyramid came along, and `HAVE_REGISTER_WINDOWS' and
`REGISTER_IN_WINDOW_P' were introduced. Then the 29k and 88k required
the `GET_SAVED_REGISTER' hook. The first three are examples of small
hooks; the latter replaces a whole function. In this specific case, it
is useful to have both kinds; it would be a bad idea to replace all the
uses of the small hooks with `GET_SAVED_REGISTER', since that would
result in much duplicated code. Other times, duplicating a few lines
of code here or there is much cleaner than introducing a large number
of small hooks.
Another way to generalize GDB along a particular interface is with an
attribute struct. For example, GDB has been generalized to handle
multiple kinds of remote interfaces - not by #ifdef's everywhere, but
by defining the "target_ops" structure and having a current target (as
well as a stack of targets below it, for memory references). Whenever
something needs to be done that depends on which remote interface we are
using, a flag in the current target_ops structure is tested (e.g.
`target_has_stack'), or a function is called through a pointer in the
current target_ops structure. In this way, when a new remote interface
is added, only one module needs to be touched - the one that actually
implements the new remote interface. Other examples of
attribute-structs are BFD access to multiple kinds of object file
formats, or GDB's access to multiple source languages.
Please avoid duplicating code. For example, in GDB 3.x all the code
interfacing between `ptrace' and the rest of GDB was duplicated in
`*-dep.c', and so changing something was very painful. In GDB 4.x,
these have all been consolidated into `infptrace.c'. `infptrace.c' can
deal with variations between systems the same way any
system-independent file would (hooks, #if defined, etc.), and machines
which are radically different don't need to use infptrace.c at all.
Don't put debugging printfs in the code.
Info Catalog
(gdbint.info) Support Libraries
(gdbint.info) Top
(gdbint.info) Porting GDB
automatically generated byinfo2html