Part 1. General (My notes on the Commodore 64)

             _____ _             ____ __   _  _
            |_   _| |__   ___   / ___/ /_ | || |
              | | | '_ \ / _ \ | |  | '_ \| || |_
              | | | | | |  __/ | |__| (_) |__   _|
              |_| |_| |_|\___|  \____\___/   |_|
__        __    _ _    _   _                           _
\ \      / /_ _| | | _| |_| |__  _ __ ___  _   _  __ _| |__
 \ \ /\ / / _` | | |/ / __| '_ \| '__/ _ \| | | |/ _` | '_ \
  \ V  V / (_| | |   <| |_| | | | | | (_) | |_| | (_| | | | |
   \_/\_/ \__,_|_|_|\_\\__|_| |_|_|  \___/ \__,_|\__, |_| |_|
                                                 |___/

              Personal notes from "MeneerJansen"
               PM me via www.lemon64.com/forum
          The most recent version of this text file
        can be found on: https://pastebin.com/hmpJmurr



o==========o
| CONTENTS |
o==========o

P A R T  1 :  G E N E R A L

  pastebin.com/hmpJmurr

  A. Introduction

  B. Recommended literature

  X. References


P A R T  2 :  M E M O R Y  M A P  O F  T H E  C 6 4

  pastebin.com/XjwVy4pD

  A. General table

  B. How RAM is used by CPU and VIC

  C. VIC memory banks
     1. General
     2. Bank positions in RAM
     3. Character ROM access

  D. I/O memory map

  X. References


P A R T  3 :  T H E  V I C  C H I P

  pastebin.com/wsY1zDmY

  A. Memory banks (reprise)

  B. RAM, ROM, CPU and VIC
     1. RAM vs. CPU/VIC access
     2. CPU: switch between I/O and char ROM
     3. I/O memory map
     4. The 47 VIC registers

  C. Memory types
     1a. Character (generator) ROM
     1b. Character memory/RAM (replacement for ROM)
     2.  Bitmap
     3.  Screen RAM/scr mem/video matrix/vid RAM (char position)
     4.  Color RAM (char color)
     5.  Bank config examples

  D. Discussion

  E. Bug

  X. References


P A R T  4 :  D I S P L A Y  M O D E S

  pastebin.com/tjPEr8Bq

  A. Introduction

  B. Standard text mode

  C. Bitmap single color

  D. Bitmap multicolor

  E. Multicolor text mode

  F. ECM text mode

  X. References


P A R T  5 :  S P R I T E S

  pastebin.com/MAWHB9Xg

  A. Activate & define

  B. Position

  C. Position beyond 255

  D. Expand sprites

  E. Collision detection

  F. Multicolor

  Y. Registers

  X. References


P A R T  6 .  T H E  S I D  C H I P

  pastebin.com/MZvuRWw5

  A. Introduction
     1. General
     2. Music
     3. Samples

  B. SID models

  C. Input/output
     1. How to play
     2. Use voice 3 as modulator

  X. References


P A R T  7 :  S O M E  A S S E M B L Y  N O T E S

  pastebin.com/PLvNc6tD

  A. Some mnemonics

  B. RAM locations

  C. Masking

  D. Self modifying code

  E. Error codes

  F. Writing under Kernal ROM bug

  G. Indirect indexed addressing

  Z. All opcodes

  Y. Tips

  X. References


P A R T  8 .  T U R B O  M A C R O  P R O

  pastebin.com/w8VCLbEx

  A. TMP with and without a REU
     1. General
     2. Memory map

  B. Status line & tips 'n hints
     1. Status line
     2. Tips/hints

  C. A REU in general

  D. BASIC ROM shadowing

  E. The jump from 140_hex

  F. TMP: REU banks and RAM
     1. General
     2. TMP's four states

  G. Appendix: Set colors for TMP

  X. References



A P P E N D I X  A :  U S E  C U S T O M  F O N T S

  pastebin.com/Ac9E82MF

  A. General
     1. Procedure
     2. Example using VIC bank 0
     3. Example using VIC bank 2
     4. Example using VIC bank 3

  B. BASIC

  C. Assembly

  X. References


A P P E N D I X  B :  P E T S C I I

  pastebin.com/EE826WT7

  A. Character ROM (reprise)

  B. PETSCII

  X. References


A P E N D I X  C :  F I L E  M A N A G E M E N T

  pastebin.com/KWh5aXcr

  A. General

  B. When channel is still open

  X. References


A P E N D I X  D :  S C A N  L I N E S

  pastebin.com/Xd2inZjv

  A. Scan lines

  B. Raster time

  C. Bad line

  D. Some calculations

  X. References


      -<>-<>-<>-<>-<>-<>-<>-





             .---------------------------.
            ( P A R T  1 .  G E N E R A L )
             `---------------------------´


o=================o
| A. Introduction |
o=================o

These are my personal notes (text files) that I referred to when I was trying to learn something about Assembly programming for the Commodore 64. To me it's like a walkthrough of a game. Hence the name of this collection of text files: "The C64 Walkthrough".

Programming "anything graphical" on the C64 is very, very complex. One does not only have to master a programming language (like BASIC or Assembly) but also has to have quite the deep understanding of the C64's inner workings as well as it's use of memory addresses (i.e. the memory map). For example, to print a single character on screen in Assembly one has to store the hexadecimal value of a letter character to memory address FFD2_hex. One also has to realize that this address is part of the kernal (yes, that is spelled the correct Commodore way) and not of the graphic chip. Even if one uses BASIC then one falls back to POKE-ing values into memory addresses very soon, which is the same as LDA- and STA-ing values in Assembly.

The real art is to not go down the rabbit hole too much and to collect "just" the right amount of books, websites and tutorials.

You also *ABSOLUTELY NEED* to keep reference books and manuals handy. One can only use the text files that I wrote with the programmers reference guide [1], a good memory map [2, 4], a book on Assembly language [3] and the manual from the SID chip [6].

What you already need to know (roughly) if you want to read these docs (use Google and Wikipedia):

    - Decimal, hexadecimal and binary number systems.
    - Bits and bytes, what is an address, nybble.
    - The terms ROM and RAM.
    - What is clock frequency.
    - What is a sprite.
    - The C64's CPU is the MOS 6510 (compatible w/ the 6502).
    - The C64's graphics chip is the VIC-II.
    - CIA  = complex input/output adapter.
    - CIA1 = keyboard, joystick, paddles, datasette, IRQ control.
    - CIA2 = serial bus, RS-232, VIC memory, NMI control.
    - Basic programming skills in BASIC (poke, peek, print).
    - MSB = most significant bit, LSB = ..., low byte, high byte.
    - What is Character ROM (4 kB), kernal ROM (8 kB), BASIC ROM (8 kB).
    - Address bus (16 bit), memory bus (8 bit).
    - Petscii codes.
    - What the term "machine language" means.


o============================o
| B.  Recommended literature |
o============================o

The books "The Programmers reference guide" [1] and "Mapping the C64" [2] are written very well. However, I consider them to be reference-books, not study books. Another reference that one must always keep handy is the "HTML version of the memory map" [4]. I converted it into a PDF file for easy reading.

Most people recommend reading the brilliant book "Machine language for the C64" by the brilliant Jim Butterfield to learn Assembly. However, like the book's title says, it's mainly about machine language: it uses a machine language monitor (MLM) to program Assembly. Additionally, it has no chapters about the most important and expensive feature of the C64: graphics & sprites. So I read [3]. That one is quite complex at some points and uses BASIC to explain graphics. Therefore it looks to me like the author was struggling a bit w/ Assembly himself and was coming from BASIC. I read those books to learn the basics of Assembly. I didn't read them thoroughly: they're not focused enough on Assembly to learn how games were programmed.

Goal was to be able to read and understand something like the extensive set of tutorials by Georg Rottensteiner (https://www.georg-rottensteiner.de/en/index.html) or the book "Retro game dev - C64 edition" by Derek Morris (www.retrogamedev.com).


o===============o
| X. References |
o===============o

[1] "C64 programmer's reference guide", Commodore Business Machines and Howard W. Sams and Co. publ., First ed. second printing (1983).

[2] "Mapping the C64", Sheldon Leemon, Compute! Publications Inc., ISBN 0-942386-23-X (1984).

[3] "Commodore 64/128 Assembly language programming", Mark Andrews, Howard W. Sams & Co. publ., ISBN 0-672-22244-5, First ed. (1986).
    Bombjack download link:
    https://commodore.bombjack.org/books/commodore/books/Commodore_64_128_Assembly_Language_Programming.zip

[4] HTML C64 memory map by Joe Forster:
    https://sta.c64.org/cbm64mem.html

[5] "Machine language for the C64, 128, and other Commodore computers", Jim Butterfield, Prentice Hall publ., ISBN 0-89303-652-8 (1986).

[6] Data sheet from the 6582 (click on: "Files"):
    http://sid.kubarth.com

[7] "Programming the C64 the definitive guide", Raetro Collin West, Compute! Publications Inc., ISBN 0-942386-50-7 (1985).

[8] Bombjack:
    https://commodore.bombjack.org/commodore/books.htm