bobp@amiga.UUCP (Robert S. Pariseau) (10/28/85)
This is a copy of a message I posted on BIX a little while back. ----------- It's been said that the Amiga is a hacker's machine. I surely wouldn't dispute that -- that's why we're going public with all (and I mean ALL) of the technical info so early. Hacking, of course, starts with total control. In aid of that I'd like to pass on a few hints on how to bend your Amiga to your will. 1) Getting into the CLI: That window you see with copyright message in it when you boot the machine is, in fact, a CLI window. What makes it go away is the last line of the startup script (the file Startup-Sequence in the directory "s"), to wit "endcli > nil:", which executes an endcli command and redirects its good-bye message to the bit-bucket device. Knock that line out of the script and you'll always have an instant CLI window when you start -- the initial Workbench screen will be underneath it. But for those of you who only want an instant CLI window SOME of the time, there's an easier way. Wait until the script has started doing the LoadWB command (which fires up the Workbench control program out of the firmware) and type a CTRL-D! The CTRL-D tells the CLI script processor to give up before starting the next command -- it will NOT interfere with the LoadWB. If you still have the standard startup script just type your CTRL-D right after the message about using Preferences to set the date and time is printed out. 2) Introducing WACK: The native Amiga debugger is called WACK (acronyms invited!). WACK is a multitasking debugger that runs in a window and allows you to debug other programs in the machine. Those of you with developer's kits have a preliminary version of WACK already in hand along with some equally preliminary documentation. Real WACK should be available in stores in November. 3) Introducing ROM WACK: Whether or not you have WACK, every Amiga comes with ROM WACK, a subset of WACK stashed in the Kickstart software (Note: We've developed the bad habit around here of using the term ROM when we really mean Kickstart software kept in the Writeable Control Store -- ROM is shorter). ROM WACK talks out the serial port at 9600 baud. 4) Exec Debug(): The Exec library includes a Debug() entry point that you can call in your program when you want to transfer control to the system debugger -- kind of a compiled-in breakpoint. Like every other library entry point in the system, Debug() is accessed through an address kept in a table in RAM. That means we can change system debuggers at will! By default, you get ROM WACK. While WACK itself is running, it installs its entry address in the Debug() vector. 5) ROMWack: Those of you with developer's kits have a program called ROMWack. This program just calls Debug(). Run ROMWack when you want to dump yourself into the debugger. If you don't already have one, create your own ROMWack -- it's useful! By the way, this approach to debugging only works due to the multitasking nature of the machine -- keep a CLI free and you'll always be able to run the ROMWack program even if whatever you are debugging becomes uncooperative. 6) Magic LoadWB switch: If you are debugging programs under the workbench, get into your startup script and replace the LoadWB command with the line "LoadWB -debug". This will cause a magic new menu strip to appear in the workbench menus just to the right of "Special". It doesn't have a title, but it's there! The first item in that menu will cause workbench to call Debug(). 7) Exiting ROM WACK: To return control to your program just after the call to Debug(), merely type a CTRL-D to ROM WACK. Remember that you must do this at 9600 baud on the serial port -- use an ASCII terminal or your favorite terminal program on another machine (Amiga terminal programs will be discussed some other time). 8) WACK commands: Type "?" to get a list of what WACK or ROM WACK understands. Command names can be abbreviated. Don't expect too much of ROM WACK, it's really a very minimal monitor. I won't go into more detail on commands here -- that would turn this into a manual and, after all, we're talking HACKING here! 9) Program traps: Software failures come in two kinds -- your code and ours. Frankly many of the failures we report as ours are really do to yours trampling over our data tables. In any event, we report ours through Alerts. Alerts are those red on black messages with the flashing red border that appear at the top of your screen. If you haven't seen one yet you've got a treat coming -- we've had near heart attacks reported at their appearance. The "guru meditation" numbers reported in the alert may give you some clue as to what's screwed up. Developers should look in the include file Alerts.i (or Alerts.h if you only read C). For debugging purposes, the key thing to remember about Alerts is that the nastiest kind, so called "Dead-end" alerts, are actually displayed AFTER the machine is reset. This is done to GUARANTEE that the machine is together enough to display the alert regardless of what's gotten screwed up by the failure. Needless to say, this means that the machine state is not very useful for debugging. But never fear! The system tells you it is about to reset itself by blinking the power light (at about half the speed it blinks during the reset time diagnostics). If while this light is blinking you type a DEL character on the SERIAL port (again at 9600 baud), you will find yourself dumped into ROM WACK with the pre-alert state preserved! Most well behaved program failures in YOUR code will present themselves as a 68000 exception (e.g., illegal instruction). If you or your WACK have not taken other action, AmigaDOS will catch the trap and display a system requester telling you that your task is "held". This is done because requesters block only one task, whereas alerts disable tasking altogether -- very nasty if you are currently writing to the disk in some other task! Wait for the disk lights to go out and then you may safely select the Cancel gadget. When you do that an alert will appear. The first part of the guru numbers is your 68000 exception code (e.g., 3=illegal address). The alert will tell you to click on the left mouse button to continue. If you do that, the machine will reset -- very dull. What the alert doesn't tell you is that, in this very special case of program traps, if you click on the right button you will be dumped into ROM WACK (on the serial...you get the idea) WITH THE STATE AT THE TIME OF THE EXCEPTION PRESERVED! ------- That's all for now. Happy Hacking!
bobp@amiga.UUCP (11/02/85)
From: amiga!bobp@caip.rutgers.edu (Robert S. Pariseau) This is a copy of a message I posted on BIX a little while back. ----------- It's been said that the Amiga is a hacker's machine. I surely wouldn't dispute that -- that's why we're going public with all (and I mean ALL) of the technical info so early. Hacking, of course, starts with total control. In aid of that I'd like to pass on a few hints on how to bend your Amiga to your will. 1) Getting into the CLI: That window you see with copyright message in it when you boot the machine is, in fact, a CLI window. What makes it go away is the last line of the startup script (the file Startup-Sequence in the directory "s"), to wit "endcli > nil:", which executes an endcli command and redirects its good-bye message to the bit-bucket device. Knock that line out of the script and you'll always have an instant CLI window when you start -- the initial Workbench screen will be underneath it. But for those of you who only want an instant CLI window SOME of the time, there's an easier way. Wait until the script has started doing the LoadWB command (which fires up the Workbench control program out of the firmware) and type a CTRL-D! The CTRL-D tells the CLI script processor to give up before starting the next command -- it will NOT interfere with the LoadWB. If you still have the standard startup script just type your CTRL-D right after the message about using Preferences to set the date and time is printed out. 2) Introducing WACK: The native Amiga debugger is called WACK (acronyms invited!). WACK is a multitasking debugger that runs in a window and allows you to debug other programs in the machine. Those of you with developer's kits have a preliminary version of WACK already in hand along with some equally preliminary documentation. Real WACK should be available in stores in November. 3) Introducing ROM WACK: Whether or not you have WACK, every Amiga comes with ROM WACK, a subset of WACK stashed in the Kickstart software (Note: We've developed the bad habit around here of using the term ROM when we really mean Kickstart software kept in the Writeable Control Store -- ROM is shorter). ROM WACK talks out the serial port at 9600 baud. 4) Exec Debug(): The Exec library includes a Debug() entry point that you can call in your program when you want to transfer control to the system debugger -- kind of a compiled-in breakpoint. Like every other library entry point in the system, Debug() is accessed through an address kept in a table in RAM. That means we can change system debuggers at will! By default, you get ROM WACK. While WACK itself is running, it installs its entry address in the Debug() vector. 5) ROMWack: Those of you with developer's kits have a program called ROMWack. This program just calls Debug(). Run ROMWack when you want to dump yourself into the debugger. If you don't already have one, create your own ROMWack -- it's useful! By the way, this approach to debugging only works due to the multitasking nature of the machine -- keep a CLI free and you'll always be able to run the ROMWack program even if whatever you are debugging becomes uncooperative. 6) Magic LoadWB switch: If you are debugging programs under the workbench, get into your startup script and replace the LoadWB command with the line "LoadWB -debug". This will cause a magic new menu strip to appear in the workbench menus just to the right of "Special". It doesn't have a title, but it's there! The first item in that menu will cause workbench to call Debug(). 7) Exiting ROM WACK: To return control to your program just after the call to Debug(), merely type a CTRL-D to ROM WACK. Remember that you must do this at 9600 baud on the serial port -- use an ASCII terminal or your favorite terminal program on another machine (Amiga terminal programs will be discussed some other time). 8) WACK commands: Type "?" to get a list of what WACK or ROM WACK understands. Command names can be abbreviated. Don't expect too much of ROM WACK, it's really a very minimal monitor. I won't go into more detail on commands here -- that would turn this into a manual and, after all, we're talking HACKING here! 9) Program traps: Software failures come in two kinds -- your code and ours. Frankly many of the failures we report as ours are really do to yours trampling over our data tables. In any event, we report ours through Alerts. Alerts are those red on black messages with the flashing red border that appear at the top of your screen. If you haven't seen one yet you've got a treat coming -- we've had near heart attacks reported at their appearance. The "guru meditation" numbers reported in the alert may give you some clue as to what's screwed up. Developers should look in the include file Alerts.i (or Alerts.h if you only read C). For debugging purposes, the key thing to remember about Alerts is that the nastiest kind, so called "Dead-end" alerts, are actually displayed AFTER the machine is reset. This is done to GUARANTEE that the machine is together enough to display the alert regardless of what's gotten screwed up by the failure. Needless to say, this means that the machine state is not very useful for debugging. But never fear! The system tells you it is about to reset itself by blinking the power light (at about half the speed it blinks during the reset time diagnostics). If while this light is blinking you type a DEL character on the SERIAL port (again at 9600 baud), you will find yourself dumped into ROM WACK with the pre-alert state preserved! Most well behaved program failures in YOUR code will present themselves as a 68000 exception (e.g., illegal instruction). If you or your WACK have not taken other action, AmigaDOS will catch the trap and display a system requester telling you that your task is "held". This is done because requesters block only one task, whereas alerts disable tasking altogether -- very nasty if you are currently writing to the disk in some other task! Wait for the disk lights to go out and then you may safely select the Cancel gadget. When you do that an alert will appear. The first part of the guru numbers is your 68000 exception code (e.g., 3=illegal address). The alert will tell you to click on the left mouse button to continue. If you do that, the machine will reset -- very dull. What the alert doesn't tell you is that, in this very special case of program traps, if you click on the right button you will be dumped into ROM WACK (on the serial...you get the idea) WITH THE STATE AT THE TIME OF THE EXCEPTION PRESERVED! ------- That's all for now. Happy Hacking!