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