Sunday, April 17, 2016

Micro-KIM Tutorial: The Monitor Program

A simplified memory map of the Micro-KIM is shown below. This tutorial explores the 2K EPROM, leaving a more detailed exploration of the free RAM and 6532 RIOT for later. Address space $1400 to $173f is unused in the standard Micro-KIM kit configuration. 

  +-----------+
  | 2K EPROM  |$1fff
  | monitor   |
  | program   |$1800
  +-----------+
  | 6532 RIOT |$17ff
  | I/O, timer|
  | and RAM   |$1740
  +-----------+
  | optional  |$173f
  | I/O, timer|
  | and RAM   |$1400
  +-----------+
  |           |$13ff
  |  5K RAM   |
  |           |$0000
  +-----------+

Addresses $1800 through $1fff are taken by the 2K EPROM, which is a read-only memory area that stores the 6530-003 and 6530-002 parts of the monitor program. You can, of course, inspect all  individual bytes in the address mode on the Micro-KIM kit, but I recommend reading the assembly listing of the monitor program in the appendix of the Setup and User's Manual of Briel Computers. The compact coding style found in this monitor program is quite educational, but the monitor program also provides a rich set of subroutines that can be used in your own programs.

When you press the reset key RS on the kit (RST signal), the 6502 processor jumps to the address stored in $1ffc/$1ffd, which has the hard-coded value $1c22 in ROM. This is the entry labeled RST in the monitor program, i.e. the KIM entry via reset. Similarly, the non-maskable interrupt (NMI signal) and interrupt request (IRQ signal) jump to addresses stored in $1ffa/$1ffb and $1ffe/$1fff, respectively, with hard-codes values $1c1c and $1c1f in ROM. These are the entries labeled NMIT and IRQT in the monitor program, which contain indirect jump instructions to the vectors NMIV and IRQV stored in RAM at addresses $17fa/$17fb and $17fe/$17ff. Since these entries in RAM are undefined on power on, the User's Manual instructs you to fill these RAM locations with the value $1c00, so that the ST key or single-step feature (NMI) or BRK instruction (IRQ) jump into the entry labeled SAVE in the monitor program.

The JP2 jumper selects whether the monitor program should handle communication over the RS232 port (jumper on) or keypad/display on the kit (jumper off). Note that both the RS232 port and keypad/display always can be programmed to work regardless of this jumper state. But the jumper is connected with bit PA0 of data port A in the 6532 RIOT, which is tested in the monitor program to decide what action to perform next.

A very useful subroutine in the monitor program labeled SCANDS appears at address $1f1f. Even though these instructions are actually part of a larger subroutine that is used to show the addresses and data during normal operation of the kit, when calling this entry directly, the kit shows the three bytes stored consecutively in zero page addresses $f9, $fa, and $fb in hexadecimal format on the 6 digit LED display.

This routine makes writing a simple three-byte counter very easy, as shown below (you can also find this source file on my Micro-KIM webpage).

scands .equ $1f1f
       .org $0200
;
; Initialize a 3 byte counter to zero.
;
       lda #0
       sta $f9
       sta $fa
       sta $fb
;
; Display and increment the 3 byte counter in a loop.
; Displaying before each increment slows down counting
; quite a bit.
;
loop   jsr scands
       inc $f9
       bne loop
       inc $fa
       bne loop
       inc $fb
       jmp loop

Using the cross-assembler as shown in the previous tutorial yields the following paper tape output.

;180200A90085F985FA85FB201F1FE6F9D0F9E6FAD0F5E6FB4C08020F22
;0000010001

Uploading this to the kit and running looks as follows, counting up a 6 digit (three byte) hexadecimal number.

Slow counter on the Micro-KIM.
Although the lower digit goes faster than the eye can see, calling the display subroutine before each increment substantially slows down counting. A follow up tutorial looks at using interrupts for display, making the actual computation, counting in this case, much faster.

That's it for now. In the next tutorial, I am going to show how to use the 6532 RIOT to take full control of the LED display, show custom-made characters at any position, control brightness, and avoid flickering. As always, like, share, or comment if you enjoy the tutorial so far.

Saturday, April 16, 2016

Micro-KIM Tutorial: A First Assembly Program

At the lowest level, the 6502 executes numerical machine code. For example, the following bytes in hexadecimal format constitute a simple program that displays a single 8 on the LED display of the Micro-KIM.

  a9 ff 8d 40 17 a9 09 8d 42 17 4c 0a 02

Let's enter this program into the memory of the Micro-KIM. Power on the kit with jumper JP2 off and press the RS key. Then enter 0200 to set the address and press DA to go into data mode. Next, enter the numbers above pressing the + key after each number pair (so, enter A9 + FF + etc.). Before running, I strongly recommend checking the values. Use AD to go back into address mode. Press 0200 again and use + repeatedly to check all entered values. Once satisfied, press 0200 and GO. If all goes well, you will see a very bright 8 as first digit on the LED display (in later tutorials I will explain why).

Displaying a single digit on the Micro-KIM
Obviously constructing and entering programs this way is tedious and error-prone. It is much easier to program in assembly language, where statements still closely relate to machine instructions, but where an assembler takes care of translating instructions and addressing modes into the numeric equivalent as well as resolving symbolic names and evaluating simple expressions into actual values. For the Micro-KIM, one typically wants to use a cross-assembler, i.e., an assembler that runs on a host computer, such as a desktop or laptop, but generates machine code for a different target computer, in this case the Micro-KIM.

While reliving the good old days of my Commodore 64, I implemented a cross-assembler that runs on Windows (win2c64), Linux (lin2c64) and MacOS (mac2c64) and generates machine code for a 65xx-based microcomputer. This assembler supports several common output formats, including the paper tape format that can be directly uploaded to the Micro-KIM. Therefore, in this series, I will use win2c64 for assembly.

The assembly code for the program above looks as follows (note, if you are a bit rusty on the 6502, I recommend reading some online documentation on the instruction set first; more details on the assembler syntax and operation of win2c64 can be found in the online manual; details on the program itself will follow in later tutorials).

sad  .equ $1740
sbd  .equ $1742
     .org $0200         ; start program at $0200
     lda #$ff
     sta sad            ; set all bits of A data
     lda #9 
     sta sbd            ; set value 9 in B data
loop jmp loop           ; loop forever to avoid
                        ; returning to monitor program

To invoke the assembler and generate paper tape format, save this code in a source file, kim.s, and then run the following from the command line.

win2c64 -P kim.s

This generates an output file kim.ptf in textual paper tape format (there is also a binary variant, but that one is less useful for uploading over TTY). The contents of this file are shown below. These can be copied-and-pasted to the Micro-KIM through the terminal, as explained in the first tutorial. Much more convenient then entering a long list of numbers!


;0D0200A9FF8D4017A9098D42174C0A02048B
;0000010001

The win2c64 binary can also be used as disassembler on the generated output as follows.

win2c64 -dP kim.ptf

Which shows the addresses, numeric encoding and instructions as follows (note how the assembler has resolved and removed all the symbolic information and comments from the original source file).

$0200 a9 ff     lda #$ff
$0202 8d 40 17  sta $1740
$0205 a9 09     lda #$09
$0207 8d 42 17  sta $1742
$020a 4c 0a 02  jmp $020a

Just looking at the encoding, you may recognize the numbers you entered manually at the start of this tutorial.

Now that you have become more familiar with the tools, you are ready for the next tutorial, where I will explore using routines from the monitor program to show more numbers on the LED display in your assembly program. After that, I will explore taking full control of the LED display!

As before, if you like this series, please let me know by liking or sharing this posting, or leave a comment.

Friday, April 15, 2016

Micro-KIM Tutorial: Getting Started

Perhaps reminiscing the past is a sign of getting older, but I cannot help but look back fondly at the times I learned programming machine code on the Commodore 64 in the eighties. Therefore, it is probably no surprise I still occasionally enjoy programming 6502 on the Micro-KIM, which is a modern replica of the seventies KIM1 microcomputer, made available by the well-known retro computer kits provider Briel Computers.

In fact, I am having so much fun with this board, I decided to write a series of tutorials on operating and programming the Micro-KIM. In this series, I assume you have already some experience with the Micro-KIM and 6502 machine code, and have read the basic documentation that is shipped with the kit. Other than that, I hope to give additional information on various topics, such as developing assembly programs, programming the display, using the RS232 port or keypad, setting up timer-based interrupts, using a cross-assembler to generate programs in paper tape format, and uploading these to the kit.

Note that the original KIM1 featured a 6502 microprocessor, 1K of static RAM, two 6530 RRIOT IC's, and a 6 character hexadecimal LED diplay. Even though the Micro-KIM is a surprisingly accurate clone, it features a single 6532 RIOT, 2K EPROM for the monitor program, and 5K RAM. Please keep these differences in mind while reading the tutorial, since not all examples that work on the Micro-KIM will also work on the original KIM1.

Let's get started by uploading a simple demo to the Micro-KIM. In following tutorials, I plan to delve into the details of the demo itself. For now, I simply give the demo in paper tape format.

;180200A97F8D4117A93F8D4317A90A85E7A200A0098C4217BD4802094C
;1802188D4017203F02E8C8C8E007D0EDC6E7D0E5A200BD48029D470C82
;18023002E8E007D0F5AD47028D4E024C0A0298A0C888D0FDA860080B70
;0702480840014008080800F2
;0000040004

First, connect the Micro-KIM through a serial cable with your computer, make sure the jumper JP2 is in the ON position to enable RS232 input in the monitor program, and switch the kit on. Next, start a terminal program on your computer, such as HyperTerminal or PuTTY, which I assume you have set up already as described in the basic documentation. Last, press the RS key on the kit and hit ENTER in the terminal program. If all goes well, the Micro-KIM greets you with a prompt that looks something like this.

Micro-KIM Prompt
Then copy the paper tape format code above into the clipboard, press L in the terminal, and then paste from the clipboard. Again, if all goes well, eventually the Micro-KIM answers with the prompt again. Then press 0200 SPACE  and G to start the program. Alternatively, you can remove the jumper, press 0200 on the keypad on the kit and GO to start this program. Both ways will work for this particular demo, which looks as follows.

Wave Demo on the Micro-KIM
In the next tutorial, I will introduce cross-assemblers and start exploring how to program the display.

If you enjoy this series so far, please let me know by liking this posting. Or leave a comment. Suggestions for new topics are also welcome!

Sunday, April 10, 2016

Micro-KIM weekend

A rainy weekend was a perfect excuse to play with my micro-KIM, which had been collecting dust in a drawer for too long. I had fun using my own cross-assembler to develop and generate programs in paper tape format, and upload these to the micro-KIM via the PuTTY client.

I figured out how to use the 6532 RIOT to set up a timer-based interrupt service, which is an important step in separating actual computation from display and keypad handling. The following clip shows the difference between incrementing a three-byte memory counter at roughly 1000 times per second (timer delayed) and 100,000 times per second (full speed with about 10 cycles per iteration at 1MHz). Perhaps a nice illustration of how fast even those early computers were.


Saturday, March 19, 2016

New Buttons for Chess for Android

Not everyone was happy with the "swipe-up" to open the options menus (for devices that lack a menu button, or that broke the legacy options menu altogether), so I decided to simply implement an on-screen button instead. I also improved the graphics in the on-screen buttons for navigation, something that as long overdue.

The result is shown below. The right-most button with the horizontal lines opens the new-style options menu. As before, the other buttons are used for navigating the game, see the manual for details. On devices that still support a physical or virtual menu button (vertical dots in the screen-shot below), that button opens the legacy options menu.

Expect a similar update for Reversi and Checkers for Android soon too.