14 Native Debugging

Several files control gdb's configuration for native support:

gdb/config/arch/xyz.mh

Specifies Makefile fragments needed by a native configuration on machine xyz. In particular, this lists the required native-dependent object files, by defining ‘NATDEPFILES=...’. Also specifies the header file which describes native support on xyz, by defining ‘NAT_FILE= nm-xyz.h’. You can also define ‘NAT_CFLAGS’, ‘NAT_ADD_FILES’, ‘NAT_CLIBS’, ‘NAT_CDEPS’, ‘NAT_GENERATED_FILES’, etc.; see Makefile.in.

Maintainer's note: The .mh suffix is because this file originally contained Makefile fragments for hosting gdb on machine xyz. While the file is no longer used for this purpose, the .mh suffix remains. Perhaps someone will eventually rename these fragments so that they have a .mn suffix.

gdb/config/arch/nm-xyz.h

(nm.h is a link to this file, created by configure). Contains C macro definitions describing the native system environment, such as child process control and core file support.

gdb/xyz-nat.c

Contains any miscellaneous C code required for this native support of this machine. On some machines it doesn't exist at all.

There are some “generic” versions of routines that can be used by various systems. These can be customized in various ways by macros defined in your nm-xyz.h file. If these routines work for the xyz host, you can just include the generic file's name (with ‘.o’, not ‘.c’) in NATDEPFILES.

Otherwise, if your machine needs custom support routines, you will need to write routines that perform the same functions as the generic file. Put them into xyz-nat.c, and put xyz-nat.o into NATDEPFILES.

inftarg.c

This contains the target_ops vector that supports Unix child processes on systems which use ptrace and wait to control the child.

procfs.c

This contains the target_ops vector that supports Unix child processes on systems which use /proc to control the child.

fork-child.c

This does the low-level grunge that uses Unix system calls to do a “fork and exec” to start up a child process.

infptrace.c

This is the low level interface to inferior processes for systems using the Unix ptrace call in a vanilla way.

14.1 ptrace

14.2 /proc

14.3 win32

14.4 shared libraries

14.4.1 AIX Shared Library Support

Shared library support on AIX is based on reading some data provided by the loader. With a live process, this information is accessed via a ptrace call (PT_LDINFO), while it is obtained by reading the ‘.ldinfo’ section when debugging from a core file. In both cases, the data has the same format, provided by the sys/ldr.h system header file.

Internally, the relevant portions of the loader information is transformed into an XML representation, which lists all objects currently mapped in memory. The associated DTD can be found in gdb/features/library-list-aix.dtd. For each library element, the following parameters are reported:

• name, the path name of an object. This is usually the name of an archive, or the name of the main executable.
• If the name parameter refers to an archive, member provides the name of the object inside the archive on which the program depends. Otherwise, this field should be omitted.
• text_addr, the address where the .text section was mapped in memory.
• text_size, the size of the .text section.
• data_addr, the address where the .data section was mapped in memory.
• data_size, the size of the .data section.

By convention, the library list always has at least one element, and the first entry always refers to the main executable.

Below is an example of such XML representation for a small program:

     <library-list-aix version="1.0">
       <library name="simple"
                text_addr="0x0000000010000000"
                text_size="128720"
                data_addr="0x0000000020000f00"
                data_size="31148">
       </library>
       <library name="/lib/libc.a"
                member="shr.o"
                text_addr="0x00000000d0100700"
                text_size="4152684"
                data_addr="0x00000000f0633e50"
                data_size="875944">
       </library>
     </library-list-aix>

In that example, the list shows that the main executable is named simple, and its text section was loaded at 0x10000000. This program depends on member shr.o from the /lib/libc.a archive, whose text and data sections were loaded at (resp.) 0xd0100700 and 0xf0633e50.

14.5 Native Conditionals

When gdb is configured and compiled, various macros are defined or left undefined, to control compilation when the host and target systems are the same. These macros should be defined (or left undefined) in nm-system.h.

I386_USE_GENERIC_WATCHPOINTS

An x86-based machine can define this to use the generic x86 watchpoint support; see I386_USE_GENERIC_WATCHPOINTS.

START_INFERIOR_TRAPS_EXPECTED

When starting an inferior, gdb normally expects to trap twice; once when the shell execs, and once when the program itself execs. If the actual number of traps is something other than 2, then define this macro to expand into the number expected.