gdbinit-MacsBug   [plain text]


#################################################################################
#                                                                               #
#                                gdbinit-MacsBug                                #
#                                                                               #
#            Macsbug-style gdb command definitions and plugin loader            #
#                                                                               #
#                                 Ira L. Ruben                                  #
#                   Copyright Apple Computer, Inc. 2000-2005                    #
#                                                                               #
#################################################################################

# This file can be either sourced'ed in by .gdbinit or explicitly to define a set
# of gdb commands that simulate a subset of MacsBug commands.  It is as faithful
# a simulation as possible within the limits of the environment.  There are also
# some extensions where it makes sense in the context of the debugging paradigm
# imposed by gdb.  Also a MacsBug-like UI is supported (use the MB command to
# initiate the UI).

# Once gdb is loaded type HELP to see a summary of all gdb command classes.  
# There are three additional classes for MacsBug: "macsbug", "screen", and 
# "useful".  Typing "help macsbug" give a summary of all MacsBug commands.  Typing 
# "help screen" gives a summary of all MacsBug screen UI-related commands which
# are additions to this MacsBug implementation.  Typing "help useful" give a list
# of "useful" gdb commands that could be used to extend this script.  Some of
# these are used internally, or are descendents from the original gdb script that
# preceded this script, or are just plain useful in their own right and should
# probably be in gdb in the first place!.

# Two existing classes, "aliases" and "support" also list some MacsBug commands.
# The "aliases" class lists aliases for some commands that don't follow the
# standard gdb abbreviation conventions (e.g., SC6 is the same as SC).  The
# "support" class lists the SET options.

# As indicated at the end of the HELP class summary you can type "mb-notes" to
# get some additional information specifically related to this implementation of
# MacsBug.

# Finally, also as indicated in the HELP summary, typing "help" followed by a
# command name displays a summary for that specific command.

# NOTE: The expression syntax used in the gdb commands is written using C syntax
#       so this implementation is only applicable for debugging C/C++.  If you
#       are trying to debug any other language, you're probably screwed!

# The author has endeavored to produce as complete a set of MacsBug commands as
# feasible within the restrictions imposed by the environment.  But others may
# have additional ideas.  So contributions and embellishments are welcome.  The
# only restrictions are that to be placed in this particular universe of commands
# they must be variants of *EXISTING* MacsBug commands.  Any other "flavors" do
# not belong here, except perhaps those dealing with the UI.

# You will not see many of the commands in this file.  That's because they are
# implemented in a set of plugins that are loaded from this file with the Apple
# gdb LOAD_PLUGIN command.  This is an Apple-specific extension to gdb.  Not only
# that the plugins must be built for the system they are running on (or at least
# compatible with the version of gdb on that system).  As such these are not as
# portable as the pure script version on which this implementation is based.

# Revision history:
#
#                                              Version 1.0
#                                              -----------
#	12-Dec-2000	ILR	Took the original gdbinit-MacsBug-without-plugin
#				  script as the starting point for this script.
#				  However this script is a shadow of its former
#				  self!  Most of the commands are now written using
#				  the Apple gdb plugin architecture.  Also a
#				  MacsBug-like UI is implemented.
#	 3-Jan-2001	ILR	Override the L[IST] command to make listing
#				  contiguous when the MacsBug screen is off.
#	 9-Jan-2001	ILR	Removed G command and made it a plugin to get around
#				  gdb bug involving executing commands assoicated
#				  with a breakpoint initiated from a CONTINUE
#				  executed withing a DEFINE command.
#				Added RA (run again) command.
#				Fixed some capitalization errors in help commands.
#
#                                              Version 1.1
#                                              -----------
#	 9-Feb-2001	ILR	Removed MQ and MSR from sidebar reg display.  Min
#				  vertical screen size now 44 instead of 46.
#	17-Feb-2001	ILR	Renamed MacsBug plugin to MacsBug_plugin and changed
#				  all related documentation.
#				Removed the install_MacsBug script.
#	24-Feb-2001	ILR	Fixed LOG command to handle '~'s in the pathname.
#	17-Mar-2001	ILR	Fixed plugin code to more gracefully coexist with
#				  ProjectBuilder. There were redirection interactions
#				  between PB and the plugin.
#				Added istty() tests in key points to prevent MacsBug
#				  from doing xterm operations when not talking to a
#				  terminal as in the case with ProjectBuilder.
#				Fixed a bug in the TD command which had a format
#				  error displaying the XER SOC bits.
#				Enhanced gdb API to allow DOCUMENT help with option-
#				   space formatting to be replaced with real spaces
#				   to display correctly in Project Builder.
#	 31-Mar-2001	ILR	Recognize all the abbreviations for the LIST command
#				  to allow these to produce contiguous listings when
#				  the MacsBug screen is off.
#				Override N[EXT], S[TEP], NEXTI, STEPI so that these
#				   also produce contiguous listings when the MacsBug
#				   screen is off.
#				Suppress attempts to make listings contiguous if such
#				  commands are run from scripts.
#	 4-Apr-2001	ILR	Enhanced WH to display file/line info and the source
#				  line if possible.
#	 3-May-2001	ILR	Changed WH so that it always defaults to WH $pc when
#				  the argument is omitted.
#				Fixed bug in register display to adjust the stack
#				  display to account for a changed window size.
#				Fixed scroll mode disassembly displays to wrap lines
#				  instead of being chopped off by register sidebar.
#	17-May-2001	ILR	Changed WH again to act something like gdb's INFO
#				  LINE command. Now takes same syntax for argument.
#	 2-Jun-2001	ILR	Changed TF to plugin and made it more MacsBug-like.
#				  TV finially implemented!
#	 8-Jun-2001	ILR	Converted BRD, BRC, SO, and T to plugins.  Only ES
#				  now remains as a DEFINE (not counting mb-notes).
#				Fixed WH to show context around target line.
#				Fixed bug in error recovery for temporarily
#				  reclassifying HELP classes.
#				Added SET mb-sidebar to enable/disable the side-
#				  bar register display when ID, IL, IP, SO, or SI
#				  are done in scroll (normal gdb) mode. 
#
###################################################################################
###################################################################################
#
# TO DO:
#    I cannot think of a thing more I want to do with this :-)
#
###################################################################################
###################################################################################

# Current highest command identifier value for $__lastcmd__ is 48
# 19, 20 are available.

# In each command assign $__lastcmd__ to a unique command number for each new
# command where applicable and update the above comment to make it easier to
# remember what to assign to future commands.

# $__lastcmd__ is not just "noise".  Some MacsBug simulated commands need to
# know what the previous command was to perform the required MacsBug semantics. 

###################################################################################
###################################################################################

#
# MB-NOTES - Additional info about MacsBug implementation.
#
define mb-notes
help mb-notes
end
#2345678901234567890123456789012345678901234567890123456789012345678901234567890
document mb-notes
Ê
The "MacsBug" supported here is gdb extended to support a subset of the Mac
Classic MacsBug commands and a MacsBug-like screen UI.  Thus it basically is
a variant of MacsBug with source-level debugging!
Ê
Use gdb's HELP to see the list of supported commands.  You will see two
additional classes when you type HELP; "macsbug" and "screen". They will allow
you to see a summary of the additional supported commands.
 
Below are some additional notes relating to this implementations differences
with the Mac Classic MacsBug.
Ê
Ê1. The $dot gdb variable is the last address referenced by certain commands.
ÊÊÊÊThis corresponds to Mac Classic's MacsBug '.' variable.  For example, SM
ÊÊÊÊsets $dot to the first address that was changed.  The default for many
ÊÊÊÊcommands is to use $dot as their address argument.  Typing DM will display
ÊÊÊÊthe memory just set and set the last command to DM.  A return after the
ÊÊÊÊparameterless DM command will use the $dot set by it to display then next
ÊÊÊÊblock of memory in sequence.  Note that this is the normal MacsBug behavior
ÊÊÊÊbut that is different from gdb which would repeat the last command.
Ê
Ê2. The $colon gdb variable is the address of the start of the proc containing
ÊÊÊÊthe current PC when the target is running.
Ê
Ê3. Only C/C++ can be debugged since the gdb commands use C/C++ syntax for
ÊÊÊÊtheir implementation (restriction imposed by this implementation's use of
ÊÊÊÊgdb).
Ê
Ê4. Arguments are written using C/C++ syntax (e.g., use -> instead of ^, !=
ÊÊÊÊinstead of <>, etc.).
Ê
Ê5. Only one command per line allowed (gdb restriction).
Ê
Ê6. Some restrictions on the commands that are supported. Do help on individual
ÊÊÊÊcommands for details.
Ê
Ê7. Decimal values are shown without leading '#' and hex is shown with
ÊÊÊÊa '0x' prefix (except in disassemblies and other displays where it's
ÊÊÊÊobvious it's hex).
Ê
Ê8. The input radix is as defined by the gdb "SET input-radix" command.  The
ÊÊÊÊdefault is decimal unlike MacsBug which defaults to hex.  Use the gdb
ÊÊÊÊcommand "SHOW input-radix" to verify the input radix.
Ê
Ê9. Many of the commands are not permitted until there is a target program
ÊÊÊÊrunning (using the G or gdb RUN command).  Most of the commands will
ÊÊÊÊcause some kind of error report until there is a target running.  Of
ÊÊÊÊcourse with Mac Classic MacsBug there is always something running.  But
ÊÊÊÊthat's not the case with gdb.
Ê
10. Some of the MacsBug SET options are supported.  Use HELP support to see
ÊÊÊÊa summary of SET commands.  All the MacsBug SET options start with "mb-"
ÊÊÊÊso you can use standard command completion (hitting tab after typing the
ÊÊÊÊ"mb" will show you all those SET options.  For compatibility with
ÊÊÊÊMac Classic MacsBug, SET ditto and SET unmangle are also supported.
Ê
11. Some Mac Classic MacsBug commands like SC6, SC7, and SC or ILP and IL
ÊÊÊÊare identical in the gdb implementation.  These alternatives take the
ÊÊÊÊform of gdb aliases.  Use HELP aliases to see the supported aliases.
Ê
12. SI is defined as the MacsBug S command since gdb already has a S
ÊÊÊÊcommand.  But this overrides gdb's SI abbreviation for STEPI.
Ê
13. When the MacsBug screen is being used command lines may be continued
ÊÊÊÊ(using '\') within the area defined for commands.  The default number
ÊÊÊÊof lines is 2 but may be increased up to 15 using the SET mb-cmd-area.
ÊÊÊÊContinuing more than the allotted space is allowed but will cause the
ÊÊÊÊcommand lines to scroll up within their area.  Unfortunately this does
ÊÊÊÊnot happen if a command is interactively created with DEFINE and you
ÊÊÊÊtry to continue one of the command's lines.  The continuations are
ÊÊÊÊallowed.  But they just don't scroll.
Ê
14. Unlike Mac Classic MacsBug, there is only one screen for gdb and the
ÊÊÊÊtarget program.  Further, gdb has no control over output generated by
ÊÊÊÊthe target program or caused by it (e.g., dyld messages).  Thus the
ÊÊÊÊMacsBug screen could get "mangled".  Use the REFRESH command to restore
ÊÊÊÊthe MacsBug screen or turn off the MacsBug screen and debug with gdb's
ÊÊÊÊnormal scroll mode.  All the MacsBug commands still work in scroll mode
ÊÊÊÊand any commands that cause disassembly will display the current
ÊÊÊÊregisters on the right side of the terminal screen (to minimize the
ÊÊÊÊaffect on scroll back viewing).
Ê
15. A set of possibly useful commands for extending this script are available.
ÊÊÊÊTyping "help useful" will list those commands.  You will see some output
ÊÊÊÊcommands that write their output to stderr instead of stdout.  This is
ÊÊÊÊonly significant in the context of the MacsBug screen.  When the MacsBug
ÊÊÊÊscreen is on (MB on) all output goes into the history area.  Output to
ÊÊÊÊstderr is written in red.  By convention this should be used for error
ÊÊÊÊreporting only.
Ê
end

###################################################################################
# Note, you will not see the commands defined here with "HELP user-defined". Look #
# for them with "HELP macsbug" along with all other MacsBug commands.             #
###################################################################################
#
# ES
#
define ES
    set confirm off
    quit
end
document ES
ES -- exit to shell (unconditionally quit gdb).
end

###################################################################################
###################################################################################

load-plugin /usr/libexec/gdb/plugins/MacsBug/MacsBug_plugin