Locksmith 6.0 Automatic Boot Tracer Soft-docs --------------------------------------------- by The Ghost ------------------------------------------------------------------------------ GHOST NOTE: This is exactly from the hard docs of Locksmith 6.0, and I have done this section first for those of you that can't wait for the full docs to get started with this feature. I'm not sure whether I will be doing the complete soft docs or not. ------------------------------------------------------------------------------ Introduction to ABT ------------------- [A] BOOT TRACER The Automatic Boot Tracer is intended for use by the more experienced Apple programmer. It is actually a sophisticated debugger which can simulate the operation of the 6502 in the Apple. Because disk reading is simulated. it is possible to actually "boot" a disk (whether protected or not) under control of this debugger, and trace the boot code of the program. Boot tracing, a normally manual and very tedious technique which is used by the most sophisticated "hackers", can be performed automatically under control of the Locksmith Automatic Boot Tracer. To invoke the boot tracer, key 'A' from the main menu. You must have a RAM card of at least 16K on your system for ABT to work. If you have an Apple //e or Apple //c, the "built-in" 16K RAM will work. Locksmith ABT will prompt you for the slot numbr of the RAM card. Key in a digit from 0 to 7. The ABT will be installed on the RAM card you choose, and the ABT will be entered. Note that in this manual, the ABT (automatic boot tracer) is also referred to as the debugger and the simulator, since it actually simulates the operation of the 6502, ad can be used as a powerful debugger. The screen will clear and a line of inverse text will appear on the top line of the display. The ABT is now operating. If you press reset at any time, you will be placed in the Apple monitor and can reboot another disk by entering the slot number followed by control-P. Be careful not to reboot a disk which will automatically load over the ABT on the RAM card you selected. INFORMATION LINE The top line of the screen which appears in inverse text is a one-line status display which appears initially as follows: FA62 CLD A=00 X=00 Y=00 P=34 S=FD The first 4 characters are the program counter (FA62 in this example). The 6502 opcode at the program counter is also displayed (CLD in this example). Next, the values of the A,X,and Y registers are displayed. The "P=" value is the processor status register contents, and the "S=" value is the stack pointer. At this time, press the R key followed by a key from A through X. Notice that the information line disappeared and moved to another line of the screen. You can put the information line on any line of the screen that is convenient for the software you will be debugging / tracing. If you don't want the information line displayed, you can place it on row Y or Z (which are off the screen). IDLE MODE The simualtor is in "idle" mode at this time. That is, the program to be simulated is not currently running, but is stopped at the address displayed by the program counter. Press control-C at this time to enable the processing of 65C02 instructions. This is necessary if you are running on an Apple //c or an enhanced Apple //e. Press the S key to start execution under control of the simualtor. The ABT is now running simulated 6502 code. The simulator is now in "running" mode. Note the rapidly changing program counter. The "beep" you hear from the speaker may sound a bit different than the Apple "beep" which you are used to, but that is only because under control of the simulator it is slowed down considerably and sounds lower. To stop the program being executed, press [control-Z]. You are now again in "idle" mode. Control-Z is the default character to stop execution of the simulated program, but it can be set to a different "stop" key if you need to be able to use control-Z with the software you are tracing. To change the stop key, first stop the program being executed and return to "idle" mode by pressing control-Z. Then press control-X followed by any other key, and the other key will be used for the "stop" key. To reset the "stop" key to control-Z, enter idle mode and press control-X, control-Z. Enter idle mode. Now press the space bar and watch the information line. The space bar is used in idle mode to single step one instruction. A "+" or "-" will appear after each conditional branch instruction, depending on whether the branch will be taken ("+") or will be taken ("-"). While in idle mode, enter control-Y. You are placed in the system monitor, and can enter any monitor commands such as "L" (to disassemble 6502 code). To re-enter the simulator, press control-Y, RETURN. Before placing you in the system monitor, the simulator saved low memory pages 00 to 07 on its RAM card. After re-entering the simualtor, this memory was "refreshed", insuring that no memory was inadvertently changed while in the system monitor. To review the idle mode commands we have already learned: Space-bar single steps one instruction. It can also be used to "single-cycle" (see below). "R" moves the information line to rows A through X. "S" starts the simulated program running and enters "running" mode. Control-Y enters the system monitor. To re-enter the simulator, press control-Y again, followed by the Return key. Control-X is used to change the program "stop" key, which stops the program and enters idle mode. Other idle mode commands: "T" (trace subroutine) executes the simulator program until a JSR or RTS instruction is fetched. Control-R causes a "simulated" reset to occur. The program counter is fetched from $FFFC. Control-I causes a "simulated" IRQ interrupt. Control-F turns off the "simulated" IRQ pending flag. Control-N causes a "simulated" NMI interrupt. Control-Q quits the simualtor and returns to the system monitor. Control-RESET also exits the simualtor. "1" is used to get single-cycle mode. In single-cycle mode, the space bar cycles one 6502 processor cycle at a time, instead of an entire instruction step. "0" is used to set instruction-step mode. It is valid only when on an instruction boundary (not on a cycle in the middle of an instruction). "D" turns the "beep" flag on and off. The beep is sounded when idle mode is entered. "C" turns the "click" flag on and off. The click is sounded for every keystroke when not in "running" mode. Control-C turns the 65C02 flag on and off. The default value for this switch is "off". If 65C02 instructions are to be simualted, this flag must be on. The Apple //e (enhanced version) and Apple //c both contain 65C02 processors in their resident ROM code. Note that the simulator itself does not use 65C02 instructions. You can therefore run 65C02 instructions on a normal 6502 processor. "K" will take the next key pressed and place it in the keyboard character register. When instruction stepping through code that reads the keyboard, this key allows a convenient way to enter a keystroke to the program being traced, without entering the keystroke in "running" mode. "ESC" is used to enter the simulator control menu. The simualtor control menu is used to display and change internal simulator control information. SIMULATOR CONTROL WINDOW Press the "ESC" key while in idle mode. The simulator control window is displayed, and the cursor appears in the upper left of the window. Use the RETURN key, and the left and right arrow keys to move the cursor around the simulator control window. These keys only move the cursor and do not change any information in the window. To change data anywhere in the window, simply position the cursor over the value to change and re-enter the desired value. To exit from the simulator control window and return to idle mode, press the ESC key again. If you wish to cancel any changes made in the simulator control window, you may press control-C instead. Let's look at the control window in detail. The top line looks very much like the information line in idle mode, except that the program counter appears to be further to the right and no instruction is disassembled on the line. The number on the left of the line is used for single-byte reading, single-byte writing, and memory editing. Enter an address value followed by 'R' to read, 'W' to write (also specify value to write), and 'E' to edit, using the memory edit window. To change display modes for the simulator program (text, graphics, hi-res, low-res, page 1, page 2, fullscreen, mixed), key in the address to toggle ($C050-$C057) and enter 'R'. When tracing a program in graphics mode, it is useful to put the information line on rows U,V,W, or X, and toggle mixed mode graphics. The simulator will display the information line on either text page 1 or 2, whichever is selected by the program being simulated. Enter an address, followed by 'E' to enter the memory edit window. While in the memory edit window, the memory is displayed in both hex and ASCII text. The cursor can be moved with the RETURN key and arrow keys. To change data, simply key in a new value in the appropiate address. The ESC key returns to the simulator control window, saving all changes to memory. If the changes made in the memory edit window are not to be made, enter control-C. The second line of the simulator control window contains: RU=65 0=I 1=I 2=I 3=S 4=I 5=I 7=I "RU=65" This value (decimal 101), the "register update" value, represents the number of instructions that are simulated before the registers and program counter are updated on the screen, when in "running" mode. If this number is set small (01 for example), the registers will be updated after every instruction. This however causes the simulator to run less efficiently, because of the overhead involved in updating the information line. SLOT SPECIFICATIONS The rest of the second line displays the slot numbers and how they are to be used. Because the simulator resides on a RAM board (indicatd by 'S' in the slot display, for "SYSTEM"), it must know about all other RAM boards and firmware boards if it is to correctly simulate their operation. Initially, the slots will be set to 'I' (invalid). Any reference by the simulated program to these invalid slots will cause the simulated program to stop and control is passed to idle mode. Valid slot specification values are: 'S' system (simulator) slot 'I' invalid 'D' floppy disk drive 'A' RAM card of 16K or 32K 'B' RAM card of 64K or more 'F' Firmware card or ROM card 'T' transparent If the specification for a slot is "transparent", any commands for the device in that slot will be given without any checking or conversion by the simulator. Transparent mode should be used for: Any devices such as RAM and ROM cards that bank select memory into the address range D000 to FFFF, which is used by the simulator. Any devices such as disk drives which are timing dependent, as the simulator runs much slower than the 6502 in native mode. Any devices that may use DMA (direct memory access) to modify memory from addresses $0000 to $07FF, as this memory is used by the simulator with a copy of the user's memory actually residing on the simulator's RAM board. ADDRESS COMPARE STOP The third line of the simulator control window starting with "PC" is the "PC compare stop" line. Up to four program counter values for "compare stops" can be specified. If the simulated program's PC equals one of these values, the simulator immediately enters idle mode. In addition, one "PC compare stop range" can be specified. To enter program counter stop values or a range, change the number (initially "0") to the number of stop addresses to be entered and then enter the addresses in the space provided. To disable PC compare stop, set the number back to "0". The "MR" line of the simulator control window is the "memory read address compare stop" line. Like the "PC compare stop" line, up to four addresses and one range can be specified. Whenever the simulated program attempts to read one of these addresses, either by direct addressing, indirect addressing or stack fetch, the simulator enters idle mode. The "MW" line of the simulator control window is the "memory write address compare stop" line. Idle mode is entered whenever the simulated program attempts to write to one of the addresses specified here. PROGRAM COUNTER SWAP The "PCSW" area of the simualtor control window is the "program counter swap" control area. Up to four address pairs can be specified here. If the simulated program's PC equals the first value of a pair, the PC is immediately set to the second value, and execution continues. This is very useful for eliminating slow timing loops, which are unnecessary in the simulator. Initially 3 pairs of PCSW values are given. They are: FCA8 FCB3 - This nullifies the monitor wait routine. BA00 BA10 - This nullifies the DOS 3.3 seek delay routine. BD9E BDAB - This nullifies the DOS 3.3 motor-on wait routine. PROGRAM COUNTER TRACE TABLE The bottom eight lines of the simulator control window contain the PC trace table. The last 64 values of the program counter are kept here, so that when the simualted program is halted, a history of the last 64 instructions can be examined. PROGRAM HALTS A program running under control of the simulator halts and the simulator enters idle mode whenever one of the following conditions is met: The "stop" key is pressed by the user. An invalid 6502 or 65C02 opcode is encountered. "???" is displayed in the information line where the opcode is normally displayed. A JSR or RTS instruction is fetched while running with the "T" (trace) command. A read or write to the device select addresses of a slot marked as "I" (invalid) in the slot table. A compare stop occurs for PC, MR, or MW, while running. An attempt is made to write to the floppy disk. An attempt is made to reference certain I/O addresses. Among these are $C060 and $C068 for either read or write. Note that in the case of a compare stop for MR or MW or an invalid device select reference, that idle mode is entered with te PC containing the address of the instruction the one that caused the compare stop. Look at the last address in the trace table to find the correct address. INTERNAL OPERATION NOTES A few notes on the internal operation of the boot tracer / simulator / debugger: Floppy disk reading is simulated by reading in an entire track of nibbles and passing them one at a time to the simulated program requesting them. Each time the simulated program requests a nibble, the next nibble in the buffer is returned. The simulated program never has to wait for a nibble by polling the high-order bit of the disk register. Because of this, framing bit timing is not reserved. In addition, the track is not synchronized to any other track upon reading. Floppy disk writing is not supported. When reading a floppy disk, the simulator maintains the nibbles of the most current track on the simulator's system RAM card. This track image is valid until either the slot or drive number is changed or reselected, or the read/write head is stepped to a different track. Only if the current track image is invalid will the real floppy disk be read again. Therefore, if the user performs a "CATALOG" operation while under control of the simulator and then changes the diskette and performs another "CATALOG" operation, the catalog information from the first disk will still be displayd because the catalog (located entirely on track $11) did not cause the head to change tracks and invalidate the track buffer. To manually invalidate the track buffer, change the slot specification to 'I' and back to 'D' while in the simulator control window. The simualtor has code for "sector assist" built-in. This means that when the simualted program requests a nibble followed by testing for disk register ready and compare for $D5, the simulator immediately finds the next $D5 in the track buffer and returns it to the simulatd program, instead of requiring the program to ignore each nibble until the value $D5 is found. The paddle I/O addresses ($C064-$C067 and $C06C-$C06F) are correctly simualted if the code that accesses the I/O addresses is similar to the monitor routine at $FB1E (PREAD). If the reference is not similar to the monitor routine, idle mode will be entered. -END-