APPENDIX J

MACHINE LANGUAGE MONITOR

J.1 Introduction

Commodore 128 has a built-in machine language monitor which lets the user write and examine machine language programs easily. Commodore 128 MONITOR includes a machine language monitor, a mini-assembler and a disassembler. The built-in monitor works only in C128 mode; either 40 column or 80 column.

Machine language programs written using Commodore 128 MONITOR can run by themselves or be used as very fast subroutines for BASIC programs since the Commodore 128 MONITOR has the ability to coexist peacefully with BASIC.

Care must be taken to position the assembly language programs in memory so the BASIC program does not overwrite them.

To enter the monitor from BASIC, type:

MONITOR {return}

Summary of Commodore 128 Monitor Commands
ASSEMBLE	Assembles a line of 8502 code.
COMPARE	Compares two sections of memory and reports differences.
DISASSEMBLE	Disassembles a line of 8502 code.
FILL	Fills a range of memory with the specified byte.
GO	Starts execution at the specified address.
HUNT	Hunts through memory within a specified range for all occurrances of a set of bytes.
JUMP	Jumps to the subroutine.
LOAD	Loads a file from tape or disk.
MEMORY	Displays the hexadecimal values of memory locations.
REGISTERS	Displays the 8502 registers.
SAVE	Saves to tape or disk.
TRANSFER	Transfers code from one section of memory to another.
VERIFY	Compares memory with tape or disk.
EXIT	Exits Commodore 128 MONITOR
(period)	Assembles a line of 8502 code (same as Assemble).
(greater than)	Modifies memory.
(semicolon)	Modifies 8502 register displays.
@ (at sign)	Displays disk status, sends disk command, displays directory.

The Commodore 128 displays 5-digit hexadecimal addresses within the machine language monitor. Normally, a hexadecimal number is only four digits, representing the allowable address range. The extra left-most (high order) digit specifies the BANK configuration (at the time the given command is executed) according to the following memory configuration table:

0 - RAM 0 only                8 - EXT ROM, RAM 0, I/O
1 - RAM 1 only                9 - EXT ROM, RAM 1, I/O
2 - RAM 2 only                A - EXT ROM, RAM 2, I/O
3 - RAM 3 only                B - EXT ROM, RAM 3, I/O
4 - INT ROM, RAM 0, I/O       C - KERNAL + INT (lo), RAM 0, I/O
5 - INT ROM, RAM 1, I/O       D - KERNAL + EXT (lo), RAM 0, I/O
6 - INT ROM, RAM 2, I/O       E - KERNAL + BASIC, RAM 0, CHARROM
7 - INT ROM, RAM 3, I/O       F - KERNAL + BASIC, RAM 0, I/O

J.2 Summary for Monitor Field Descriptors

The following designators precede monitor data fields (e.g. memory dumps). When encountered as a command, these designators instruct the monitor to alter memory or register contents using the given data.

.  {period}       precedes lines of disassembled code
>  {right angle}  precedes lines of memory dump
;  {semicolon}    precedes line of a register dump

The following designators precede number fields (e.g. addresses) and specify the radix (number base) of the value. Entered as commands, these designators instruct the monitor simply to display the given value in each of the four radices.

   {null}         (default) precedes hexadecimal values.
$  {dollar}       precedes hexadecimal (base-16) values
+  {plus}         precedes decimal (base-10) values
&  {ampersand}    precedes octal (base-8) values
%  {percent}      precedes binary (base-2) values

The following characters are used by the monitor as field delimiters or line terminators (unless encountered within an ASCII string).

   {space}        delimiter  seperates two fields
,  {comma}        delimiter  seperates two fields
:  {colon}        terminator logical end of line
?  {question}     terminator logical end of line

J.3 Commodore 128 Monitor Command descriptions

Note: < > enclose required parameters
[ ] enclose optional parameters

Please note that any number field (e.g. addresses, device number, and data bytes) may be specified as a based number. This affects the operand field of the ASSEMBLE command as well. Also note the addition of the directory syntax to the disk command.

As a further aid to programmers, the Kernel error message facility has been automatically enabled while in the Monitor. This means the Kernel will display &quot;I/O ERROR#&quot; and the error code, should there be any failed I/O attempt from the MONITOR. The message facility is turned off when exiting the MONITOR.

COMMAND:	A
PURPOSE:	Enter a line of assembly code
SYNTAX:	A	<address> <opcode mnemonic> <operand>
		<address>	A hexadecimal number indicating the location in memory to place the opcode.
		<opcode mnemonic>	A standard MOS technology assembly language mnemonic, e.g. LDA, STX, ROR.
		<operand>	The operand, when required, can be any of the legal addressing modes.

A {return} is used to indicate the end of the assembly line. If there are any errors on the line, a question mark is displayed to indicate an error, and the cursor moves to the next line. The screen editor can be used to correct the error(s) on that line.

EXAMPLE:

A01200 LDX #$00
A 1202

NOTE: A period (.) is equal to the ASSEMBLE command.

EXAMPLE:

.02000 LDA #$23

COMMAND:	C
PURPOSE:	Compare two areas of memory
SYNTAX:	C	<address1> <address 2> <address 3>
		<address 1>	A number indicating the start address of the area of memory to compare against.
		<address 2>	A number indicating the end address of the area of memory to compare against.
		<address 3>	A number indicating the start address of the other area of memory to compare with.

Addresses that do not agree are printed on the screen.

COMMAND:	D
PURPOSE:	Disassemble machine code into assembly language mnemonics and operands.
SYNTAX:	D	[<address 1>] [<address 2>]
		<address 1>	A number setting the address to start the disassembly.
		<address 2>	An optional ending address of code to be disassembled.

The format of the disassembly differs slightly from the input format of an assembly. The difference is that the first character of a disassembly is a period rather than an A (for readability), and the hexadecimal code is listed as well.

A disassembly listing can be modified using the screen editor. Make any changes to the mnemonic or operand on the screen, then hit the carriage return. This enters the line and calls the assembler for further modifications.

A disassembly can be paged. Typing a D{return} causes the next page of disassembly to be displayed.

EXAMPLE:

D 3000 3003
.03000 A9 00      LDA #$00
.03002 FF         ???
.03003 D0 2B      BNE $3030

COMMAND:	F
PURPOSE:	Fill a range of locations with a specified byte.
SYNTAX:	F	<address 1> <address 2> <byte>
		<address 1>	The first location to fill with the <byte>.
		<address 2>	The last location to fill with the <byte>.
		<byte>	Number to be written.

This command is useful for initializing data structures or any other RAM area.

EXAMPLE:

F 0400 0518 EA

COMMAND:	G
PURPOSE:	Begin execution of a program at a specified address.
SYNTAX:	G	[<address>]
		<address>	An address where execution is to start. When address is left out, execution begins at the current PC. (The current PC can be viewed using the R command.)

The GO command restores all registers (displayable by using the R command) and begins execution at the specified starting address. Caution is recommended in using the GO command. To return to Commodore 128 MONITOR mode after executing a machine language program, use the BRK instruction at the end of the program.

EXAMPLE:

G 140C

COMMAND:	H
PURPOSE:	Hunt through memory within a specified range for all occurrences of a set of bytes.
SYNTAX:	H	<address 1> <address 2> <data>
		<address 1>	Beginning address of hunt procedure.
		<address 2>	Ending address of hunt procedure.
		<data>	Data set to search for data may be numbers or an ASCII string.

EXAMPLES:

H A000 A101 A9 FF 4C

H 2000 9800 'CASH

COMMAND:	J
PURPOSE:	Begin execution of a program at a specified address.
SYNTAX:	J	[<address>]
		<address>	An address where execution is to start. When address is left out, execution begins at the current PC.(The current PC can be viewed using the R command.)

The JUMP command restores all registers (displayable by using the R command) and begins execution at the specified starting address. Caution is recommended in using the JUMP command. To return to Commodore 128 MONITOR mode after executing a machine language program, use the RTS instruction at the end of the program.

EXAMPLE:

J 1300

COMMAND:	L
PURPOSE:	Load a file from cassette or disk.
SYNTAX:	L	<"file name"> [,<device> [,alt load address] ]
		<"file name">	Any legal Commodore 128 file name.
		<device>	A hexadecimal number indicating the device to load from, 1 is cassette, 8 is disk (or 9, A, etc.).
		[alt load address]	Option to load a file to a specific address (4-digit number), or a bank configuration and address (5-digit number).

The LOAD command causes a file to be loaded into memory. If the alternate load address is not used, the file will be loaded to the address in bank 0 that is specified in the cassette header, or the first two bytes of a disk file. The alternate load address is used to specify a different start address, which may range from $00000 to $FFFFF.

EXAMPLE:

L "PROGRAM", $12000

COMMAND:	M
PURPOSE:	To display memory as a hexadecimal and ASCII dump within the specified address range.
SYNTAX:	M	[<address 1> [<address 2>]]
		<address 1>	First address of memory dump. Optional. If omitted, one page is displayed. The first byte is the bank number to be displayed, the next four bytes are the first address to be displayed.
		<address 2>	Last address of memory dump. Optional. If omitted, one page is displayed. The first byte is the bank number to be displayed, the next four bytes are the ending address to be displayed.

Memory is displayed in the following format:

>03000 45 58 2E 56 41 4C 55 45:EX.VALUE

Memory content may be edited using the screen editor. Move the cursor to the data to be modified, type the desired correction and hit {return}. If there is a bad RAM location or an attempt to modify ROM has occurred, an error flag (?) is displayed.

An ASCII dump of the data is displayed in REVERSE (to contrast with other data displayed on the screen) to the right of the hex data. When a character is not printable, it is displayed as a reverse period (.).

As with the disassembly command, paging down is accomplished by typing M and {return}.

EXAMPLE:

M F4151 F4201

>F41F1 20 43 4F 4D 4D 4F 44 4F: COMMODO
>F41F9 52 45 20 45 4C 45 43 54:RE ELECT
>F4201 52 4F 4E 49 43 53 2C 20:TRONICS,

NOTE: The above display is produced by the 40-column editor.

COMMAND:	R
PURPOSE:	Show important 8502 registers. The program status register, the program counter, the accumulator, the X and Y index registers and the stack pointer are displayed.
SYNTAX:	R

The values of PC, SR, AC, XR, YR and SP are transfered to the 8502 before the Go or Jump command is executed.

EXAMPLE:

R
   PC   SR  AC  XR  YR  SP
;01002  01  02  03  04  F6

NOTE: ; {semicolon} can be used to modify register displays in the same fashion as > (greater than) can be used to modify memory registers.

COMMAND:	S
PURPOSE:	Save an area of memory onto tape or disk.
SYNTAX:	S	<"file name">, <device>, <address 1>, <address 2>
		<"file name">	Any legal Commodore 128 file name. To save the data the name must be enclosed in double quotes. Single quotes cannot be used.
		<device>	A hexadecimal number indicating on which device the file is to be placed. Cassette is 1; disk is 8, 9, etc.
		<address 1>	Starting address of memory to be saved.
		<address 2>	Ending address of memory to be saved + 1. All data up to, but not including the byte of data at this address, is saved.

The file may be recalled, using the L command. When saving to cassette only bank 0 can be saved from.

EXAMPLE:

S "GAME",8,0400,0C00

COMMAND:	T
PURPOSE:	Transfer segments of memory from one memory area to another.
SYNTAX:	T	<address 1> <address 2> <address 3>
		<address 1>	Starting address of data to be moved.
		<address 2>	Ending address of data to be moved.
		<address 3>	Starting address of of new location where data will be moved.

Data can be moved from low memory to high memory and vice versa. Additional memory segments of any length can be moved forward or backward. An automatic "compare" is performed as each byte is transferred, and any differences are listed by address.

EXAMPLE:

T 1400 1600 1401

COMMAND:	V
PURPOSE:	Verify a file on cassette or disk with the memory contents.
SYNTAX:	V	<"file name"> [,<device> [,alt start address] ]
		<"file name">	Any legal Commodore 128 file name.
		<device>	A hexadecimal number indicating the device to load from, 1 is cassette, disk is 8, 9, etc.).
		[alt start address]	Option to start verification at this address (4-digit number), or a bank configuration and address (5-digit number).

The Verify command compares a file to memory contents. The Commodore 128 responds with VERIFYING. If an error is found the word ERROR is added; if the file is successfully verified the cursor reappears.

EXAMPLE:

V "WORKLOAD", 8

COMMAND:	X
PURPOSE:	Exit to BASIC.
SYNTAX:	X

COMMAND:	. {point}
PURPOSE:	Can be used to enter a line of assembly code.
SYNTAX:	see the A command.

COMMAND:	> (greater than)
PURPOSE:	Can be used to set up to 8 or 16 memory locations.
SYNTAX:	>	<address> [<data byte 1... 8/16>]
		<address>	First memory address to set.
		<data byte 1... 8/16>	Data to be placed in succesive memory locations following the address, with a space preceding each data byte.

The maximum number of bytes that can be entered is 8 (in 40 column mode) or 16 (in 80 column mode). When the {return} key is pressed the contents of the 8/16 locations after the address are displayed in hexadecimal value and as ASCII character.

EXAMPLES:

>2000

>2000 31 32 38

COMMAND:	; {semicolon}
PURPOSE:	Can be used to modify the display of important 8502 registers.
SYNTAX:	;	[<PC> [<SR> [<AC> [<XR> [<YR> [<SP>]]]]]]
		<PC>	A 5 digit hexadecimal number, consisting of the (leading) 1-digit bank configuration number and 4-digit value of the 8502 Program Counter.
		<SR>	A 2-digit hexadecimal number, indicating the value of the 8502 Status Register.
		<AC>	A 2-digit hexadecimal number, indicating the value of the 8502 Accumulator.
		<XR>	A 2-digit hexadecimal number, indicating the value of the 8502 X index Register.
		<YR>	A 2-digit hexadecimal number, indicating the value of the 8502 Y index Register.
		<SP>	A 2-digit hexadecimal number, indicating the value of the 8502 Stack Pointer.

It is easier to use the R command, because the register labels are listed above the line containing the register values.

The values of PC, SR, AC, XR, YR and SP are transfered to the 8502 before the Go or Jump command is executed.

COMMAND:	@ {at sign}
PURPOSE:	Can be used to display the disk status.
SYNTAX:	@	[<unit#>], <disk cmd string>
		<unit#>	Device unit number (optional).
		<disk cmd string>	String command to disk.
	NOTE: @ alone gives the status of the disk drive.

EXAMPLES:

@
00, OK, 00, 00

@,I

@,$