System Monitor

From A2wiki
Jump to: navigation, search

From: tdiaz-a(in_a_circle)-apple2-dotsero-org (Tony Diaz)
Newsgroups: comp.sys.apple2,comp.answers,news.answers
Approved: news-answers-request@MIT.EDU
Followup-To: comp.sys.apple2
Subject: comp.sys.apple2 Apple II System Monitor CMD Reference

Archive-name: apple2/faq/sysmon
Posting-Frequency: monthly
Last-modified: October 11 2007
Version: 0.54
URL: http://apple2.info/wiki/index.php?title=System_Monitor

The next section is the Frequently Asked Questions (FAQ) posting of the comp.sys.apple2 newsgroup. Copyright (c) 2007 by Tony Diaz (email: tdiaz-a(in_a_circle)-apple2-dotsero-org), all rights reserved. This document can be freely copied so long as 1) it is not sold, 2) any sections reposted elsewhere from it are credited back to this FAQ with the FAQ's copyright info and official WWW location ( http://apple2.info/wiki/index.php?title=System_Monitor) left in place.

This may not be the latest version of this FAQ-- this is an archived copy. For that, drop by http://apple2.info/wiki/index.php?title=System_Monitor

This FAQ may not be sold, bundled on disks or CD-ROMs, reprinted in magazines, books, periodicals, or the like without prior consent from the maintainer, Tony Diaz. Exceptions are explicitly granted for Juiced.GS and _The_Lamp. Email me for permission otherwise.

Big thanks to Nathan Mates, the previous maintainer of this comp.sys.apple2 FAQ, for allowing it to live on after his departure and anyone who took up that mantle before him.

Begin part 1 of 1

Apple II System Monitor command reference

NOTE: this reference is in beta form, and is still being written. Expect a few minor continuing changes in its layout, content, and correctness. Most info should be correct-- I'd like to be notified of any problems noted in here.



Table of Contents Section 1: General Intro to this FAQ and its conventions Section 2: System monitor commands listed by system: 2.1 How to enter the System Monitor 2.2 Commands in all System Monitor ROMs 2.3 GS Extensions to the System Monitor Section 3: The Miniassembler


General Intro to this reference and System Monitor

This FAQ attempts to be a reference for the commands supported by the inbuilt System Monitor contained in the ROM of all Apple II models. As there were a number of versions of the System Monitor, I've attempted to delineate which features are available depending on which model of the Apple II is present.

Warning: the System Monitor allows you to change blocks or bytes of RAM at will. You are advised that any manipulations of your Apple II's memory may cause your Apple II to crash or worse. You have been warned of the possibility of causing any damage to your system integrity, and by following any commands listed below, you accept responsibility for what you do.

This reference is one of a series of references that have been written detailing the Apple II. You may also want to read the Applesoft Basic FAQ, the DOS & Commands FAQ, or the comp.sys.apple2 FAQ.

Conventions used by this FAQ: Commands are given in double quotes, but those are not to be typed. <return> is the return key on the keyboard, and should be the last thing typed on a line to be parsed. "^C" (or any other letter) is shorthand for Control-C, i.e. hold down the control key and press C. 'Address', 'Address1', 'Address2' are valid addresses for your system-- either 16 bits or 24 for regular Apple II or GS. 'Val', 'Val2' ... are valid bytes to store in memory or registers. All addresses, values, etc are hex unless explicitly stated otherwise. In addition, leading 0s from addresses and values can be omitted.

System monitor commands listed by system

How to enter the System Monitor

The system monitor is identified with an asterisk ('*') for a prompt. If you have one of the earliest versions of the Apple II ROM, you will be placed in the monitor immediately on powerup. However, later ('Autostart') versions look for disks to boot first. From all Apple IIs at the Basic (either Applesoft or Integer) prompt, "CALL -151" will enter the monitor. ProDOS's BASIC.SYSTEM version 1.4 and up added the "MTR" command to do the same thing.

GSs with a ROM 01 or 3 have a "Visit Monitor" CDA (Classic Desk Accessory-- accessible from most programs by pressing Control-OpenApple-Escape at once) that is builtin, but not always enabled. To enable this CDA, the easiest way is to go to the "SetStart" Graphical Control Panel, and make sure "Enable Programmer CDAs" is selected, than reboot.

Commands in all System Monitor ROMs

Exiting the monitor:

From within the monitor, the easiest ways to get out are either "^B" or "^C" (don't forget to hit <return> at the end of your line), which return you to either Applesoft or Integer Basic. ^B zaps any program and variables in memory, while ^C preserves them. If you entered the GS's monitor through the "Visit Monitor" CDA, DO NOT use this method to exit to Basic; instead use ^Y as is printed when you enter the monitor-- your system will tend to crash as you attempt to exit.


Examining Memory

"Address" will dump the byte at that address; after that, if <return> is pressed again on a blank line, up to 8 bytes (16 if on a GS in 80-column mode) will be printed in continuing order.

"Address1.Address2" will dump all the memory between the two at up to 8/16 bytes per line. [If Address2 is less than Address1, only the byte at Address1 will be printed.] While doing a memory dump, ^S (no <return> needed) will pause, ^X will stop the dump.


Disassembling Memory

"AddressL" will disassemble 20 lines worth of "instructions" starting at that address; "L" by itself will continue on from wherever the previous "L" ended. Note that there is no effective difference between code and data in terms of the actual bytes in memory, so if the disassembly makes no sense, it may not be of executable code.


Setting Memory

"
Address: val1 [val2...]
" sets one or more bytes of memory. There is a practical limit of the number of bytes you can set at once due to the ~255 character limit of the command line, but whatever you type will be set. "
:val1 [val2...]
" continues setting memory from where the last memory set ended, allowing you to continue without retyping the starting address. If you try to mix examining and setting memory, setting reverts to the last explicitly specified address, not whatever was last displayed. For example,
2000
:FF" will set 2000 to FF.

Moving and comparing memory

"
Address1" will move memory in the range from Address2 to Address3 to the destination start address of Address1.

This is more of a copy than move, as the source memory is not modified if the destination range does not overlap the source. The copy is done in increasing order from Address2 to Address3.

"
Address1" will verify memory in the same type of block range as for moving, and print all differences, one difference per line. The address printed is the address in the source block, along with the value in the source block followed by the value (but not address) in the destination block in parens.

Simple math

"
Val1+Val2
" and "
Val1-Val2
" print the result of adding or subtracting the values, truncated to 8 bits. Examining/Setting registers, running programs "
^E
" will dump the current values of the registers. On pre-GS machines, this is only the A,X,Y,P and S registers.

To set the registers, immediately after a ^E, type

"
:NewA [NewX [NewY [NewP [NewS]]]]
". Registers may be omitted from the right sides if you don't want to change them, but the first value always goes into the accumulator, etc. "
AddressG
" provides a machine language JSR to the specified address with the current registeres set as above. Assuming your code returns with a RTS, you will normally return to the monitor cleanly; if you try to execute data instead of code, the results are usually a crash.

Cassette I/O

If your Apple II supports this (Apple ][, ][+ and //e only), you can read and write programs to a cassette interface attached to your computer's ports. To write a block of memory out, type

"
Address1.Address2W
"; reading is accomplished with "
Address1.Address2R
".

DOS I/O

Assuming that you have booted and entered the Monitor from DOS 3.x or ProDOS's BASIC.SYSTEM, you can execute all normal legal DOS commands just by typing them. This is because the OS intercepts the I/O vectors, and gets commands first before passing them on to whatever else is running. For a full list of commands, see the DOS & Commands FAQ at DOS

Misc I/O command

"
N
" sets the text display to "Normal" mode (white text on black background on normal Apple IIs; foreground text color on background text color for the GS); "
I
" sets it to "Inverse" (i.e. reverse) mode. "
n^P
" (n=0..7) sends output to that slot; "
n^K
" gets input from that slot. However, if DOS or ProDOS is active, it is highly recommended that you use the "PR#n" and "IN#n" commands to redirect I/O.

GS Extensions to the System Monitor

Note that the following are in addition to the normal features of the Apple II System Monitor as detailed above, except for the obvious lack of cassette tape support.

If you're doing extensive GS programming work, you may find the combination of the GSBug init and the Nifty List CDA to be invaluable and far more useful and powerful than the builtin monitor. GSBug is available from Apple's FTP site; Niftylist is on the usual legitimate Apple II ftp sites, such as:

ftp://apple2.caltech.edu/pub/apple2/addons/cda/niftylist34.shk

Extended syntax

As the 65816 in the GS can address memory 24 bits wide, addresses can now have a third byte in them. They must be specified with a '/' after the bank byte, i.e. "AB/CDEF". Banks specified simply by themself (such as "AB/") are sticky; i.e. if the bank is omitted after that, the last set bank is used.

Searching Memory

"
/Pattern/" searches at most one bank for the

specified pattern. The pattern can be a set of bytes, or a string enclosed in "s.

Extended register examining and setting "
^E
" still works, but prints much more information on the GS's extended registers. In addition, it is possible to set any register directly with "val=RegisterName" using the reister names as printed by ^E. The m and x registers are used by the builtin disassembler ("L") to decide whether to print one or two bytes after immediate mode instructions. The ROM 00/01 does not track REP/SEP instructions, so if they chnage in the middle of code, the disassembly will look wrong.

The ROM 3 does it right, but may still need to be told what mode to start disassembling in. "^R" resets registers to a "default" state of mostly all 0.

Extended running programs

"
AddressG
" still uses a JSR, so your code should be in bank 0. [A beep will tend to occur if you are not in bank 0.] "AddressX" does a JSL to the address, and "AddressR" does a JML to that code.

Extended math and conversions

Math operations can now take up to 32-bit operands as input. Multiplication is implemented as '*', and integer division is implemented as '_'. The result of addition/subtraction is reported as a 32-bit number; multiplication has a 64-bit result. Division has a 32-bit remainder and quotient reported. Conversions between hexadecimal and decimal is now possible; use "hexval=" to convert to decimal and "=decval" to convert to hex.

Random other GS stuff

"
=T
" shows the current system date and time. "
\{Bytes to put on stack} {Bytes to pull off stack} {Parameter bytes} {Function %23} {Tool %23}\U
" will attempt to do a GS toolset call. All of the parameters are bytes, with the possible exception of the parameter list. Any execution error is reported.

The Miniassembler

The miniassembler is aptly named-- it supports going from assembly mnemonic to the hex form one instruction at a time, no support for labels, inserting code, or anything else. It is mostly useful for quick tests of code.

The miniassembler is accessible from most but not all Apple IIs. From ][s and ][+s with Integer Basic in ROM, type '
F666G
' to enter it from the monitor prompt; //c, enhanced //e, IIc+ and GS, type "!" from the monitor prompt to enter the miniassembler. This miniassembler is identified with a "!" prompt, and is separate from the normal monitor-- monitor commands won't work in it.

In the miniassembler, the first instruction is entered as follows: "Address: opcode [data]". If there are any errors in a line, the speaker beeps, and a ^ is placed under the first location where it thinks there is an error. Continuing lines can be entered as follows: " opcode [data]" (note leading space on line).

To exit the miniassembler, simply hit return on a blank line. In the GS, the miniassembler does not keep track of register sizes; if you want to use a 16-bit value, you must provide 3 or 4 digits, padding it with leading 0s on the left to make that many digits.