RTEMS GNU Tools On-Line Library

Coding

GDB Internals

Chapter 12: Coding

This chapter covers topics that are lower-level than the major algorithms of GDB.

12.1: 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).

12.2: 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.

12.3: 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'.

12.3.1: 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.

12.3.2: 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.

12.3.3: 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.

12.3.4: 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.

12.3.5: 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.

GDB Internals