Jump to content

MacsBug Reference and Debugging Guide: Difference between revisions

From RetroTechCollection
← Older edit

Josh (talk | contribs)

8 user groups
17,759 edits
undo
VisualWikitext
P4 verification: real documentation page - contents, what each document settles, and honest classification (The Laser Writer Family 1992 is a third-party Business One Irwin book, not an Apple document)
Update links to Programmer's Guide to MPW Volume I 1991 after page move
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
The '''''MacsBug Reference and Debugging Guide''''' is '''Apple Computer, Inc.'s''' developer manual for '''MacsBug 6.2''', published by '''Apple Developer Press, 1995''' (© 1994, 1990 Apple Computer, Inc.). '''410 pages''', with full bookmarks and a text layer.
The '''''MacsBug Reference and Debugging Guide''''' is Apple Computer, Inc.'s manual for MacsBug 6.2, Apple's low-level assembly-language debugger for 68000-family Macintosh computers. It was published by Apple's Developer Press in 1995 (© 1994, 1990 Apple Computer, Inc.). The text, glossary and index are numbered to p. 385; the PDF has 410 pages, bookmarks and a text layer.<ref name="mb">Apple Computer, ''MacsBug Reference and Debugging Guide, for MacsBug 6.2'', Developer Press, 1995. Title and copyright pages (PDF pp. 1-2), contents pp. iii-xiii, Appendix C pp. 337-358, index pp. 379-385.</ref>
 
MacsBug is Apple's low-level assembly-language debugger for the 68 K Macintosh — the tool that catches a machine at the moment it crashes, below the level any application-level debugger reaches.


== Contents ==
== Contents ==
* Preface: About This Manual (p. xxi)
* Preface: About This Manual (xxi)
* '''1. MacsBug and Low-Level Debugging''' (p. 1) — error handling on the Macintosh, why low-level debugging, new features in 6.2
* 1 MacsBug and Low-Level Debugging (1)
* '''2. Getting Started''' (p. 9) — installing MacsBug, '''installing under A/UX''', displaying MacsBug on a different monitor (System 3.2–6.x and System 7.0 differ), the Debugger Prefs file, the MacsBug display regions (command line, PC, output, status/stack/register), '''invoking MacsBug''' — the programmer's switch, an 'FKEY' resource, or <code>DebugStr</code> from source
* 2 Getting Started (9): installing MacsBug, including under A/UX; the MacsBug display; invoking MacsBug with the programmer's switch, an 'FKEY' resource or DebugStr; the Debugger Prefs file
* '''3. An Assembly-Language Primer''' (p. 33) — 68 K instruction syntax and every addressing mode
* 3 An Assembly-Language Primer (33): 68000 instruction syntax and addressing modes, reading MacsBug's disassembly
* '''4. Macintosh Memory Organization''' (p. 65) — the memory map and its regions, '''using low-memory globals to draw a memory map''', memory management under System 7, 32-bit addressing, virtual memory, registers, templates, the heap and heap blocks, and '''detecting a corrupted heap'''
* 4 Macintosh Memory Organization (65): the memory map, low-memory globals, memory management under System 7 (32-bit addressing, virtual memory), the heap, the stack, the jump table
* '''5–6''' — the stack and A-traps, '''Macintosh interrupts''' and code that runs at interrupt time, VBL tasks, the A-trap action table, the file system (drive queue, file control blocks, file I/O queue)
* 5 The Macintosh Operating System (119): exceptions, A-traps, patches and glue, interrupts, the Macintosh managers
* '''7. Debugging Strategies''' (p. 163) — before the crash and after it; the named failure modes "The Deep Freeze", "The Restart Surprise", "Nasty Pointers", "No Room to Maneuver"
* 6 Discipline (155): Apple's tool for checking Toolbox calls
* '''8''' — macros, <code>'mxbm'</code> resources, dcmds and how to build one
* 7 Debugging Strategies (163): before the crash, after the crash, and common problems ("The Deep Freeze", "The Restart Surprise", "Nasty Pointers", "No Room to Maneuver", "Mind-Reading Problems")
* '''9. MacsBug Commands''' (p. 207) — the full command reference, alphabetically from ATB
* 8 Introduction to MacsBug Commands (181): the command line, macros, dcmds
* 9 MacsBug Commands (207): every command, alphabetically
* Appendices: A Command Summary (325); B Error Messages (333); C Macintosh Error Codes (337); D and E on procedure definitions and how MacsBug installs itself; Glossary; Index (379)
<ref name="mb" />


== What it is good for on this wiki ==
== Sad Mac and system error codes ==
'''A Macintosh that crashes reproducibly at a known address is diagnosable with this book and a keyboard, without opening the case.''' Chapter 7 is the part worth reading: it separates a software crash from a hardware fault by what the machine does at the moment of failure, which is exactly the question a repairer needs answered before desoldering anything.
Appendix C is Apple's own list of Macintosh error codes. It starts with the "Sad Macintosh" codes that the ROM displays when it finds a hardware failure during start-up, in two tables:<ref name="mb" />
* Table C-1 (pp. 337-338) covers the Macintosh Plus, 128K, 512K and 512KE, whose codes are six hexadecimal digits: 01xxxx ROM test failed, 02xxxx to 05xxxx RAM test failures (Apple's labels are "bug subtest", "byte write", "mod3 test" and "add uniqueness"), 0F00xx processor exceptions, and 0F0064 "Couldn't read system file".
* Table C-2 (pp. 338-340) covers all other Macintosh computers, whose codes are two eight-digit hexadecimal numbers. The low word of the first number identifies the test: 0001 ROM, 0002 to 0005 RAM, 0006 VIA1, 0007 VIA2, 0008 ADB, 0009 MMU, 000A NuBus, 000B SCSI chip, 000C IWM, 000D SCC, 000E data bus test, and 000F exceptions, with the exception type in the second number.
The appendix goes on to the System Error Handler (bomb box) alert numbers and the operating system error codes, grouped by manager.<ref name="mb" /> The wiki's own decoding of these codes, machine by machine, is at [[Sad Mac Error Codes]].


Chapter 4's memory map and low-memory globals are also the reference behind the address interpretation used in [[Sad Mac Error Codes]] — though the Sad Mac codes themselves come from the ROM, not from MacsBug.
== What the manual does not contain ==
 
It is a software manual. Apart from the start-up test codes, it has no hardware information: no schematics, part numbers, component values or voltages.
== What it does not contain ==
'''No hardware information of any kind.''' No schematic, no part number, no component value, no voltage, no connector pinout. It is a software debugger manual. Do not cite it for a hardware figure.


== Related pages ==
== Related pages ==
* [[Sad Mac Error Codes]] · [[Sad Mac Decoder]] · [[Diagnostic Serial Console]]
* [[Sad Mac Error Codes]]
* [[Diagnostic Serial Console]]
* [[Programmer's Guide to MPW Volume I 1991]]
* [[Programming For System 7 1991]]
* [[:Category:Apple Programming Documentation]]
* [[:Category:Apple Programming Documentation]]


<pdf> File:MacsBug Reference and Debugging Guide.pdf </pdf>
<pdf> File:MacsBug Reference and Debugging Guide.pdf </pdf>


Download the MacsBug Reference and Debugging Guide here: [[:File:MacsBug Reference and Debugging Guide.pdf|MacsBug Reference and Debugging Guide.pdf]] (1.5 MB)
Download: [[:File:MacsBug Reference and Debugging Guide.pdf|MacsBug Reference and Debugging Guide.pdf]] (1.5 MB)
 
== References ==
<references />


[[Category:Apple Documentation]]
[[Category:Apple Documentation]]

Latest revision as of 19:27, 1 October 2026

The MacsBug Reference and Debugging Guide is Apple Computer, Inc.'s manual for MacsBug 6.2, Apple's low-level assembly-language debugger for 68000-family Macintosh computers. It was published by Apple's Developer Press in 1995 (© 1994, 1990 Apple Computer, Inc.). The text, glossary and index are numbered to p. 385; the PDF has 410 pages, bookmarks and a text layer.[1]

Contents

[edit | edit source]
  • Preface: About This Manual (xxi)
  • 1 MacsBug and Low-Level Debugging (1)
  • 2 Getting Started (9): installing MacsBug, including under A/UX; the MacsBug display; invoking MacsBug with the programmer's switch, an 'FKEY' resource or DebugStr; the Debugger Prefs file
  • 3 An Assembly-Language Primer (33): 68000 instruction syntax and addressing modes, reading MacsBug's disassembly
  • 4 Macintosh Memory Organization (65): the memory map, low-memory globals, memory management under System 7 (32-bit addressing, virtual memory), the heap, the stack, the jump table
  • 5 The Macintosh Operating System (119): exceptions, A-traps, patches and glue, interrupts, the Macintosh managers
  • 6 Discipline (155): Apple's tool for checking Toolbox calls
  • 7 Debugging Strategies (163): before the crash, after the crash, and common problems ("The Deep Freeze", "The Restart Surprise", "Nasty Pointers", "No Room to Maneuver", "Mind-Reading Problems")
  • 8 Introduction to MacsBug Commands (181): the command line, macros, dcmds
  • 9 MacsBug Commands (207): every command, alphabetically
  • Appendices: A Command Summary (325); B Error Messages (333); C Macintosh Error Codes (337); D and E on procedure definitions and how MacsBug installs itself; Glossary; Index (379)

[1]

Sad Mac and system error codes

[edit | edit source]

Appendix C is Apple's own list of Macintosh error codes. It starts with the "Sad Macintosh" codes that the ROM displays when it finds a hardware failure during start-up, in two tables:[1]

  • Table C-1 (pp. 337-338) covers the Macintosh Plus, 128K, 512K and 512KE, whose codes are six hexadecimal digits: 01xxxx ROM test failed, 02xxxx to 05xxxx RAM test failures (Apple's labels are "bug subtest", "byte write", "mod3 test" and "add uniqueness"), 0F00xx processor exceptions, and 0F0064 "Couldn't read system file".
  • Table C-2 (pp. 338-340) covers all other Macintosh computers, whose codes are two eight-digit hexadecimal numbers. The low word of the first number identifies the test: 0001 ROM, 0002 to 0005 RAM, 0006 VIA1, 0007 VIA2, 0008 ADB, 0009 MMU, 000A NuBus, 000B SCSI chip, 000C IWM, 000D SCC, 000E data bus test, and 000F exceptions, with the exception type in the second number.

The appendix goes on to the System Error Handler (bomb box) alert numbers and the operating system error codes, grouped by manager.[1] The wiki's own decoding of these codes, machine by machine, is at Sad Mac Error Codes.

What the manual does not contain

[edit | edit source]

It is a software manual. Apart from the start-up test codes, it has no hardware information: no schematics, part numbers, component values or voltages.

[edit | edit source]

Download: MacsBug Reference and Debugging Guide.pdf (1.5 MB)

References

[edit | edit source]
  1. ↑ 1.0 1.1 1.2 1.3 Apple Computer, MacsBug Reference and Debugging Guide, for MacsBug 6.2, Developer Press, 1995. Title and copyright pages (PDF pp. 1-2), contents pp. iii-xiii, Appendix C pp. 337-358, index pp. 379-385.
Retrieved from "https://wiki.retrotechcollection.com/index.php?title=MacsBug_Reference_and_Debugging_Guide&oldid=20627"