680xx Apollo support kit for GNU debugger gdb-4.13 for use with
gcc-2.6.0 or later and gas-2.3 or later under the SR10.x OS.

     This patch kit requires a virgin copy of gdb-4.13.  It should be
built using the GNU C compiler.  It supports .stabs debugging, but
NOT the native Apollo format.

     This code has been tested on an Apollo DN4500 running SR10.3.5 with the
ANSI header files and a BSD environment using gcc.  It should work on any
SR10 system.  New files are provided separately from the patch file since
some versions of patch will not make new files.  The Apollo C compiler has
not been tested, but is likely to have problems.

This patch kit contains the following files:

README:       this document
DIFFS:        context diffs
copyconfigs:  A shell script to copy configuration files

Installation:

Unpack gdb-4.13 and this patch kit.  This gives directories gdb-4.13 and
apolgdb-4.13 at the same level.  Apply the patches and set up the
configuration files with the following UNIX shell commands.
(Running from the directory containing gdb-4.13 and apolgdb-4.13.)

/usr/new/patch -p0 < apolgdb-4.13/DIFFS
apolgdb-4.13/copyconfigs

Now configure and build the debugger using m68k-apollo-bsd for the
BSD environment or m68k-apollo-sysv for the sys5 environment.
This builds using gcc with optimization, stripped output, and no
debugging symbols.  To change compiler options, edit the makefile
stubs in gdb-4.13/config and gdb-4.13/gdb/config/m68k, then
run apolgdb-4.13/copyconfigs from just above gdb-4.13 to propagate
the changes.  Running configure will use the new values.

cd gdb-4.13
configure m68k-apollo-bsd
make

The finished debugger is in gdb-4.13/gdb/gdb.



Notes:

     The BFD COFF support code is used.  Debugging information is stored
in COFF sections names ".stab" and ".stabstr".  The native Apollo format
is not supported.  Code to do so is present in gdb-4.13/gdb/dstread.c, but
it is disabled by this patch kit.


Source files changed by the patch kit:

bfd/coff-apollo.c:  changed tables, added some new code
bfd/coffcode.h:
  sec_to_styp_flags, styp_to_sec_flags, coff_set_flags:
    added Apollo-specific flags and section names.
bfd/coffswap.h:  coff_swap_aouthdr_out:  added missing Apollo fields.

gdb/a68v-nat.c:  BUGFIX corrected FP register placements in
  fetch_inferior_registers () and store_inferior_registers ().
  Added apollo_float_info () for the "info float" command.
gdb/breakpoint.c:  create_longjmp_breakpoint () defining UNBREAKABLE_LONGJMP
  disables the automatic breakpoints for the *longjmp routines.
gdb/coffread.c:  read_one_sym () defining APOLLO_KGT_LOOKUP enables
  special symbol code for Apollo shared library objects.
gdb/stabsread.c:
  define_symbol () BUGFIX global symbols had address of zero.  Defining
    N_GSYM_VALUE_0 enables the fix.
gdb/symfile.c:
  find_sym_fns () disable native debugger code, use stabs-in-COFF instead.

The configuration files were changed to add Apollo configurations and to
make all the Apollo makefile stubs consistent with each other.



Known bugs and limitations:

The native Apollo debugging format is not supported.
Once you have GCC and GDB, you probably won't want that Apollo CC and
DDE stuff anyway!  :-)

Tracing position-independent code (PIC) and shared library code is not well
supported.  Setting a breakpoint to a PIC function will fail, but setting
a breakpoint to the first line of the function works.  This could be
hard to fix since PIC function entry points are in the data area.
As a rule, shared library code to be debugged should be compiled and loaded
as part of an ordinary program, debugged, then recompiled as PIC after
it works.

Stepping out of the "main" routine may cause a harmless message about
not being able to set breakpoint 0.  This is caused by the PIC code
for _start in the Apollo libraries.

Data objects in shared libraries will appear as type "int" due to Apollo
symbol conventions.  Printing "errno" or calling "printf" does work.
Explicit casts may be used to print composite shared objects.

Stepping across a longjmp call is not breakpoint-protected.  The longjmp
routine is in a write-protected shared library, so the code to
automatically set breakpoints aroung longjmp is turned off.  Stepping
across a longjmp call will result in the target program regaining
control.  As a work-around, manually set breakpoints just after each
setjmp call.

It is not possible to set a breakpoint at any shared library routine such
as printf.  All the global shared library code is write-protected which
makes placing breakpoints inside it impossible.

The Apollo "strip" command can not remove the debugging sections.

The Apollo DN10000 is not supported.



Possible improvements and things to watch.

printcmd.c:  print_frame_args () if the NUM parameter is not -1, then
  the integer rounding for current_offset will not be appropriate.
  Currently NUM is always -1, by way of the FRAME_NUM_ARGS macro
  in tm-m68k.h.

a68v-nat.c:  the floating point register retrieval does not use the
  Apollo-supplied routines.  This code works at SR10.3.5 but might
  fail if other OS revisions store the registers differently in the
  "struct ptrace_$floating_regs_m68k" in ptrace.h.

m68k-tdep.c:  better support for PIC code could be added by changing
  m68k_skip_prologue () and m68k_find_saved_regs () to know about the
  PIC entry sequence.  This would only be useful for debugging PIC code
  that was loaded as an ordinary program.  Shared library code is
  usually write-protected so that breakpoints are useless.



Questions about this patch kit may be addressed to

William J. Eaton
Email wje@hoffman.rstnu.bcm.tmc.edu
Phone (USA) (713) 798-5161
