################################################################################# # # # 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