The Woz Monitor
When a computer is powered up it must know what it must do.
It goes without saying that a piece of software must be executed.
Since the computer has just been powered up there must be some software in memory somewhere.
This software is programmed in ROM memory because ROM chips are non volatile and will not forget the contents when power is removed.
Fairly obvious don't you think?
Well, think again!
The most popular "personal computer" back then, the Altair 8800, had no ROM at all.
When you powered that machine up it did absolutely nothing.
You had to flip a few hundred switches in order to enter the first program, which was then able to load the real stuff in.
When a computer is powered up it must know what it must do.
It goes without saying that a piece of software must be executed.
Since the computer has just been powered up there must be some software in memory somewhere.
This software is programmed in ROM memory because ROM chips are non volatile and will not forget the contents when power is removed.
The Apple 1 was far more advanced, it did contain some ROM memory. The basic version of the Apple 1 had a total of 256 bytes of ROM! Remember that memory used to be very expensive at the time the Apple 1 was developed. This ROM was filled with the legendary Woz Monitor. It allowed the user to examine and change memory contents and it allowed machine language programs to be started.
Using The Woz Monitor
The original Apple 1 did not come with a Reset circuit, which means that the user has to press the RESET button in order to get the machine started. Once you do that a back slash '\' is printed on the screen and the cursor will drop down one line. The cursor position is represented by a flashing '@' symbol.
You can now type address, data and commands which will be executed as soon as you press the Return key.
The input buffer can hold up to 127 character, if you type more characters before hitting the Return key the input line will be erased and will start again from scratch.
This overflow situation is indicated by a new back slash after which the cursor drops one line again.
Because of the primitive nature of the terminal there are not many line-editing features available.
You can press the back arrow key to erase characters from the input buffer, but the erased characters will not be erased from the screen nor will the cursor position back-up.
You'll have to keep track of the changes yourself.
It's obvious that you can easily get confused when a line contains too many corrections or when an error is detected all the way at the other end of the input line.
In that case it would be easiest to cancel the input and start all over again.
Canceling the input is done by pressing the ESC key.
Address inputs are truncated to the least significant 4 hexadecimal digits.
Data inputs are truncated to the least significant 2 hexadecimal digits.
Thus entering 12345678 as address will result in the address 5678 to be used.
Tip: This can also be used to your advantage to correct typing errors, instead of using the back arrow key.
If an error is encountered during the parsing of the input line then the rest of the line is simply ignored, without warning! Commands executed before the error are executed normally though.
Examining memory (memory dump)
You can examine the contents of a single memory location by typing a single address followed by a Return.
4F 004F: 0F
Note: The bold typed characters are what the user types. All other characters are responses from the Apple 1.
Now let us examine a block of memory from the last opened location to the next specified location.
.5A 0050: 00 01 02 03 04 05 06 07 0058: 08 09 0A
Note: 004F is still considered the most recently opened location.
We can also combine the previous two examples into one command:
4F.5A 004F: 0F 0050: 00 01 02 03 04 05 06 07 0058: 08 09 0A
Note: Only the first location of the block 4F is considered opened.
You can also examine several locations at once, with all addresses on one command line.
4F 52 56 004F: 0F 0052: 02 0056: 06
Note: 0056 is considered the most recently opened address.
Let's take this concept into the extremes and combine some block and single address examinations on one command line.
4F.52 56 58.5A 004F: 0F 0050: 00 01 02 0056: 06 0058: 08 09 0A
Note: By now you won't be surprised that 0058 is considered the most recently opened location.
Finally let's examine some successive blocks of memory. This can be handy if you want to examine a larger block of memory which will not fit on one monitor screen. Remember that there is no way to halt a large examine list other than hitting the RESET button!
4F.52 004F: 0F 0050: 00 01 02 .55 0053: 03 04 05 .5A 0056: 06 07 0058: 08 09 0A
Depositing memory (changing memory contents)
This is how to change a single memory location (provided it is RAM memory of course).
30:A0 0030: FF
Note: FF is what location 0030 used to contain before the operation, from now on it contains A0. Location 0030 is now considered the most recently opened location.
Now we're going to deposit some more bytes in successive locations, starting from the last deposited location.
:A1 A2 A3 A4 A5
Note: Location 31 now contains A1, location 32 contains A2 and so on until location 35 which now contains A5.
Combining these two techniques will give us the next example.
30:A0 A1 A2 A3 A4 A5 0030: FF
Note: Location 0030 used to contain FF in this example.
Breaking up a long entry into multiple command lines is done like this:
30:A1 A2 0030: FF :A2 A3 :A4 A5
Note: A colon in a command means "start depositing data from the most recently deposited location, or if none, then from the most recently opened location.
Now we're going to examine a piece of memory and then deposit some new data into it:
30.35 0030: A0 A1 A2 A3 A4 A5 :B0 B1 B2 B3 B4 B5
Note: New data deposited beginning at most recently opened location, which is 0030 in this example.
Running a program
To run a program at a specified address:
10F0 R 10F0: A9
Note the cursor is left immediately to the right of the displayed data; it is not returned to the next line. It's the program's responsibility to control the rest of the output.
From now on the user program is in control of the Apple 1. If the user program does not return to the Woz monitor (by jumping to address $FF1F) you'll have to press the RESET key to stop your program and return to the Woz Monitor.
You can also enter a program and run it all from the same command line. Please note that this only works for very short programs of course.
40: A9 0 20 EF FF 38 69 0 4C 42 0 R 40: FF
Note: FF is the previous contents of location 0040.
This little program will continue printing characters to the screen.
It can only be stopped by pressing the RESET key.
The Woz Monitor's RAM Use
The monitor needs some RAM memory to perform its tasks. When a user program is running all bytes used by the monitor may be recycled, the monitor doesn't care about the contents of any of the memory locations when it regains control again. Here's the complete list of all the memory the Woz Monitor requires while it is running:
| Zero page | $24 to $2B | General purpose storage locations. None of the bytes are very important and they may all be changed by the user program. |
| Stack page | $0100 to $01FF | Although the Woz Monitor only uses 3 bytes of stack space at most, there is no way of telling where the stack actually is.
This is because the stack pointer is not initialized by the Woz Monitor.
A user program may use the entire stack for its own purposes. However be careful when entering code on page $01 before the stack pointer is initialized, the monitor may overwrite your code again. |
| Input buffer | $0200 to $027F | This space is used as input buffer. User programs may use this area. However you can not enter code here manually because it will be overwritten by the monitor. |
The next addresses are not exactly RAM locations, which doesn't make them less important though. They are the 6821 PIA control registers.
| KBD | $D010 | Keyboard input register.
This register holds valid data when b7 of KBDCR is "1".
Reading KBD will automatically clear b7 of KBDCR.
Bit b7 of KBD is permanently tied to +5V. The monitor expects only upper case characters. |
| KBDCR | $D011 | The only bit which we are interested in in this register is the read-only bit b7. It will be set by hardware whenever a key is pressed on the keyboard. It is cleared again when the KBD location is read. |
| DSP | $D012 | Bits b6..b0 are the character outputs for the terminal display.
Writing to this register will set b7 of DSP, which is the only input bit of this register.
The terminal hardware will clear bit b7 as soon as the character is accepted. This may take up to 16.7ms though! |
| DSPCR | $D013 | This register is better left untouched, it contains no useful data for a user program. The Woz Monitor has initialized it for you. Changing the contents may kill the terminal output until you press RESET again. |
Useful Routines
Apart from the monitor program itself the Woz Monitor contains only a few useful routines which can be called by user programs.
| $FF1F | GETLINE | This is the official monitor entry point. If your program is finished and you want to return to the monitor you can simply jump to this location. It will echo a CR and from then on you are back in the monitor. |
| $FFEF | ECHO | This simple routine prints the character in the Accumulator to the terminal.
The contents of the Accumulator are not disrupted, only the flag register will be changed.
Although this is a fairly short routine it may take up to some 16.7ms before it returns control to the user program. For more details about this behaviour please read the page about the terminal. |
| $FFDC | PRBYTE | This routine prints the byte which is held in the Accumulator in hexadecimal format (2 digits). The contents of the Accumulator are disrupted. |
| $FFE5 | PRHEX | Prints the least significant 4 bits of the Accumulator in hexadecimal format (1 digit). The contents of the Accumulator are disrupted. |
If you want to read a single character from the keyboard from within your own machine language program you can use the following piece of code:
KBDIN LDA KBDCR See if there is a character available
BPL KBDIN Not as long as b7 remains low
LDA KBD Get the character and clear the flag
The Woz Monitor In More Detail
As a user you do not need to know the details about the Woz Monitor. But since I had to understand how the Apple 1 worked I had to find out all the details for myself anyway. Therefore I might as well share them with you in case you're interested.
;-------------------------------------------------------------------------
;
; The WOZ Monitor for the Apple 1
; Written by Steve Wozniak 1976
;
;-------------------------------------------------------------------------
.CR 6502
.OR $FF00
.TF WOZMON.HEX,HEX,8
;-------------------------------------------------------------------------
; Memory declaration
;-------------------------------------------------------------------------
XAML .EQ $24 Last "opened" location Low
XAMH .EQ $25 Last "opened" location High
STL .EQ $26 Store address Low
STH .EQ $27 Store address High
L .EQ $28 Hex value parsing Low
H .EQ $29 Hex value parsing High
YSAV .EQ $2A Used to see if hex value is given
MODE .EQ $2B $00=XAM, $7F=STOR, $AE=BLOCK XAM
IN .EQ $0200,$027F Input buffer
KBD .EQ $D010 PIA.A keyboard input
KBDCR .EQ $D011 PIA.A keyboard control register
DSP .EQ $D012 PIA.B display output register
DSPCR .EQ $D013 PIA.B display control register
; KBD b7..b0 are inputs, b6..b0 is ASCII input, b7 is constant high
; Programmed to respond to low to high KBD strobe
; DSP b6..b0 are outputs, b7 is input
; CB2 goes low when data is written, returns high when CB1 goes high
; Interrupts are enabled, though not used. KBD can be jumpered to IRQ,
; whereas DSP can be jumpered to NMI.
;-------------------------------------------------------------------------
; Constants
;-------------------------------------------------------------------------
BS .EQ $DF Backspace key, arrow left key
CR .EQ $8D Carriage Return
ESC .EQ $9B ESC key
PROMPT .EQ "\" Prompt character
;-------------------------------------------------------------------------
; Let's get started
;
; Remark the RESET routine is only to be entered by asserting the RESET
; line of the system. This ensures that the data direction registers
; are selected.
;-------------------------------------------------------------------------
RESET CLD Clear decimal arithmetic mode
CLI
LDY #%0111.1111 Mask for DSP data direction reg
STY DSP (DDR mode is assumed after reset)
LDA #%1010.0111 KBD and DSP control register mask
STA KBDCR Enable interrupts, set CA1, CB1 for
STA DSPCR positive edge sense/output mode.
; Program falls through to the GETLINE routine to save some program bytes
; Please note that Y still holds $7F, which will cause an automatic Escape
;-------------------------------------------------------------------------
; The GETLINE process
;-------------------------------------------------------------------------
NOTCR CMP #BS Backspace key?
BEQ BACKSPACE Yes
CMP #ESC ESC?
BEQ ESCAPE Yes
INY Advance text index
BPL NEXTCHAR Auto ESC if line longer than 127
ESCAPE LDA #PROMPT Print prompt character
JSR ECHO Output it.
GETLINE LDA #CR Send CR
JSR ECHO
LDY #0+1 Start a new input line
BACKSPACE DEY Backup text index
BMI GETLINE Oops, line's empty, reinitialize
NEXTCHAR LDA KBDCR Wait for key press
BPL NEXTCHAR No key yet!
LDA KBD Load character. B7 should be '1'
STA IN,Y Add to text buffer
JSR ECHO Display character
CMP #CR
BNE NOTCR It's not CR!
; Line received, now let's parse it
LDY #-1 Reset text index
LDA #0 Default mode is XAM
TAX X=0
SETSTOR ASL Leaves $7B if setting STOR mode
SETMODE STA MODE Set mode flags
BLSKIP INY Advance text index
NEXTITEM LDA IN,Y Get character
CMP #CR
BEQ GETLINE We're done if it's CR!
CMP #"."
BCC BLSKIP Ignore everything below "."!
BEQ SETMODE Set BLOCK XAM mode ("." = $AE)
CMP #":"
BEQ SETSTOR Set STOR mode! $BA will become $7B
CMP #"R"
BEQ RUN Run the program! Forget the rest
STX L Clear input value (X=0)
STX H
STY YSAV Save Y for comparison
; Here we're trying to parse a new hex value
NEXTHEX LDA IN,Y Get character for hex test
EOR #$B0 Map digits to 0-9
CMP #9+1 Is it a decimal digit?
BCC DIG Yes!
ADC #$88 Map letter "A"-"F" to $FA-FF
CMP #$FA Hex letter?
BCC NOTHEX No! Character not hex
DIG ASL
ASL Hex digit to MSD of A
ASL
ASL
LDX #4 Shift count
HEXSHIFT ASL Hex digit left, MSB to carry
ROL L Rotate into LSD
ROL H Rotate into MSD's
DEX Done 4 shifts?
BNE HEXSHIFT No, loop
INY Advance text index
BNE NEXTHEX Always taken
NOTHEX CPY YSAV Was at least 1 hex digit given?
BEQ ESCAPE No! Ignore all, start from scratch
BIT MODE Test MODE byte
BVC NOTSTOR B6=0 is STOR, 1 is XAM or BLOCK XAM
; STOR mode, save LSD of new hex byte
LDA L LSD's of hex data
STA (STL,X) Store current 'store index'(X=0)
INC STL Increment store index.
BNE NEXTITEM No carry!
INC STH Add carry to 'store index' high
TONEXTITEM JMP NEXTITEM Get next command item.
;-------------------------------------------------------------------------
; RUN user's program from last opened location
;-------------------------------------------------------------------------
RUN JMP (XAML) Run user's program
;-------------------------------------------------------------------------
; We're not in Store mode
;-------------------------------------------------------------------------
NOTSTOR BMI XAMNEXT B7 = 0 for XAM, 1 for BLOCK XAM
; We're in XAM mode now
LDX #2 Copy 2 bytes
SETADR LDA L-1,X Copy hex data to
STA STL-1,X 'store index'
STA XAML-1,X and to 'XAM index'
DEX Next of 2 bytes
BNE SETADR Loop unless X = 0
; Print address and data from this address, fall through next BNE.
NXTPRNT BNE PRDATA NE means no address to print
LDA #CR Print CR first
JSR ECHO
LDA XAMH Output high-order byte of address
JSR PRBYTE
LDA XAML Output low-order byte of address
JSR PRBYTE
LDA #":" Print colon
JSR ECHO
PRDATA LDA #" " Print space
JSR ECHO
LDA (XAML,X) Get data from address (X=0)
JSR PRBYTE Output it in hex format
XAMNEXT STX MODE 0 -> MODE (XAM mode).
LDA XAML See if there's more to print
CMP L
LDA XAMH
SBC H
BCS TONEXTITEM Not less! No more data to output
INC XAML Increment 'examine index'
BNE MOD8CHK No carry!
INC XAMH
MOD8CHK LDA XAML If address MOD 8 = 0 start new line
AND #%0000.0111
BPL NXTPRNT Always taken.
;-------------------------------------------------------------------------
; Subroutine to print a byte in A in hex form (destructive)
;-------------------------------------------------------------------------
PRBYTE PHA Save A for LSD
LSR
LSR
LSR MSD to LSD position
LSR
JSR PRHEX Output hex digit
PLA Restore A
; Fall through to print hex routine
;-------------------------------------------------------------------------
; Subroutine to print a hexadecimal digit
;-------------------------------------------------------------------------
PRHEX AND #%0000.1111 Mask LSD for hex print
ORA #"0" Add "0"
CMP #"9"+1 Is it a decimal digit?
BCC ECHO Yes! output it
ADC #6 Add offset for letter A-F
; Fall through to print routine
;-------------------------------------------------------------------------
; Subroutine to print a character to the terminal
;-------------------------------------------------------------------------
ECHO BIT DSP DA bit (B7) cleared yet?
BMI ECHO No! Wait for display ready
STA DSP Output character. Sets DA
RTS
;-------------------------------------------------------------------------
; Vector area
;-------------------------------------------------------------------------
.DA $0000 Unused, what a pity
NMI_VEC .DA $0F00 NMI vector
RESET_VEC .DA RESET RESET vector
IRQ_VEC .DA $0000 IRQ vector
;-------------------------------------------------------------------------
.LI OFF
Woz monitor listing
The source code wozmon.asm is part of a download package which can be downloaded from the downloads section. Here you see the entire listing of the Woz Monitor. I did my best to describe in detail what is actually happening in the program, although most of the remarks are the original remarks made by the Woz himself.
Now we're going to take a closer look under the bonnet of the Woz Monitor.
After studying it a bit closer you'll soon notice that Steve had to make every effort to squeeze his monitor in the tight 256 bytes memory space of ROM he had available.
Personally I have made some modifications to the Apple ]['s DOS system in the distant past.
There I had to squeeze some patches in the few bytes which were still free or could be freed by altering the existing code a little.
Therefore I can fully appreciate the efforts Steve has made to make it fit.
However all this squeezing came with a cost. I've listed some of the concessions Steve had to make in order to get the job done with only 256 bytes at his disposal.
- The Stack pointer is not initialized. This means that the stack can be all over the place in page $01. This is not really a problem if you use page $01 for stack purposes only. If you intend to put some code in page $01 you'd better initialize the stack pointer, otherwise the stack may overwrite your code without warning.
- The PIA is not properly initialized. It only works because the PIA is automatically set to Data Direction Mode after a Reset. Steve used this fact to set the Data Direction Mode without explicitly selecting the DDR registers. Thus initializing the PIA directly after a Reset is no problem. However you're not supposed to restart the system by calling address $FF00!
- Only upper case ASCII characters are accepted. Lower case characters are not recognized and are considered an error. Also bit b7 of every ASCII character is always set, whereas officially it should be cleared.
-
Error situations simply reset the input buffer, a back slash symbol is printed to indicate that an error has occurred and the cursor is dropped one line.
No error messages are output at all.
Obviously Steve didn't have resources enough for a complete human interface. -
The program is written in a top-down manner.
No problem for a processor of course, but it is harder to read and understand for us humans.
But who cares, it works!
Often results from one operation are recycled later in the program for completely unrelated purposes. This saves some bytes because certain registers already contain the proper value and don't have to be initialized again. Thus altering one part of the code may cause problems somewhere else in the program. -
The GETLINE routine only partially parses the input line.
Any input character below the ASCII value for '.' is regarded to be a blank.
This means that entering 00 01 02 03 is equal to 00!01#02,03 for instance.
Today a program like this would not be considered to be fool proof, but maybe we've got better fools today compared to '76.
Mind you, despite of all these concessions Steve managed to do it all in 254 bytes, 2 bytes of the ROM are still unused at the end.
Finally looking at the vector table at the end of the program teaches us that NMI handling should be done by code at address $0F00.
And IRQ handling is done by code starting at address $0000.
Per default both interrupt lines are not connected to any source.
Therefore you don't have to bother about these handling routines.
