Re: Monitoring Program

[dempson@actrix.gen.nz (David Empson)]

Ingo Soetebier <ingo@igd.fhg.de> wrote:

> Hello,
> 
> I remember that there is a monitoring program (I hope it's the right
> translation - a program which shows the content of the memory as hexdump
> or as assembler listing) built in the Apple //c.

Yes.  Every Apple II has a built in "System Monitor", which lets you
play around with memory contents.

To get into it, start in BASIC and type CALL-151.

You then get an * prompt to indicate you are in the monitor.  To get
back to BASIC at a later point, press Control-C then return (on a line
by itself).

The monitor has a lot of commands and the syntax is rather cryptic.
Everything is entered and displayed in hexadecimal (base 16).

The simplest commands are a single letter.  For example, the "I" command
sets the display to inverse, and "N" sets it to normal.

The next level up in complexity are commands which expect a single
address parameter.  The address must be entered first, followed by the
command letter.  In some cases, the monitor remembers the last address
used, so you can continue where you left off by using the command letter
by itself.

An example of this is the "L" command (list) which disassembles 20
instructions.  The normal usage is to enter the start address followed
by an "L".  After you've seen one screenful, type "L" by itself and you
get another screenful continuing from the next address.

e.g.

E000L
L

The first command will list the first page of code for the Applesoft
BASIC interpreter, and the second command will list the second page.

You can use multiple commands on the same line, as long as you know what
you are doing.  If you don't mind pausing and resuming the scrolling
output (use Ctrl-S to pause, any key to resume), you can do something
like:

E000LLLLLLL

to get several pages of disassembly at once.


Moving up another step are commands that accept a range of addresses.
The address range is entered, with the start and end address separated
by a period (fullstop), and the command letter (if any) goes on the end.

The best example of this is a memory dump, which doesn't have a command
letter.  If you want to display a range of bytes as a hex dump, use
something like this:

E000.E07F

The monitor displays eight bytes per line, with the address at the
beginning of each line.  If you don't start on a multiple of eight, then
the first line will have less than eight bytes and subsequent lines will
be aligned on eight byte boundaries.

There are variations on the memory dump that can be used for special
cases:

1. You can press return on a blank line to display the next eight bytes.
2. If you enter an address and press return, one location is displayed.
3. You can continue from the end of the previous dump to a specified
address by entering a dot followed by the end address.

You can also display scattered locations by entering them as separate
commands.  For example:

E000 E003 E006

will display the three specified locations, one per line.


The third layer of command complexity are the commands which expect a
destination address and a source address range.  The destination address
goes first, then a less-than sign, then the source range (with a dot in
the middle), and finally the command letter.  The main example of this
is a memory move ("M"):

4000<6000.7FFFM

This will move 8192 (2000 hex) bytes from locations 6000 through 7FFF
down to 4000.

If your source and destination ranges overlap, the move will work
correctly if you are moving data to a lower memory location, but if
moving to a higher location you will get a repeating pattern of the data
from the start of the source range.


There is one major command that breaks the rules above: the "set memory"
command.  The general syntax for this is the start address followed by a
colon, then a space-separated list of bytes to be entered into memory.
If you enter more than two digits for the data bytes, only the low order
two digits are used.

If you are entering a lot of data, you can continue the command on
subsequent lines by starting the command with a colon (no address).

The rest of the command line after the colon is regarded as part of the
data to be entered, unless the monitor encounters a single letter
command first.

For example, the following single line command will enter a short
machine code program and disassemble it.  The "N" command (normal) is
used as a dummy command to force the data entry to terminate.

300:20 58 FC A9 C8 20 ED FD A9 E9 20 ED FD 20 8E FD 60 N 300L

Having got all that out of the way, here are the major monitor commands,
each given in example form.

<return>         Display next line of hex dump
1000             Hex dump one location
1000.101F        Hex dump a range of locations
.102F            Continue hex dump to specified address
1000:1 2 3 50    Set memory
:51 52 53        Continue set memory
300G             Go - call subroutine at specified location
G                Go again - call same address as last time
I                Inverse
300L             List - disassemble 20 lines
L                List again - continue disassembly
1000<2000.207FM  Move - copy range to destination address
N                Normal
1000<2000.207FV  Verify - compare range to destination address

There are also several commands that use control characters:

Ctrl-B           Cold start BASIC (avoid this)
Ctrl-C           Warm start BASIC
Ctrl-E           Display the saved CPU registers
Ctrl-K           Set input to specified slot (preceded by slot number)
Ctrl-P           Set output to specified slot (preceded by slot number)
Ctrl-Y           User command

The Ctrl-E command also lets you set the saved CPU registers, which will
be used on a subsequent G (go) command.  Type Ctrl-E then a colon,
followed by the data to place into the A, X and Y registers.

The Ctrl-K and Ctrl-P commands should be avoided if you are running
under DOS 3.3 or ProDOS, because they may cause DOS to be disconnected
from the I/O.  Use PR#n or IN#n instead.

Ctrl-Y is an "escape hatch", which allows third-party code to hook into
the monitor for this one command.

On the Apple IIgs, IIc (with UniDisk ROM or later), and enhanced IIe
there is also a mini-assembler which can be accessed from the monitor by
typing an exclamation mark as a monitor command.  While in the
mini-assembler you enter lines of the form Address:Instruction, or to
enter instructions in sequence, type a space then the instruction.  (You
must specify the address for the first instruction, or you could be
writing anywhere.)  Press <return> on a blank line to get back to the
monitor.

e.g. starting in the monitor, type in the following:

!
1000:JSR FC58
 LDA #C8
 JSR FDED
 LDA #E9
 JSR FDED
 JSR FD8E
 RTS
<return>
1000L
1000G

This is the same program I gave above as an example of the set memory
command, loaded at a different location.


It is important to keep in mind that you can do all sorts of nasty
things to the computer if you play around in the monitor and don't know
where things are located in memory.

The safest bet if you want to have a play would be to start the computer
with no disk in the drive, then get into the monitor.

Don't play around with the following memory areas at all (unless you
know exactly what you are doing):

0020-004F  Zero page memory area used by the monitor
0100-01FF  Stack
0200-02FF  Input buffer
03D0-03FF  System vectors
C000-C0FF  I/O space.  Don't even read memory in this area unless
           you know what you are doing.
C100-C7FF  I/O firmware (usually ROM on cards in slots, or emultated
           slots).  Some I/O cards may have I/O ports in this area (but
           not for the IIc).
C800-CFFF  Bank-switched area used by I/O cards.  It is safe to read
           this area in the IIc, but it has to be handled carefully
           in other machines.

The following areas must be handled carefully to avoid problems:

0050-00FF  Zero page memory area used by Applesoft BASIC
0400-07FF  Text screen and "screen holes", which contain system data
D000-FFFF  ROM and bank-switched RAM ("language card").  Don't write
           anything into this area, especially if you are running under
           ProDOS.

Other memory areas that you may need to be aware of:

0800-????  Applesoft BASIC programs normally go here, followed by
           variables
2000-3FFF  Hires graphics buffer for page 1
4000-5FFF  Hires graphics buffer for page 2
9600-BFFF  Normally used by DOS 3.3 or ProDOS
????-95FF  Normally used for strings in Applesoft BASIC

The hires graphics buffers are only an issue if you need to use them.
Under DOS 3.3 or ProDOS, the upper memory limit (9600) may change
depending on the use of the MAXFILES command under DOS or the number of
open files under ProDOS.

This leaves you with the following areas that you can usually play with
to your heart's content.  There are _some_ exceptions, but I've covered
enough for one article.

0000-001F  This isn't entirely free, but is usually OK.
0300-03CF  Often used for small machine code programs.
1000(ish)-7FFF(ish)

The last area varies wildly depending on the size of any BASIC program
and its variables.

-- 
David Empson
dempson@actrix.gen.nz
Snail mail: P.O. Box 27-103, Wellington, New Zealand