About MacsBug 6.6

10/22/99

Installation Instructions
A-Traps
Breakpoints
Command Line
Contextual Menus
Disassembly
Expressions
Heap Commands
Log Command
Macros
MacBugApp
Memory Commands
Menu Bar
Miscellaneous
Multitasking
Show Command
Stat Command
Symbol Lookup
TaskLevel
Watch Points 3.0
Dcmds

Download From TFBBS/Headgap - MacsBug 6.6.sit

INSTALLATION INSTRUCTIONS

• MacsBug includes a number of folders. The contents of each is as follows:

“into System Folder” - This contains MacsBug itself. To install, place the “MacsBug” file
into your System folder and restart your machine.

“into MacsBug Preferences folder” - This contains optional debugger commands (“dcmds”).
There are currently two dcmds in this folder; Leaks and PageFaults. Leaks is no longer
included within MacsBug because it patches a number of Memory Manager traps with 68K code,
potentially slowing down the system. PageFaults isn’t installed because it patches the
virtual memory system, also potentially slowing down some operations. To install either
dcmd, copy the appropriate file into your “MacsBug Preferences” folder, which is located
in your “Preferences” folder.

“into Debugger Prefs file” - This contains the standard U.S. 'KCHR' keyboard translation
resource. It is needed when using MacsBug to debug on a system that is using a non-U.S.
keyboard layout (MacsBug requires U.S. keyboard translation). To install, copy the
'KCHR' resource from this file into your “Debugger Prefs” file using ResEdit, or rename
the file to “Debugger Prefs”. The file must be located in the System Folder.

“Building dcmds” - This contains sample C and Pascal source for a variety of dcmds, as
well as all headers and libraries necessary to build dcmds within the MPW and Metrowerks
CodeWarrior environments.

• The set of dcmds that was previously distributed in the optional file “PowerPC dmcds” has
been merged into MacsBug itself. When installing MacsBug, you should make sure to
remove this file from your “MacsBug Preferences” folder.

• When MacsBug is first entered, it displays a message if it has encountered dcmds that have
the same name. If you see this message, you should examine all of your preference files and
remove any duplicates. MacsBug does not guarantee which dcmd is used when a name
collision occurs, so you may be accidentally using an old dcmd.


A-TRAPS

• Fixed a problem with ATC (A-Trap Clear) command where you could clear all of your A-Traps by
accident. If you specified a trap or trap range that didn't coincide with any set ranges, we'd
silently clear all breaks. We now don't clear any ranges, and warn when you specify an invalid
trap or range.


BREAKPOINTS

• When you set a breakpoint in PowerPC code, MacsBug doesn't know to set a PowerPC
breakpoint unless you use the BRP (BReakpoint PowerPC) command. If you accidentally use the
BR (BReakpoint) command, MacsBug trusts you and places a 68K breakpoint at the requested
address. If this code is executed, it will most likely result in an illegal PowerPC instruction. If
this happens, MacsBug will display the message:

NOTE: It looks like you set a 68K breakpoint (BR) in PowerPC code.
See ?BR and ?BRP. You can probably clear the breakpoint (BRC) and go on.


COMMAND LINE

• Command-quote (' or ") puts double quotes around the word you're typing. For example, if
you're typing “FRAGS "Navigation Real"” you can type Command-quote just before the blank,
and keep typing.

• Added Control-U, which behaves just like like Control-X (clear the entire command line);
Control-D does a forward-delete; Control-A moves the cursor to the beginning of the line;
Control-E moves the cursor to the end of line.

• If an entered command line causes a syntax error, we now show the fully-expanded command
line in case there were macros involved.

• The insertion cursor now blinks based on PowerPC timebase timing, so it should be more
accurate.

• The command line history size has been increased from 150 bytes to 1K (this is the Command-V/
Command-B history).


CONTEXTUAL MENUS

• This is a new feature in MacsBug. Contextual menus are available in three general locations; the
history area, the stack/registers area, and the command line.

History Area - This area has two modes of operation. If you hold down the control key when
clicking, a pop-up menu will be displayed that has items relevant to the type of data clicked.
If you select an item, the command will be executed using the highlighted data as the input
expression. If you click in the history area without the control key down, a highlight area will
track live as you drag. If the mouse is released, the selected text will be inserted into the
command line. If you click in white space between two 16-bit hex values, they will be entered
as one long word.

Stack/registers Area - Here you can click on a number of items to get more information.

- 68K and PowerPC registers
- CurApName
- Interrupt Level
- Virtual/Real memory status

Command Line - Clicking here shows a pop-up menu that allows you to browse and re-execute
old command lines (the items shown are the same as those from the Command-V/Command-B
history).


DISASSEMBLY

• If you accidentally use one of the PowerPC commands that allows an implied PC such as ILP,
IRP, IDP, etc., but the current PC is 68K, we now use the 68K PC, rather than a random address.

• The PowerPC instructions “blr” and “bctr” will no longer show “Will branch” when
disassembled at the current PC.


EXPRESSIONS

• We now allow registers from other ISAs in break conditions. This means you can type things
like:

TVB Gestalt r3='nin '

when the PC is in 68K code.


HEAP COMMANDS

• “HC ALL” (Heap Check) now reports System heap and Process Manager extra space. This extra
space is the amount of free space between the highest non-free block in the System heap and the
lowest non-free block in the Process Manager heap.

• “HD” (Heap Dump) and “HT” (Heap Total) now show values in K or M, in addition to byte
counts.

• “HD” (Heap Dump) shows the names of code fragments if they are contained in any heap blocks
shown.

• All heap commands now properly support debugging versions of the Modern Memory Manager.


LOG COMMAND

• “LOG” inside an EVERYTIME or FIRSTTIME macro no longer waits for a key press.

• “LOG -h” tells you the current log status when it's done (which is, the log is still open).


MACROS

• Macro expansion has been fixed so that macro text longer then 127 characters works.


MACSBUGAPP

• If you terminate MacsBugApp abnormally, such as when you “ES” (Exit to Shell) from the real
MacsBug, we now clean up properly by patching ExitToShell.

• MacsBugApp does fewer MacsBug-like things, such as occasionally disabling interrupts. This
should make it more reliable.


MEMORY COMMANDS

• When displaying an IOTRAPWORD basic type, we now special case selectors $51 (PBReadFork) and
$52 (PBWriteFork) to look up HFSPlusDispatch ($A0A8).

• The IOREFNUM basic type understands HFS Plus iterators.

• “SB” (Set Byte), “SW” (Set Word), and “SM” (Set Memory) can now be used on addresses that lie
within file mapped files.

• Added the “FINDMASK” command. This allows you to search through a range of memory for data
that, when ANDed with the specified masks, matches the specified values.

• Removed the “FP” (Find Pointer) command. This was useful in the days of 24-bit memory
addressing, but it's obsolete today.

• “F” (Find), “FB” (Find Byte), “FW” (Find Word), and “FL” (Find Long) are two to three times
faster and provide a progress bar. Searches can be cancelled by typing Command-'.' (period).

• Enumeration macros can use decimal now. Previously the enum macro value had to be hex.

• Fixed the display of the RGNHANDLE basic type so that it doesn't abort when the handle seems
correct but the dereferenced handle causes a bus error.

• Add “DS” (Display memory Strings) command. This searches through memory and displays the
first string of characters that match a given criteria. A valid string has all characters in the ASCII
range #32..#127, and has a minimum specified length, which defaults to five characters.

The following example finds all strings in the current application heap that are at least 20
characters long.

DS InApp #20


MENU BAR

• This is a new experimental feature in MacsBug. It is off by default, but can be dynamically
enabled with the “SET MENUBAR” command. To enable the menu bar by default, copy the ‘mxpr’
and ‘TMPL’ resources from MacsBug into your “Debugger Prefs” file, then edit the ‘mxpr’, and set
the “Show MacsBug menu bar” bit.


MISCELLANEOUS

• When appropriate, MacsBug now uses the File System Manager FCB accessor functions to get
information on open files, rather than accessing the FCB table directly. This is for compatibility
with Mac OS 9.

• If you crash a PowerPC application and then “ES” (Exit to Shell), MacsBug now sets the low
memory location DSErrCode to a reasonable non-zero value. The Process Manager captures
DSErrCode and sends it to the parent process in the child-died event, so you'll now see the
message, “The application <blah> has unexpectedly quit...” just like you do with 68K applications.

• Entering MacsBug no longer causes the Macintosh to lose the network connection when booted
from a NetBoot server.

• The mouse is properly refreshed when MacsBug is entered, the “Don't swap display bit depth”
danger bit is set, and the display bit depth has been changed.

• MacsBug calls the G4 processor “7400 (G4)”.

• Text is now highlighted in various colors to show errors, warnings, etc.

• Added a ‘vend’ resource with the MacsBug updates URL. This is displayed by Conflict Catcher 8,
for example.

• “SET UNMANGLE” re-displays the PC window in case your PC is inside a C++ routine when you
change the unmangle setting.

• Removed the “EA” (Exit to Application) command. Use “ES” (Exit to Shell) instead.

• MacsBug now has a 40K stack (bloated for now). This works around some problems where the
stack would overflow on some machines.

• Symbol lookups will no longer deadlock the machine if done while the file system is busy, and
VM is on (but it's not VMs fault). This bug was introduced in MacsBug 6.5.4a7c1.


MULTITASKING

• MacsBug now supports basic debugging of MPTasks. It requires a 2.0 or later version of the
MPLibrary. You can debug one task at a time, including stepping, tracing, breakpoints, and TVector
breaks.


SHOW COMMAND

• Extra Return presses after “SHOW <foo>” cycle through the different display modes like “SHOW”
already did without parameters.


STAT COMMAND

• “STAT -i” shows interesting internal MacsBug statistics such as memory use, stack use, and
dcmd size.

• Added subliminal VM related message to the “STAT” command since VM does not suck.


SYMBOL LOOKUP

• “WH” (WHere) can now say the address is “in the <foo> dcmd inside MacsBug”.


TASKLEVEL

• “TASKLEVEL” is now more reliable. The test for Secondary Interrupt time would sometimes give
false positive results (the bit would be set when a secondary interrupt task was installed, and
immediately run at non-interrupt time). We would also report that VBLs were active just because
a page fault was in progress.

An easy way to use TaskLevel is with the “TL” macro.

BR NewHandle TL!=0

breaks on NewHandle when TaskLevel is not equal to zero.


WATCH POINTS 3.0

• Completely rewritten, once again. This version is compatible with Mac OS 8.6 and 9.0, and
supports the PowerPC Velocity Engine (AltiVec™) instructions.

• Due to a bug in the 68K Emulator, MacsBug requires Emulator Update Extension 2.0 (included
with MacsBug 6.6) to have patched the Emulator. This means you can't presently do Watch Points
until INIT time. MacsBug will let you know if the current Emulator doesn't have the bug fixed.
This bug is fixed on NewWorld-architecture (ROM-in-RAM) machines running Mac OS 9.

• You can't watch locations on the stack. If you do, you'll eventually bus error with the stack
pointer off in hyperspace. We understand this, but don't yet have a deliverable fix (it's not
MacsBug).

• You can't watch a location that is within a page that someone will be using atomic operations to
(lwarx/stwcx). If you do, the reservation will always be lost, and the atomic operation will loop
forever. If the machine seems to lock up, and you NMI in at the previous instruction is a “stwcx.”,
you need to clear the Watch Point to make forward progress. This is due to a NanoKernel feature.
It's not clear if this can be fixed without completely replacing the NanoKernel.

• If you try to set a watch point in I/O space or ROM, we now display a useful error message
instead of pretending that the watch point has actually been set.

• Made “WP” with no parameters work right when there is a watch point set (it shows the currently
set watch point).

• Fixed a case where we'd hit a protected page, but our exception handler wouldn't see the hit.

• Break expressions now work.


DCMDS, PREDEFINED MACROS, AND DCMD SUPPORT

• When checking for duplicate dcmds, we now show if any dcmd names collide with built-in
command names.

• Added a “Startup Actions” preference file. The version that ships with MacsBug contains a
FIRSTTIME macro that turns on the “EBBE” (Even Better Bus Error) dcmd. In general, you
shouldn't install this unless you're actively looking for write-to-nil/read-from-nil bugs.

• Added a bunch of new macros:

AEWH, AEWHS, AEBRK - AppleEvent stuff
APIB, APIC - API Break (set breaks with both ATB and TVB), API Clear (clear both ATB and TVB)
FIEL -> FILE - For poor spellars
“Files”, “Driver” and “Drivers” - Simple aliases to “File” and “Drvr” dcmds
Threads - Simple alias to the “Scream” dcmd
WNEA, WNEP, WNEPA, WNEFNDR, WNEF - Break at next WaitNextEvent call

• Replaced the “-b” option to the Drvr dcmd in ShowLog with “-v”, show parameter block at
qHead if the driver is busy, added Drive, “vol”, “dm sp 80”, and Process Manager heap totals.

• Add IOPosMode enum, which is used in HFS/HFS Plus parameter blocks.

• Changed various ParamBlockRec templates to use the VRefNum type.

• Added UTVolCacheReadIP, UTVolCacheWriteIP, UTResolveFileRefNum, UTCheckFCB,
UTCheckForkPermissions, UTAddFCBToSearchList, UTRemoveFCBFromSearchList,
UTLocateFCBInSearchList, UTGetForkControlBlockSize, PBGetXCatInfoSync/Async, HFS
Plus API stuff for the HFSPlusDispatch (A0A8) trap, IPCKillListPorts, GetDimSuspendState,
SetDimSuspendState, and ServerDispatch

• HighLevelFSDispatch (AA52) and AliasDispatch (A823) had the wrong selector sizes.


• Aevt - 1.1

This is a new dcmd that displays the contents of an AppleEvent record.

• ATVB - Removed. Use TVB instead.

• Cache - 3.0

Use File System Manager FCB accessors for Mac OS 9 compatibility.

• DRD - 3.0

We now try to show the routine name and address, so you don't have to manually dereference the
ProcPtr value if it points to PowerPC code.

• Drive - 2.0.1

Added 'W' flag for drive is non-ejectable but wants eject call.

• Drvr - 3.1

Added “-v” (verbose) option.

• EBBE - 2.1

Changed from kEbbeValue (0x50FF8001) to kBlessedBusErrorBait (0x68F168F1). This new
value will be guaranteed to be in the middle of a 64K unmapped range on Mac OS 8 and 9.

Added “-v” (set EBBE value) option.

• Error - 3.2

Changed hMenuFindErr to fsDSIntErr.

Fixed typo in opWrErr.

• File - 4.0

Pretty much a complete rewrite. It now handles multiple command line options correctly, so you
can use things like:

FILE -p 2001 -t 'TEXT'

to show files opened by process 2001 that are of type text.

Use File System Manager FCB accessors for Mac OS 9 compatibility.

“FILE fRefNum” now dumpes the FCBRec, ForkControlBlock, or IteratorControlBlock
(whichever is appropriate) unless the “-s” option is used. This supports Mac OS 9's HFS Plus
APIs.

Added code to display sizes 4 GB or larger.

Add “-s” option to replicate old, minimal display of the specified file.

• Frags - 1.1

By default, check for lib-name-contains-string instead of equals-string. If you want to check for an
exact match, use the new option “-x”.

Add “-i” to show a fragment’s import libraries.

Display all context, closure and connection IDs in hex.

• Gestalt - 3.2

No changes other than the version.

• Leaks - 6.6.1

Fixed bus-error handling to restore the SR (re-enter User mode) after catching a bus error when
stack crawling.

“LEAKS DUMP” displays the depth of the internal tree.

Display “[end of Leaks display]” at the end of a dump, so you don't have to wonder if it's
done yet (watching for the blinking insertion point is a mediocre workaround).

Leaks can now track 2,000 blocks.

• PageFaults. - 1.0

Use File System Manager FCB accessors for Mac OS 9 compatibility.

• PP - 2.0

No changes other than the version.

• RD - 3.0.3

Use File System Manager FCB accessors for Mac OS 9 compatibility.

• Scream - 2.1

Added display of thread entry pointer, creation flags, termination proc/data, pointer to thread app
globals and pointer to thread record sturcture.

• ShowPath - 1.0

This is a new dcmd that displays a full path to a specified file or directory. This dcmd, like the Log
command, is best used at TaskLevel 0.

• StopAS - 3.0

No changes other than the version.

• Thing

Made the tRefNum functionality actually work. The dcmd now displays only the component
matching the given tRef number if your parameter is an unquoted number.

• UserFns - 1.0

Display interrupt level correctly (including Time Mgr tasks).

• VMDump - 3.0

Use File System Manager FCB accessors for Mac OS 9 compatibility.

• Vol - 3.0.2

Updated for HFS Plus volumes to show real number of blocks and real block size. Enlarged a few
field sizes so larger values can be shown. Some fields are still truncated to 6 hex digits, but that is
enough for any normal volume (we do not expect to see volumes with a block size, file count, or
directory count 16M or greater for a while).

• WhatIs - 1.0

This is a new dcmd that explains what a given PowerPC mnemonic means.


© 1999 Apple Computer, Inc. All rights reserved.

Apple, the Apple logo, Apple IIGS, Macintosh, MPW, Power Macintosh, and PowerBook are trademarks of Apple Computer, Inc., registered in the United States and other countries. PowerPC is a trademark of International Business Machines Corporation, used under license therefrom. AltiVec is a trademark of Motorola, Inc.

Download From TFBBS/Headgap - MacsBug 6.6.sit