Trace C64 I/O Kernal Jump Table Calls

See what your C64 programs are up to!   Debug, or help transition from BASIC to assembly language I/O programming.

c64-io_monitor is a program that allows monitoring or tracing input/output calls on the Commodore 64.  It can show counts or a trace log of what calls have occurred.   

The screenshots show the initial copyright screen, with usage hints, and status (includes trace log bytes available), followed by an example program, and the counts and trace log from running this program.

Basic usage includes loading io_monitor program from disk at absolute address $C000.   It is recommended to lower BASIC by poking to memory address 56 (e.g. POKE 56, 128).  Then NEW to both clear variables and reset BASIC program pointers.  And use SYS 49152 to initialize the trace/monitor.

    LOAD "io?monitor",8,1
    POKE 56,128
    NEW
    SYS 49152 : REM START MONITOR

The monitor copies BASIC/KERNAL ROMs to RAM, patches them to hook the I/O entry points in the Commodore 64 kernal jump table at the end of ROM within the $FF00-$FFFF range.  The hooks take care of counting calls, and logging trace information in available RAM.  While each call is made, the border color is incremented to show it is working.

At this point, you may make any I/O calls including keyboard input (plus RETURN), screen output, disk/tape I/O, etc.   The I/O calls will be counted/logged.

When you are finished with the monitoring session, it is recommended to press STOP+RESTORE to reset back to the KERNAL ROMs, then the counts and tracing is turned off.

Counts can be displayed with SYS 49155, and the trace log can be displayed with SYS 49158.

The trace log can be sent to a file with statements like the following:

    OPEN 1,8,3,"@0:TESTLOG,S,W"
    CMD 1
    SYS 49155: REM COUNTS
    SYS 49158: REM VIEW LOG
    PRINT#1
    CLOSE 1

Why did I create this?  I have been developing some simple (text only) 6502 Commodore emulators (one, two, three, four, five) for multiple targets (web, Windows console/terminal, Linux terminal, Mac terminal, Arduino UART, ESP32 UART, Teensy LCD, STM32F4 LCD, and more embedded targets) and am looking at supporting file I/O emulation (open, input, get, print, close, etc.) above and beyond my D64 emulation.  One step along the way is understanding Commodore I/O some more from the machine language level.  Seeing a trace log provides a closer in-action view of the kernal I/O routines.

Links

The D64 disk image contains the machine code for io_monitor (also available as PRG), and some sample programs that can be used to demonstrate the functionality, including viewlog which opens and displays a sequential file (e.g. testlog saved to disk like above).  The source code posted to github is open source (MIT Licensed meaning free to use/alter/distribute, giving credit where credit is due, with no warranties).

Low Resolution Graphics for Commodore

Commodore systems come with a graphical character set that can be used for low resolution graphics.

PETSCII low resolution 80x50 example

All the Commodores include block patterned graphics that can be used to display 2x2 pattern blocks, to double both the horizontal and vertical text resolution, for example from 40x25 to 80x50.  Like 4K for the day!  

PETSCII block characters including inverted

In the back of our high school math classroom was an original PET 2001.   This system had a chicklet keyboard, built-in cassette drive, and 40 column white on black monochrome screen.  This system has no graphics modes beyond the PETSCII capabilities.

One of the exercises in my Algebra 2 class was to graph mathematically functions.  I successfully challenged myself back then to plot the graph on the PET using this block graphics method.

Using 8 PETSCII characters, and the inverse of those characters, all 16 combinations of the patterns can be achieved by setting (POKE) the correct value onto the screen (see the A array in the source).  Also achieved is reading (PEEK) the current PETSCII value, converting that into pixel data, and combining existing plotted pixels with a new pixel (see the B array in the source).

LORES PET 40COL listing

My handwritten PET listing from 1982

I found my handwritten program listing that dates back to 1982.  It's beautiful to see that graphics could be achieved with PETSCII with only a few lines of code.  From my positive experiences with the PET, I purchased a Commodore Vic-20, and the Super Expander later in 1983 and switched to high resolution graphics at that point.

A disk image (D64) of samples for PET/Vic-20/C64 is available.  Screen memory locations for PEEK/POKE are different for all the systems, and sizes are adjusted with variables for the 80 column PET, and 22 column Vic-20.  The Vic-20 and C64 also have color memory, so an additional POKE is included to match the current text foreground color (PEEK(646)).  Sorry, there is no port to Commodore 128 80 column screen as that would require additional handling for pushing values to the non-memory mapped VDC chip, and porting to the TED (C16, Plus/4) series systems is also left as an exercise for the reader.

Disk Listing for different Commodore Models

Vic-20 low resolution 44x46 plot

Contrast with 320x200 high resolution from C64

PET 80 column screen 160x50 sample

[Change:] 80 P=COS(I)*SIN(I)*2

C64 Emulator for Teensy 4.1 LCD/USB/SD(D64)

Here is my Teensy 4.1 on a breadboard pretending to be a Commodore 64.  USB keyboard, color text, background, border, and D64 (1541 image) support for LOAD/$/SAVE.  6502 emulation supports machine language, and Commodore 2.0 BASIC programs.   Sorry text only, no games, no graphics, no sound, no joysticks, just simple stuff for now.  But that simple stuff works! (mileage may vary, lightly tested, please try this at home under controlled conditions).

My Open source: https://github.com/davervw/c-simple-emu6502-cbm/tree/teensy_lcd

How to Build Vice 3.5 (x64sc, etc.) on Raspberry Pi 400

Raspberry Pi 400

The Raspberry Pi 400 invokes a sense of nostalgia back to the all-in-one systems of the past, such as those commonly available in the 80's (about 40 years ago!) of having the keyboard and computer all in one, with connections at the back of the enclosure, and expansion at the back of the enclosure.

My favorite system released January 1982 was the Commodore 64.

So why not have both?  With emulation, let the Raspberry Pi 400 become a Commodore 64 as well.

Vice 3.5 built, running on Raspian

One way to do this, is using Vice (the Versatile Commodore emulator).  Of course you can use a prepackaged solution like Retropie and Emulation Station.  But since it is open source, you can also just download and build the source yourself.

As vice 3.5 was just released Christmas Eve, 2020, it makes a lot of sense to build yourself, so you can have the latest build relatively easily.  Just think of all those new features!!!

I've attempted this myself on my Raspberry Pi 400 (and expect should work on others fine too) with Raspian.  I've tested with both the latest 32-bit ARM, and beta 64-bit ARM builds.

Following are the steps I took to accomplish building the default configuration.  I followed the basic instructions, and when configuration or build failed due to a dependency, researched the dependencies necessary (thanks Google and all those who have built before me and posted their solutions).  

Grab yourself your favorite beverage, power up your Pi, and get building!   And once you're done, feel free to test my hires.d64 image.  Maybe even pick up some keyboard stickers.   And also can run Pet, Vic-20, Commodore 128, etc.

Summary

1. Install dependency packages
2. Download three archives from web: vice 3.5, SDL2, SDL2_image
3. extract the archives to their respective directories
4. configure, build, and install each iteratively in the order: SDL2, SDL2_image, vice 3.5

Full Steps (note versions may change, these were the ones available January 2021):

• sudo apt-get install flex bison xa65 libgtk2.0-dev texinfo libxxf86vm-dev dos2unix libpulse-dev libasound2-dev
• sudo apt-get install texlive-latex-base texlive-fonts-recommended texlive-fonts-extra texlive-latex-extra 

• http://libsdl.org/download-2.0.php Download SDL2-2.0.14.tar.gz - GPG signed
• cd ~
• tar xvfz ~/Downloads/SDL2-2.0.14.tar.gz
• cd SDL2-2.0.14 
• ./configure
• make
• sudo make install

• https://www.libsdl.org/projects/SDL_image/ Download SDL2_image-2.0.5.tar.gz
• cd ~
• tar xvfz ~/Downloads/SDL2_image-2.0.5.tar.gz
• cd SDL2_image-2.0.5 
• ./configure
• make
• sudo make install

• https://vice-emu.sourceforge.io/ Download tarball: vice-3.5.tar.gz
• cd ~
• tar xvfz ~/Downloads/vice-3.5.tar.gz
• cd vice-3.5
• ./configure
• make
• sudo make install

Commodore 64 BASIC CRUNCH Routine Commented

The disassembled code here is from

Commodore 64 ROM.

The comments and intermediate labels

are mine.

Together they are useful.

Placing this here as is for reference.

I found this exercise necessary when

implementing my hires extensions for C64

including a patch of this routine.

        ; C64 crunch is A57C-A612

        ; C64 tokens are A09E-A19D

crunch ; from C64 ROM

       ; INPUT: PETASCII of entered line is at buffer $0200, ending with #$00 null character

       ; OUTPUT: tokenizes in place entire line, ending line with #$00 null character

       ; HINT: because of tokens, result is smaller than original so can modify in place

         LDX $7A        ; source buffer index

         LDY #$04       ; storage index starts at 4 (4+$1FB+1 = $200)

         STY $0F        ; set not DATA flag (4=NOT, 0=DATA)

.go      LDA $0200,X    ; retrieve next character from input buffer

         BPL .lowch     ; branch if 00-7F

         CMP #$FF       ; PI?

         BEQ .store     ; branch if PI, already tokenized

         INX            ; advance source index

         BNE .go        ; always skip initial character 80-FE, as X shouldn't ever wrap to 0

.lowch   CMP #$20       ; compare to ASCII space

         BEQ .store     ; branch if space, store literal

         STA $08        ; no, store character, non-zero = not REMark

         CMP #$22       ; compare to ASCII quote

         BEQ .literal   ; branch if string, store literal characters instead of matchng tokens

         BIT $0F        ; test if in DATA statement

         BVS .store     ; branch if in DATA statement, store literal characters instead of matching tokens

         CMP #$3F       ; compare to ASCII question mark

         BNE .chkzero   ; no, skip next part

         LDA #$99       ; replace question mark with token PRINT

         BNE .store     ; unconditional branch, store token

.chkzero CMP #$30       ; compare to ASCII zero digit

         BCC .scantbl   ; branch if less

         CMP #$3C       ; compare to ASCII less than

         BCC .store     ; branch if less, so branch if numeric or colon or semi-colon, store literal character

.scantbl STY $71        ; save storage offset index

         LDY #$00       ; initialize token table byte index to zero

         STY $0B        ; initialize token number to zero

         DEY            ; cancel out the next increment for loop beginning with decrement

         STX $7A        ; save source index

         DEX            ; cancel out the next increment for loop beginning with decrement

.advance INY            ; advance token table index

         INX            ; advance source index

.scanch  LDA $0200,X    ; retrieve character from buffer

         SEC            ; prepare for subtraction

         SBC $A09E,Y    ; compare to Commodore token table

         BEQ .advance   ; branch if character match, look for more matches

         CMP #$80       ; end of token?

         BNE .scannxt   ; branch if not end of token, mismatch, so get ready to check next token

         ORA $0B        ; match! combine zero based token number with $80 high bit set for storage

.storaty LDY $71        ; retrive storage offset index

.store   INX            ; advance input index

         INY            ; advance output index

         STA $01FB,Y    ; store token or character

         LDA $01FB,Y    ; set Z flag if end of line

         BEQ .endline   ; branch if end of line, finish up

         SEC            ; prepare for subtraction

         SBC #$3A       ; subtract ASCII colon

         BEQ .setf      ; branch if colon

         CMP #$49       ; DATA?

         BNE .skipset   ; skip setting flag if not DATA

.setf    STA $0F        ; $49 if DATA, or $00 if colon

.skipset SEC            ; prepare for subtraction

         SBC #$55       ; REM?

         BNE .go        ; branch if not REM to get next character

         STA $08        ; store flag zero = REM

.litloop LDA $0200,X    ; retrieve next character from input

         BEQ .store     ; branch if end of line

         CMP $08        ; compare to token that got us in this loop (e.g. 0x22 quote), or 0x00 (REM)

         BEQ .store     ; branch if REMark end of line

.literal INY            ; advance destination index

         STA $01FB,Y    ; store in buffer

         INX            ; advance source index

         BNE .litloop   ; repeat getting next character

.scannxt LDX $7A        ; retrieve source index

         INC $0B        ; advance token number

.endtok  INY            ; advance destination index

         LDA $A09D,Y    ; retrieve character from token table

         BPL .endtok    ; loop until find end of token

         LDA $A09E,Y    ; retrieve next character from token table

         BNE .scanch    ; branch if not end of token table

         LDA $0200,X    ; re-retrieve character from input buffer

         BPL .storaty   ; branch if character 00-7F, should be if got here, no token match

.endline STA $01FD,Y    ; store end of line nul character $00

         DEC $7B        ; update TXTPTR

         LDA #$FF       ;  to point to

         STA $7A        ;  $01FF

crunch_finish:

         RTS            ; done

Commodore 64 running in web browser

Open full size window: c64emu.davevw.com

• Coded in TypeScript(/JavaScript) with some HTML of course
• Portable (got a web browser right?)
• Keyboard driver works best with Firefox
• Works on Mobile and TV too (click on screen for configuration, help)
• F9 to toggle Help
• Recommend use wired or bluetooth keyboard instead of onscreen keyboard
• This is based on my earlier efforts (see previous posts)

I coded this as a learning experience with TypeScript.  Go ahead and try it out!

Included features:

✓ 6502 Emulation, machine code

✓ Commodore 64 Text Screen

✓ Commodore Fonts: Uppercase/Graphics, Lowercase/Uppercase

✓ Commodore Colors: Foreground, Background, Border

✓ Commodore BASIC v2 (Microsoft)

✓ 64K RAM

✓ 20K ROM

✓ Attach D64 image

✓ Load directory from D64

✓ Restart with PRG image

✓ JavaScript speedloader to bypass slow C64 disk access

✓ Save/Download PRG

✓ Great wired/wireless keyboard support

✓ Keyboard scan code support - press/release, multiple keys support, separate left/right Shift

✓ Standard to Commodore keyboard symbolic mapping, add/remove Shift

✓ Special key mappings: Stop, Home, Restore, F1-F8, Ctrl, Commodore

✓ Mobile/TV browser keyboard support (but minimal)

✓ Clipboard paste support

✓ IRQ 60 times per second

✓ NMI on Restore key

✓ Works best with Firefox

Missing features or limitations:

✗ 6502 undocumented instructions

✗ Accurate, regulated instruction timing

✗ 6502 emulation battery drain (one thread always running 100%, no idle sleep)

✗ VIC-II register support

✗ Device register support

✗ Programmable timers

✗ Serial Port - User Port

✗ High Resolution 320x200 and 160x200 graphics

✗ Multi-color text mode

✗ Programmable characters

✗ Sprites

✗ Cartridges

✗ Joysticks, Paddles

✗ Printer

✗ Cassette Tape

✗ Save to D64

✗ SEQ, RND, etc. files

✗ LOAD PRG from running program

✗ Positional keyboard mapping

✗ On-screen keyboard

✗ Clipboard copy

✗ A few graphic character key strokes (punctuation keys) may not be mapped yet

✗ Known issues with Google Chrome

Commodore 64 for STM32F429 Discovery board

So here is a Commodore 64 emulator I built for STM32F429 Discovery board:

Yeah, the LCD is tiny at 2.4", and the emulation runs about 15% slower than an NTSC C64.  But it's running on a small embedded board that's available for under $30 US (DigiKey, Mouser, ...) including mounted LCD display and USB OTG jack.  Just add keyboard, OTG USB adapter, and power supply.

This is a port of my portable C64/6502 emulator for terminal console, which was a port of my Commodore/6502 emulator for Windows Console.   But this time, I dropped the console part, and went for real video (LCD) and USB keyboard support.   Hello PETSCII!

Keyboard mapping (showing my Dell keyboard):

   STOP(ESC) F1 F2 F3 F4 F5 F6 F7 F8            Restore(PrtScr/SysRq) Run/Stop(Pause/Break)

             1! 2@ 3# 4$ 5% 6^ 7& 8* 9( 0) -_ += Del/Ins(Back)    Ins Hme/Clr     / * -

   Ctrl(Tab) Q  W  E  R  T  Y  U  I  O  P  [  ]  £ (\)            Del           7 8 9 +

             A  S  D  F  G  H  J  K  L  ;: '" Return(ENTER)                     4 5 6

   LShift    Z  X  C  V  B  N  M  ,< .> /?  RShift                     Up       1 2 3

   C=(Ctrl)           SPACEBAR              C=(Ctrl)              Lft Down Rt   0 .   Enter

Features:

• 320x200 text screen on graphics LCD, with top/bottom border.
• USB Keyboard (e.g. PC-103) support (symbolic, not positional)
• Tab maps to C64 Ctrl key
• Ctlr maps to C64 Commodore key
• Esc key maps to C64 RUN/STOP key
• PrtScr/SysRq maps to C64 RESTORE key (supports STOP+RESTORE)
• PgUp also maps to C64 RESTORE key
• Full 6502 emulation.  Go ahead, run some machine language on it.
• Commodore character set
• Text video at $0400 (address 1024)
• Text color at $D800 (address 55296)
• Keyboard scan by writing to $DC00, reading from $DC01
• Full 64K RAM.  Update 2020-04-14: RAM/ROM/IO/Charset banking is implemented!  And 1K color nybbles
• 1/60 second IRQ.  So we've got the software clock: TI, TI$
• Upper/lower case switch ($D018), and reverse characters.
• Border color ($D020) and background color ($D021).

Limitations:

• Approximately 85% cpu speed of a real C64
• No NMI.  No Restore key.  Update 2020-04-15: implemented, see keyboard above.
• No other device support.  No tape, no disk, no serial, no cartridges, no joysticks, no printer.
• VIC-II support is limited to getting system booted.
• No full register support.
• Text address can't be moved.
• No graphics support.
• No programmable characters.
• No raster interrupts.
• No sprites.
• No left/right side border displayed.  Ran out of pixels.
• No CIA1/CIA2 (except for keyboard data ports, but no data direction registers)
• No SID.
• In progress.  There are bugs lurking (for example, the IRQ and USB keyboard stops working exactly at 35 minutes, 38 seconds from start, maybe a resource leak in third party libraries, so we'll call that time limited I guess)
• Keyboard support may need tweaks for more complete PETSCII key support
• No CAPS LOCK or SHIFT LOCK supported
• Doesn't utilize full capabilities of the STM32F429 MCU and discovery board components including 2.0MB of Flash (uses 110KB), 256KB of RAM (uses 83KB), 8MB SDRAM, motion sensor, user leds, user button, or other expansion capabilities.  Opportunity awaits!

Links:

• Source on mbed.com (utilizes MBED OS, MBED USBHOST, ST429 BSP)
• Terminal Console related C64/6502 emulator source on github.com
• Binary firmware (yes you can flash and try right now if you have the hardware)
• ST-Link Utility (flash utility for STM32, programmer built into discovery board)
• STM32F429x Datasheet
• STM32F429IDISCOVERY resources at st.com

Credit:  

• Something similar has been done before (but not source related).  See hackaday.com.
• Thanks to STMicroelectronics for the cool development board!