textfiles/apple/DOCUMENTATION/ls.6.boot.trace

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