KIM Uno: a DIY clone of the KIM-1
How to Use the KIM-1/KIM Uno
The KIM's monitor program is actually pretty user-friendly. That is, once you understand the basic ideas of Address and Data modes and the purpose of the PC button....
To start off the Quick Introduction below, shown below are the KIM-1 and KIM Uno keyboards. Following after that Quick Introduction, this page also describes some of the extra features in the KIM Uno, such as using the EEPROM memory space. Also, Disassembler and three small-but-important utility programs from the First Book of KIM are built in to the KIM Uno. Movit, Relocate and Branch are explained at the end of the page.
Handy to have at hand when programming the KIM: Instructions and their opcodes. Can be printed out to 6x9cm to fit the KIM Uno.
The KIM Uno with a 1976 vintage ADM 3A terminal - using a TTL serial to RS232 converter.
1. Quick Introduction to the KIM-1 ROM
To start, enter [AD] 0 2 0 0
Hitting [AD] puts you in Address Mode. In other words, you type 4 digits to select any address in the KIM's memory.
You now see that address 0x0200, which is where you normally start your user programs, holds the value A5. Search for $A5 on the chart to the left or on this page, which is a great way to learn 6502 coding. A5 is the code for LDA...
The Plus key just increases the memory address by one, so you can view the next byte. This way you can step through memory to look at it.
Now enter [DA] A5
[DA] puts you in Data Mode. Instead of your digits ending up to form an address, they now form an 8-bit value that can be stored in the memory address shown in the leftmost 4 hex digits. As you typed in A5, that'll overwrite the old value.
Hit [+] to go to the next memory address, enter two digits, save them with [+], two digits, [+]... this way you can quickly enter a program that you may have assembled on your PC or whatever. By the way, a good interactive, online assembler to quickly cook up code is here (link). Just write the assembler code, hit the Assemble button on the middle of the page, and start entering the byte codes at the bottom of the browser page into your KIM.
Hit the Arduino's small Reset button.
This is just for restoring the demo program that KIM Uno boots up with in 0x0200-0x0209, it might have been damaged by your tinkering just now. The stunning little demo program included at no extra cost in your KIM Uno is the very first program from the First Book of KIM. It swaps the value in 0x0010, which happens to be 0x10, with the value in 0x0011, which happens to be 0x11.
Enter [AD] 0010
Observe that address 0010 holds the value 10. Hit +. Notice 0011 holds the value 11. Hit 0200 to go back to 0200 again. You'll see 'A5' again.
The program runs and the address shown afterwards is 020A, which is the first byte after the program's end.
Press [AD] 0010
0010 now holds 11 instead of 10, and if you hit +, you'll see 0011 holds 10 instead of 11. Indeed: the values have been swapped by running the program.
Press the [SST] button (original KIM-1: slide the SST switch to the On position)
Type 0200 to go back there, you're still in Address mode.
Press [GO] and notice that only the first instruction is executed. The display now shows 0202 A6, which is the address and code of the following, second instruction (LDX).
But to further inspect the CPU state after the initial LDA instruction that you just executed, you can also explore the following memory locations. They hold a copy of the CPU registers after running that first instruction just now.So press [AD] 00F3 and see that the accumulator holds 0x10, etc. You can also edit these stored register values using the [DA] key.
00EF = Program counter Low byte 00F0 = Program counter High byte
00F1 = Status Register (P) 00F2 = Stack Pointer (SP)
00F3 = Accumulator (A)
00F4 = Y Index Register 00F5 = X Index Register
Press [PC]. This will show you the program counter is still at 0202, ready to execute the second instruction. Hit [GO] to execute it. Keep hitting [GO] until you are at program end (0208). Get out of SST mode by pressing [SST] (or set the slide switch to OFF on the original KIM-1)
Above, you've gone through the entire programming interface of the KIM. Congratulations, all you need to do now is memorise the 6502 instruction set in byte code, using this page to search for mnemonics and byte codes.
Or if you are limited in free brain memory, use this page as an assembler and type in the byte codes it generates for you.
You might still wonder about a few things:
you can stop your program using the [ST] key, where ST stands for STop your program and in the ROM source code, it stands for STart the monitor.
the [RS] key is a normal Reset button. Note that it will not erase memory, and in fact leave many other settings like they were before. But you enter the KIM Monitor this way if the [ST] key is not strong enough. By the way - [ST] triggers a NMI, and [RS] a RST signal to the 6502.
how to set break points like a debugger provides? Simple: enter value 00 (for the 6502's BRK instruction) in the address you want to generate a break point at. Do not forget to note down the original value in that byte, and put it back afterwards. Value 00 is the BRK instruction, and it drops you in the KIM Monitor just like Single-Step mode does. So inspect the CPU registers, change them as you like, and hit [GO] to continue. But remember you nuked an instruction by overwriting it with a BRK instruction. Real KIM Progammers used to enter spare NOP instructions at points where they thought they might like a break point for testing later on.
The above description assumes you are using the onboard LEDs and keyboard. If you use a serial terminal, the keystrokes are a bit different. Read the KIM-1 user manual below - and remember to have Caps Lock on at all times.
That's it. It used to be simple with computers, once upon a time! For further reference, read/use:
the KIM-1 User Manual
the First Book of KIM
Andrew Jacobs' 6502 Reference web page holds all 6502 mnemonics, their functions and byte codes in the best possible way. Use your browsers Search function to get around the page.
Mass:werk's online assembler gets you from assembler to byte code very fast. In case you do not know 6502 byte codes by heart and do not care to change that.
Using the cassette tape from the KIM-1 ROM
(Valid for the new 2020 firmware only)
The KIM Uno uses the 1K EEPROM inside the Arduino as a virtual cassette tape, you can save up to 5 files on your 1K of tape space. It works as the KIM-1 manual describes. You enter 5 bytes of data in the designated memory addresses, and run from address 1800 (for saving) or 1873 (for loading). Example:
17F5 <DA> D0 + 02 + E0 + 02 + 01 <AD> 1800 <GO>.
<-----> <-----> <> <------->
Start_Adddr End_Addr ID Run Save Routine
This will save the block from 02D0 up to 02E0 with a file ID (think 'file name') of 01.
Remember, <DA> is Ctrl-D, <AD> is Ctrl-A, and <GO> is Ctrl-G on the serial port.
For loading, all you need to do is enter the ID in address 17F9 and run 1873.
Because it is 2020 now, there are some extras:
1900 <GO> will print out a directory of the tape.
17F9 <DA> 32 <AD> 1901 <GO> will delete the file with ID=32
1902 <GO> will initialise/clear the tape. You have to do this before you do your first save!
In summary, here is the tape loading cheat sheet for the KIM Uno:
Enter these parameters first:
Start Address: 17F5 (SAL, low byte) 17F6 (SAH, high byte)
End Address: 17F7 (EAL, low byte) 17F8 (EAH, high byte)
File ID: 17F9
Original KIM-1 functions: Additional KIM Uno functions:
1800 <GO> -- save 1900 <GO> -- dir
1873 <GO> -- load 1901 <GO> -- del ID
1902 <GO> -- init
Caveats: I wrote the EEPROM file system, so I would not trust it with mission-critical data... Although using the EEPROM as a simulated cassette tape is very fast, you only have 1K of tape storage, and you can only save a maximum of 5 files on the tape.
The utility programs are taken from the First Book of KIM by Jim Butterfield. Read it online here, or download a PDF here.
Turn the KIM Uno into a clock with the mini program of ArduinoEnigma on Hackaday
2. Use the Eeprom as a nonvolatile 2nd 1K of RAM
The 1K EEPROM in the atMega is also mapped as a second K of RAM. So any access to addresses 0x400-0x7FF goes through to the EEPROM. You can use it as extra RAM memory (it will be a bit slower, but not noticeably so for most things), and it will save your work.
For writing to work, press the [RS] key for more than a second (or press '>' on the serial terminal) to toggle between R/O (default) and R/W Eeprom access. Write protection is useful because
although there's at least a hundred thousand write cycles in the Eeprom, you can wear it out. Theoretically.
this 1K of EEPROM has an alternative use: as emulated cassette tape storage (see above). In fact, you can inspect the data on the simulated cassette tape by just looking at addresses $400-7FF. This also means: either use the EEPROM as cassette tape, or as an extra 1K of RAM. Not both...
3. Utility: Movit
This is the first of three crucial utility programs from the famous First Book of KIM. It allows you to comfortably move sections of memory (for instance, 0200-0240 might contain your freshly developed program) to anywhere else (for instance, copy it to 0400-0440 where it will be saved into the eeprom. Do not forget to write-enable the eeprom by pressing ST for more than 1 second first).
At boot-up of the KIM Uno, movit is copied to the 64 bytes of RAM at $1780. You can overwrite it with your own code. It is also fully relocatable so you can move it anywhere. Movit is not a relocator - it does not adjust any adresses or jumps in the program you want to move. It just moves contents of a memory adress to another.
Enter original start adress of the program to move in $00D0 (LSB) and $00D1 (MSB),
Enter original end adress of the program to move in $00D2 (LSB) and $00D3 (MSB),
Enter new start adress of the program to move in $00D4 (LSB) and $00D5 (MSB),
and press 1780 [GO].
4. Utility: Relocate
Relocate complements movit: it adjusts those bits in your code that contain calling addresses and jumps that would otherwise be wrong when you move a program in memory. Relocate is not a trivial program. KIM Uno stores it at $0110. That means it lives in the stack space of the 6502, which is fine because the monitor ROM only uses 8 bytes of the whole stack page. But if you write huge programs, you might overwrite Relocate. Which is fine, it is not needed for anything else.
The following is quoted from Jim Butterfield, the author, in the First Book of KIM:
Ever long for an assembler? Remember when you wrote that 300 byte program - and discovered that you'd forgotten one vital instruction in the middle? And to make room, you'd have to change all those branches, all those address... RELOCATE will fix up all those addresses and branches for you, whether you're opening out a program to fit in an extra instruction, closing up space you don't need, or just moving the whole thing someplace else.
RELOCATE doesn't move the data. It just fixes up the addresses before you make the move. It won't touch zero page addresses; you'll want them to stay the same. And be careful: it won't warn you if a branch instruction goes out of range.
You'll have to give RELOCATE a lot of information about your program:
Where your program starts. This is the first instruction in your whole program (including the part that doesn't move). RELOCATE has to look through your whole program, instruction by instruction, correcting addresses and branches where necessary. Be sure your program is a continuous series of instructions (don't mix data in; RELOCATE will take a data value of 10 as a BEL instruction and try to correct the branch address), and place a dud instruction (FF) behind your last program instruction. This tells RELOCATE where to stop. Place the program start address in locations EA and EB, low order first as usual. Don't forget the FF behind the last instruction; it doesn't matter if you temporarily wipe out a byte of data - you can always put it back later.
Where relocation starts, this is the first address in your program that you want to move. If you're moving the whole program, it will be the same as the program start address, above. This address is called the boundary. Place the boundary address in locations EC and ED, low order first.
How far you will want to relocate information above the boundary. This value is called the increment. For example, if you want to open up three more locations in your program, the increment will be 0003. If you want to close up four addresses, the increment will be FFFC (effectively, a negative number). Place the increment value in locations E8 and E9, low order first.
A page limit, above which relocation should be disabled. For example, if you're working on a program in the 0200 to 03FF range, your program might also address a timer or I/O registers, and might call subroutines in the monitor. You don't want these addresses relocated, even though they are above the boundary! So your page limit would be 17, since these addresses are all over 1700. On the other hand, if you have memory expansion and your program is at address 2000 and up, your page limit will need to be much higher. You'd normally set the page limit to FF, the highest page in memory. Place the page limit in location E7.
Now you're ready to go. Set RELOCATE's start address , hit [GO] - and ZAP!-your addresses are fixed up. After the run, it's a good idea to check the address now in 00EA and 00EB - it should point at the FF at the end of your program, confirming that the run went OK. Now you can move the program. If you have lots of memory to spare, you can write a general MOVE program and link it in to RELOCATE, so as to do the whole job in one shot. [this is why movit is included]
Last note: the program terminates with a BRK instruction. Be sure your interrupt vector (at l7FE and 17FF) is set to KIM address 1C00 so that you get a valid "halt" [note: this is always done in the KIM Uno].
5. Utility: Branch
Branch is a small tool to calculate relative jumps. Start it through 01A5[GO]. Then, key in the last two digits of a branch instruction address; then the last two digits of the address to which you are branching; and read off the relative branch address.
Example: To calculate the branch value for a BEQ instruction located at $0226, needing to jump back to $0220: hit 26 (from 0226); 20 (from 0220) and read F8 on the two right hand digits of the display.
Keep in mind that the maximum "reach" of a branch instruction is 127 locations forward (7F) or 128 locations backward (80). If you want a forward branch, check that the calculated branch is In the range 0l to 7F. Similarly, be sure that a backward branch produces a value from 80 to FE. In either case, a value outside these limits means that your desired branch is out of reach.
The program must be stopped with the RS key.
6. Utility: Disassembler
2020 update: the disassembler has been replaced by the mini-assembler ($FDDD). You can still include the original disassembler as a firmware compile option, however. See the Apple-1 page for the mini-assembler.
Last but not least. Disassembler was written by Steve Wozniak and Allen Baum and published in the September 1976 edition of Dr. Dobbs. This KIM-1 port is from Bob Kurtz (1979) in 6502 User Notes #14. In 505 bytes, Baum and Wozniak were able to write a full disassembler... seriously vintage bytes.
Store the address from which you want to start disassembling in $00 (high byte, ie 02) and $01 (low byte, ie 00). Obviously, given that this outputs text, you will need to work from the serial terminal and be in serial mode (on the KIM Uno, press [TAB] to switch into that mode). Then enter 2000<space>G . The first 13 lines of disassembly roll by. Hit G again to continue.
7. Utility: Floating Point Library
The fltpt65 floating point package resides at $5000. See the 'How to use 6502 Calculator' page if you just want to use it as a (more or less) normal calculator. But you can also use this ROM in any KIM-1 program. To do so, load the operation (add, subtract, sin, cos, etc - see the Calculator page) in the A register and do a JSR $5000. Note that fltpt65 will use page 1 memory, erasing the relocate and branch programs. Should you want to use them afterwards, you need to press the reset button on the back of the Pro Mini.
8. Loading and saving programs to your PC
In serial mode (ie, Option 2, press [TAB] to go there), saving goes as follows: store the end address in 0x17F7 (upper byte, i.e. 02) and 0x17F8 (lower byte, i.e. FF). Now go to the address that is the starting address (0200 most likely). Press Q and a data file will be sent to the terminal. On the PC, you can then copy it, or capture it to a text file. For all the KIM knows, it has just created a paper tape... The command L allows you to upload a file into the KIM-1. Just press L, the KIM will wait for paper tape data so let your terminal program send the file. In Windows' HyperTerminal: Transfer->Send Text File. You may need to lower the speed at which the PC is sending bytes, HyperTerminal has a setting for that.
THE HURKLE IS HIDING ON A 10 BY 10 GRID. HOMEBASE ON THE GRID IS POINT 00 AND A GRIDPOINT IS ANY PAIR OF WHOLE NUMBERS. TRY TO GUESS THE HURKLE'S GRIDPOINT. YOU GET 5 GUESSES
230 ?="GUESS #";
250 ?=" ?";
320 ?="GO ";
450 ?="THAT'S 5 GUESSES"
460 ?="THE HURKLE IS AT ";
510 ?="LETS PLAY AGAIN."
520 ?="HURKLE IS HIDING"
540 ?="YOU FOUND HIM IN ";
560 ?=" GUESSES"
9. VTL-02 Interpreter
VTL-02 is a nifty little programming language - 1020 bytes of code gives you something close to Basic. Written in 1976 for the Altair 6800 by Frank McCoy and Gary Shannon, it was only recently ported to the 6502 by Mike, and then tuned by Klaus, on the 6502 forum (link). It counts as one of the top early microcomputer programming achievements.
Enter FC00 [GO], and on the serial terminal, the OK prompt appears.
Press [RS] to return to the KIM Monitor.
The VTL-02 manual is here (link). Keep in mind: #=1<return> starts your program. Check how many bytes of memory you still have by entering ?=*-& .
That matters, because only half a K of memory is available in the unexpanded KIM-1. You could add the KIM Uno's 2nd K of eeprom to that, but that would be cheating. See the VTL-02 manual on how to change the top memory nevertheless, but disable write protection first.
Tip: if you use TeraTerm (or another terminal program that has this feature), use its settings to add a 10ms pause after each character, and a 100ms pause after each CR. Now, you can copy & paste programs from your PC. Like the ones to the left and right.
10. Keyboard templates
The KIM Uno special keys:
Press [ST] for more than one second, and the write-protect on the eeprom is toggled on or off. On the serial terminal, this is the '>' key.
Press [SST] for more than one second, and you toggle in/out of Calculator Mode.
Which, as of September 1 2014, is a bad idea because you fall into test routines. But soon, you can then press C,D,E,F to view and edit the floating point registers of fltpt65. But that is another subject.
Click to enlarge picture.
Top line: the corresponding keypresses for special KIM Uno functions relating to Calculator Mode
Second line: the key functions within Microchess
Bottom line: corresponding keystrokes through the Serial port (using Option 3! For Option 2, please refer to the original KIM-1 User Manual). It may be handy to keep at hand.
Correction to picture: in Calculator Mode, A is decimal point, B is 'E' for 'Exponent'.