Category Archives: 6502

Fully Commented Commodore 64 BASIC ROM Disassembly – based on Microsoft’s Source

On my quest of collecting as many commentaries on the Commodore 64 ROM at pagetable.com/c64rom, we have gathered Lee Davison’s excellent commentary, the German de facto standard by Data Becker, and an adaptation of Bob Sander-Cederlof’s Apple II ROM commentary, all in the same cross-referenced HTML format.

Now that Microsoft’s original source of MOS 6502 BASIC is available, I’ve added it as the fourth commented disassembly, with the standard disassembly on the left, and the original source, both assembly and comments, lined up correctly on the right:

As always, the HTML version is available at pagetable.com/c64rom, while the raw txt files are maintained at github.com/mist64/c64rom.

While this may be the best set of comments for the BASIC part, we’re not done yet! There are many more (either direct or indirect) commentaries on the C64 ROM in existence:

Please contribute to our collection by helping convert one or more of these sources into the common format! Send me an email if you are interested!

Microsoft BASIC for 6502 Original Source Code [1978]

This is the original 1978 source code of Microsoft BASIC for 6502 with all original comments, documentation and easter eggs:

M6502.MAC (1978-07-27, 6955 lines, 161,685 bytes)

This is currently the oldest publicly available piece of source written by Bill Gates.

Language

Like the 8080 version, the 6502 version was developed on a PDP-10, using the MACRO-10 assembler. A set of macros developed by Paul Allen allowed MACRO-10 to understand and translate 6502 assembly, albeit in a modified format to fit the syntax of macros, for example:

MOS 6502 MACRO-10
LDA #0 LDAI 0
LDA (ADDR),Y LDADY ADDR

MACRO-10 did not support hex numbers, which is why most numbers are in decimal format. In the floating point code, all numbers are octal. The RADIX statement switches between the two. Octal can also be forced with a ^O prefix.

Conditional translation is done using the IFE and IFN statements, which test whether the argument is zero. The following only adds the string to the binary if REALIO is equal to 4:

IFE     REALIO-4,<DT"APPLE BASIC V1.1">

Macros

The source defines many macros that make development easier. There are some examples:

Macro Definition Comment
SYNCHK (Q) LDAI <Q>
JSR SYNCHR
Get the next character and make sure it’s Q, otherwise SYNTAX ERROR. This pattern is used a lot.
LDWD (WD) LDA WD
LDY <WD>+1
Most 16 bit constants are loaded into A/Y with this macro, but macros for A/X and X/Y also exist.
LDWDI (WD) LDAI <<WD>&^O377>
LDYI <<WD>/^O400>
This loads an immediate constant into A/Y.
PSHWD (WD) LDA <WD>+1
PHA
LDA WD
PHA
This pushes a 16 bit value from memory (absolute or zero page) onto the stack.
JEQ (WD) BNE .+5
JMP WD
A compact way to express out-of-bounds branches. Macros exist for all branches.
SKIP2 XWD ^O1000,^O054 This emits a byte value of 0x2C (BIT absolute), which skips the next instruction. (The ^O1000 part wraps the byte in a PDP-10 instruction – see below.)

Configurations

The BASIC source supports several compile-time configuration options:

Name Comment Description
INTPRC INTEGER ARRAYS
ADDPRC FOR ADDITIONAL PRECISION 40 bit (9 digit) vs 32 bit (7 digit) float
LNGERR LONG ERROR MESSAGES Error message strings instead of two-character codes
TIME CAPABILITY TO SET AND READ A CLK TI and TI$ support
EXTIO EXTERNAL I/O PRINT#, INPUT#, CMD, SYS (!), OPEN and CLOSE support
DISKO SAVE AND LOAD COMMANDS LOAD, SAVE (and on Commodore: VERIFY) support
NULCMD FOR THE "NULL" COMMAND NULL support, a command to configure the number of NUL characters to print to the terminal after each line break
GETCMD GET support
RORSW If 1, the ROR instruction is not used
ROMSW TELLS IF THIS IS ON ROM The RAM version can optionally jetison the SIN, COS, TAN and ATN commands at startup
CLMWID Column width for TAB()
LONGI LONG INITIALIZATION SWITCH
STKEND The top of stack at startup
BUFPAG Page of the input buffer; if 0, the buffer uses parts of the zero page
BUFLEN INPUT BUFFER SIZE
LINLEN TERMINAL LINE LENGTH
ROMLOC ADDRESS OF START OF PURE SEGMENT
KIMROM KIM-specific smaller config

Targets

The constant REALIO is used to configure what computer system to generate the binary for. It has one of the following values:

Value Comment Banner Machine
0 PDP-10 SIMULATING 6502 SIMULATED BASIC FOR THE 6502 V1.1 Paul Allen’s Simulator on PDP-10
1 MOS TECH,KIM KIM BASIC V1.1 MOS KIM-1
2 OSI OSI 6502 BASIC VERSION 1.1 OSI Model 500
3 COMMODORE ### COMMODORE BASIC ### Commodore PET 2001
4 APPLE APPLE BASIC V1.1 Apple II
5 STM STM BASIC V1.1 (unreleased)

All versions except Commodore also print “COPYRIGHT 1978 MICROSOFT” in a new line.

The target defines the setting of the configuration constants, but some code is also conditionally compiled depending on a specific target.

What is interesting is that initially it was Microsoft adapting their source for the different computers, instead of giving source to the different vendors and having them adapt it. Features like file I/O and time support seem to have been specifically developed for Commodore, for example. Later, the computer companies would get the source from Microsoft and develop themselves – source code of the Apple and Commodore derivatives is available; they both contain Microsoft comments.

By the way, the numbering of these targets probably indicated in which order Microsoft signed contracts with computer manufacturers. MOS was first (for the KIM), then OSI, then Commodore/MOS again (this time for the PET), then Apple.

The PDP-10 Target

Paul Allen’s additional macros for 6502 development made the MACRO-10 assembler output one 36 bit PDP-10 instruction word for every 6502 byte. When targeting a real 6502 machine, the 6502 binary could be created by simply extracting one byte from every PDP-10 word.

In the case of targeting the simulator, the code created by the assembler could just be run without modification, since every emitted PDP-10 instruction was constructed so that it would trap – the linked-in simulator would then extract the 6502 opcode from the instruction and emulate the 6502 behavior.

While this trick was mostly abstracted by the (unreleased) macro package, its workings can be seen in a few cases in the BASIC source. Here, it defines SKIP1 and SKIP2. Instead of just emitting 0×24 or 0x2C, respectively, it combines it with the octal value of 01000 to make it a PDP-10 instruction that traps:

DEFINE  SKIP1,  <XWD ^O1000,^O044>      ;BIT ZERO PAGE TRICK.
DEFINE  SKIP2,  <XWD ^O1000,^O054>      ;BIT ABS TRICK.

In the initialization code, it writes a JMP instruction into RAM. On the simulator, it has to patch up the opcode of JMP (0x4C, decimal 76) to be the correct PDP-10 instruction:

        LDAI    76              ;JMP INSTRUCTION.
IFE     REALIO,<HRLI 1,^O1000>  ;MAKE AN INST.

With this information, we can reconstruct what the set of 6502 macros, which is not part of this source, probably looked like. Here is LDAI (LDA immediate):

DEFINE  LDAI    (Q),<
        XWD ^O1000,^O251        ;EMIT OPCODE
        XWD ^O1000,<Q>          ;EMIT OPERAND
>

You can also see native TJSR PDP-10 assembly instructions for character I/O:

IFE     REALIO,<
        TJSR    INSIM##>        ;GET A CHARACTER FROM SIMULATOR
IFE     REALIO,<
        TJSR    OUTSIM##>       ;CALL SIMULATOR OUTPUT ROUTINE

The DDT command, which breaks into the PDP-10′s DDT debugger, only exists in this config:

IFE     REALIO,<
DDT:    PLA                     ;GET RID OF NEWSTT RETURN.
        PLA
        HRRZ    14,.JBDDT##
        JRST    0(14)>

The KIM and OSI Targets

The KIM target is meant for the MOS KIM-1 and Ohio Scientific OSI Model 500 single-board computers. These are the first ports to specific computers, and also the cleanest, i.e. except for the character I/O interface and the very simple LOAD/SAVE implementation for the KIM, there is nothing specific about these targets.

The Commodore Target

The Commodore target is meant for the Commodore PET 2001. It includes LOAD/SAVE/VERIFY (the commands jump directly to outside “KERNAL” ROM code), the I/O commands (SYS, PRINT#, OPEN etc.), the GET command and the π, ST, TI and TI$ symbols. CLEAR is renamed to CLR, "OK" is renamed to "READY.", the BEL character is not printed, and character I/O code behaves differently to account for the more featureful screen editor of the PET.

Oh, and the Commodore version of course includes the Bill Gates WAIT 6502,1 easter egg! This is the WAIT instruction:

; THE WAIT LOCATION,MASK1,MASK2 STATEMENT WAITS UNTIL THE CONTENTS
; OF LOCATION IS NONZERO WHEN XORED WITH MASK2
; AND THEN ANDED WITH MASK1. IF MASK2 IS NOT PRESENT, IT
; IS ASSUMED TO BE ZERO.

FNWAIT: JSR     GETNUM
        STX     ANDMSK
        LDXI    0
        JSR     CHRGOT
        BEQ     ZSTORDO
        JSR     COMBYT          ;GET MASK2.
STORDO: STX     EORMSK
        LDYI    0
WAITER: LDADY   POKER
        EOR     EORMSK
        AND     ANDMSK
        BEQ     WAITER
ZERRTS: RTS                     ;GOT A NONZERO.

Note how the BEQ instruction references ZSTORDO, not STORDO – execution sneaks out of this function here.

Well, on non-Commodore machines, ZSTORDO is assigned to be the same as STORDO, so everything is fine:

IFN     REALIO-3,<ZSTORDO=STORDO>

But on Commodore, we have this code hidden near the top of the floating point math package – close enough so the BEQ can reach it, but inside code that is least likely to get touched:

IFE     REALIO-3,<
ZSTORD:!        LDA     POKER
        CMPI    146
        BNE     STORDO
        LDA     POKER+1
        SBCI    31
        BNE     STORDO
        STA     POKER
        TAY
        LDAI    200
        STA     POKER+1
MRCHKR: LDXI    12
IF1,<
MRCHR:  LDA     60000,X,>
IF2,<
MRCHR:  LDA     SINCON+36,X,>
        ANDI    77
        STADY   POKER
        INY
        BNE     PKINC
        INC     POKER+1
PKINC:  DEX
        BNE     MRCHR
        DEC     ANDMSK
        BNE     MRCHKR
        RTS
IF2,<PURGE ZSTORD>>

(IF1 and IF2 are true on the first and the second assembler pass, respectively, so the conditional there is to hint to the assembler in the first pass that SINCON+36 is not a zero page address. Also note that all numbers here are octal, since this code is in the floating point package.)

First of all, the final line here removes ZSTORD from the list of symbols after the second pass, so that Commodore would not notice it in a printout of all symbols – very smart!

As has been discussed before, this code writes the string “MICROSOFT!” into the PET’s screen RAM if the argument to WAIT is “6502″. The encoded string is hidden as two extra 40 bit floating point numbers appended to the coefficients used by the SIN function:

IFN     ADDPRC,<
SINCON: 5               ;DEGREE-1.
        204     ; -14.381383816
        346
        032
        055
        033
        206     ; 42.07777095
        050
        007
        373
        370
        207     ; -76.704133676
        231
        150
        211
        001
        207     ; 81.605223690
        043
        065
        337
        341
        206     ; -41.34170209
        245
        135
        347
        050
        203     ; 6.2831853070
        111
        017
        332
        242
        241     ; 7.2362932E7
        124
        106
        217
        23
        217     ; 73276.2515
        122
        103
        211
        315>

These last ten bytes, nicely disguised as octal values of floating point constants, spell out “MICROSOFT!” backwards after clearing the upper two bits. What’s interesting is that the floating point values next to them are actually incorrect: They should be 7.12278788E9 and 26913.7691 instead.

Also note that these constants are not conditionally assembled! All versions built since the Commodore easter egg was introduced also contained these 10 bytes – including BASIC for the Motorola 6800!

The Apple Target

The Apple target is meant for the Apple II, and contains no customizations other than some changes around I/O handling (which calls into the monitor ROM). Note that this is not yet the “AppleSoft” version of BASIC, which was a more customized version modified by Apple later.

The STM Target

“STM” most likely stands for “Semi-Tech Microelectronics” – a company that never shipped a 6502-based computer. Their first machine was the “Pied Piper”, a Z80-based system, and they later made a PC clone. It seems they had a 6502-based computer in development that never shipped – or at least they were considering making one, and Microsoft added the target; this target doesn’t actually change any of the defaults.

Organization of the Source

The source uses the PAGE and SUBTTL keywords for organization. Here are the headings:

SUBTTL  SWITCHES,MACROS.
SUBTTL  INTRODUCTION AND COMPILATION PARAMETERS.
SUBTTL  SOME EXPLANATION.
SUBTTL  PAGE ZERO.
SUBTTL  RAM CODE.
SUBTTL  DISPATCH TABLES, RESERVED WORDS, AND ERROR TEXTS.
SUBTTL  GENERAL STORAGE MANAGEMENT ROUTINES.
SUBTTL  ERROR HANDLER, READY, TERMINAL INPUT, COMPACTIFY, NEW, REINIT.
SUBTTL  THE "LIST" COMMAND.
SUBTTL  THE "FOR" STATEMENT.
SUBTTL  NEW STATEMENT FETCHER.
SUBTTL  RESTORE,STOP,END,CONTINUE,NULL,CLEAR.
SUBTTL  LOAD AND SAVE SUBROUTINES.
SUBTTL  RUN,GOTO,GOSUB,RETURN.
SUBTTL  "IF ... THEN" CODE.
SUBTTL  "ON ... GO TO ..." CODE.
SUBTTL  LINGET -- READ A LINE NUMBER INTO LINNUM
SUBTTL  "LET" CODE.
SUBTTL  PRINT CODE.
SUBTTL  INPUT AND READ CODE.
SUBTTL  THE NEXT CODE IS THE "NEXT CODE"
SUBTTL  DIMENSION AND VARIABLE SEARCHING.
SUBTTL  MULTIPLE DIMENSION CODE.
SUBTTL  INTEGER ARITHMETIC ROUTINES.
SUBTTL  FRE FUNCTION AND INTEGER TO FLOATING ROUTINES.
SUBTTL  SIMPLE-USER-DEFINED-FUNCTION CODE.
SUBTTL  STRING FUNCTIONS.
SUBTTL  PEEK, POKE, AND FNWAIT.
SUBTTL  FLOATING POINT ADDITION AND SUBTRACTION.
SUBTTL  NATURAL LOG FUNCTION.
SUBTTL  FLOATING MULTIPLICATION AND DIVISION.
SUBTTL  FLOATING POINT MOVEMENT ROUTINES.
SUBTTL  SIGN, SGN, FLOAT, NEG, ABS.
SUBTTL  COMPARE TWO NUMBERS.
SUBTTL  GREATEST INTEGER FUNCTION.
SUBTTL  FLOATING POINT INPUT ROUTINE.
SUBTTL  FLOATING POINT OUTPUT ROUTINE.
SUBTTL  EXPONENTIATION AND SQUARE ROOT FUNCTION.
SUBTTL  EXPONENTIATION FUNCTION.
SUBTTL  POLYNOMIAL EVALUATOR AND THE RANDOM NUMBER GENERATOR.
SUBTTL  SINE, COSINE AND TANGENT FUNCTIONS.
SUBTTL  ARCTANGENT FUNCTION.
SUBTTL  SYSTEM INITIALIZATION CODE.

Paul Allen vs. Bill Gates

The source of the 8080 version states:

PAUL ALLEN WROTE THE NON-RUNTIME STUFF.
BILL GATES WROTE THE RUNTIME STUFF.
MONTE DAVIDOFF WROTE THE MATH PACKAGE.

People have since wondered what runtime vs. non-runtime meant, especially since Paul Allen’s recent debate on whether the company’s ownership was faily split.

The BASIC for 6502 source sheds some light on this:

NON-RUNTIME STUFF
        THE CODE TO INPUT A LINE, CRUNCH IT, GIVE ERRORS,
        FIND A SPECIFIC LINE IN THE PROGRAM,
        PERFORM A "NEW", "CLEAR", AND "LIST" ARE
        ALL IN THIS AREA. [...]

So by “runtime” they just literally mean “at run time”: all code that is active when the program runs, as opposed to non-runtime, which is all code that assists editing the program.

By this understanding, we can assume this:

  • Paul Allen wrote the macro package for the MACRO-10 assembler, the 6502 simulator, the tokenizer, the detokenizer, as well as finding, inserting and deleting BASIC lines.
  • Bill Gates implemented all BASIC statements, functions, operators, expression evaluation, stack management for FOR and GOSUB, the memory manager, as well as the array and string library.
  • Monte Davidoff wrote the floating point math package.

Version and Date

The last entry in the change log has a date of 1978-07-27. Both the comment in the first line of the file and the message printed at startup call it version 1.1.

What does this say about the version of the source? Is it the last version? Let’s look at the last bug fix and compare which BASIC binaries contain this fix, and let’s see whether there are fixes in BASIC binaries that are not in the source.

I have previously compared binaries of derivatives of BASIC for 6502 and compiled the information at github.com/mist64/msbasic. The last entry in the log of this source is about a bug that failed to correctly invalidate a pointer in the RETURN statement. According to my analysis of BASIC 6502 versions, this is fixed in the BASIC binaries for AIM-65, SYM-1, Commodore v2, KBD BASIC and MicroTAN, i.e. on everything my previous analysis calls CONFIG_2A and higher.

The same analysis also came to the conclusion that there were two successors, CONFIG_2B and CONFIG_2C. At least the two CONFIG_2B fixes exist in two BASIC binaries: KBD BASIC and MicroTAN, but they don’t exist in this source. It’s very unlikely that both these bugs (and only these!) got fixed by the two computer manufacturers independently, so it’s safe to assume that this source is not the final version – but pretty close to it!

Interesting Finds

  • This code is comparing a keyboard input character to the BEL code. Bob Albrecht is a computer educator that “was instrumental in helping bring about a public-domain version of Basic (called Tiny Basic) for early microcomputers.”.
    CMPI    7               ;IS IT BOB ALBRECHT RINGING THE BELL
                            ;FOR SCHOOL KIDS?
    
  • External documentation usually calls the conversion of ASCII BASIC text into the compressed format “tokenizing”. The source calls this “crunching”.
  • Microsoft is still spelled “Micro-Soft”.
  • Apparently the multiplication function could use some performance improvements:
    		
    BNE     MLTPL2          ;SLOW AS A TURTLE !
    
  • The NEW command is actually called SCRATCH in labels and comments – maybe other BASIC dialects called it that, and they decided to rename it to NEW later?
  • The math package documentation says:
    MATH PACKAGE
            THE MATH PACKAGE CONTAINS FLOATING INPUT (FIN),
            FLOATING OUTPUT (FOUT), FLOATING COMPARE (FCOMP)
            ... AND ALL THE NUMERIC OPERATORS AND FUNCTIONS.
            THE FORMATS, CONVENTIONS AND ENTRY POINTS ARE ALL
            DESCRIBED IN THE MATH PACKAGE ITSELF.
    

    Commodore’s derived source changes this to:

    ; MATH PACKAGE
    ;       THE MATH PACKAGE CONTAINS FLOATING INPUT FIN, OUTPUT
    ;       FOUT, COMPARE FCOMP...AND ALL THE NUMERIC OPERATORS
    ;       AND FUNCTIONS.  THE FORMATS, CONVENTIONS AND ENTRY
    ;       POINTS ARE ALL DESCRIBED IN THE MATH PACKAGE ITSELF.
    ;       (HA,HA...)
    
  • CHRGET is a central piece of BASIC for 6502. Here it is in its entirety:
    ; THIS CODE GETS CHANGED THROUGHOUT EXECUTION.
    ; IT IS MADE TO BE FAST THIS WAY.
    ; ALSO, [X] AND [Y] ARE NOT DISTURBED
    ;
    ; "CHRGET" USING [TXTPTR] AS THE CURRENT TEXT PNTR
    ; FETCHES A NEW CHARACTER INTO ACCA AFTER INCREMENTING [TXTPTR]
    ; AND SETS CONDITION CODES ACCORDING TO WHAT'S IN ACCA.
    ;       NOT C=  NUMERIC   ("0" THRU "9")
    ;       Z=      ":" OR END-OF-LINE (A NULL)
    ;
    ; [ACCA] = NEW CHAR.
    ; [TXTPTR]=[TXTPTR]+1
    ;
    ; THE FOLLOWING EXISTS IN ROM IF ROM EXISTS AND IS LOADED
    ; DOWN HERE BY INIT. OTHERWISE IT IS JUST LOADED INTO THIS
    ; RAM LIKE ALL THE REST OF RAM IS LOADED.
    ;
    CHRGET: INC     CHRGET+7        ;INCREMENT THE WHOLE TXTPTR.
            BNE     CHRGOT
            INC     CHRGET+8
    CHRGOT: LDA     60000           ;A LOAD WITH AN EXT ADDR.
    TXTPTR= CHRGOT+1
            CMPI    " "             ;SKIP SPACES.
            BEQ     CHRGET
    QNUM:   CMPI    ":"             ;IS IT A ":"?
            BCS     CHRRTS          ;IT IS .GE. ":"
            SEC
            SBCI    "0"             ;ALL CHARS .GT. "9" HAVE RET'D SO
            SEC
            SBCI    256-"0"         ;SEE IF NUMERIC.
                                    ;TURN CARRY ON IF NUMERIC.
                                    ;ALSO, SETZ IF NULL.
    CHRRTS: RTS                     ;RETURN TO CALLER.
    

    Did you ever wonder why all versions have $EA60 encoded into the LDA instruction that later gets overwritten? Because it’s 60000 decimal. That’s why! The source actually uses 60000 as a placeholder for 16 bit values in several places.

  • The handling of π, ST, TI and TI$ (all Commodore-specific) looks wonky: Instead of making them tokens, they are special cased in several places. I always assumed it was Commodore adding this without understanding (or wanting to disrupt) the existing code, but it was Microsoft adding these features. Maybe they were added by someone other than the original developers?

Origin of the File

The source was posted on the Korean-language blog 6502.tistory.com without further comment, in a marked-up format:

================================================================================================
FILE: "david mac g5 b:m6502.asm"
================================================================================================

000001  TITLE   BASIC M6502 8K VER 1.1 BY MICRO-SOFT
[...]
006955          END     $Z+START

End of File -- Lines: 6955 Characters: 154740

SUMMARY:

  Total number of files : 1
  Total file lines      : 6955
  Total file characters : 154740

This formatting was created by an unpublished tool by David T. Craig, who published a lot of Apple-related soure code (Apple II, Apple III, Lisa) in this format in as early as 1993, first anonymously, later with his name).

The filename “david mac g5 b:m6502.asm” (disk name “david mac g5 b”, file name “m6502.asm”, since it was a classic Mac OS tool) confirms David Craig’s involvement, and it means the line numbers were added no earlier than 2003.

Given all this, it is safe to assume the file with the Microsoft BASIC for 6502 source originated at Apple, and was given to David Craig together with the other source be published.

The version I posted is a reconstruction of the original file, with the header, the footer and the line numbers removed, and the spaces converted back into tabs. I chose the name “M6502.MAC” to be consistent with the MACRO-10 file extension used by the Microsoft BASIC for 8080 sources.

Fully Commented Commodore 64 BASIC ROM Disassembly – based on Applesoft!

In our series about C64 ROM commentaries (English version by Lee Davison, German version by Data Becker), I’m now presenting a most unusual C64 ROM commentary – based on a commented disassembly of the Apple II ROM.

S-C DocuMentor for Applesoft” is a commented disassembly of the BASIC ROM of the Apple II computer. Like Commodore BASIC, “Applesoft” BASIC is based on Microsoft BASIC for 6502, but on an older revision. Since the two BASIC interpreters are almost the same instruction for instruction (modulo some command extensions on both sides), the commentary translated over very nicely.

The cross-referenced HTML version of the “S-C C64 BASIC Disassembly” is available here at pagetable.com/c64rom.

The raw txt files of all commentaries are maintained at github.com/mist64/c64rom. Fixes and additions happily accepted!

Fully Commented Commodore 64 ROM Disassembly (English)

After last week’s German C64 ROM disassembly from the “64 intern” book, I have now also converted Lee Davison’s commented disassembly into the same format.

The cross-referenced HTML version is available here at pagetable.com/c64rom.

The raw txt files of both the German and the English commented disassemblies are maintained at github.com/mist64/c64rom. The two files seem to have been independently developed, which gives us the opportunity to compare, find mistakes, and merge missing information.

I will happily accept additions and corrections to either file – let’s create the one true source of C64 ROM information!

Fully Commented Commodore 64 ROM Disassembly (German)

Whenever I need to look up some code in the ROM of the Commodore 64, I have the choice of the commented disassembly by Marko Mäkelä, the one by Ninja/The Dreams, or the one by Lee Davison – or I can just use my paper copy of “Das neue Commodore-64-intern-Buch“, an excellent line-by-line commentary in German.

That’s why I scanned, OCRed, cleaned up and cross-referenced it.

The raw txt file is maintained at github.com/mist64/c64rom. Corrections, additions and translations welcome.

The cross-referenced HTML version is available here at pagetable.com/c64rom.

Clockslide: How to waste an exact number of clock cycles on the 6502

by Sven Oliver ‘SvOlli’ Moll; the original German language version has been simultaneously posted on his blog.

This is an article about the 6502 processor about the topic: how to “waste” a number of clock cycles stated in a register, in this case the X register. The principle is simple: you have a number of operations that do close to nothing. The more the code is jumped to at the “front”, the more clock cycles are needed to get to the actual code. If the code is jumped to more at the “end”, the CPU gets to the code in question more quickly.

This nice theory won’t work directly on the 6502, because every instruction takes at least two clock cycles to execute. If you want to get it down to the precision of one cycle, this is getting more difficult. The first half of this trick I found in code of Eckhard Stollberg, who is one of the guys that pionieered homebrew on the Atari 2600 VCS. There, I found some strange bytes:

C9 C9 C9 C9 C9 C9 C9 C9 C9 C9 C9 C9 C5 EA

The disassembly looks like this:

; CODE1
CMP #$C9 ; 2
CMP #$C9 ; 2
CMP #$C9 ; 2
CMP #$C9 ; 2
CMP #$C9 ; 2
CMP #$C9 ; 2
CMP $EA  ; 3

To run through the code, you’ll need 15 clock cycles, and nothing changes except for some state registers. If the code is called with an offset of one byte, this code will be processed:

; CODE2
CMP #$C9 ; 2
CMP #$C9 ; 2
CMP #$C9 ; 2
CMP #$C9 ; 2
CMP #$C9 ; 2
CMP #$C5 ; 2
NOP      ; 2

This makes 14 clock cycles, and only the status register will be changed. If the code is called with an offset of two bytes, it is started at the CODE1 segment at the second instruction. Add another one, you’ll get to the second instruction of the CODE2 segment, and so on. This way it is possible to specify the exact number of clock cycles to be “wasted”. With on exception: to be more specific there are 2 + X clock cycles that are wasted. There is no way to waste exactly one clock cycle.

Now we need a way to specify the “entry” of our “slide”. On a C=64 this would be done using self-modifying code. The operand of a JMP $XXXX instruction will be replaced with the calculated address. This is not possible on systems like the Atari 2600, since the code is run in ROM. One option for example would be to use JMP ($0080) after writing the entry point to $0080 and $0081.

My approach differs a bit from the usual way. RAM is scarce on the Atari, and I don’t want to “waste” up two of the 128 bytes available, when there is another way. When the CPU executes a JSR $XXXX (jump to subroutine) command, it writes the current address to the stack. To be more specific, it is the address of the JSR command + 2 which is the return address – 1. And this is what I do: I write my entry point – 1 to the stack and use the command RTS (return from subroutine) to jump into the clock slide. So, I’m still using two bytes of RAM, but only for a short time, without the need to evaluate which two bytes are available at this point.

; the X register specifies how many of the
; 15 clock cycles possible should be skipped
LDA #>clockslide
PHA
TXA
CLC
ADC #<clockslide
PHA
STA WSYNC ; <= this syncs to start of next scanline
clockslide:
RTS
CMP #$C9
CMP #$C9
CMP #$C9
CMP #$C9
CMP #$C9
CMP #$C9
CMP $EA
realcode:
; and here the real code continues

This approach still has one problem: between “clockslide” and “realcode”, no page crossing may occur. If this were the case, I’d have to increase the high byte on the stack by one. But since the position of the code segments is under my control, I left this out as an exercise for the reader. ;-)

The story of 15 Second Copy for the C-64

by Mike Pall, published with permission.

[This is a follow-up to Thomas Tempelmann’s Story of FCopy for the C-64.]

Ok, I have to make a confession … more than 25 years late:

I’ve reverse-engineered Thomas Tempelmann’s code, added various improvements and spread them around. I guess I’m at least partially responsible for the slew of fast-loaders, fast-copys etc. that circulated in the German C64 scene and beyond. Uh, oh …

I’ve only published AFLG (auto-fast-loader-generator) under my real name in the German “RUN” magazine. It owes quite a bit to TT’s original ideas. I guess I have to apologize to Thomas for not giving proper credit. But back then in the 80′s, intellectual property matters wasn’t exactly something a kid like me was overly concerned with.

Later on, everyone was soldering parallel-transfer cables to the VIA #1 of the 1541 and plugging them into the C64 userport. This provided extra bandwidth compared to the standard serial cable. It allowed much faster loading of programs with a tiny parallel loader (a file named “!”, that was prepended on all disks). Note that the commercial kits with cables, custom EPROMs and silly dongles followed only much later.

So I wrote “15 second copy”, which worked with a plain parallel cable. Yes, it copied a full 35 track disk in 15 seconds! There was only one down-side: this was only the time for reading/writing from and to disk — you had to swap the floppies seven times (!) and that usually took quite a bit more extra time! ;-)

It worked by transferring the “live” GCR-encoded data from the 1541′s disk head to the C64 and simultaneously doing a fast checksum. Part of the checksumming was done on the 1541, part was done on the C64. There simply weren’t enough cycles left on either side! Most of the transfer happened asynchronously by adjusting for the slightly different CPU frequencies and with only a minimum number of handshakes. This meant meticulous cycle counting and use of some odd tricks.

The raw GCR took up more space (684*324 bytes) in the C64 RAM, so that’s why it required 4 passes. Other copy programs fully decoded the GCR and required only 3 passes. But GCR decoding was rather time-consuming, so they had to skip some sectors and read every track multiple times. OTOH my program was able to read/write at the full 300rpm, i.e. 5 tracks per second plus stepper time, which boils down to 2x ~7.5 seconds for read and write. Yep, you had to swap the floppies every 2 seconds …

Ok, so I spread the program. For free. I even made a 40 track version, which took 17 seconds. Only to see these coming back in various mutations, with the original credits ripped out, decorated with multiple intros, different groups pretending they wrote it or cracked it (it was free, there was nothing to crack!). The only thing they left alone were the copy routines, probably because they were extremely fragile and hard to understand. So it was really easy to recognize my own code. Some of the commercial parallel-cable + ROM kits even bragged with “Backups in 15 seconds!”. These were blatant rip-offs: they basically changed the screen colors and added a check for their dongles. Duh.

Let’s just say this rather frustrating experience taught me a lot and that’s why I’m doing open source today.

So I shelved my plans to write an enhanced version which would try to compress the memory to reduce the number of passes. Ah, yes … I wrote quite a few packers, too … but I’ll save that story for another time.

I still have the disks with the source code somewhere in my basement. But I’m not so sure I’ll be able to read them anymore. They weren’t of high quality to begin with … and I’d have to find my homegrown toolchain, too. ;-)

But I took the time to reverse-engineer my own code from one of the copies that are floating around on the net. For better understanding on the C64/1541 handshake issues, refer to this article. If you’re wondering about the weird bvc * loops: the 6502 CPU of the 1541 has an SO pin, which is triggered by a full shift register for the data from the disk head. This directly sets the overflow flag in the CPU and allows reading the contents from the shift register with very low latency.

Yes, there’s a lot more weird code in there. For the sake of brevity, here are only the inner loops of the I/O routines for the read, write and verify pass for the C64 and the 1541 side. Enjoy!

  ;--- 1541: Read ---
  ldy #$20
f_read:
  bvc *        ; Wait for disk shift register to fill
  clv
  lda $1c01    ; Load data from disk
  sta $1801    ; Send byte to C64 via parallel cable
  inc $1800    ; Toggle serial pin
  eor $80      ; Compute checksum for 1st GCR byte in $80
  sta $80
  bvc *
  clv
  lda $1c01    ; Load data from disk
  sta $1801    ; Send byte to C64 via parallel cable
  dec $1800    ; Toggle serial pin
  eor $81      ; Compute checksum for 2nd GCR byte in $81
  sta $81
  ; ...
  ; Copy and checksum to $82 $83 $84
  ; And another time for $80 $81 $82 $83 $84 with inverted toggles
  ; ...
  dey
  beq f_read_end
  jmp f_read
f_read_end:
  ; Copy the remaining 4 bytes and checksum to $80 $81 $82
  ; Lots of bit-shifting and xoring to indirectly verify
  ; the sector checksum from the 5 byte xor of the raw GCR data

  ;--- C64: Read ---
  ; Setup ($5d) and ($5f) to point to GCR buffer
  ldy #$00
c_read:
  bit $dd00    ; Wait for serial pin to toggle
  bpl *-3
  lda $dd01    ; Read incoming data (from 1541)
  sta ($5d),y  ; Store to buffer
  iny
  bit $dd00    ; Wait for serial pin to toggle
  bmi *-3
  lda $dd01    ; Read incoming data (from 1541)
  sta ($5d),y  ; Store to buffer
  iny
  bne c_read
c_read2:
  bit $dd00    ; Wait for serial pin to toggle
  bpl *-3
  lda $dd01    ; Read incoming data (from 1541)
  sta ($5d),y  ; Store to buffer
  iny
  bit $dd00    ; Wait for serial pin to toggle
  bmi *-3
  lda $dd01    ; Read incoming data (from 1541)
  sta ($5d),y  ; Store to buffer
  iny
  cpy #$44
  bne c_read2

  ;--- C64: Write ---
  ; Setup ($5d) and ($5f) to point to GCR buffer
  ldy #$00
  tya
c_write:
  eor ($5d),y  ; Load from buffer and compute checksum
  bit $dd00    ; Wait for serial pin to toggle
  bpl *-3
  sta $dd01    ; Store xor'ed outgoing data (to 1541)
  iny
  eor ($5d),y  ; Load from buffer and compute checksum
  bit $dd00    ; Wait for serial pin to toggle
  bmi *-3
  sta $dd01    ; Store xor'ed outgoing data (to 1541)
  iny
  bne c_write
c_write2:
  eor ($5f),y  ; Load from buffer and compute checksum
  bit $dd00    ; Wait for serial pin to toggle
  bpl *-3
  sta $dd01    ; Store xor'ed outgoing data (to 1541)
  iny
  eor ($5f),y  ; Load from buffer and compute checksum
  bit $dd00    ; Wait for serial pin to toggle
  bmi *-3
  sta $dd01    ; Store xor'ed outgoing data (to 1541)
  iny
  cpy #$44
  bne c_write2
  ldx $5b
  sta $0200,x  ; Store checksum for verify pass
  inx
  stx $5b

  ;--- 1541: Write ---
  ldy #$a2
  lda #$00
f_write:
  bvc *        ; Wait for disk shift register to clear
  clv
  eor $1801    ; Xor with incoming data (from C64)
  sta $1c01    ; Write data to disk shift register
  dec $1800    ; Toggle serial pin
  lda $1801    ; Reload data to undo xor for next byte
  bvc *        ; Wait for disk shift register to clear
  clv
  eor $1801    ; Xor with incoming data (from C64)
  sta $1c01    ; Write data to disk shift register
  inc $1800    ; Toggle serial pin
  lda $1801    ; Reload data to undo xor for next byte
  dey
  bne f_write

  ;--- 1541: Verify ---
  ; Get checksum computed by c_write on the C64 side
  ldy #$a2
f_verify:
  bvc *        ; Wait for disk shift register to fill
  clv
  eor $1c01    ; Xor with data from disk
  bvc *        ; Wait for disk shift register to fill
  clv
  eor $1c01    ; Xor with data from disk
  dey
  bne f_verify
  ; Verify is ok if checksum is zero

The story of FCopy for the C-64

by Thomas Tempelmann, reprinted with permission.

Back in the 80s, the Commodore C-64 had an intelligent floppy drive, the 1541, i.e. an external unit that had its own CPU and everything.

The C-64 would send commands to the drive which in turn would then execute them on its own, reading files, and such, then send the data to the C-64, all over a propriatory serial cable.

The manual for the 1541 mentioned, besides the commands for reading and writing files, that one would read and write to its internal memory space. Even more exciting was that one could download 6502 code into the drive’s memory and have it executed there.

This got me hooked and I wanted to play with that – execute code on the drive. Of course, there was no documention on what code could be executed there, and which functions it could use.

A friend of mine had written a disassembler in BASIC, and so I read out all its ROM contents, which was 16KB of 6502 CPU code, and tried to understand what it does. The OS on the drive was quite amazing and advanced IMO – it had a kind of task management, with commands being sent from the communication unit to the disk I/O task handler.

I learned enough to understand how to use the disk I/O commands to read/write sectors of the disk. Actually, having read the Apple ][‘s DOS 3.3 book which explained all of the workings of its disk format and algos in much detail, was a big help in understanding it all.

(I later learned that I could have also found reverse-eng’d info on the more 4032/4016 disk drives for the “business” Commodore models which worked quite much the same as the 1541, but that was not available to me as a rather disconnected hobby programmer at that time.)

Most importantly, I also learnt how the serial comms worked. I realized that the serial comms, using 4 lines, two for data, two for handshake, was programmed very inefficiently, all in software (though done properly, using classic serial handshaking).

Thus I managed to write a much faster comms routine, where I made fixed timing assumptions, using both the data and the handshake line for data transmission.

Now I was able to read and write sectors, and also transmit data faster than ever before.

Of course, it would have been great if one could simply load some code into the drive which speeds up the comms, and then use the normal commands to read a file, which in turn would use the faster comms. This was not possible, though, as the OS on the drive did not provide any hooks for that (mind that all of the OS was in ROM, unmodifiable).

Hence I was wondering how I could turn my exciting findings into a useful application.

Having been a programmer for a while already, dealing with data loss all the time (music tapes and floppy disks were not very realiable back then), I thought: Backup!

So I wrote a backup program which could duplicate a floppy disk in never-before seen speed: The first version did copy an entire 170 KB disk in only 8 minutes (yes, minutes), the second version did it even in about 4.5 minutes. Whereas the apps before mine took over 25 minutes. (Mind you, the Apple ][, which had its disk OS running on the Apple directly, with fast parallel data access, did this all in a minute or so).

And so FCopy for the C-64 was born.

It became soon extremely popular. Not as a backup program as I had intended it, but as the primary choice for anyone wanting to copy games and other software for their friends.

Turned out that a simplification in my code, which would simply skip unreadable sectors, writing a sector with a bad CRC to the copy, did circumvent most of the then-used copy protection schemes, making it possible to copy most formerly uncopyable disks.

I had tried to sell my app and sold it actually 70 times. When it got advertised in the magazines, claiming it would copy a disk in less than 5 minutes, customers would call and not believe it, “knowing better” that it can’t be done, yet giving it a try.

Not much later, others started to reverse engineer my app, and optimize it, making the comms even faster, leading to copy apps that did it even in 1.5 minutes. Faster was hardly possible, because, due to the limited amount of memory available on the 1541 and the C-64, you had to swap disks several times in the single disk drive to copy all 170 KB of its contents.

In the end, FCopy and its optimized successors were probably the most-popular software ever on the C-64 in the 80s. And even though it didn’t pay off financially for me, it still made me proud, and I learned a lot about reverse-engineering, futility of copy protection and how stardom feels. (Actually, Jim Butterfield, an editor for a C-64 magazine in Canada, told its readers my story, and soon he had a cheque for about 1000 CA$ for me – collected by the magazine from many grateful users sending 5$-cheques, which was a big bunch of money back then for me.)

Chaosradio Express #177: Commodore 64

(This article is about a German-language podcast episode on the C64.)

Im Februar hat mich Tim Pritlove auf der Durchreise in Frankfurt abgefangen, wo ich mit einem Koffer voll mit zwölf Commodore 64 Motherboards in einem Hotelzimmer saß, und mit mir eine 2 Stunden und 42 Minuten lange Episode für Chaosradio Express aufgenommen.

Chaosradio Express #177: Commodore 64

Hier also nochmal der Hinweis auf die Folge, die jetzt schon ein paar Monate zurückliegt, für all diejenigen, die sie nicht schon anderweitig entdeckt haben. :-)

Inside Commodore DOS [PDF]


Richard Immers and Gerald G. Neufeld:
Inside Commodore DOS : the complete guide to the 1541 disk operating system.
Northridge, Calif. : Datamost, 1985.
ISBN 0-8359-3091-2

(512 pages, 7.4 MB PDF)

In my quest to preserve retrocomputing documents, here is the invaluable book “Inside Commodore DOS”, which describes most of the internals of the Commodore 1541 disk drive. The scanning was done in 2002 by Kenneth S. Moore, who in 2005 released an OCRed version, which unfortunately replaced the original page images. My version here comes with the original page images and a table of contents, and is nevertheless fully searchable.

Here is a fun quote from the book by the way:

Over the years numerous writers have advised Commodore owners not to use the save and replace command because it contained a bug. Our study of the ROM routines and a lot of testing has convinced us that the bug in the replace command is a myth.

Of course, this is wrong. Don’t use “SAVE@” on a 1541.