COMMODORE 128

PROGRAMMER'S
REFERENCE GUIDE

Bantam Computer Books

Ask your bookseller for the books you have missed
THE AMIGADOS MANUAL
by Commodore-Amiga, Inc.
THE APPLE //c BOOK
by Bill O'Brien
THE ART OF DESKTOP
PUBLISHING
By Tony Bove, Cheryl Rhodes,
and Wes Thomas
ARTIFICIAL INTELLIGENCE
ENTERS THE MARKETPLACE
by Larry R. Harris and
Dwight B. Davis

HOW TO GET THE MOST OUT OF

COMPUSERVE, 2d ed.
by Charles Bowen and David Peyton
HOW TO GET THE MOST OUT OF THE
SOURCE
by Charles Bowen and David Peyton
THE MACINTOSH
by Bill O'Brien
MACINTOSH C PRIMER PLUS
by The Waite Group/Stephen W. Prata
THE NEW jr. A GUIDE TO IBM'S PCjr
by Winn L. Rosch

THE BIG TIP BOOK FOR

THE APPLE II SERIES
by Bert Kersey and
Bill Sanders

ORCHESTRATING SYMPHONY
by The Waite Group/Dan Shafer with
Mary Johnson

THE COMMODORE 64 SURVIVAL

MANUAL
by Winn L. Rosch

PC-DOS/MS-DOS
User's Guide to the Most Popular Operating
System for Personal Computers
by Alan M. Boyd

COMMODORE 128 PROGRAMMER'S

REFERENCE GUIDE
by Commodore Business Machines, Inc.
THE COMPUTER AND THE BRAIN
by Scott Ladd/
The Red Feather Press
EXPLORING ARTIFICIAL INTELLIGENCE
ON YOUR APPLE II
by Tim Hartnell
EXPLORING ARTIFICIAL INTELLIGENCE
ON YOUR COMMODORE 64
by Tim Hartnell
EXPLORING ARTIFICIAL INTELLIGENCE
ON YOUR IBM PC
by Tim Hartnell
EXPLORING THE UNIX ENVIRONMENT
by The Waite Group/Irene Pasternack
FRAMEWORK FROM THE GROUND UP
by The Waite Group/Cynthia Spoor and
Robert Warren

POWER PAINTING: COMPUTER GRAPHICS

ON THE MACINTOSH
by Verne Bauman and Ronald Kidd/
illustrated by Gasper Vaccaro
SMARTER TELECOMMUNICATIONS
Hands-On Guide to On-Line Computer Services
by Charles Bowen and Stewart Schneider
SWING WITH JAZZ: LOTUS JAZZ ON THE
MACINTOSH
by Datatech Publications Corp./S. Michael McCarty
UNDERSTANDING EXPERT SYSTEMS
by The Waite Group/Mike Van Horn
USER'S GUIDE TO THE AT&T PC 6300
PERSONAL COMPUTER
by David B. Peatroy, Ricardo A. Anzaldua,
H. A. Wohlwend, and Datatech Publications
Corp.

C O M M O D O R E 128
PROGRAMMER'S
REFERENCE GUIDE

COMMODORE BUSINESS MACHINES, INC.

BANTAM BOOKS
TORONTO NEW YORK LONDON SYDNEY AUCKLAND

COMMODORE 128 PROGRAMMER S REFERENCE GUIDE

A Bantam Book / February 1986

Commodore 64 and Commodore 128 are registered trademarks of Commodore
Electronics. Ltd.
CP/M and CP/M Plus Version 3.0 are registered trademarks of Digital Research
lnc.
Perfect is a registered trademark ofPerfect Software.
TouchTone is a registered trademark ofAT&T.
WordStar is a registered trademark ofMicroPro International Corporation.
Grateful acknowledgment is made for permission to reprint two bars of Invention
13 (Inventio 13) by Johann Sebastian Bach. Sheet music copyright C. F. Peters,
Corp., New York.
Book design by Ann Gold.
Cover design by Jo Ellen Temple.

All rights reserved.

Copyright 1986 by Commodore
This book may not be reproduced
mimeograph or any other means,
For information address: Bantam

Capital, lnc.
in whole or in part, by
without permission.
Books, Inc.

ISBN 0-553-34292-4
Published simultaneously in the United States and Canada
Bantam Books are published by Bantam Books, Inc. Its trademark, consisting of
the words "Bantam Books" and the portrayal ofa rooster, is Registered in U.S.
Patent and Trademark Office and in other countries. Marca Registrada. Bantam
Books, lnc., 666 Fifth Avenue, New York, New York 10103.

P R I N T E D lN T H E U N I T E D S T A T E S O F

HL

AMERICA

CONTENTS
Chapter 1
Introduction

Chapter 2
BASIC Building Blocks and BASIC 7.0 Encyclopedia

11

Chapter 3
One Step Beyond Simple BASIC

91

Chapter 4
Commodore 128 Graphics Programming

109

Chapter 5
Machine Language on the Commodore 128

123

Chapter 6
How
to Enter
Machine
Language Programs Into the
Commodore
128
Chapter
7

181

Mixing Machine Language and BASIC

197

Chapter 8
The Power Behind Commodore 128 Graphics

207

Chapter 9
Sprites

265

Chapter 10
Programming the 80-Column (8563) Chip

291

Chapter 11
Sound and
Chapter
Input/Output
12 Music
Guideon the Commodore 128

335
371

Chapter 13
The Commodore 128 Operating System

401

Chapter 14
CP/M 3.0 on the Commodore 128

477

Chapter 15
The Commodore 128 and Commodore 64 Memory Maps

501

Chapter 16
C128 Hardware Specifications

555

Appendixes

643

Glossary

731

Index

739

ACKNOWLEDGMENTS

Written by Larry Greenley

and
Fred Bowen
Bil Herd
Dave Haynie
Terry Ryan
Von Ertwine
Kim Eckert
Mario Eisenbacher
Norman McVey
The authors are deeply indebted to the many people who have contributed to the
preparation of this book. Special thanks go to Jim Gracely of Commodore Publications,
who reviewed the entire manuscript for technical accuracy and provided important
corrections, clarifications, and user-oriented suggestions, and to Steve Beats and Dave
Middleton of Commodore Software Engineering for their programming assistance and
expertise.
We also want to recognize the contributions of Frank Palaia of Commodore Hardware
Design, who provided expertise in the operation of the Z80 hardware, and of Dave
DiOrio of Commodore Integrated Circuit Design, who provided insight into the design
of the Memory Management Unit and the C128 VIC chip enhancements.
For their extensive technical reviews of the manuscript, we wish to thank Bob Albright,
Pete Bowman, Steve Lam and Tony Porrazza of Commodore Engineering. We also
thank Dan Baker, Dave Street and Carolyn Scheppner of Commodore Software Technical Support for providing an always available source of technical assistance. In addition,
we want to acknowledge the valuable contributions of members of Commodore Software Quality Assurance, especially Mike Colligon, Karen Mackenzie, Pat McAllister,
Greg Rapp, Dave Resavy, and Stacy English.
We also thank Carol Sullivan and Donald Bein for carefully proofreading various
sections of the text, Michelle Dreisbach for typing the manuscript, Marion Dooley for
preparing the art, Jo-Ellen Temple for the cover design, and Nancy Zwack for overall
coordination assistance.
Finally, we would like to acknowledge the unflagging support and guidance provided by
senior Commodore executives Paul Goheen, Harry McCabe and Bob Kenney.

J
INTRODUCTION

COMMODORE 128

The Commodore 128 Personal Computer is a versatile, multimode computer. The

Commodore 128 is the successor to the commercially successful Commodore 64 computer. The principal features of the Commodore 128 are:

128K bytes of RAM, optionally expandable to 256K or 640K

80-column horizontal screen display
Hardware and software compatibility with Commodore 64
CP/M 3.0 operation
Enhanced BASIC language

As this Guide shows, the Commodore 128 has many other new or expanded
capabilities and features. Those listed above, however, are the most significant when
assessing the Commodore 128's capabilities against those of the Commodore 64 and
other microcomputers.
The Commodore 128 is actually three computers in one, with the following three
primary operating modes:

C128 Mode
C64 Mode
CP/M Mode

Two of these primary modes (C128 and CP/M) can operate using either a 40- or
80-column screen display. Following is a summary of the major features of each of the
three primary operating modes.

CI28 MODE
In C128 Mode, the Commodore 128 Personal Computer provides the capabilities and
memory needed to run sophisticated applications, such as word processing, spreadsheets,
and database programs.
C128 Mode features include:

8502 processor running at 1.02 or 2.04 MHz

New, enhanced C128 Kernal
Built-in machine language monitor
Commodore BASIC 7.0 language, with over 140 commands and functions
Special new BASIC 7.0 commands that provide better, quicker and easier ways
to create complex graphics, animation, sound and music programs
40-column text and bit map screen output using VIC II chip
80-column text screen output using 8563 chip

INTRODUCTION

NOTE: The 40- and 80-column screen displays can be used either singly
or simultaneously with two monitors.

Sound (three voices) using SID chip

A 92-key keyboard that includes a full numeric keypad and ESCAPE, TAB,
ALT, CAPS LOCK, HELP, LINE FEED, 40/80 DISPLAY, and NO SCROLL
keys
Access to the full capabilities of the new peripheral devices from Commodore
(1571 fast disk drive, 1902 dual 40/80-column RGBI monitor, etc.)
Access to all standard Commodore serial peripherals
RAM expansion to 256 or 640K with optional RAM expansion modules

C64 MODE
In C64 Mode, the Commodore 128 retains all the capabilities of the Commodore 64,
thus allowing you to use the wide range of available Commodore 64 software.
C64 Mode features include:

8502 processor running at 1.02 MHz

Standard C64 Kernal
BASIC 2.0 language
64K of RAM
40-column output using VIC II chip
Sound (three voices) using SID chip
Standard Commodore 64 keyboard layout except for function keys
All standard Commodore 64 keyboard functions
Access to all Commodore 64 graphics, color and sound capabilities, used
as on a Commodore 64
Compatibility with standard Commodore 64 peripherals, including user port and
serial devices, Datassette, joysticks, composite video monitors, and RF
(TV) output devices

NOTE: The 1571 disk drive will function in C64 Mode, but only
at standard 1541 speed. C64 compatibility requirements make it impossible for the 1571 to operate in C64 Mode at fast speed.

COMMODORE 128

CP/M MODE
In CP/M Mode, an onboard Z80 microprocessor gives you access to the capabilities of
Digital Research's CP/M Version 3.0, plus a number of new capabilities added by Commodore.
CP/M Mode features include:

Integral Z80 processor running at 2.04 MHz

Disk-based CP/M 3.0 System
128K bytes of RAM (in 64K banks)
40-column screen output using VlC II chip
80-column screen output using 8563 chip
Access to the full keyboard, including the numeric keypad and special keys
Access to the new fast serial disk drive (1571) and the standard serial peripherals
Ability to redefine almost any key
Ability to emulate several terminals (Lear-Siegler ADM31, ADM3A)
Support for various MFM disk formats (IBM, Kaypro, Epson, Osborne)
RAM expansion to 256 or 640K RAM with optional RAM expansion modules

The incorporation of CP/M 3.0 (also called CP/M Plus) into the Commodore 128
makes thousands of popular commercial and public domain software programs available
to the user.

HARDWARE COMPONENTS
The Commodore 128 Personal Computer incorporates the following major hardware
components:

PROCESSORS
8502: Main processor in C128, C64 Modes; I/O support for CP/M; 6502 softwarecompatible; runs at 1.02 or 2.04 MHz
Z80: CP/M Mode only; runs at 2.04 MHz

MEMORY
ROM: 64K standard (C64 Kernal plus BASIC; C128 Kernal plus BASIC, character
ROMs and CP/M BIOS); one 32K slot available for software
RAM: l28K in two 64K banks; 16K display RAM for 8563 video chip; 2K x 4 Color RAM

VIDEO
8564: 40-column video (separate versions for NTSC and PAL TV standards)
8563: 80-column video

INTRODUCTION

SOUND
6581: SID Chip

INPUT/OUTPUT
6526: Joystick ports/keyboard scan/cassette
6526: User and serial ports

MEMORY MANAGEMENT
8921: PLA (C64 plus C128 mapping modes)
8922: MMU (Custom gate array)
For details on these and other hardware components see Chapter 16, Commodore
128 Hardware Specifications.

COMPATIBILITY WITH
COMMODORE 64
The Commodore 128 system is designed as an upgrade to the Commodore 64. Accordingly, one of the major features of the Commodore 128 design is hardware and software
compatibility with the Commodore 64 when operating in C64 Mode. This means that in
C64 Mode the Commodore 128 is capable of running Commodore 64 application
software. Also, the Commodore 128 in C64 Mode supports Commodore 64 peripherals
except the CP/M 2.2 cartridge. (NOTE: The Commodore 128's built-in CP/M 3.0
capability supersedes that provided by the external cartridge. This cartridge should not
be used with the Commodore 128 in any mode.)
The C128 Mode is designed as a compatible superset to the C64. Specifically, all
Kernal functions provided by the Commodore 64 are provided in the C128 Kernal.
These functions are also provided at the same locations in the jump table of the C128
Kernal to provide compatibility with existing programs. Zero page and other system
variables are maintained at the same addresses they occupy in C64 Mode. This simplifies interfacing for many programs.
Providing Commodore 64 compatibility means that the new features of the Commodore 128 cannot be accessed in C64 Mode. For example, compatibility and memory
constraints preclude modifying the C64 Mode Kernal to support the 1571 fast serial disk
drive. As noted previously, C64 Mode sees this drive as a standard serial disk drive. For
the same reason, C64 Mode does not have an 80-column screen editor, and C64 Mode
BASIC 2.0 cannot use the second 64K bank of memory.

13

COMMODORE 128

SWITCHING FROM MODE TO MODE

As mentioned before, in the C128 and CP/M Modes the Commodore 128 can provide
both 40-column and 80-column screen displays. This means that the Commodore 128
actually has five operating modes, as follows:

C128 Mode with 80-column display

C128 Mode with 40-column display
C64 Mode (40-column display only)
CP/M Mode with 80-column display
CP/M Mode with 40-column display

Figure 1-1 summarizes the methods used to switch from mode to mode.
FROM
TO
OFF

CI28
40 COL

CI28
80 COL

C128
40 COL

1. Check that
40/80 key
is UP.
2. Make sure
that:
a)NoCP/M
system
disk is
in drive
b)No C64
cartridge
is in expansion
port
3. Turn computer ON.
~T. Press
~T. Press
40/80 key
ESC key;
DOWN.
release.
2. Turn com- 2. Press X
puter ON.
key.
OR
1. Press
40/80 key
DOWN.
2. Press
RESET
button.

C128
80 COL

C64

1. Press ESC
key;
release.
2. Press X
key.
OR
1. Check that
40/80 key
is UP.
2. Press
RESET
button.

1. Check that
40/80 key
is UP.
2. Turn computer OFF,
then ON.
3. Remove
cartridge
if present

~T. Press
40/80 key
DOWN.
2. Turn computer OFF,
then ON.
3. Remove
cartridge
if present.

Figure l - l . Commodore 128 Mode Switching Chart

CP/M

CP/M
40 COL

80 COL

1. Check that
40/80 key
is UP.
2. Turn computer OFF,
then ON.

1. Check that
40/80 key
is UP.
2. Turn computer OFF,
then ON.

Press
40/80 key
DOWN.
2. Remove
CP/M system disk
from
drive, if
necessary.
3. Turn computer OFF,
then ON.

~T Check that
40/80 key
is DOWN.
2. Remove
CP/M system disk
from
drive, if
necessary.
3. Turn computer OFF,
then ON.

INTRODUCTION

FROM
TO
OFF

C128

C128

CP/M

CP/M

40 COL

80 COL

40 COL

80 COL

1. Turn computer OFF.

2. Check that
40/80 key
is UP.
3. Hold
DOWN
O key
while
turning
computer
ON.
OR
1. Turn computer OFF.
2. Insert C64
cartridge.
3. Turn
power ON.

1. Turn computer OFF.

2. Check that
40/80 key
is UP.
3. Hold
DOWN
0 key
while turning computer ON.
OR
1. Turn computer OFF.
2. Insert C64
cartridge.
3. Turn
power
ON.

C64

C64

1. Hold
" 0 "key
DOWN.
2. Turn computer ON.
OR
1. Insert C64
cartridge.
2. Turn computer ON.

1. Type GO
64; press
RETURN.
2. The computer responds:
ARE YOU
SURE?
Type Y;
press
RETURN.

1. Type GO
64; press
RETURN.
2. The computer responds:
ARE YOU
SURE?
Type Y;
press
RETURN.

CP/M
40 COL

1. Turn disk
drive ON.
2. Insert
CP/M system disk
in drive.
3. Check that
40/80 key
is UP.
4. Turn computer ON.

1. Turn disk
drive ON.
2. Insert
CP/M system disk
in drive.
3. Check that
40/80 key
is UP.
4. Type:
BOOT
5. Press
RETURN.

1. Turn disk
drive ON.
2. Insert
CP/M system disk
in drive.
3. Check that
40/80 key
is UP.
4. Type:
BOOT
5. Press
RETURN.

1. Check that
40/80 key
is UP.
2. Turn disk
drive ON.
3. Insert
CP/M system disk
in drive.
4. Turn computer OFF.

1. Turn disk
drive ON.
2. Insert
CP/M system disk
in drive.
3. Press
40/80 key
DOWN.
4. Turn computer ON.

1. Turn disk
drive ON.
2. Insert
CP/M system disk
in drive.
3. Press
40/80 key
DOWN.
4. Type:
BOOT
5. Press
RETURN.

1. Turn disk
drive ON.
2. Insert
CP/M system disk
in drive.
3. Check that
40/80 key
is DOWN.
4. Type:
BOOT.
5. Press
RETURN.

1. Press
40/80 key
DOWN.
2. Turn disk
drive ON.
3. Insert
CP/M system disk
in drive.
4. Turn computer OFF.

CP/M
80 COL

1. Insert
CP/M utilities disk
in drive.
2. At screen
prompt,
A > type:
DEVICE
CONOUT: =
40 COL

3. Press
RETURN.
1. Insert
CP/M utilities disk
in drive.
2. At screen
prompt,
A > type:
DEVICE
CONOUT =
80 COL

3. Press
RETURN.

Figure l - l . Commodore 128 Mode Switching Chart (continued)

COMMODORE 128

NOTE: If you are using a Commodore 1902 dual monitor, remember to

move the video switch on the monitor from COMPOSITE or SEPARATED to RGBI when switching from 40-column to 80-column display;
reverse this step when switching from 80 to 40 columns. Also, when
switching between modes remove any cartridges from the expansion port.
You may also have to remove any disk (e.g., CP/M) from the disk drive.

CP/M 3.0 SYSTEM RELEASES

When you send in your C128 warranty card, your name will be added to a list
which makes you eligible for CP/M system release dates.

HOW TO USE THIS GUIDE

This guide is designed to be a reference tool that you can consult whenever you need
detailed technical information on the structure and operation of the Commodore 128
Personal Computer. Since many of the design features of the Commodore 128 can be
viewed from various aspects, it may be necessary to consult several different chapters to
find the information you want. Note that certain groups of chapters form logical sequences
that cover in detail an extended topic like BASIC, graphics, or machine language.
The following chapter summaries should help you pinpoint what chapter or
chapters are most likely to provide the answer to a specific question or problem.
C H A P T E R 2. BASIC BUILDING BLOCKS AND BASIC 7.0 ENCYCLOPEDIA
Defines and describes the structural and operational components of the BASIC
language, including constants, variables and arrays, and numeric and string expressions and operations.
C H A P T E R 3. ONE STEP BEYOND SIMPLE BASICProvides routines (menu,
keyboard buffer, loading, programming function keys) and techniques ("crunchi n g " or saving memory; debugging and merging programs; relocating BASIC)
that can be incorporated in your own programs. Provides modem-related information (how to generate TouchTone frequencies, how to detect telephone ringing,
etc.) plus technical specifications for Commodore Modemyi200 and Modem/300.
C H A P T E R 4. COMMODORE 128 GRAPHICS PROGRAMMINGDescribes the
general BASIC 7.0 graphics commands (COLOR, GRAPHIC, DRAW, LOCATE, BOX, CIRCLE, PAINT) and gives annotated examples of use, including
programs. Describes the structure and general function of the color modes and
character and bit map graphics modes that are fundamental to Commodore 128
graphics.

INTRODUCTION

C H A P T E R 5. MACHINE LANGUAGE ON THE COMMODORE 128Defines,

with examples, machine language (ML) and associated topics, including the
Kernal; the 8502 registers, binary and hexadecimal numbers, and addressing
modes. Defines, with examples, types of ML instructions (op codes, etc.).
Includes 8502 instruction and addressing table.
C H A P T E R 6. HOW TO ENTER MACHINE LANGUAGE PROGRAMS INTO THE
C O M M O D O R E 128Describes, with examples, how to enter ML programs by
using the built-in Machine Language Monitor or by POKEing decimal op-code
values with a BASIC program. Defines, with examples, the ML Monitor commands.
C H A P T E R 7. MIXING MACHINE LANGUAGE AND BASICDescribes, with
examples, how to combine BASIC and ML instructions in the same program by
using BASIC READ, DATA, POKE and SYS commands. Shows where to place
M L programs in memory.
C H A P T E R 8. THE POWER BEHIND COMMODORE 128 GRAPHICSDescribes
the C128 Mode memory banking concept and tells how to manage banked
memory. Defines the use of shadow registers. Describes how screen, color and
character memory are handled in BASIC and machine language, for both character
and bit map modes. Shows how to redefine the character set. Describes use of
split-screen modes. Includes a tabular graphics programming summary.
C H A P T E R 9. SPRITESDescribes programming of sprites or MOBs (movable object
blocks). Defines and shows how to use the BASIC 7.0 sprite-related commands
(SPRITE, SPRDEF, MOVSPR, SSHAPE, GSHAPE, SPRSAV). Provides annotated examples of use, including programs.
C H A P T E R 10. PROGRAMMING THE 8O-COLUMN (8563) CHIPDefines the
8563 registers and describes, with machine language examples, how to program
the 80-column screen in character and bit map modes.
C H A P T E R I I . SOUND AND MUSIC ON THE COMMODORE 128Defines the
BASIC 7.0 sound and music commands (SOUND, ENVELOPE, VOL, TEMPO,
PLAY, FILTER). Describes how to code a song in C128 Mode. Defines in detail
the Sound Interface Device (SID) and how to program it in machine language.
C H A P T E R 12. INPUT/OUTPUT GUIDEDescribes software control of peripheral
devices connected through I/O ports, including disk drives, printers, other User
Port and Serial Port devices, the Datassette, and Controller Port devices. Provides
pin-out diagrams and pin descriptions for all ports.
C H A P T E R 13. THE COMMODORE 128 OPERATING SYSTEMDescribes, with
examples, the operating system (Kernal), which controls the functioning of the
Commodore 128; includes the Kernal Jump Table, which lists the ROM entry
points used to call the Kernal routines; defines each Kernal routine; defines the
C128 Screen Editor. Describes the Memory Management Unit (MMU), defines
the MMU registers, tells how to select and switch banks in BASIC and ML, and
tells how to predefine memory configurations.
C H A P T E R 14. CP/M 3.0 ON THE COMMODORE 128Summarizes the Commodore version of CP/M 3.0. Defines the general system layout and the operating
system components (CCP, BIOS and BDOS). Describes the Commodore enhancements to CP/M 3.0. (Additional details on CP/M 3.0 are given in Appendix K.)

10

COMMODORE 128

C H A P T E R 15. COMMODORE 128 AND COMMODORE 64 M E M O R Y M A P S

Provides detailed memory maps for C128 and C64 modes. (The Z80 memory
map is shown in Appendix K.)
C H A P T E R 16. HARDWARE SPECIFICATIONSIncludes technical specifications for
Commodore 128 hardware components (8563, 8564, etc.).
A P P E N D I X E S A through LProvide additional technical information and/or a more
convenient grouping of information supplied elsewhere in the Guide (e.g., pinout
diagrams).
GLOSSARYProvides standard definitions of technical terms.

2
BASIC
BUILDING
BLOCKS AND
BASIC 7.0
ENCYCLOPEDIA

II

12

COMMODORE 128

The BASIC language is composed of commands, operators, constants, variables, arrays

and strings. Commands are instructions that the computer follows to perform an
operation. The other elements of BASIC perform a variety of functions, such as
assigning values to a quantity, passing values to the computer, or directing the computer
to perform a mathematical operation. This section describes the structure and functions
of the elements of the BASIC language.

COMMANDS AND STATEMENTS

By definition, commands and statements have the following distinctions. A command is
a BASIC verb which is used in immediate mode. It is not preceded by a program line
number and it executes immediately after the RETURN key is pressed. A statement is
a BASIC verb which is contained within a program and is preceded by a line number.
Program statements are executed with the RUN command followed by the RETURN key.
Most commands can be used within a program. In this case the command is
preceded by a line number and is said to be used in program mode. Many commands
also can be used outside a program in what is called direct mode. For example, LOAD
is an often-used direct mode command, but you can also include LOAD in a program.
GET and INPUT are commands that only can be used in a program; otherwise, an
ILLEGAL DIRECT ERROR occurs. While PRINT is usually included within a
program, you can also use PRINT in direct mode to output a message or numeric value
to the screen, as in the following example:
PRINT ' T h e Commodore 128''

RET U R N

Notice that the message is displayed on the screen as soon as you press the return
key. The following two lines display the same message on the screen. The first line is a
program mode statement; the second line is a direct mode command.
10 PRINT "The Commodore 128"
RUN

RETURN

RETURN

It is important to know about the concepts behind memory storage before examining the Commodore BASIC language in detail. Specifically, you need to understand
constants, variables and arrays.

NUMERIC MEMORY STORAGE:

CONSTANTS, VARIABLES AND ARRAYS
There are three ways to store numeric information in Commodore BASIC. The first way
is to use a constant. A constant is a form of memory storage in which the contents
remain the same throughout the course of a program. The second type of memory
storage unit is a variable. As the name indicates, a variable is a memory storage cell in

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

which the contents vary or change throughout the course of a program. The last way to store
information is to use an array, a series of related memory locations consisting of variables.
Each of these three units of memory storage can have three different types of
information or data assigned. The three data types are INTEGER, FLOATING-POINT
or STRING. Integer data is numeric, whole number datathat is, numbers without
decimal points. Floating-point is numeric data including fractional parts indicated with a
decimal point. String data is a sequential series of alphanumeric letters, numbers and
symbols referred to as character strings. The following paragraphs describe these three
data types and the way each memory storage unit is assigned different data type values.

CONSTANTS: INTEGER,
FLOATING-POINT AND STRING
INTEGER CONSTANTS
The value assigned to a constant remains unchanged or constant throughout a program.
Integer constants can contain a positive or negative value ranging from -32768 through
+ 32767. If the plus sign is omitted, the C128 assumes that the integer is positive.
Integer constants do not contain commas or decimal points between digits. Leading
zeros are ignored. Integers are stored in memory as two-byte binary numbers, which
means a constant requires 16 bits or two bytes of memory to store the integer as a base
two number. The following are examples of integer constants:
1
1000
-32
0
-32767

FLOATING-POINT CONSTANTS
Floating-point constants contain fractional parts that are indicated by a decimal
point. They do not contain commas to separate digits. Floating-point constants may be
positive or negative. If the plus sign is omitted, it is assumed that the number is
positive. Again, leading zeros are unnecessary and ignored. Floating-point constants are
represented in two ways depending on their value:
1.
2.

Simple Number Notation

Scientific Notation

In simple number notation, the floating-point number is calculated to ten digits of

precision and stored using five bytes, but only nine digits are displayed on the screen or
printer. If the floating-point number is greater than nine digits, it is rounded according to
the tenth digit. If the tenth digit is greater than five, the ninth digit is rounded to the next
higher digit. If the tenth digit is less than five, the ninth digit is rounded to the next
lower digit. The rounding of floating-point numbers may become a factor when calculat-

13

14

C O M M O D O R E 128

ing values based upon floating-point numbers greater than nine digits. Your program
should test floating-point results and take them into consideration when basing these
values on future calculations.
As mentioned, floating-point numbers are displayed as nine digits. If the value o f a
floating-point constant is less than .01 or greater than 999999999, the number is
displayed on the screen or printer in scientific notation. For example, the number
12345678901 is displayed as 1.23456789E+ 10. Otherwise, the simple number notation
is displayed. A floating-point constant in scientific notation appears in three parts:
1.
2.
3.

The mantissa is the leftmost number separated by a decimal point.

The letter E indicates that the number is displayed in exponential (scientific)
notation.
The exponent specifies the power of ten to which the number is raised and the
number of places the decimal point is moved in order to represent the number
in simple number notation.

The mantissa and exponent can be positive or negative. The exponent can be
within the range - 3 9 to + 3 8 . If the exponent is negative, the decimal point moves to
the left representing it as a simple number. If the exponent is positive, the decimal
point moves to the right representing it in simple number notation.
The Commodore 128 limits the size of floating-point numbers. The highest
number you can represent in scientific notation is 1.70141183E + 38. If you try to
represent a number larger than that, an OVERFLOW ERROR occurs. The smallest
number you can represent in scientific notation is 2.93873588E-39. If you try to
represent a number smaller than that, no error occurs but a zero is returned as the value.
You should therefore test floating-point values in your programs if your calculations are
based on very small numbers and the results depend on future calculations. Here are
examples of floating-point constants in simple number notation and others in scientific
notation:

SIMPLE NUMBER

SCIENTIFIC

9.99
.0234
+ 10.01
-90.23

22.33E + 20
99999.234E-23
^5.89E-11
-3.14E + 17

NOTE: The values in either column are not equivalent.

STRING CONSTANTS
A string constant, as mentioned, is a sequential series of alphanumeric characters
(numbers, letters and symbols). A string constant can be as long as a 160-character input

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

line, minus the line number and any other information appearing on that program line.
By concatenating strings together, you may form a string as long as 255 characters. The
string may contain numbers, letters, and even decimal points and commas. However,
the string cannot contain the double quote ( " ) character, since this character delimits or
marks the beginning or ending of the string. You can represent a double quote character
within a string using CHR$(34). You can omit the closing double quote character of a
string if it is the last statement in a line of a program.
A string can even be assigned a null value, meaning no characters are actually
assigned to it. Assign a string a null value by omitting characters between the double
quotes and follow the opening double quote directly with a closing double quote. Here
are some examples of string constants:
"Commodore 128"
"qwerl234!#$%()*.:,"
" " (null string)
"John and Joan"

VARIABLES: INTEGER,
FLOATING-POINT AND STRING
Variables are units of memory storage that represent varying data values within a
program. Unlike constants, variables may change in value throughout the course of a
program. The value assigned to a variable can be an integer, a floating-point number, or
a string. You can assign a value to a variable as the result of a mathematical calculation.
Variables are assigned values using an equals sign. The variable name appears to the left
of the equals sign and the constant or calculation appears to the right. When you refer to
a variable in a program before you assign it a value, the variable value becomes zero if
it is an integer or floating-point number. It becomes a null string if the variable is a
string.
Variable names can be any length, but for efficiency you should limit the size
of the variable to a few characters. Only the first two characters of a variable name
are significant. Therefore, do not begin the names of two different variables with
the same two characters. If you do, the C128 will interpret them as the same variable
name.
The first character of a variable name must be a letter. The rest of the
variable name can be any letter or number from zero to nine. A variable name
must not contain any BASIC keyword. If you include a BASIC keyword in
a variable name, a SYNTAX ERROR occurs. BASIC keywords include all
BASIC statements, commands, function names, logical operator names and reserved
variables.
You can specify the data type of a variable by following the variable name with
a percent sign (%) if the variable is an integer value, or a dollar sign if the
variable is a string. If no character is specified, the C128 assumes that the variable
value is a floating-point number. Here are some examples of variables and how they are
assigned:

15

16

COMMODORE 128

A Z% F$ T Count % =
G$ =
H$ -

3.679 (floating-point)
714 (integer)
"CELEBRATE THE COMMODORE 128" (string)
A + Z% (floating-point)
Count % + 1 (integer)
"SEEK A HIGHER LEVEL OF CONSCIOUSNESS" (string)
F$ + G$ (string)

ARRAYS: INTEGER,
FLOATING-POINT AND STRING
Although arrays were defined earlier in this chapter as series of related variables or
constants, you refer to them with a single integer, floating point or string variable name.
All elements have the same data type as the array name. To access successive elements
within the array, BASIC uses subscripts (indexed variables) to refer to each unique storage
compartment in the array. For example, the alphabet has twenty-six letters. Assume an
array called " A L P H A " is constructed and includes all the letters of the alphabet. To
access the first element of the array, which is also the first letter of the alphabet (A),
label Alpha with a subscript of zero:
ALPHA$(0)

To access the letter B, label Alpha with a subscript of one:

ALPHA$(1)

Continue in the same manner to access all of the elements of the array ALPHA, as in
the following:
ALPHA$(2)
ALPHA$(3)
ALPHA$(4)
ALPHA$(5)

C
D
E
Z

Subscripts are a convenient way to access elements within an array. If subscripts

did not exist, you would have to assign separate variables for all the data that would
normally be accessed with a subscript. The first subscript within an array is zero.
Although arrays are actually stored sequentially in memory, they can be multidimensional. Tables and matrices are easily manipulated with two-dimensional arrays.
For example, assume you have a matrix with ten rows and ten columns. You need 100
storage locations or array elements in order to store the whole matrix. Even though
your matrix is ten by ten, the elements in the array are stored in memory one
after the other for 100 hundred locations.
You specify the number of dimensions in the arrays with the DIM statement. For
example:

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

10 DIM A(99)
dimensions a one-dimensional floating-point array with 100 elements. The following are
examples of two-, three- and four-dimensional integer arrays:
20 DIM B(9, 9)
30 DIM C(20,20,20)
40 DIM D(10,l5,15,10)

(100 elements)
(9261 elements)
(30976 elements)

In theory the maximum number of dimensions in an array is 255, but you cannot
fit a DIMension statement that long on a 160-character line. The maximum number of
DIMension statements you can fit on a 160-character line is approximately fifty. The
maximum number of elements allowed in each dimension is 32767. In practice, the size
of an array is limited to the amount of available memory. Most arrays are one-, two- or
three-dimensional. If an array contains fewer than ten elements, there is no need for a
DIM statement since the C128 automatically dimensions variable names to ten elements.
The first time you refer to the name of the undimensioned array (variable) name, the
C128 assigns zero to the value if it is a numeric array, or a null string if it is a string
array.
You must separate the subscript for each dimension in your DIMension statement
with a comma. Subscripts can be integer constants, variables, or the integer result of an
arithmetic operation. Legal subscript values can be between zero and the highest
dimension assigned in the DIMension statement. If the subscript is referred to outside of
this range, a BAD SUBSCRIPT ERROR results
The type of array determines how much memory is used to store the integer,
floating-point or string data.
Floating-point string arrays take up the most memory; integer arrays require the
least amount of memory. Here's how much memory each type of array requires:

+
+
OR +
OR +
AND 4-

5
2
2
5
3
1

bytes for the array name

bytes for each dimension
bytes for each integer array element
bytes for each floating-point element
bytes for each string element
byte per character in each string element

Keep in mind the amount of storage required for each type of array. If you only
need an integer array, specify that the array be the integer type, since floating-point
arrays require much more memory than does the integer type.
Here are some example arrays:
A$(0) = "GROSS SALES"
MTH$(K%) = " J A N "
G2%(X) = 5
CNT%(G2%(X)) = CNT%( 1) FP(12*K%) = 24.8

(string array)
(string array)
(integer array)
(integer array)
(floating-point array)

17

18

COMMODORE 128

SUM(CNT%( 1)) = FP*K%

A(5) = 0
B(5,6) = 26

C(l,2,3)=100

(floating-point array)
Sets the 5th element in the 1 dimensional array
called " A " equal to 0
Sets the element in row position 5 and column
position 6 in the 2 dimensional array called " B "
equal to 26
Sets the element in row position 1, column
position 2, and depth position 3 in the 3 dimensional array called " C " equal to 100

EXPRESSIONS AND OPERATORS

Expressions are formed using constants, variables and/or arrays. An expression can be a
single constant, simple variable, or an array variable of any type. It also can be a
combination of constants and variables with arithmetic, relational or logical operators
designed to produce a single value. How operators work is explained below. Expressions can be separated into two classes:
1.
2.

ARITHMETIC
STRING

Expressions have two or more data items called operands. Each operand is
separated by a single operator to produce the desired result. This is usually done by
assigning the value of the expression to a variable name.
An operator is a special symbol the BASIC Interpreter in your Commodore 128
recognizes as representing an operation to be performed on the variables or constant
data. One or more operators, combined with one or more variables and/or constants
form an expression. Arithmetic, relational and logical operators are recognized by
Commodore 128 BASIC.

ARITHMETIC EXPRESSIONS
Arithmetic expressions yield an integer or floating-point value. The arithmetic operators
( + , - , * , / , f ) are used to perform addition, subtraction, multiplication, division and
exponentiation operations, respectively.

ARITHMETIC OPERATIONS
An arithmetic operator defines an arithmetic operation which is performed on the two
operands on either side of the operator. Arithmetic operations are performed using
floating-point numbers. Integers are converted to floating-point numbers before an
arithmetic operation is performed. The result is converted back to an integer if it is
assigned to an integer variable name.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

ADDITION ( + )
The plus sign (4-) specifies that the operand on the right is added to the operand on the
left.
EXAMPLES:

2+2
A+B+ C
X% + 1
BR+10E-2

SUBTRACTION ( - )
The minus sign (-) specifies that the operand on the right is subtracted from the operand
on the left.
EXAMPLES:
4-1
100-64
A-B
55-142
The minus also can be used as a unary minus which is the minus sign in front of a
negative number. This is equal to subtracting the number from zero (0).
EXAMPLES:
-5
-9E4
-B
4 - ( - 2 ) (same as 4 + 2)

MULTIPLICATION (*)
An asterisk (*) specifies that the operand on the left is multiplied by the operand on the
right.
EXAMPLES:
100*2
50*0
A*X1
R%*14

DIVISION (/)
The slash (/) specifies that the operand on the left is divided by the operand on the
right.

19

20

COMMODORE 128

EXAMPLES:
10/2
6400/4
A/B
4E2/XR

EXPONENTIATION ( t )
The up arrow ( f ) specifies that the operand on the left is raised to the power specified
by the operand on the right (the exponent). If the operand on the right is a 2, the number
on the left is squared; if the exponent is a 3, the number on the left is cubed, etc. The
exponent can be any number as long as the result of the operation gives a valid
floating-point number.
EXAMPLES:
2
3
4
AB
3

f
t
f
f
j

2
3
4
CD
-2

Equivalent to 2*2
Equivalent to 3*3*3
Equivalent to 4*4*4*4
Equivalent to

V3*V3

RELATIONAL OPERATORS
The relational operators ( < , = , > , < = , > = , < > ) are primarily used to compare the
values of two operands, but they also produce an arithmetic result. The relational
operators and the logical operators (AND, OR, and NOT), when used in comparisons,
produce an arithmetic true/false evaluation of an expression. If the relationship stated in
the expression is true, the result is assigned an integer value of - 1 . If it's false a value of
0 is assigned. Following are the relational operators:
<
=

>
< > =
<>

LESS THAN
EQUAL TO
GREATER THAN
LESS THAN OR EQUAL TO
GREATER THAN OR EQUAL TO
NOT EQUAL TO

EXAMPLES:
5 - 4 = 1 result true (-1)
1 4 > 6 6 result false (0)
1 5 > = 15 result true (-1)
Relational operators may be used to compare strings. For comparison purposes,
the letters of the alphabet have the order A < B < C < D , etc. Strings are compared by

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

evaluating the relationship between corresponding characters from left to right (see
string operations).
EXAMPLES:
"A" < "B"
"X" - "YY"
BB$ < > CC$

result true (-1)

result false (0)
result false (0) if they are the same

Numeric data items can only be compared (or assigned) with other numeric items.
The same is true when comparing strings; otherwise, the BASIC error message ?TYPE
MISMATCH occurs. Numeric operands are compared by first converting the values of
either or both operands from integer to floating-point form, as necessary. Then
the relationship between the floating-point values is evaluated to give a true/false
result.
At the end of all comparisons, you get an integer regardless of the data type
of the operand (even if both are strings). Because of this, a comparison of two
operands can be used as an operand in performing calculations. The result will
be - 1 or 0 and can be used as anything but a divisor, since division by zero is
illegal.

LOGICAL OPERATORS
The logical operators (AND, OR, NOT) can be used to modify the meaning of the
relational operators or to produce an arithmetic result. Logical operators can produce
results other than - 1 and 0, although any nonzero result is considered true when testing
for a true/false condition.
The logical operators (sometimes called Boolean operators) also can be used to
perform logical operations on individual binary digits (bits) in two operands. But when
you're using the NOT operator, the operation is performed only on the single operand to
the right. The operands must be in the integer range of values (-32768 to + 3 2 7 6 7 )
(floating-point numbers are converted to integers) and logical operations give an integer
result.
Logical operations are performed bit-by-corresponding-bit on the two operands.
The logical AND produces a bit result of 1 only if both operand bits are 1. The logical
OR produces a bit result of 1 if either operand bit is 1. The logical NOT is the opposite
value of each bit as a single operand. In other words, "If it's NOT 1 then it is 0. If it's
NOT 0 then it is 1 . "
The exclusive OR IF (XOR) doesn't have a logical operator but it is performed as
part of the WAIT statement or as the XOR function. Exclusive-OR means that if the
bits of two operands are set and equal, then the result is 0; otherwise the result is 1.
Logical operations are defined by groups of statements which, when taken together, constitute a Boolean "truth table" as shown in Table 2 - 1 .

21

22

COMMODORE 128

The AND operation results in a 1 only if both bits are 1:

1 AND 1 = 1
0 AND 1 - 0
1 AND 0 = 0
0 AND 0 = 0
The OR operation results in a 1 if either bit is 1:
1 OR 1 = 1
0 OR 1 = 1
1 OR 0 = 1
0 OR 0 = 0
The NOT operation logically complements each bit:
NOT 1 = 0
NOT 0 = 1
The exclusive OR (XOR) is a function (not a logical operator):
1 XOR 1 = 0
1 XOR 0 = 1
0 XOR1 = 1
0 XOR 0 = 0
Table 2-1 Boolean Truth Table

The logical operators AND, OR and NOT specify a Boolean arithmetic operation
to be performed on the two operand expressions on either side of the operator. In the
case of NOT, only the operand on the right is considered. Logical operations (or
Boolean arithmetic) aren't performed until all arithmetic and relational operations in an
expression have been evaluated.
EXAMPLES:
IF A - 100 AND B = 100 THEN 10

A = 96 AND 32: PRINT A

IF A = 100 OR B = 100 THEN 20
A = 64 OR 32: PRINT A
X = NOT 96

(if both A and B have a value of 100 then

the result is true)
(A = 32)
(if A or B is 100 then the result is true)
(A = 96)
(result is - 9 7 (two's complement))

HIERARCHY OF OPERATIONS
All expressions perform the different typesof operations according to a fixed hierarchy.
Certain operations have a higher priority and are performed before other operations. The
normal order of operations can be modified by enclosing two or more operands within

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

parentheses ( ), creating a "subexpression." The parts of an expression enclosed in parentheses will be reduced to a single value before evaluating parts outside the parentheses.
When you use parentheses in expressions, pair them so that you always have an
equal number of left and right parentheses. If you don't, the BASIC error message
7SYNTAX ERROR will occur.
Expressions that have operands inside parentheses may themselves be enclosed in
parentheses, forming complex expressions of multiple levels. This is called nesting.
Parentheses can be nested in expressions to a maximum depth of ten levelsten
matching sets of parentheses. The innermost expression has its operations performed
first. Some examples of expressions are:
A+ B
C f ( D + E)/2
( ( X - C | (D + E)/2)*10)+1
GG$>HH$
JJ$ + " M O R E "
K % = 1 AND M < > X
K% = 2 OR (A = B AND M < X )
NOT (D = E)
The BASIC Interpreter performs operations on expressions by performing arithmetic operations first, then relational operations, and logical operations last. Both arithmetic and logical operators have an order of precedence (or hierarchy of operations) within
themselves. Relational operators do not have an order of precedence and will be
performed as the expression is evaluated from left to right.
If all remaining operators in an expression have the same level of precedence, then
operations are performed from left to right. When performing operations on expressions
within parentheses, the normal order of precedence is maintained. The hierarchy of
arithmetic and logical operations is shown in Table 2-2 from first to last in order of
precedence. Note that scientific notation is resolved first.
OPERATOR

DESCRIPTION

EXAMPLE

Exponentiation

BASE t EXP

Negation (Unary Minus)

-A

*/

Multiplication
Division

AB * CD
EF/GH

Addition
Subtraction

CNT 4- 2
JK-PQ

> = <

Relational Operations

A <= B

NOT

Logical NOT
(Integer Two's Complement)

NOT K%

AND

Logical AND

OR

Logical OR

JK AND 128
PQ OR 15

Table 2-2 Hierarchy of Operations Performed on Expressions

23

24

COMMODORE 128

STRING OPERATIONS
Strings are compared using the same relational operators ( = , < > , < = , > = , < , > )
that are used for comparing numbers. String comparisons are made by taking one
character at a time (left-to-right) from each string and evaluating each character
code position from the character set. If the character codes are the same, the characters are equal. If the character codes differ, the character with the lower CBM ASCII
code number is lower in the character set. The comparison stops when the end of either
string is reached. All other factors being equal, the shorter string is considered less than
the longer string. Leading or trailing blanks are significant in string evaluations.
Regardless of the data types, all comparisons yield an integer result. This is
true even if both operands are strings. Because of this, a comparison of two string
operands can be used as an operand in performing calculations. The result will
be - 1 or 0 (true or false) and can be used in any mathematical operation but division
since division by zero is illegal.

STRING EXPRESSIONS
Expressions are treated as if an implied " < > 0 " follows them. This means that if an
expression is true, the next BASIC statement on the same program line is executed. If
the expression is false, the rest of the line is ignored and the next line in the program is
executed.
Just as with numbers, you can perform operations on string variables. The only
arithmetic string operator recognized by BASIC 7.0 is the plus sign ( + ) which is used
to perform concatenation of strings. When strings are concatenated, the string on the
right of the plus sign is appended to the string on the left, forming a third string. The
result can be printed immediately, used in a comparison, or assigned to a variable name.
If a string data item is compared with (or set equal to) a numeric item, or vice-versa, the
BASIC error message ?TYPE MISMATCH occurs. Some examples of string expressions and concatenation are:
10 A$ = " F I L E " : B$ = " N A M E "
20 NAM$ = A$ + B$
(yields the string " F I L E N A M E " )
3 0 R E S $ - " N E W " + A$ + B$ (yieldsthestring "NEWFILENAME")

ORGANIZATION OF THE
BASIC 7,0 ENCYCLOPEDIA
This section of Chapter 2 lists BASIC 7.0 language elements in an encyclopedia
format. It provides an abbreviated list of the rules (syntax) of Commodore 128
BASIC 7.0, along with a concise description of each. Consult the Commodore 128
System Guide BASIC 7.0 Encyclopedia (Chapter 5) included with your computer for a

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

more detailed description of each command. BASIC 7.0 includes all the elements of
BASIC 2.0.
The different types of BASIC operations are listed in individual sections, as
follows:
1.

2.
3.

Commands and Statements: the commands used to edit, store and erase
programs, and the BASIC program statements used in the numbered lines of a
program.
Functions: the string, numeric and print functions.
Reserved Words and Symbols: the words and symbols reserved for
use by the BASIC 7.0 language, which cannot be used for any other
purpose.

COMMAND AND
STATEMENT FORMAT
The command and statement definitions in this encyclopedia are arranged in the following format:

Command name

AUTO

Brief definition

Enable/disable automatic line numbering

Command formatDiscussion of
format and use

AUTO [line#]
This command turns on the automatic line-numbering feature.
This eases the job of entering programs, by automatically typing
the line numbers for the user. As each program line is entered by
pressing RETURN, the next line number is printed on the screen,
and the cursor is positioned two spaces to the right of the line
number. The line number argument refers to the desired increment between line numbers. AUTO without an argument turns off
the auto line numbering, as does RUN. This statement can be
used only in direct mode (outside of a program).

EXAMPLES:
AUTO 10

Automatically numbers program lines in increments of 10.

AUTO 50

Automatically numbers lines in increments of 50.

Example(s)-

AUTO

Turns off automatic line numbering.

25

26

COMMODORE 128

The boldface line that defines the format consists of the following elements:
DLOAD "program name" [,D0,U8]

keyword

argument

The parts of the command

capital letters. Words the
capitalized.
When quote marks ( "
user should include them in

additional arguments
(possibly optional)

or statement that must be typed exactly as shown are in

user supplies, such as the name of a program, are not
" ) appear (usually around a program name or filename), the
the appropriate place, according to the format example.

Keywords are words that are part of the BASIC language. They are the central part of a
command or statement, and they tell the computer what kind of action to take.
These words cannot be used as variable names. A complete list of reserved words
and symbols is given at the end of this chapter.
Keywords, also called reserved words, appear in upper-case letters. Keywords may be typed using the full word or the approved abbreviation. (A full list
of abbreviations is given in Appendix I). The keyword or abbreviation must be
entered correctly or an error will result. The BASIC and DOS error messages are
defined in Appendices A and B, respectively.
Arguments, also called parameters, appear in lower-case letters. Arguments complement keywords by providing specific information to the command or statement.
For example, the keyword LOAD tells the computer to load a program while the
argument "program name" tells the computer which specific program to load. A
second argument specifies from which drive to load the program. Arguments
include filenames, variables, line numbers, etc.
Square Brackets [ ] show optional arguments. The user selects any or none of the
arguments listed, depending on requirements.
Angle Brackets < > indicate the user MUST choose one of the arguments listed.
A Vertical Bar | separates items in a list of arguments when the choices are limited to
those arguments listed. When the vertical bar appears in a list enclosed in
SQUARE BRACKETS, the choices are limited to the items in the list, but the
user still has the option not to use any arguments. If a vertical bar appears within
angle brackets, the user MUST choose one of the listed arguments.
Ellipsis . . . (a sequence of three dots) means an option or argument can be repeated more
than once.
Quotation Marks " " enclose character strings, filenames and other expressions.
When arguments are enclosed in quotation marks, the quotation marks must be
included in the command or statement. In this encyclopedia, quotation marks are
not conventions used to describe formats; they are required parts of a command or
statement.
Parentheses ( ) When arguments are enclosed in parentheses, they must be included in
the command or statement. Parentheses are not conventions used to describe
formats; they are required parts of a command or statement.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

Variable refers to any valid BASIC variable names, such as X, A$, T%, etc.
Expression refers to any valid BASIC expressions, such as A + B + 2,.5*(X + 3),
etc.

NOTE: For all DOS commands, variables and expressions used as

arguments must be endorsed in parentheses.

BASIC COMMANDS AND

STATEMENTS
APPEND
Append data to the end of a sequential file
APPEND #logical file number,'Tilename"[,Ddrive number][<ON|,>Udevice]
EXAMPLES:
Append # 8, " M Y F I L E "

OPEN logical file 8 calied " M Y F I L E " , and prepare

to append with subsequent PRINT # statements.

Append #7,(A$),D0,U9

OPEN logical file named by the variable in A$ on

drive 0, device number 9, and prepare to APPEND.

AUTO
Enable/disable automatic line numbering
AUTO [line#]
EXAMPLES:
AUTO 10
AUTO 50
AUTO

Automatically numbers program lines in increments of 10.

Automatically numbers lines in increments of 50.
Turns off automatic line numbering.

BACKUP
Copy the entire contents from one disk to another on a dual disk drive
BACKUP source Ddrive number TO destination Ddrive number [ < O N | , >
Udevice]

NOTE: This command can be used only with a dual-disk drive.

27

28

C O M M O D O R E 128

EXAMPLES:
BACKUP DO TO D1

Copies all files from the disk in drive 0 to the disk

in drive 1, in dual disk drive unit 8.

BACKUP DO TO D1 ON U9

Copies all files from drive 0 to drive 1, in disk

drive unit 9.

BANK
Select one of the 16 BASIC banks (default memory configurations), numbered 0-15 to
be used during PEEK, POKE, SYS, and WAIT commands.
BANK bank number
Here is a table of available BANK configurations in the Commodore 128 memory:
BANK

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

CONFIGURATION

RAM(0) only
RAM(1) only
RAM(2) only (same as 0)
RAM(3) only (same as 1)
Internal ROM , RAM(0), I/O
Internal ROM , RAM(1), I/O
Internal ROM , RAM(2), I/O (same as 4)
Internal ROM , RAM(3), I/O (same as 5)
External ROM , RAM(0), I/O
External ROM , RAM(1), I/O
External ROM , RAM(2), I/O (same as 8)
External ROM , RAM(3), I/O (same as 9)
Kernal and Internal ROM (LOW), RAM(0), I/O
Kernal and External ROM (LOW), RAM(0), I/O
Kernal and BASIC ROM, RAM(0), Character ROM
Kernal and BASIC ROM, RAM(0), I/O

Banks are described in detail in Chapter 8, The Power Behind Commodore 128
Graphics and Chapter 13, The Commodore 128 Operating System.

BEGIN / BEND
A conditional statement like IF . . . THEN: ELSE, structured so that you can include
several program lines between the start (BEGIN) and end (BEND) of the structure.
Here's the format:

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

IF condition THEN BEGIN : statement

statement
statement BEND : ELSE BEGIN
statement
statement BEND
EXAMPLE
10 IF X = 1 THEN BEGIN: PRINT " X = 1 is True"
20 PRINT " S o this part of the statement is performed"
30 PRINT "When X equals 1"
40 BEND: PRINT "End of BEGlN/BEND structure":GO to 60
50 PRINT " X does not equal l":PRINT "The statements between BEGIN/
BEND are skipped"
60 PRINT "Rest of Program"

BLOAD
Load a binary file starting at the specified memory location
BLOAD "filename"[,Ddrive number][<ONI,U>device number] [,Bbank
number] [,Pstart address]
where:

filename is the name of your file

bank number selects one of the 16 BASIC banks (default memory configurations)

start address is the memory location where loading begins

EXAMPLES:
BLOAD "SPRITES", B0, P3584
BLOAD " D A T A 1 " , D0, U8, B1, P4096

LOADS the binary file " S P R I T E S "

starting in location 3584 (in BANK 0).
LOADS the binary file "DATA 1"
into location 4096 (BANK 1) from
Drive 0, unit 8.

BOOT
Load and execute a program which was saved as a binary file
BOOT "filename''[,Ddrive number][<ON|,>Udevice][,Palt LOAD ADD]
EXAMPLE:
BOOT

BOOT a bootable disk (CP/M Plus for example).

29

30

COMMODORE 128

BOOT "GRAPHICS 1", D0, U9

LOADS the binary program "GRAPHICS 1"

from unit 9, drive 0, and executes it.

BOX
Draw box at specified position on screen
BOX [color source], XI, Yl[,X2,Y2][,angle][,paint]
where:
color source

0 = Background color
1 = Foreground color (DEFAULT)
2 = Multi-color 1
3 = Multi-color 2

X1,Y1

Corner coordinate (scaled)

X2,Y2

Corner diagonally opposite X I , Y1, (scaled); default is the PC

location.

angle

Rotation in clockwise degrees; default is 0 degrees

paint

Paint shape with color

0 = Do not paint
1 = Paint
(default = 0)

EXAMPLES:
BOX 1, + 10, + 10

BOX 1, 10, 10, 60, 60

BOX , 10, 10, 60, 60, 45, 1
BOX , 30, 90, , 45, 1

Draw a box 10 pixels to the right and 10 down from

the current pixel cursor location.
Draws the outline of a rectangle.
Draws a painted, rotated box (a diamond).
Draws a filled, rotated polygon.

Any parameter can be omitted but you must include a comma in its place, as in the last
two examples.

NOTE: Wrapping occurs if the degree is greater than 360.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

BSAVE
Save a binary file from the specified memory locations
BSAVE "fflename"[,Ddrive number][<ONI,U>device number] [,Bbank
number],Pstart address TO Pend address
where:

start address is the starting address where the program is SAVEd from

end address is the last address 4- 1 in memory which is SAVEd

This is similar to the SAVE command in the Machine Language MONITOR.

EXAMPLES:
BSAVE "SPRITE DATA",B0,
P3584 TO P4096
BSAVE "PROGRAM.SCR",DO,
U9,B0,P3182 TO P7999

Saves the binary file named "SPRITE DATA",

starting at location 3584 through 4095 (BANK
0).

Saves the binary file named "PROGRAM.

S C R " in the memory address range 3182
through 7999 (BANK 0) on drive 0, unit 9.

CATALOG
Display the disk directory
CATALOG [Ddrive number][<ON|,>Udevice number][,wildcard string]
EXAMPLE:
CATALOG

Displays the disk directory on drive 0.

CHAR
Display characters at the specified position on the screen
CHAR [color source],X,Y[,string][,RVS]
This is primarily designed to display characters on a bit mapped screen, but it can also
be used on a text screen. Here's what the parameters mean:
color source

0 = Background
1 = Foreground
Character column (0-39) (VIC screen)
(0-79) (8563) screen

31

32

COMMODORE 128

Y
string
reverse

Character row (0-24)

String to print
Reverse field flag (0 = off, 1 = on)

EXAMPLE:
10
20
30
30

COLOR 2,3: REM MULTI-COLOR 1 = RED

COLOR 3,7: REM MULTI-COLOR 2 = BLUE
GRAPHIC 3,1
CHAR 0,10,10, " T E X T " , 0

CIRCLE
Draw circles, ellipses, arcs, etc., at specified positions on the screen
CIRCLE [color source],X,Y[,Xr][,Yr] [,sa][,ea][,angle][,inc]
where:
color source

0 = background color
1 = foreground color
2 = multi-color 1
3 - multi-color 2

X,Y

Center coordinate of the CIRCLE

Xr

X radius (scaled); (default = 0)

Yr

Y radius (sealed default is Xr)

sa

Starting arc angle (default 0 degrees)

ea

Ending arc angle (default 360 degrees)

angle
inc

Rotation is clockwise degrees (default is 0 degrees)

Degrees between segments (default is 2 degrees)

EXAMPLES:

o:

CIRCLE1, 160,100,65,10

Draws an ellipse.

CIRCLE1, 160,100,65,50

Draws a circle.

sa

ea

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

ClRCLEl, 60,40,20,18,,,,45

Draws an octagon.

CIRCLE1, 260,40,20,,,,,90

Draws a diamond.

CIRCLE1, 60,140,20,18,,,, 120

Draws a triangle.

CIRCLE 1, + 2, + 2,50,50

Draws a circle (two pixels down and two to the

right) relative to the original coordinates of the
pixel cursor.

C1RCLE1, 30;90

Draws a circle 30 pixels and 90 degrees to the

right of the current pixel cursor coordinate
position.

You may omit a parameter, but you must still place a comma in the appropriate
position. Omitted parameters take on the default values.

CLOSE
Close logical file
CLOSE file number
EXAMPLE:
CLOSE 2

Logical file 2 is closed.

CLR
Clear program variables
CLR

CMD
Redirect screen output to a logical disk or print file.
CMD logical file number [,write list]
EXAMPLE:
OPEN 1,4
CMD 1
LIST

Opens device 4 (printer).

All normal output now goes to the printer.
The LlSTing goes to the printer, not the screeneven the word
READY.

PRINT#1

Sends output back to the screen.

CLOSE 1

Closes the file.

33

34

COMMODORE 128

COLLECT
Free inaccessible disk space
COLLECT [Ddrive number][<ON|,>Udevice]
EXAMPLE:
COLLECT DO

Free all available space which has been incorrectly allocated to

improperly closed files. Such files are indicated with an asterisk
on the disk directory.

COLLISION
Define handling for sprite collision interrupt
COLLISION type [,statement]
type
Type of interrupt, as follows:
1 = Sprite-to-sprite collision
2 = Sprite-to-display data collision
3 = Light pen (VIC screen only)
statement
BASIC line number of a subroutine
EXAMPLE:
Collision 1, 5000
Collision 1
Collision 2, 1000

Enables a sprite-to-sprite collision and program control sent to

subroutine at line 5000.
Stops interrupt action which was initiated in above example.
Enables a sprite-to-data collision and program control directed
to subroutine in line 1000.

COLOR
Define colors for each screen area
COLOR source number, color number
This statement assigns a color to one of the seven color areas:
AREA

SOURCE

0
1
2
3
4
5
6

40-column (VIC) background

40-column (VIC) foreground
multicolor 1
multicolor 2
40-column (VIC) border
character color (40- or 80-column screen)
80-column background color

BASIC BUILDING BLOCKS AND BASIC 7.0 ENCYCLOPEDIA

Colors that are usable are in the range 1-16.

COLOR CODE

COLOR

COLOR CODE

1
2
3
4
5
6
7
8

Black
White
Red
Cyan
Purple
Green
Blue
Yellow

9
10
11
12
13
14
15
16

COLOR

Orange
Brown
Light Red
Dark Gray
Medium Gray
Light Green
Light Blue
Light Gray

Color Numbers in 40-Column O u t p u t

1
2
3
4
5
6
7
8

Black
White
Dark Red
Light Cyan
Light Purple
Dark Green
Dark Blue
Light Yellow

9
10
11
12
13
14
15
16

Dark Purple
Dark Yellow
Light Red
Dark Cyan
Medium Gray
Light Green
Light Blue
Light Gray

Color Numbers in 80-Column O u t p u t

EXAMPLES:
COLOR 0, 1:

Changes background color of 40-column screen to black.

COLOR 5, 8:

Changes character color to yellow.

CONCAT
Concatenate two data files
CONCAT "file 2" [,Ddrive number] TO "fHe 1"
[,Ddrive number][<ON|,>Udevice]
EXAMPLE:
Concat "File B " to "File A "

FILE B is attached to FILE A, and the combined

file is designated FILE A.

Concat (A$) to (B$), D1, U9

The file named by B$ becomes a new file with

the same name with the file named by A$ attached to the end of B$. This is performed on
Unit 9, drive 1 (a dual disk drive).

35

36

COMMODORE 128

Whenever a variable is used as a filename, as in the last example, the filename variable
^ must be within parentheses.

CONT
Continue program execution
CONT

COPY
Copy a file from one drive to another within a dual disk drive. Copy one file to
another with a different name within a single drive
COPY [Ddrive number,]"source fiIename"TO[Ddrive
filename"[<ON|,>Udevice]

number,]"destination

NOTE: Copying between two single or double disk drive units cannot be
done. This command does not support unit-to-unit copying.

EXAMPLES:
COPY DO, "TEST" TO D1, "TEST PROG"

Copies " t e s t " from drive 0 to drive

1, renaming it "test prog" on drive 1.

COPY DO, " S T U F F " TO D1, " S T U F F "

Copies " S T U F F " from drive 0 to

drive 1.

COPY DO TO D1

Copies all files from drive 0 to drive

1.

COPY " W O R K . P R O G " TO " B A C K U P "

Copies " W O R K . P R O G " as a file

called "BACKUP" on the same disk
(drive 0).

DATA
Define data to be used by a program
DATA list of constants
EXAMPLE:
DATA 100, 200, FRED, "HELLO, M O M " , , 3, 14, ABC123

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

DCLEAR
Clear all open channels on disk drive
DCLEAR [Ddrive number][<ON|,>Udevice]
EXAMPLES:
DCLEAR D0
DCLEAR D l , U 9

Clears all open files on drive 0, device number 8.

Clears all open files (channels) on drive 1, device number 9.

DCLOSE
Close disk file
DCLOSE [#logical file number][<ON|,>Udevice]
EXAMPLES:
DCLOSE
DCLOSE # 2
DCLOSE ON U9

Closes all channels currently open on unit 8.

Closes the channel associated with the logical file number 2 on
unit 8.
Closes all channels currently open on unit 9.

DEF FN
Define a user function
DEF FN name (variable) = expression
EXAMPLE:
10 DEF FNA(X) 20 PRINT FNA(7)

12*(34.75-X/.3) + X

The number 7 is inserted each place X is located in the formula given in the DEF
statement. In the example above, the answer returned is 144.

NOTE: If you plan to define a function in a program that will use BASIC
7.0 graphics commands, invoke the GRAPHIC command before defining
your function. The portion of memory where functions are defined and
where the graphics screen is located is shared. Once you allocate your
graphics area, the function definitions are safely placed somewhere else
in memory. If you don't take this precaution and you invoke the GRAPHIC
command after you define a function, the function definition (between
$1C00 and $4000) is destroyed.

37

38

COMMODORE 128

DELETE
Delete lines of a BASIC program in the specified range
DELETE [first line] [-last line]
EXAMPLES:
DELETE 75
DELETE 10-50
DELETE-50
DELETE 75-

Deletes line 75.

Deletes lines 10 through 50, inclusive.
Deletes all lines from the beginning of the program up to and
including line 50.
Deletes all lines from 75 to the end of the program, inclusive.

DIM
Declare number of elements in an array
DIM variable (subscripts) [,variable(subscripts)] . . .
EXAMPLE:
10 DIM A$(40),B7(15),CC%(4,4,4)
Dimension three arrays where arrays A$, B7 and CC% have 41 elements, 16 elements
and 125 elements respectively.

DIRECTORY
Display the contents of the disk directory on the screen
DIRECTORY [Ddrive number][<ON|,>Udevice][,wildcardl
EXAMPLES:
DIRECTORY
DIRECTORY D1, U9, " W O R K "
DIRECTORY "AB*

DIRECTORY D0, " 7 . B A K "

Lists all files on the disk in unit 8.

Lists the file named " W O R K , " on drive 1 of
unit 9.
Lists all files starting with the letters " A B "
like ABOVE, ABOARD, etc. on unit 8. The
asterisk specifies a wild card, where all files
starting with " A B " are displayed.
The ? is a wild card that matches any single
character in that position. For example: FILE
l.BAK, FILE 2.BAK, FILE 3.BAK all match
the string.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

DIRECTORY Dl,U9,(A$)

LISTS the filename stored in the variable A$

on device number 9, drive 1. Remember, whenever a variable is used as a filename, put the
variable in parentheses.

NOTE: To print the DIRECTORY of the disk in drive 0, unit 8, use the
following example:
LOAD"$O",8
OPEN4,4:CMD4:LIST
PRINT#4:CLOSE4

DLOAD
Load a BASIC program from the disk drive, device 8.
DLOAD "filename" [,Ddrive number][<ON|,>Udevice number]
EXAMPLES:
DLOAD " B A N K R E C S "
DLOAD (A$)

Searches the disk for the program

and LOADS it.

"BANKRECS"

LOADS a program from disk in which the name is

stored in the variable A$. An error message is given if
A$ is null. Remember, when a variable is used as a
filename, it must be enclosed in parentheses.

DO / LOOP / WHILE / UNTIL / EXIT

Define and control a program loop
DO fUNTIL condition | WHILE condition]
statements [EXIT]
LOOP [UNTIL condition | WHILE condition]
This loop structure performs the statements between the DO statement and the LOOP
statement. If no UNTIL or WHILE modifies either the DO or the LOOP statement,
execution of the statements in between continues indefinitely. If an EXIT statement is
encountered in the body of a DO loop, execution is transferred to the first statement
following the LOOP statement. DO loops may be nested, following the rules defined by
the FOR-NEXT structure. If the UNTIL parameter is specified, the program continues
looping until the condition is satisfied (becomes true). The WHILE parameter is the
opposite of the UNTIL parameter; the program continues looping as long as the
condition is TRUE. As soon as the condition is no longer true, program control resumes
with the statement immediately following the LOOP statement. An example of a
condition (boolean argument) is A = 1, or G > 6 5 .

39

40

COMMODORE 128

EXAMPLES:
10
20
30
40
50
60

X - 25
DO UNTIL X - 0
X - X-1
PRINT " X = " ; X
LOOP
PRINT "End of Loop"

This example performs the statements X = X-1

and PRINT " X - '';X until X = 0 . W h e n X - 0the
program resumes with the PRINT "End of Loop"
statement immediately following LOOP.

10 DO WHILE A $ < > CHR$ (13):GETKEY A$:PRINT A$:LOOP

20 PRINT " T H E RETURN KEY HAS BEEN PRESSED"
This DO loop waits for a key to be pressed,
receives input from the keyboard one character at
a time and prints the letter of the key which is
pressed. If the RETURN key is pressed, control is
transferred out of the loop and line 20 is executed.
10
20
30
40
50
60

DOPEN # 8 , "SEQFILE"
DO
GET # 8 , A $
PRINT A$;
LOOP UNTIL ST
DCLOSE # 8

This program opens file " S E Q F I L E " and gets

data until the ST system variable indicates all data
is input.

DOPEN
Open a disk file for a read and/or write operation
DOPEN # logical f!le number,"fllename[,<type>]"[,Lrecord length]
[,Ddrive number][<ON|,>Udevice number][,W]
where type is:
S
P
U
R
L
W

=
=
=
=
=
=

Sequential File Type

Program File Type
User File Type
Relative File Type
Record Length = the length of records in a relative file only
Write Operation (if not specified a read operation occurs)

EXAMPLES:
DOPEN#l, "ADDRESS",W

Create the sequential file number 1 (ADDRESS)

for a write operation

DOPEN#2 "RECIPES",Dl,U9

Open the sequential file number 2 (RECIPES)

for a read operation on device number 9, drive 1

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

DRAW
Draw dots, lines and shapes at specified positions on the screen
DRAW [color source] [,X1, Yl][TO X2, Y2] . . .
where:
Color source

X1,Y1
X2,Y2

0 = Bit map background

1 - Bit map foreground
2 = Multi-color 1
3 = Multi-color 2
Starting coordinate (0,0 through 319,199)
Ending coordinate (0,0 through 319,199)

EXAMPLES:
DRAW 1, 100, 50

Draw a dot.

DRAW , 10,10 TO 100,60

Draw a line.

DRAW , 10,10 TO 10,60 TO 100,60 TO 10,10

Draw a triangle.

DRAW 1, 120;45

Draw a dot 45 relative and 120 pixels

away from the current pixel cursor
position.

DRAW

Draw a dot at the present pixel cursor

position. Use LOCATE to position the
pixel cursor.

You may omit a parameter but you still must include the comma that would have
followed the unspecified parameter. Omitted parameters take on the default values.

DSAVE
Save a BASIC program file to disk
DSAVE "filename" [,Ddrive number][<ON|,>Udevice number]
EXAMPLES:
DSAVE " B A N K R E C S "
DSAVE (A$)
DSAVE "PROG 3 " , D l , U 9

Saves the program " B A N K R E C S " to disk.

Saves the disk program named in the variable A$.
Saves the program " P R O G 3 " to disk on unit number 9, drive 1.

41

42

COMMODORE 128

DVERIFY
Verify the program in memory against the one on disk
DVERIFY "filename"[,Ddrive number][<ON|,>Udevice number]
To verify Binary data, see VERIFY "filename",8,l format, under VERIFY command
description.
EXAMPLES:
DVERIFY " C 1 2 8 "
DVERIFY "SPRITES'',D0,U9

Verifies program " C 1 2 8 " on drive 0, unit 8.

Verifies program "SPRITES" on drive 0, device 9.

END
Define the end of program execution
END

ENVELOPE
Define a musical instrument envelope
ENVELOPE n[,atk] [,dec] [,sus] [,re!][,wf] [,pw]
where:
n
atk
dec
sus
rel
wf

pw

Envelope number (0-9)

Attack rate (0-15)
Decay rate (0-15)
Sustain (0-15)
Release rate (0-15)
Waveform: 0 = triangle
1 = sawtooth
2 = variable pulse (square)
3 = noise
4 = ring modulation
Pulse width (0-4095)

See the " T " option in the PLAY command to select an envelope in a PLAY string.
EXAMPLE:
ENVELOPE 1, 10, 5, 10, 0, 2, 2048

This command sets envelope 1 to Attack

= 10, Decay = 5, Sustain = 10, Release
= 0, waveform = variable pulse (2), and
the pulse width = 2048

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

FAST
Sets the 8502 microprocessor at a speed of 2MHz.
FAST
This command initiates 2MHz mode, causing the VIC 40-column screen to be turned off.
All operations are speeded up considerably. Graphics may be used, but will not be visible
until a SLOW command is issued. The Commodore 128 powers up in lMHz mode. The
DMA operations (FETCH, SWAP, STASH) must be performed at lMHz (slow) speed.

FETCH
Get data from expansion (RAM module) memory
FETCH #bytes, intsa, expsa, expb
where bytes = Number of bytes to get from expansion memory (0-65535) where 0 =
64K (65535 bytes)
intsa = Starting address of host RAM (0-65535)
expb = 64K expansion RAM bank number (0-7) where expb = 0 - 1 for 128K
and expb = 0 - 7 for up to 512K.
expsa = Starting address of expansion RAM (0-65535)
The host BANK for the ROM and I/O configuration is selected with the BANK
command. The DMA(VIC) RAM bank is selected by bits 6 and 7 of the RAM
configuration register within the MMU($D506).

FILTER
Define sound (SID chip) filter parameters
FILTER [freq][,lp] [,bp] [,hp] [,res]
where:
freq
ip
bp
hp
res

Filter cut-off frequency (0-2047)

Low-pass filter on (1), off (0)
Band-pass filter on (1), off (0)
High-pass filter on (1), off (0)
Resonance (0-15)

Unspecified parameters result in no change to the current value.

EXAMPLES:
FILTER 1024,0,1,0,2

Set the cutoff frequency at 1024, select the band pass

filter and a resonance level of 2.

FILTER 2000,1,0,1,10

Set the cutoff frequency at 2000, select both the low

pass and high pass filters (to form a notch reject) and set
the resonance level at 10.

43

44

COMMODORE 128

FOR / TO / STEP / NEXT

Define a repetitive program loop structure.
FOR variable - start value TO end value [STEP increment] NEXT variable
The logic of the FOR/NEXT statement is as follows. First, the loop variable is set to the
start value. When the program reaches a program line containing the NEXT statement, it
adds the STEP increment (default = 1) to the value of the loop variable and checks to
see if it is higher than the end value of the loop. If the loop variable is less than or equal
to the end value, the loop is executed again, starting with the statement immediately
following the FOR statement. If the loop variable is greater than the end value, the loop
terminates and the program resumes immediately following the NEXT statement. The
opposite is true if the step size is negative. See also the NEXT statement.
EXAMPLE:
10
20
30
40

FOR L = 1 TO 10
PRINT L
NEXT L
PRINT " I ' M DONE! L =

"L

This program prints the numbers from one to 10 followed by the message I'M DONE!
L - 11.
EXAMPLE:
10
20
30
40

FOR L - 1 TO 100
FOR A - 5 TO 11 STEP .5
NEXT A
NEXT L

The FOR . . . NEXT loop in lines 20 and 30 are nested inside the one in line 10 and 40.
Using a STEP increment of .5 is used to illustrate the fact that floating point indices are
valid. The inner rested loop must lie completely within the outer rested loop (lines 10
and 40).

GET
Receive input data from the keyboard, one character at a time, without waiting for a key
to be pressed.
GET variable list
EXAMPLE:
10 DO:GETA$:LOOP UNTIL A$ = " A "

This line waits for the A key to be

pressed to continue.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

20 GET B, C, D

GET numeric variables B,C and D from the keyboard without

waiting for a key to be pressed.

GETKEY
Receive input data from the keyboard, one character at a time and wait for a key to be
pressed.
GETKEY variable list
EXAMPLE:
10 GETKEY A$
This line waits for a key to be pressed. Typing any key continues the program.
10 GETKEY A$,B$,C$
This line waits for three alphanumeric characters to be entered from the keyboard.

GET#
Receive input data from a tape, disk or RS232
G E T # logical file number, variable list
EXAMPLE:
10 G E T # l , A $

This example receives one character, which is stored in the

variable A$, from logical file number 1. This example assumes
that file 1 was previously opened. See the OPEN statement.

G064
Switch to C64 mode
G064
To return to C128 mode, press the reset button, or turn off the computer power and
turn it on again.

GOSUB
Call a subroutine from the specified line number
GOSUB line number
EXAMPLE:
20 GOSUB 800

This example calls the subroutine beginning at line 800 and executes
it. All subroutines must terminate with a RETURN statement.

45

46

C O M M O D O R E 128

800 PRINT " T H E C128 WAS WORTH THE WAIT!": RETURN

GOTO / GO TO
Transfer program execution to the specified line number
GOTO line number
EXAMPLES:
10 PRINT 4 'COMMODORE''
20 GOTO 10

The GOTO in line 20 makes line 10 repeat continuously until RUN/STOP is pressed.

GOTO 100

Starts (RUNs) the program starting at line 100,

without clearing the variable storage area.

GRAPHIC
Select a graphic mode
1) GRAPHIC mode [,clear][,s]
2) GRAPHIC CLR
This statement puts the Commodore 128 in one of the six graphic modes:
MODE

DESCRIPTION

0
1
2
3
4
5

40-eolumn text (default)

standard bit-map graphics
standard bit-map graphics (split screen)
multi-color bit-map graphics
multi-color bit-map graphics (split screen)
80-column text

EXAMPLES:
GRAPHIC 1,1
GRAPHIC 4,0,10

Select standard bit map mode and clear the bit map.
Select split screen multi-color bit map mode, do not clear the
bit map and start the split screen at line 10.

GRAPHIC 0

Select 40-column text.

GRAPHIC 5

Select 80-column text.

GRAPHIC CLR

GSHAPE
See SSHAPE.

Clear and deallocate the bit map screen.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

HEADER
Format a diskette
HEADER "diskname" [,1 i.d.] [,Ddrive number]
[<ON|,>Udevice number]
Before a new disk can be used for the first time, it must be formatted with the HEADER
command. The HEADER command can also be used to erase a previously formatted
disk, which can then be reused.
When you enter a HEADER command in direct mode, the prompt ARE YOU
SURE? appears. In program mode, the prompt does not appear.
The HEADER command is analogous to the BASIC 2.0 command:
OPEN l,8,15,"N0:diskname,i.d."
EXAMPLES:
HEADER "MYDISK",I23, D0

This headers " M Y D I S K " using i.d. 23

on drive 0, (default) device number 8.

HEADER " R E C S " , 145, D1 ON U9

This headers " R E C S " using i.d. 45, on

drive 1, device number 9.

HEADER "C128 PROGRAMS", D0

HEADER (A$),I76,D0,U9

This is a quick header on drive 0, device

number 8, assuming the disk in the drive
was already formatted. The old i.d. is
used.
This example headers the diskette with
the name specified by the variable A$,
and the i.d. 76 on drive 0, device number 9.

HELP
Highlight the line where the error occurred
HELP
The HELP
is typed in
containing
line where

command is used after an error has been reported in a program. When HELP
40-column format, the line where the error occurs is listed, with the portion
the error displayed in reverse field. In 80-column format, the portion of the
the error occurs is underlined.

IF / THEN / ELSE
Evaluate a conditional expression and execute portions of a program depending on the
outcome of the expression

47

48

COMMODORE 128

IF expression THEN statements [:ELSE

else-clause]

THE IF . . . THEN statement evaluates a BASIC expression and takes one of two
possible courses of action depending upon the outcome of the expression. If the
expression is true, the statement(s) following THEN is executed. This can be any
BASIC statement or a line number. If the expression is false, the program resumes with
the program line immediately following the program line containing the IF statement,
unless an ELSE clause is present. The entire IF . . . THEN statement must be contained
within 160 characters. Also see BEGIN/BEND.
The ELSE clause, if present, must be on the same line as the IF . . . THEN
portion of the statement, and separated from the THEN clause by a colon. When an
ELSE clause is present, it is executed only when the expression is false. The expression
being evaluated may be a variable or formula, in which case it is considered true if
nonzero, and false if zero. In most cases, there is an expression involving relational
operators ( , < , > , < = , > = , < > ) .
EXAMPLE:
50 IF X > 0 THEN PRINT " O K " : ELSE END
This line checks the value of X. lf X is greater than 0, the statement immediately
following the keyword THEN (PRINT " O K " ) is executed and the ELSE clause is
ignored. If X is less than or equal to 0, the ELSE clause is executed and the statement
immediately following THEN is ignored.
10 IF X = 10 THEN 100
This example evaluates the value of X.
20 PRINT " X DOES NOT EQUAL 10" IF X equals 10, the program control is
transferred to line 100 and the message
99 STOP
" X EQUALS 10" is printed. IF X
100 PRINT " X EQUALS 10"
does not equal 10, the program resumes with line 20, the C128 prints the
prompt " X DOES NOT EQUAL 10"
and the program stops.

INPUT
Receive a data string or a number from the keyboard and wait for the user to press
RETURN
INPUT ["prompt string";] variable list
EXAMPLE:
10 INPUT "PLEASE TYPE A NUMBER";A
20 INPUT "AND YOUR NAME";A$
30 PRINT A$ " YOU TYPED THE NUMBER";A

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

INPUT #
Input data from an I/O channel into a string or numeric variable
I N P U T # file number, variable list
EXAMPLE:
10 OPEN 2,8,2
20 INPUT#2, A$, C, D$
This statement INPUTs the data stored in variables A$, C and D$ from the disk file
number 2, which was OPENed in line 10.

KEY
Define or list function key assignments
KEY [key number, string]
The maximum length for all the definitions together is 241 characters, (p. 3-41)
EXAMPLE:
KEY 7, " G R A P H I C 0 " + CHR$(13) + " L I S T " + CHR$(13)
This tells the computer to select the (VIC) text screen and list the program whenever the
F7 key is pressed (in direct mode). CHR$(13) is the ASCII character for RETURN and
performs the same action as pressing the RETURN key. Use CHR$(27) for ESCape.
Use CHR$(34) to incorporate the double quote character into a KEY string. The keys
may be redefined in a program. For example:
10 KEY 2,"PRINT D S $ " + CHR$(13)
This tells the computer to check and display the disk drive error channel variables
(PRINT DS$) each time the F2 function key is pressed.
10
20
30
40

FOR
KEY
FOR
KEY

1= 1 to 7 STEP 2
I, CHR$(I + 132):NEXT
I = 2 to 8 STEP 2
I, CHR$(I + 132):NEXT

This defines the function keys as they are defined on the Commodore 64.

LET
Assigns a value to a variable
[LET] variable = expression
EXAMPLE:
10 LET A = 5

Assign the value 5 to numeric variable A.

49

50

COMMODORE 128

20 B = 6

Assign the value 6 to numeric variable B.

30 C = A * B + 3

Assign the numeric variable C, the value resulting from 5

times 6 plus 3.

40 D$ = " H E L L O "

Assign the string " H E L L O " to string variable D$.

LIST
List the BASIC program currently in memory
LIST [first line] [- last line]
In C128 mode, LIST can be used within a program without terminating program execution.
EXAMPLES:
LIST

Shows

LIST 100-

Shows

LIST 10

Shows

LIST - 1 0 0

Shows

LIST 10-200

Shows

LOAD
Load a program from a peripheral device such as the disk drive or Datassette
LOAD "filename" [,device number] [,relocate flag]
This is the command used to recall a program stored on disk or cassette tape. Here, the
filename is a program name up to 16 characters long, in quotes. The name must be
followed by a comma (outside the quotes) and a number which acts as a device number
to determine where the program is stored (disk or tape). If no number is supplied, the
Commodore 128 assumes device number 1 (the Datassette tape recorder).
EXAMPLES:
LOAD

Reads in the next program from tape.

LOAD " H E L L O "

Searches tape for a program called HELLO, and

LOADs it if found.

LOAD (A$),8

LOADs the program from disk whose name is

stored in the variable A$.

LOAD"HELLO",8

Looks for the program called HELLO on disk drive

number 8, drive 0. (This is equivalent to DLOAD
"HELLO").

LOAD"MACHLANG",8,l

LOADs the machine language program called

" M A C H L A N G " into the location from which it
was SAVEd.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

LOCATE
Position the bit map pixel cursor on the screen
LOCATE X,Y
The LOCATE statement places the pixel cursor (PC) at any specified pixel coordinate on
the screen.
The pixel cursor (PC) is the coordinate on the bit map screen where drawing of
circles, boxes, lines and points and where PAINTing begins.
EXAMPLE:
LOCATE 160,100

Positions the PC in the center of the bit map screen. Nothing will be seen until something is drawn.

LOCATE +20,100

Move the pixel cursor 20 pixels to the right of the last PC

position and place it at Y coordinate 100.

LOCATE - 3 0 , + 20

Move the PC 30 pixels to the right and 20 down from the

previous PC position.

The PC can be found by using the RDOT(O) function to get the X-coordinate and
RDOT(l) to get the Y-coordinate. The color source of the pixel at the PC can be found
by PRINTing RDOT(2).

MONITOR
Enter the Commodore 128 machine language monitor
MONITOR
See Chapter 6 for details on the Commodore 128 Machine Language Monitor.

MOVSPR
Position or move sprite on the screen
1) MOVSPR number,X,Y
2) MOVSPR number, + / - X , + / - Y
3) MOVSPR number,X;Y

Place the specified sprite at absolute

sprite coordinate X,Y.
Move sprite relative to the position
of the sprite's current position.
Move sprite distance X at angle Y
relative to the sprite's current position.

51

52

COMMODORE 128

4) MOVSPR number, angle # speed

Move sprite at an angle relative to

its current coordinate, in the clockwise direction and at the specified
speed.

where:
number is sprite's number (1 through 8)
X,Y is coordinate of the sprite location.
angle is the angle (0-360) of motion in the clockwise direction relative to the
sprite's original coordinate.
speed is a speed (0-15) in which the sprite moves.
This statement moves a sprite to a specific location on the screen according to
the SPRITE coordinate plane (not the bit map plane) or initiates sprite motion at a
specified rate. See MOVSPR in Chapter 9 for a diagram of the sprite coordinate
system.
EXAMPLES:
MOVSPR 1,150,150

Position sprite 1 near the center of the screen, x,y

coordinate 150,150.

MOVSPR 1, + 20,-30

Move sprite 1 to the right 20 coordinates and up 30

coordinates.

MOVSPR 4, - 5 0 , + 100

Move sprite 4 to the left 50 coordinates and down 100

coordinates.

MOVSPR 5, 45 # 1 5

Move sprite 5 at a 45 degree angle in the clockwise

direction, relative to its original x and y coordinates.
The sprite moves at the fastest rate (15).

NOTE: Once you specify an angle and a speed as in the fourth example
of the MOVSPR statement, the sprite continues on its path (even if the
sprite display is disabled) after the program stops, until you set the speed
to 0 or press RUN/STOP and RESTORE. Also, keep in mind that the
SCALE command affects the MOVSPR coordinates. If you add SCALing
to your programs, you also must adjust the sprites' new coordinates so
they appear correctly on the screen.

NEW
Clear (erase) BASIC program and variable storage
NEW

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

ON
Conditionally branch to a specified program line number according to the results of the
specified expression
ON expression <GOTO/GOSUB> line # 1 [, line # 2 , . . .]
EXAMPLE:
10
20
25
30
40
50
60

INPUT X:IF X < 0 THEN 10

ON X GOTO 30, 40, 50, 60
STOP
PRINT " X - 1"
PRINT " X = 2 "
PRINT " X - 3 "
PRINT " X = 4 "

When X = 1, ON sends control to the first line

number in the list (30). When X = 2, ON sends
control to the second line (40), etc.

OPEN
Open files for input or output
OPEN logieal file number, device number [,secondary address] [<,"filename
[,f!letype[, [mode"]]|<,cmd string>]
EXAMPLES:
10 OPEN 3,3

OPEN the screen as file number

3.

20 OPEN 1,0

OPEN the keyboard as file number 1.

30 OPEN l , l , O , " D O T "

OPEN the cassette for reading, as

file number 1, using " D O T " as
the filename.

OPEN 4,4

OPEN the printer as file number 4.

OPEN 15,8,15

OPEN the command channel on

the disk as file 15, with secondary
address 15. Secondary address 15
is reserved for the disk drive error
channel.

5 OPEN 8,8,12,"TESTFILE,S,W"

OPEN a sequential disk file for

writing called TESTFILE as file
number 8, with secondary address
12.

53

54

COMMODORE 128

See also: CLOSE, CMD, G E T # , INPUT#, and PRINT# statements and system
variables ST, DS, and DS$.

PAINT
Fill area with color
PAINT [color source],X,Y[,mode]
where:
color source

0
1
2
3

=
=
=
=

bit map foreground

bit map background (default)
multi-color 1
multi-color 2

X,Y

starting coordinate, scaled (default at pixel cursor (PC))

mode

0 = paint an area defined by the color source selected

1 = paint an area defined by any nonbackground source

The PAINT command fills an area with color. It fills in the area around the specified
point until a boundary of the same specified color source is encountered. For example, if
you draw a circle in the foreground color source, start PAINTing the circle where the
coordinate assumes the background source. The Commodore 128 will only PAINT
where the specified source in the PAINT statement is different from the source of the x
and y pixel coordinate. It cannot PAINT points where the sources are the same in the
PAINT statement and the specified coordinate. The X and Y coordinate must lie
completely within the boundary of the shape you intend to PAINT, and the source of the
starting pixel coordinate and the specified color source must be different.
EXAMPLE:
10 CIRCLE 1, 160,100,65,50

Draws an outline of a circle.

20 PAINT 1, 160,100

Fills in the circle with color from source 1 (VIC

foreground), assuming point 160,100 is colored in
the background color (source 0).

10 BOX 1, 10, 10, 20, 20

Draws an outline of a box.

20 PAINT 1, 15, 15

Fills the box with color from source l, assuming

point 15,15 is colored in the background source
(0).

30 PAINT 1, + 10, + 10

PAINT the screen in the foreground color source

at the coordinate relative to the pixel cursor's
previous position plus 10 in both the vertical and
horizontal positions.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

100 PAINT 1, 100;90

Paint the screen area 90 relative to and 100

pixels away from the current pixel cursor coordinate.

PLAY
Defines and plays musical notes and elements within a string or string variable.
PLAY "Vn,On,Tn,Un,Xn,elements, notes"
where the string or string variable is composed of the following
Vn = Voice (n = 1-3)
On = Octave (n = 0-6)
Tn = Tune Envelope Defaults (n = 0-9)
0 = piano
1 = accordion
2 = calliope
3 = drum
4 = flute
5 = guitar
6 = harpsichord
7 = organ
8 = trumpet
9 = xylophone
Un = Volume (n = 0-8)
Xn = Filter on (n = 1), off(n = 0)
notes:
A,B,C,D,E,F,G
elements:
#
Sharp
$
Flat
W
Whole note
H
Half note
Q
Quarter note
I
Eighth note
S
Sixteenth note
Dotted
R
Rest
M
Wait for all voices currently playing to end
the current "measure"
The PLAY statement gives you the power to select voice, octave and tune envelope
(including ten predefined musical instrument envelopes), the volume, the filter, and the
notes you want to PLAY. All these controls are enclosed in quotes. You may include
spaces in a PLAY string for readability.
All elements except R and M precede the musical notes in a PLAY string.

55

56

COMMODORE 128

EXAMPLES:
PLAY ' ' V 1 0 4 T 0 U 5 X 0 C D E F G A B ' '

Play the notes C , D , E , F , G , A and B

in voice 1, octave 4, tune envelope
0 (piano), at volume 5, with the
filter off.

PLAY " V 3 0 5 T 6 U 7 X 1 # B $ A W . C H D Q E I F ' '

Play the notes B-sharp, A-flat, a

whole dotted-C note, a half D-note,
a quarter E-note and an eighth
F-note.

A$ = " V 3 0 5 T 6 U 3 A B C D E " : PLAY A$

PLAY the notes and elements within

A$.

PLAY ' 4 V l C V 2 E V 3 G ' '

Plays a chord in the default setting.

POKE
Change the contents of a RAM memory location
POKE address, value
EXAMPLE:
10 POKE 53280,1

Changes VIC border color

PRINT
Output to the text screen
PRINT [print list]
The word PRINT can be followed by any of the following:
Characters inside quotes
Variable names
Functions
Expressions
Punctuation marks

( ' ' text'')

(A, B, A$, X$)
(SIN(23), ABS(33))
(2 + 2),A + 3,A = B)
(;,)

EXAMPLES:
10 PRINT " H E L L O "
20A$ ="THERE":PRINT "HELLO";A$
30 A - 4:B = 2:?A + B
40 J = 41:PRINT J;:PRINT J - 1
50 PRINT A;B;:D = A + B:PRINT D;A-B
See also POS, SPC, TAB and CHAR functions.

RESULTS

HELLO
HELLO THERE

6
41 40
4 2 6

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

PRINT#
Output data to files
P R I N T # file number[, print list]
P R I N T # is followed by a number which refers to the data file previously OPENed.
EXAMPLE:
10 OPEN 4,4
20 P R I N T # 4 , " H E L L O T H E R E ! " , A $ , B $

Outputs the data " H E L L O T H E R E "

and the variables A$ and B$ to the
printer.

10 OPEN 2,8,2
20 P R I N T # 2 , A , B $ , C , D

Outputs the data variables A, B$, C

and D to the disk file number 2.

NOTE: The P R I N T # command is used by itself to close the channel to

the printer before closing the file, as follows:
10
30
40
50

OPEN 4,4
PRINT#4, "PRINT WORDS"
PRINT#4
CLOSE 4

PRINT USING
Output using format
PRINT [#fiIe number,] USING"format list"; print list
This statement defines the format of string and numeric items for printing to the text
screen, printer or other device.
EXAMPLE:
5 X = 32: Y = 100.23: A$ = " C A T "
10 PRINT USING " $ # # . # # # " ; 1 3 . 2 5 , X , Y
20 PRINT USING " # # # > # " ; " C B M " , A $
When this is RUN, line 10 prints:
$13.25 $32.00

$*****

Five asterisks (*****) are printed instead of a Y

value because Y has five digits, and this condition
does not conform to format list (as explained below).

Line 20 prints this:

CBM

CAT

Leaves two spaces before printing " C B M " as defined in format list.

57

58

COMMODORE 128

The pound sign ( # ) reserves room for a single character in the output field. If the data
item contains more characters than there are # signs in the format field, the entire field
is filled with asterisks (*): no characters are printed.
EXAMPLE:
10 PRINT USING " # # # # " ; X
For these values of X, this format displays:
A - 12.34
A = 567.89
A = 123456

12
568
****

For a STRING item, the string data is truncated at the bounds of the field. Only as many
characters are printed as there are pound signs ( # ) in the format item. Truncation occurs
on the right.
EXAMPLES:
FIELD

EXPRESSION

RESULT

COMMENT

##.#
##.#

-.1

^).1

Leading zero added.

1.0

Trailing zero added.

####

-100.5

-101

Rounded to no decimal places.

####

-1000

****

Overflow because four digits and a minus sign

cannot fit in field.

###.

10

10.

Decimal point added.

#$##

$1

Floating dollar sign.

PUDEF
Redefine symbols in PRINT USING statement
PUDEF " n n n n "
Where " n n n n " is any combination of characters, up to four in all. PUDEF allows you to
redefine any of the following four symbols in the PRINT USING statement: blanks, commas,
decimal points and dollar signs. These four symbols can be changed into some other character by placing the new character in the correct position in the PUDEF control string.
Position 1 is the filler character. The default is a blank. Place a new character here
for another character to appear in place of blanks.
Position 2 is the comma character. Default is a comma.
Position 3 is the decimal point. Default is a decimal point.
Position 4 is the dollar sign. Default is a dollar sign.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

EXAMPLES:
10 P U D E F " * "
20 P U D E F " < "

PRINT * in the place of blanks.

PRINT < in the place of commas.

READ
Read data from DATA statements and input it into a numeric or string variable)
READ variable list
This statement inputs information from DATA statements and stores it in variables,
where the data can be used by the RUNning program.
In a program, you can READ the data and then re-read it by issuing the
RESTORE statement. The RESTORE sets the sequential data pointer back to the
beginning, where the data can be read again. See the RESTORE and DATA statements.
EXAMPLES:
10 READ A, B, C
20 DATA 3, 4, 5

READ the first three numeric variables from

the closest data statement.

10 READ A$, B$, C$

20 DATA JOHN, PAUL, GEORGE

READ the first three string variables from

the nearest data statement.

10 READ A, B$, C
20 DATA 1200, NANCY, 345

READ (and input into the C128 memory) a

numeric variable, a string variable and another numeric variable.

RECORD
Position relative file pointers
R E C O R D # logical file number, record number [,byte number]
This statement positions a relative file pointer to select any byte (character) of any
record in the relative file.
When the record number value is set higher than the last record number in the file,
the following occurs:
For a write ( P R I N T # ) operation, additional records are created to expand the file
to the desired record number.
For a read ( I N P U T # ) operation, a null record is returned and a " R E C O R D NOT
PRESENT ERROR occurs". See your disk drive manual for details about relative
files.
EXAMPLES:
10
20
30
40

DOPEN#2,"FILE"
RECORD#2,10,1
PRINT#2,A$
DCLOSE#2

59

60

COMMODORE 128

This example opens an existing relative file called " F I L E " as file number 2 in
line 10. Line 20 positions the relative file pointer at the first byte in record number 10.
Line 30 actually writes the data, A$, to file number 2.

REM
Comments or remarks about the operation of a program line
REM message
EXAMPLE:
10 NEXT X:REM THIS LINE INCREMENTS X.

RENAME
Change the name of a file on disk
R E N A M E "old filename" TO "new
Udevice number]

filename"

[,Ddrive n u m b e r ] [ < O N I , >

EXAMPLES:
RENAME " T E S T " TO " F I N A L T E S T " , D 0

Change the name of the file

" T E S T " to " F I N A L T E S T " .

RENAME (A$) TO (B$),D0,U9

Change the filename specified in

A$ to the filename specified in B$
on drive 0, device number 9. Remember, whenever a variable name
is used as a filename, it must be
enclosed in parentheses.

RENUMBER
Renumber lines of a BASIC program
RENUMBER
number]

[new starting line number][,increment][,old starting line

EXAMPLES:
RENUMBER

R E N U M B E R 2 0 , 20, 1

Renumbers the program starting at 10, and increments

each additional line by 10.
Starting at line 1, renumbers the program. Line 1 becomes line 20, and other lines are numbered in increments of 20.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

RENUMBER,, 65

Starting at line 65, renumbers in increments of 10. Line

65 becomes line 10. If you omit a parameter, you must
still enter a comma in its place.

RESTORE
Reset READ pointer so the DATA can be reREAD
RESTORE [line#]
If a line number follows the RESTORE statement, the READ pointer is set to the first
data item in the specified program line. Otherwise the pointer is reset to the beginning of
the first DATA statement in the BASIC program.
EXAMPLES:
10
20
30
40
50
60
70

FOR I = 1 TO 3
READ X
ALL = X + ALL
NEXT
RESTORE
GOTO 10
DATA 10,20,30

This example READs the data in line 70 and stores it in

numeric variable X. It adds the total of all the numeric
data items. Once all the data has been READ, three
cycles through the loop, the READ pointer is RESTOREd to the beginning of the program and it returns
to line 10 and performs repetitively.

10
20
30
40
50
60

READ A , B , C
DATA 100,500,750
READ X , Y , Z
DATA 36,24,38
RESTORE 40
READ S,P,Q

Line 50 of this example RESTORES the DATA pointer

to the beginning data item in line 40. When line 60 is
executed, it will READ the DATA 36,24,38 from line
40, and store it in numeric variables S, P, and Q,
respectively.

RESUME
Define where the program will continue (RESUME) after an error has been trapped
RESUME [line number | NEXT]
This statement is used to restart program execution after TRAPping an error. With no
parameters, RESUME attempts to re-execute the statement in which the error occurred.
RESUME NEXT resumes execution at the statement immediately following the one indicating the error. RESUME followed by a line number will GOTO the specific line and
resume execution from that line number. RESUME can only be used in program mode.
EXAMPLE:
10
15
20
40

TRAP 100
INPUT 44 ENTER A N U M B E R " ; A
B - 100/A
P R I N T " T H E RESULT = " ; B

61

62

COMMODORE 128

50 INPUT " D O YOU WANT TO RUN IT AGAIN (Y/N)";Z$:IF Z$ =

THEN 10
60 STOP
100 I N P U T " E N T E R ANOTHER NUMBER (NOT Z E R O ) " ; A
110 RESUME 20

"Y"

This example traps a "DIVISION BY ZERO E R R O R " in line 20 if 0 is entered in line

15. If zero is entered, the program goes to line 100, where you are asked to input another
number besides 0. Line 110 returns to line 20 to complete the calculation. Line 50 asks
if you want to repeat the program again. If you do, press the Y key.

RETURN
Return from subroutine
RETURN
EXAMPLE:
10 PRINT " E N T E R MAIN P R O G R A M "
20 GOSUB 100
30 PRINT " E N D OF P R O G R A M "

90 STOP
100 PRINT "SUBROUTINE 1 "
110 RETURN
This example calls the subroutine at line 100 which prints the message " S U B R O U TINE 1 " and RETURNs to line 30, the rest of the program.

RUN
Execute BASIC program
1) RUN [line number]
2) RUN "filename" [,Ddrive number][<ON|,>Udevice number]
EXAMPLES:
RUN
RUN 100
RUN"PRG1"
RUN(A$)

Starts execution from the beginning of the program.

Starts program execution at line 100.
DLOADs " P R G 1 " from disk drive 8, and runs it from the
starting line number.
DLOADs the program named in the variable A$.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

SAVE
Store the program in memory to disk or tape
SAVE [' 6 filename''][,device number][,EOT flag]
EXAMPLES:
SAVE
SAVE " H E L L O "
SAVE A$,8

Stores program on tape, without a name.

Stores a program on tape, under the name HELLO.
Stores on disk, with the name stored in variable A$.

SAVE " H E L L O " , 8

Stores on disk, with name HELLO (equivalent to

DSAVE " H E L L O " ) .

SAVE " H E L L O " , 1, 2

Stores on tape, with name HELLO, and places an END

OF TAPE marker after the program.

SCALE
Alter scaling in graphics mode
SCALE n [,Xmax,Ymax]
where:
n = 1 (on) or 0 (off)
Coordinates may be scaled from 0 to 32767 (default = 1023) in both X and Y (in either
standard or multicolor bit map mode), rather than the normal scale values, which are:
multi-color mode
bit map mode

X = 0 to 159
X = 0 to 319

Y = 0 to 199
Y = 0 to 199

EXAMPLES:
10 GRAPHIC 1,1
20 SCALE l:CIRCLE 1,180,100,100,100

Enter standard bit map, turn scaling

on to default size (1023, 1023) and
draw a circle.

10 GRAPHIC 1,3
20 SCALE 1,1000,5000
30 CIRCLE 1,180,100,100,100

Enter multi-color mode, turn scaling

on to size (1000, 5000) and draw a
circle.

The SCALE command affects the sprite coordinates in the MOVSPR command. If
you add scaling to a program that contains sprites, adjust the MOVSPR coordinates
accordingly.

63

64

COMMODORE 128

SCNCLR
Clear screen
SCNCLR mode number
The modes are as follows:

MODE NUMBER

0
2
3
4
5

MODE

40 column (VIC) text

bit map
split screen bit map
multi-color bit map
split screen multi-color bit map
80 column (8563) text

This statement with no argument clears the graphic screen, if it is present, otherwise the
current text screen is cleared.
EXAMPLES:
SCNCLR 5
SCNCLR 1
SCNCLR 4

Clears 80 column text screen.

Clears the (VIC) bit map screen.
Clears the (VIC) multicolor bit map and 40-column text split screen.

SCRATCH
Delete file from the disk directory
SCRATCH "filename" [,Ddrive n u m b e r ] [ < O N | , > U d e v i c e number]
EXAMPLE:
SCRATCH " M Y B A C K " , D0
This erases the file MY BACK from the disk in drive 0.

SLEEP
Delay program for a specific period of time
SLEEP N
where N is seconds 0 < N < = 65535.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

SLOW
Return the Commodore 128 to lMHz operation
SLOW

SOUND
Output sound effects and musical notes
SOUND v,f,d[,dir][,m][,s][,w][,p]
where:

v
f
d
dir
m
s
w

=
=
=
=
=
=
=

voice (1..3)
frequency value (0..65535)
duration (0..32767)
step direction (0(up), l(down) or 2(oscillate)) default = 0
minimum frequency (if sweep is used) (0..65535) default = 0
step value for sweep (0..32767) default = 0
waveform (0 = triangle, 1 = sawtooth, 2 = variable, 3 = noise)
default = 2
= pulse width (0..4095) default = 2048

p
EXAMPLES:

SOUND 1,40960,60

Play a SOUND at frequency 40960 in voice 1

for 1 second.

SOUND 2,20000,50,0,2000,100

Output a sound by sweeping through frequencies starting at 2000 and incrementing upward
in units of 100 up to 20,000. Each frequency is
played for 50 jiffies.

SOUND3,5000,90,2,3000,500,1

This example outputs a range of sounds starting at a minimum frequency of 3000, through
5000, in increments of 500. The direction of
the sweep is back and forth (oscillating). The
selected waveform is sawtooth and the voice
selected is 3.

SPRCOLOR
Set multi-color 1 and/or multi-color 2 colors for all sprites
SPRCOLOR [smcr-l][,smcr-2]
where:
smcr-1
smcr-2

Sets multi-color 1 for all sprites.

Sets multi-color 2 for all sprites.

65

66

COMMODORE 128

Either of these parameters may be any color from 1 through 16.

EXAMPLES:
SPRCOLOR 3,7

Sets sprite multi-color 1 to red and multi-color 2 to blue.

SPRCOLOR 1,2

Sets sprite multi-color 1 to black and multi-color 2 to white.

SPRDEF
Enter the SPRite DEFinition mode to create and 6dit sprite images.
SPRDEF
The SPRDEF command defines sprites interactively
Entering the SPRDEF command displays a sprite work area on the screen which
is 24 characters wide by 21 characters tall. Each character position in the grid corresponds to a sprite pixel in the sprite displayed to the right of the work area. Here
is a summary of the SPRite DEFinition mode operations and the keys that perform
them:

USER INPUT

DESCRIPTION

1-8
A
CRSR keys
RETURN KEY
RETURN key

Seleets a sprite number at the SPRITE NUMBER? prompt only.

Turns on and off automatic cursor movement.
Moves cursor in work/area.
Moves cursor to start of next line.
Exits sprite designer mode at the SPRITE NUMBER? prompt
only.
Moves cursor to top left corner of sprite work area.
Erases entire grid.
Selects color source (enables/disables pixels).
Selects sprite foreground color (1-8).
Selects sprite foreground color (9-16).
Cancels changes and returns to prompt.
Saves sprite and returns to SPRITE NUMBER? prompt.
Expands sprite in X (horizontal) direction.
Expands sprite in Y (vertical) direction.
Multi-color sprite mode.
Copies sprite data from one sprite to another.

HOME key
CLR key
1-4
CTRL key, 1-8
Commodore key, 1-8
STOP key
SHIFT RETURN
X
Y
M
C

SPRITE
Turn on and off, color, expand and set screen priorities for a sprite
SPRITE < n u m b e r > [,on/offj[,fgnd][,priority][,x-exp] [,y-exp][,mode]
The SPRITE statement controls most of the characteristics of a sprite.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

PARAMETER

DESCRIPTION

number
on/off
foreground
priority

Sprite number (1-8)

Turn sprite on (1) or off (0)
Sprite foreground color (1-16) (default = sprite number)
Priority is 0 if sprites appear in front of objects on the screen. Priority
is 1 if sprites appear in back of objects on the screen.
Horizontal EXPansion on (1) or off (0)
Vertical EXPansion on (1) or off (0)
Select standard sprite (0) or multi-color sprite (1)

x-exp
y-exp
mode

Unspecified parameters in subsequent sprite statements take on the characteristics of the

previous SPRITE statement. You may check the characteristics of a SPRITE with the
RSPRITE function.
EXAMPLES:
SPRITE 1, 1,3

Turn on sprite number 1 and color it red.

SPRITE 2,1,7,1, 1,1

Turn on sprite number 2, color it blue, make it pass

behind objects on the screen and expand it in the vertical
and horizontal directions.

SPRITE 6,1,1,0,0, 1,1

Turn on SPRITE number 6, color it black. The first 0

tells the computer to display the sprites in front of objects
on the screen. The second 0 and the 1 following tell the
C128 to expand the sprite vertically only. The last 1
specifies multi-color mode. Use the SPRCOLOR command to select the sprite's multi-colors.

SPRSAV
Copy sprite data from a text string variable into a sprite or vice versa, or copy data trom
one sprite to another.
SPRSAV < o r i g i n > , < d e s t i n a t i o n >
Either the origin or the destination can be a sprite number or a string variable but they
both cannot be string variables. They can both be sprite numbers. If you are storing a
string into a sprite, only the first 63 bytes of data are used. The rest are ignored since a
sprite can only hold 63 data bytes.
EXAMPLES:
SPRSAV l , A $

Transfers the image (data) from sprite 1 to the string named A$.

SPRSAV B$,2

Transfers the data from string variable B$ into sprite 2.

SPRSAV 2,3

Transfers the data from sprite 2 to sprite 3.

67

68

COMMODORE 128

SSHAPE / GSHAPE
Save/retrieve shapes to/from string variables
SSHAPE and GSHAPE are used to save and load rectangular areas of bit map
screens to/from BASIC string variables. The command to save an area of the bit map
screen into a string variable is:
SSHAPE string variable, X I , Y1 [,X2,Y2]
where:
string variable
X1,Y1
X2,Y2

String name to save data in

Corner coordinate (0,0 through 319,199) (scaled)
Corner coordinate opposite (X1,Y1) (default is the PC)

The command to retrieve (load) the data from a string variable and display it on
specified screen coordinates is:
GSHAPE string variable [X,Y][,mode]
where:
string
X,Y

Contains shape to be drawn

Top left coordinate (0,0 through 319,199) telling where to draw the shape
(scaledthe default is the pixel cursor)
Replacement mode:
0 = place shape as is (default)
1 = invert shape
2 = OR shape with area
3 = AND shape with area
4 = XOR shape with area

mode

The replacement mode allows you to change the data in the string variable so you can
invert it, perform a logical OR, exclusive OR (turn off bytes that are on) or AND
operation on the image.
EXAMPLES:
SSHAPE A$,10,10

Saves a rectangular area from the coordinates 10,10

to the location of the pixel cursor, into string variable A$.

SSHAPE B$,20,30,43,50

Saves a rectangular area from top left coordinate

(20,30) through bottom right coordinate (43,50) into
string variable B$.

SSHAPE D$, 4- 10, + 10

Saves a rectangular area 10 pixels to the right and

10 pixels down from the current position of the pixel
cursor.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

GSHAPE A$,120,20

Retrieves shape contained in string variable A$ and

displays it at top left coordinate (120,20).

GSHAPE B$,30,30,1

Retrieves shape contained in string variable B$ and

displays it at top left coordinate 30,30. The shape is
inverted due to the replacement mode being selected
by the 1.

GSHAPE C$, + 20, 4- 30

Retrieves shape from string variable C$ and displays

it 20 pixels to the right and 30 pixels down from the
current position of the pixel cursor.

NOTE: Beware using modes 1-4 with multi-color shapes. You may
obtain unpredictable results.

STASH
Move contents of host memory to expansion RAM
STASH #bytes, intsa, expsa, expb
Refer to FETCH command for description of parameters.

STOP
Halt program execution
STOP

SWAP
Swap contents of host RAM with contents of expansion RAM
SWAP #bytes, intsa, expsa, expb
Refer to FETCH command for description of parameters.

SYS
Call and execute a machine language subroutine at the specified address
SYS address [,a][,x][,y][,s]
This statement calls a subroutine at a given address in a memory configuration previously
set up according to the BANK command. Optionally, arguments a,x,y and s are loaded into
the accumulator, x, y and status registers, respectively, before the subroutine is called.
The address range is 0 to 65535. The 8502 microprocessor begins executing the
machine-language program starting at the specified memory location. Also see the
BANK command.

69

70

COMMODORE 128

EXAMPLES:
SYS 32768

Calls and executes the machine-language routine at location 32768

($8000).

SYS 6144,0

Calls and executes the machine-language routine at location 6144

($1800) and loads zero into the accumulator.

TEMPO
Define the speed of the song being played
TEMPO n
where n is a relative duration between (1 and 255)
The default value is 8, and note duration increases with n.
EXAMPLES:
TEMPO 16
TEMPO 1
TEMPO 250

Defines the Tempo at 16.

Defines the TEMPO at the slowest speed.
Defines the TEMPO at 250.

TRAP
Detect and correct program errors while a BASIC program is RUNning
TRAP [line number]
The RESUME statement can be used to resume program execution. TRAP with no line
number turns off error trapping. An error in a TRAP routine cannot be trapped. Also see
system variables ST, EL, DS and DS$.
EXAMPLES:
. 100 TRAP 1000

If an error occurs, GOTO line 1000.

. 1000 7ERR$(ER);EL

Print the error message, and the error number.

.1010 RESUME

Resume with program execution.

TROFF
Turn off error tracing mode
TROFF

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

TRON
Turn on error tracing
TRON
TRON is used in program debugging. This statement begins trace mode. When you
RUN the program, the line numbers of the program appear in brackets before any action
for that line occurs.

VERIFY
Verify program in memory against one saved to disk or tape
VERIFY "filename" [,device number][,relocate flag]
Issue the VERIFY command immediately after you SAVE a program.
EXAMPLES:
VERIFY

Checks the next program on the tape.

VERIFY ' ' H E L L O ' '

Searches for HELLO on tape, checks it against memory.

VERIFY " H E L L O " , 8 , l

Searches for HELLO on disk, then checks it against

memory.

VOL
Define output level of sound for SOUND and PLAY statements
VOL volume level
EXAMPLES:
VOL 0
VOL 15

Sets volume to its lowest level.

Sets volume for SOUND and PLAY statements to its highest output.

WAIT
Pause program execution until a data condition is satisfied
WAIT < l o c a t i o n > , < m a s k - I > [ , m a s k - 2 > ]
where:
location = 0-65535
masks
= 0-255
The WAIT statement causes program execution to be suspended until a given memory
address recognizes a specified bit pattern or value.
The first example below WAITs until a key is pressed on the tape unit to
continue with the program. The second example will WAIT until a sprite collides with
the screen background.

71

72

COMMODORE 128

EXAMPLES:
WAIT 1, 32, 32
WAIT 53273, 2
WAIT 36868, 144, 16

WIDTH
Set the width of drawn lines
WIDTH n
EXAMPLES:
WIDTH 1
WIDTH 2

Set single width for graphic commands

Set double width for drawn lines

WINDOW
Define a screen window
WINDOW top left col,top left row,bot right col,bot right row[,clear]
This command defines a logical window within the 40 or 80 column text screen. The
coordinates must be in the range 0-39/79 for 40- and 80-column values respectively and
0-24 for row values. The clear flag, if provided (1), causes a screen-clear to be
performed (but only within the limits of the newly described window).
EXAMPLES:
WINDOW 5,5,35,20

Defines a window with top left corner coordinate as

5,5 and bottom right corner coordinate as 35,20.

WINDOW 10,2,33,24,1

Defines a window with upper left corner coordinate

10,2 and lower right corner coordinate 33,24. Also
clears the portion of the screen within the window as
specified by the 1.

BASIC FUNCTIONS
The format of the function description is:
FUNCTION (argument)
where the argument can be a numeric value, variable or string.
Each function description is followed by an EXAMPLE. The first line appearing
below the word "EXAMPLE" is the function you type. The second line without bold is
the computer's response.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

ABS
Return absolute value of argument X
ABS(X)
EXAMPLE:
PRINT ABS (7*(-5))
35

ASC
Return CBM ASCII code for the first character in X$
ASC(X$)
This function returns the CBM ASCII code of the first character of X$.
EXAMPLE:
X$ = " C 1 2 8 " : P R I N T ASC (X$)
67

ATN
Return the arctangent of X in radians
ATN (X)
The value returned is in the range - Tr/2 through Tr/2.
EXAMPLE:
PRINT ATN (3)
1.24904577

BUMP
Return sprite collision information
B U M P (N)
To determine which sprites have collided since the last check, use the BUMP function.
BUMP(1) records which sprites have collided with each other, and BUMP(2) records
which sprites have collided with other objects on the screen. COLLISION need not be
active to use BUMP. The bit positions (0-7) in the BUMP value correspond to sprites 1
through 8 respectively. BUMP(n) is reset to zero after each call.

73

74

COMMODORE 128

Here's how the sprite numbers and BUMP values that are returned correspond:
BUMP Value:
Sprite Number:

128

64

32

16

EXAMPLES:
PRINT BUMP (1)

12 indicates that sprites 3 and 4 have collided.

PRINT BUMP (2)

32 indicates the sprite 6 has collided with an object on the screen.

CHR$
Return character for specified CBM ASCII code X
CHR$(X)
The argument (X) must be in the range 0-255. This is the opposite of ASC and returns the
string character whose CBM ASCU code is X. Refer to Appendix E for a table of CHR$ codes.
EXAMPLES:
PRINT CHR$ (65)
A
PRINT CHR$ (147)

Prints the A character.

Clears the text screen.

COS
Return cosine for angle of X in radians
COS(X)
EXAMPLE:
PRINT COS (TT/3)
.5

FNxx
Return value from user defined function xx
FNxx(X)
This function returns the value from the user defined function xx created in a DEF
FNxx statement
EXAMPLE:
10 DEF FNAA(X) = (X-32)*5/9
20 INPUT X
30 PRINT FNAA(X)
RUN
740 (? is input prompt)
4.44444445

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

NOTE: If GRAPHIC is used in a program that defines a function, issue

the GRAPHIC command before defining the function or the function
definition is destroyed.

FRE
Return number of available bytes in memory
FRE (X)
where X is the RAM bank number. X = 0 for BASIC program storage and X = 1 to
check for available BASIC variable storage.
EXAMPLES:
PRINT FRE (0)
58109

Returns the number of free bytes for BASIC programs.

PRINT FRE (1)

64256

Returns the number of free bytes for BASIC variable storage.

HEX$
Return hexadecimal string equivalent to decimal number X
HEX$(X)
EXAMPLE:
PRINT HEX$(53280)
D020

INSTR
Return starting position of string 2 within string 1
INSTR (string 1, string 2 [,starting position])
EXAMPLE:
PRINT INSTR ( " C O M M O D O R E 1 2 8 " , " 1 2 8 " )

11

INT
Return integer form (truncated) of a floating point value
INT(X)
This function returns the integer value of the expression. If the expression is positive,
the fractional part is left out. If the expression is negative, any fraction causes the next
lower integer to be returned.

75

76

COMMODORE 128

EXAMPLES:
PRINT INT(3.14)
3
PRINT INT(-3.14)
^

JOY
Return position of joystick and the status of the fire button
JOY(N)
when N equals:
1
2

JOY returns position of joystick 1.

JOY returns postion of joystick 2.

Any value of 128 or more means that the fire button is also pressed. To find the joystick
position if the fire button is pressed subtract 128 from the JOY value. The direction is
indicated as follows.
1

8
7

6
5
EXAMPLES:
PRINT JOY (2)
135

Joystick 2 fires to the left.

IF (JOY (1) > 127) THEN PRINT " F I R E "

Determines whether the fire button

is pressed.

DIR = J O Y ( l ) AND 15

Returns direction (only) ofjoystick 1.

LEFT$
Return the leftmost characters of string
LEFT$ (string,integer)
EXAMPLE:
PRINT L E F T $ ( " C O M M O D O R E ' ' , 5 )
COMMO

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

LEN
Return the length of a string
LEN (string)
The returned integer value is in the range 0-255.
EXAMPLE:
PRINT LEN ( ' ' C O M M O D O R E 128'')

12

LOG
Return natural log of X
LOG(X)
The argument X must be greater than 0.
EXAMPLE:
PRINT LOG (37/5)
2.00148

MID$
Return a substring from a larger string
MLD$ (string,starting position[,length])
This function extracts the number of characters specified by length (0-255), from string,
starting with the character specified by starting position (1-255).
EXAMPLE:
PRINT M I D $ ( " C O M M O D O R E 128",3,5)
MMODO

PEEK
Return contents of a specified memory location
PEEK(X)
The data will be returned from the bank selected by the most recent BANK command.
See the BANK command.
EXAMPLE:
10
20
30
40

BANK 15:VlC = D E C ( " D 0 0 0 " )

FOR I = 1 TO 47
PRINT PEEK(VIC + I)
NEXT

This example displays the contents of the registers of the VIC chip (some of which
are ever-changing).

77

78

COMMODORE 128

PEN
Return X and Y coordinates of the light pen
PEN(n)
where n
n
n
n
n

=
=
=
=
=

0 PEN returns the X coordinate of light pen position on any VIC screen,
1 PEN returns the Y coordinate of light pen position on any VIC screen,
2 PEN returns the character column position of the 80 column display,
3 PEN returns the character row position of the 80 column display,
4 PEN returns the (80-column) light pen trigger value.

The VIC PEN values are not sealed and are taken from the same coordinate plane as
sprites use. Unlike the 40 column (VIC) screen, the 80 column (8563) coordinates are
character row and column positions and not pixel coordinates like the VIC screen. Both
the 40 and 80 column screen coordinate values are approximate and vary, due to the
nature of light pens. The 80-column read values are not valid until PEN(4) is true.
Light pens are always plugged in to control port 1.
EXAMPLES:
10 PRINT PEN(0);PEN(1)

Displays the X and Y coordinates of the light

pen (for the 40 column screen).

10 DO UNTIL PEN(4):LOOP

Ensures that the read values are valid (for the

80 column screen).

20 X - PEN(2)
30 Y = PEN(3)
40 REM:REST OF PROGRAM
TT
Return the value of pi (3.14159265)
TT

EXAMPLE:
PRINT TT This returns the result 3.14159265.

POINTER
Return the address of a variable
POINTER (variable name)
This function returns a zero if the variable is not defined.
EXAMPLE:
A = POINTER (Z)

This example returns the address of variable Z.

NOTE: Address returned is in RAM BANK 1.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

POS
Return the current cursor column position within the current screen window
POS(X)
The POS function indicates where the cursor is within the defined screen window. X is a
dummy argument, which must be specified, but the value is ignored. The values
returned range from 0-39 on the VIC screen and 0-79 on the 80-column screen.
EXAMPLE:
FOR I = 1 to 10 : 7SPC(I); POS(O): NEXT
This displays the current cursor position within the defined text window.

POT
Returns the value of the game-paddle potentiometer
POT (n)
when:
n
n
n
n

=
=
=
=

1,
2,
3,
4,

POT
POT
POT
POT

returns
returns
returns
returns

the
the
the
the

position
position
position
position

of
of
of
of

paddle
paddle
paddle
paddle

# 1 (control
# 2 (control
# 3 (control
# 4 (control

port
port
port
port

1)
1)
2)
2)

The values for POT range from 0 to 255. Any value of 256 or more means that the fire
button is also depressed.
EXAMPLE:
10 PRINT POT(l)
20 lF POT(l) > 256 THEN PRINT " F I R E "
This example displays the value of game paddle 1.

RCLR
Return color of color source
RCLR(N)
This function returns the color (1 through 16) assigned to the color source N (0< = N = <
6), where the following N values apply:

79

80

C O M M O D O R E 128

SOURCE

DESCRIPTION

0
1
2
3
4
5

40-column background
bit map foreground
multi-color 1
multi-color 2
40-column border
40- or 80-column character color
80-column background color

The counterpart to the RCLR function is the COLOR command.

EXAMPLE:
10 FOR I - 0 TO 6
20 PRINT " S O U R C E " ; I ; " l S COLOR CODE";RCLR(I)
30 NEXT
This example prints the color codes for all six color sources.

RDOT
Return current position or color source of pixel cursor
RDOT (N)
where:
N = 0 returns the X coordinate of the pixel cursor
N = 1 returns the Y coordinate of the pixel cursor
N = 2 returns the color source (0-3) of the pixel cursor
This function returns the location of the current position of the pixel cursor or the
current color source of the pixel cursor.
EXAMPLES:
PRINT RDOT(O)
PRINT RDOT( 1)
PRINT RDOT(2)

Returns X position of pixel cursor

Returns Y position of pixel cursor
Returns color source of pixel cursor

RGR
Return current graphic mode
RGR(X)
This function returns the current graphic mode. X is a dummy argument, which must be
specified. The counterpart of the RGR function is the GRAPHIC command. The value
returned by RGR(X) pertains to the following modes:

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

VALUE

0
1
2
3
4
5

GRAPHIC MODE

40 column (VIC) text

Standard bit map
Split screen bit map
Multi-color bit map
Split screen Multi-color bit map
80 column (8563) text

EXAMPLE:
PRINT RGR(0)
1

Displays the current graphic mode; in this case, standard bit

map mode.

PRINT RGR(0)

Both multi-color bit map and 80-column text modes are enabled.

RIGHT$
Return sub-string from rightmost end of string
RIGHT$(string, numeric)
EXAMPLE:
PRINT RIGHT$C'BASEBALL'' ,5)
EBALL

RND
Return a random number
RND (X)
If X = 0
If X > 0

RND returns a random number based on the hardware clock.

RND generates a reproducible random number based on the seed
value below.

If X < 0

produces a random number which is used as a base called a seed.

EXAMPLES:
PRINT RND(0)
.507824123
PRINT INT(RND(l)*100 4- 1)
89

Displays a random number between 0 and 1.

Displays a random number between 1 and 100.

81

82

COMMODORE 128

RSPCOLOR
Return sprite multicolor values
RSPCOLOR (X)
When:
X = 1
X = 2

RSPCOLOR returns the sprite multi-color 1.

RSPCOLOR returns the sprite multi-color 2.

The returned color value is a value between 1 and 16. The counterpart o f t h e RSPCOLOR
function is the SPRCOLOR statement. Also see the SPRCOLOR statement.
EXAMPLE:
10 SPRITE 1,1,2,0,1,1,1
20 SPRCOLOR 5,7
30 PRINT "SPRITE MULTI-COLOR 1 IS";RSPCOLOR(l)
40 PRINT "SPRITE MULTI-COLOR 2 IS";RSPCOLOR(2)
RUN
SPRITE MULTI-COLOR 1 IS 5
SPRITE MULTI-COLOR 2 IS 7
In this example line 10 turns on sprite 1, colors it white, expands it in both the X and Y
directions and displays it in multi-color mode. Line 20 selects sprite multi-colors 1 and 2
(5 and 7 respectively). Lines 30 and 40 print the RSPCOLOR values for multi-color 1 and 2.

RSPPOS
Return the speed and position values of a sprite
RSPPOS (sprite number,position|speed)
where sprite number identifies which sprite is being checked, and position and speed
specifies X and Y coordinates or the sprite's speed.
When position equals:
0 RSPPOS returns the current X position of the specified sprite.
1 RSPPOS returns the current Y position of the specified sprite.
When speed equals:
2 RSPPOS returns the speed (0-15) of the specified sprite.
EXAMPLE:
10 SPRITE 1,1,2
20 MOVSPR 1,45#13
30 PRINT RSPPOS (l,O);RSPPOS (l,l);RSPPOS (1,2)
This example returns the current X and Y sprite coordinates and the speed (13).

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

RSPRITE
Return sprite characteristics
RSPRITE (sprite number,characteristic)
RSPRITE returns sprite characteristics that were specified in the SPRITE command.
Sprite number specifies the sprite (1-8) you are checking and the characteristic specifies
the sprite's display qualities as follows:
RSPRITE RETURNS
CHARACTERISTIC

0
1
2
3
4
5

THESE VALUES:

Enabled(l) / disabled(0)
Sprite color (1-16)
Sprites are displayed in front of (0) or behind
(1) objects on the screen
Expand in X direction
Expand in Y direction
Multi-color

yes = 1, no = 0
yes = 1, no = 0
yes = 1, no = 0

EXAMPLE:
10 FOR I = 0 TO 5
20 PRINT RSPRITE (1,1)
30 NEXT

This example prints all 6 characteristics of sprite 1.

RWINDOW
Returns the size of the current window or the number of columns of the current
screen
RWINDOW (n)
When n equals:
0 RWINDOW returns the number of lines in the current window.
1 RWINDOW returns the number of rows in the current window.
2 RWINDOW returns either of the values 40 or 80, depending on the current
screen output format you are using.
The counterpart of the RWINDOW function is the WINDOW command.
EXAMPLE:
10 WINDOW 1,1,10,10
20 PRINT RWINDOW(0);RWINDOW(l);RWINDOW(2)
RUN
9 9 40
This example returns the lines (10) and columns (10) in the current window. This
example assumes you are displaying the window in 40 column format.

83

84

COMMODORE 128

SGN
Return sign of argument X
SGN(X)
EXAMPLE:
PRINT SGN(4.5);SGN(0);SGN(-2.3)
1
0- 1

SIN
Return sine of argument
SIN(X)
EXAMPLE:
PRINT SIN (ir/3)
.866025404

SPC
Skip spaces on printed output
SPC (X)
EXAMPLE:
PRINT ''COMMODORE'';SPC(3);" 128"
COMMODORE
128

SQR
Return square root of argument
SQR (X)
EXAMPLE:
PRINT SQR(25)
5

STR$
Return string representation of number
STR$ (X)

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

EXAMPLE:
PRINT STR$(123.45)
123.45
PRINT STR$(-89.03)
-89.03
PRINT STR$(lE20)
lE + 20

TAB
Moves cursor to tab position in present statement
TAB (X)
EXAMPLE:
10 PRINT''COMMODORE"TAB(25)'' 128''
COMMODORE
128

TAN
Return tangent of argument in radians
TAN(X)
This function returns the tangent of X, where X is an angle in radians
EXAMPLE:
PRINT TAN(.785398163)
1

USR
Call user-defined subprogram
USR(X)
When this function is used, the BASIC program jumps to a machine language program
whose starting point is contained in memory locations 4633($1219) and 4634($121A), (or
785($0311) and 786($0312) in C64 mode). The parameter X is passed to the machinelanguage program in the floating-point accumulator ($63-$68 in C128 mode). A value is
returned to the BASIC program through the calling variable. You must direct the value
into a variable in your program in order to receive the value back from the floating-point
accumulator. An ILLEGAL QUANTITY ERROR results if you don't specify this
variable. This allows the user to exchange a variable between machine code and
BASIC.

93

86

COMMODORE 128

EXAMPLE:
10
20
30
40

POKE 4633,0
POKE 4634,48
A = USR(X)
PRINT A

Place starting location ($3000 = 12288:$00 = 0:$30) = 48 of machine language

routine in location 4633 and 4634. Line 30 stores the returning value from the floatingpoint accumulator. The USER vector is assumed to be in BANK 15. Your machine
language routine MUST be in RAM bank 0 below address $4000.

VAL
Return the numeric value of a number string
VAL(X$)
EXAMPLE:
10 A$ = " 1 2 0 "
20 B$ = " 3 6 5 "
30 PRINT VAL (A$ + B$)
RUN
485

XOR
Return exclusive OR value
XOR (nl,n2)
This function returns the exclusive OR of the numeric argument values nl and n2.
X = XOR (nl,n2)
where n l , n2, are 2 unsigned values (0-65535)
EXAMPLE:
PRINT XOR(128,64)
192

RESERVED SYSTEM WORDS

(KEYWORDS)
This section lists the words used to make up the BASIC 7.0 language. These words
cannot be used within a program as other than a component of the BASIC language. The
only exception is that they may be used within quotes (in a PRINT statement, for example).

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

ABS
DELETE
HELP
AND
DIM
HEX$
APPEND
DIRECTORY IF
ASC
DLOAD
INPUT
ATN
DO
INPUT#
AUTO
DOPEN
INSTR
DRAW
BACKUP
INT
BANK
DS
JOY
BEGIN
DS$
KEY
BEND
DSAVE
LEFT$
DVERIFY
BLOAD
LEN
BOOT
EL
LET
BOX
ELSE
LIST
END
BSAVE
LOAD
BUMP
ENVELOPE
LOCATE
CATALOG ER
LOG
ERR$
CHAR
LOOP
CHR$
EXIT
MID$
CIRCLE
EXP
MONITOR
FAST
CLOSE
MOVSPR
CLR
FETCH
NEW
CMD
FILTER
NEXT
COLLECT FN
NOT
COLLISION FOR
(OFF)
COLOR
FRE
ON
CONCAT
GET
OPEN
CONT
GET#
OR
COPY
G064
PAINT
COS
GOSUB
PEEK
DATA
GOTO
PEN
DCLEAR
GO TO
PLAY
DCLOSE
GRAPHIC
POINTER
DEC
GSHAPE
POKE
DEF FN
HEADER
POS

POT
PRINT
PRINT#
PUDEF
(QUIT)
RCLR
RDOT
READ
RECORD
REM
RENAME
RENUMBER
RESTORE
RESUME
RETURN
RGR
RIGHT$
RND
RREG
RSPCOLOR
RSPPOS
RSPRITE
RUN
RWINDOW
SAVE
SCALE
SCNCLR
SCRATCH
SGN
SIN
SLEEP
SLOW
SOUND
SPC

SPRCOLOR
SPRDEF
SPRITE
SPRSAV
SQR
SSHAPE
ST
STASH
STEP
STOP
STR$
SWAP
SYS
TAB
TAN
TEMPO
THEN
TI
TI$
TO
TRAP
TROFF
TRON
UNTIL
USING
USR
VAL
VERIFY
VOL
WAIT
WHILE
WIDTH
WINDOW
XOR

NOTE: Keywords shown in parentheses are not implemented in C128

BASIC 7.0.

Reserved variable names are names reserved for the variables DS, DS$, ER, EL,
ST, TI and TI$, and the function ERR$. Keywords such as TO and IF or any other
names that contain keywords, such as RUN, NEW or LOAD cannot be used.
ST is a status variable for input and output (except normal screen/keyboard
operations). The value of ST depends on the results of the last I/O operation. In general,
if the value of ST is 0, then the operation was successful.

87

88

C O M M O D O R E 128

TI and TI$ are variables that relate to the real time clock built into the Commodore
128. The system clock is updated every l/60th of a second. It starts at 0 when the
Commodore 128 is turned on, and is reset only by changing the value of TI$. The
variable TI gives the current value of the clock in l/60th of a second. TI$ is a string that
reads the value of the real time clock as a 24-hour clock. The first two characters of TI$
contain the hour, the third and fourth characters are minutes and the fifth and sixth
characters are seconds. This variable can be set to any value (so long as all characters
are numbers) and will be updated automatically as a 24-hour clock.
EXAMPLE:
TI$ = "101530"

Sets the clock to 10:15 and 30 seconds (AM).

The value of the clock is lost when the Commodore 128 is turned off. It starts at
zero when the Commodore 128 is turned on, and is reset to zero when the value of the
clock exceeds 235959 (23 hours, 59 minutes and 59 seconds).
The variable DS reads the disk drive command channel and returns the current
status of the drive. To get this information in words, PRINT DS$. These status variables
are used after a disk operation, like DLOAD or DSAVE, to find out why the error light
on the disk drive is blinking.
ER, EL and the ERR$ function are variables used in error trapping routines. They
are usually only useful within a program. ER returns the last error number encountered
since the program was RUN. EL is the line where the error occurred. ERR$ is a
function that allows the program to print one of the BASIC error messages. PRINT
ERR$(ER) prints out the proper error message.

SYMBOL

USE(S)

Plus sign

Arithmetic addition; string concatenation; relative pixel

cursor/sprite movement; declare decimal number in machine language monitor
Arithmetic subtraction; negative number; unary minus;
relative pixel cursor/ sprite movement
Arithmetic multiplication
Arithmetic division
Arithmetic exponentiation
Separate keywords and variable names
Value assignment; relationship testing
Relationship testing
Relationship testing
Format output in variable lists; command/statement function parameters

Minus sign
H

|
=
<
>

Asterisk
Slash
Up arrow
Blank space
Equal sign
Less than
Greater than
Comma

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA

SYMBOL

USE(S)

Period
Semicolon
Colon
Quotation mark
Question mark
Left parenthesis
Right parenthesis
Percent

#
$

Number
Dollar sign

&

And sign
Pi

Decimal point in floating-point constants

Format output in variable lists; delimiter
Separate multiple BASIC statements on a program line
Enclose string constants
Abbreviation for the keyword PRINT
Expression evaluation and functions
Expression evaluation and functions
Declare a variable name as integer; declare binary number in machine language monitor
Precede the logical file number in input/output statements
Declare a variable name as a string and declare hexadecimal number in machine language monitor
Declare octal number in machine language monitor
Declare the numeric constant 3.141592654

.
5

:
ii 95

(
)

7T

89

3
ONE STEP
BEYOND
SIMPLE B A S I C

91

92

COMMODORE 128

This chapter takes you one step beyond simple BASIC and presents a collection of useful
routines. You can incorporate these routines into your own programs as needed. In most
cases the routines will require only line number changes to be fitted into your programs.

CREATING A MENU
A menu is a list of choices you select to perform a specific operation within an
application program. A menu directs the computer to a particular part of a program.
Here is a general example of a menu program:
5 REM MENU SKELETON
10 SCNCLR 0
20 PRINT"1. FIRST ITEM"
30 PRINT"2. SECOND ITEM"
40 PRINT"3. THIRD ITEM"
50 PRINT"4. FOURTH ITEM"
100 PRINT:PRINT"SELECT AN ITEM FROM ABOVE"
110 GETKEY A$
120 A=VAL (A$): IF A>4 THEN 10
130 ON A GOSUB 100 0,2000,3000,4000
140 GOTO 10:REM RETURN TO MENU
99 9 STOP
1000 REM START FIRST ROUTINE FOR ITEM ONE HERE
199 9 RETURN
2000 REM START SECOND ROUTINE HERE
2999 RETURN
3000 REM START THIRD ROUTINE HERE
3999 RETURN
40 0 0 REM START FOURTH ROUTINE HERE
4999 RETURN

Program 3 - 1 . Menu Skeleton

The SCNCLR 0 command in line 10 clears the 40-column screen. (Use SCNCLR
5 if you are using the 80-column screen. The easiest selection is by a number. You may
use as many selections as can fit on the screen. Line 100 displays a message to the user.
The GETKEY command in line 110 forces the computer to wait for a key to be pressed.
Since a key represents a character symbol, A$ is a string variable. So that it can be
interpreted as a numeric value in an ON GOTO statement, the string variable is
converted to a number with the VAL function in line 120. The IF . . . THEN statement
in line 120 screens user errors by preventing the user from selecting a number that is not
in the range of numbers used for choices (4). Line 130 directs control to the appropriate
section (i.e., line number) in your program. Since four selections are offered in this
example, you must include at least four line numbers. Line 1999 returns to the menu at
the end of each subroutine that you add at lines 1000, 2000, 3000 and 4000 in the menu
skeleton.

ONE STEP BEYOND SIMPLE BASIC

BUFFER ROUTINE
The C128 keyboard buffer can hold and dispense up to ten characters from the
keyboard. This is useful in a word processing program where it is possible at certain
moments to type faster than the software can actually process. The characters that
haven't been displayed yet are temporarily stored in the keyboard buffer. The computer
can hold the next instruction in the buffer for use when the program is ready. This buffer
allows a maximum of ten characters in queue. To see the buffer in action, enter the
command SLEEP 5 and immediately press ten different letter keys. After five seconds,
all ten characters are displayed on the screen.
Here is a buffer routine that allows you to put items in the keyboard buffer
from within a program so they are dispensed automatically as the computer is able to act
upon them.
In line 10, memory location 208 (198 in C64 mode) is filled with a number
between 0 and 10the number of keyboard characters in the keyboard buffer. In line
20, memory locations 842 through 851 (631-640 in C64 mode) are filled with any ten
characters you want placed there. In this example, seven characters are in the buffer,
each a carriage RETURN character. CHR$(13) is the character string code for the
carriage return character.
Line 40 places the text "7CHR$(156)" on the screen, but does not execute the
instruction. Line 50 displays the word " L I S T " on the screen. Neither command is
executed until the program ends. In the C128, the keyboard buffer automatically empties
when a program ends. In this case, the characters in the buffer (carriage return) are
emptied and act as though you are pressing the RETURN key manually. When this occurs
on a line where the commands from lines 40 and 50 are displayed, they are executed
as though you typed them in direct mode and pressed the RETURN key yourself. When
this program ends, the character color is changed to purple and the program is LISTED
to the screen. This technique is handy in restarting programs (with RUN or GOTO).
The next section gives a practical example of using the buffer routine.
10 POKE 208 ,7:REM SPECIFY # OF CHARS IN BUFFER
20 FOR 1=842 TO 849:POKE I,13:NEXT:REM PLACE CHARS IN BUFFER
3 0 SLEEP 2 :REM DELAY
40 SCNCLR:PRINT:PRINT:PRINT:PRINT:PRINT:PRINT:PRINT"? CHR$(156)"
50 PRINT:PRINT:PRINT:PRINT"LIST":REM PLACE LIST ON SCREEN
60 PRINT CHR$(19):PRINT:PRINT:REM GO HOME AND CURSOR DOWN TWICE
7 0 REM WHEN PROGRAM ENDS, BUFFER EMPTIES AND EXECUTES 7 RETURNS.
80 REM THIS CHANGES CHAR COLOR TO PURPLE AND LISTS THE PROGRAM AUTOMATICALLY
9 0 REM AS IF YOU PRESSED THE RETURN KEY MANUALLY

Program 3-2. Buffer Return

LOADING ROUTINE
The buffer can be used in automatic loader routines. Many programs often involve the
loading of several machine code routines as well as a BASIC program. The results of
the following loader are similar to many found on commercial software packages.

93

94

COMMODORE 128

2 COLOR 4,1:COLOR 0,1:COLOR 5,1

5 A$="PICTURE"
10 SCNCLR:PRiNT:PRINT:PRINT:PRINT"LOAD"CHR$(34)A$CHR$(34)",8,1"
15 PRINT:PRINT:PRINT"NEW"
25 B$="FILE3.BIN"
30 PRINT:PRINT:PRINT"LOAD"CHR$(34)B$CHR$(34)",8,1"
4 5 PRINT:PRINT:PRINT:PRINT:PRINT:PRINT"SYSl2*2 56"
90 PRINT CHR$(5):PRINT"
GREETINGS FROM COMMODORE"
100 PRINT"
PLEASE STAND BY - LOADING":PRINT CHR$(144)
200 PRINT CHR$(19)
3 00 POKE20 8,7:F0RI = 8 4 2T08 51:POKEI,13:NEXT

Program 3-3. Loading Routine

Line 2 colors the border, screen and characters black. Line 5 assigns A$ the
filename " P I C T U R E " , which in this example assumes that it is an 8K binary file of a
bit-mapped screen. Line 10 places the LOAD instruction for the picture file on the
screen, but does not execute it. A carriage return from the keyboard buffer executes the
load instruction once the program ends and the keyboard buffer empties. Line 15 prints
the word " N E W " on the screen. Again, this operation is not carried out until a carriage
return is executed on the same line once the keyboard buffer empties. After loading a
machine language program, a NEW is performed to set pointers to their original
positions and clear the variable storage area. Line 30 displays the second load instruction for the machine language program " F I L E 3 . B I N " . This hypothetical program
enables the bit mapped PICTURE, and anything else you want to supply in the program.
Line 45 initiates (SYS12*256), the "FILE3.BIN" program starting at 3072 ($0C00)
once the keyboard buffer empties. This is only a template sample for you to follow.
" P I C T U R E " and "FILE3.BIN" are programs you supply and are only used to illustrate
one technique of automatic loading. Since the previous character color was black, all the
loading instructions are displayed in black on a black background, so they can't be seen.
The CHR$(5) in line 90 changes the character color to white, so the only visible
messages are the ones in white in lines 90 and 100, while the disk drive is loading
" P I C T U R E " and "FILE3.BIN". Line 300 is the buffer routine.
If you were to do each step manually it would require seven " R E T U R N S " . This
program places seven carriage return characters in the keyboard buffer, and they are
dispensed automatically when the program ends. As each RETURN is accepted, the
corresponding screen instruction is enacted automatically as if you had pressed the
RETURN key manually.

PROGRAMMING THE
CI28 FUNCTION KEYS
As each of the function keys (F1 through F8) is pressed, the computer displays a BASIC
command on the screen and in some cases acts immediately. These are known as the
default values of the function keys. Enter a KEY command to get a list of function key
values at any time.

ONE STEP BEYOND SIMPLE BASIC

CHANGING FUNCTION KEYS

You can change the value assigned to any function key by entering the KEY command
followed by the number (1 through 8) of the key you want changed, a comma, and the
new key instruction in a string format. For example:
KEY1, ' ' D L O A D " + CHR$(34) + "PROGRAM N A M E "
+ CHR$(34) + CHR$( 13) + ' 'LIST'' + CHR$( 13)
This tells the computer to automatically load the BASIC program called "program
name" and list it immediately (whenever F1 is pressed). The character string code value
for the quote character is 34. It is necessary for LOAD and SAVE operations. The
character string code value for RETURN is 13 and provides immediate execution.
Otherwise, the instruction is only displayed on the screen and requires you to supply the
additional response and press the RETURN key.
The following example uses the ASCII value for the ESCape key to assign the F3
key to cause a downward scroll:
KEY 3,CHR$(27) + " W "
N O T E : All eight KEY definitions in total must not exceed 246 characters.

USING C64 FUNCTION KEY VALUES

IN CI28 MODE
Programs previously written for the C64 which incorporate the function keys may still
be used in C128 mode by first assigning the C64 ASCII values to them with this
instruction:
10J = 132:FORA= l T 0 2 : F 0 R K - A T 0 8 S T E P 2 : J - J + l : K E Y K , C H R $ ( J ) : N E X T :
NEXT

HOW TO CRUNCH B A S I C PROGRAMS

Several techniques known collectively as memory crunching allow you to get the most
out of your computer's memory. These techniques include eliminating spaces, using
multiple instructions, having syntax relief, removing remark statements, using variables,
and in general using BASIC intelligently.

ELIMINATING SPACES
In most BASIC commands, spacing is unnecessary, except inside quotes when you want
the spaces to appear on the screen. Although spaces improve readability, the extra space
consumes additional memory. Here is an instructional line presented both ways:
10INPUT"FIRST NAME";N$:FOR T = A TO M:PRINT " O K " :
10INPUT"FIRST NAME'';N$:FORT - ATOM:PRINT"OK'':

95

96

COMMODORE 128

USING MULTIPLE INSTRUCTIONS

Colons allow you to place several instructions within a single program line. Each
program line consumes additional memory. Be careful, however, crunching lF statements. Any instruction after the IF statement with the same line number can be bypassed
along with the IF . . . THEN condition. The following line is the equivalent of five
lines:
(A)
10 PRINTX:INPUTY:PRINTY. SCNCLR0: ?J
10
20
30
40
50

(B)
PRINTX
INPUTY
PRINTY
SCNCLRO
PRINTJ

Example A requires less space in memory and on disk. Example B requires 16

additional bytes; 2 bytes for each additional line number and 2 bytes for the link to the
next line number.

SYNTAX RELIEF
Some BASIC syntax is very flexible and this flexibility can be used to your advantage.
The LET statement, for example, can be written without LET. LET Y = 2 is the same as
Y = 2. Although it is good practice to initialize all variables to zero, it is not necessary
since the computer automatically sets all variables to zero, including subscripted variables. DIMension all arrays (subscripted variables) to have twelve or more elements. The
C128 automatically dimensions each variable to have eleven subscripted elements if no
dimension is specified following DIM and the variable names. Often semicolons are not
required in PRINT statements. Both of these perform the same results:
10 PRINT''A";Z$;"WORD'';CHR$(65);"NOW $ "
20 P R I N T ' ' A ' ' Z $ " W O R D " C H R $ ( 6 5 ) " N O W $ "

REMOVING REM STATEMENTS

Although REM statements are useful to the programmer, removing them makes a
considerable amount of memory available again. It might be a good idea to create a
separate listing with REM statements.

USING VARIABLES
Replace repeated numbers with a variable. This is especially important with large
numbers such as memory addresses. POKEing several numbers in sequence conserves
memory if a variable is used, such as POKE 54273 + V, etc. Of course, single-letter
variable names require the least memory. Reuse old variables such as those used in FOR
. . . NEXT loops. Whenever possible, make use of integer variables since they consume
far less memory than floating-point variables.

ONE STEP BEYOND SIMPLE BASIC

USING B A S I C

INTELLIGENTLY

If information is used repeatedly, store the data in integer arrays, if possible. Use DATA
statements where feasible. Where a similar line is used repeatedly, create a single line
with variables and access it with GOSUBs. Use TAB and SPC functions in place of
extensive cursor controls.

MASKING BITS
Any of the bits within a byte can be controlled individually, using the Boolean operators
AND and OR. Calculations with AND and OR are based on a truth table (Table 3-1)
showing the results given all possible true and false combinations of the arguments X and Y.

X AND Y

X OR Y

Table 3 - 1 . A N D and O R T r u t h Table

With " 0 " representing False and " 1 " Truth, Table 3-1 shows how the operators
AND and OR work. The result of an AND operation between two bits is only true if
both bits are true (1). Otherwise the combination is false. Any bit combination with a
zero yields a zero in an AND operation. The result of an AND operation is only true
(equal to 1) if both bits are true (equal to 1).
The result of an OR operation is only false if each bit is false. Otherwise the result
is true. Any bit combination with a one yields a one in an OR operation. ONLY two
zeros result in a zero.
Observe the following example with the numbers 5 and 6 in binary form. When
you type the command PRINT 5 AND 6, the result is 4. Here's why:

ANDed

5=
6=

0000
0000

0101
0110

4=

0000

0100

Instead of adding, ANDing performs a bit-by-bit comparison in accordance with

the rules of the AND truth table. Compare column-for-column from the right: 1 AND
0 - 0 , 0 AND 1 - 0 , 1 AND 1 = 1, 0 AND 0 - 0 . The result " 0 1 0 0 " converted to
decimal is the number 4.
What is the effect of ORing 5 and 6? Again comparing bit-by-bit, using the rules
from the OR truth table:

97

98

COMMODORE 128

ORing

5=
6=

0000
0000

0101
0110

7=

0000

0111

The result 0111 is decimal 7. Notice from the right that 1 OR 0 = 1, 0 OR 1 - 1, 1 OR

1 = 1 and 0 OR 0 = 0.
Understanding how these OR and AND combinations work gives you the power to
control individual bits within your computer's memory. Many of the 8-bit bytes utilize
each bit for separate control parameters.

USING OR A N D A N D T O MODIFY
THE BIT VALUES IN A BYTE
A byte is a group of eight binary digits labeled, from right to left, 0 to 7. Each binary
digit position represents a decimal value equal to two raised to the power of the position
number. For example, the decimal value of position 6 is 2**6 or 64. From left to right
the positions are:
7

and the corresponding values in decimal are:

128

64

32

16

To turn on a bit, place a " 1 " in its position. To turn it off, enter a " 0 " . Hence the
binary 10010000 has bits 4 and 7 on. Their values are 128 and 16. So if a particular byte
is POKED with 144 (128+ 16), these two bits are turned on. To turn bits on, store
(POKE) a new value to that bytea value equal to the sum of all the decimal
equivalents of all the bits that are enabled (on). Of course, you do not always know
which bits are already on. You may only want to turn on specific bits without
affecting the others. That's the purpose of the logical operations AND and OR.
First, obtain the decimal value of the byte by PEEKing. Then add the decimal
value of the bit you wish to turn on. The following command turns on bit 2 of memory
address " V " :
POKEV, PEEK(V) + 4
This assumes bit 2 (third bit from the right) had a value of 0. Had it already been
" o n , " it would have no effect. To prevent such confusion, the C128 uses the power of
Boolean Logic.
Ideally you want to read (PEEK) each bit. The proper approach is to OR the byte
with an operand byte which will yield the desired binary value. Suppose we want to
turn on bit 5; the operand byte becomes 00100000. By ORing this with any byte it will
affect only bit 5, because any combination involving 1 in an OR operation results in 1.
Thus no bit already ON can be inadvertently turned off.
POKEV,PEEK(V) OR 32
Just as OR turns a switch on, AND can turn a switch offwith a slight difference.
AND results in a " 1 " only if both bits compared are " 1 . " The trick is to compare the

ONE STEP BEYOND SIMPLE BASIC

byte in question with an operand byte of all ON bits except the bit you want turned off.
Bits to remain on will not be affected. To turn off bit 5, AND the byte in question with
the mirror image of 00100000 or the operand byte 11011111. In decimal this value is
always 255 minus the value of the bit(s) you want to turn off. Thus:
POKEV,PEEK(V) AND (255-32)
turns off bit 5.
Use OR to turn bits ON
Use AND to turn bits OFF
EXAMPLES:
POKEW,PEEK(W) OR 129

Turns ON bits 0 and 7 of memory address W.

POKES,PEEK(S) AND 126

Turns OFF bits 0 and 7 of memory register S

(Remember 255-129 -

POKEC,PEEK(C)AND254
POKEC,PEEK(V)OR63

126)

Turns OFF bit 0

Turns ON all bits except 6 and 7

DEBUGGING PROGRAMS
No program when first written is free of " b u g s " or errors. The process of finding errors
and removing them, debugging, combines editing with problem solving.

SYNTAX ERRORS
Syntax errors result from misspelling or misusing the guidelines and formats of BASIC
commands. An error message is displayed on the screen defining the line where the
error occurs. Typing HELP < R E T U R N > or pressing the HELP key also highlights the
line with the error. Common syntax errors include misspelled BASIC terms, misplaced
punctuation, unpaired parentheses, reserved variable names such as TI$, use of line
numbers that do not exist, etc.

LOGIC ERRORS
Sometimes errors exist in the program logic, with the result that the program doesn't do
exactly what you think it is supposed to do. Some logic errors are caused by the order of
instructions. One common fault occurs when you forget that anything on a line after an
IF statement is affected by the IF condition.
Some errors in logic require a trial-and-error investigation. This is best initiated by
asking the computer for help in BASIC.

USING A DELAY
Where the computer responds rapidly, it often helps to see a response by inserting a
SLEEP command for a temporary time delay. This gives you a chance to see exactly
what is happening in the program.

99

100

COMMODORE 128

USING PRINT A N D STOP

Insert STOP statements within your program prior to the suspect instruction line. Good
locations are at the end of specific tasks. Run the program. After the STOP statement
puts you into direct mode, use the PRINT command to identify clues to the problem by
determining the values of the various variables, especially those within loops. Check
these with what you expect. Continue the program with CONT to the next STOP
statement until you modify your program.

TRAPPING A N ERROR
Debugging is the art of detecting the source of problem. The following program is
perfectly valid; however, it produces an error when B equals zero.
10 INPUT A,B
20 PRINT A/B
30 GOTO 10
Although in this case the computer defines the error as a DIVISION BY ZERO
error, it is not always obvious how the variable B became a zero. It could have been
derived from a complex formula embedded in your program, or directly inputting the
value zero into a variable.
The BASIC TRAP command has a technique of trapping such an error in a
program without crashing. Since you can't always foresee all the possible values of the
variable B, you can screen the probable error of division of zero by including a TRAP at
the beginning of the program.
5
10
20
30
50
60
70

TRAP 50
INPUT A,B
PRINTA/B
GOTOlO
PRINT' 'DIVISION BY ZERO IS NOT POSSIBLE"
PRINT"ENTER ANOTHER NUMBER FOR B BESIDES Z E R O "
RESUME

RESUME is required after the TRAP response in order to reactivate the TRAP. If
you include the option to enter a replacement for B, RESUME without a line number
returns to the cause of the errorline 20and executes it as follows:
65

INPUT B

The use of RESUME NEXT proceeds with the next line after the TRAP command,
i.e., line 10.
TRAP tells the computer to go to a specific line number whenever an error occurs.
Do NOT use TRAP until you have removed all syntax errors first. TRAP can only catch
the error condition it is looking for. An error in the syntax or the logic of your TRAP
routine may cause an error, or may not catch the error that you are looking for. In other
words, TRAP routines are sensitive to errors, too.

ONE STEP BEYOND SIMPLE BASIC

ERROR FUNCTIONS
Several reserved variables inherent in the system store information about program
errors. ER stores the error number. EL stores the relevant program line number.
ERR$(N) returns the string representing ER or EL. In the example of division by zero,
ERR$(ER) returns "DIVISION BY Z E R O " and ERR$(EL) returns " B R E A K " . Add
this to the program in the previous section. See Appendix A for a complete listing of
errors.

DOS

ERRORS

Information on disk errors is determined from the variables DS and DS$ where DS is the
error number (See Appendix B) and DS$ provides the error number, error message, and
track and sector of the error. DS$ reads the disk error channel and is used during a disk
operation to determine why the disk drive error light is blinking.
Trying to read a directory without a disk in place results in the following error
when the PRINT DS$ command is issued:
74, DRIVE NOT READY, 00, 00
Appendix B highlights specific causes of errors. To convert a function key to read
the disk-drive error channel automatically, use:
KEY 1, "PRINT DS$ + CHR$(13)

TRACING A N ERROR
Some programs have many complex loops that are tedious to follow. A methodical
step-by-step trace is useful. The BASIC TRON and TROFF commands can be used
within a program as a debugging tool to trace specific routines.
Some errors can only be found by acting like the computer and methodically
following each instruction step-by-step, and then doing all the calculations until you
discover something wrong. Fortunately the Commodore 128 can trace errors for you.
Enter the direct command TRON prior to running a program. The program displays each
line number as they occur in brackets, followed by each result. (To slow down the
display, hold the Commodore (Qi ) key down.)
Try it with this double loop:
10
20
30
40
50

FOR A = 1T05
FOR B - 2T06
C - B*A:K - K + C:PRINTK
NEXTB:NEXTA
PRINTK

The results will start off like this:

[10] [20] [30] [30] [30]2
[40] [30] [30] [30]5
meaning the first printed result is the number 2 after operations in lines 10, 20, 30 are
performed. Then lines 40 and 30 result in 5, etc. Notice three activities were performed
in line 30. The Trace function is turned off with the direct command TROFF.

101

102

COMMODORE 128

WINDOWING
The standard screen display size is 40- or 80-columns by 25 lines. It is often convenient
to have a portion of the screen available for other work. The process of producing and
isolating small segments of your screen is called "windowing."

DEFINING A WINDOW
There are two ways to create a windoweither directly or within a program using the
WINDOW command. Using the ESCape key followed by a T or B is all that is
necessary to describe and set a window.
Here's how to define a window in direct mode:
1.
2.

Move the cursor to the upper-left corner position of the proposed window.
Press the (ESC) escape key, then press the letter T key.
Move the cursor to the bottom right corner and press the escape key (ESC)
then press the letter B key.

Now that your window is in effect, all commands and listings remain in the
window until you exit by pressing the HOME key twice. This is useful if you have a
listing on the main screen and wish to keep it while you display something else in a
window. See Chapter 13, the Commodore 128 Operating System, under the screen
editor for special ESCape controls within a window.
Although it is possible to define several windows simultaneously on the screen, only
one window can be used at a time. The other windows remain on the display, but they are
inactive. To re-enter a window you have exited, define the top and bottom corners of the
window with the ESC T and ESC B commands, respectively, as you did originally.
The second way to define a window is with the BASIC window command. The
command:
WINDOW 20,12,39,24,1
establishes a window with the top-left corner at column 20, row 12, and the bottomright corner at column 39, row 24. The 1 signifies the area to be cleared. Once this
command is specified, all activities are restricted to this window.
Use the window command within a program whenever you want to perform an
activity in an isolated area on the screen.

O N E STEP B E Y O N D SIMPLE BASIC

ADVANCED B A S I C
PROGRAMMING TECHNIQUES
FOR COMMODORE MODEMS
The following information tells you how to:
1.
2.
3.
4.

Generate Touch Tone frequencies

Detect telephone ringing
Program the telephone to be on or off the hook
Detect carrier

The programming procedures operate in C128 or C64 modes with the Modemy300.
In C128 mode, select a bank configuration which contains BASIC, I/O, and the Kernal.

GENERATING T O U C H TONE
(DTMF) FREQUENCIES
Each button on the face of a Touch Tone telephone generates a different pair of tones
(frequencies). You can simulate these tones with your Commodore 128 computer. Each
button has a row and column value in which you must store the appropriate memory
location in order to output the correct frequency. Here are the row and column
frequency values that apply to each button on the face of your Touch Tone telephone:

TOUCH TONE FREQUENCY

Row
Row
Row
Row

1 (697
2 (770
3 (852
4 (941

Hz)
Hz)
Hz)
Hz)

TABLE

COLUMN 1 (1029 HZ)

COLUMN 2 (1336 HZ)

COLUMN 3 (1477 HZ)

1
4
7
*

2
5
8
0

3
6
9
#

To generate these tones in BASIC with your Commodore 128, follow this procedure:
1.

Initialize the sound (SID) chip with the following BASIC statements:
SID POKE
POKE
POKE

2.

54272
SID + 24,15:POKE SID + 4,16
SID + 11,16:POKE SID + 5,0:POKESID + 12,0
SID + 6,15*16:POKESID + 13,15*16:POKESID + 23,0

Next, select one row and one column value for each digit in the telephone
number. The POKE statement for each row and column are as follows:

103

104

COMMODORE 128

Column 1: POKE SID, 117:POKE SID + 1,77

Column 2: POKE SID,152:POKE SID + 1,85
Column 3: POKE SID,161, POKE SID + 1,94
Row 1: POKE SID 4- 7,168:POKE SID + 8,44
Row 2: POKE SID + 7,85,:POKE SID + 8,49
Row 3: POKE SID + 7,150:POKE SID + 8,54
Row 4: POKE SID + 7,74 :POKE SID + 8,60
For example, to generate a tone for the number 1, POKE the values for row
1, column 1 as follows
POKE SlD + 7,168:POKE SID + 8,44:REM ROW 1
POKE SID,117:POKE SID + l,77:REM COLUMN 1
3.

Turn on the tones and add a time delay with these statements:
POKE SID 4- 4,17:POKE SID + ll,17:REM ENABLE TONES
FOR I = 1 TO 50:NEXT:REM TIME DELAY

4.

Turn off the tones and add a time delay with the following statements:
POKE SID 4- 4,16:POKE SID + ll,16:REM DISABLE TONES
FOR I = 1 TO 50:NEXT:REM TIME DELAY

5.
6.

Now repeat steps 2 through 4 for each digit in the telephone number you are
dialing.
Finally, disable the sound chip with this statement:
POKE SID + 24,0

DETECTING TELEPHONE RINGING

To detect whether your telephone is ringing using a Commodore 128, use the following
statement:
IF (PEEK(56577) AND 8) - 0 THEN PRINT " R I N G I N G "
If bit 3 of location 56577 contains a value other than 0, the phone is not ringing.

PROGRAMMING THE TELEPHONE

T O BE O N OR OFF THE HOOK
To program the phone to be off the hook using a Commodore 128, enter the following
statements in a program:
OH - 56577:HI - 32:LO - 255 - 32
POKE (OH 4 2),(PEEK(OH + 2) OR HI)
POKE OH,(PEEK(OH) AND LO)
To hang up the phone with a Commodore 128, enter this statement in a program:
POKE OH,(PEEK(OH) OR HI)

ONE STEP BEYOND SIMPLE BASIC

Here is the procedure to dial and originate a communication link:

1.
2.
3.
4.
5.
6.

Set the modem's answer/originate switch to the " 0 " for originate.
Program the telephone to be OFF the hook.
Wait 2 seconds (FOR I = 1 to 500:NEXT:REM 2-SECOND DELAY)
Dial each digit and follow it with a delay (FOR I - 1 TO 50:NEXT)
When a carrier (high pitched tone) is detected, the Modem/300 automatically
goes on-line with the computer you are connecting with.
Program the phone to hang up when you are finished.

Here is the procedure to answer a call:

1.
2.
3.
4.
5.

Set the modem's answer/originate switch to " A " for answer.

To manually answer, program the telephone to be OFF the hook.
To automatically answer, detect if the phone is ringing then program the
phone to be OFF the hook.
The Modem/300 automatically answers the call.
Program the phone to hang up when you are finished.

DETECTING CARRIER
Your Commodore Modem/1200 and Modem/300 are shipped from the factory with the
ability to detect a carrier on the Commodore 128.
That ability is useful in an unattended auto-answer mode. By monitoring the
carrier detect line, the computer can be programmed to hang up after loss of carrier.
Since a caller may forget to hang up, your program should monitor the transmit and
receive data lines. If there is no activity for five minutes or so, the modem itself should
hang up.
To detect carrier on the Commodore 128, the following statement can be used in a
BASIC program:
OH = 56577:
IF ((PEEK (OH) AND 16) = 0) THEN PRINT "CARRIER DETECTED"
If bit 4 of location 56577 contains a value other than 0, then no carrier is detected.

ROTARY (PULSE) DIALING

In order to dial a number with a modem, the software in the computer must generate
pulses at a prescribed rate. In the United States and Canada, the rate is between 8 and 10
pulses per second with a 58% to 64% break duty cycle. Most people, however, use 10
pulses per second with a 60% break duty cycle.
So to make a call, your software must first take the phone " o f f - h o o k " (the
equivalent of you picking up the receiver). Then to dial the first digit, a 3 for instance,

105

116

COMMODORE 128

the software must put the phone on-hook for 60 milliseconds and off-hook for 40
milliseconds. Repeat this process three times to dial a 3.
The same method is used to dial other digits, except 0, which is pulsed ten times.
Pause at least 600 milliseconds between each digit.

USING E S C APE CODES

To perform any of the escape capabilities within a program, use a line such as:
10150 PRINT CHR$(27) + " U "
to create an underline cursor (in 80-column only). For example, to clear from the cursor
to the end of a window:
10160 PRINT CHR$(27) + " @ "
(See the Screen Editor section of Chapter 13 for all the escape and control codes
available on the Commodore 128.)

RELOCATING BASIC
To relocate the beginning or ending of BASIC (in C128 mode) for additional memory or
to protect machine-language programs from being overwritten by BASIC text, it is
necessary to redefine the starting and ending pointers in required memory addresses.
The Start of BASIC pointer is located at address 45($2D) and 46($2E). The Top
of BASIC pointer is at addresses 4626($1212) and 4627($1213). The following instruction displays the default locations of the beginning and end of BASIC text, respectively
(when a VIC bit-mapped screen is not allocated):
PRINT PEEK(45),PEEK(46),PEEK(4626),PEEK(4627)
1

28

255

Since the second number in each case is the high byte value, the default start of
basic is 28*256 plus 1 or 7169 while the top is 255*256 or 65280.
The following command reduces the size of BASIC text (program) area by 4K by
lowering the top of BASIC to address 61184 (239*256):
POKE4626,239:POKE4627,0:NEW
To move the beginning of BASIC up in memory by lK, from 7168 to 8192, use
this command line:
POKE 46,32:POKE45,l:NEW
This is the case only when a bit-mapped graphics screen is not allocated. Remember, the beginning of BASIC starts at 16384($4000) when a bit-mapped screen is
allocated, and other parts of memory are shifted around.

ONE STEP BEYOND SIMPLE BASIC

MERGING PROGRAM A N D FILES

Files can be merged (combined) by opening an existing file and locating the pointer to
the end of the file so subsequent data can be written to the disk file. C128 BASIC has
included the APPEND command to accomplish this:
APPEND#5, "FILE N A M E "
opens channel 5 to a previously stored file named "FILE N A M E . " Subsequent write
(PRINT#5) statements will add further information to the file. APPEND is primarily
used for data files.
The command CONCAT allows the concatenation (combine in sequence) of two
files or programs while maintaining the name of the first.
CONCAT"PART2B" TO " P A R T 2 "
creates a new file called Part 2, consisting of the old Part 2, plus the new Part 2b in
sequence. Concatenated BASIC program files must be renumbered before they can
work. Other corrections may also be necessary.
The BASIC routines described in this chapter can greatly enchance the capabilities
of your programs. So far, BASIC has been discussed in detail. The machine language
programming introduced in Chapter 5 can extend program capabilities even further.
And, as shown in Chapter 7, for still greater flexibility and power, you can combine
BASIC and machine language in your programs.

107

4
COMMODORE 128
GRAPHICS
PROGRAMMING
HOW TO USE
THE GRAPHICS SYSTEM

109

114

COMMODORE 128

COMMODORE 128 VIDEO FEATURES

In C128 Mode, Commodore BASIC 7.0 offers fourteen high-level graphics commands
that make difficult programming jobs easy. You can now draw circles, boxes, lines,
points and other geometric shapes, with ten high level commands such as DRAW, BOX
and CIRCLE, and with four sprite commands. (The sprite commands are described in
Chapter 9.) You no longer have to be a machine language programmer, or purchase
additional graphics software packages to display intricate and visually pleasing graphics
displaysthe Commodore 128 BASIC graphics capabilities take care of this for you. Of
course, if you are a machine language programmer or a software developer, the
exceptional C128 video hardware features offer high price/performance value for any
microcomputer application.
The C128 graphics features include:
Specialized graphics and sprite commands

16 colors
6 display modes, including:
Standard character mode
Multi-color character mode
Extended background color mode
Standard bit map mode
Multi-color bit map mode
Combined bit map and character modes (split-screen)
8 programmable, movable graphic objects called SPRITES which make animation possible
Custom programmable characters
Vertical and horizontal scrolling
The Commodore 128 is capable of producing two types of video signals: 40column composite video, and 80-column RGBI video. The composite video signal,
channeled through a VIC II (Video Interface Controller) chip (8564)similar to that
used in the Commodore 64mixes all of the colors of the spectrum in a single signal to
the video monitor. The 8563 separates the colors red, green and blue to drive separate
cathode ray guns within the video monitor for a cleaner, crisper and sharper image than
composite video.
The VIC II chip supports all of the Commodore BASIC 7.0 graphics commands,
SPRITES, sixteen colors, and the graphic display modes mentioned before. The 80column chip, primarily designed for business applications, also supports sixteen colors
(a few of which are different from those of the VIC chip), standard text mode, and bit
map mode. Sprites are not available in 80-column output. Bit map mode is not
supported by the Commodore BASIC 7.0 language in 80-column output. The 80-column
screen can be bit mapped through programming the 8563 video chip with machine
language programs. See Chapter 10, Programming the 80-Column (8563) Chip, for
information on bit mapping the 80-column screen.

COMMODORE 128 GRAPHICS PROGRAMMING

This chapter discusses how to use the Commodore 128 graphics features through
BASIC using the VIC (40-column) screen. Except for the sprite commands, each
graphic command is listed in alphabetical order. The sprite commands are covered in
Chapter 9. Following the format of each command are example programs that illustrate
the features of that command. Wherever possible, machine language routines are
included to show how the machine language equivalent of a BASIC graphics command
operates.
Chapter 8, The Power Behind Commodore 128 Graphics, is a description of the
inner workings of the Commodore 128 graphics capabilities. It explains how screen,
color and character memory are used and how these memory components store and
address data in each display mode. Chapter 9 then explains how to use sprites with the
new BASIC commands. Chapter 9 also discusses the inner workings of sprites, their
storage and addressing requirements, color assignments, and describes how to control
sprites through machine language.

TYPES OF SCREEN DISPLAY

Your C128 displays information several different ways on the screen; the parameter
" s o u r c e " in the command pertains to three different modes of screen display.

TEXT DISPLAY
Text display shows only text or characters, such as letters, numbers, special symbols
and the graphics characters on the front faces of most C128 keys. The C128 can display
text in both 40-column and 80-column screen formats. Text display includes standard
character mode, multi-color character mode and extended background color mode.
The Commodore 128 normally operates in standard character mode. When you
first turn on the Commodore 128, you are automatically in standard character mode. In
addition, when you write programs, the C128 is in standard character mode. Standard
character mode displays characters in one of sixteen colors on a background of one of
sixteen colors.
Multi-color character mode gives you more control over color than the standard
graphics modes. Each screen dot, a pixel, within an 8-by-8 character grid can have one
of four colors, compared with the standard mode which has only one of two colors.
Multi-color mode uses two additional background color registers. The three background
color registers and the character color register together give you a choice of four colors
for each dot within an 8-by-8 dot character grid.
Each pixel in multi-color mode is twice as wide as a pixel in standard character
mode and standard bit map mode. As a result, multi-color mode has only half the
horizontal resolution (160 X 200) of the standard graphics modes. However, the
increased control of color more than compensates for the reduced horizontal resolution.
Extended background color mode allows you to control the background color and
foreground color of each character. Extended background color mode uses all four
background color registers. In extended color mode, however, you can only use the first
sixty-four characters of the screen code character set. The second set of sixty-four
characters is the same as the first, but they are displayed in the color assigned to

111

112

COMMODORE 128

background color register two. The same holds true for the third set of sixty-four
characters and background color register three, and the fourth set of sixty-four characters
and background color register four. The character color is controlled by color memory.
For example, in extended color mode, you can display a purple character with a yellow
background on a black screen.
Each of the character display modes receives character information from one of
two places in the Commodore 128 memory. Normally, character information is taken
from character memory stored in a separate chip called ROM (Read Only Memory).
However, the Commodore 128 gives you the option of designing your own characters
and replacing the original characters with your own. Your own programmable characters
are stored in RAM.

BIT MAP DISPLAY

Bit map mode allows you to display highly detailed graphics, pictures and intricate
drawings. This type of display mode includes standard bit map mode and multi-color bit
map mode. Bit map modes allow you to control each individual screen dot or pixel
(picture element) which provides for considerable detail in drawing pictures and other
computer art. These graphic displays are only supported in BASIC by the VIC chip.
The 80-column chip is designed primarily for character display, but you can bit
map it through your own programs. See Chapter 10, Programming the 80-Column (8563)
Chip, for detailed information.
The difference between text and bit map modes lies in the way in which each
screen addresses and stores information. The text screen can only manipulate entire
characters, each of which covers an area of 8 by 8 pixels on the screen. The more
powerful bit map mode exercises control over each pixel on your screen.
Standard bit map mode allows you to assign each screen dot one o f t w o colors. Bit
mapping is a technique that stores a bit in memory for each dot on the screen. In
standard bit map mode, if the bit in memory is turned off, the corresponding dot on the
screen becomes the color of the background. If the bit in memory is turned on, the
corresponding dot on the screen becomes the color of the foreground image. The series
of 64,000 dots on the screen and 64,000 corresponding bits in memory control the
image you see on the screen. Most of the finely detailed computer graphics you see in
demonstrations and video games are bit mapped high-resolution graphics.
Multi-color bit map mode is a combination of standard bit map mode and
multi-color character mode. You can display each screen dot in one of four colors within
an 8 X 8 character grid. Again, as in multi-color character mode, there is a tradeoff
between the horizontal resolution and color control.

SPLIT SCREEN DISPLAY

The third type of screen display, split screen, is a combination of the first two types.
The split-screen display outputs part of the screen as text and part in bit map mode
(either standard or multi-color). The C128 is capable of this since it depends on two
parts of its memory to store the two screens: one part for text, and the other for
graphics.

COMMODORE 128 GRAPHICS PROGRAMMING

COMMAND SUMMARY
Following is a brief explanation of each graphics command available in BASIC 7.0:
B O X : Draws rectangles on the bit-map screen
CHAR: Displays characters on the bit-map screen
CIRCLE: Draws circles, ellipses and other geometric shapes
COLOR: Selects colors for screen border, foreground, background and characters
DRAW: Displays lines and points on the bit-map screen
GRAPHIC: Selects a screen display (text, bit map or split-screen bit map)
GSHAPE: Gets data from a string variable and places it at a specified position on the
bit-map screen
LOCATE: Positions the bit-map pixel cursor on the screen
P A I N T : Fills area on the bit-map screen with color
SCALE: Sets the relative size of the images on the bit-map screen
SSHAPE: Stores the image of a portion of the bit-map screen into a text-string variable
W I D T H : Sets the width of lines drawn
The following paragraphs give the format and examples for each of the non-sprite
BASIC 7.0 graphic commands. For a full explanation of each of these commands, see
the BASIC 7.0 Encyclopedia in Chapter 2.

BOX
Draw a box at a specified position on the screen.
BOX [color source], XI, Yl[,X2,Y2][,angle][,paint]
where:
color source

XI, Y1
X2, Y2
angle
paint

0 = Background color
1 = Foreground color
2 = Multi-color 1
3 = Multi-color 2
Top left corner coordinate (scaled)
Bottom right corner opposite X I , Y1, is the pixel cursor
location (scaled)
Rotation in clockwise degrees; default is 0 degrees
Paint shape with color
0 = Do not paint
1 = Paint

113

114

COMMODORE 128

EXAMPLES:
10 COLOR O,l:COLOR l,6:COLOR 4,1
2 0 GRAPHIC l,l:REM SF,LECT BMM
30 BOX 1,10,10,70,70,90,1:REM DRAW FILLED GREEN BOX
40 FOR 1=20 TO 140 STEP 3
50 BOX 1,1,I,I + 6 0,1 + 60,I + 8 0:REM DRAW AND ROTATE BOXES
60 NEXT
70 BOX 1,140,140, 200, 200, 220,1:REM DRAW 2ND FILLED GREEN BOX
80 COLOR l,3:REM SWITCH TO RED
90 BOX 1 , 150 , 20 , 210 , 80 , 90 , 1 :REM DRAW FILLED RED BOX
100 FOR 1=20 TO 140 STEP 3
110 BOX 1 , 1+130 , 1 , 1 + 190 ,1 + 60 , 1 + 7 0 :REM DRAW AND ROTATE RED BOXES
120 NEXT
130 BOX 1,270,140,330,200,210,1:REM DRAW 2ND FILLED RED BOX
140 SLEEP 5 :REM DELAY
15 0 GRAPHIC 0,1:REM SWITCH TO TEXT MODE

10 COLOR O,l:COLOR 4,l:COLOR 1,6

20 GRAPHIC 1,1
30 BOX 1,0,0,319,199
40 FOR X=10 TO 160 STEP 10
50 C=X/10
6 0 COLOR 1,C
70 BOX l,X,X,320-X,320-X
8 0 NEXT
90 SLEEP 5
100 GRAPHIC 0,1

10 COLOR O,l:COLOR 4,l:COLOR 1,6

20 GRAPHIC 1,1
30 BOX 1,50,50,150,120
40 BOX 1,70,70,170,140
50 DRAW 1,50,50 TO 70,70
60 DRAW 1,150,120 TO 170,140
70 DRAW 1,50,120 TO 70,140
80 DRAW 1,150,50 TO 170,70
90 CHAR 1,20,20,"CUBE EXAMPLE"
100 SLEEP 5
110 GRAPHIC 0,1

10 COLOR l,6:COLOR 4,l:COLOR 0,1

20 GRAPHIC l,l:REM SELECT BIT MAP MODE
30 DO :REM CALCULATE RANDOM POINTS
40 Xl=INT(RND(l)*319+l)
50 X2=INT(RND(1)*319 + 1)
60 X3=INT(RND(1)*319+1)
70 X4=INT(RND(1)*319 + 1)
80 Yl=INT(RND(l)*199+l)
90 Y2=INT(RND(1)* 19 9+1)
100 Y3=INT(RND(1)* 19 9+1)
110 Y4 = INT(RND(1)* 19 9 + 1)
120 BOX l,Xl,Yl,X2,Y2:REM DRAW THE RANDOM BOXES
130 BOX l,X3,Y3,X4,Y4
140 DRAW l,Xl,Yl TO X3,Y3:REM CONNECT THE POINTS
150 DRAW l,X2,Y2 TO X4,Y4
160 DRAW l,Xl,Y2 TO X3,Y4
170 DRAW 1,X2,Y1 TO X4,Y3
180 SLEEP2:REM DELAY
190 SCNCLR
200 LOOP:REM LOOP CONTINUOUSLY

COMMODORE 128 GRAPHICS PROGRAMMING

CHAR
Display characters at the specified position on the screen.
CHAR [color source],X,Y[,string][,RVS]
This is primarily designed to display characters on a bit mapped screen, but it can also
be used on a text screen. Here's what the parameters mean:
color source
X
Y
string
RVS

0 = Background
1 = Foreground
Character column (0-79) (wraps around to the next line
in 40-column mode)
Character row (0-24)
String to print
Reverse field flag (0 = off, 1 = on)

EXAMPLE:
10
20
30
40

COLOR 2,3: REM multi-color l = R e d

COLOR 3,7: REM multi-eolor2 = Blue
GRAPHIC 3,1
CHAR 0,10,10, " T E X T " , 0

CIRCLE
Draw circles, ellipses, arcs, etc. at specified positions on the screen.
CIRCLE [color source],X,Y[,Xr][,Yr]
[,sa][,ea][,angle][,inc]
where:
color source

X,Y
Xr
Yr
sa
ea
angle
inc

0 = background color
1 = foreground color
2 = multi-color 1
3 = multi-color 2
Center coordinate of the CIRCLE
X radius (scaled)
Y radius (default is xr)
Starting arc angle (default 0 degrees)
Ending arc angle (default 360 degrees)
Rotation in clockwise degrees (default is 0 degrees)
Degrees between segments (default is 2 degrees)

EXAMPLES:
CIRCLE1, 160,100,65,10
CIRCLE1, 160,100,65,50
CIRCLE1, 60,40,20,18,,,,45

Draws an ellipse.
Draws a circle.
Draws an octagon.

115

116

COMMODORE 128

CIRCLE1, 260,40,20,,,,,90
CIRCLE1, 60,140,20,18,,,, 120
CIRCLE1, + 2, + 2,50,50

Draws a diamond.
Draws a triangle.
Draws a circle (two pixels down and two to
the right) relative to the original coordinates of
the pixel cursor.

SAMPLE PROGRAMS:
10 REM SUBMARINE TRACKING SYSTEM
2 0 COLOR O,l:COLOR 4,l:COLOR l,2:REM SELECT BKGRND, BRDR,SCREEN COLORS
3 0 GRAPHIC l,l:REM ENTER BIT MAP MODE
40 BOX 1,0,0,319,199
50 CHAR 1,7,24,"SUBMARINE TRACKING SYSTEM" :REM DISPLAY CHARS ON BIT MAP
6 0 COLOR l,3:REM SELECT RED
70 XR=0:YR=0:REM INIT X AND Y RADIUS
8 0 DO
90 CIRCLE 1,160,100,XR,YR, 0 , 360, 0 , 2 :REM DRAW CIRCLES
100 XR=XR+10:YR=YR+10:REM UPDATE RADIUS
110 LOOP UNTIL XR=9 0
120 DO
130 XR= 0:YR= 0
140 DO
150 CIRCLE 0,160,10 0,XR,YR,0,3 60,0,2 :REM ERASE CIRCLE
160 COLOR 1,2 :REM SWITCH TO WHITE
170 DRAW 1 , 160 , 100+XR:DRAW 0,160, 100 + XR:REM DRAW SUBMARINE BLIP
180 COLOR l,3:REM SWITCH BACK TO RED
190 SOUND 1,16 000,15:REM BEEP
200 CIRCLE 1,160,100,XR,YR, 0 , 360 , 0 , 2 :REM DRAW CIRCLE
210 XR=XR+10:YR=YR+10 :REM UPDATE RADIUS
220 LOOP UNTIL XR=90 :REM LOOP
2 30 LOOP
10
20
30
40
50
60
70
80
90

COLOR O,l:COLOR 4,l:COLOR 1,7

GRAPHIC l,l:REM SELECT BMM
X=150:Y= 150:XR=150:YR=15 0
DO
CIRCLE l,X,Y,XR,YR
X=X + 7 :Y=Y-5:REM INCREMENT X AND Y COORDINATES
XR=XR-5 :YR=YR-5:REM DECREMENT X AND Y RADII
LOOP UNTIL XR=0
GRAPHIC 0,1:REM SELECT TEXT MODE

COLOR
Define colors for each screen area.
COLOR source number, color number
This statement assigns a color to one of the seven color areas:
AREA

SOURCE

0
1
2
3
4
5
6

40-column (VIC) background

40-column (VIC) foreground
multi-color 1
multi-color 2
40-column (VIC) border
character color (40- or 80-column screen)
80-coIumn background color

Colors codes are in the range 1-16.

COMMODORE 128 GRAPHICS PROGRAMMING

COLOR CODE

COLOR

COLOR CODE

1
2
3
4
5
6
7
8

Black
White
Red
Cyan
Purple
Green
Blue
Yellow

9
10
11
12
13
14
15
16

COLOR

Orange
Brown
Light Red
Dark Gray
Medium Gray
Light Green
Light Blue
Light Gray

Color Codes in 40-Column ( V I C ) O u t p u t

EXAMPLE:
COLOR 0, 1:
COLOR 5, 8:

Changes background color of 40-column screen to black.

Changes character color to yellow.

SAMPLE PROGRAM:
10 REM CHANGE FOREGROUND BIT MAP COLOR
20 GRAPHIC 1,1
30 1 = 1
4 0 DO
50 COLOR 1,1
60 BOX 1,100,100,219,159
70 I=I+1:SLEEP 1
80 LOOP UNTIL 1=17
90 GRAPHIC 0,1
100 REM CHANGE BORDER COLOR

110 1=1
120
130
140
150
16 0
170
180
190
200
210
220
230
240
25 0
260
270
280
290

DO
COLOR 4,1
I=I+1:SLEEP 1
LOOP UNTIL 1=17
REM CHANGE CHARACTER COLOR
1=1
DO
COLOR 5,1
PRINT"COLOR CODE";I
I=I+1:SLEEP 1
LOOP UNTIL 1=17
REM CHANGE BACKGROUND COLOR
1=1
DO
COLOR 0,1
I = I + 1:SLEEP 1
LOOP UNTIL 1=17
COLOR O,l:COLOR 4,l:COLOR 5,2

DRAW
Draw dots, lines and shapes at specified positions on screen.
DRAW [color source], [XI, Yl][TO X2, Y2] . . .
Here are the parameter values:

117

118

COMMODORE 128

where:
color source

X1,Y1
X2,Y2

0 Bit map background

1 Bit map foreground
2 Multi-color 1
3 Multi-color 2
Starting coordinate (0,0 through 319,199) (scaled)
Ending coordinate (0,0 through 319,199) (scaled)

EXAMPLES:
Draw a dot.
DRAW 1, 100, 50
Draw a line.
DRAW , 10, 10 TO 100,60
DRAW , 10, 10 TO 10,60 TO 100,60 TO 10,10 Draw a triangle.
SAMPLE PROGRAMS:
10 REM DRAW EXAMPLES
2 0 COLOR O,l:COLOR 4,l:COLOR 1,6
30 GRAPHIC 1,1
40 CHAR 1,10,1,"THE DRAW COMMAND"
50 X=10
60 DO
70 DRAW l,X,50:REM DRAW POINTS
8 0 X=X+10
90 LOOP UNTIL X=320
100 CHAR 1,12,7 ,"DRAWS POINTS"
110 Y=7 0
120 DO
130 Y=Y+5
140 DRAW l,l,Y TO Y,Y :REM DRAW LINES
150 LOOP UNTIL Y=130
160 CHAR 1 , 18,11,"LINES"
170 DRAW 1,10,140 TO 10,199 TO 90,165 TO 40,160 TO 10,140:REM DRAW SHAPE 1
180 DRAW 1,120,145 TO 140,195 TO 195,195 TO 225,145 TO 120,145:REM DRAW SHAPE
190 DRAW 1,250,199 TO 319,199 TO 319,60 TO 250,199:REM DRAW SHAPE 3
200 CHAR l,22,15,"AND SHAPES"
210 SLEEP 5:GRAPHIC 0,1
10 COLOR 0,1:COLOR 4,l:COLOR 1,7
20 GRAPHIC l,l:REM SELECT BMM
30 Y=1
4 0 DO
50 DRAW 1,1,Y TO 3 20,Y:REM DRAW HORIZONTAL LINES
60 Y=Y+10
70 LOOP WHILE Y<200
75 X=1
8 0 DO
90 DRAW 1,X,1 TO X,200:REM DRAW VERTICAL LINES
95 X=X+10
97 LOOP WHILE X<320
100 COLOR l,3:REM SWITCH TO RED
110 DRAW 1,160,0 TO 160,200:REM DRAW X AXIS IN RED
120 DRAW 1,0,100 TO 320,100:REM DRAW Y AXIS IN RED
130 COLOR l,6:REM SWITCH TO GREEN
140 DRAW 1,0,199 TO 50,100 TO 90,50 TO 110,30 TO 150,20 TO 180,30
150 DRAW 1,180,30 TO 220,10 TO 260,80 TO 320,0:REM DRAW GROWTH CURVE
160 CHAR 1,7,23,"PROJECTED SALES THROUGH 1990"
170 CHAR 1 ,1 , 21 , "1970
1975
1980
1985
1990"
180 SLEEP 10:GRAPHIC 0,1:REM DELAY AND SWITCH TO TEXT MODE

COMMODORE 128 GRAPHICS PROGRAMMING

GRAPHIC
Select a graphic mode.
1) GRAPHIC mode [,clear][,s]
2) GRAPHIC CLR
This statement puts the Commodore 128 in one of the six graphic modes:

MODE

DESCRIPTION

0
1
2
3
4
5

40-column text
standard bit map graphics
standard bit map graphics (split screen)
multi-color bit map graphics
multi-color bit map graphics (split screen)
80-coIumn text

EXAMPLES:
GRAPHIC 1,1
GRAPHIC 4,0,10
GRAPHIC 0
GRAPHIC 5
GRAPHIC CLR

Select standard bit map mode and clear the bit map.
Select split screen multi-color bit map mode, do not clear
the bit map and start the split screen at line 10.
Select 40-column text.
Select 80-column text.
Clear and deallocate the bit map screen.

SAMPLE PROGRAM:
10 REM GRAPHIC MODES EXAMPLE
2 0 COLOR O,l:COLOR 4,l:COLOR 1,7
30 GRAPHIC l,l:REM ENTER STND BIT MAP
40 CIRCLE 1,160,100,60,60
50 CIRCLE 1,160,100,30,30
60 CHAR 1,9,24,"STANDARD BIT MAP MODE"
7 0 SLEEP 4
80 GRAPHIC 0,1:REM ENTER STND CHAR MODE
9 0 COLOR l,6:REM SWITCH TO GREEN
100 FOR I=lTO 25
110 PRINT"STANDARD CHARACTER MODE"
120 NEXT
130 SLEEP 4
140 GRAPHIC 2,l:REM SELECT SPLIT SCREEN
150 CIRCLE 1,160,70,50,50
160 CHAR 1 , 14,1, "SPLIT SCREEN"
170 CHAR 1,8,16,"STANDARD BIT MAP MODE ON TOP"
180 FOR 1=1 TO 25
190 PRINT" STANDARD CHARACTER MODE ON THE BOTTOM"
2 00 NEXT
210 SLEEP 3:REM DELAY
220 SCNCLR:REM CLEAR SCREEN
230 GRAPHIC CLR:REM DE-ALLOCATE BIT MAP

GSHAPE
Retrieve (load) the data from a string variable and display it on a specified coordinate.
GSHAPE string variable [X,Y][,mode]

119

120

COMMODORE 128

where:
string
X,Y

Contains shape to be drawn

Top left coordinate (0,0 through 319,199) telling where to
draw the shape (scaledthe default is the pixel cursor)
Replacement mode:
0 = place shape as is (default)
1 = invert shape
2 = OR shape with area
3 = AND shape with area
4 = XOR shape with area

mode

SAMPLE PROGRAM:
10 REM DRAW, SAVE AND GET THE COMMODORE SYMBOL
2 0 COLOR O,l:COLOR 4,l:COLOR 1,7
30 GRAPHIC l,l:REM SELECT BMM
40 CIRCLE 1 , 160, 100, 20,15 :REM OUTER CIRCLE
50 CIRCLE 1 , 160, 100, 10, 9:REM INNER CIRCLE
60 BOX 1 , 165 , 8 5, 18 5, 115 :REM ISOLATE AREA TO BE ERASED
70 SSHAPE A$, 166 , 8 5 , 18 5, 115 :REM SAVE THE AREA INTO A$
80 GSHAPE A$, 166 , 8 5 , 4 :REM EXCLUSIVE OR THE AREA-THIS (ERASES) TURNS OFF PIXELS
9 0 DRAW 0,165,94 TO 165,106:REM TURN OFF (DRAW IN BKGRND COLOR) PIXELS IN "C="
100 DRAW 1,166,94 TO 166,99 TO 180,99 TO 185,94 TO 166,94:REM UPPER FLAG
110 DRAW 1,166,106 TO 166,101 TO 180,101 TO 185,106 TO 166,106:REM LOWER FLAG
120 PAINT 1,160,110:REM PAINT "C"
130 PAINT 1,168,98 :REM UPPER FLAG
140 SLEEP 5:REM DELAY
150

SSHAPE

160
170
180
190
200
210
220
230
240
250
260
270
280

DO
SCNCLR
Y=10
DO
X=10
DO
GSHAPE B$,X,Y:REM GET AND DISPLAY SHAPE
X=X+50:REM UPDATE X
LOOP WHILE X<280
Y=Y+4 0:REM UPDATE Y
LOOP WHILE Y<160
SLEEP 3
LOOP

B $ , 13 7, 84 , 1 8 7 , 116 :REM SAVE

SHAPE

INTO

B$

LOCATE
Position the bit map pixel cursor (PC) on the screen.
LOCATE X, Y
EXAMPLE:
LOCATE 160,100
LOCATE +20,100
LOCATE + 30, + 20

Position the PC in the center of the bit map screen.

Nothing will be seen until something is drawn.
Move the PC 20 pixels to the right of the last PC position
and place it at Y coordinate 100,
Move the PC 30 pixels to the right and 20 down from
the previous PC position.

PAINT
Fill area with color.
PAINT [color source],X,Y[,mode]

COMMODORE 128 GRAPHICS PROGRAMMING

where:
color source

X,Y
mode

0 Bit map background

1 Bit map foreground (default)
2 Multi-color 1
3 Multi-color 2
starting coordinate, scaled (default at pixel cursor (PC))
0 = paint an area defined by the color source selected
1 = paint an area defined by any non-background source

EXAMPLE:
10 CIRCLE 1, 160,100,65,50
20 PAINT 1, 160,100

10 BOX 1, 10, 10, 20, 20

20 PAINT 1, 15, 15

Draws an outline of a circle.

Fills in the circle with color from source 1 (VIC
foreground), assuming point 160,100 is colored
in the background color (source 0).
Draws an outline of a box.
Fills the box with color from source 1, assuming
point 15,15 is colored in the background source

(0).
30 PAINT 1, + 1 0 , + 1 0

PAINT the screen in the foreground color source

at the coordinate relative to the pixel cursor's
previous position plus 10 in both the vertical and
horizontal positions.

SCALE
Alter scaling in graphics mode.
SCALE n [,Xmax,Ymax]
where:
n = 1 (on) or 0 (off)
X max = 320-32767
(default = 1023)
Y max = 200-32767
(default = 1023)
The default scale values are:
Multi-color mode
Bit map mode

X = 0 to 159 Y = 0 to 199
X = 0 to 319 Y - 0 to 199

EXAMPLES:
10 GRAPHIC 1,1
20 SCALE 1 :CIRCLE 1,180,100,100,100

Enter standard bit map, turn scaling

on to default size (1023, 1023) and
draw a circle.

121

122

COMMODORE 128

10 GRAPHIC 1,3
20 SCALE 1,1000,5000
30 CIRCLE 1,180,100,100,100

Enter multi-color mode, turn scaling

on to size (1000,5000) and draw a
circle.

SSHAPE
Save shapes to string variables.
SSHAPE and GSHAPE are used to save and load rectangular areas of multi-color or bit
mapped screens to/from BASIC string variables. The command to save an area of the
screen into a string variable is:
SSHAPE string variable, XI, Y1 [,X2,Y2]
where:
string variable
X1,Y1
X2,Y2

String name to save data in

Corner coordinate (0,0 through 319,199) (scaled)
Corner coordinate opposite (X1,Y1) (default is the PC)

EXAMPLES:
SSHAPE A$,10,10

SSHAPE B$, 20,30,47,51

SSHAPE D$, + 1 0 , + 10

Saves a rectangular area from the coordinate 10,10

to the location of the pixel cursor, into string variable A$.
Saves a rectangular area from top left coordinate
(20,30) through bottom right coordinate (47,51) into
string variable B$.
Saves a rectangular area 10 pixels to the right and 10
pixels down from the current position of the pixel
cursor.

Also, see the example program under GSHAPE for another example.

WIDTH
Set the width of drawn lines.
WIDTH n
This command sets the width of lines drawn using BASIC's graphic commands to either
single or double width. Giving n a value of 1 defines a single width line; a value of 2
defines a double width line.
EXAMPLES:
WIDTH 1 Set Single width for graphic commands
WIDTH 2 Set double width for drawn lines

5
MACHINE
LANGUAGE
O N THE
COMMODORE 128

123

124

COMMODORE 128

This chapter introduces you to 6502-based machine language programming. Read this
section if you are a beginner or novice machine language programmer. This section
explains the elementary principles behind programming your Commodore 128 in machine
language. It also introduces you to the 8502 machine language instruction set and how
to use each instruction. If you are already an experienced machine language programmer, skip this section and continue to the 8502 Instruction and Addressing Table at the
end of the chapter for reference material on machine language instructions. The 8502
instruction set is exactly the same as the 6502 microprocessor instruction set.

W H A T IS MACHINE LANGUAGE?
Every computer has its own machine language. The type of machine language depends
on which processor is built into the computer. Your Commodore 128 understands 8502
machine language, which is based on 6502 machine language, to carry out its operations. Think of the microprocessor as the brain of the computer and the instructions as
the thoughts of the brain.
Machine language is the most elementary level of code that the computer actually
interprets. True machine language is composed of binary strings of zeroes and ones.
These zeroes and ones act as switches to the hardware, and tell the circuit where to apply
voltage levels.
The machine language discussed in this chapter is symbolic 6502 Assembly
language as it appears in the C128 Machine Language Monitor. This is not the
full-blown symbolic assembly language as it appears in an Assembler package, since
symbolic addresses or other higher level utilities that an Assembler software package
would provide are not implemented.
Machine language is the lowest level language in which you can instruct your
computer. BASIC is considered a high-level language. Although your Commodore 128
has BASIC built in, the computer must first interpret and translate it to a lower level that
it can understand, before the computer can act upon BASIC instructions.
With each microinstruction, you give the computer a specific detail to perform.
The computer takes nothing for granted in machine language, unlike BASIC, where
many unnoticed machine-level functions are performed by one statement. One BASIC
statement requires several machine language instructions to perform the same operation.
Actually, when you issue a BASIC command, you are really calling a machine language
subroutine that performs a computer operation.

WHY USE MACHINE LANGUAGE?

If machine language is more intricate and complicated than BASIC, why use it? Certain
applications, such as graphics and telecommunications, require machine language because of its speed. Since the computer does not have to translate from a higher-level
language, it runs many times faster than BASIC.

MACHINE LANGUAGE O N THE COMMODORE 128

Programs such as those used in arcade games cannot operate in the relatively slow
speed of BASIC, so they are written in machine language. Other instances dictate the
use of machine language simply because those programming operations are handled
better than in a high-level language like BASIC. But some programming functions such
as string operations are easier in BASIC than in machine language. In these cases,
BASIC and machine language can be used together. You can find information on how to
mix machine language with BASIC in Chapter 7.
Inside your computer is a perpetually running program called the operating
system. The operating system program controls every function of your computer. It
performs functions at lightning speeds you are not even aware of.
The operating system program is written entirely in machine language and is
stored in a portion of the computer called the Kernal ROM. (Chapter 13 describes how
to take advantage of the machine language programs within the Kernal, and how to use
parts of the operating system in your own machine-language programs.)
Though machine language programming may seem more complicated and difficult
than BASIC at first, think back to when you didn't know BASIC or your first
programming language. That seemed difficult at first, too. If you learned BASIC or
another programming language, you can learn machine language. Although it's a good
idea to learn a higher-level language such as BASIC before you start machine language,
it's not absolutely necessary.

W H A T DOES MACHINE LANGUAGE

LOOK LIKE?
Chapter 2 describes the C128 BASIC 7.0 language. Most statements in BASIC start
with a BASIC verb or keyword, followed by an operand. The BASIC keywords
resemble English verbs. The operands are variables, or constants, that are part of an
expression. For example, A 4- B = 2, is an expression where A, B, and 2 are operands
in the expression. Machine-language instructions are similar, though they have a uniform
format. Here's the format for an 8502 symbolic machine language instruction as it
appears in the C128 Machine Language Monitor:
OP-CODE FIELD

OPERAND FIELD

OPERATION CODE (OP-CODE) FIELD

The first part of a machine-language instruction is called the operation code or op-code.
The op-code is comparable to a BASIC verb, in that it is the part of the instruction that
performs an action. A machine language op-code is also referred to in an assembly
language as a mnemonic. All 8502 (6502) machine language assembler mnemonics are
three-letter abbreviations for the functions they perform. For example, the first and most
common instruction you will learn is LDA, which stands for LoaD the Accumulator.
This chapter defines all of the mnemonics.

125

126

COMMODORE 128

OPERAND FIELD
The second portion of a machine-language instruction is the OPERAND field. In the
C128 Machine Language Monitor, the operand is separated from the op-code with at
least one space and preceded by a ($) dollar sign, ( + ) plus sign (decimal), (&)
ampersand (octal), or a (%) percent (binary) sign to signify that the operand is a
hexadecimal, decimal, octal or binary number. An ADDRESS is the name of or
reference to a specific memory location within the computer.
The number of a memory location is its address, just like houses on your street are
numbered. Addresses in your computer are necessary so they can receive, store and send
(LOAD) data back and forth to the microprocessor.
When you use the Commodore 128's built-in machine-language monitor, all
numbers and addresses default to hexadecimal numbers, but they can be represented in
decimal, octal or binary. The address is the hexadecimal number of the specified
memory location. When you use an ASSEMBLER, the addresses are referred to as
symbolic addresses. Symbolic addresses allow you to use variable names, instead of
absolute addresses that specify the actual memory location. You declare the symbolic
address to be the numeric address in the beginning of your machine language program or
allow the assembler to assign the address.
When you refer to that address later in the program, you can refer to the symbolic
address rather than to the absolute address as does the Machine Language Monitor.
Using an assembler and symbolic addresses make programming in machine language
easier than using the machine-language monitor and absolute addresses. You will
learn about the eleven addressing modes later in this chapter.
As you know, the second part of a machine-language instruction is the OPERAND. A machine language operand can be a constant; it does not necessarily have to be
an address reference. When a constant in machine language appears in place of an
address as the second part of an instruction, an operation is performed on a data value
rather than a memory location.
A pound sign ( # ) in front of the operand signifies immediate addressing, which
you will learn more about later in the chapter. The pound sign is only used as an aid for
the symbolic language programmer. The pound sign tells the computer to perform
machine-language instruction on a constant, and not an address. In the case of the
Machine Language Monitor, variable names are not allowed. To represent variables in
the monitor, you must reference a memory location where your variable data value is
stored.

EXAMPLES OF
MACHINE-LANGUAGE INSTRUCTIONS
LDA
LDA
LDA
LDA
LDA

$100
$10
($FA),Y
$2000,X
#$10

Absolute addressing
Zero page absolute addressing
Indirect indexed addressing
Indexed addressing (absolute)
Immediate addressing (constants)

MACHINE LANGUAGE O N THE COMMODORE 128

THE SIMILARITIES A N D DIFFERENCES BETWEEN A N

ASSEMBLER A N D A MACHINE LANGUAGE MONITOR
An assembler and machine-language monitor both provide for symbolic op-codes.
Assemblers typically allow symbolic operands as well, whereas the C128 machinelanguage monitor refers to addresses and operands literally (absolutely).
An assembler typically has two forms of a file: source code and object code.
Source code is the file you create when you are writing the program including symbolic
start addresses and comments.
The source code file is not executable. It must be assembled (in an intermediate
process) into object code, which is executable code.
The machine language monitor start address is determined by where you place the
actual instructions in memory. The monitor does not provide for comments. The resulting
program, once it is input, is executed immediately as a binary file. No intermediate
assembly step is needed.

THE 8502 MICROPROCESSOR REGISTERS

You have learned that an address is a reference to a specific memory location among the
2 banks of RAM within the Commodore 128. Separate and independent of those RAM
locations are special purpose work and storage areas within the microprocessor chip
itself, called registers. These registers are where the values are manipulated. The
manipulation of the microprocessor registers and their communication with the computer's memory (RAM and ROM) accomplishes all the functions of machine language and
your computer's operating system.
Figure 5-1 shows a block diagram of the 8502 microprocessor. As shown in the
figure, the 8502 microprocessor registers are:
Accumulator
X index register
Y index register
Status register
Program counter
Stack pointer
Following are descriptions of these registers.

THE ACCUMULATOR
The accumulator is one of the most important registers within the 8502 microprocessor.
As the name implies, it accumulates the results of specific operations. Think of
the accumulator as the doorway to your microprocessor. All information that enters
your computer must first pass through the accumulator (or the X or Y register).

127

128

COMMODORE 128

For example, if you want to store a value within one of the RAM locations, you must
first ioad the value into the accumulator (or the X or Y register) and then store it into the
specified RAM location. You cannot store a value directly into RAM, without placing it
into the accumulator or the index registers first. (The index registers are described in the
following section.)

Figure 5-1. 8502 Block Diagram

MACHINE LANGUAGE O N THE COMMODORE 128

All mathematical operations are performed within the arithmetic logic unit (ALU)
and stored in the accumulator. It is considered a temporary mathematical work area. For
example, you want to add two numbers, 2 + 3. First, load the accumulator with the 2.
Next add 3 with the ADC mnemonic. Now, you want to perform another operation. You
must store the answer from the accumulator into a RAM location before you perform the
next math operation. If you don't, your original answer is erased.
The accumulator is so important that it has an addressing mode of its own. All the
instructions using this mode pertain specifically to the accumulator. The following three
sample instructions pertain solely to the accumulator in its own addressing mode:
LDA - LOAD accumulator with memory
STA - STORE the accumulator in memory
ADC - ADD contents of memory to the accumulator
Details on all of the accumulator addressing commands are given later in this chapter.

THE X A N D Y INDEX REGISTERS

The second most used registers are the X and Y index registers. These index registers are
used primarily to modify an address by adding an index within a machine-language
instruction. They also can be used as temporary storage locations or to load values and
store them in RAM like the accumulator.
When modifying an address, the contents of the index registers are added to an
original address, called the base address, to find an address relative to the base address.
The resulting address yields the effective addressi.e., the location where a data value
is stored or retrieved. The effective address is acted upon by machine-language instructions. For example, you want to place the value 0 in locations 1024 through 1034. In
BASIC, here's how you do it:
10 FOR I = 1024 to 1034
20 POKE 1,0
30 NEXT
Here's how you do it in symbolic machine language by using the X or Y index
register. NOTE: Don't worry if you don't understand all of the following instructions. They
are discussed fully in the TYPES OF INSTRUCTIONS section, later in this chapter.
LDA # $ 0 0
TAX
START

STA $0400,X
INX
CPX # $ 0 B
BNE START
BRK

Load the Accumulator with 0

Transfer the contents of Accumulator (0) to X
Register.
Store contents of Accumulator in address $0400 + X
Increment the X register
Compare the X register with $0B (11 decimal)
If X register does not equal 11 branch to START.
Stop

* = In the machine-language monitor the symbolic label START is not allowed, so it

would appear as an absolute address reference (eg; $183B).

129

130

COMMODORE 128

The BASIC example above places a 0 in locations (addresses) 1024 through 1034.
Line 10 sets up a loop from memory locations 1024 to 1034. Line 20 POKEs the value 0
into the location specified by I. The first time through the loop, I equals 1024. The
second time through the loop, I equals 1025 and so on. Line 30 increments the index
variable I by 1 each time it is encountered.
The previous machine-language example accomplishes the same task as the BASIC example. LDA # $ 0 0 loads a 0 into the accumulator. TAX transfers the contents of
the accumulator into the X-index register. The following machine-language instructions
form a loop:
START

STA $0400,X
INX
CPX # $ 0 B
BNESTART

Here's what happens within the loop. STA $0400,X stores a 0 in location $0400
(hex) the first time through the loop. Location $0400 is location 1024 decimal. INX
increments the X register by 1, each cycle through the loop. CPX # $ 0 B compares the
contents of the X register with the constant 11 ($0B). If the contents of the X register do
not equal 11, the program branches back to START STA $0400,X and the loop is
repeated.
The second time through the loop, 0 is stored in address $0401 (1025 decimal) and
the X register is incremented again. The program continues to branch until the contents
of the X register equal 11.
The effective address for the first cycle through the loop is $0400 which is 1024
decimal. For the second cycle through the loop the effective address is $0400 + 1, and
so on. Now you can see how the index registers modify the address within machinelanguage instruction.

THE STATUS REGISTER

The microprocessor's status register indicates the status of certain conditions within the
8502. The status register is controlled by seven programming states of the microprocessor, and indicates the conditions with flags. The status register is one byte, so each flag
is represented by a single bit. Bit 5 is not implemented.
Branching instructions check (4 of the 7 bits in) the status register to determine
whether a condition has occurred. The conditions for branching pertain to the value of
the bits in the status register. If a condition is true, meaning the FLAG bit corresponding
to one of the four conditions is high (equal to a 1), the computer branches. If the
condition you are testing is not true, the computer does not branch and the program
resumes with the instruction immediately following the branch.
Figure 5 - 2 shows the layout of the 8502 status register and lists the conditions
the status register flags.

MACHINE LANGUAGE O N THE COMMODORE 128

N ] V 1 ] B ] p 1 I 1 Z]C]

PROCESSOR STATUS REG "P"

^ CARRY
1 = TRUE
^ZERO
1 = RESULT ZERO
^IRODISABLE
1 = DISABLE
+ DECIMAL MODE
1 = TRUE
+ BRK COMMAND
- OVERFLOW

1 = TRUE

NEGATIVE

1 = NEG

Figure 5-2. 8502 Status Register

The Carry bit (0) is set if an addition operation carries a bit into the next position
to the left of the leftmost bit. The Carry bit is set by other conditions, of which this is
one. The SEC instruction sets the Carry bit. CLear the Carry bit with the CLC
instruction.
The Zero bit (1) is set if the result of an operation equals zero. The command BEQ
stands for Branch on result EQual to Zero. The command BNE stands for Branch on
Result Not Equal to zero. If the zero bit in the status register is set, the program
branches to the address relative to the current program counter value (for a BEQ
instruction). Otherwise, the BEQ command is skipped and the program resumes with the
instruction immediately following the BEQ statement.
The IRQ Disabled bit (2) is set if your program requests interrupts to be disabled with the SEI command (Set Interrupt Disable Status). The Disable Interrupt
Status bit is cleared with the CLI command (CLear Interrupt Disable bit) to permit
interrupts to occur. You will learn more about programming interrupts in the section
entitled TYPES OF INSTRUCTIONS and in the Raster Interrupt program explanation in
Chapter 8.
The microprocessor sets the Decimal Mode bit (3) if you instruct the microprocessor to SEt Decimal Mode with the SED instruction. CLear the Decimal Mode bit with
the CLD instruction, CLear Decimal Mode.
The BRK flag (bit 4) operates similar to the IRQ disable flag. If a BRK instruction
occurs, it is set to 1. Like an IRQ interrupt, the BRK causes the contents of the
program counter to be pushed onto the stack. The contents of the status register is
pushed on top of the stack and evaluated. If the BRK flag is set, the operating system
or your application program must evaluate whether or not a BRK or interrupt has
occurred.
If the BRK flag is cleared once the status register is pushed onto the stack, the
processor handles this as an interrupt and services it. Unlike an interrupt, the BRK flag
causes the address of the program counter plus two to be saved. The microprocessor
expects this to be the address of the next instruction to be executed. You may have to

131

132

COMMODORE 128

adjust this address since it may not be the actual address of the next instruction within
your program.
The Overflow flag (bit 6) is set by a signed operation overflowing into the sign
bit (bit 7) of the status register. You can clear the Overflow bit in the status register with
the CLV instruction (CLear Overflow flag). You can conditionally branch if the
Overflow bit is set with the BVS (Branch Overflow Set) instruction. Similarly, you can
conditionally branch if the overflow bit is clear with the BVC (Branch Overflow Clear)
instruction. The BIT instruction can be used to intentionally set the overflow flag.
The microprocessor sets the negative flag (bit 7) if the result of an arithmetic
operation is less than 0. You can conditionally branch if the result of an arithmetic
operation is negative, using the BMI instruction, (Branch on result Minus) or positive
using the BPL instruction, (Branch on Result Positive).
The status register indicates seven important conditions within the microprocessor
while your machine language program is executing. Your program can test for certain
conditions, and act upon the results. It gives you a way to conditionally control certain
machine level functions depending on the value of the status flags.

THE PROGRAM COUNTER

So far all of the registers within the 8502 are 8 bits, or one byte. The program counter
is twice as wide (16 bits) as the accumulator, X or Y registers or the status register. The
program counter is a 16-bit register because it holds the current address of the next
instruction to be executed. The addresses used in an 8502-based microprocessor are all 16
bits wide. They have to be in order to address all locations within each 64K RAM
bank.
The program counter holds the address of the next instruction to be executed. It
fetches the addresses of the instructions sequentially (usually) and places them on the
16-bit address bus. The processor obtains the data or instructions at the specified 16-bit
address from the data bus. Then they are decoded and executed.

THE STACK POINTER

Within the RAM of the Commodore 128 is a temporary work area called the stack. It
starts at location decimal 256 and ends at location 511 (hex $100 to $lFF). This area of
computer RAM is referred to as page 1. Paging is explained in the next section.
The stack is used for three purposes in your computer: temporary storage, control
of subroutines, and interrupts. The stack is a LIFO (Last In, First Out) structure which
means the last value placed on the stack is the first one taken off. When you place a
value on the stack, it is referred to as pushing. When you take a value off the stack, it is
considered pulling or popping.
Think of the structure as a stack of lunch trays in a cafeteria. The first tray used is
the one that is pulled off the top. The last one used is the one on the bottom, and it is
used only if all the others are pulled off before it.
The stack pointer is the address of the top stack value (plus 1). When a value
is pulled from the stack, the stack pointer then indicates the new address of the
next item on the stack. When a subroutine is called or an interrupt occurs, the

MACHINE LANGUAGE O N THE COMMODORE 128

address where the interrupt or subroutine occurs is pushed on top of the stack. Once
the interrupt or subroutine is serviced, the address where it occurred is popped off
the stack and the computer continues where it left off when the interrupt or subroutine
occurred.

I6-BIT ADDRESSING:
THE CONCEPT OF PAGING
The Commodore 128 contains 128K of Random Access Memory (RAM). This means
you have two banks of 65536 (64K) RAM memory locations (minus two for locations 0
and 1, which are always present in a RAM bank). Since the 8502 is an 8-bit microprocessor, it needs two 8-bit bytes to represent any number between 0 and 65535. One
eight-bit byte can only represent numbers between 0 and 255. Your computer needs a
way to represent numbers as large as 65535 in order to address all the memory
locations.
Here's how your computer represents the largest number in one 8-bit byte. The
computer stores it as a binary number. You usually represent it as a hexadecimal number
in your machine-language programs. Figure 5-3 shows the relationship between binary,
hexadecimal and decimal numbers.

BINARY

HEXADECIMAL

DECIMAL

1 eight-bit Byte = 1 1 1 1 1 1 1 1

$FF

255

Figure 5-3. Comparison of N u m b e r Systems

A byte contains eight binary digits (bits). Each bit can have a value of 0 or 1. The
largest number your computer can represent in eight binary digits is 1 1 1 1 1 1 1 1,
which equals 255 in decimal. This means all eight bits are set, or equal to 1. A
bit is considered off if it is equal to 0. In converting binary to decimal, all the binary
digits that are set are equal to 2 raised to the power of the bit position. The bit
positions are labeled 0 through 7 from right to left. Figure 5^4 provides a visual
representation of converting binary to decimal.

27

26

25

24

One binary byte

=
1
1
1
1
The byte in decimal = 128 + 64 4- 32 + 16 +
Figure 5-4. Binary/Decimal Conversion

23

22

21

1
8 +

1
4 +

1
2 +

1
1 = 255

133

134

COMMODORE 128

The top of each column represents the value of 2 raised to the power of the bit
position. Since each bit is turned on when you represent the largest number in one byte,
add all the values at the bottom of each to obtain the decimal equivalent. Figure 5-5
shows another example that converts the binary number 1 1 0 0 1 0 1 0 to decimal.

27

26

25

One binary byte

=
1
1
The byte in decimal = 128 + 64 +

24

23

0
0
1
0 4- 0 4- 8 +

22

21

0
0 +

1
2 +

0
0 = 202

Figure 5-5. Binary/Decimal Conversion

Remember, only add the values of two raised to the bit position if the bit is set.
If a bit is off, it equals zero.
Now that you can convert one byte from binary to decimal, you are probably
wondering what this has to do with 16-bit addressing. We mentioned before that the
program counterthe register responsible for storing the address of the next instruction
to be executedis 16 bits wide. This means it uses two bytes side-by-side to calculate
the address.
You just learned about the low byte, the lower half of the 16 bits used to represent
an address. The upper half of the 16-bit address is called the high byte. The high byte
calculates the upper half of the address the same way as the low byte, except the bit
position numbers are labeled from 8 on the right to 15 on the left. When you raise 2 to
the power of these bit positions, and add the resulting values to the low byte of the
address, you arrive at addresses that go up to 65535. This allows your computer
to represent any number between 0 and 65535, and address any memory location
within each 64K RAM bank. Figure 5 - 6 is an illustration of a 16-bit address in
decimal:

High Byte
One binary byte =
The byte in
decimal

215

214

213

212

211

210

29

28

=32768 + 16384+ 8192 + 4096 + 2048 + 1024 + 512 + 256 = 65280

Low Byte

27

26

25

24

23

22

21

One binary byte =

The byte in
decimal

= 128 + 64 + 32 + 16 + 8 + 4 + 2 +

Figure 5-6. Example of 16-Bit Address in Decimal

1 =

255-255
65535

MACHINE LANGUAGE O N THE COMMODORE 128

You can see that the highest number of the high byte of the 16-bit address is
65280. And you know that the highest number of the low byte of the 16-bit address
equals 255. Add the highest high-byte and the highest low-byte number (65280 + 255),
to arrive at 65535, the highest address within each of the two 64K RAM banks.
When the microprocessor calculates the address of the next instruction, it looks at
the high byte of the 16-bit program counter. Try to think of the high byte of the address
as just another 8-bit byte. If this was the case, the bit positions would be labeled from 0
on the right through 7 on the left, just like the low byte of the address. Therefore, the
largest number this 8-bit byte can represent again is 255 decimal.
The value in the high byte determines which 256-byte block is accessed. These
256-byte blocks are referred to as pages. The high byte determines the page boundary of
the address, so the high byte is calculated in increments of 256 bytes. The high byte of
the program counter determines which of the possible 256 pages is being addressed. If
you multiply the number of possible pages, 255 by 256 bytes, you realize the highest
page starts at location 65280, decimal, the same number as in the high byte in Figure
5-6. Location 65280 is the highest page boundary addressable.
What if you want to address a memory location that does not lie on a page
boundary? That's where the low byte of the 16-bit address comes in.
The high byte of the program counter represents the 256-byte page boundary.
All addresses between boundaries are represented by the low byte. For example, to
address location 65380 decimal represent the high byte as 255, since 255 times
256 equals 65280. You still have to move 100 addresses higher in memory to location
65380.
The low byte contains the value 100 decimal. The low byte value is added to the
high byte to find the actual, or effective address.
When you look at the memory map of your Commodore 128, you will see
references to the low byte and high byte pointers or vectors to certain machine-language
routines within the operating system or to important system memory locations, like the
start of BASIC.
You can find out the contents of these addresses and where the routines reside in
your Commodore 128's memory by using the PEEK command in BASIC, or the
Memory command in the Machine Language Monitor. To find the effective address
using BASIC, look in the memory map for the reference to a specific routine or system
function, sometimes called a vector. PEEK the high byte, the page number of the
routine. Multiply by 256 to find the page boundary. Then PEEK the low byte and add it
to the page boundary to arrive at the effective decimal address.
Keep in mind that all the address calculations are performed in binary. They are
explained in decimal so they're easier to understand. In your machine language programs, you will usually reference memory in hexadecimal notation, explained in the
next section.

135

136

COMMODORE 128

HEXADECIMAL NOTATION
Your 8502 microprocessor only understands the binary digits 0 and 1. Although machine
language usually requires hexadecimal notation and BASIC processes decimal numbers,
those numbers are translated and processed as binary numbers. Your computer uses
three different number systems, binary (base 2), hexadecimal (base 16) and decimal
(base 10). The machine-language monitor also uses the octal number base. A number
base is also referred to as a radix; therefore, the C128 uses four radices, but the
microprocessor only understands binary at machine level.
BASIC understands decimal numbers because they are easiest for people to use.
Although BASIC doesn't process as fast as machine language, the ease of use makes up
for the loss of speed.
Machine language uses hexadecimal notation because it is closer to the binary
number system and easier to translate than decimal. Hexadecimal representation is also
used usually by machine-level programmers because it is easier for people to think of a
group of eight binary digits (a whole byte) than it is to think of them as separate digits
by themselves. How do you find it easier to represent this value:
3A (hexadecimal), or as 00111010 (binary)?
Once values are translated from the higher level language into a form that the
microprocessor can understand (binary digits or bits), they are interpreted as electronic
switches by the internal circuitry. The switches determine if an electronic impulse will
be transmitted by the integrated circuit (I.C.) to perform a specific function, such as
addressing a memory location. If the bit equals 1, the switch is interpreted as on, which
sends a voltage level (approximately 3 to 5 volts) through the I.C. If the binary digit is
equal to 0, no voltage is transmitted. Though this is a simplified illustration, you get an
idea of how the microcomputer system can translate, process and perform the instructions you give to your computer. The hardware and software merge here, at machine
level.

UNDERSTANDING HEXADECIMAL
(HEX) N O T A T I O N
The key behind understanding hexadecimal (base 16) numbers is to forget about decimal
(base 10). Hexadecimal digits are labeled from 0 through 9 and continuing with A
through F, where F equals 15 in decimal. By convention, hexadecimal numbers are
written with a dollar sign preceding the value so that they can be distinguished from
decimal values. Figure 5 - 7 provides a table of the hexadecimal digits and their decimal
and binary equivalents:

MACHINE LANGUAGE O N THE COMMODORE 128

HEXADECIMAL

$0
$1
$2
$3
$4
$5
$6
$7
$8
$9
$A
$B
$C
$D
$E
$F

DECIMAL

0
1
2
3
4
5
6

7
8
9
10
11
12
13
14
15

BINARY

0000
0001
0010
0011
0100
0101
0110
0111
1000
1001
1010
1011
1100
1101
1110
1111

Figure 5-7. Hexadecimal/Decimal/Binary Conversion

Each hex digit represents four bits. The highest number you can represent with
four bits is 15 decimal. In machine language, you usually represent operands and
addresses as two or four hex digits. Since each hex digit of a four-digit hexadecimal
address takes up four bits, four of them represent 16 bits for addressing.
At first you'll find yourself converting decimal addresses and operands into
hexadecimal. Then you'll want to convert the other way. See the HEX$ and DEC
functions for quick and easy decimal to HEX conversions. In the machine language
monitor, use the ( + ) plus sign to represent decimal numbers. Use the conversions for
now, but eventually you should find yourself thinking hexadecimal notation instead of
always converting from decimal to hexadecimal.

ADDRESSING MODES IN
THE COMMODORE 128
Addressing is the process by which the microprocessor references memory. The 8502
microprocessor has many ways to address the internal locations in memory. The
different addressing modes require either one, two or three bytes of storage depending
on the instruction. Each instruction has a different version and op-code. For example,
LDA (LoaD the Accumulator) has eight versions, each with a different op-code to
specify the various addressing modes. See the 8502 Instruction and Addressing Table
section for the different versions of all the 8502 machine-language instructions.

137

138

COMMODORE 128

ACCUMULATOR ADDRESSING
Accumulator addressing implies that the specified operation code operates on the
accumulator. The operand field is omitted since the instruction can only perform the
operation on the accumulator. Accumulator instructions require only one byte of storage. Here are some examples of accumulator addressing instructions:

INSTRUCTION

HEX OPCODE

MEANING

ASL
LSR
ROR

$0A
$4A
$6A

Shift one bit left

Shift one bit right
Rotate one bit right

IMMEDIATE ADDRESSING
Immediate addressing specifies that the operand be a constant value rather than the
contents of a particular address. The operand is the data, not a pointer to the data. At
machine level, the microprocessor actually interprets an operand field constant
and an address in the operand field as two different op-codes, so the pound sign gives
the programmer a way to distinguish between the data and a pointer to the data.
Immediate addressing instructions require two bytes of storage. Here are some immediate addressing instruction examples:

INSTRUCTION

HEX OPCODE

MEANING

LDA #$0F

$A9

Load the accumulator with 15 ($0F)

CMP #$FF

$C9

Compare the accumulator with 255 ($FF)

SBC #$E0

$E9

Subtract 224 ($E0) from accumulator

ABSOLUTE ADDRESSING
Absolute addressing allows you to access any of the memory locations within either 64K
RAM bank. Absolute addressing requires three bytes of storage; the first byte for the
op-code, the second for the low byte of the address and the third for the high byte. Here
are some examples of absolute addressing instructions:

M A C H I N E L A N G U A G E O N T H E C O M M O D O R E 128

INSTRUCTION

HEX OPCODE

INC $4FFC

$EE

Increment the contents of address $4FFC by 1

LDX $200C

$AE

Load the X register with the contents of address

$200C

JSR $FFC3

$20

Jump to location $FFC3 and save the return address

MEANING

ZERO-PAGE ADDRESSING
Zero-page addressing requires two bytes of storage; the first byte is used for the opcode
and the second for the zero-page address. Since zero page ranges from addresses 0
through 255, the computer only needs the low byte to represent the actual address. The
high byte is assumed to be 0; therefore, it is not specified. When addressing a zero-page
location, you can still use absolute addressing; however, the execution time is not as fast
as zero-page addressing. Here are some examples:

INSTRUCTION

HEX OPCODE

MEANING

LDA $FF

$A5

Load the accumulator with the contents of zero-page

location $FF (255)

ORA $E4

$05

OR the accumulator with the contents of location

$E4

ROR $0F

$66

Rotate the contents of location $0F one bit to the

right

IMPLIED ADDRESSING
In implied addressing mode, no operand is specified because the op-code suggests the
action to be taken. Since no address or operand is specified, an implied instruction
requires only one byte for the op-code. Some examples are:

INSTRUCTION

HEX OPCODE

MEANING

DEX

$CA

Decrement the contents of the X register

INY

$C8

Increment the contents of the Y register

RTS

$60

Return from Subroutine

139

140

COMMODORE 128

RELATIVE ADDRESSING
Relative addressing is used exclusively with branch instructions. The branch instructions
(BEQ, BNE, BCC, etc.) allow you to alter the execution path depending on a particular
condition. Branch instructions are similar to IF . . . THEN statements in BASIC since
they both conditionally perform a specified set of instructions.
The operand in the branch instruction determines the destination of the conditional
branch. For example, the op-code BEQ stands for Branch on result EQual to zero. If the
zero flag in the status register is equal to 1 add the operand to the program counter and
continue execution at this new address. Figure 5 - 8 provides an example in symbolic
assembly language.

START

LDA #$01
STA TEMP
DEC TEMP
BEQ START
LDX #$01
STA COUNT
(A)

.01800 A9 01
.01802 85 FA
.01804 C6 FA
.01806 F0 FC
.01808 A2 01
.0180A 85 FB
(B)

LDA #$01
STA $FA
DEC $FA
BEQ $1804
LDX #$01
STA $FB
(C)

*NOTE: The machine language monitor does not provide for

symbolic addresses and labels like TEMP and START.

Figure 5-8. Relative Addressing

Figure 5 - 8 lists the (A) code on the left as it appears in symbolic assembly
language. The code (B) in the middle is the actual machine-level machine code
as it appears in the machine language monitor. The (C) code to the right is the symbolic
machine language as it appears in the monitor as executable code.
In this program segment, the first instruction LoaDs the Accumulator with 1.
STA is the op-code for STore the contents of the Accumulator in the variable
TEMP. The third instruction, DEC, decrements the contents of the variable TEMP. In
the third instruction, START is a label which marks the beginning of the conditional
loop. The branch instruction (BEQ) checks to see if the value stored in TEMP equals
0 as a result of the DECrement instruction. The instruction marks the end of the
loop.
The first time through this loop, the result in TEMP equals 0 so program control
branches back to the instruction specified by the label START.
The second time through the loop, TEMP is less than zero; therefore, the zero
flag in the status register is cleared, the program does not branch to START and
continues with the statement directly following the branch instruction (LDX #$01).

MACHINE LANGUAGE O N THE COMMODORE 128

Because of the way this program segment is written, a branch can occur only once, the
first time through the loop.
Under relative addressing, the first byte of the instruction is the op-code and the
second is the operand, representing an offset of a number of memory locations. The
location to branch back to is not interpreted as an absolute address but an offset relative to
the location of the branch instruction in memory.
The offset ranges from - 1 2 8 through 127. If the condition of the branch is met,
the offset is added to the program counter and the program branches to the address in
memory.
In the example in Figure 5 - 8 , notice that the operand in the branch instruction is
only one instruction past the label START. The operand START is interpreted by the
computer as an offset of three bytes backward in memory since the DEC instruction use
2 bytes and the BEQ op-code uses one byte. The 8502 can only branch forward 127
bytes and branch backward by 128 bytes.
If you enter the machine-language monitor and disassemble the machine-language
code, you'll see how the computer represents a branch instruction operand as in part (B)
of Figure 5-8. The symbolic code in part (C) operand field represents the operands as
absolute addresses but the assembled hexadecimal code to the left in part (B) of the op
code stores the operand using one byte, a number plus or minus the address of the
branch instruction. The largest number for a forward branch is $7F. A backward branch
is represented by hex numbers greater than $80. When you are within the machinelanguage monitor, subtract the operand offset from 255 ($FF) to find the actual value of
the negative offset. In this case $FF minus 3 equals $FC, which is the operand in the
branch instruction in part (B) of Figure 5-8.
Here are some examples of relative addressing branch instructions:

INSTRUCTION

HEX OP-CODE

MEANING

BEQ

$F0

Branch on result Equal to 0

BNE

$D0

Branch on result Not Equal to 0

BCC

$90

Branch on Carry Clear

INDEXED ADDRESSING MODES

The Commodore 128 has two special-purpose registers: the X and Y index registers.
In indexing addressing modes, index registers modify an address by adding their
contents to a base address to arrive at the actual or effective address. For example,
here's a program segment that illustrates the importance of address modification, using
the X and Y index registers:

141

142

C O M M O D O R E 128

LDA
LDX
LOOP STA
INX
BNE

#$0F
#$00
$2000,X
LOOP

The first instruction in this program loads the accumulator with $0F(15 decimal).
The second instruction loads the X register with 0. The third instruction stores the
contents of the accumulator into the address $2000 added to the contents of the X index
register. The first time the loop cycles, $0F is stored in address $2000 ($2000 4- 0 =
$2000). The next instruction (lNX) increments the contents of the X register. The last
instruction in the loop branches to the statement specified by the label LOOP, which is
the STA $2000, X instruction. The second time through the loop, $0F is stored in
location $2001 ($2000 + 1). The third cycle ofthe loop stores $0F in location $2002, etc.
The loop continues to cycle and stores $0F in consecutive locations until the X
register equals 0. In other words, the loop circulates 256 times until the X register
equals 0, since 255 plus 1 is represented as 0. This is because the extra bit is carried
over to the ninth bit position, which doesn't exist in an eight-bit number, so the register
is reset to zero. This is similar to when your car odometer is set at 99,999 miles. When
you travel another mile the dial resets to 00,000.
This example shows just one way to modify addresses with the index registers.
The Commodore 128 has four indexed addressing modes: (1) indexed absolute addressing (illustrated in the example just shown), (2) indexed zero-page addressing, (3)
indexed indirect addressing, and (4) indirect indexed addressing.

INDEXED ZERO-PAGE ADDRESSING

This type of addressing is similar to zero-page addressing except that the index registers
(X or Y) are used to modify addresses within page zero ($00 to $FF) of memory. Since
zero-page addressing requires no high byte to represent the page number, this type of
instruction requires only two bytes of memory. The effective (actual) address is calculated by adding the contents of the index register to the low byte of the address in the
program counter. This addressing mode is faster and more efficient than using indexed
absolute addressing in zero page.
Here are some examples of indexed zero-page addressing instructions:

INSTRUCTION

HEX OP-CODE

MEANING

INC operand, X

$F6

Increment the contents of memory by 1.

The base address (the operand) is added to the
contents of the index register (X)).

CMP operand,X

$D5

Compare the contents of the accumulator with

memory. The memory base address (the operand) is added to the contents of the index register
(X)).

MACHINE LANGUAGE O N THE COMMODORE 128

INDEXED ABSOLUTE ADDRESSING

Indexed absolute addressing allows you to access and modify any of the memory
locations in each of the two 64K banks. The effective address is calculated by adding
the contents of the index register (X or Y) to the high and low byte base address
determined by the operand. Since absolute addressing can access any of the available
memory locations, high and low bytes are required to form the 16-bit address. Therefore, this type of addressing requires three bytes.
Here are some examples of indexed absolute addressing instructions:

INSTRUCTION

HEX OP-CODE

MEANING

AND operand,Y

$39

Perform the logical AND operation on the

accumulator and the contents of memory base
address plus the contents of the register (Y).

ASL operand,X

$lE

Shift the contents of the memory (the memory

is the base address (the operand) added to the
contents of the index register (X)) one bit to the
left.

THE INDIRECT ADDRESSING CONCEPT

So far you've learned that the computer calculates the effective address as the
base address (in the program counter) plus the offset from the contents of the index
registers if indexed addressing is used. Indirect addressing calculates the effective
address differently.
Think of indirect addressing as the address of an address. Here's an illustration
using absolute indirect addressing:
JMP ($0326)
The above JuMP instruction is an example of absolute indirect addressing. This
type of instruction requires three bytes: one for the op-code, one for the low byte and
one byte for the high byte of the 16-bit address. The parentheses indicate that indirect
addressing is used. The second and third bytes of the JMP instruction specify the low and
high byte of the address. The address in the operand field is only the low byte of the effective
address. The contents of the byte immediately following the address specified in the JMP
instruction is automatically placed into the program counter as the high byte of the effective
address. In this example, the contents of location $0326 and $0327 represent the address of
the actual instructions to be executed. For example, location $0326, the low byte of
the effective address, contains the value $65 and location $0327, the high byte of the
effective address, contains the value $F2. The high- and low-byte values are placed in

143

144

COMMODORE 128

the program counter as the address $F265, the actual address of the next instruction
the computer executes then is $F265.
lf the parentheses were not present, the assembler interprets the instruction
as an absolute addressing instruction. The computer would understand the low
byte to be $26 and the high byte to be $03 and would JuMP to the instruction
located at $0326 instead of the intended address of $F265. Since this is not the
case, the high byte is automatically presumed to be the low byte address plus 1
(the contents of $0327).
The last two addressing modes, indirect indexed and indexed indirect, use the
same principle as absolute indirect addressing. Here's an explanation of each.

INDEXED INDIRECT ADDRESSING

Indexed indirect addressing is similar to absolute indirect, although it uses index
registers to modify an address. This type of addressing, sometimes called indirect X
addressing, requires two bytes of storage: the first byte is for the op-code and the second
is for the operand which is used in the effective address calculation. The address
specified in the second byte is added to the contents of the X register and the carry, if
any, is ignored. The results point to an address in page zero in which its contents
contain the low byte of the effective address. The zero page address plus 1 indicates the
high byte of the effective address. Both locations in which the low and high bytes of the
effective address are contained must be located in page zero, locations $00 through $FF.
Here's an example:
LDX # $ 0 4
LDA # $ 0 0
STA ($DF,X)
The first line loads the X register with $04. Next, the accumulator is loaded with
0. The third instruction stores zero in the effective address. Calculate the effective
address by taking the base address $DF (not the contents of it) and add the contents of
the X register ($04) to it, which equals $E3. The contents of location $E3 is the low
byte of the effective address and the contents of $E4 is the high byte of the effective
address. For example, the contents of address $E3 contain $56 and the contents of
address $E4 contain $F3. Since the contents of $E3 is the low byte and the contents of
$E4 is the high byte, the effective address is $F356. Indexed indirect addressing is
referred to as pre-indexing because the indexing occurs before the effective address is
actually obtained. Indirect X addressing is useful in addressing a series of pointers such
as the zero-page memory of the Commodore 128.

INDIRECT INDEXED ADDRESSING

This mode, also called indirect Y addressing, is post-indexed, which means the adding
of the index itself obtains the effective address. This mode operates on the principle of a
base address and a displacement. Here's how it works.
The first of two bytes is the op-code, the second is the operand, a pointer to a

MACHINE LANGUAGE O N THE COMMODORE 128

zero-page memory address. The contents of the pointer and the contents of the Y
register are added to arrive at the low byte of the effective address. The contents of the
pointer act as the base address and the contents of the Y register act as the displacement.
The carry, if any, is added to the memory location directly following the low-byte
address which becomes the high byte of the effective address. This is true indexing,
designed specifically for manipulating tables of data. In order to access different table
values, just change the contents of the Y register since the base address is already
established. Here's an example:
LDY # $ 0 8
LDA # $ 0 0
STA ($EA),Y
The first instruction loads the Y register with $08. The second instruction loads
the accumulator with 0. The third instruction stores the contents of the accumulator in
the effective address.
To find the effective address, add the contents of the zero page memory location
(base address) specified in the instruction to the contents of the Y register (displacement). In this example, the contents of the address $EA equals $F0. Add $F0 to the
contents of the Y register ($08) to arrive at $F8, the low byte of the effective address of
the next instruction. The high byte of the effective address is obtained by adding the
carry (none in this case) to the zero-page memory location immediately following the
low-byte address. For example, location $F9 contains the value $3F. Since the low byte
is $F8 and the high byte equals $3F, the effective address is $3FF8.
Notice the difference between indirect indexed and indexed indirect addressing
modes as they can be confusing. Remember, the most important difference between the
two addressing modes is the way the effective address is calculated. Indexed indirect is
X indexing, which is indexed prior to the arrival of the effective address. Indirect
indexed is post-indexed with the Y register.
You havejust covered all the addressing modes in the Commodore 128. Each calls
for different circumstances and you should use the correct mode whenever circumstances dictate it to obtain optimal performance from the microprocessor. For example,
use indexed zero-page addressing when you are manipulating zero-page locations instead of using indexed absolute.

TYPES OF INSTRUCTIONS
This section explains all the types of machine-language instructions available in the
Commodore 128. They are first covered by type of instruction, such as REGISTER TO
MEMORY and COMPARE instructions; then they are listed alphabetically by op-code
mnemonic with all the different addressing options. This section provides important
information on programming in machine language on the Commodore 128 (or any
6502-based microcomputer).

145

146

COMMODORE 128

Use this information as a reference for background on each instruction. Figure 5 - 9

provides an alphabetized list of the 8502 microprocessor op-code mnemonics. For
detailed, quick-reference information, see the following section for an alphabetic list of
instructions, their hexadecimal op-codes, the different versions of the instructions for
each addressing mode and the way they affect the flags in the status register.

8502 MICROPROCESSOR INSTRUCTION S E T ALPHABETIC SEQUENCE

ADC
AND
ASL

Add Memory to Accumulator with Carry

"AND" Memory with Accumulator
Shift Left One Bit (Memory or Accumulator)

BCC
BCS
BEQ
BIT
BMI
BNE
BPL
BRK
BVC
BVS

Branch on Carry Clear

Branch on Carry Set
Branch on Result Zero
Test Bits in Memory with Accumulator
Branch on Result Minus
Branch on Result not Zero
Branch on Result Plus
Force Break
Branch on Overflow Clear
Branch on Overflow Set

CLC
CLD
CLI
CLV
CMP
CPX
CPY

Clear Carry Flag

Clear Decimal Mode
Clear Interrupt Disable Bit
Clear Overflow Flag
Compare Memory and Accumulator
Compare Memory and Index X
Compare Memory and Index Y

DEC
DEX
DEY

Decrement Memory by One

Decrement Index X by One
Decrement Index Y by One

EOR

"Exclusive-Or" Memory with Accumulator

INC
INX
INY

Increment Memory by One

Increment Index X by One
Increment Index Y by One

JMP
JSR

Jump to New Location

Jump to New Location Saving Return Address

LDA
LDX
LDY
LSR

Load Accumulator with Memory

Load Index X with Memory
Load Index Y with Memory
Shift Right One Bit (Memory or Accumulator)

NOP

No Operation

MACHINE LANGUAGE O N THE COMMODORE 128

8502 MICROPROCESSOR INSTRUCTION S E T ALPHABETIC SEQUENCE (cont'd)

ORA

"OR" Memory with Accumulator

PHA
PHP
PLA
PLP

Push Accumulator on Stack

Push Processor Status on Stack
Pull Accumulator from Stack
Pull Processor Status from Stack

ROL
ROR
RTI
RTS

Rotate One Bit Left (Memory or Accumulator)

Rotate One Bit Right (Memory or Accumulator)
Return from Interrupt
Return from Subroutine

SBC
SEC
SED
SEI
STA
STX
STY

Subtract Memory from Accumulator with Borrow

Set Carry Flag
Set Decimal Mode
Set Interrupt Disable Status
Store Accumulator in Memory
Store Index X in Memory
Store Index Y in Memory

TAX
TAY
TSX
TXA
TXS
TYA

Transfer
Transfer
Transfer
Transfer
Transfer
Transfer

Accumulator to Index X
Accumulator to Index Y
Stack Pointer to Index X
Index X to Accumulator
Index X to Stack Pointer
Index Y to Accumulator

Figure 5-9. 8502 Op-Code Mnemonics

REGISTER TO MEMORY
INSTRUCTIONS
The REGISTER TO MEMORY instructions are:
LDA
LDX
LDY

STA
STX
STY

The register to memory instructions either place a value into the accumulator, X
register or Y register from memory, or store a value from a register (A, X, or Y) into a
memory address.

LOADING THE ACCUMULATOR

The first and most common instruction is LDA, LoaD the Accumulator. This places a value
into the accumulator, the most powerful and active register in the microprocessor. The
value is derived from the contents of a memory location or a constant. Here's an example:

147

148

COMMODORE 128

LDA $2000
This instruction loads the contents of the memory location $2000 (8192 decimal)
into the accumulator. The value in the memory location $2000 remains the same. The
value also remains in the accumulator until another value is placed there or another
operation acts upon it.
The previous example is just one of the addressing modes for loading the accumulator. Another form the LDA instruction can take is to load a constant. To load a
constant into the accumulator, you must precede the dollar sign ($) with a pound sign
( # ) . For readability, it's a good idea to place at least one space between the op-code and
the operand but it is not necessary. Here's an example of loading a constant into the
accumulator:
LDA # $ 0 A
This loads the constant $0A (10 decimal) into the accumulator. Remember,
precede a constant with a pound sign, or else the assembler interprets the instruction as
the contents of a memory address.
The LDX and LDY instructions work the same way as the LDA instruction.
Again, you can load a constant or the contents of a memory address into the X and Y
registers. Examples:
LDX # $ 0 A
LDX $2000
LDX # $ F B

STORE: THE OPPOSITE OF LOAD

You know how to place a value into a register, but how do you do the opposite? The
STORE instruction performs the opposite of a load. It places a value from the A
(accumulator), X, or Y registers into a specified memory address. As you learned in the
addressing section, the load, store and most other machine-language instructions have
several versions, depending on the type of addressing used. Here's an example:
STA $FC3E
This stores the contents of the accumulator into memory location $FC3E. The
contents of the accumulator remain the same until another instruction modifies it. The
STX and STY instructions work the same way; they store the contents of the register
into a specified memory address. There is no immediate version or pound sign version
of the store command.

COUNTER INSTRUCTIONS
The COUNTER instructions are
INC
INX
INY

DEC
DEX
DEY

Counter instructions can be used to keep track of or count the number of times an
event occurs. These instructions are used for mathematical manipulations or indexing a

MACHINE LANGUAGE O N THE COMMODORE 128

series of addresses. The counter instruction, INC, increments the contents of a memory
address by a value of 1 each time it is encountered. These instructions are used primarily
within a program loop and in conjunction with a branch instruction. Here's an example
of a loop and how INC keeps track of a number of occurrences of an event:

START

LDX # $ 0 0
TXA
STA $2000,X
INX
BNE START

The first instruction loads a 0 into the X register. The second instruction transfers
the contents of the X register into the accumulator (without erasing the X register).
Instruction three stores the contents of the accumulator (0) into location $2000 the first
time through the loop. The fourth instruction increments the contents of the X register.
The last instruction branches to the instruction specified by the label START, until the
value of the X register equals 0.
This program segment stores 0's in an entire page (256 locations) starting at $2000
and ending at $20FF. When the contents of the X register equals 255 and it is
incremented again, it is reset to 0, since it can only hold an eight-bit number. When this
occurs, the branch is skipped and the program continues with the instruction directly
following the branch instruction.
The INY instruction operates in the same way as INX, since it also only uses
implied addressing. The INC instruction, on the other hand, uses several different
addressing modes including absolute, which uses 16-bit addresses. With the INC
instruction, you can count past the capacity of an 8-bit number, though you must
separate the counter into a high byte and a low byte. For example, the low byte counts
the increments of less than a page and the high byte keeps track of the number of pages.
When low-byte counter is at 255 and is incremented, it is set back to 0. When this
occurs, increment the high-byte counter. To count up to 260 (decimal), the highbyte value equals 1 and the low byte equals 4. Here's an equation to illustrate the point:
(1 * 256) 4- 4 = 260
Here's the machine-language code that does this:

LOOP

LOOP 2

LDA # $ 0 0
STA HIGH
STA LOW
INC LOW
BNE LOOP
INC HIGH
INC LOW
LDA LOW
CMP # $ 0 4
BNE LOOP2

The DECrement instructions operate the same way as the increment instructions.
They are the negative number counterparts of the increment counters.

149

150

COMMODORE 128

COMPARE INSTRUCTIONS
The Commodore 128 has three compare instructions that check the contents of a register
with the contents of memory. A compare operation can be used to determine which
instructions to execute as a result of a conditioned value. The compare instructions are:
CMP
CPX
CPY
The CMP instruction compares the contents of the accumulator with the contents
of the specified address in the instruction. Compare instructions essentially subtract
memory from a register value but change neitherthey just set status flags. CPX
compares the contents of the X register with the specified address. CPY compares the
contents of the Y register with the specified memory location.
All three instructions have versions that will operate in immediate, zero-page and
absolute addressing modes. This means you can compare the contents of a register
(A,X, or Y) with the contents o f a zero-page location, any other address above zero page,
or against a constant. Here's an example:

ONE

LDX
LDA
STA
INX
CPX
BNE

#$00
#$00
$DF,X
#$0A
ONE

The preceding program segment stores 0's in 10 consecutive memory addresses

starting at $DF. The first instruction loads the X register with 0, the second loads 0 into
the accumulator. The third instruction stores 0 in location $DF plus the contents of the X
register. The fourth instruction increments the X register. The fifth instruction compares
the contents of the X index register with the constant $0A (10 decimal). If the contents
of the X register does not equal $0A, the program segment branches back to the store
instruction specified by the label ONE. After the loop cycles ten times, the X register
and the constant $0A are equal. Therefore the processor does not take the branch
and the program continues with the instruction immediately following BNE.
You can compare the value of a register with the contents of an absolute memory
address. Here's the same example as above using the contents of a memory address
instead of a constant:

ONE

LDA
STA
LDX
LDA
STA
INX
CPX
BNE

#$0A
$FB
#$00
#$00
$DF,X
$FB
ONE

MACHINE LANGUAGE O N THE COMMODORE 128

Remember, if you want to compare numbers larger than eight bits can represent
(greater than 255 decimal), you must separate the number into a low byte and a
high byte.
The BIT instruction can also be used for comparisons. See the logical instructions
next.

ARITHMETIC A N D
LOGICAL INSTRUCTIONS
The accumulator is responsible for all mathematical and logical operations performed in
your computer. The mathematical and logical instructions available in machine language are:
ADC
AND
BIT

EOR
ORA
SBC

Here's what each instruction means:

ADCAdd the contents of the specified memory address to the contents of the
accumulator with a carry. It is considered a good programming practice to clear
the carry bit with the CLC instruction before performing any addition. This avoids
adding the carry into the result.
ANDPerform the logical AND operation with the contents of the accumulator and the
contents of the specified memory address.
BITCompare the bits in the specified memory address with those in the accumulator. Bits 6 and 7 are transferred to the status register flags. Bit 7 is transferred to the negative status flag bit and bit 6 is sent to the overflow status flag bit.
EORPerform the exclusive OR operation with the contents of the specified memory
address and the contents of the accumulator.
ORAPerform the logical OR operation with the contents of the specified memory
address and the contents of the accumulator.
SBCSubtract the contents of the specified memory address from the contents of the
accumulator with a borrow. (It is a good practice to set the carry flag before
performing subtraction. This avoids subtracting the borrowed bit from the result.)

ARITHMETIC INSTRUCTIONS
(ADC, SBC)
The addition and subtraction instructions are easy to understand. Here's an example:
CLC
LDA
STA
ADC
SEC
SBC
ADC
STA

#$0A
$FB
#$04
#$06
$FB
$FD

151

152

COMMODORE 128

This program segment essentially performs the following mathematical operation:

(10 + 4 ) - 6 + 10= 18.
The first instruction clears the carry bit. The second instruction loads the accumulator with $0A (10 decimal). The third instruction stores the value in address $FB for
later use. The fourth instruction adds the constant $04 to the value already in the
accumulator. The SBC instruction subtracts the constant $06 from the contents of the
accumulator. The next instruction, ADC $FB, adds the contents of memory location
$FB to the contents of the accumulator. The resulting value (18($12)) of all the
mathematical operations is stored in address $FD.

LOGICAL INSTRUCTIONS
(AND, EOR, A N D ORA)
These instructions operate on the contents of a memory address and a register. The AND
operation is a binary (Boolean) algebra operation having two operands that can result in
one of two values, 0 or 1. The only way an AND operation can result in a 1 is if both
the operands equal 1; otherwise the result is 0. For example, the two operands are the
contents of a specified memory address and the contents of the accumulator. Here's an
illustration of this concept:
Memory address - 10001010
Accumulator
= 11110010
Result of AND

= 10000010

As noted, the result of an AND operation is (true) 1, only if the two operands are
equal to 1; otherwise the result is 0. Notice bit 7 (high-order bit) equals 1 because both
bit 7's in the operands are 1. The only other resulting bit equal to 1 is bit 1, since both bit
l ' s are equal to 1. The rest of the bits are equal to zero since no other bit positions in
both operands are equal to 1. A 1 and a 0 equals 0, as does a 0 and a 0.
The Boolean OR works differently. The general rule is:
If one of the operands equals 1, the resulting Boolean value equals 1.
For example, the two operands are the contents of a specified memory address and
the contents of the accumulator. Each individual bit can be treated as an operand. Here's
an illustration.
Contents of Memory Address = 10101001
Contents of Accumulator
= 10000011
Result of the OR operation

= 10101011

For all the bit positions that equal one in either operand, the resulting value of that
bit position equals 1. The result is 1 if either operand or both operands are equal to 1.
The exclusive OR works similarly to the OR operation, except if both operands
equal 1, the result is zero. This suggests the following general rule:

MACHINE LANGUAGE O N THE COMMODORE 128

If either of the operands equals 1, the resulting Boolean value is 1, except if both
operands are 1, then the result equals 0.
Here's an example using this rule:
Contents of Memory Address = 10101001
Contents of Accumulator
= 10000011
Result of the exclusive OR

= 00101010

In this example, the operands are the same as in the previous OR example. Notice
bits 0 and 7 are now equal to 0 since both operands are equal to 1. All other bit values
remain the same.

BIT
The BIT instruction performs a logical AND operation on the contents of the specified
memory address and the contents of the accumulator, but the resulting value is not
stored in the accumulator. Instead, the zero flag in the status register is set by the result
of the operation. The BIT instruction compares the contents of the accumulator and the
contents of the memory address, bit-for-bit. If the result of the operation of the
accumulator being ANDed by a memory location is 0, then the zero flag (in the status
register) is set to a 1. Otherwise the zero flag is 0.
Your machine language program can then act conditionally depending on the
result of the zero flag in the status register. In addition, bits 7 and 6 from the specified
memory address are moved into the negative-flag and overflow-flag bit positions in the
status register, respectively. These flags can also be used to perform conditional
instructions depending on the value of the flag. For example, the BIT instruction
performs the following:
7
NV
Contents of Memory Address = 10101001
Contents of Accumulator
= 11001101
Result of BIT instruction
(Not stored in accumulator)

10001001

1 0

0
BDIZC
0

Status Register

Since the resulting bit pattern is not 0, the zero flag in the status register is 0.
In addition, bits 7 and 6 are placed in the bit positions of the negative and overflow
flags, respectively, in the status register. Notice the result of the BIT instruction's AND
operation is not stored in the accumulator. The original contents of the accumulator
remain intact. See the following example of 2-bit pattern operands that result in 0 when
ANDed:

153

154

COMMODORE 128

7
NV
Contents of Memory Address = 01111010
Contents of Accumulator
- 10000100
Result of BIT instruction

00001000

0 1

0
BDIZC
1

Status Register

This time the bit patterns result in 0. Therefore, the zero flag in the status register
is set to 1. Bits 7 and 6 are also placed into their respective negative and overflow status
register bit positions from their positions in the memory location.
Now you know how each of the arithmetic and logical instructions operate. The
next section discusses branching instructions. Branching instructions are designed so
you can conditionally execute a certain set of instructions, depending on the result of a
condition. Many times the conditions are contingent on the results of an arithmetic or
logical operation, which affects the flags in the status register. The branching instructions then act according to the flags in the status register.

BRANCHING INSTRUCTIONS
The 8502 microprocessor has many conditional branching instructions. By definition, a
branch temporarily redirects the otherwise sequential execution of program instructions.
It transfers control to a location of a machine-language instruction other than the one
immediately following the branch instruction in memory.
The conditional branch instructions cause the microprocessor to examine a particular flag in the status register. The processor, depending on the value of the tested flag,
either takes the branch and transfers control of the program to another location or skips
the branch and resumes with the instruction immediately following the branch.
Think of a conditional branch as a test. For example, if the condition passes the
test, the program branches or shifts control to an instruction that is not the next
sequential instruction in the computer's memory. If it fails the test, the branch is skipped
and program control resumes with the instruction immediately following the branch
instruction in memory. Remember that program control can also be shifted to an
instruction that is out of sequential order if it fails a test. This means you can transfer
control of the execution of your program depending on the conditions you create. You
may set a condition that branches if the value of a certain flag (operand) is zero.
In another instance, you may set a condition to branch if a specific flag is set
to 1.
The conditional branch instructions available in the 8502 microprocessor are:
BCC
BCS
BEQ
BMI

BNE
BPL
BVC
BVS

Here's what the conditional branch instructions mean. The phrases in parentheses
are the literal translations of the op-code mnemonics. The remainder explains the
meaning behind the op-codes.

MACHINE LANGUAGE O N THE COMMODORE 128

BCC(Branch on Carry Clear) Branch if the Carry flag in the status register equals 0.
BCS(Branch on Carry Set) Branch if the Carry flag in the status register equals 1.
BEQ(Branch on result EQual zero) Branch if the zero flag in the status register equals 1.
BMI(Branch on result Minus) Branch if the negative flag in the status register equals 1.
BNE(Branch on result Not Equal to zero) Branch if the zero flag in the status register
equals 0.
BPL(Branch on result PLus) Branch if the negative flag in the status register equals 0.
BVC(Branch on oVerflow Clear) Branch if the overflow flag in the status register
equals 0.
BVS(Branch on oVerflow Set) Branch if the overflow flag in the status register
equals 1.
As you can see, all branching instructions depend on the value of a flag in the
status register.
Here are some branching examples.
READY.
MONITOR
PC SR AC XR YR SP
; FB000 00 00 00 00 F8

.
.
.
.
.

01828 E6 FA
0182A A5 FA
0182C D0 02
0182E E6 FB
01830 C8

INC
LDA
BNE
INC
INY

$FA
$FA
$1830
$FB

This program segment keeps track of the low and high pointers in $FA and $FB
respectively. The first instruction (INC $FA) increments the low byte address pointer.
Next, the contents of $FA is loaded into the accumulator. The branch instruction (BNE
$1830) evaluates the value of the accumulator. If the value is not equal to zero, the
branch is taken to the instruction located at address $1830 (INY). In this case the high
byte pointer is not yet ready to be incremented, so the INC $FB instruction is skipped. If
the value in the accumulator is equal to zero, the branch is skipped and the high byte
address pointer is incremented.
This is an example of the BPL (Branch on Result Plus) instruction.
READY.
MONITOR
PC SR AC XR YR SP
; FB000 00 00 00 00 F8
.
.
.
.

01858
0185B
0185E
01860

8E
2C
10
8D

00 D6 STX $D600
00 D6 BIT $D600
FB
BPL $185B
01 D6 STA $D601

This example is a routine that checks the update ready status bit for the 8563
address register, and ensures that data is valid before writing a value to an 8563 register.
The first instruction stores the contents of the X register, which was previously loaded

155

156

COMMODORE 128

with an 8563 register number, into the 8563 address register. The BIT instruction places
bit 7 of location $D600 into the negative flag in the 8502 status register. The BPL
instruction branches to the BIT instruction in location $185B as long as the value of the
negative flag is equal to 0. To the 8563 chip, this means the data is not yet valid and
cannot be written to or read from until bit 7 is set. This loop continues until the value of
bit 7 is 1, then it is transferred to the negative flag. The result now becomes negative
so the branch is skipped and control is passed to the next instruction in memory, which
stores the data into the 8563 data register. Refer to Chapter 10, Writing to an 8563
Register for an expanded version of this program.

REGISTER TRANSFER INSTRUCTIONS

Register transfer instructions move a value from one register (A, X, or Y) to another.
This instruction is useful since it only requires one byte of memory and saves the
programmer the trouble of loading the value from one register and storing it in another.
The 8502 microprocessor has the following six register transfer instructions:
TAXTransfer contents of accumulator to X index register
TAYTransfer contents of accumulator to Y index register
TSXTransfer the contents of the stack pointer to X index register
TXATransfer the contents of X index register to the accumulator
TYATransfer the contents of the Y index register to the accumulator
TXSTransfer the contents of the X register to the stack pointer
The TXS and TSX instructions transfer values from the X index register to the
stack pointer and vice versa. This is useful if you need to take a value off the stack
temporarily, in a mathematical operation (for example, to operate on it and then replace
it on the stack). Another use is to take a value off the stack, place it in the X register for
temporary storage, add a new value on the stack, and then place the old value back on
top. This could be the case when you need to sort values in ascending order.

SHIFT A N D ROTATE INSTRUCTIONS

The shift and rotate instructions manipulate the bits of the accumulator or memory.
Following are the shift and rotate instructions used by the 8502 family of microprocessors:
ASLShift the whole byte one bit to the left
LSRShift the whole byte one bit to the right
ROLRotate the whole byte one bit to the left
RORRotate the whole byte one bit to the right

SHIFT INSTRUCTIONS
The shift instructions are useful when evaluating the value of a single bit at a time in a
series of bits that control your program. For example, a joystick read routine is an
example that calls for the shift instruction. Locations $DC00 and $DC01 control the
joystick direction (bits 0-3), and the joystick fire button (bit 4). One way to evaluate
these values is to shift them to the right. This causes the value to be passed to the carry

MACHINE LANGUAGE O N THE COMMODORE 128

flag. If the carry flag is enabled (1), then the joystick is being pushed in the direction
corresponding to that bit. Here is a joystick read routine that uses the LSR instruction to
evaluate the direction of the joystick:
READY.
MONITOR
PC SR AC XR YR SP
; FB000 00 00 00 00 F8

01800
01803
01805
01807
01808
0180A
0180B
0180C
0180E
0180F
01810
01812
01813
01814
01816
01817
01818
0181A
0181C

AD
A0
A2
4A
B0
88
4A
B0
C8
4A
B0
CA
4A
B0
E8
4A
86
84
60

00 DC LDA $DC00
LDY #$00
00
LDX #$00
00
LSR
01
BCS $180B
DEY
LSR
01
BCS $180F
INY
LSR
01
BCS $1813
DEX
LSR
BCS $1817
01
INX
LSR
STX $FA
FA
STY $FB
FB
RTS

ROTATE INSTRUCTIONS
The rotate instructions operate a little differently. Instead of the shifted bit falling into
the carry flag, the bit "falling off the edge" is placed in the carry bit, then the carry bit
is placed at the opposite end of the byte. For example, if the ROR (rotate right)
instruction is specified, each bit is moved one position to the right. Now bit 7 is placed in
the carry bit and the carry bit is rotated around to the left and placed in the bit 7 bit
position. The ROL instruction operates in the same manner, except the rotation is
leftward rather than to the right. See Figure 5-10 to visualize the rotation concept of the
ROR (rotate right) instruction:

Bit Position

Figure 5-10. Concept of ROR (Rotate Right) Instruction

157

158

COMMODORE 128

SET A N D CLEAR INSTRUCTIONS

The set and clear instructions are designed to manipulate the bits (flags) within the status
register and control certain conditions within the microprocessor. These are the set and
clear instructions available in 8502 machine language:
SEC
SED
SEI

Set the Carry Flag

Set Decimal Mode
Set the Interrupt Disable Bit

CLC
CLD
CLI
CLV

Clear
Clear
Clear
Clear

the Carry Flag

Decimal Mode
the Interrupt Disable Bit
the Overflow Flag

Each of these instructions applies to a flag in the status register that controls a
particular microprocessor condition. Notice that each clear instruction has a counterpart
which sets the condition, except for CLV (Clear Overflow Flag). The overflow flag can
be set by the BIT instruction or from the result of a signed mathematical operation
overflowing into the sign bit.
Figure 5-11 shows the 8502 status register:
7
[N | V|

0
| B| p | I | Z |C|

PROCESSOR STATUS REG P"

L**CARRY
1 * TRUE
ZERO
1 = RESULT ZERO
IRQ DISABLE
1 * OISABLE
DECIMAL MODE
1 a TRUE
BRK COMMAND
OVERFLOW

1 TRUE

1 NEG

NEGATIVE

Figure 5-l I. 8502 Status Register

The flags of the status register are set for various reasons. For example, set
decimal mode when you want to perform calculations in binary coded decimal (BCD)
notation rather than hexadecimal. Set the carry flag when you are performing subtraction. Set the interrupt disable bit when you want to prevent interrupts from occurring.
An example of a split screen, smooth scrolling raster interrupt routine is given at the end
of Chapter 8.
The clear instructions operate in the reverse of the set instructions. To make sure
that a carry does not occur during an addition operation, clear the carry flag before

MACHINE LANGUAGE O N THE COMMODORE 128

adding two numbers in the accumulator. To perform mathematical operations in hexadecimal or binary numbers, clear the decimal mode flag so that your calculations are not
mistakenly performed in binary coded decimal. Whenever the result of a signed mathematical operation overflows into the sign bit an overflow error occurs. To correct this,
clear the overflow flag with the CLV op-code.
When a program requires interrupts, first set the interrupt disable bit (SEI) to
prevent interrupts from occurring. At the end of the interrupt initialization routine, issue
the CLI (Clear Interrupt Disable bit) instruction to enable (allow) interrupts to occur.

JUMP A N D RETURN INSTRUCTIONS

JUMP INSTRUCTIONS
The 8502 processor makes use of two jump instructions:
JMPJump to new location
JSRJump to new location Saving the Return address
These instructions both redirect control of the microprocessor to a location other than
the one immediately following it in memory. The first instruction, JMP, is a one-way trip
to the location specified in the operand field, or the contents of it (indirect). For example:
JMP $1800
jumps to location $1800 and executes the instruction contained in that location. This is a
direct jump.
You can also jump indirectly. For example:
JMP ($1800)
jumps to the address specified in the contents of location $1800. For instance, location
$1800 contains the value $FE and location $1801 contains the value $C0. Therefore, the
above instruction jumps to location $C0FE, and not location $1800. Jumping indirectly
is always denoted by parentheses around the address in the operand field, and it means
to jump to the location specified by the CONTENTS OF the address in the operand field.
The JSR instruction calls subroutines and saves the return address to the stack, so
when an RTS instruction is encountered at the end of the subroutine, the microprocessor
knows where to resume processing in the main (calling) program. Program control
resumes with the instruction in memory immediately following the JSR instruction. In
short, JSR is a round trip, while JMP is one way. For example:
. 01804
. 01807

20 58 18 JSR $1858
A2 0C
LDX #$0C

jumps to the subroutine starting at location $1858. The return address is saved on the
stack, so when the RTS instruction is encountered in this subroutine:

IS9

160

COMMODORE 128

01858
0185B
0185E
01860
01863

8E
2C
10
8D
60

00 D6 STX $D600
00 D6 BIT $D600
FB
BPL $185B
01 D6 STA $D601
RTS

the processor resumes with the main program instruction (LDX #$0C) in location $1807.

RETURN INSTRUCTIONS
The 8502 instruction set has two return instructions:
RTIReturn from Interrupt
RTSReturn from Subroutine
The first instruction returns from your interrupt service routine after the interrupt
disable bit is cleared (CL1) and the interrupt occurs. The RT1 is the last instruction in the
interrupt service routine. The interrupt service routine is the series of instructions which
are performed on the occurrence of an interrupt. Refer to Chapter 8, Raster Interrupt
Split Screen Program with Horizontal Scrolling for a working example of an interrupt
service routine.
The RTS instruction is the last instruction in a machine language subroutine called
from BASIC or by the machine language JSR instruction. See the Jump instructions
above for an example.

STACK INSTRUCTIONS
Four stack instructions are included in the 8502 instruction set to manipulate the values
on the stack. These instructions are as follows:
PHAPush accumulator on the stack
PHPPush processor status on the stack
PLAPull accumulator from the stack
PLPPull processor status from the stack
The term push means to place a value on the stack, while pull means to remove
a value from the stack. The only values pushed or pulled on to or off the stack are the
contents of the status register or the accumulator. The manipulation of the stack values
is important to the programmer when processing interrupts. The Raster Interrupt Split
Screen Program with Horizontal Scrolling section in Chapter 8 illustrates the manipulation of the stack values prior to returning from the interrupt.

THE NOP INSTRUCTION

The NOP instruction stands for no operation, lt is often used to add space between
program segments for readability. This instruction is not executable.

MACHINE LANGUAGE O N THE COMMODORE 128

8502 INSTRUCTION AND

ADDRESSING TABLE
The next 16 pages contain the 8502 Instruction and Addressing Table. These are the
conventions used in the table:
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.

OP-CODE
Brief definition
Operation notation
Status flags
Flags affected
Addressing Modes
Assembly language form
OP-CODE (in hex)
Number of bytes
Number of instruction cycles

The following notation applies to this summary:

A
X,Y
M
P
S
/
+
A
yI
i
^
<
V
PC
PCH
PCL
OPER
#

Accumulator
Index Registers
Memory
Processor Status Register
Stack Pointer
Change
No Change
Add
Logical AND
Subtract
Logical Exclusive Or
Transfer from Stack
Transfer to Stack
Transfer to
Transfer from
Logical OR
Program Counter
Program Counter High
Program Counter Low
OPERAND
IMMEDIATE ADDRESSING MODE

161

162

COMMODORE 128

ADC

Add memory to accumulator with carry

Operation: A + M + C ^ A, C

N
J

E
J

ADC
C
J

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Immediate
Zero Page
Zero Page, X
Absolute
Absolute, X
Absolute, Y
(Indirect, X)
(Indirect), Y

ADC
ADC
ADC
ADC
ADC
ADC
ADC
ADC

69
65
75
6D
7D
79
61
71

2
2
2
3
3
3
2
2

2
3
4
4
4*
4*
6
5*

# Oper
Oper
Oper, X
Oper
Oper, X
Oper, Y
(Oper, X)
(Oper), Y

I
-

D
-

V
J

* Add 1 if page boundary is crossed.

AND

" A N D " memory

AND

with accumulator

Logical AND to the accumulator

Operation: A AM ^ A

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Immediate
Zero Page
Zero Page, X
Absolute
Absolute, X
Absolute, Y
(Indirect, X)
(Indirect), Y

AND
AND
AND
AND
AND
AND
AND
AND

29
25
35
2D
3D
39
21
31

2
2
2
3
3
3
2
2

2
3
4
4
4*
4*

# Oper
Oper
Oper, X
Oper
Oper, X
Oper, Y
(Oper, X)
(Oper), Y

* Add 1 if page boundary is crossed.

6
5

M A C H I N E L A N G U A G E O N T H E C O M M O D O R E 128

ASL

ASL Shift Left One Bit (Memory or Accumulator)

Operation: C

7 6 5 4 3 2 10

Z
J

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Accumulator
Zero Page
Zero Page, X
Absolute
Absolute, X

ASL
ASL
ASL
ASL
ASL

0A
06
16
0E
lE

1
2
2
3
3

2
5
6
6
7

BCC

A
Oper
Oper, X
Oper
Oper, X

ASL
I

BCC Branch on Carry Clear

Operation: Branch on C = 0

BCC
N

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Relative

BCC

90

2*

Oper

Add 1 if branch occurs to same page.

Add 2 if branch occurs to different page.

BCS

BCS Branch on carry set

Operation: Branch on C = 1

BCS
N

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Relative

BCS

B0

2*

Oper

* Add 1 if branch occurs to same page.

* Add 2 if branch occurs todifferentpage.

163

164

C O M M O D O R E 128

BEQ

BEQ

BEQ Branch on result zero

Operation: Branch on Z = 1

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Relative

BEQ

F0

2*

Oper

* Add 1 if branch occurs to same page.

* Add 2 if branch occurs to next page.

BIT

BIT

BIT Test bits in memory with accumulator

Operation: A A M, M7 ^ N, M6 ^ V
Bit 6 and 7 are transferred to the status register.
If the result of AAM is zero then Z = 1, otherwise
Z =0

N Z
M7 /

C
-

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Zero Page
Absolute

BIT
BIT

24
2C

2
3

3
4

BMI

Oper
Oper

I
-

D
-

V
M6

BMI

BMI Branch on result minus

Operation: Branch on N = 1

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Relative

BMI

30

2*

Oper

* Add 1 if branch occurs to same page.

* Add 2 if branch occurs to different page.

BNE

BNE

BNE Branch on result not zero

N

Operation: Branch on Z = 0

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Relative

BNE

D0

2*

Oper

* Add 1 if branch occurs to same page.

* Add 2 if branch occurs to different page.

M A C H I N E L A N G U A G E O N T H E C O M M O D O R E 128

BPL

BPL

BPL Branch on result plus

Operation: Branch on N = 0

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Relative

BPL Oper

10

2*

* Add 1 if branch occurs to same page.

* Add 2 if branch occurs to different page.

BRK

BRK

BRK Force Break

Operation: Forced Interrupt PC + 2 | P j

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

BRK

00

1. A BRK command cannot be masked by setting I.

BVC

BVC

BVC Branch on overflow clear

Operation: Branch on V = 0

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Relative

BVC

50

2*

Oper

* Add 1 if branch occurs to same page.

* Add 2 if branch occurs to different page.

BVS

BVS

BVS Branch on overflow set

Operation: Branch on V = 1

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Relative

BVS

70

2*

Oper

* Add 1 if branch occurs to same page.

* Add 2 if branch occurs to different page.

165

166

COMMODORE 128

CLC

CLC Clear carry flag

CLC
N
-

Operation: 0

Z
-

C
0

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

CLC

18

CLD

I
-

CLD

CLD Clear decimal mode

Operation: 0 ~> D

N
-

Z
-

C
-

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

CLD

D8

CLI

I
-

V
-

CL/ Clear interrupt disable bit

Operation: 0 ^ I

CLI

N
-

Z
-

C
-

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

CLI

58

CLV

I
0

D
-

V
-

CLV Clear overflow flag

Operation: 0 ^ V

CLV
N

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

CLV

B8

D
-

V
0

MACHINE LANGUAGE O N THE COMMODORE 128

CMP

CMP

CMP Compare memory and accumulator

Operation: A - M

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Immediate
Zero Page
Zero Page, X
Absolute
Absolute, X
Absolute, Y
(Indirect, X)
(Indirect), Y

CMP
CMP
CMP
CMP
CMP
CMP
CMP
CMP

C9
C5
D5
CD
DD
D9
C1
D1

2
2
2
3
3
3
2
2

2
3
4
4
4*
4*
6
5*

#Oper
Oper
Oper, X
Oper
Oper, X
Oper, Y
(Oper, X)
(Oper), Y

* Add 1 if page boundary is crossed.

CPX

CPX

CPX Compare Memory and Index X

Operation: X - M

v/

v /

v /

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Immediate
Zero Page
Absolute

CPX
CPX
CPX

E0
E4
EC

2
2
3

2
3
4

CPY

#Oper
Oper
Oper

V
-

CPY

CPY Compare memory and index Y

Operation: Y - M

N
J

Z
j

C
y

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Immediate
Zero Page
Absolute

CPY
CPY
CPY

CO
C4
CC

2
2
3

2
3
4

#Oper
Oper
Oper

167

168

COMMODORE 128

DEC

DEC

DEC Decrement memory by one

Operation: M - 1 ^ M

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Zero Page
Zero Page, X
Absolute
Absolute, X

DEC
DEC
DEC
DEC

C6
D6
CE
DE

2
2
3
3

5
6
6
7

DEX

Oper
Oper, X
Oper
Oper, X

DEX Decrement index X by one

Operation: X - 1 ^ X

DEX

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

DEX

CA

DEY

DEY

DEY Decrement index Y by one

Operation: Y - 1 ^ Y

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

DEY

88

EOR

D V

EOR

EOR "ExclusiveOr" memory with accumulator

Operation : A ^ M ^ A

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Immediate
Zero Page
Zero Page, X
Absolute
Absolute, X
Absolute, Y
(Indirect, X)
(Indirect), Y

EOR
EOR
EOR
EOR
EOR
EOR
EOR
EOR

49
45
55
4D
5D
59
41
51

2
2
2
3
3
3
2
2

2
3
4
4
4*
4*
6
5*

#Oper
Oper
Oper, X
Oper
Oper, X
Oper, Y
(Oper, X)
(Oper), Y

* Add 1whenpage boundary is crossed.

MACHINE LANGUAGE O N THE COMMODORE 128

/NC Increment memory by one

INC

Operation: M + 1

INC
C

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Zero Page
Zero Page, X
Absolute
Absolute, X

INC
INC
INC
INC

E6
F6
EE
FE

2
2
3
3

INX

Oper
Oper, X
Oper
Oper, X

INX

INX Increment Index X by one

Operation: X + 1 ^ X

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

INX

E8

INY

INY

INY Increment Index Y by one

Operation: Y + 1 ^ Y

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

INY

C8

JMP

JMP

JMP Jump to new location

Operation: (PC + 1) ^ PCL

(PC + 2) ^ PCH

N
-

Z
-

C
-

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Absolute
Indirect

JMP
JMP

4C
6C

3
5

Oper
(Oper)

I
-

D
-

V
-

169

170

C O M M O D O R E 128

JSR

JSR

JSR Jump to new location saving return address

Operation: PC + 2 1 , (PC + 1) ^ PCL

(PC + 2) ^ PCH

N Z
- -

C
-

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Absolute

JSR

20

LDA

Oper

I
-

D
-

V
-

LDA

LDA Load accumulator with memory

Operation: M ~> A

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Immediate
Zero Page
Zero Page, X
Absolute
Absolute, X
Absolute, Y
(Indirect, X)
(Indirect), Y

LDA
LDA
LDA
LDA
LDA
LDA
LDA
LDA

A9
A5
B5
AD
BD
B9
A1
B1

2
2
2
3
3
3
2
2

2
3
4
4
4*
4*
6
5*

#Oper
Oper
Oper, X
Oper
Oper, X
Oper, Y
(Oper, X)
(Oper), Y

D V

* Add 1 if page boundary is crossed.

LDX

LDX

LDX Load index X with memory

Operation: M ^ X

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Immediate
Zero Page
Zero Page, Y
Absolute
Absolute, Y

LDX
LDX
LDX
LDX
LDX

A2
A6
B6
AE
BE

2
2
2
3
3

2
3
4
4
4*

#Oper
Oper
Oper, Y
Oper
Oper, Y

* Add 1 when page boundary is crossed.

D V

MACHINE LANGUAGE O N THE COMMODORE 128

LDY

LDY

LDY Load index Y with memory

Operation: M ^ Y

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Immediate
Zero Page
Zero Page, X
Absolute
Absolute, X

LDY
LDY
LDY
LDY
LDY

AO
A4
B4
AC
BC

2
2
2
3
3

2
3
4
4
4*

#Oper
Oper
Oper, X
Oper
Oper, X

* Add 1 when page boundary is crossed.

LSR

LSR

LSR Shift right one bit (memory or accumulator)

Operation:

|7|6|5l4l3l2lllol ^

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Accumulator
Zero Page
Zero Page, X
Absolute
Absolute, X

LSR A
LSR Oper
LSR Oper, X
LSR Oper
LSR Oper, X

4A
46
56
4E
5E

1
2
2
3
3

2
5
6
6
7

NOP

o / y- - -

NOP No operation

NOP

Operation: No Operation (2 cycles)

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

NOP

EA

171

172

COMMODORE 128

ORA "OR" memory with accumulator

ORA

Operation: A V M

N 2
/

ORA

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Immediate
Zero Page
Zero Page, X
Absolute
Absolute, X
Absolute, Y
(Indirect, X)
(Indirect), Y

ORA
ORA
ORA
ORA
ORA
ORA
ORA
ORA

09
05
15
0D
lD
19
01
11

2
2
2
3
3
3
2
2

2
3
4
4
4*
4*
6
5

#Oper
Oper
Oper, X
Oper
Oper, X
Oper, Y
(Oper, X)
(Oper), Y

* Add 1 on page crossing

PHA Push accumulator on stack

PHA

ation : A |

PHA

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

PHA

48

PHP Push processor status on stack

PHP

Operation: P 1

PHP

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

PHP

08

PLA Pull accumulator from stack

PLA

Operation: A f

PLA

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

PLA

68

MACHINE LANGUAGE O N THE COMMODORE 128

PLP

PLP Pull processor status from stack

PLP

Operation: P f

C I D
From Stack

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

PLP

28

ROL Rotate one bit left (memory or accumulator)

ROL

Operation:

M or A
|7|6|5l4l3|2[l

- & H

Z
J

C
J

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Accumulator
Zero Page
Zero Page, X
Absolute
Absolute, X

ROL A
ROL Oper
ROL Oper, X
ROL Oper
ROL Oper, X

2A
26
36
2E
3E

1
2
2
3
3

2
5
6
6
7

ROL

ROR Rotate one bit right (memory or accumulator)

ROR

Operation: ^C

7_ 6 5_4 3 2 i 0

Z
J

c
/

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Accumulator
Zero Page
Zero Page, X
Absolute
Absolute, X

ROR A
ROR Oper
ROR Oper, X
ROR Oper
ROR Oper,X

6A
66
76
6E
7E

1
2
2
3
3

2
5
6
6
7

ROR

173

174

C O M M O D O R E 128

RTI

RTI

RTI Return from interrupt

Operation: P | PC |

C I D
From Stack

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

RTI

40

RTS

RTS

RTS Return from subroutine

Operation: PC | , PC + 1 ^ PC

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

RTS

60

SBC

SBC Subtract memory from accumulator with borrow

Operation: A - M - C ^ A
Note: C = Borrow

N
/

Z
J

C
/

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Immediate
Zero Page
Zero Page, X
Absolute
Absolute, X
Absolute, Y
(Indirect, X)
(Indirect), Y

SBC
SBC
SBC
SBC
SBC
SBC
SBC
SBC

E9
E5
F5
ED
FD
F9
El
F1

2
2
2
3
3
3
2
2

2
3
4
4
4*
4*

#Oper
Oper
Oper, X
Oper
Oper, X
Oper, Y
(Oper, X)
(Oper), Y

* Add 1 when page boundary is crossed.

6
5*

SBC
I
-

D
-

V
J

MACHINE LANGUAGE O N THE COMMODORE 128

SEC

SEC Set carry flag

SEC

Operation: 1 ^ C

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

SEC

38

SED

SED Set decimal mode

Operation: 1

SED

N X

C
-

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

SED

F8

SEI

I
-

D
1

V
-

SE/ Set interrupt disable status

Operation: 1 ^ I

SEI

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

SEI

78

STA

STA

STA Store accumulator in memory

Operation: A ^ M

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Zero Page
Zero Page, X
Absolute
Absolute, X
Absolute, Y
(Indirect, X)
(Indirect), Y

STA
STA
STA
STA
STA
STA
STA

85
95
8D
9D
99
81
91

2
2
3
3
3
2
2

3
4
4
5
5
6
6

Oper
Oper, X
Oper
Oper, X
Oper, Y
(Oper, X)
(Oper), Y

175

176

COMMODORE 128

STX Store index X in memory

STX

Operation: X ^ M

STX

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Zero Page
Zero Page, Y
Absolute

STX
STX
STX

86
96
8E

2
2
3

Oper
Oper, Y
Oper

D V

4
4

STY Store index Y in memory

STY

Operation: Y ^ M

STY

z c

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Zero Page
Zero Page, X
Absolute

STY
STY
STY

84
94
8C

2
2
3

3
4
4

Oper
Oper, X
Oper

TAX Transfer accumulator to index X

TAX

Operation: A ^ X

N
/

Z
J

TAX

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

TAX

AA

TAY

TAY

TAY Transfer accumulator to index Y

Operation: A ^ Y

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

TAY

A8

M A C H I N E L A N G U A G E O N T H E C O M M O D O R E 128

TSX

TSX

Transfer

stack

pointer

to index

N
y

Operation: S

TSX

Z
j

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

TSX

BA

TXA

TXA

Transfer

index

X to

Z
y

ADDRESSING

ASSEMBLY

OP

NO.

NO.

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

TXA

8A

Transfer

index

X to stack

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

TXS

9A

index

Y to

TXS

ADDRESSING

TYA Transfer

pointer

Operation: X

TYA

TXA

MODE

TXS

accumulator

Operation: X

TXS

accumulator

Operation: Y

N
J

TYA

ADDRESSING

ASSEMBLY

OP

NO.

NO.

MODE

LANGUAGE FORM

CODE

BYTES

CYCLES

Implied

TYA

98

177

178

COMMODORE 128

INSTRUCTION ADDRESSING MODES AND

RELATED EXECUTION TIMES (in clock cycles)

et
O
H
< w
H
5 <J
S 3W
p
u
u<
ADC
AND
ASL
BCC
BCS
BEQ
BIT
BMI
BNE
BPL
BRK
BVC
BVS
CLC
CLD
CLI
CLV
CMP
CPX
CPY
DEC
DEX
DEY
EOR
INC
INX
INY
JMP
JSR
LDA
LDX
LDY
LSR
NOP
ORA
PHA
PHP

.
.
2

.
.
.
.

.
.
.

2
2
.

2
2
2
.

2
.

X >w w
o o

3
3
5

3
3
3
5

3
5

w
H
< < P
&
&
o o o
X X w
W W CQ
<

X
w
H
J5
oCfl
CQ
^t!

4
4
6

4
4
6

4*
4*
7

4
.
.
6

4
6

.
.
.

.
.
.
.

.
.

fcsT
H
3

O
c
CQ

W
>
H
<
W
06

H
U
W

3
z

.
.

6
6

5*
5*

2**
2**
2**

.
.
.

.
.
.

2**
2**
2**

.
.
.

.
.
.

2
2
2
2
.

2**
2**
.
.
.
.
.

.
.
.
.
.
.
6

.
.
.
.
.
.
5*

2
2
.

.
.
.

.
.
6

.
.
5*

2
2

.
.

.
.

.
.

.
.

.
.

6
.

5*
.

2
.
3
3

.
.
.
.

.
6
.
.

.
5*
.
.

4*
4*

.
.

<

4
4
4
6

4
6

.
.
.
2

2
2
2
.

3
3
3
5

4
.
4
6

.
4
.
.

3
6
4
4
4
6

4*

4*

4* 4*
7

4*
.
4*
7

4*
4*

4* 4*

H
u
w

5
z5
w
H

J
oy>

MACHINE LANGUAGE O N THE COMMODORE 128

os
o
H
<
J
P
S
p
u
V

W
O
<
0*
O
X
w
N

<

PLA
PLP
ROL
ROR
RTI
RTS
SBC
SEC
SED
SEI
STA
STX
STY
TAX
TAY
TSX
TXA
TXS
TYA

X
w
o
<
a.
O
x
W
N

>*

w
o
<
co
X
W
N

W
H
J3
oc^
n

<

><

fcd W
H H
U
>

ow oc^
CQ

CQ

<

, ,, , , , ,
2
2

.
.

5
5

. .
. .
2 3
.
, .

6
6

.
.

, .

.
.
.

3 4
3 .
3 4

6
6

.
.

4
4
4

4* 4*

4
4

.
.

6
6

.
.

2
2
2

.
.
.

H
U
W
0*
3

>

Z&

H
U
UJ
0*
5

w
H
o
CQ

<

. .
.

7
7

.
.
4
.

W
Q >
H H
3 <| XW

H
U
w

. .
. .

5*

, ,
2
2
2
2
2
2

.
.
.
.
.
.

* Add one cycle if indexing across page boundary

** Add one cycle if branch is taken. Add one additional if branching
operation crosses page boundary

A clock cycle is the speed at which the processor operates as determined by the
number of bytes transferred from one internal logic component to another. The 8502
operates at a default speed of 1 MHz, which is equivalent to 1,000,000 cycles per
second.

179

6
HOW TO ENTER
MACHINE LANGUAGE
PROGRAMS INTO THE
COMMODORE 128

181

182

COMMODORE 128

Now that you know about addressing modes, types of instructions and opcodes, you
need to know how to actually enter machine language instructions into the Commodore
128 memory. The C128 offers three methods of inputting instructions so that they may
be operated on by the microprocessor. You can enter machine language instructions by:
1.
2.
3.

Using the built-in machine language monitor (available in C128 mode only).
POKEing the translated decimal opcode values into memory with a BASIC
program (C128 and C64 modes).
Using an additional software program called an assembler.

All three methods have advantages and disadvantages. For instance, the built-in
machine language monitor is easy to use and allows you to program in machine
language without any additional aids such as an assembler. It makes merging BASIC
and machine language easy. In addition, you can save machine language programs as
binary files with the monitor SAVE command. Since you are already working in an
object code, there is no need to compile from source code into an object code, as is
necessary with an assembler.
Though these are powerful features, the monitor does not allow the use of symbolic
operand names or commented code. The monitor produces executable (object) code;
hence, no source files are produced. The resulting coded program contains actual
(absolute) address references, whereas an assembler source code file allows the use of
symbolic addresses and arguments as well as comments. When you display a machine
language program in the monitor, you do not have the luxury of comments or symbolic
address variables, so you really have to know what you are looking for when reading
other people's code. On the other hand, an assembler source file must be compiled into
executable object code, then used often with an additional program called a loader. This
requires three steps, whereas the monitor's machine language is ready to run as soon as
you finish writing the program.
The second method, POKEing translated decimal opcode data into memory with a
BASIC program, is an alternative usually implemented only when the first two options
are not available. This is the case if you have no assembler and are writing a machine
language routine in Commodore 64 mode, which does not make the built-in monitor
available to you. However, it is sometimes handy to POKE small routines from
BASIC if the application program you are writing is more suited for BASIC and you
need the speed of machine language for only a small portion of the program (though for
the most part, this method is tedious, bulky and time-consuming). Use it only if you
have no alternative, since once it is POKED into memory, you cannot display a listing
of the machine language routine as in the monitor or the assembler.
This chapter explains how to enter machine language programs in the first two
methods described above. The third method, using an assembler, requires an additional
software package similar to the Commodore 64 Assembler Development System. For
specific details on how to enter machine language programs with the assembler, refer to
the manual that is packed with the assembler software package you buy.

HOW T O ENTER MACHINE LANGUAGE PROGRAMS INTO THE COMMODORE 128

ENTERING MACHINE LANGUAGE

INSTRUCTIONS IN THE MONITOR
Begin entering machine language instructions by entering the monitor from BASIC with
the following command:
MONITOR

RETURN

The Commodore 128 responds with the following display:

MONITOR
PC
SR AC XR YR SP
; FB000 00 00 00 00 F8
These values indicate the contents of the microprocessor registers upon entering
the monitor. The abbreviations and definitions of the register names are as follows:
PCProgram Counter
SRStatus Register
ACAccumulator
XRX Index Register
YRY Index Register
SPStack Pointer

Marks the address of the current machine language

instruction
Flags that alert the microprocessor of certain conditions
Register for all mathematical operations
Used for effective address modification
Same as X register
Indicates the address of the first available memory
location on the stack

Now you can begin to enter machine language instructions. The ASSEMBLE
command within the monitor enters the instructions into the specified memory location.
To enter instructions, follow the format of this example:
A 01800 LDA # $ 0 0
Make sure to leave at least one space between each of the fields. Here's what each
part of the instruction means:
<Assemble>

<Address in memory where opcode is stored>

<Opcode>

<Operand>

The A stands for ASSEMBLE an opcode. The second part (field) is the address
where the opcode in the instruction is placed in the Commodore 128 memory. Notice
the 5-digit hexadecimal number specifying the address. The leftmost digit (0-F) specifies the configuration of the Commodore 128 memory layout. This is the same as the
BANK command in BASIC.
Once the entire machine language program is entered, reference the address that is
contained in the first instruction you entered to start execution of the program. Execute
the program with the GO command in the monitor, or exit the monitor with the X
(EXIT) command and issue the SYS command from BASIC. If you SYS to the start of
the program, you must use the decimal equivalent of the hexadecimal address, which

183

184

COMMODORE 128

appears in the first instruction you entered. You must have an RTS instruction at the end
of the routine if you want to return to BASIC. Often, the Kernal must be resident in the
current configuration in context in order to obtain results.
The opcode is the 8502 instruction that is carried out by the microprocessor when
your program is running. See the 8502 Instruction Set Table in Chapter 5 for allowable
instructions.
The operand is the address or value that is acted upon by the opcode in the
instruction. If the operand field is preceded by a pound sign ( # ) , the opcode will act
upon a constant value. If no pound sign is specified, the microprocessor assumes the
opcode will act upon an address.
Remember to separate each field in the instruction with at least one space. If you
don't, the computer indicates that an error has occurred by displaying a question mark at
the end of the instruction.
Once a routine is displayed on the screen, the monitor allows shortcuts in entering
instructions. To display a listing of a machine language program, issue the DISASSEMBLE command as follows:
D 04000 04010

RET U R N

The " D " stands for disassemble. The first number (04000) specifies the starting
memory location in which you want the contents displayed. The second number
specifies the end address in which to display.
Now for the shortcut. Since the address where the opcodes are stored is already on
the screen, you can simply move the cursor to the opcode field, type over the existing opcode and operand on the screen, erase any unwanted characters and press
R ET U RN
. The computer registers the instruction in memory by displaying the
hexadecimal values for the opcode and operand directly to the left of the opcode
mnemonic you just entered. This is a faster and easier way of entering machinelanguage routines, rather than typing the ASSEMBLE command and the address each
time you enter an instruction.

EXECUTING (RUNNING)
YOUR MACHINE-LANGUAGE PROGRAM
Once you have finished entering your machine language routine, you may execute it in
three different ways. Within the monitor, issue the GO or JUMP to Subroutine command as follows:
GF1800
J F1800

(JMP)
(JSR)

The G stands for GO, or go to the start address of the machine language program
in memory, and begin executing it at the specified address. The value following the
letter G refers to the start address of your routine. The J stands for Jump to Subroutine, similar to the JSR mnemonic in machine language.
The third way to invoke a machine language routine is to exit the monitor by

H O W T O ENTER MACHINE LANGUAGE PROGRAMS I N T O THE COMMODORE 128

pressing the X key and R E T U R N . This places you back within the control of the
BASIC language. Next, issue the SYS command and reference the starting address in
decimal as follows:
BANK 15
SYS 6144
This SYS command is the same as the GO command (G F1800) example above.
The BANK 15 command and the leading F in the 5-digit hexadecimal number F1800
specify memory configuration 15. The Kernal, BASIC and other ROM code are
resident in this configuration. The only difference is that it executes the machine
language routine from BASIC, instead of within the monitor.
The machine language routine given below clears the text screen. Starting at
location 1024 ($0400), the value 32 ($20) is stored in each screen location. The
character string value 32 is the space character, which blanks out each character position
on the screen. When finished, an RTS instruction returns control to BASIC. Here's the
main BASIC program and the machine language screen-clear subroutine as it appears in
the machine language monitor.

10
20
30
40
50
60
70
80
90

FOR 1= 1 TO 2 5
PRINT"FILL THE SCREEN WITH CHARACTERS"
NEXT
PRINT:PRINT
PRINT"NOW CALL THE MACHINE LANGUAGE"
PRINT" ROUTINE TO CLEAR THE SCREEN"
SLEEP 5
SYS DEC("1800")
PRINT"THE SCREEN IS NOW CLEARED"

READY.
MONITOR

PC SR AC XR YR SP
; FB000 00 00 00 00 F8
.
.
.
.
.
.
.
.
.

01800
01802
01804
01807
0180A
0180D
01810
01811
01813

A2
A9
9D
9D
9D
9D
E8
D0
60

00
20
00
00
00
E7
F1

04
05
06
06

LDX
LDA
STA
STA
STA
STA
INX
BNE

#$00
#$20
$ 0 400 , X
$0500,X
$0600,X
$0 6E7,X
$1804

RTS

In this sample program, the SYS command executes the subroutine to clear the
text screen. Once the text screen is cleared, control of the microprocessor is returned to
BASIC by the RTS instruction, and the READY prompt is displayed.

185

186

C O M M O D O R E 128

MACHINE LANGUAGE
MONITOR COMMANDS

The C128's built-in machine language monitor has several additional commands that
manipulate your machine language routines once they are entered into memory. Figure
6 - 1 is a summary of all the commands available to you in the machine language
MONITOR.

FORMAT

KEYWORD

FUNCTION

ASSEMBLE

Assembles a line of 8502 code

COMPARE

Compares two sections of mem- C

ory and reports differences
Disassembles a line or lines of 8502 D
code
Fills a range of memory with spec- F
ified byte
Starts execution at the specified G
address
Hunts through memory within a H
specified range for all occurrences
H
of a set of bytes

DISASSEMBLE
FILL
GO
HUNT

GOSUB
LOAD

Jumps to the subroutine

Loads a file from tape or disk

MEMORY

Displays the hexadecimal values M

of memory locations
Displays the 8502 registers
R
Saves to tape or disk
S

REGISTERS
SAVE

J
L

<start address> <opcode>

[operand]
<start address> <end address>
<new start address>
[<start address> <end address>]
<start address> <end address>
<byte>
[address]
<start address> <end address>
<bytel> [<byte n> . . .]
<start address> <end address>
<ascii string>
[address]
"<fiIename>"[,<device # >
[,<load address>]]
[<start address>
[<end address>]]
"<filename>",<device # > ,
<start address> <last address
i
T

TRANSFER
VERIFY
EXIT
(period)
(greater than)
(semicolon)

Transfers code from one section

of memory to another
Compares memory with tape or
disk
Exits Commodore 128 MONITOR
Assembles a line of 8502 code
Modifies memory
Modifies 8502 register displays

T
V

i \
1^>

<start address> <end address>

<new start address>
"<filename>"[,<device # > [ ,
<load address>]]

X
>
5

[address]

HOW T O ENTER MACHINE LANGUAGE PROGRAMS INTO THE COMMODORE 128

FORMAT

KEYWORD

FUNCTION

(at sign)

Displays disk status, sends disk

command, displays directory
disk status
disk command
disk catalog

@
@[device # ]
@[device #],<command
string>]
@[device #],$[[<drive>:<file
spec>]]

NOTES < > enclose required parameters

[] enclose optional parameters
Figure 6 - 1 . Summary of C o m m o d o r e 128 Monitor Commands

N O T E : 5-Digit Addresses
The Commodore 128 displays 5-digit hexadecimal addresses within the
machine language monitor. Normally, a hexadecimal number is only four
digits, representing the allowable address range. The extra left-most (high
order) digit specifies the BANK configuration (at the time the given
command is executed) according to the following memory configuration
table:
0RAM 0 only
1RAM 1 only
2RAM 2 only
3RAM 3 only
4INT ROM, RAM
5INT ROM, RAM
6INT ROM, RAM
7INT ROM, RAM

0,
1,
2,
3,

I/O
I/O
I/O
I/O

8EXT ROM, RAM 0, I/O

9EXT ROM, RAM 1, I/O
AEXT ROM, RAM 2, I/O
BEXT ROM, RAM 3, I/O
CKERNAL + INT (lo). RAM 0, I/O
DKERNAL + EXT (lo), RAM 1, I/O
EKERNAL + BASIC, RAM 0, CHARROM
FKERNAL + BASIC, RAM 0, I/O

SUMMARY OF MONITOR
FIELD DESCRIPTORS
The following designators precede monitor data fields (e.g., memory dumps). When
encountered as a command, these designators instruct the monitor to alter memory or
register contents using the given data.

>
;

<period> precedes lines of disassembled code.

<right angle> precedes lines of a memory dump.
<semicolon> precedes line of a register dump.

The following designators precede number fields (e.g., address) and specify the radix
(number base) of the value. Entered as commands, these designators instruct the monitor
simply to display the given value in each of the four radices.

187

188

COMMODORE 128

$
+
&
%

< n u l l > (default) precedes hexadecimal values.

<dollar> precedes hexadecimal (base-16) values.
< p l u s > precedes decimal (base-10) values.
<ampersand> precedes octal (base-8) values.
<percent> precedes binary (base-2) values.

The following characters are used by the monitor as field delimiters or line terminators
(unless encountered within an ASCII string).

:
?

< s p a c e > delimiterseparates two fields,

< c o m m a > delimiterseparates two fields.
< c o l o n > terminatorlogical end of line.
<question> terminatorlogical end of line.

MONITOR COMMAND DESCRIPTIONS

The following are descriptions of each of the C128 Machine Language Monitor commands.

COMMAND:
PURPOSE:
SYNTAX:

Enter a line of assembly code.

A <address> <opcode mnemonic> <operand>
<address>
A number indicating the location in memory to
place the opcode. (See 5-digit address note on
previous page.)
<opcode>
A standard MOS technology assembly language
mnemonic, e.g., LDA, STX, ROR.
<operand>
The operand, when required, can be any of the
legal addresses or constants.

A R E T U R N is used to indicate the end of the assembly line. If there are

any errors on the line, a question mark is displayed to indicate an error, and the
cursor moves to the next line. The screen editor can be used to correct the error(s) on
that line.
EXAMPLE:
.A 01200 LDX # $ 0 0
.A 01202
N O T E : A period (.) is equal to the ASSEMBLE command.

EXAMPLE:
.02000 LDA # $ 2 3

H O W T O ENTER MACHINE LANGUAGE PROGRAMS I N T O THE COMMODORE 128

COMMAND:
PURPOSE:
SYNTAX:

COMMAND:
PURPOSE:
SYNTAX:

Compare two areas of memory.

C <address 1> <address 2 > <address 3 >
<address 1>
A number indicating the start address of the area
of memory to compare against,
<address 2 >
A number indicating the end address of the area
of memory to compare against,
<address 3 >
A number indicating the start address of the other
area of memory to compare with. Addresses that
do not agree are printed on the screen.

D
Disassemble machine code into assembly language mnemonics and
operands.
D [ < a d d r e s s > ] [<address 2 > ]
<address>
A number setting the address to start the disassembly.
<address 2 >
An optional ending address of code to be disassembled.

The format of the disassembly differs slightly from the input format of an assembly. The
difference is that the first character of a disassembly is a period rather than an A (for
readability), and the hexadecimal value of the op-code is listed as well.
A disassembly listing can be modified using the screen editor. Make any changes
to the mnemonic or operand on the screen, then hit the carriage return. This enters the
line and calls the assembler for further modifications.
A disassembly can be paged. Typing a D R E T U R N
causes the next page
of disassembly to be displayed.
EXAMPLE:
D3000
.03000
.03002
.03003

COMMAND:
PURPOSE:
SYNTAX:

3003
A9 00
FF
D0 2B

LDA # $ 0 0
77?
BNE $3030

F
Fill a range of locations with a specified byte.
F <address 1> <address 2 > < b y t e >
<address 1>
The first location to fill with the < b y t e > .
<address 2 >
The last location to fill with the < b y t e > .
< b y t e value>
A 1- or 2-digit hexadecimal number to be written.

This command is useful for initializing data structures or any other RAM area.

189

190

COMMODORE 128

EXAMPLE:
F0400 0518 EA
Fill memory locations from $0400 to $0518 with $EA (a NOP instruction).
COMMAND:
PURPOSE:
SYNTAX:

G
Begin execution of a program at a specified address.
G [<address>]
<address>
An address where execution is to start. When
address is left out, execution begins at the current
PC. (The current PC can be viewed using the R
command.)

The GO command restores all registers (displayable by using the R command) and
begins execution at the specified starting address. Caution is recommended in using the
GO command. To return to the Commodore 128 MONITOR after executing a machine
language program, use the BRK instruction at the end of the program.
EXAMPLE:
G 140C
Execution begins at location $140C in configuration (BANK)0. Certain applications may require that Kernal and/or I/O be present when execution begins.
Precede the four-digit hexadecimal number with the hex configuration number
which contains those appropriate portions of memory.)
COMMAND:
PURPOSE:
SYNTAX:

H
Hunt through
set of bytes.
H <address
<address
<address
<data>

memory within a specified range for all occurrences of a

1> <address 2 > < d a t a >
1>
Beginning address of hunt procedure,
2>
Ending address of hunt procedure,
Data set to search for data may be hexadecimal
for an ASCII string.

EXAMPLE:
H A000 A101 A9
Search for data $A9 from A000 to A101.
H2000 9800 'CASH'
Search for the alpha string " C A S H " .
COMMAND:
PURPOSE:
SYNTAX:

J
Jump to a machine language subroutine.
J
<address>

The JUMP to SUBROUTINE command directs program control to the machine language

H O W T O ENTER MACHINE LANGUAGE PROGRAMS I N T O THE COMMODORE 128

subroutine located at the specified address. This command saves the return address as
does the 8502 instruction JSR (Jump to Subroutine). In other words, the JUMP
command is a two-way instruction, where the application gains control of the computer.
Only after the subroutine encounters an RTS instruction does the machine language
monitor regain control.
EXAMPLE:
J 2000
Jump to the subroutine starting at $2000 in configuration 0.
COMMAND:
PURPOSE:
SYNTAX:

L
Load a file from cassette or disk.
L < " f i I e n a m e " > [ , < d e v i c e > [ , a l t load address]]
< " f i l e n a m e " > Any legal Commodore 128 file name,
<device>
A number indicating the device to load from. 1 is
cassette. 8 is disk (or 9, A, etc.).
[alt load address] Option to load a file to a specified address.

The LOAD command causes a file to be loaded into memory. The starting address is
contained in the first two bytes of the disk file (a program file). In other words, the
LOAD command always loads a file into the same place it was saved from. This is very
important in machine language work, since few programs are completely relocatable.
The file is loaded into memory until the end of file (EOF) is found.
EXAMPLE:
L " P R O G R A M " , 8 Loads the file name PROGRAM from the disk.

COMMAND:
PURPOSE:
SYNTAX:

M
To display memory as a hexadecimal and ASCII dump within the
specified address range.
M [<address 1>] [<address 2 > ]
<address 1>
First address of memory dump. Optional. If omitted, one page is displayed. The first digit is the
bank number to be displayed, the next four digits
are the first address to be displayed,
<address 2 >
Last address of memory dump. Optional. If omitted, one page is displayed. The first digit is the
bank number to be displayed; the next four digits
are the ending address to be displayed.

Memory is displayed in the following format:

>1A048 41 42 43 44 45 46 47 48:ABCDEFGH

191

192

COMMODORE 128

Memory contents may be edited using the screen editor. Move the cursor to the data to be
modified, type the desired correction and hit R E T U R N . If a syntax error
or an attempt to modify ROM has occurred, an error flag (?) is displayed. An
ASCII dump of the data is displayed in reverse (to contrast with other data displayed on
the screen) to the right of the hex data. When a character is not printable, it is displayed
as a reverse period. As with the disassembly command, paging down is accomplished by typing M and R E T U R N
EXAMPLE:
M 21C00
>21C00 41 4A 4B 4C 4D 4E 4F 50 :AJKLMNOP
N O T E : The above display is produced by the 40-column editor.

COMMAND:
PURPOSE:

Show important 8502 registers. The status register, the program counter,
the accumulator, the X and Y index registers and the stack pointer are
displayed. The data in these registers is copied into the microprocessor
registers when a " G " or " J " command is issued.

SYNTAX:
EXAMPLE:
R
PC
SR AC XR YR SP
; 01002 01 02 03 04 F6

N O T E : ; (semicolon) can be used to modify register displays in the same

fashion as > can be used to modify memory registers.

COMMAND:
PURPOSE:
SYNTAX:

Save the contents of memory onto tape or disk.

S < " f i l e n a m e " > , < d e v i c e > , < a d d r e s s 1>, <address 2 >
< " f i l e n a m e " > Any legal Commodore 128 filename. To save
the data, the file name must be enclosed in double quotes. Single quotes cannot be used,
<device>
A number indicating on which device the file is
to be placed. Cassette is 01; disk is 08, 09, etc.
<address 1>
Starting address of memory to be saved,
<address 2 >
Ending address of memory to be saved + 1. All
data up to, but not including, the byte of data at
this address is saved.

H O W T O ENTER MACHINE LANGUAGE PROGRAMS I N T O THE COMMODORE 128

The file created by this command is a program file. The first two bytes contain the
starting address <address 1> of the data. The file may be recalled, using the L
command.
EXAMPLE:
S "GAME",8,0400,0C00
Saves memory from $0400 to $OBFF onto disk.

COMMAND:
PURPOSE:
SYNTAX:

T
Transfer segments of memory from one memory area to another.
T <address 1> <address 2 > <address 3 >
<address 1>
Starting address of data to be moved,
<address 2 >
Ending address of data to be moved,
<address 3 >
Starting address of new location where data will
be moved.

Data can be moved from low memory to high memory and vice versa. Additional
memory segments of any length can be moved forward or backward. An automatic
"compare" is performed as each byte is transferred, and any differences are listed by
address.
EXAMPLE:
T1400 1600 1401
Shifts data from $1400 up to and including $1600 one byte higher in memory.

COMMAND.
PURPOSE:
SYNTAX:

V
Verify a file on cassette or disk with the memory contents.
V < " f i l e n a m e " > [ , < d e v i c e > ] [ , a l t start address]
< ' ' f i l e n a m e " > Any legal Commodore 128 file name,
<device>
A number indicating which device the file is on.
Cassette is 01; disk is 08, 09, etc.
[alt start address] Option to start vertification at this address.

The VERIFY command compares a file to memory contents. If an error is found, the
words VERIFY ERROR are displayed; if the file is successfully verified, the cursor
reappears without any message.
EXAMPLE:
V " W O R K L O A D ' ' ,08

193

194

COMMODORE 128

COMMAND:
PURPOSE:
SYNTAX:
COMMAND:
PURPOSE:
SYNTAX:

COMMAND:
PURPOSE:
SYNTAX:

Exit to BASIC.
X
> (greater than)
Can be used to assign values for one to eight memory locations at a time
(in 40-column mode; up to 16 in 80-column mode).
> <address> <data byte 1> <data byte 2 . . . 8 >
<address>
First memory address to set.
<data byte 1>
Data to be put at address,
<data byte 2 . . . 8>Data to be placed in the successive memory
locations following the first address (optional)
with a space preceding each data byte.
@ (at sign)
Can be used to send commands to the disk drive.
@ [<device number>], <disk cmd string>
<device number> Device unit number (optional),
<disk cmd string>String command to disk.

N O T E : @ alone gives the status of the disk drive.

EXAMPLES:
@
@,I

checks disk status

00, OK, 00, 00
initializes drive 8

@,$
@,$0:F*

displays disk directory on unit 8.

display all files on Drive 0, unit 8 starting with the letter F.

As a further aid to programmers, the Kernal error message facility has been automatically enabled, while in the Monitor. This means the Kernal will display T/O E R R O R # '
and the error code, should there be any failed I/O attempt from the MONITOR. The
message facility is turned off when exiting the MONITOR.

MANIPULATING TEXT WITHIN

THE MACHINE LANGUAGE MONITOR
Certain machine language application programs require the manipulation of strings of
characters. If you are using an assembler package, it contains provisions for handling
strings of characters. However, within the monitor, strings of characters must be placed
in memory, either (1) through modifying a memory dump using the screen editor, or (2)

H O W T O ENTER MACHINE LANGUAGE PROGRAMS INTO THE COMMODORE 128

by placing the ASCII values of the characters in memory locations within a program.
To modify a memory dump using the screen editor, issue the M E M O R Y command with the address range in which you want to place the character string information. For example, suppose you want to place the word " T E X T " in memory starting at
location $2000. First, enter the machine language monitor with the MONITOR command. Next, issue the memory command containing the address $2000 as follows:
M 2000
The 128 responds with this display:
02000 FF 00 FF 00 FF 00 FF 00: 7r.TT.7r.TT.
The entire screen is filled with the contents of the memory (dump) locations $2000
through $205F. For illustrative purposes, only one line of the memory dump is shown.
This line pertains to the address range $2000 through $2007. At the right of the screen is
an area that displays the corresponding ASCII character for each value within a memory
location in that line of the memory dump. The left character in the display area
corresponds to location $2000, the second character position to the right pertains to
address $2001, and so on. To place the word " T E X T " in memory starting at location
$2000, move the cursor up to the first line of the memory dump, move the cursor right
to the memory address that pertains to address $2000, and place the ASCII character
string code for the letter T in this position. To do this, type over the characters that are
there and replace them with the hexadecimal equivalent of decimal 84 ($54) and press
RETURN
. Notice that the letter T is now displayed at the right of the screen.
Refer to Appendix E, ASCII and CHR$ Codes, for a list of the Commodore ASCII
codes for each character available in the Commodore 128.
Now do the same procedure for the letters E, X and T. When you are through, the
word " T E X T " is displayed in the display area. The first line of the memory dump now
looks like this:
02000 54 45 58 54 FF 00 FF 00: TEXT 7r. 7r.
Now the character string you wish to manipulate is in memory, starting at address
$2000. Your machine language routine can now act upon the characters of the word
" T E X T " in order to display them on the screen. An efficient way of manipulating
entire words is to use the start address in memory where the text begins, in this case
$2000. Determine the length of the string, and use an index register as an offset to the
end of the word. See the section Raster Interrupt Split Screen Program with Horizontal
Scrolling in Chapter 8, for a working example of manipulating text. This chapter has
described the use of machine language. For additional information on machine language
topics, see Chapter 5, 7, 8, 9, 10, 11, and 13.

195

7
MIXING
MACHINE
LANGUAGE
AND B A S I C

197

198

COMMODORE 128

WHY MIX B A S I C AND

MACHINE LANGUAGE?
Certain application programs are better suited for a high-level language such as BASIC
rather than low-level machine language. In other cases, however, certain portions of a
program, such as displaying graphics, may require the speed of machine language while
the rest of the program lends itself to the use of BASIC. This is the main reason for
mixing BASIC programs with machine language subroutines. Another reason may be
the lack of an alternative in programming machine language. For example, in C64
mode, a machine language monitor is not ordinarily available to the user. In addition,
you may not have an assembler package, so the only alternative is to enter machine
language programs through the BASIC language. This method has disadvantages; it can
be tedious and time-consuming, and once the routine is entered into memory, you have
no way of listing it to the screen for editing. This method is recommended only if no
alternative is available.

ENTERING MACHINE LANGUAGE

SUBROUTINES THROUGH B A S I C
In Chapter 6, you saw an example of how to use the SYS command to go from BASIC
to a machine language routine that cleared the text screen. The SYS command invoked
the subroutine, cleared the screen, and returned to BASIC with the RTS instruction.
This example illustrated the SYS command within a program. You can also SYS to a
machine language subroutine outside a BASIC program, as follows:
SYS 8192
This example assumes you entered the machine language subroutine through the
monitor (and it is still in memory). What if you don't have the monitor available to you,
as in C64 mode, and you want to mix a machine language subroutine with a BASIC
program?
The answer to this is to POKE decimal data that represents the hexadecimal
opcodes and operands into memory. To activate the subroutine, you SYS to it as you did
before. This method of entering machine language programs requires these steps:
1.
2.

3.

Write your machine language program on a piece of paper.

Translate the hexadecimal op-code values into decimal. Some instructions
require 3 bytes of memory, while others only use 1 or 2 bytes of memory. For
a list of hexadecimal opcodes for the 8502 machine language instruction set,
see the 8502 Instruction and Addressing Table, in Chapter 5.
Enter the decimal equivalents of the opcodes into DATA statements in such a
way that a 2-byte instruction, for example, is entered as follows:

MIXING MACHINE LANGUAGE A N D BASIC

1000 DATA 162,0: REM - LDX # $ 0 0 = $A2, $00

4.

The hexadecimal number $A2 represents the 8502 instruction for LDX, which
equals 162 in decimal. The 0 (zero) represents the operand 0, which is
loaded into the X register in the instruction. In hex, 0 is the same as in
decimal, so the second byte of the instruction is the operand value 0. The
hexadecimal opcodes are translated into strings of binary digits (bits), so the
microprocessor can interpret and operate them. This is the true machine
language of the computer at its lowest level.
Once you have translated all the opcodes and operands into decimal, you
must place them in memory. Accomplish this by READing a DATA value in
BASIC and POKEing it into memory in an appropriate address range. For
example, to enter the LDX # $ 0 0 instruction into memory, in C128 mode,
perform the following routine:
10
20
30
40
45
50
60
70
80

ALPHA - 8192
I - 0
DO
READ A
IF A - 9 9 9 THEN EXIT
POKE ALPHA + I,A
I = 1+1
LOOP
PRINT " A L L DATA IS NOW IN M E M O R Y "

1000 DATA 162,0,-999

For C64 mode use this routine:
10
20
40
50
60

ALPHA = 8192
FOR 1 = 0 TO 1
READ A
POKE ALPHA + I,A
NEXT

80 PRINT "ALL DATA IS NOW IN M E M O R Y "

1000 DATA 162,0

The first example, in C128 mode, READs all DATA and POKEs it into
memory, starting at location 8192 ($2000), until a data item is equal to - 9 9 9 .
When the data item equals -999, EXIT the loop and print a message saying
all the data is read into memory at the specified locations. This DO . . .
LOOP allows you to enter as many data items as you please without the need
to know how many data items are in the data list, since it checks for the
terminator value -999. This programming approach makes it easy to modify
the number of data entries without having to change any of the code. This
program assumes that the bit map screen is not being used ($2000-$3FFF).

199

200

COMMODORE 128

5.

The second example, in C64 mode, uses a F O R . . . NEXT loop to

enter the data. This requires you to know how many data items are in the data
list. You can add an IF . . . THEN statement to check for a terminator value
like - 9 9 9 , as in the first example. However, this method illustrates a different
way of accomplishing the same thing.
The final step in entering machine language subroutines through BASIC is
executing the subroutine with the SYS command. Add line 90 to your BASIC
routines above as follows:
90 SYS 8192
This command executes the machine language routine that you POKEd into
memory starting at location 8192.

Although the DATA statement in the example in Step 4 does not show it, all
machine language subroutines must end with an RTS instruction so you can return to
BASIC. The decimal code for an RTS machine language instruction is 96. Your last
decimal data item in the final data statement in your program must be 96, unless you use
a terminator like -999; then - 9 9 9 will be your last decimal data item.
Figure 7-1 shows a step-by-step translation from the machine language screenclear routine as it appears in the monitor and a complete program that mixes the clear
screen routine with the BASIC program that POKEs in the data and executes the
machine language subroutine. It only operates in the 40-column (VIC) screen.

MIXING MACHINE LANGUAGE A N D BASIC

Address

Symbolic
Instruction

Hex Opcode

Decimal Equivalent
1st Byte
(Opcode)

02000
02002
02004
02007
0200A
0200D
02010
02011

A2
A9
9D
9D
9D
9D
E8
D0

02013

60

00
20
00
00
00
E7
F1

04
05
06
06

LDX
LDA
STA
STA
STA
STA
INX
BNE

#$00
#$20
$0400,X
$0500,X
$0600,X
$ 0 6E7,X

=
=
=
=

$2004

RTS

162
169
157
157
157
157
232
208

2nd Byte
3rdByte
(Operand)

0
32
0
0
0
231

4
5
6
6

241

Figure 7-1. Step-by-step Translation into Decimal

To find the hexadecimal opcodes, refer to the 8502 Instruction and Addressing Table in Chapter 5. Notice in Figure 7-1 that the hexadecimal opcodes are displayed
within the monitor, directly to the left of the symbolic instruction. These hexadecimal
numbers are the codes that you translate into decimal data items in a BASIC program.
Notice that the second byte in the BNE instruction is the value 241. ln a branch
instruction, the operand is not an absolute address, but is instead an offset to the
instruction to which it will branch. In this case, the BNE instruction branches backward
to location $2004; therefore, it branches backward 15 locations in memory to the first
store (STA) instruction.
You're probably wondering how the code 241 tells the computer to branch
backward by 15. The number 241 (decimal) is the 2's complement of the value 15.
When bit 7 is enabled, the microprocessor branches backward. The number 241
signifies to branch backward by 15 memory locations and execute the instruction in that
location. To find the root value of a 2's complement number, do this:
1.
2.
3.

Translate the value into binary:

241 = 1111 0001
Subtract 1:
- 1 1 1 1 0000 = 240
Convert each bit to its complement; in other words,
ohange each bit to the opposite value:
= 0000 1111 = 15

To find the two's complement of a number, perform steps 1 and 3 above;

then add 1 to the value instead of subtracting.
Here's the complete C128 mode program, including all the decimal DATA
equivalents of the instructions in the machine language, clear-screen subroutine above:
10 ALPHA=8192
20

1=0

30
40
45
50

DO
:
:
:

60 :

READ A
IF A=-999 THEN EXIT
POKE ALPHA+I,A

I=I+1

7 0 LOOP
80 PRINT"ALL DATA IS NOW IN MEMORY"
8 5 SLEEP 1
90 SYS 8192
1000 DATA 162, 0 , 16 9, 32 , 157 , 0, 4 , 15 7 , 0, 5, 15 7 , 0, 6 , 15 7 , 231 ,6
2000 DATA 232 , 20 8 , 241 , 96 , -999

201

202

COMMODORE 128

Here is the corresponding program in C64:

10 ALPHA=8192
20 FOR 1=0 TO 19
40 :
READ A
50 :
POKE ALPHA+I,A
6 0 NEXT
80 PRINT"ALL DATA IS NOW IN MEMORY"
85 FOR 1 = 1 TO 2500:NEXT
90 SYS 8192
1000 DATA 162,0,169,32,157,0,4,157,0,5,157,0,6,157,231,6
2000 DATA 232,208,241,96

When you run this program, the computer READs the DATA, POKEs it into
memory, and executes the machine language, clear-screen subroutine with the SYS
command. After you RUN the program, enter the machine language monitor (assuming
you are currently in C128 mode) and disassemble the code in the range $2000 through
$2015 with this command:
D 2000 2015
Notice that the subroutine you POKEd in through BASIC is the same as the
subroutine that appears in Figure 7-1. The two different methods accomplish the same
goalprogramming in 8502 machine language.

WHERE T O PLACE MACHINE

LANGUAGE PROGRAMS IN MEMORY
The Commodore 128 has 128K of RAM memory, divided into two 64K RAM banks.
Much of the 128K of RAM is overlaid by ROM, but not at the same time. The
Commodore 128 memory is layered, so RAM is beneath the overlaid ROM. The
designers of the Commodore 128 have managed to squeeze 28K of ROM and 128K of
RAM into 128K of address space. Only one bank is available or mapped in at a time,
since the highest address an 8-bit microprocessor can address is 65535 ($FFFF).
However, because the C128 is capable of banking RAM and ROM in and out so fast, it
may seem as though 128K is always available.
In the portions of memory shared by RAM and ROM, a read operation returns a
ROM data value and a write operation "bleeds through" to the RAM beneath the
layered ROM. The data is stored in the RAM memory location. If the data in RAM
beneath the ROM is a program, the ROM on top must be switched out before the
program in RAM can be executed. The RAM and ROM layout in memory is all
regulated and controlled through the Configuration Register (CR) of the Memory-

MIXING MACHINE LANGUAGE AND BASIC

Management Unit (MMU). For detailed information, refer to the sections on the
Registers of the Memory Management Unit (specifically, the discussion of the Configuration Register) in Chapter 13.

WHERE TO PLACE MACHINE LANGUAGE ROUTINES

IN CONJUNCTION WITH B A S I C
Within BASIC, the operating system takes care of the mapping in and out of ROM and
RAM. The C128 operating system provides sixteen (default) memory configurations.
They each contain different values in the Configuration Register; therefore, each has a
different configuration. This gives you sixteen different configurations of memory to
choose from. Figure 7 - 2 lists the sixteen default memory configurations available under
the control of the BASIC language.

BANK

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

CONFIGURATION

RAM(0) only
RAM(1) only
RAM(2) only
RAM(3) only
Internal ROM, RAM(0), I/O
Internal ROM, RAM(1), I/O
Internal ROM, RAM(2), I/O
Internal ROM, RAM(3), I/O
External ROM, RAM(0), I/O
External ROM, RAM(1), I/O
External ROM, RAM(2), I/O
External ROM, RAM(3), I/O
KernaI and Internal ROM (LOW), RAM(0), I/O
Kernal and External ROM (LOW), RAM(0), I/O
Kernal and BASIC ROM, RAM(0), Character ROM
Kernal and BASIC ROM, RAM(0), I/O

Figure 7 - 2 . Bank Configuration Table

If you want to place a machine language subroutine in memory while the BASIC
language is running, put the subroutine in a bank that contains RAM, preferably bank 0
since this bank is composed entirely of RAM. If you place the machine language
subroutine in a bank other than 0, not all of the RAM is available for programs, since ROM overlays some of the RAM. You must check the value of the
Configuration Register within that bank to see which addresses within these banks
contain ROM. Check the value of the Configuration Register within each of the sixteen
configurations and compare the value with the table in Figure 13-5 to see exactly where
ROM maps in.
Follow this procedure when calling machine language subroutines from BASIC:

203

204

COMMODORE 128

1.

2.

Place the subroutine, preferably in bank 0, either through the monitor or by

POKEing in the code through BASIC. Jf the Kernal, BASIC, and I/O are
required, execute your program from configuration (BASIC Bank) 15. If you
enter the subroutine through the monitor, place the routine in bank 0 by
placing the digit 0 before the 4-digit hexadecimal address where the instructions are stored. If you are POKEing the codes in through BASIC (not the
preferred method), issue the BANK 0 command within your program, assuming you are placing the routine into BANK 0; then POKE in the decimal data
for the opcodes and operands. The recommended memory range to place
machine language routines in conjunction with BASIC is between $1300 and
$lBFF. The upper part of BASIC text is also available, provided your BASIC
program is small and does not overwrite your routine.
Now, to process the rest of your BASIC program, return to bank 15 (the
default bank) with this command:
BANK 15

3.

Now call the subroutine with the SYS command. SYS to the start address
where the first machine language instruction of your program is stored in
memory. In this case, assume the subroutine starts at hex location $2000
(assuming the VIC bit map screen is not used) and enter:
SYS 8192

The RAM in configuration 0 in Figure 7 - 2 is the same RAM that appears in configurations (BANKS) 4, 8, 12, 13, 14, and 15. For example, you can enter programs into
BANK 15, but you must make sure that no ROM overlays your program area.
N O T E : If you plan to return to BASIC, make sure your subroutine ends
with an RTS instruction.

WHERE TO PLACE MACHINE LANGUAGE

ROUTINES WHEN B A S I C IS DISABLED
When you are programming in machine language and you don't require the services of
the BASIC ROM, you can disable BASIC by mapping out the BASIC ROMs. Do this
by placing certain values into the Configuration Register in your own machine language
routines as follows:
LDA # $ 0 E
STA $D501
STA $FF01

;Set up the Configuration Register value

;Write to Preconfiguration Register A
;Write to LCR A to change value of CR

You can use this sequence:

LDA # $ 0 E
STA $FF00
When you switch out BASIC, the sixteen default configurations no longer exist

MIXING MACHINE LANGUAGE A N D BASIC

via the BASIC command, so it becomes your responsibility to manage the memory
configurations by manipulating the Configuration Register in your application program.
Figure 13-5, on page 462, defines the values to place in the configuration register to
arrive at the different memory configurations.
When you switch out the BASIC ROMs, the address range where BASIC usually
resides ($4000 through $7FFF for BASIC low and $8000 through $BFFF for BASIC
high), is available for your machine language programs. Be careful when switching out
the Kernal, since the Kernal controls the entire operation of the C128, including routines
that seem transparent to the user (i.e., routines that you may take for granted).
At certain points within your machine language programs, you may need to
disable the I/O operation of the C128 temporarily. For instance, if you want to copy
portions of the character ROM into RAM when programming your own characters, you
must switch out the I/O registers $D000 through $DFFF of the C128, transfer the
character data into RAM, and then switch the I/O back in.
See the section discussing the Configuration Register, in Chapter 13, for a full
explanation of how the C128 RAM and ROM memory is configured.
This chapter has described the use of BASIC and machine language together. For
material on using BASIC alone, see Chapters 2, 3 and 4. For material on using machine
language see Chapters 5, 6, 8, 9, 10, 11 and 13.

205

8
THE POWER
BEHIND
COMMODORE 128
GRAPHICS

207

208

COMMODORE 128

THE RELATIONSHIP BETWEEN

VIDEO BANKS, RAM BANKS
AND MEMORY CONFIGURATIONS
Many of you are familiar with how the Commodore 64 manages memory. This section
explains how the Commodore 128 manages video memory, and how the video banks
relate to the currently selected memory configuration.

MANAGING BANKED MEMORY

Banking is a process in which a section of memory is addressed by the microprocessor.
The memory is said to be banked in when it is available to the microprocessor in the
current memory configuration.
The Commodore 128 is programmable in its memory configuration. BASIC and
the Machine Language Monitor give you 16 pre-programmed default configurations of
memory (referred to in BASIC as banks). For the purposes of this discussion, BASIC
banks are referred to simply as default memory configurations which are combinations
of ROM and RAM in various ranges of memory. The current configuration, whether in
BASIC or machine language, is determined by the value in the configuration register of
the C128 Memory Management Unit (MMU) chip.
The sixteen different configurations in BASIC and the Machine Language Monitor
require different values to be placed in the configuration register so that particular
combinations of ROM and RAM can be banked into memory simultaneously. For
example, the character ROM is only available in memory configuration 14 (Bank 14 in
BASIC; the fifth digit hexadecimal prefix " E " in the Machine Language Monitor),
since this configuration tells the C128 MMU to swap out the I/O registers between
$D000 and $DFFF, and replace them with the character ROM. To swap the I/O
capabilities back in, change to any configuration number that contains I/O. Figure 8-1
lists the sixteen default memory configurations available in BASIC and the Machine
Language Monitor. Information on programming the MMU is contained in Chapter 13,
The Commodore 128 Operating System.

THE T W O 64K RAM BANKS

The Commodore 128 memory is composed of two RAM banks (labeled 0 and 1), each
having 64K of RAM, giving a total of 128K. The 8502 microprocessor address bus is 16
bits wide, allowing it to address 65536 (64K) memory locations at a time. Figure 8 - 2
illustrates the two separate 64K RAM banks.
Although only 64K can be accessed at one time, the MMU has provisions for
sharing up to 16K of common RAM between the two RAM banks. Common RAM is
discussed in Chapter 13.
The 8502 microprocessor and the VIC chip can each access a different 64K RAM
bank. The 8502 RAM bank is selected by the configuration register (bits 6 and 7) and

THE POWER BEHIND COMMODORE 128 GRAPHICS

BANK

CONFIGURATION

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

RAM(0) only
RAM(1) only
RAM(2) only (same as 0)
RAM(3) only (same as 1)
Internal ROM , RAM(0), I/O
Internal ROM , RAM(1), I/O
Internal ROM , RAM(2), I/O (same as 4)
Internal ROM , RAM(3), I/O (same as 5)
External ROM , RAM(0), I/O
External ROM , RAM(1), I/O
External ROM , RAM(2), I/O (same as 8)
External ROM , RAM(3), I/O (same as 9)
Kernal and Internal ROM (LOW), RAM(0), I/O
Kernal and External ROM (LOW), RAM(0), I/O
KernaI and BASIC ROM, RAM(0), Character ROM
Kernal and BASIC ROM, RAM(0), I/O

Figure 8 - 1 . C I 2 8 Default M e m o r y Configurations

64K

64K

Figure 8 - 2 . C I 2 8 64K R A M Banks

the VIC RAM bank is selected by the RAM configuration register (bits 6 and 7). This
also is covered in detail in Chapter 13.
The configuration determined by the configuration register can be composed of
RAM and ROM, where the ROM portion overlays the RAM layer underneath, as
illustrated in Figure 8-3.

209

210

COMMODORE 128

Write
Operation
(POKE, STA $

).

-READ Operation (PEEK, LDA $----)

ROM

ROM

RAM
65535
memory
Figure 8-3. ROM Overlay

A read (PEEK) operation returns a ROM value, and a write (POKE) operation
bypasses the ROM and stores the value in the RAM underneath.
Many different combinations of memory can be constructed to comprise a 64K
configuration of accessible memory. Bits six and seven of the configuration register
specify which RAM bank lies beneath the ROM layers specified by bits zero through
five. The underlying RAM bank can be switched independently of any ROM layers on
top. For instance, you may switch from RAM Bank 0 to RAM Bank 1, while
maintaining the Kernal, BASIC and I/O.

I6K VIDEO BANKS

In C128 graphics programming, a video bank is a 16K block of memory that contains
the essential portions of memory controlling the C128 graphics system: screen and
character memory. These two types of memory, which are discussed in the following
section, must lie within the 16K range of memory referred to as a (VIC) video bank.
The VIC chip is capable of addressing 16K of memory at any one time, so all graphics
memory must be present in that 16K. Since the Commodore 128 microprocessor
addresses 64K at a time, there are four video banks in each 64K RAM bank, or a total
of eight video banks. (See Figure 8 ^ . )
Where you place the VIC video bank depends on your application program. The
Commodore 128 ROM operating system expects this bank in default video Bank 0, in
the bottom of RAM Bank 0. Screen and character memory may be located at different
positions within each 16K video bank, though in order to successfully program the VIC
chip, the current 16K bank must contain screen and character memory in their entirety.
You'll understand this after reading the next few pages.

THE POWER BEHIND COMMODORE 128 GRAPHICS

video bank 3

video bank 2

video bank 1

video bank 0

3
2

video bank 3
video bank 2

video bank 1

video bank 0

64K

64K

Figure 8 - 4 . Video Banks within R A M Banks

The four video banks in each 64K RAM bank are set up in the memory ranges
specified in Figure 8-5:
BANK

ADDRESS RANGE

0
1
2
3

$0-$3FFF
$4000-$7FFF
$8000-$BFFF
$C000-$FFFF

VALUE OF BITS 1 & 0 IN $DD00

BINARY DECIMAL

11=
10=
01=
00=

3 (DEFAULT)
2
1
0

Figure 8 - 5 . Video Banks M e m o r y Ranges

Each RAM bank (0 and 1) has this memory layout.

Bits 0 and 1 of location $DD00 select the video bank. To select a video bank in
BASIC, type this command:
POKE 56576, (PEEK(56576) AND 252) OR X
Where X is the decimal value of bits 1 and 0 in Figure 8-5.
In machine language, run the following program segment to select video banks:
LDA $DD00; load the accumulator with contents of $DD00
AND # $ F C ; preserve the upper 6 bits of $DD00
ORA # $ X ; where X is the hex value of bits 1 and 0 from Figure 8 - 5 above
STA $DD00; Place the value in $DD00

211

212

COMMODORE 128

In the third instruction, replace X with the hexadecimal value of bits 1 and 0 in
Figure 8-5. The default value is $03, which selects video bank zero.
Whenever you change video banks, you must add $4000 to the address of your
starting screen memory (video matrix) and character memory (bit map in bit map mode)
for each bank above 0. To change to video Bank 1, add $4000 to your starting screen
and character address; for Bank 2 add $8000; for Bank 3 add $C000. You must always
add an offset of $4000 to the start of your screen and character memory for each video
bank that is greater than zero.

SUMMARY OF BANKING CONCEPT

The major features of the banking concept can be summarized as follows:
1.

BASIC and the Machine Language Monitor have sixteen 64K memory configurations that give you sixteen different combinations of memory layouts.
The MMU chip, particularly the value in the configuration register, controls
most of the memory management in the Commodore 128. In order to PEEK
(read) from or POKE (write) to a particular portion of memory, you must
choose a BASIC or monitor configuration that contains the desired section of
memory. Figure 8 - 1 lists the sixteen default memory configurations available
in BASIC and the Machine Language Monitor.

2.

The 128K of memory is divided into two 64K RAM banks. Only one bank is
addressable at a time by the microprocessor. RAM bank selection is controlled by the MMU configuration register (bits 6 and 7), which is part of the
C128 I/O memory. The VIC chip and 8502 microprocessor can each access a
different 64K RAM bank. Figure 8 - 2 illustrates the two separate and independent 64K RAM banks.
Each 64K RAM bank is divided into four 16K video segments. The screen
and character memory must both lie within the selected 16K video segment in
order to successfully display graphics and characters on the screen. For each
16K video bank higher than zero, remember to add $4000 (16384 decimal) to
the start address of screen and character memory. Figure 8^4 shows how four
16K video banks fit into each of the two 64K RAM banks.

3.

Here's how the banks fit together and operate within the Commodore 128. One
64K RAM bank is always mapped into memory. Within BASIC or the Machine
Language Monitor, sixteen different memory configurations are available in a 64K bank.
To change the configuration, issue the BASIC BANK command, or precede the four
digit hexadecimal address in the Machine Language Monitor with an additional hexadecimal digit 0 through F. Outside of BASIC or the monitor, you can select other
configurations, by changing the value in the configuration register at location $FF00
(or $D500). See Chapter 13 for details.
Within the selected configuration, and part of the current 64K RAM bank, is a
16K range reserved for a video bank. The 16K video bank must encompass lK of screen
memory, and either 4K of character ROM or an 8K block of memory for the bit map
data. All these components must be present in order for graphics to operate.

THE POWER BEHIND COMMODORE 128 GRAPHICS

In essence, the bank concept can be thought of in this way: The C128 has a 16K
(VIC) video bank within a selected memory configuration within a 64K RAM bank.
Figures 8-28 through 8-32 at the end of this chapter provides a graphics programming summary.

SHADOW REGISTERS: INTERMEDIATE STORAGE

LOCATIONS USED BY THE CI28 SCREEN EDITOR
Users who are experienced in programming the Commodore 64 VIC chip will find that
most of the graphics operations of the Commodore 128 are performed in the same way
as the C64. The main difference between the Commodore 64 and the Commodore 128
graphics systems is the hardware implementation of split-screen modes.
C128 mode provides two types of split-screen displays:
1.
2.

Standard character mode and bit map mode

Standard character mode and multi-color bit map mode

Because the split-screens switch from one display mode to another at a given
time, the screen editor must be interrupt-driven. The interrupt indicates at what point
the mode is to be switched. At that point, the VIC chip is loaded with preset values
already contained in RAM. These preset values are known as shadow registers. Each
time an interrupt occurs, certain video-chip registers are cleared and refreshed with the
values in the shadow registers. These shadow registers add a variation in programming
the VIC chip compared to the way the Commodore 64 handles it.
The primary intermediate storage locations for VIC chip programming are:

NAME

INDIRECT LOCATION

ACTl AL LOCATION

DESCRIPTION

GRAPHM

BIT 7 - 216 ($00D8)

BIT 4 - 53270 ($D016)

Multicolor Mode Bit

GRAPHM

Bit 6 - 216 ($00D8)

GRAPHM

BIT 5 - 216 ($00D8)

BIT 5 - 53265 ($D011)

Bit Map Mode Bit

VM1*

BITS 7-4 - 2604 ($0A2C)

BITS 7-4 - 53272 ($D018)

Video Matrix (screen memory) Pointer

VM1

BITS 3-0 - 2604 ($0A2C)

BITS 3-0 - 53272 i$D018)

Character Base Pointer

VM2**

BITS 7-4 - 2605 ($0A2D)

BITS 7-4 - 53272 ($D018)

Video Matrix (screen memorv) Pointer

VM2

BITS 3-0 - 2605 ($0A2D)

BITS 3-0 - 53272 ($D018)

Bit Map Pointer

Split Screen Bit

* V M 1 applies o n l y to standard and m u l t i - c o l o r character (text) m o d e s .

* * V M 2 applies o n l y to standard a n d m u l t i - c o l o r bit m a p m o d e s .

213

214

COMMODORE 128

You must store to and load from the indirect locations when accessing the above
features of the VIC (8564) chip. For example, in C64 mode, this is how you set up the
video matrix and bit map mode:
10 POKE 53272, 120: REM Select bit map @ 8192, video matrix @ 7168
20 POKE 53265, PEEK(53265) OR 32: REM Enter bit map mode
Line 10 sets the video matrix at 7168 ($1C00) and the bit map at 8192 ($2000).
Line 20 enables bit map mode.
Normally, you would perform this operation with the high-level, 7.0 BASIC
command:
GRAPHIC 1
The comparable way to accomplish this with POKE commands in C128 mode is
as follows:
10 POKE 2605,120
20 POKE 216,PEEK(216) OR 32
In C128 machine language, use these instructions:
LDA #$78; set bit map @ $2000
STA $0A2D; set video matrix @ 7168
LDA $00D8
ORA # $ 2 0
STA $00D8; select bit map mode
Although these examples do more than just select bit map mode and set up the
video matrix and bit map pointer (such as wait on a video retrace when the raster is off
the visible coordinate plane), these examples give you an idea of how to perform these
programming steps.
As you can see, C128 mode requires a slight variation in programming the VIC
chip. You must keep this in mind when programming graphics in C128 mode. Usually,
the high-level BASIC 7.0 commands take care of these variations. However, if you are
programming in machine language, remember to address these indirect storage locations
and not the actual ones. If you store values directly to the actual registers, the value will
be cleared in a jiffy and no apparent action occurs.

DISABLING THE INTERRUPT DRIVEN

SCREEN EDITOR
You can disable the interrupt-driven C128 screen editor by storing the value 255
($FF) in location 216 ($00D8). The actual VIC registers are not affected, and you
can program the VIC chip the same way as the C64. This makes it unnecessary to
address the indirect shadow registers. In BASIC, enter:
POKE 216,255
In machine language, you enter:

THE POWER BEHIND COMMODORE 128 GRAPHICS

LDA # $ F F
STA $00D8
Since disabling the interrupt allows you to program the VIC chip in the same way
as the Commodore 64, you can store values directly to the actual registers. You do not
have to address the indirect storage locations for VIC chip programming. However, if
you don't disable the interrupt, it is still active and your values will be cleared upon the
first occurrence of the raster interrupt.
Remember, you must either disable the interrupt or address the indirect storage
locations. Failure to do one or the other can cause serious problems in your program.
The 80-column chip indirect memory locations are discussed in Chapter 10,
Programming the 80-Column 8563 Chip. Certain other I/O functions require the use of
indirect locations also. These are covered in Chapter 12, Input/Output Guide.

THE COMMODORE 128

GRAPHICS SYSTEM
This section describes where the SCREEN, COLOR and CHARACTER memory components in the graphics system are located in character modes and bit map modes.
Screen and character memory are addressed and stored differently in the character
modes than in the bit-map modes. The split-screen modes use a section of both the
character screen storage and the bit map screen storage.
In graphics operations, the C128 can operate in either BASIC or machine language
in both C128 and C64 modes.
This section tells you where the graphics locations and screen color character
memory are stored under each graphic mode. The next section details the inner workings
of each graphic display mode including how color and data are assigned and how
screen, color and character memory are interpreted.

SCREEN MEMORY (RAM)

The location in which screen RAM is stored in memory and the way the data are stored
within it depends on the current graphics mode and operational mode of the C128.

CI28 BASIC
In Commodore 128 BASIC, the character screen memory is located in the default address
range 1024 ($0400) through 2023 ($07E7). The text screen memory can be moved.
Remember, certain address6s use indirect memory locations to change the value of the
actual address. The shadow register for the pointer to the text screen memory is location
2604 ($0A2C). The actual location is 53272, but the screen editor uses a shadow since
the VIC screen is interrupt-driven. A direct poke to 53272 ($D018) is changed back to
its original value every sixtieth of a second. Here's how to change the location of screen
memory in C128 BASIC:

215

216

COMMODORE 128

POKE, 2604 (PEEK(2604) AND 15) OR X

where X is a value in Figure 8-6.
If you move the screen memory, make sure that the screen and character memory
do not overlap. In addition, make sure to add an offset of $4000 to the start address of
screen and character memory for each bank above 0. Additional commands are required
to make the program work. Details follow in the discussion of each graphic mode, as
well as program examples.

L O C A T IO N*

BITS

0
16
32
48
64
80
96
112
128
144
160
176
192
208
224
240

ooooxxxx
0001XXXX
0010XXXX
0011XXXX
0100XXXX
0101XXXX
0110XXXX
0111XXXX
1000XXXX
1001XXXX
1010XXXX
1011XXXX
1100XXXX
1101XXXX
1110XXXX
llllXXXX

DECIMAL

0
1024
2048
3072
4096
5120
6144
7168
8192
9216
10240
11264
12288
13312
14336
15360

HEX

$0000
$0400 (DEFAULT)
$0800
$0C00
$1000
$1400
$1800
$1C00
$2000
$2400
$2800
$2C00
$3000
$3400
$3800
$3C00

*Remember that the BANK ADDRESS offset of $4000 per

video bank must be added if changing to a higher video
bank above 0.
Figure 8^>. Screen M e m o r y Locations

This register also controls where character memory is placed in memory. The
upper four bits control the screen, the lower four control character memory. The " A N D
15" in the POKE 2604 statement ensures that the lower nybble is not upset. (If it had
been, you would not see the correct character data.)
In Commodore 128 bit map mode (standard or multi-color), the default bit map
screen memory (video matrix) is located between 7168 ($1C00) and 8167 ($lFFF).
Screen memory is interpreted differently in bit map mode than in text mode. The video
matrix in bit map mode actually supplies color information to the bit map. This is
explained in detail in the Standard Bit Map Mode section elsewhere in this chapter. To
change the location of the bit map screen memory (video matrix), use this command:
POKE 2605, (PEEK(2605) AND 15) OR X

T H E P O W E R B E H I N D C O M M O D O R E 128 G R A P H I C S

where X is a value in Figure 8-6. Location 2605 is also a shadow register for 53272, but
only for bit map mode. When you move the video matrix you must ensure that it does
not overlap the bit map (data). In addition, be sure to add an offset of $4000 to the start
address of the video matrix and the bit map for each video bank above zero.

C64 BASIC
In C64 mode, the text screen defaults to locations 1024 ($0400) through 2023
($07E7). In bit map mode, the video matrix (screen memory) also defaults to this range
though the screen memory is interpreted differently in either mode. Commodore 64
BASIC allows you to move the location of the video matrix to any one of the sixteen
locations specified in Figure 8-6. The upper four bits of location 53272 ($D018) control
the location of the screen memory. To change the location of screen memory, use the
following command:
POKE 53272, (PEEK(53272) AND 15) OR X
where X is equal to one of the values in Figure 8 - 6
NOTE: The following paragraph pertains to both C128 and C64 modes.

Bits zero and one of location 56576 ($DD00) control which of the four video
banks is selected. The default bank is 0. If you change to another video bank (from 0 to
1, for example), then for each bank higher than bank zero, you must add an offset of
$4000 to the starting video matrix (screen memory) address in Figure 8-6. This yields
the actual address of the video matrix. For example, if you're changing from bank 0 to
bank 1, add $4000. If you are going to bank 2, add $8000; if you are changing to bank
3, add $C000. Remember, this is true for both C128 and C64 modes.

MACHINE LANGUAGE
In machine language, use the commands listed underA in Figure 8 - 7 to move the C128
(VIC) text screen. Use the commands underZ? to move the C128 bit map screen memory
(video matrix). Use the commands under C to move the C64 text or bit map screen
memory (video matrix).

(A)

(B)

(C)
MOVE C64

iMOVE C128

MOVE C128

TEXT OR BIT MAP

TEXT SCREEN

BIT MAP SCREEN

SCREEN MEMORY

LDA $0A2C
AND #$0F
ORA#$X
STA $0A2C

LDA $0A2D
AND #$0F
ORA #$X
STA $0A2D

LDA $D018
AND #$0F
ORA #$X
STA $D018

Figure 8-7. Moving Screen Memory in Machine Language

217

218

COMMODORE 128

In Figure 8 - 7 , X is the hexadecimal equivalent of the decimal value X in the left

column in Figure 8-6. The second and third instructions in each example in Figure
8 - 7 make sure not to upset the lower four bits of location 53272 or its shadow registers,
2604 ($0A2C) and 2605 ($0A2D), since they control the character data for text and bit
map modes.

COLOR RAM
CI28 BASIC
Color RAM within the Commodore 128 is always stationary in memory. It occupies the
address range 55296 ($D800) through 56295 ($DBE7). In standard character mode,
screen RAM and color RAM correspond to one another on a one-to-one basis. Location
1024 gets color data from 55296, 1025 gets color from 55297 and so on. Multi-color
character mode utilizes color RAM also, but in a different manner. Additional explanations and examples are provided in the Standard Character Mode section of this chapter.

COLOR RAM BANKING

In C128 mode, the LORAM and HIRAM signal lines allow the graphics system to
make use of an additional Color RAM bank, which is not available in C64 mode. This
allows fast and clean switching of colors for the character or multi-color bit map screen.
The LORAM signal line allows the 8502 microprocessor to access one color RAM
bank, while the HIRAM control line allows the VIC chip to access either Color RAM
bank independently of the microprocessor. Bit 0 of location 1 controls the LORAM
signal line. LORAM selects color RAM bank 0 or 1 as seen by the 8502 microprocessor
depending on the value of the bit. If the bit value is low, the color RAM bank 0 is
accessed by the 8502. If the value of the bit is high, the upper color RAM bank is
accessed by the 8502 microprocessor.
Bit 1 of location 1 controls the HIRAM signal line. HIRAM selects color RAM
bank 0 or 1 as seen by the VIC chip, depending on the value of the bit. If the bit value is
low, the color RAM bank 0 is accessed by the VIC chip. If the value of the bit is high,
the upper color RAM bank 1 is accessed by the VIC chip.
These control lines add flexibility to the already powerful C128 graphics system.
This allows you to change colors of the multi-color bit map or character screen on the fly,
without any time delay. It allows you to swap color RAM banks instantly.
In standard bit map mode, color information is obtained from the bit map
screen memory (the video matrix, $1C00 through $lFFF), not color memory. Bit
map mode interprets screen memory differently than character mode. Color RAM
is used in standard character mode, multi-color bit map mode, multi-color character
mode and the split-screen mode.

C64 BASIC
In standard character mode, color RAM is located in the same place as in C128 mode:
55296 ($D800) through 56295 ($DBE7).
In bit map mode, C64 BASIC receives color information from screen memory (the

THE POWER BEHIND COMMODORE 128 GRAPHICS

video matrix) as does C128 mode, though the default location for screen memory is
1024 ($0400) through 2023 ($07E7).

MACHINE LANGUAGE
In machine language or in BASIC, standard character mode color data always comes
from the same place. Color RAM is used for multi-color character mode. In
standard bit map mode, however, color data originates from screen memory, so wherever you place screen memory, the color data for the bit map comes from the specified
screen memory (video matrix) range. Multi-color bit map mode receives color from three
places: color RAM, screen memory and background color register 0. This is explained in
depth in the sections on the multi-color character and multi-color bit map modes.

CHARACTER MEMORY (ROM)

CI28 BASIC-CHARACTER MODES
In standard character mode, character information is stored in the character ROM in the
memory range 53248 ($D000) through 57343 ($DFFF). In location 1 of the Commodore 128 memory map, the CHAREN (CHARacter ENable) signal determines whether
the character set is available in any given video bank (0-3). Bit 2 of location 1 is the
CHAREN bit. If the CHAREN bit is high (1), the Commodore character set is not
available within the currently selected video bank in context. If the value of bit 2 in
location 1 is low, equal to zero, then the C128 character set is available in the currently
selected video bank. This is true in any of the four video banks in both 64K RAM
banks. This feature allows the Commodore 128 character set to be available in any video
bank at any time. To read the character ROM, enter BANK 14 either in BASIC or the
MONITOR, and read the ROM, starting at location 53248. This configuration switches
out I/O, and maps in character ROM in the range $D000 through $DFFF. Figure 8 - 8
shows how the character sets are stored in the character ROM:

ADDRESS
BLOCK

DECIMAL

53248
53760
54272
54784
55296
55808
56320
56832

vic*
HEX

IMAGE

CONTENTS

D000-D1FF
D200-D3FF
D400-D5FF
D600-D7FF
D800-D9FF
DA00-DBFF
DC00-DDFF
DE00-DFFF

1000-11FF
1200-13FF
1400-15FF
1600-17FF
1800-19FF
1A00-1BFF
IC00-1DFF
1E00-1FFF

Upper case characters

Graphics characters
Reversed upper case characters
Reversed graphics characters
Lower case characters
Upper case & graphics characters
Reversed lower case characters
Reversed upper case & graphics
eharaeters

* = in C64 mode only

Figure 8-8. Breakdown of Character Set Storage in Character ROM

219

220

COMMODORE 128

The character memory is relocatable as is screen memory. To move standard

character memory in C128 BASIC, alter the lower four bits (nybble) of location 2604
($0A2C). Location 2604 is a shadow register for 53272 for the text screen memory
(upper four bits) and character memory (lower four bits). To move the standard
character memory use the following command:
POKE 2604, (PEEK(2604) AND 240) OR Z.
where Z is a value in Figure 8-9.

LOCATION

OF C H A R A C T E R

MEMORY

VALUE
OFZ

BITS

DECIMAL

HEX

0
2
4

xxxxooox
XXXX001X
XXXX010X

0
2048
4096

$0000-$07FF
$080a-$0FFF
$1000-$17FF

6
8
10
12
14

XXXX011X
XXXX100X
XXXX101X
XXXX110X
XXXXlllX

6144
8192
10240
12288
14336

$1800-$lFF
$2000-$27FF
$2800-$2FFF
$3000-$37FF
$3800-$3FFF

ROM IMAGE in BANK 0 & 2

(defauIt)*
ROM IMAGE in BANK 0 & 2*

* = in C64 mode only.

Figure 8 - 9 . Character M e m o r y Locations

As with the other graphic system components, character data behaves differently in
bit map mode than in text mode.
Remember, the upper nybble controls where the screen memory maps in, so make
sure not to upset those bits. The AND 240 in the POKE statement above takes care of
preserving the upper four bits.
In C128 mode the character sets are available in all video banks depending on the
value of CHAR ENable

NOTE: Remember to add an offset of $4000 to the start address of

character memory, for each bank above 0; i.e., for bank 3 add
3*$4000 = $C000

THE POWER BEHIND COMMODORE 128 GRAPHICS

CI28 BASIC-BIT MAP MODES

In bit map mode, the character memory data, also referred to as the bit map, defaults to
the range 8192 ($2000) to 16191 ($3F3F). The bit patterns of these 8000 bytes tell the
computer which pixels to turn on. This block of memory " m a p s o u t " the picture on the
screen, according to the data in this 8000-byte block. Since the standard bit map screen
is 320 x 200, 64000 pixels make up the screen image. Divide 64000 by 8 to arrive at
8000 bytes of memory for the bit map.
Besides the upper four bits for the video matrix, bit 3 of location 2605 ($0A2D) is
the only significant bit in bit map mode. Location 2605 is the indirect memory location
of 53272 for bit map mode only.
When you issue the G R A P H I C 1 command, bit 3 in 2605 is set. This specifies
the bit map (data) to start at location 8192 ($2000). Whenever you enter bit map mode
with the GRAPHIC command, bit 3 is always set. Outside of BASIC, you can specify
the bit map to start at location $0000; therefore, the value of bit 3 is zero.
If the C128 is running under the control of C128 BASIC, the bit map always starts
on a boundary of $2000 (since bit 3 is set) within a given video bank. In video bank
zero, the bit map starts at $2000. For banks 1, 2 and 3, the bit map begins at $6000,
$A000 and $E000, respectively, since you must add an offset of $4000 for each bank
number above zero. In machine language, however, bit 3 may have a value of zero or
one. Therefore the bit map may start at $0000 if bit 3 is zero, or at $2000 if bit 3 is one,
in each video bank. This means that the bit map has eight possible starting locations
(per 64K RAM bank) in machine languagetwo for each of the four video banks. In
C128 BASIC, the bit map can only start at one of the four locations.
Don't forget to add the mandatory $4000 offset for each video bank above 0. The
eight possible starting locations of a bit map in a machine language program are shown
in Figure 8 - 1 0 .
This gives you the choice of eight starting locations in which to place your bit map
data. Though only one bit map can fit in each video bank, you must leave room for the
video matrix. Since the C128 has two RAM bankseach with four video banks per
RAM bankyou may have a total of eight bit maps in memory, one for each video
bank. Each video bank can fit only one bit map, because you need l K for screen RAM,
and 8K for the bit map since a video bank has a maximum of 16K. To access another bit
map, you must switch video banks. To access a bit map in the upper RAM bank (1),
you may have to switch RAM banks and video banks.

VIDEO BANK

0
1
2
3

VALUE OF BIT 3 =

0
$0000
$4000
$8000
$C000

1
$2000
$6000
$A000
$E000

Figure 8-10. Starting Locations for Bit Map in Machine Language

221

222

COMMODORE 128

C64 BASIC-CHARACTER MODES

In standard character mode in C64 BASIC, the lower four bits of location 53272 control
where character memory is placed. As in C128 mode, the character ROM is actually
mapped into memory between 53248 ($D000) and 57343 ($DFFF). The ROM image
appears in RAM in the range 4096-8191 (in video bank 0) and 3 6 8 6 4 ^ 0 9 5 9 in bank 2,
since it must be accessible to the VIC chip in a 16K range in video banks 0 and 2. The
character sets are not accessible in video banks 1 and 3. This ROM imaging in RAM
applies only to character data as seen by the VIC chip. These memory ranges are still
usable for data and programs and have no effect on the contents of RAM as far as your
programs are concerned.
In C64 mode, the ROM image overlays the RAM underneath. A write operation
"bleeds through" to the RAM underneath, while a read returns a ROM value depending
on which memory configuration is currently in context. Since the VIC chip accesses
16K at a time, the character set images must appear in the 16K which the VIC chip is
currently addressing in video banks 0 and 2. Remember, in C128 mode, the character
sets are available in all video banks according to the value of the CHAREN bit in
location 1.
You can change the location of character memory with the following command:
POKE 53272, (PEEK(53272) AND 240) OR Z
where Z is a decimal value in the table in Figure 8-9.
The breakdown of the character sets is the same as in the C128 for the character
ROM (see Figure 8-8).

C64 BASIC BIT MAP MODE

In bit map mode, bit 3 of location 53272 specifies the start of the bit map either at
$0000 or $2000 depending whether the value of bit 3 is 0 or 1, respectively. Use the
following command:
POKE 53272 (PEEK (53272) AND 240) OR Z
where Z is zero if you want the bit map to start at $0000 in each bank, or Z = 8 if you
want to place the bit map starting at 8192 ($2000) in each video bank.
See Figure 8-10 for the arrangement of the bit map in each of the four 16K video
banks within the two RAM banks. If you switch video banks, don't forget to add the
$4000 (hex) offset for each bank above 0. See the Character Memory section under
C128 Bit Map Mode in the last section for more detail on the arrangement of bit maps in
memory.

THE POWER BEHIND COMMODORE 128 GRAPHICS

MACHINE LANGUAGE
There are three ways to select the placement of character memory, as shown in Figure
8-11. Example A places character memory using the shadow register $0A2C in place of
the actual $D018 register. Example B specifies the start of the bit map at $2000 (using
shadow register $0A2D). Example C specifies the start of the C64 bit map or character
memory.

LDA $02AC
AND #$F0
ORA #$Z
STA $02AC

LDA $02AD
AND #$F0
ORA #$08
STA $02AD

LDA $D018
AND #$F0
ORA #$Z
STA $D018

Figure 8-11. Selected Character Memory Location

In Figure 8-11, Z is a value in the table in Figure 8-9.

STANDARD CHARACTER MODE

HOW T O ENTER STANDARD
CHARACTER MODE
The C128 powers up in standard character mode. This mode displays characters on the
default screen. The character is displayed in a single color on a single color background.
This is the mode in which you write (enter) programs. When you press RUN/STOP and
RESTORE, the C128 defaults to the text screen.
Location 53265 (and its shadow register $00D8) determine whether the C128 is
operating in standard character mode. If bit 5 is 0, as it is on power-up, the C128 is in
character mode; otherwise it is in bit map mode.
Location 53270 (and its shadow register $00D8) determine whether the characters
are standard (single color) or multi-color. Bit 4 of 53270, and the shadow bit, bit 7 of
$00D8, specify multi-color mode. If these bits are equal to zero, characters are standard;
otherwise they are multi-color. See the Multi-color Character Mode section for more
details on selecting multi-color character mode.

223

224

COMMODORE 128

SCREEN LOCATION
In standard character mode, the screen memory defaults to the range 1024 ($0400) through
2023 ($07E7). This is relocatable. See the Screen Memory section in the preceding pages.
Since the screen is 40 columns by 25 lines, the text screen requires 1,000 memory
locations to store all of the screen information in memory. The final twenty-four memory
locations in screen memory do not store displayed data; they are used for other purposes.
Each column of every row you see on the screen has its own screen memory location.
The top-left screen location, referred to as HOME, is stored at address 1024 ($0400).
The second screen location marked by the cursor is 1025 ($0401), and so on. Although
the screen you see is constructed in rows and columns, the screen memory within the
computer is stored linearly, starting at 1024 ($0400) and ending at location 2023 ($07E7).
Figure 8-12 shows a screen memory map, so you can visualize how a screen memory
location corresponds to the location on the physical screen of your video monitor.
SCREEN M E M O R Y M A P
COLUMN

10

20

30
1063
*

1024
1064
1104
1144
1184
1224
1264
1304
1344
1384
1424
1464

*-

10

1584
1624
1664
1704
1744
1784
1824
1864
1904
1944
1984
t

2023
Figure 8-12. Screen M e m o r y Map

HOW THE SCREEN MEMORY DATA

IS INTERPRETED
This screen memory range stores whole characters only. The characters are not represented as ASCII character string codes (CHR$). Instead, they are stored in memory as
screen codes as shown in Appendix D. The screen codes and character string codes are

THE POWER BEHIND COMMODORE 128 GRAPHICS

different due to the way they are stored in the character ROM. Notice in Appendix D
that the screen code for an at-sign (@) is 0. The @ is numbered 0 because it is the first
character to be stored in the character ROM. The letter " A " is the second character
ROM; therefore its code is 1. The letter " B " is the third character in the character
ROM, etc. The screen code is actually an index from the starting location of the
character ROM, beginning with zero.
Jf you want to POKE a character directly into screen memory, use the screen code
rather than the ASCII character string (CHR$) code. The same holds true for the
machine language monitor. For example:
POKE 1024,1
places the letter A in the HOME position on the VIC screen. From the monitor, placing
the value 1 in location $0400 (decimal 1024) also displays the letter A in the HOME
position on the VIC screen.

COLOR DATA
In standard character mode, color information comes from color RAM, in the address
range 55296 ($D800) through 56295 ($DBE7). This memory determines the color of the
characters in each of the 1,000 screen locations. The background color of the screen is
determined by the background color register 0 which is location 53281.
The color RAM and the screen RAM locations correspond on a one-to-one basis.
Screen location 1024 pertains to color RAM location 55296; screen location 1025
corresponds to color location 55297, etc. Figure 8 - 1 3 is the color RAM memory map.
The map shows how color RAM corresponds to the locations in screen RAM and the
placement on your video display.
COLOR MEMORY MAP
C0lUMN

10

20
55335

t
55296UlJl
55336
55376
55416
__J
55456
55496
55536
55576
_TI
5i-J55616
1
|
55656
fI
TTj
TI_
55696
n_
;
JI_
55736
j| ;n
||
55776
]
j
55816
{
|
55856
_T
j"
55896
Jl
I
TjZ
55936
TTTI
"
55976
ZT
ZU J
56016
jf
|
'
56056
Jl
56096
J~
'
56136
'
56176
__3
56216
;
56256
7TT
Figure 8-13. Color Memory Map

10 o

56295

225

226

COMMODORE 128

HOW COLOR MEMORY IS

INTERPRETED
The contents of the color RAM locations contains the color codes 0-15. Each color
memory location may have a different color code. The lower four bits (nybble) of
COLOR RAM are significant. Figure 8-14 shows the COLOR RAM color codes:

0 Black
1 White
2 Red
3 Cyan
4 Purple
5 Green
6 Blue
7 Yellow

8 Orange
9 Brown
10 Light Red
11 Dark Gray
12 Medium Gray
13 Light Green
14 Light Blue
15 Light Gray

Figure 8-14. Color Codes^40 Columns

Notice these color code values are one less than the color codes used by the
keyboard and BASIC. If you want to store a value directly into COLOR RAM, store the
values in the table above, not the color codes used by BASIC and the keyboard. For
example:
POKE 55296,1
colors the character in the HOME position white. From the monitor, place the value 1 in
location $D800, and the same results occur.
Remember, these color codes only control the color of the foreground character.
The background color is controlled by background color register 0 (53281). The pixels
that make up the character image are enabled by bits in character memory. If the bit is
enabled, the pixel in the foreground is turned on in the foreground color, and is
therefore controlled by color RAM. If the bits making up the character are turned off,
they default to the color in background color register 0. The combination of on and off
bits makes up the image of the character. The value of these bits determines whether the
color data comes from color RAM or background color register 0. You'll learn more
about character patterns in the next few paragraphs.

CHARACTER MEMORY
In standard character mode, the C128 receives character data from the CHARACTER
ROM. The character ROM is stored in the range 53248 ($D000) through 57343
($DFFF). Since the VIC chip is capable of accessing 16K at a time, the C128 needs a
way to have the character ROM available in the 16K VIC range. In C128 mode, the
character ROM is available in any VIC bank in C128 mode, based on the value of

T H E P O W E R B E H I N D C O M M O D O R E 128 G R A P H I C S

CHAREN. See the chapter set availability in the Character Memory section in the
beginning of this chapter.
In C64 mode the character ROM is available only in banks 0 and 2. This is
accomplished by having a ROM IMAGE of the character ROM (53248-57343) mapped
into memory in place of RAM, in the range 4096-8191 ($1000-$lFFF) in video BANK
0, and 3 6 8 6 4 ^ 0 9 5 9 ($9000-$9FFF) in video BANK 2. In banks 1 and 3, the character
ROM is not available to the VIC chip.
Notice that the range where the character ROM is actually stored (53248-57343)
is also occupied by the I/O registers but not at the same time. When the VIC chip
accesses the character ROM, the character ROM is switched into the currently selected
video bank as a ROM image (in C64 mode only). When the character ROM is not
needed, the I/O registers are available in the usual range. It is important to note the
ROM image applies only to the character data as seen by the VIC chip. The RAM locations where the ROM image maps in are still usable for programs and data. The locations
where the VIC chip looks for the character data are relocatable. See the Character
Memory section elsewhere in this chapter for information on moving character memory.

HOW T O INTERPRET CHARACTER MEMORY

IN STANDARD CHARACTER MODE
Typically, a complete character set contains 256 characters. The C128 contains two sets
of characters, for a total of 2 times 256 or 512 characters. In 40-column (VIC) output,
only one character set is available at a time. Upon power-up, the uppercase/graphics
character set is available through the keyboard. To access the second character set, press
the Commodore key ( & ) and shift key at the same time. The second character set is
composed of the upper- and lowercase/graphics characters.
In character ROM, each character requires eight bytes of storage to make up the
character pattern. Since 256*8 is equal to 2048 bytes or 2K, and since there are two
character sets, the C128 has a total of 4K of character ROM. Figure 8-15 shows where
each character set is stored in the character ROM.

ADDRESS
BLOCK

DECIMAL

53248
53760
54272
54784
55296
55808
56320
56832

HEX

VIC-II
IMAGE

D000-D1FF
D200-D3FF
D400-D5FF
D600-D7FF
D800-D9FF
DA00-DBFF
DC00-DDFF
DE00-DFFF

1000-11FF
1200-13FF
1400-15FF
1600-17FF
1800-19FF
1A00-1BFF
1C00-1DFF
1E00-1FFF

CONTENTS

Upper case characters

Graphics characters
Reversed upper case characters
Reversed graphics characters
Lower case characters
Upper case & graphics characters
Reversed lower case characters
Reversed upper case & graphics
characters

Figure 8-15. Location of Character Sets in Character ROM

227

228

COMMODORE 128

Note that there is really 8K of character ROM4K for C64 mode and 4K for
C128 mode. The system automatically selects the appropriate character ROM for each
mode of operation.
The bit patterns stored in the character ROM have a direct relationship to the
pixels on the screen, where the character is displayed. In memory, each character
requires eight bytes of storage. On the screen, a character is made up of an 8 by 8 pixel
matrix. Think of a character as eight rows of eight pixels each. Each row of pixels
requires one byte of memory, so each pixel requires one bit.
Since a character is an 8 by 8 pixel matrix, each character requires a total of 64
bits or eight bytes. Within each byte, if a bit is equal to 1, the corresponding pixel in
that character position is turned on. If a bit in a character ROM byte is equal to 0, the
corresponding pixel within the character on that screen position is turned off. The
combination of on and off pixels creates the image of the characters on the screen.
Figure 8 - 1 6 demonstrates the correspondence between a character on the screen and the
way it is represented in the character ROM.

60
102
110
110
96
98
60
0
Character on
the Screen

Byte 1 -+
Byte 2 ^
Byte3^
Byte 4 ^
Byte 5 ^
Byte 6 ^
Byte 7 ^
Byte 8 ^

0_ 0 JL 1 1 JL 0 _0
0_ J_ jL V _0 jL JL JO
0_ J_ JL 0_J_ J_ J_ 0
0_ 1 JL 0_ JL JL jL 0_
0 J_ jL 0_ 0_ 0_5 _0
0_ J_ JL 0_ _0_ 0_ jL _0
0 0 JL T J_ jL 0L 0
0 ^cT 0 0 0 0 0 ~0

=
=
=
=
=
=
-

$D000
$D001
$D002
$D003
$D004
$D005
$D006
$D007

Character as
Represented
in Character ROM

Figure 8-16. Relationship of Screen Character to Character ROM.

In Figure 8 - 1 6 , the first eight bytes of character ROM, ($D000-$D007) are equal
to 60,102,110,110,96,98,60 and 0. These decimal numbers are calculated from the
binary value of the eight bytes that pertain to each row of pixels in the character. For
each bit that is equal to one, raise two to the bit position (0-7). For example, the first
byte of character ROM ($D000) is equal to 60, which is calculated by raising two to the
following bit positions:
2 2 + 2 3 + 2 4 + 2 5 = 4 + 8 + 16 + 32 = 60
The bits that are set (on) correspond to pixels that are enabled on the screen in the
foreground color. Bits that are clear correspond to pixels that are disabled, which are
displayed in the background color, according to background color register 0 at location
53281.
The second byte (row of pixels) of the at-sign (@) character is equal to 102
(decimal) and is obtained by the following:

THE POWER BEHIND COMMODORE 128 GRAPHICS

21 + 2 2 + 2 5 + 2 6 = 102
The last byte of the at-sign character is equal to zero, since no bits are set.
Therefore, each pixel on the screen is displayed in the background color. The values of
the binary digits on the right in Figure 8-16 are directly related to the image of the
character as it appears on the screen on the left in Figure 8-16.

ACCESSING CHARACTER ROM

CI28 BASIC
To access character ROM in C128 BASIC, type and run the following program:
10 BANK 14
20 FOR 1=53248
3 0 BANK 15

TO 5 3 2 4 8+7:PRINTPEEK(I);:NEXT

Enter Bank 14, the only BASIC bank where the character ROM is accessible.
Then print the PEEK value of the first eight bytes of the character ROM. When
finished, return to Bank 15.

MACHINE LANGUAGE
To access character ROM in C128 Machine Language, type and run the following
program:

MONITOR
PC

SR AC XR YR

SP

; FB0 0 0 0 0 0 0 0 0 0 0 F6
.
.
.
.
.
.
.
.
.
.
.

01800
01802
01805
01807
0180A
0180D
0180E
01810
01812
01814
01817

A9
8D
A2
BD
9D
E8
E0
D0
A9
8D
60

01
LDA #$01
00 FF STA $FF00
00
LDX #$00
00 D0 LDA $D000,X
40 18 STA $1840,X
INX
07
CPX #$07
F5
BNE $1807
00
LDA #$00
00 FF STA $FF00
RTS

10 SYS 6144
20 FOR 1=6208 TO 6208 +7:PRINTPEEK(I);:NEXT

These machine language and BASIC routines accomplish the same task as the preceding
four-line BASIC program. The first two machine language instructions switch in the
character ROM, and switch out I/O. The next six instructions transfer the first eight

229

230

COMMODORE 128

bytes of character ROM into locations 6208 ($1840) through 6215 ($1847). The last
three instructions switch out the character ROM, replace it with the I/O registers and
return from the machine language subroutine to BASIC.
The BASIC routine activates the machine language subroutine, then prints the
values that were temporarily stored in 6208 through 6215. See Chapter 6, How to
Enter Machine Language Programs, for details on how to input machine language
instructions on the C128.

C64 BASIC
To access character ROM in C64 BASIC, enter and run the following program:

40 POKE 5 6 3 3 4 ,PEEK( 5 6 3 3 4)AND 254

50 POKE 1,PEEK(1) AND 251
80 FOR 1=0 TO 7:POKE 6144+1, PEEK(5 3 2 4 8+I):NEXT
90 POKE 1,PEEK(1) OR 4
105 POKE 5 6 3 3 4 ,PEEK(5 6 3 3 4) OR 1
130 FOR 1=6144 TO 614 4+7:PRINTPEEK(I);:NEXT

Line 40 turns off the interrupt timer. Line 50 switches out I/O and replaces it with
character ROM. Line 80 transfers the first eight bytes of character ROM (53248-53255)
to 6144-6151. Line 90 switches out character ROM, and replaces it with the I/O
registers. Line 105 turns on the interrupt timer. Line 130 prints the first eight character
ROM values that were temporarily stored in 6144 through 6151.
You may need to transfer parts of the character ROM data into RAM if you are
creating your own character set, and you want the remainder to be from the C128
character set. This is covered in more detail later in the chapter. These methods of
looking at the character ROM demonstrate how the character ROM is accessed, what the
patterns of the characters look like and why you would want to access the character
ROM.
The next section explains how to program your own custom characters in C128
mode.

PROGRAMMABLE CHARACTERS
The Commodore 128 has a feature that allows you to redefine the character set into
custom characters of your own. In most cases, you'll want to redefine only a few
characters at most, while obtaining the rest of the character set from the Commodore
128 character ROM.
With programmable characters, you tell the C128 to get character information
from RAM. Usually, characters are taken from the character ROM. If you only want
certain characters, you can choose the ones you want, copy the character patterns into
RAM and leave the rest in ROM. You cannot write to the character data in ROM;
however, the character data placed in RAM can be redefined.
The first step in programming your own characters is to define the image. In the

THE POWER BEHIND COMMODORE 128 GRAPHICS

Standard Character Mode section, you saw how a character on the screen is stored in the
character ROM. Each character requires eight bytes of storage. Each byte corresponds to
a row of pixels on the visible screen within the 8 by 8 character matrix; therefore, eight
rows of pixels make up one character.
This section shows how to customize an uppercase cursive (script) character set
for the letters A through H. Figure 8 - 1 7 shows the design for the uppercase cursive
letter A. The grid in the figure demonstrates how the character appears on the screen
within the 8 by 8 pixel matrix. Each row of the grid determines which bits are on within
the character bit pattern, and, hence, which corresponding pixels are enabled on the
screen. The eight-bit binary strings to the right of the grid are the bit patterns as stored
in RAM. The numbers to the right of the binary strings are the decimal equivalents of
the binary bit patterns. This decimal value is the data you POKE into RAM in order to
display the character.

o
1

0
= 00001110 = 14

- 32

= 01000010 = 6 6

= 10000010 = 130
= 10000100 = 132

- 00010001 = 17
= 00100000

= 10001010 = 138

= 01110001 = 123

Figure 8-17. Design for Cursive letter " A "

The following program creates and displays the upper-case cursive characters A
through H. Enter it into the computer and RUN it. You'll see the letters A through H
change from uppercase block letters to uppercase cursive letters. When you press the
newly defined lettered keys, they are displayed in cursive form.
Line 10 selects the uppercase character set, the set being redefined. Line 20
protects the character set from being overwritten by the BASIC program and prepares a
location in RAM in which to place your character set. The end of user BASIC text and
the top of string storage is moved from 65280 to 12288 (decimal), which substantially
cuts down the size of BASIC programming space. The character set will be placed
beginning at location 12288, but it does not have to be located there. The character set
does have to be within the first 16K of memory unless another bank is selected. The
VIC chip can only access 16K at a time so each video bank consists of 16K of memory.

231

232

COMMODORE 128

10 PRINT CHR$(142) :REM SELECT UPPER CASE

20 POKE5 4 , 48 :POKE5 8 , 48:CLR:REM PROTECT CHAR SET
3 0 BANK 14 :REM SWITCH TO BANK 14 FOR CHARACTER ROM
40 FORI = l TO 511:POKEI + 12 2 88 ,PEEK(1 + 5 3 2 4 8) :NEXT:REM ROM TO RAM TRANSFER
50 BANK 15:REM SWITCH TO DEFAULT BANK
60 POKE 2 60 4, (PEEK(2 60 4 ) AND 240)+12:REM START CHAR BASE AT 12288
70 FORJ=12 2 88TOl2 28 8+71 :REM PLACE CHARACTER DATA IN RAM
8 0 READ A
90 POKEJ,A
100 NEXT J
110 SCNCLR
120 DATA 0,0,0,0,0,0,0,0:REM @
130 DATA 14 , 17 , 3 2 , 66 , 1 30 , 1 3 2 , 1 3 8 , 12 3:REM A
140 DATA 124, 66,66, 124, 66, 81,225,126:REM B
150 DATA 62 , 67 , 130 , 128 , 128 , 128 , 1 31,12 6 :REM C
160 DATA 125 , 98 , 12 5 , 6 5, 65 , 19 3,161 , 254 :REM D
170 DATA 225 , 6 6, 64 , 5 6, 120, 6 5 , 6 6 , 12 4:REM E
180 DATA 127 , 129, 2 , 4 , 14 , 228 , 68,56:REM F
190 DATA 193 , 163 , 253 , 3 3,249 , 65,99 , 190:REM G
20 0 DATA 2 27 , 16 5 , 36 , 36 , 12 6 , 36 , 3 7 , 2 31 :REM H

You can leave yourself more BASIC text area, but to do this you must enter a video
bank higher than zero. This sample program operates in Bank 0. If you place your
character set in a higher video bank, remember to add an offset of 16384 ($4000) to the
start of RAM character memory for each bank above video Bank 0.
The CLR in line 20 clears out memory starting at 12288 because, prior to the
placement of the character set there, the memory locations are filled with random bytes.
The random bytes must be cleared before new character information can be stored.
Line 30 selects BANK configuration 14. This configuration makes the character
ROM visible with a PEEK command or within the machine language monitor, and
temporarily switches out the I/O registers. Both the I/O functions and the 4K character
ROM share the same locations ($D000-$DFFF). Depending on whether bit 0 in the
configuration register (location $FF00) is on or off, the C128 addresses the I/O registers
or the character ROM. Normally the C128 powers up with bit 1 turned off; therefore,
the I/O registers in locations $D000-$DFFF are addressed. The BANK command in line
30 sets bit 0 in location $FF00; therefore, the character ROM in locations 53248-57343
($D000-$DFFF) is addressed. The character ROM is accessed in order to make the
transfer of characters to RAM.
Line 40 makes the actual transfer from ROM to RAM. Since the character ROM is
accessed in line 30, it now begins at location 53248. The first 512 bytes (the uppercase
character set) from the character ROM are POKEd into the 512 bytes of RAM beginning
at location 12288 and ending at 12800. At this point the character set is ready to be
redefined to custom characters.
Line 50 switches the I/O registers back in, meaning the character ROM is no
longer available.
Line 60 specifies the start of the character set base at location 12288. The character
set base can be stored in locations other than 12288. (See the Character Memory section
earlier in this chapter for more information on moving character memory.) Location
2604 is the intermediate memory location that the interrupt-driven C128 screen editor
uses to point to screen and character memory in character mode. You must use this
indirect location to change the value of the actual register that points to the screen and
character memory 53272. If you try to POKE directly to location 53272, the interrupt will

THE POWER BEHIND COMMODORE 128 GRAPHICS

change the value back to the original one within a sixtieth of a second. (You can, however, disable the interrupt-driven screen editor. See the Shadow Register section for details.)
The value (AND 240) or 12 is placed in address 2604 to tell the C128 to point to
character memory in RAM, starting at address 12288. If the value (AND 240) or 8 is
placed into 2604, the character set will begin at 8192 and your BASIC program must be
less than 6K, but the complete 4K of characters can be redefined. If the value (AND 240)
or 14 is placed into that location, the character set starts at 14336. Your BASIC program
then must be less than 2K, since the programmable character set must reside within a
single 16K block, but the BASIC program that creates the characters can be almost 14K.
If a number other than 12 is POKED into 2604, other program lines must be modified.
Lines 70 through 100 start a loop at the beginning of the character base (12288),
read the values from the data statements which define the new characters (lines 120 and
200), and POKE them (line 90) into the locations allocated for the character set base,
starting at location 12288. The value 12288 + 71 in line 70 sets aside seventy-two
storage locations for the data values in lines 120 through 200 for storage in locations
12288 through 12359. When more data statements are added, the value (12288 + 71)
must be increased to 12288 plus the number of data values in the data statements minus
1. For example, if more characters were defined and there were twenty data statements
with eight values in each, then line 70 would read:
70 FOR J - 12288 TO 12288 + (160-1)

MULTI-COLOR CHARACTER MODE

Standard character mode displays text in two colors: the foreground color of the
character as determined by COLOR RAM, and the background color as determined by
background color register 0 at location 53281 ($D021).
Multi-color character mode gives you the ability to display characters in four colors
within an 8 by 8 character matrix. This substantially increases the freedom of using color.
However, the horizontal resolution is only half the resolution of standard character mode
(160*200), since multi-color mode bits and screen pixels are grouped in pairs. This means
that the color definition and pixel density is twice as wide as standard character mode. The
tradeoff in horizontal resolution is compensated for by the increased freedom of using color.

HOW T O ENTER MULTI-COLOR MODE

Location 53270 and its shadow register ($00D8) determine whether the C128 is outputting standard or multi-color characters on the screen. Bit 4 of 53270 and bit 7 of 216
($00D8) control multi-color mode for character and bit map modes. If bit 4 of 53270
(and bit 7 of 216) is equal to 1, multi-color mode is enabled. Otherwise, standard mode
is enabled. Most of the new 7.0 BASIC graphics commands have provisions for multicolor mode. However, if you want to enter multi-color mode with a POKE command, type:
10 POKE 216,255: REM Disable IRQ Editor
20 POKE 53270, PEEK (53270) or 16: REM Select MCM
This enters multi-color mode, either for character mode or bit map mode.

233

234

COMMODORE 128

SCREEN LOCATION
The screen location in multi-color character mode defaults to 1024 ($0400) through 2023
($07E7), the same as standard character mode. The screen memory locations can be
relocated. See the Screen Memory section for details.

HOW SCREEN DATA IS INTERPRETED

In multi-color character mode, the screen data from screen memory is interpreted as
screen codes the same way as in standard character mode. The screen codes are listed in
Appendix D. See the screen data interpretation in the standard character memory
section. The only difference between standard character mode and multi-color character
mode is the way color is assigned to the characters on the screen.

CHARACTER MEMORY LOCATION

The character memory in multi-color character mode, as in standard character mode, is
taken from between 53248 ($D000) and 57343 ($DFF) when I/O is switched out. See
standard character mode for more detailed information on character memory.

HOW CHARACTER MEMORY IS INTERPRETED

IN MULTI-COLOR CHARACTER MODE
Character memory is interpreted virtually the same way in multi-color and in
standard character modes, except for one difference: In standard character mode, if
a bit in the character definition image is on, the pixel corresponding to that bit
is colored in the foreground color as specified by color RAM. If a bit in the character
image in the character ROM is equal to zero, the corresponding pixel on the screen is
colored in the background color, as specified by background color register 0 (location 53281).
In multi-color character mode, color assignments to the pixels that make up the
character on the screen are not in a direct one-to-one relationship to the bits in the
character ROM data patterns. Instead, the bits that make up a character are grouped in
pairs, as shown in figures 8-18, 8-19 and 8-20.

Figure 8-18. "At" Sign (@) Character as It Appears on the Screen

THE POWER BEHIND COMMODORE 128 GRAPHICS

_0_ 0_ J - J_ J_ j _ o _0
0_ 1 X 0 JL X 1 _0_
0_ 1 X _0_x T T 0
0 X 1 0_ _L j _ _j_ 0
0 J_ X 0_ o_ _o_ o_ _0
0_ J_ 1 0 o_ _o_jL 0
0_ _0_T J_ j _ j _ o_ 0
0__0__0__0__o__o _0__0
Figure 8-19. Bit Patterns of the "At" Sign (@) Character as They Appear in
Character ROM

00
01
01
01
01
01
00
00

11
10
10
10
10
10
11
00

11
01
11
11
00
00
11
00

00
10
10
10
00
10
00
00

Figure 8-20. Bit Patterns of the "At" Sign (@) Character as They Are Grouped
in Pairs in Multi-Color Character Mode
The bits are grouped in pairs, since the horizontal resolution is only half as wide in
multi-color mode. The bit pair determines the color assignments for the pixels within the
character on the screen. The following section describes how the colors are assigned in
multi-color character mode.

COLOR DATA
The color of the pixels in a multi-color character originate from four sources, depending
on the bit pairs. Since the bit pairs have four color possibilities, two bits are needed to
represent four values: 00, 01, 10 and 11. In Figure 8-21, the value of the four bit pair
combinations determines the color assignments for the pixels in a multi-color character.

BIT PAIR

00
01
10
11

COLOR REGISTER

LOCATION

Background # 0 color (screen color)

Background #1 color
Background # 2 color
Color specified by the
lower 3 bits in color memory

53281 ($D021)
53282 ($D022)
53283 ($D023)
color RAM

Figure 8-21. Truth Table for Color Data

235

236

COMMODORE 128

If the bit pair equals 00 (binary), the color ofthose two pixels corresponding to the
bit pair are colored by background color register 0 (location 53281 ($D021)). If the bit
pair equals 01 (binary), the pixels are colored by background color register 1 (location
53282 ($D022)). If the bit pair equals 10 (binary), color for those two pixels within the
character are colored from background color register 2 (location 53283 ($D023)).
Finally, if the bit pair from the character pattern equals 11 (binary), those two pixels are
colored from the color specified in the lower three bits (2, 1, 0) of color RAM. Color
RAM is located between 55296 ($D800) and 56295 ($DBE7).
When multi-color character mode is selected, you can still display standard
characters on some screen locations, and display others in multi-color mode. Bit 3 of
each color RAM location determines whether the character is displayed in standard or
multi-color mode. If bit 3 in color RAM is set (1), characters are displayed in
multi-color mode. Ifbit 3 is clear (0), characters are displayed in standard character mode.
This means that in order to display characters in multi-color mode, you must fill color
RAM with a color code greater than 7. The colors greater than 7 (the ones that are
displayed in multi-color mode) are shown in Figure 8-22.

COLOR CODE

COLOR

8
9
10
11
12
13
14
15

Orange
Brown
Light Red
Dark Gray
Medium Gray
Light Green
Light Blue
Light Gray

Figure 8-22. Color Codes

Remember, the multi-color bit (bit 3) must be set to display multi-color characters.
The following program illustrates multi-color character mode.
10

COLOR

20
30
31
32
33
35
37
40
50
60
70
85
90

COLOR 2,1
:REM MULTCLR 1 = WHITE
COLOR 3,2
:REM MULTCLR 2 = RED
FOR I = lT02 5
PRINT "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
NEXT
FOR 1=55296+512 TO 55296+1023:POKE I,7:NEXT:REM PLACE YELLOW IN COLOR RAM
POKE 216, 255:REM DISABLE SCREEN EDITOR
POKE 5 32 7 0 ,PEEK(5 3 27 0) OR 16:REM SET MULTICOLOR BIT
FOR I = lT025
PRINT "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
NEXT
FOR 1=55296 TO 55296+1023:POKE I,14:NEXT:REM FILL COLOR RAM WITH BLUE
GRAPHIC 0:REM RETURN TO STANDARD COLOR

0,1

:REM BKGND

BLACK

Lines 10, 20 and 30 place the color codes for black, white and red into background
color registers 0, 1 and 2, respectively. Lines 31 through 33 print the letters of the

THE POWER BEHIND COMMODORE 128 GRAPHICS

alphabet on the screen twenty-five times. Line 35 fills the last 512 bytes of color RAM
with yellow. Line 37 disables the IRQ VIC screen editor. Line 40 enables multi-color
mode. At this point, all the screen locations corresponding to the color RAM locations
which have a color code greater than or equal to 8 are displayed in multi-color mode.
Since the yellow color code is 7, all the color RAM locations having this code are
placed in standard character mode. The default color for color RAM is code 13 (light
green) for C128 mode, and code 14 (light blue) for C64 mode. Line 85 fills color RAM
with the light blue color code. The multi-color characters displayed on the screen are
red, white and blue on a black background.

EXTENDED BACKGROUND COLOR MODE

The third type of character display mode, extended background color mode, allows you
to display three colors at a time on the text screen. For example, you have the character
color, the background color of the screen, and an additional background color within
each 8 by 8 character matrix. This means you can display a white character with a green
background in the 8 by 8 character matrix, on a black screen background. This mode
offers the use of an additional color in an 8 by 8 character matrix, without any loss in
screen resolution.
There is one sacrifice, however. In extended background color mode, only the
first sixty-four characters of the screen code character set are available. The reason for
this is that bits 6 and 7 determine which color will be selected for the background within
the 8 by 8 pixel character matrix. This only leaves five bits for the computer to interpret
which character is currently on the screen. The highest number you can represent with
five bits is 63. This means only the screen code values between 0 and 63 are available
for display on the screen within extended background color mode.

HOW T O ENTER EXTENDED

BACKGROUND COLOR MODE
Enabling bit 6 of location 53265 selects extended background color mode. Use this
POKE in BASIC:
POKE 53265, PEEK(53265) OR 64
To turn it off, use this POKE:
POKE 53265, PEEK(53265) AND 191

SCREEN LOCATION
The screen location in extended background color mode is the same as the standard
character and multi-color character modes, 1024 ($0400) through 2023 ($07E7). This
screen range can be relocated. See the SCREEN MEMORY section for details.

237

248

C O M M O D O R E 128

HOW T O INTERPRET SCREEN DATA

The data in screen memory is interpreted as screen codes, which are actually the indexes
into the character ROM. Instead of representing the data as ASCII characters, the screen
codes represent the index into the character ROM which provide the ASCII codes. The
first character in character ROM is the at sign (^t); therefore the first screen code, 0, is the
code for the at sign.
Remember, since extended background color mode only uses five bits to determine the screen code value, only the first 64 screen code characters (0-63) are available.

COLOR DATA
The color assignments for the three colors on the screen stem from three sources. Just as
in standard character mode, the foreground color is assigned by COLOR RAM, in the
range 55296 ($D800) through 563295 ($DFE7). As described in the standard character
mode section, each color RAM location has a direct one-to-one correspondence with the
screen memory locations. See the Standard Character Mode section for screen and color
memory maps and an explanation of how the two sections of memory correspond to one
another.
The screen background color is assigned by background color register zero (location
53281 ($D021)). This is the color of the entire screen, on which the foreground and an
additional 8 by 8 character matrix background is placed.
The additional 8 by 8 character matrix background colors are determined by the
value of bits 6 and 7 of the screen code character value. Depending on the value of these
bits, the extended background color (the color within the 8 by 8 character matrix for
each character), comes from one of the four background color registers. Since there are
four choices for the extended background color, the computer needs two bits to
represent the four color choices. Figure 8-23 shows the four-bit combinations and the
corresponding background color registers associated with them.

B A C KG R0 UN D
C H A R A C T E R
RANGE

0-63
64-127
128-191
192-255

C O D E

C 0 LO R

R E G IS T ER

BIT 7

BIT 6

NUMBER

0
0
1
1

0
1
0
1

0
1
2
3

ADDRESS

53281
53282
53283
53284

($D021)
($D022)
($D023)
($D024)

Figure 8-23. Extended Background Color Registers

For example, POKE the screen code for the letter A (1) into screen location 1024.
Now POKE the screen value 65 into screen location 1025. You might expect the
character to be a reverse A, the second character of the second screen code character set.

THE POWER BEHIND COMMODORE 128 GRAPHICS

However, in this mode, you can only represent the first sixty-four characters, since you
only have five bits to represent screen characters. By trying to represent the screen code
65, bit 6 is enabled, which tells the computer to select the background color register 1
(location 53282 ($D022)), and display the same character, but with the extended
background color specified by background color register 1.
Here's a program that illustrates how extended background color mode operates:
5 SCNCLR
10 COLOR 0,1 :REM BKGRD=BLACK
20 COLOR 2,1 :REM MULTICOLOR 1
3 0 COLOR 3,2 :REM MULTICOLOR 2
40 POKE 5 3 284,3:REM BACKGRD COLOR 3
45 POKE 5 3265 ,PEEK(5 3 26 5) OR 64:REM SET EXTENDED BKGRND BIT
50 FOR 1=1024 TO 1256:POKE I,I-102 3:NEXT
60 PRINT:PRINT:PRINT:PRINT

In the program, line 5 clears the screen. Lines 10 through 40 assign colors to the
four background color registers: black, white, red and cyan, respectively. Line 45
enables extended background color mode. Line 50 POKEs 232 characters into screen
memory. Each time sixty-four characters are stored into the screen memory, the same
set of sixty-four characters is POKEd into the next sixty-four screen locations. However,
the next extended background color is displayed. First, the sixty-four characters are
displayed with a black extended background, then a white extended background, then
red, then cyan.

CHARACTER DATA
Character data is interpreted the same way as in standard character mode, except only
the first 64 characters of the screen character set are available. The character data is also
located in the same range as in standard character mode. See standard character mode
for more information on character data.

STANDARD BIT MAP MODE

Standard Bit Map Mode, also referred to as high-resolution mode, offers the ability to
display detailed graphic images in two colors. The resolution of bit map mode is
320 by 200 pixels. In this mode, the C128 no longer operates in terms of characters,
which are 8 by 8 pixel images stored in those complete units at a time. Bit map mode
allows you to address single pixels at a time, therefore exercising a substantial amount
of control over the detail of images on your screen. The smallest unit addressed in the
character display modes is an 8 by 8 pixel character. Standard bit map mode allows you
to address every individual pixel of the possible 64000 pixels that make up an entire
high-resolution screen image. Figure 8-24 shows how that bit-map coordinate plane is
set up.

239

246

COMMODORE 128

X Coordinate
0,0

319,0

Y Coordinate

0,199

319,199

Figure 8-24. Bit Map Screen Coordinates

HOW T O ENTER STANDARD BIT MAP MODE

To enter standard bit map mode, set bit 5 of location 216 ($00D8) (the shadow
register of location 53265 ($D0ll)). When you issue the GRAPHIC l , l command
in C l 2 8 BASIC, bit map mode is enabled and the bit map screen is cleared.
You can also use a POKE command as follows, but you should use the highestlevel commands wherever possible:
POKE 216, PEEK (216) OR 32
This command turns on bit 5 of the GRAPHM register, which is the interface between
the VIC chip and the interrupt-driven C128 screen editor. This indirectly turns on bit 5
in location 53265 and enters bit map mode.
You can disable the interrupt-driven screen editor and select bit map mode directly
with these commands:
POKE 216, 255
POKE 53265, PEEK (53265) OR 32
In C128 mode machine language, use this program sequence:
LDA $00D8
ORA # $ 2 0
STA $00D8
In C64 mode machine language, try this:
LDA $D011
ORA # $ 2 0
STA $D011

THE VIDEO MATRIX

(SCREEN MEMORY) LOCATION
The default location o f t h e C128 video matrix (i.e., the bit map screen memory) is 7168
($1C00) through 8167 ($lFE7).
The default location of the C64 video matrix is 1024 ($0400) through 2023

THE POWER BEHIND COMMODORE 128 GRAPHICS

($07E7). The video matrix can be moved, however. See the Screen Memory section
elsewhere in this chapter for information on relocating the video matrix.

HOW THE VIDEO MATRIX

IS INTERPRETED
ln bit map mode, the video matrix (bit map screen memory) is interpreted differently
than it is in the character display modes. In the character display modes, the screen
memory data is interpreted as screen codes corresponding to the characters in character
ROM. However, in bit map mode, the video matrix data is interpreted as the supplier of
color information for the bit map. The upper four bits (nybble) supply the color
information for the bit map foreground, and the lower nybble supplies the color code for
the bit map background.
The next section explains how pixels on the bit map screen are assigned to either
the foreground color or the background color.

BIT MAP DATA

In bit map mode, the character data, referred to as the bit map, is also interpreted
differently than in the character display modes. The character data is not taken from
character ROM at all. Instead, it is taken from an 8K section of RAM memory, known
as the bit map.
The standard high-resolution screen is composed of 200 rows of 320 pixels, so
that the entire screen is composed of 64,000 pixels. In bit map mode, one bit in memory
is dedicated to an individual pixel on the screen. Therefore 64000 pixels require 64000
bits (or 8000 bytes) of memory to store the entire bit mapped image.
If a bit in memory in the 8000 byte bit map is set, the corresponding pixel on
the screen is enabled, and becomes the color of the foreground as specified in the upper
four bits of the video matrix. If a bit in the bit map is equal to zero, the corresponding
pixel on the screen becomes the color of the background, as specified in the lower four
bits of the video matrix. The combination of on and off bits in the bit map and the
corresponding pixels on the screen define the highly detailed image on the video screen.
The bit map default location in memory ranges from 8192 ($2000) through 16191
($3F3F). This requires 8000 bytes orjust under 8K of memory. The spare bytes are used
for other purposes. Location 53272 determines the location of the video matrix and bit
map in memory. Since the screen editor is running on the IRQ, location 2605 ($0A2D)
is an indirect address you must use to place a value in location 53272 ($D018). The
upper four bits of 53272 determine where the video matrix begins and the lower four
bits determine where the bit map begins. In bit map mode, only bit 3 is significant, so
the bit map is either placed starting at location 0 or location 8192 ($2000) in each video
bank.
If you change to a higher bank number, remember to add an offset of $4000 to the
start of the bit map and the video matrix for each bank number above 0.
The video matrix is relocatable. See the Screen Memory section in the beginning
of the chapter for details on how to move the video matrix.

241

242

COMMODORE 128

The bit map tells the computer which pixels in the foreground to enable on the
screen. Like a road map, it spells out exactly which pixels to turn on (in the foreground)
and off (in the background color) in order to display a picture on the screen. For
example, if the bit map started at location 8192 (the C128 BASIC default) the first
byte of the bit map corresponds to the bit map pixel coordinates 0,0 through 0,7. The
second byte of the bit map, location 8193, corresponds to coordinates 1,0 through 1,7
and so on. See Figure 8-25 to see how the bit map data in locations 8192-16191
correspond to the pixels on the visual screen:
X Coordinate

Figure 8-25. Relationship of Bit Map Data to Screen Pixels

Now you know how bit map mode operates internally within yourC128. However,
you need an easy way to turn on and off pixels in the bit map in order to display
graphics on the screen. The new, high level BASIC 7.0 commands such as DRAW,
CIRCLE, BOX and PAINT allow you to control the turning on and off of bits and their
corresponding screen pixels. The use of the X and Y coordinates on the bit map
coordinate plane easily orient you to displaying graphics. You can display highresolution graphics in other ways, outside of the BASIC 7.0 graphics commands.
This includes using commercial software packages that employ graphics tablets or
joysticks to draw on the screen, writing your own draw routines using a joystick or
paddle, or physically entering data into the bit map (which is painfully tedious and not
recommended).

THE POWER BEHIND COMMODORE 128 GRAPHICS

Another way to display graphics, which involves manipulating bits in the bit map,
is through mathematical equations, using geometry. Several books are available which
offer geometrical equations on how to draw three-dimensional objects and to move them.
Refer to the Suggestions for Further Reading the back of the book for sources on graphics.

COLOR RAM
In standard bit map mode, color RAM is not used since the color information for the bit
map is taken from the upper and lower nybble of screen RAM. Color RAM is used,
however, in multi-color bit map mode.

MULTI-COLOR BIT MAP MODE

Multi-color bit map mode is a combination of standard bit map mode and multi-color
character mode. Multi-color bit map mode allows the display of four colors within an 8
by 8 pixel bit map area. Like multi-color character mode, the horizontal resolution is
only half of the standard bit map mode, though the tradeoff in resolution is compensated
for by the use of two additional colors within an 8 by 8 pixel, bit mapped area.

HOW T O ENTER MULTI-COLOR

BIT MAP MODE
To enter multi-color bit map mode from C128 BASIC, issue the following command:
GRAPHIC 3
You can enter this mode with a POKE command as well. But make use of the
highest level commands available for the easiest programming:
POKE 216, PEEK (216) OR 160
This POKEs the value 160 and turns on the multi-color mode bit 7 (value 128) and
the bit map mode bit 5 (value 32) in the GRAPHM register which interfaces to the C128
interrupt driven screen editor. This indirectly turns on, respectively, bit 4 (multi-color
mode) of location 53270 ($D016), and bit 5 (bit map mode) of location 53265 ($D011).
Bit 5 of location 53265 determines whether the C128 is in bit map mode or
character mode. If bit 5 is equal to 1, bit map mode is enabled. Bit 4 of location 53270
determines whether the C128 is in standard or multi-color mode. If bit 4 is set, the
C128 operates in multi-color mode, regardless of whether it is in character or bit map
mode.
In C64 mode, you can store a value directly to these registers. But in C128 mode,
the GRAPHM intermediate register must be used as a gateway to these actual registers.
Again, this is because the C128 screen editor is interrupt driven, enabling the splitscreen modes for text and simultaneous bit map displays. Since the screen editor is
interrupt driven, an indirect register is used to restore the values that you need to use for

243

244

COMMODORE 128

specific VIC registers. GRAPHM is one such register; therefore, every sixtieth of a
second, the value in the GRAPHM register is loaded into the appropriate VIC registers.

MACHINE LANGUAGE
To select multi-color bit map mode in C128 machine language, perform the following
instructions:
LDA $A0; enables bits 4 and 5 of GRAPHM, the shadow location
STA $00D8
In C64 machine language, enter:
LDA $D011
ORA #$20; select Bit map mode
STA $D011
LDA $D016
ORA #$10; select multi-color mode
STA $D016
In both cases, you must clear the screen, color RAM and the bit map in your own
program.

VIDEO MATRIX LOCATIONS

The video matrix defaults to locations 7168 ($1C00) through 8167 ($lFE7) in C128
mode.
In C64 mode, the video matrix defaults to locations 1024 ($0400) through 2023
($07E7). This is relocatable. See the Screen Memory section earlier in this chapter.

HOW T O INTERPRET THE VIDEO MATRIX

The contents of the video matrix are interpreted the same way as in standard bit map
mode. The upper nybble is the color code for the foreground color; the lower nybble is
the color code for the background color of the bit map.

ADDITIONAL COLOR DATA

The upper and lower nybbles of screen memory supply the multi-color bit map screen
with two of the color sources. This mode offers two additional colorsbackground
color register 0 (location 53281) and the lower nybble of color RAM.
As in multi-color character mode, the bit patterns of the bytes in the bit map
determine the color assignments for the pixels on the screen. The bits are similarly
grouped in pairs, within 8-bit bytes, so there are 4-bit pairs in each byte. Bits 0 and 1, 2
and 3, 4 and 5, and 6 and 7 are grouped in pairs respectively. Depending on the values
of the bit pairs, the corresponding pixels in the bit map are assigned colors from the
sources in Figure 8-26.

THE POWER BEHIND COMMODORE 128 GRAPHICS

BITS

COLOR INFORMATION COMES FROM

00
01
10
11

Background color # 0 (screen color)

Upper four bits of video matrix
Lower four bits of video matrix
Color RAM

Figure 8-26. Multi-Color Bit Map Pixel Color Assignments

THE BIT MAP

Bit patterns determine how color is assigned to the multi-color bit map screen. If the bit
pair is equal to 00 (binary), color is taken from background color register 0 (location
53281). If the bit pair is equal to 01 (binary), the color assigned to these two pixels
comes from the upper nybble of video matrix. If the bit pair in the bit map is equal to
10 (binary), then the color assigned to those two pixels comes from the lower nybble of
video matrix. Finally, if the bit pair in the bit map is equal to 11 (binary), the color is
taken from the lower four bits of color RAM. Unlike multi-color character mode, the
screen is either all standard bit map, or all multi-color bit map, unless you develop a
sophisticated interrupt-driven application program that handles the two separate bit
maps.

COLOR RAM
In multi-color bit map mode, color RAM is used if the bit pair from the bit map equals
11 (binary). Each color RAM location may have one of sixteen color codes, which
means that one 8 by 8 bit map area can have black, red, white and blue colors,
respectively, for the background color register 0, the upper nybble, the lower nybble, and
the color RAM. The 8 by 8 multi-color bit map area next to it can have black, red, white
and green colors, since each color RAM location is independent of any other. The other
three color sources usually remain constant throughout a bit map screen, though you can
change the upper and lower nybbles of the video matrix. The background color register
is almost always the same throughout a bit map screen.
The C128 has powerful and varied graphics display capabilities. Certain applications call for one type of display over another. Experiment with them all and see which
one meets your needs best. Figures 8-28 through 8-32 provide a graphics programming
summary that should be helpful in understanding graphics on the C128.

SPLIT-SCREEN MODES
The Commodore 128 has a split-screen feature that allows you to display the top portion
of the screen in bit map mode and the bottom portion in character mode. This allows you to
enter a BASIC graphics program and RUN it while the BASIC program listing is

245

246

COMMODORE 128

present and the bit map image is displayed, which saves time switching back and forth
between bit map and character modes.
Before, you would have had to enter the graphics program (in machine language),
RUN it and switch back to the text screen to make a change. Now you can display the
graphic image and have your text screen available to you all at the same time. You can
alter the program while your bit map image is still on the screen, RUN it and see the
immediate results without losing the text screen.
Without the Commodore 128's split-screen capabilities, you would have to program a split screen yourself. This involves raster interrupts which utilize either two
screen memories in two different video banks, or a fairly choppy single-screen memory,
usually with a visible raster line. With the C128 split-screen mode, all you have to do to
enter a split-screen mode is to issue the GRAPHIC command in BASIC. For example,
the command:
GRAPHIC 2,1
sets up a standard bit map screen on top and a text screen on the bottom. Similarly, the
command:
GRAPHIC 4,1
constructs a multi-color bit map screen on the top portion of the screen and a text screen
on the bottom portion. The " 1 " in these commands clears the bit map screen. To leave
the bit map screen intact, once you have already displayed an image, replace the " 1 "
with a zero (0).
The GRAPHIC command has an additional parameter that allows you to define
where the split occurs. The split-screen starting location is defined in terms of a
character row, as if the C128 were in a character display mode. For example,
GRAPHIC 4,1,15
selects a split screen with multi-color bit map mode on top of the screen and the text
screen on the bottom, starting at character row 15. If the start of the split screen is not
defined, the C128 defaults the start to line 19.

HOW SPLIT-SCREEN MODES ARE

ORGANIZED IN MEMORY
SCREEN LOCATIONS
The split-screen modes, both multi-color and standard, use two independent screen
memories. The bit map video matrix is taken from the address range 7168 ($1C00)
through 8191 ($lFFF), just as in standard and multi-color bit map modes. The text
portion of the screen takes its screen memory from default character mode screen
locations 1024 ($0400) through 2023 ($07E7), just as in standard and multi-color
character mode. The hidden portions of the screen, the bottom portion of the bit map
screen and the upper portion of the text screen, still store data, but it is invisible
since the other screen memory has overlaid it.

THE POWER BEHIND COMMODORE 128 GRAPHICS

INTERPRETING SCREEN DATA

The text portion of the split screen is interpreted according to the standard character mode
section. The bit map portion, whether standard or multi-color, is interpreted according to the
description in the bit map mode section. Consult the Standard Character Mode, Standard Bit Map
Mode and Multi-color Bit Map Mode sections for information on how screen data is interpreted.

CHARACTER MEMORY LOCATIONS

The split-screen modes also take character data from two independent parts of memory.
The bit map data, referred to simply as the bit map, is taken from the default range 8192
($2000) through 16191 ($3FE7) for both the multi-color and standard bit map mode
portions of the screen.
The character memory for the text portion of the split screen is derived from the
character ROM. The actual character ROM occupies the memory locations 53248
($D000) through 57343 ($DFFF) overlaying the I/O registers. The I/O registers must be
switched out to view the actual character ROM, in bank configuration 14, for example.
For information on how character data is interpreted in standard character, standard bit map and multi-color bit map modes, see the sections describing these modes.
See also the Color RAM Banking section.

COLOR DATA
Each of the standard bit map, multi-color bit map and standard character modes interpret
color differently. See each section for detailed information on color assignments.

MACHINE LANGUAGE
In machine language, you must program a split screen yourself. This is not the easiest of
programming tasks, since it involves raster interrupt processing, which can be tricky. In
C128 mode, bit 6 in the GRAPHM register is the split screen bit. If bit 6 of $0008
(GRAPHM) is set, a split screen is displayed. Otherwise, bit 6 is clear (0) and a single
screen is displayed.
The C64 mode has no corresponding split screen bit. C64 mode is programmed
differently for split screens. See the Raster Interrupt Split-Screen Program at the end of
the chapter to learn how to program a split screen in machine language.
CAUTION: A system crash may occur if the display mode is changed
while the interrupt-driven screen editor is enabled. See the Shadow
Register section for details.

THE INTERRUPT-DRIVEN SCREEN EDITOR

The intermediate memory locations, sometimes referred to in this guide as shadow
registers, are designed specifically for handling the split-screen modes. In order to
provide split-screen modes, the C128 screen editor has to be wedged into the system's
interrupt handling routines.

247

248

COMMODORE 128

Unlike the Commodore 64, the C128 handles interrupts exclusively according to
the raster beam. This has made it necessary to merge the C128 screen editor into the
interrupt request routines (IRQ). The C64 uses interrupt timers which makes interrupt
processing less predictable. By processing the interrupts from the raster beam, the
operating system always knows where and when the interrupt will occur. Timer interrupts made catching a raster interrupt less reliable because the operating system never
knew exactly where an interrupt would occur in relation to the raster beam.
The raster interrupt-driven screen editor made it necessary to use indirect storage
locations for certain registers of the VIC chip and 80-column chip. This way, the
intermediate memory locations refresh the actual video chip registers every sixtieth of a
second, each time the raster beam begins a new scan at the top of the screen. The raster
beam scans the entire screen sixty times a second, so on each pass of the raster beam the
intermediate memory locations refresh the actual VIC chip and 8563 chip registers.

RASTER INTERRUPT
SPLIT SCREEN PROGRAM
WITH HORIZONTAL SCROLLING
This section explains how and provides a program to perform split screen raster
interrupts in machine language. The program is explained as it applies to Commodore
64 mode, but it can be modified to run in Commodore 128 mode.
You already have a way to split the screen in C128 mode with the BASIC
GRAPHIC command. The program provided in this section splits the screen in machine
language in C64 mode. See the figure in the shadow register section to see which
addresses must be changed to make this program work in C128 Mode. A few differences will occur in the timing of the raster. In Commodore 128 mode, all interrupts
occur according to the position of the raster beam as it scans the screen. This is why
shadow registers are necessary for certain graphics locations, since the C128 screen
editor is interrupt driven to allow the split screen modes in BASIC.
The program in this section also scrolls text on the bottom quarter of a standard
character screen, while the top three quarters are displayed in multi-color bit map mode.
The standard character screen resides in video bank 0 ($0400-$07E7) while the multicolor bit map video matrix is stored in video bank 1 starting at $5C00 ($1C00 +
$4000 = $5C00). Every time an interrupt occurs, the program changes video banks,
display modes, the character memory and video matrix pointers. This program supplies
the data that scrolls at the bottom of the screen, but it assumes you have placed an 8000
byte bit map starting at address 8192 ($2000) plus an offset of 16384 ($4000) for the
change of video banks. This makes the absolute start address of the bit map 24576 ($6000).
An 8000 byte bit map is just too large to present in this book. However, the easy
way to place a bit map in this area is as follows:

THE POWER BEHIND COMMODORE 128 GRAPHICS

1.

First start in C128 mode, and enter split screen (multi-color) bit map
mode through BASIC with this command:
GRAPHIC 4,1

2.
3.
4.

Now draw on the screen with the BOX, CIRCLE, DRAW and PAINT
commands either in a program or in direct mode.
When you are finished drawing, enter the machine language monitor either by
pressing the F8 function key or by typing the MONITOR command.
Now transfer the video matrix and bit map from the C128 default locations of
$1C00 through $lFFF and $2000 through $3FFF respectively, to $5C00 through
$5FFF and $6000 through $7FFF respectively. The new start addresses are
the default locations plus an offset of $4000 for both the video matrix and bit
map pointers. The new start of the video matrix is at $5C00 ($1C00 +
$4000). The new bit map begins at address $6000 ($2000 + $4000). This
transfer can be accomplished with a single transfer command within the
machine language monitor as follows:
T 1C00 3FFF 5C00

This command transfers the contents of memory locations $1C00 through $3FFF
to $5C00 through $7FFF. Since the default locations of the video matrix and bit map are
continuous in memory, the transfer can be done with a single command. If the default
addresses of the video matrix and bit map had not been contiguous, two transfers would
have been necessary. See Chapter 6 for details on using the Machine Language Monitor.
Now that you are still within the control of the Machine Language Monitor, begin
entering the machine language instructions in the listing provided in the next few pages.
Start entering the program at address $0C00. The program, including the scrolled data
occupies memory up to address $0DF9, which means the program is a total of 505 bytes,
or almost half a kilobyte (K).
Now save the program you just painstakingly entered with the Monitor Save (S)
command as follows:
S "filename", 08, 0C00, 0DFF
If you have a C128 assembler, create a source file, assemble and load it. If your
assembler allows it, save the program as a binary file.

NOTE: If you have the Commodore 64 Assembler Development System,

create a source file (with start address $0C00), assemble and load it in
C64 mode. Then press the RESET button (not the ON/OFF switch) to enter
C128 mode. Don't worry, your program will still be in memory, but this
time it's in C128 memory. Next enter the Machine Language Monitor
and use the Monitor Save (S) command to make a binary file as described
above.

249

250

C O M M O D O R E 128

Now you are ready to enter C64 mode and run the program with the following
command:
GO 64
Reply to the question " A R E YOU SURE?" by pressing the " Y " key and
RETURN. You are now placed in C64 mode.
At this point, you may say to yourself, "After I just did all that work, why am I
going to waste it by changing modes?"
Actually, you are not wasting any effort. When you GO 64 (or press the reset
button), much of the RAM for machine language programs and data is preserved in
RAM bank 0. BASIC programs are erased, however. Specifically, these are the ranges
of RAM that are preserved when changing between C128 and C64 modes:

C128 MEMORY LAYOUT

$ocoo $0DFF
$1300 - $lBFF
$1C00 $lFFF
$2000 - $3FFF
$4000 - $FF00

RS232 Input and Output Buffers

Available Memory for Machine Language application programs
Bit Map Video Matrix
Bit Map Data
BASIC Text Area

Figure 8-27. Preserved RAM Between CI28 and C64 Modes

The rest of the RAM memory is allocated for other purposes and the contents
change from mode to mode. There are other particular bytes that are preserved from
mode to mode, but these small chunks of memory are not worth mentioning here. The
blocks of memory mentioned above provide enough of a clue to the RAM used by both
modes. Remember, however, that the RAM is only preserved if you switch from C128
mode to C64 mode with the GO 64 command, or you switch from C64 to C128 mode
with the reset button (warm start). If you perform a cold start, turn the computer power
off, then on again, all RAM is cleared and none is preserved.
Notice that the address ranges where you placed your program, the video
matrix and the bit map are in the portions of RAM that are preserved from mode to
mode.

Now start (run) the program from C64 BASIC with this command:
SYS 12*256
The top three quarters of the screen is the bit map screen you created with the
C128 BASIC graphics commands, the lower quarter is horizontally scrolling text.
The following program is the listing that performs the split screen and scrolling.

THE POWER BEHIND COMMODORE 128 GRAPHICS

1000
1010
1020
1030
1040
1050
1060
1070
1080
1090
1100
1110
1120
1130
1140
1150
1160
1170
1180
1190
1200
1210
1220
1230
1240
1250
1260
1270
1280
1290
1300
1310
1320
1330
1340
1350
1360
1370
1380
1390
1400
1410
1420
1430
1440
1450
1460
1470
1480
1490
1500
1510
1520
1530
1540
1550
1560
1570
1580
1590
1600
1610
1620
1630
1640
1650
1660
1670
1680

; RASTER INTERRUPT SPLIT SCREEN WITH :

IVEC =$0314
TEMP =$1806
RAS TRO= $ D 012
BACOL=$D021
POINT=$1802
FLAG:= $FC
FLAG2=$FD
SCROLL=$FE
SREG==$D016
TXTPTR = $FA
;POINTER INTO SCROLLING
*=$0C00
;
LDA
STA
LDA
STA

#<FRANK ;POINT TO TEXT

TXTPTR
#>FRANK
TXTPTR+1

;
LDA #$07 ;SET HI VAL SREG
STA SCROLL
STA FLAG2
;
LDA $DD02 ;SET TO OUTPUT
ORA #$03
STA $DD02
;
;
LDA $D016 ;SET 3 8 COL.
AND #$F7
STA $D016
;
;
LDA
LDX
BONK
INX
CPX
BNE

#$01 ;CLEAR CRAM

#$00
STA $DB20,X
#200
BONK
INITIALIZE INTERRUPT

LOOPl. SEI
LDA IVEC
STA TEMP
LDA IVEC+1
STA TEMP+1
LDA #<MINE
STA IVEC
LDA #>MINE
STA IVEC+1
;
LDA #$00 ;DISABLE TIMER IRQ
STA $DC0E
STA FLAG
;
LDA #49
STA POINT
STA RASTRO
;
LDA #201
STA POINT+1
LDA
STA
STA
LDA

#1
$D0lA ;ENABLE INTERRUPT
$D019 ;RASTER COMPARE
$D011 ;CLEAR HI BIT

251

252

COMMODORE 128

1690
1700
1710
1720
1730
1740
1750
1760
1770
1780
1790
1800
1810
1820
1830
1840
1850
1860
1870
1880
1890
1900
1910
1920
1930
1940
1950
1960
1970
1980
1990

AND #$7F
STA $D011 ;DISABLE INTRPT DIS BIT
CLI

CHECK LDA FLAG2

BPL CHECK
LDA #$00
STA FLAG2

'LDX #39
LDY #39
SHIFT LDA (TXTPTR),Y
STA $0770 ,X
DEX
DEY
BPL SHIFT
INC TXTPTR
BNE MVTIME ;TIME TO RESET POINTER
INC TXTPTR+1
MVTIME LDA TXTPTR ;ARE WE AT THE END OF THE TEXT YET
CMP #<ENDTXT
BNE CHECK
LDA TXTPTR+1
CMP #>ENDTXT
BNE CHECK
LDA #<FRANK ;SET POINTER BACK TO THE BEGINNING
STA TXTPTR
2000
LDA # > FRANK
2010 STA TXTPTR+1
2020
JMP CHECK
2030
2040 FRANK .BYT
2050 . BYT '
2060 .BYT 'THIS IS AN EXAMPLE OF SCROLLING
2070 .BYT 'IN THE HORIZONTAL (X) DIRECTION.
2080 .BYT 'ONCE THE DATA HAS BEEN DISPLAYED,
2090 . BYT 'SCROLLING STARTS AGAIN FROM THE '
2100 .BYT 'BEGINNING.'
2110
2120 ENDTXT .BYT
2130 . BYT
2140
2150
INTERRUPT SERVICE ROUTINE
2160
2170 MINE LDA $D019
2180 STA $D019
2190
2200
LDA FLAG ; FLAG -0 .A=0
2210 EOR #1 ;FLAG =0 .A=1
2220
STA FLAG ; FLAG =1 .A=1
2230 TAX ; .X=1
.A=1
2240 LDA POINT, X ;.X=1
.A=2 0 0
2250 STA RASTRC) ;.X=1 RASTRQ=200
2260 CPX #1
2270 BNE BOTTOM
2280

2290
2300
2310
2320
2330
2340
2350
2360
2370

LDA
ORA
STA
LDA
ORA
STA
LDA
ORA
STA

$D011 ;BIT MAP MODE

#$2 0
$D011 ; BMM
$D018
#$78 ; CHAR=$2 0 0 0 + $4 0 0 0
$D018 ; SCR=$lC00 + $ 4 0 0 0
$D016
#$10
$D016; SET MULTICOLOR

T H E POWER B E H I N D C O M M O D O R E 128 GRAPHICS

2380
2390
2400
2410
2420
2430
2440
2450
2460
2470
2480
2490
2500
2510
2520
2530
2540
2550
2560
2570
2580
2590
2600
2610
2620
2630
2640
2650
2660
2670
2680
2690
2700
2710
2720
2730
2740
2750
2760
2770
2780
2790
2800
2810
2820
2830
2840
2850
2860
2870
2880
2890
2900
2910
2920

LDA $DD00 ;SELECT BANK 1

AND #$FE
STA $DD00
;
LDA
AND
ORA
STA

SREG ;SET SCRRREG

#$F8
# $03
SREG

;
LDA #14
STA $D021
;
PLA
TAY
PLA
TAX
PLA
RTI
;
;
BOTTOM LDA $D011 ; SET TEXT
AND #$FF-$2 0
STA $D011
;
LDA $DD00 ;CHANGE TOBANK 0
ORA #$01
STA $DD00
;
LDA $D016 ; DISABLE MULTI
AND #$FF-$10
STA $D016
;
LDA #2 3 ;
MEMORY
STA $D018
LDA #$00
STA $D021
LDA SCROLL
;
DEC SCROLL
LDA SCROLL
STA FLAG2
CMP #$FF
BNE SLURP
LDA # $ 0 7
SLURP STA SCROLL
LDA SREG
AND #$FF-$07
ORA SCROLL
STA SREG
BASIRQ JMP (TEMP)
;
. END

For readability, the program is listed as a source file, as though it was entered
through an assembler editor. It is easier to understand as a source file rather than a
listing from the Machine Language Monitor. To enter this program into the Machine
Language Monitor, reference the actual address in place of the variable operand addresses. Most of the actual addresses are listed in the beginning of the program (lines
1010 through 1100). Keep in mind that these are only line numbers for an assembler

253

254

COMMODORE 128

editor. You will enter the program into a memory location number (address) in the
Machine Language Monitor. In this case, the program is stored in memory starting at
address $0C00. Line 1120 specifies this start address with:

* - $ocoo
Here's an instruction-by-instruction explanation of the scrolling split screen program.
Line 1010 assigns the variable IVEC to the address $0314, the hardware interrupt
request (IRQ) vector. The interrupt vector is the means by which the Commodore 128
displays split screens and scrolling. By wedging your own routine into the hardware
interrupt vector (in this case scrolling and splitting the screen), it enables you to perform
operations that usually take too long for the microprocessor to perform under an
application program not using interrupts. The interrupt vector is checked for an interrupt
routine every 60th of a second. In this program, the screen is split 60 times per second,
so it appears you have two different screens displayed at the same time. You could not
split the screen without requesting an interrupt; the microprocessor is not able to perform
all the required operations fast enough to keep up with the raster scan of the video
controller. The speed that the screen is continually updated, known as the raster scan,
also occurs at the speed of 60 times per second. For a split screen to occur, you tell the
computer the point on the screen where one type of display ends and the new one (bit
map for example) begins. The way you tell the computer this is by placing the number
of a pixel row, also called a raster row, in the raster compare register located at address
$D012. Line 1030 assigns this address to the variable RASTRO.
You'll see later in the program that the value placed in the Raster Compare Register
starts the text screen at raster row 201. The raster scan is again interrupted at raster row
50 at the top of the screen to display the bit map screen. This is repeated 60 times every
second, so it appears to the human eye that two different display modes are active at the
same time.
On with the program explanation. Line 1040 defines the BACOL variable for the
background color register zero, located at address $D021. Line 1050 assigns the variable
POINT to location $1802. POINT is used to store the raster row value where the text
screen begins. Line 1060 assigns the variable FLAG to location $FC. FLAG is used later
in the program (lines 2200-2270) to determine where the interrupt occurred, either raster
row 50 or raster row 200.
Lines 1070 and 1080 assign the variables FLAG2 to location $FD and SCROLL to
location $FE respectively. Both FLAG2 and SCROLL store the value of the scrolling
register. SREG is assigned to location $D016, the scrolling register. Only bits 0 through
2 are used as the scrolling bits. The other bits in this address are used for other
purposes. Three scrolling bits are necessary since characters that are scrolled are moved
over seven pixels then shifted to the next character position to the left or right, then
scrolled smoothly again seven more pixels.
Line 1100 assigns the variable TXTPTR to address $FA. This variable marks the
starting address in memory where the scrolled characters are stored.
As was mentioned earlier, line 1120 specifies where the program storage begins in
memory. This is the address where the execution of the program begins in memory. You

THE POWER BEHIND COMMODORE 128 GRAPHICS

will SYS to this address to start the program in BASIC, or GO to this address from the
Machine Language Monitor.
The first sequence of program instructions starting at line 1140 places the contents
of the address (named FRANK) of the beginning of the scrolling text into the memory
locations ($FA and $FB) called TXTPTR and T X T P T R + 1 . FRANK is the label in line
2040 which marks the location where the first scrolled character is stored. In this
program the first character is a space; in fact the first forty characters that are scrolled
across the screen are spaces. The forty-first character marks the beginning of the data
T H I S IS AN EXAMPLE OF SCROLLING' in line 2060. The scrolled data in lines
2040 through 2130 is stored starting at location $0C98, once this source file is
assembled into object code. In this case, the low byte stored in $FA is $98 and the high
stored in $FB is $0C. The full 16-bit address $0C98 is important, since this is the base
address which you increment as you scroll each letter across the VIC screen. When the
text pointer (TXTPTR) reaches the end of the scrolling text, the base address $0C98 is
again stored in TXTPTR.
The second sequence of instructions starting at line 1190 sets the high value of the
two scrolling variables SCROLL ($FE) and FLAG2 ($FD) to 7. These are used and will
be explained later in the program.
Sequence three starting at line 1230 sets the data direction register to output.
The next module of instructions in lines 1280 through 1300 set the screen size to
38 columns, reducing the screen width by a column on each side. In order to scroll
smoothly, you must set the screen size to 38 columns. Clearing bit 3 of location $D016
sets 38 column size. Setting bit 3 restores the VIC screen to its normal 40 column size.
The extra column on each side of the screen border provides a place for the
scrolled data to scroll smoothly to and from offscreen. This program scrolls left, so each
newly scrolled character is placed in column 39 on the right, before it becomes visible in
column 38. At the same time, the lead character on the left scrolls from column 2 to
offscreen column 1. This occurs in lines 1770 through 2020 and is explained as the
program progresses.
Lines 1330 through 1380 set the text screen color RAM to a white foreground. The lower four bits specify the foreground character color in standard
character mode.
The screen memory is stored in video bank 0 where the scrolling text appears at
the bottom fourth of the screen. The bit map and video matrix are stored in video bank
1, the 16K range between $4000 and $7FFF.
The reason only 200 color RAM locations are filled is because only the lower five
rows are visible on the text screen. There is no point clearing the other 800 locations
since they are not visible.
Lines 1410 through 1700 make up the interrupt initialization routine. Line 1430,
labeled LOOPl, sets the interrupt disable bit in the status register. When this bit is set,
interrupts are disabled and none can occur. Only when the interrupt disable bit is cleared

255

256

COMMODORE 128

(0) can interrupts occur. The last line (1720) of the interrupt initialization routine clears
the interrupt disable and allows interrupts to occur.
Lines 1440 through 1470 store the original contents of the Interrupt Request (IRQ)
vector into temporary storage locations TEMP (low byte $1806) and T E M P + 1 (high
byte $1807). This is necessary in order to store the original contents of the IRQ vector
so you can jump back to this location once the interrupt is serviced as in line 2900.
Lines 1480 through 1510 store the starting location of the interrupt service routine
into the IRQ vector. In this case, MINE is the source file label in line 2170 where the
interrupt service routine begins. In the assembled object file, as in the Machine
Language Monitor, the low byte is $71 and the high byte is $0D, to form the 16 bit
address $0D71. Once the interrupt disable bit is cleared and an interrupt occurs, the
8502 microprocessor finishes executing its current instruction and sets the interrupt
disable status bit, so no other interrupts can occur. The processor then places the
contents of the high byte and low byte of the program counter and the status register on
the stack respectively. Finally, the 8502 fetches the address contained in the IRQ vector
and executes the routine starting at this address, in this case $0D71.
Lines 1530 and 1540 disable the CIA timer in location $DC0E. In addition, line
1550 initializes the variable FLAG to zero. This variable is used later in the program to
figure out where the raster interrupt has occurred, either at the top of the screen (raster
row 49) for bit map mode or near the bottom fourth of the screen (raster row 201) for
standard character mode.
The instructions in lines 1570 through 1590 define the variable POINT ($1802) as
the value of the raster row 49 ($31) where the interrupt occurs to select bit map mode. In
addition, this value is also stored in the Read/Write Raster Register ($D012) for raster
row comparisons later in the program.
The C128 VIC screen consists of 200 raster rows, each row one pixel tall, having
320 pixel columns. You know how BASIC addresses the bit map coordinates on a
coordinate plane of 0,0 in the top left corner and 319,199 in the bottom right. However,
the visible raster rows are not labeled in the same way. The visible raster rows start at
50 at the top of the screen and end at 250 at the bottom. These are the same row
numbers as sprites use. Notice there are still 200 rows but that they offset the bit map
coordinate row number by 50. The raster row numbers below 50 and above 250 are off
the visible screen. These offscreen raster rows are referred to as the vertical retrace.
The instructions in lines 1610 and 1620 define the variable POINT+ 1 ($1803) as
the value of the raster row 201 ($C9) where the interrupt occurs to select standard
character mode.
Lines 1650 and 1660 enable the raster IRQ Mask Register. Line 1670 sets the
Raster Compare IRQ Flag. By setting bit one in these registers, the raster interrupt
attached to the IRQ line is allowed to occur (once lines 1680 through 1720 are
executed), depending upon whether the physical raster row compares and matches with
either of the values in POINT or P O I N T + 1 . If either of these match, the interrupt
occurs.
The instructions in lines 1680 through 1700 clear the raster compare high bit (bit
8). This is an extra bit from location $D012 for raster compares.

THE POWER BEHIND COMMODORE 128 GRAPHICS

The instruction in line 1720 clears the interrupt disable status bit, which enables
interrupts to occur. This is the last operation to be performed by the interrupt initialization routine. Now interrupts are ready to occur and be serviced.
Lines 1770 through 1800 check the value of FLAG2. If FLAG2 is positive, the
program branches to the label CHECK in line 1770 and checks the value of FLAG2
again. The value stored in FLAG2 represents the value of the lower three bits in the
horizontal scrolling register at location $D016. The variable SCROLL is also associated
with the variable FLAG2. In the interrupt service routine (in lines 2760 through 2810),
the value in SCROLL is decremented and stored in FLAG2. This value pertains to the
value placed in the actual horizontal scrolling register at $D016. The reason this is
counted is as follows.
The direction of the scrolling is right to left; therefore, you must place the
maximum value (7) in the lower three bits of $D016 and decrement that value by one. If
the program had scrolled left to right, you would initialize the scrolling register to zero
and increment the lower three bits. When the scrolling register value is decremented, the
characters in the screen memory locations which are to be scrolled are moved to the left
by one pixel. Each time the scrolling register is decremented, the characters move
another pixel to the left. When the value (the lower three bits) of the scrolling register
equals zero, you must move the scrolled characters up in screen memory by one location.
This routine is contained in lines 1840 through 1880. After the shift, the lower three bits
of the scrolling register are set back to 7, the characters are again shifted by the VIC
chip 7 pixels to the left and your routine shifts the characters up in memory again by
one. The additional details are covered in the explanation of lines 2760 through 2900.
The instructions in lines 1820 through 1880 shift the text to be scrolled up in
memory by one location for each cycle of the loop. First the X and Y registers are
loaded with the decimal value 39 ($27). The instruction in line 1840 loads the value of
the memory location where the scrolled text begins using indirect Y addressing. The
address is calculated by taking the contents of zero page memory variable TXTPTR
($98) and adding the offset 39 to its contents to arrive at $BF. The effective address
gives the low byte where the scrolled data begins. The first scrolled character is actually
a space. Subsequent data elements are accessed by modifying the value of the Y register.
The store instruction in line 1850 stores the first character of the scrolling text in
screen location 1943 ($0770 + $27), which is the fortieth column of the twenty-third
row. This column is not visible when the screen size is set to 38 columns for horizontal
scrolling. Each newly scrolled character must be placed in this position in order to scroll
smoothly from the offscreen location. Lines 1860 and 1870 decrement the X and Y
registers respectively. Line 1880 branches to the label SHIFT if the Y register is positive
(greater than zero).
The second time through the loop, the low byte of the scrolled character (at
location $98 + $26 = $BE) is stored in screen location 1942 ($0770 + $26), so the
(space) character in $0CBE is stored in screen location $0796. The third time through
the loop, $0CBD is stored in $0795 and so on. This process continues until the X and
Y registers equal zero. So far, only the series of 39 space characters in lines 2040 and
2050 have been shifted across the screen.

257

258

COMMODORE 128

Once the X and Y registers have been decremented to zero, the TXTPTR is
incremented in line 1890 so that subsequent characters such as 4 'THlS lS AN EXAMPLE . . . " can be scrolled. In the first 39 cycles through the loop (in lines 1840 through
1880) 39 spaces are shifted (scrolled) one character position on the twenty-third character
row on the screen. The next 39 cycles shift 38 spaces and the letter U T " in " T H I S " one
character position across the screen. The next 39 cycles, 37 spaces and the letters " T H "
in ' T H I S " are shifted in memory and scrolled one character position on the screen and
so on. This process occurs until all characters in the data (in lines 2040 through 2130)
are scrolled.
Line 1900 branches to the label MVTIME while TXTPTR (the low byte of the
start of scrolled data) is greater than zero, otherwise TXTPTR + 1 incremented to update
the high byte. Lines 1920 through 1970 check to see if the text pointers are at the end of
the scrolled character data ($0D70 in the assembled program). If the pointers are not at
the end of the character data, the program branches to the label CHECK and the data is
shifted by the VIC chip by seven pixels and the scrolling process repeats again. If the
text pointers are at the end of the scrolled character data, lines 1980 through 2010 set the
text pointers to the beginning of the scrolled data in memory and the process is repeated
continuously as specified by the JMP CHECK instruction.
Lines 2040 through 2130 represent the data to be scrolled by the program. The
data is stored in .BYTE statements as it appears in the Commodore Assembler 64
Development System. In your case, the Machine Language Monitor handles data by
simply storing it in an absolute memory range. In the assembled object code program
the data turns out to be stored in the range $0C98 through $0D70. You will refer to the
data with these addresses and not with a label as in this explanation.

THE INTERRUPT SERVICE ROUTINE

The program instructions in lines 2170 through the end of the program make up the
interrupt service routine. Depending upon the value of the raster comparison, particular
segments of the routine are executed upon the detection of an interrupt. For instance, if
the result of the raster comparison detects an interrupt to occur at raster row 49, lines
2290 through 2560 are executed. This selects bit map mode and performs additional
functions that are explained in a moment. If the raster comparison detects the interrupt
to occur at raster row 201, lines 2590 through 2900 are executed. These instructions
select standard character mode, among other things. Keep in mind that both segments of
the interrupt service routine are executed within a single, complete raster scan of the
screen sixty times per second. Instructions 2170 through 2270 are always executed when
an interrupt occurs.
The instruction in line 2170 clears the raster compare IRQ flag after the interrupt
has occurred. The address of the label MINE, which is loaded into the IRQ vector in
lines 1480 through 1510, tells the 8502 where the interrupt service routine resides upon
the occurrence of an interrupt. In the assembled object code, this is an absolute address
($0D71).

THE POWER BEHIND COMMODORE 128 GRAPHICS

Lines 2200 through 2270 determine the location (raster row) in which the raster
interrupt has occurred. Line 2200 loads the value of FLAG, which was initialized to
zero, into the accumulator. Line 2210 XOR's the accumulator with 1, which effectively
places a one in the accumulator for the first pass through this routine. This value is then
stored back into FLAG. In each subsequent occurrence of an interrupt, the value of both
the accumulator and FLAG are toggled between zero and one. The accumulator is then
transferred to the X register in line 2230. Line 2240 loads the value of POINT or POINT
4-1 depending upon the value in the X register. If the X register equals 0, POINT is
loaded into the accumulator, which specifies the interrupt to occur at raster row 49. If
the X register equals 1, POINT + 1 is loaded into the accumulator, which specifies the
interrupt to occur at raster row 201. Line 2250 stores the accumulator value into the
variable RASTRO. The X register is compared with 1 in line 2260. If the X register
equals 1, the interrupt has occurred at raster row 201 and the program branches to the
instructions in lines 2590. If the value of the X register equals 0, the branch in line 2270
falls through and the instructions in lines 2290 through 2650 are performed.
The instructions in lines 2290 through 2560 perform the operations associated with
bit map mode. Lines 2290 through 2310 select bit map mode. Lines 2320 through 2340
set the video matrix at $1C00 and the bit map at $2000. Both of these start addresses are
offset by the compulsory $4000, since this screen appears in video bank 1 ($4000-$7FFF).
Lines 2350 through 2370 set multi-color mode. Lines 2390 through 2410 select video
bank 1. Lines 2430 through 2460 set the lower two bits of the scrolling register (to the
value 3).
The instructions in 2510 through 2550 restore the original values of the X, Y and
A (accumulator) registers. Line 2560 returns from the interrupt and exits the interrupt
service routine.
Lines 2590 through 2900 perform all the associated text mode operations. Lines
2590 through 2610 select standard character mode. Lines 2630 through 2650 changes
back to video bank 0, the default bank ($0000-$3FFF). Lines 2670 through 2690 disable
multi-color mode, and return to the standard color mode. Lines 2710 and 2720 set the
default screen location 1024 ($0400) and the default start of character memory, with the
decimal value 23 ($17). All numbers which are not preceded by a dollar sign are
assumed to be decimal in this particular assembler editor. Lines 2740 and 2750 set the
background color for the text screen to black.
Lines 2760 through 2890 set the value of the scrolling register, which scrolls the
characters across the screen by 7 pixels, before they are shifted in memory with the
routine in lines 1840 through 1880.
Finally, line 2900 jumps to the default IRQ vector which was saved early in the
program into the variable TEMP. This allows the 8502 to process the normal interrupt
services as though this program's service routine had not occurred.
Although this program example is long and complex, it contains useful routines
and explanations that have never appeared before in any Commodore text. Study these
routines carefully and add them into your own programs. This section includes a wealth
of information for the novice and experienced software developer alike. Figures 8-28
through 8-32 on the following four pages provide a summary of graphics programming.

259

260

COMMODORE 128

CI28
BASIC

CHANGING VIDEO BANKS

MOVING SCREEN RAM

POKE 56576, (PEEK (56576)

AND 252) OR X

TEXT

WHERE X IS THE DECIMAL

VALUE OF BITS 0 AND 1 IN
TABLE 8-30 ON PAGE 262

POKE 2604, (PEEK(2604 AND 15)

OR X
WHERE X IS THE DECIMAL
VALUE IN TABLE 8-29 ON P. 262
BIT MAP

POKE 2605, (PEEK(2605 AND 15)

OR X
WHERE X IS A VALUE IN
TABLE 8-29 ON P. 262
CI28
MACHINE
LANGUAGE

LDA $DD00
AND #$FC
ORA #$X
STA $DD00
WHERE X IS THE HEX VALUE
OF THE BITS IN TABLE 8-30 ON
P. 262

C64
BASIC

POKE 56576, (PEEK (56576)

AND 252) OR X
WHERE X IS THE DECIMAL
VALUE OF BITS 0 and 1 IN
TABLE 8-30 on P. 262

C64
MACHINE
LANGUAGE

LDA $DD00
AND #$FC
ORA #$X
STA $DD00
WHERE X IS THE HEX VALUE
OF BITS 0 AND 1 IN
TABLE 8-30 ON P. 262

TEXT

BIT MAP

LDA$0A2C LDA$0A2D
AND #$0F
AND #$0F
ORA #$X
ORA #$X
STA $0A2C STA $0A2D
WHERE X IS A HEX EQUIVALENT OF THE DECIMAL
VALUE IN FIGURE 8-29 ON P.
262
TEXT OR BIT MAP

POKE 53272, (PEEK(53272)

AND 15) OR X
WHERE X IS A DECIMAL
VALUE IN FIGURE 8-29 ON P.
262

TEXT OR BIT MAP

LDA $D018
AND #$0F
ORA #$X
STA $D018
WHERE X IS A HEX
EQUIVALENT OF THE DECIMAL
VALUE IN FIGURE 8-29 ON P.
262
IN C64 MODE, YOU CAN SET
UP TWO DIFFERENT SCREENS,
ONE FOR TEXT AND THE
OTHER FOR BIT MAP, AS THE
C128 KERNAL DOES.

Figure 8-28. Graphics Programming SummaryPART I

THE POWER BEHIND COMMODORE 128 GRAPHICS

MOVING CHARACTER MEMORY

ACCESSING CHARACTER ROM

TEXT

10 BANK 14: REM SWAP IN CHAR ROM

20 FOR I = 0 TO 7
30 ? PEEK (I)
40 NEXT
50 BANK 15

POKE 2604, (PEEK(2604)AND 240) OR Z

BIT MAP*

POKE 2605, (PEEK (2605)AND 240) OR Z

WHERE Z IS A DECIMAL VALUE
IN FIGURE 8-31 ON P. 262
* = ONLY BIT 3 IS SIGNIFICANT
IN BIT MAP MODE

TEXT

BIT MAP*

LDA $0A2C
AND #$F0
ORA #$Z
STA $0A2C

LDA $0A2D
AND #$F0
ORA #$Z
STA $0A2D

WHERE Z IS THE HEX EQUIVALENT OF

A DECIMAL VALUE IN FIGURE 8-31 ON
P. 262
* = ONLY BIT 3 IS SIGNIFlCANT IN BMM
TEXT OR BIT MAP*

POKE 53272, (PEEK(53272)AND240) OR Z

WHERE Z IS A DECIMAL VALUE IN
FIGURE 8-31 ON P. 262
* = ONLY BIT 3 IS SIGNIFICANT
IN BIT MAP MODE

TEXT OR BIT MAP*

LDA $D018
AND #$F0
ORA #$Z
STA $D018
WHERE Z IS THE HEX EQUIVALENT
OF A DECIMAL VALUE IN FIGURE
8-31 ON P. 262
* = ONLY BIT 3 IS SIGNIFICANT
IN BIT MAP MODE

LDA #$01
STA $FF00
LDX #$00
LDA #$D000,X
LOOP STA $TEMP,X
INX
CPX #$07
BNE LOOP
LDA #$00
STA $FF00
5 TEMP = 6144
10 POKE 56334,PEEK (56334) AND 254
20 POKE 1, PEEK (1) AND 251
30 FOR I = 0 TO 7
40 POKE (TEMP + I, PEEK (53248 + I)
50 NEXT
60 POKE 1, PEEK (1) OR 4
70 POKE 56334, PEEK (56334) OR 1
80 FOR I = TEMP TO TEMP + 7
90 ? PEEK (I);
100 NEXT
LDA $DC0E
AND #$FE
STA $DC0E
LDA $01
AND #$FB
STA $01
LDX #$00
LOOP LDA $D000,X
STA $TEMP,X
INX
CPX #$07
BNE LOOP
LDA $01
ORA #$01
STA $01
LDA $DC0E
ORA #$01
STA $DC0E

Figure 8-28. Graphics Programming SummaryPART 2

261

262

COMMODORE 128

L O C A T I O N*
X

BITS

DECIMAL

HEX

0
16
32
48
64
80
96
112
128
144
160
176
192
208
224
240

ooooxxxx
0001XXXX
0010XXXX
0011XXXX
0100XXXX
0101XXXX
0110XXXX
0111XXXX
1000XXXX
1001XXXX
1010XXXX
1011XXXX
1100XXXX
1101XXXX
1110XXXX
llllXXXX

0
1024
2048
3072
4096
5120
6144
7168
8192
9216
10240
11264
12288
13312
14336
15360

$0000
$0400 (DEFAULT)
$0800
$0C00
$1000
$1400
$1800
$1C00
$2000
$2400
$2800
$2C00
$3000
$3400
$3800
$3C00

*Remember that the BANK ADDRESS offset of $4000 for each video

bank above zero must be added to the screen memory address.

Figure 8-29. Screen Memory Locations

BANK

ADDRESS RANGE

0
1
2
3

$0-$3FFF
$4000-$7FFF
$8000-$BFFF
$C000-$FFFF

VALUE OF BITS 1 & 0 IN $DD00

BINARY DECIMAL

11 = 3 (DEFAULT)
10 = 2
01 = 1
00 = 0

Figure 8-30. Video Bank Memory Ranges

LOCATION

OF C H A R A C T E R

MEMORY*

VALUE
OFZ

BITS

DECIMAL

HEX

0
2
4

xxxxooox
xxxxooix
XXXX010X

0
2048
4096

$0000-$07FF
$O8OO-$OFFF
$1000-$17FF

6
8
10
12
14

XXXX011X
XXXX100X
XXXX101X
XXXX110X
XXXXlllX

6144
8192
10240
12288
14336

$1800-$lFFF
$2000-$27FF
$2800-$2FFF
$3000-$37FF
$3800-$3FFF

ROM IMAGE in BANK 0 & 2

(defauIt)*
ROM IMAGE in BANK 0 & 2*

Remember to add an offset of $4000 to the start address of character memory for each
bank above 0; for bank 3 add 3*$4000 = $C000
in C64 mode only.

Figure 8-31. Character Memory Locations

T H E POWER B E H I N D C O M M O D O R E 128 GRAPHICS

SCREEN DATA

COLOR DATA

263

CHARACTER DATA

TEXT

BIT MAP

TEXT

BIT MAP

TEXT

BIT MAP

C128 BASIC
(DEFAULTS)

10242023
($0400-$07E7)

7168-8167
($1C00$lFE7)

55296-56295
($D800$DBE7)

*TAKEN
FROM BIT
MAP VIDEO
MATRIX

53248-57343
($D000$DFFF)

8192-16383
($2000-$3FFF)

C128
MACHINE
LANGUAGE

1024-2023
($0400-$07E7)

7168-8167
($lC00-SlFE7)

8192-16383

53248-57343

($2000-$3FFF)

THIS IS
ALSO PROGRAMMABLE
SEE
GRAPHICS
SUMMARY

*TAKEN
FROM BIT
MAP VIDEO
MATRIX

TEXT

THIS IS
ALSO PROGRAMMABLE

55296-56295
($D800$DBE7)

1024-2023
($0400-$07E7)

1024-2023
($0400-$07E7)

55296-56295
($D800$DBE7)

*TAKEN
FROM BIT
MAP VIDEO
MATRIX

ROM IMAGE
IS AT
4096-8191*
($1000l$FFF)

1024-2023
($0400-$07E7)

55296-56295
($D800$DBE7)

*TAKEN
FROM BIT
MAP VIDEO
MATRIX
UPPER
NYBBLE =
FOREGROUND
LOWER
NYBBLE =
BACKGROUND

ROM IMAGE

C64 BASIC
(DEFAULTS)

THIS IS
ALSO PROGRAMMABLE

C64
MACHINE
LANGUAGE

10242023
($0400-$07E7)

THIS IS ALSO PROGRAMMABLE

$DFFF)

4096^8191 *
($1000-$lFFF)

i s i s

ALSO PROGRAMMABLE
SEE
GRAPHICS
SUMMARY
NO DEFAULT
MUST
BEPROGRAMMED
SEE
GRAPHICS
SUMMARY
NO DEFAULT
^ T B E
O R A M M E D

SEE
GRAPHICS
* = actual characier
ROM location =
53248-57343
($DOOO-DFFF)

Figure 8-32. Default Graphics Memory Locations

N O T E : These locations pertain to video bank zero (0) only.

SUMMARY

9
SPRITES

265

266

COMMODORE 128

SPRITES:
MOVABLE OBJECT BLOCKS
A sprite is a movable bit-mapped object that you can define into a particular shape for
display on the screen. The sprite image can be as large as 24 pixels wide by 21 pixels
tall. Each pixel corresponds to a bit in memory in the sprite storage range; therefore,
each sprite requires 63 bytes of storage. The C128 has predefined storage locations for
sprite data in the range 3584 ($0E00) through 4095 ($0FFF).
The C128 graphics system has 8 sprites. Each sprite moves on its own independent plane. A sprite may move in front of or behind objects or other sprites on the
screen, depending on the specified priority. Standard bit-mapped sprites may be any one
of the sixteen available colors. Multi-color sprites may have three colors. The colors that
are assigned to the pixels within the sprite depend on the bit patterns of the image. In
sprite storage memory, the on bits (1) enable the sprite pixels to display the color
selected by the sprite color register; the off bits (0) disable the corresponding sprite pixels,
making them transparent and thus allowing the background color to pass through and be
displayed. Sprites also can be expanded to twice the normal size in both vertical and
horizontal directions.
Most of the commercially available graphics software packages for the Commodore 128 and C64 rely on sprites. For graphics programming applications, sprites offer
superior animation capabilities. Single sprites are useful for small moving objects.
However, you can adjoin and overlay several sprites to give greater detail to animated
graphic images. For example, suppose you are writing a program that animates a person
running on the screen. You can make the image of the person as a single sprite, but the
effect looks much more realistic if you allocate separate sprites for different parts of the
person's body. The arms can be one sprite, the body another, and the legs a third. Then,
you can define two additional sprites: one as a second set of legs in a different position,
and the other as a second set of arms in a different position. Position the first set of
arms, the body and the first set of legs on the screen so that they are joined into a full
body. By continually turning on and off the two different sets of arms and legs, the
image appears to be running. This process involves overlaying and adjoining sprites.
The explanation given here is a simplified algorithm, and the actual programming can be
tricky. Sprite programming has been made easy with the new BASIC 7.0 sprite
commands.
The first part of this section explains the new BASIC sprite commands and
illustrates the procedure for overlaying and adjoining sprites. The second part
explains the internal operations of sprites, including storage information, color assignments, sprite expansion and addressing the sprite registers in machine language.

SPRITES

BASIC 7.0
SPRITE COMMAND SUMMARY
Here's a brief description of each BASIC 7.0 sprite command:
COLLISION: Defines the type of sprite collision on the screen, either sprite to sprite or
sprite to data collision
MOVSPR: Positions or moves sprites from one screen location to another
SPRCOLOR: Defines colors for multi-color sprites
SPRDEF: Enters sprite definition mode to edit sprites
SPRITE: Enables, colors, sets sprite screen priorities, and expands a sprite
SPRSAV: Stores a text string variable into a sprite storage area and vice versa or
copies data from one sprite to another
SSHAPE: Stores the image of a portion of the bit-map screen into a text-string variable

BASIC 7.0
SPRITE COMMAND FORMATS
COLLISION
Define sprite collision priorities
where:
COLLISION type [,statement]
type

statement

Type of collision, as follows:

1 = Sprite-to-sprite collision
2 = Sprite-to-display data collision
3 = Light pen (40 columns only)
BASIC line number of a subroutine

EXAMPLE:
COLLISION 1,5000

Detects a sprite-to-sprite collision and program control sent

to subroutine at line 5000.

COLLISION 1

Stops interrupt action which was initiated in above example.

COLLISION 2,1000

Detects sprite-to-data collision and program control directed

to subroutine in line 1000.

MOVSPR
Position or move sprite on the screen (using any of the following four formats):
1.

MOVSPR number ,X,Y

Place the specified sprite at absolute

sprite coordinate X,Y.

267

268

COMMODORE 128

2.

MOVSPR number, + X, + Y

3.

MOVSPR number, X;Y

4.

MOVSPR number, angle # speed

Move sprite relative to its current

position.
Move sprite distance x at angle y
relative to its current position.
Move sprite at an angle relative to its
original coordinates, in the clockwise
direction and at the specified speed.

where:
number is sprite's number (1 through 8)
X , Y > is coordinate of the sprite location.
ANGLE is the angle (0-360) of motion in the clockwise direction relative to the sprite's
original coordinate.
SPEED is the speed (0-15) at which the sprite moves.
This statement positions a sprite at a specific location on the screen according to
the SPRITE coordinate plane (not the bit map plane). MOVSPR also initiates sprite
motion at a specified rate. This chapter contains a diagram of the sprite coordinate
plane.
EXAMPLES:
MOVSPR 1, 150, 150

Position sprite 1 at coordinate 150,150.

MOVSPR 1, 4- 20, + 30 Move sprite 1 to the right 20 (X) coordinates and down
30 (Y) coordinates.
MOVSPR 4, 50; 100

Move sprite 4 by 50 coordinates at a 100 degree

angle.

MOVSPR 5, 45 # 1 5

Move sprite 5 at a 45 degree angle in the clockwise

direction, relative to its original x and y coordinates.
The sprite moves at the fastest rate (15).

NOTE: Once you specify an angle and a speed in the fourth form of the
MOVSPR statement, the sprite continues on its path (even if the sprite
is disabled) after the program stops, until you set the speed to zero (0)
or press RUN/STOP and RESTORE.

SPRCOLOR
Set multi-color 1 and/or multi-color 2 colors for all sprites
SPRCOLOR [smcr-1] [,smcr-2]
where:

SPRITES

smcr-1
smcr-2

Sets multi-color 1 for all sprites.

Sets multi-color 2 for all sprites.

Either of these parameters may be any color from 1 through 16.

EXAMPLES:
SPRCOLOR 3,7

Sets sprite multi-color 1 to red and multi-color 2 to blue.

SPRCOLOR 1,2

Sets sprite multi-color 1 to black and multi-color 2 to white.

SPRDEF
Enter the SPRite DEFinition mode to create and edit sprite images.
SPRDEF
The SPRDEF command defines sprites interactively.
Entering the SPRDEF command displays a sprite work area on the screen which is
24 characters wide by 21 characters tall. Each character position in the grid corresponds
to a sprite pixel in the displayed sprite to the right of the work area. Here is a summary
of the SPRite DEFinition mode operations and the keys that perform them:

USER INPUT

DESCRIPTION

1-8 keys
A
CRSR keys
RETURN key
RETURN key

Selects a sprite number at the SPRITE NUMBER? prompt only.

Turns on and off automatic cursor movement.
Moves cursor.
Moves cursor to start of next line.
Exits sprite designer mode at the SPRITE
NUMBER? prompt only.
HOME key
Moves cursor to top left
corner of sprite work area.
CLR key
Erases entire grid.
1^1 keys
Selects color source and enables sprite pixels.
CTRL key, 1-8
Selects sprite foreground color (1-8).
Commodore key, 1-8 Selects sprite foreground color (9-16).
STOP key
Cancels changes and returns to prompt.
SHIFT RETURN
Saves sprite and returns to
SPRITE NUMBER? prompt.
X
Expands sprite in X (horizontal) direction.
Y
Expands sprite in Y (vertical) direction.
M
Multi-color sprite.
Copies sprite data from one sprite to another.
C

This SPRite DEFinition area is shown in Figure 9-1.

269

270

COMMODORE 128

i
Figure 9-1. SPRite DEFinition Area

SPRITE CREATION PROCEDURE IN

SPRITE DEFINITION MODE
Here's the general procedure to create a sprite in SPRite DEFinition mode:
1.
2.

3.

4.

Clear the work area by pressing the shift and CLR/HOME keys at the same
time.
If you want a multi-color sprite, press the M key and the cursor ( + ) appears
twice as large as the original one. The double-width cursor appears since
multi-color mode actually turns on two pixels for every one in standard
sprite mode. Multi-color sprites have only half the horizontal resolution of
standard sprites.
Select a sprite color. For colors between 1 and 8, hold down the CONTROL
key and press a key between 1 and 8. To select color codes between 9 and
16, hold down the Commodore (C1) key and press a key between 1 and 8.
Now you are ready to create the shape of your sprite. The numbered keys 1
through 4 fill the sprite and give it shape. For a single-color sprite, use the 2
key to fill a character position within the work area. Press the 1 key to erase
what you have drawn with the 2 key. If you want to fill one character

SPRITES

5.

6.

7.

8.
9.

10.

position at a time, press the A key. Now you have to move the cursor
manually with the cursor keys. If you want the cursor to move automatically
to the right while you hold it down, press the A key again. As you fill in a
character position within the work area, you can see the corresponding pixel
in the displayed sprite turn on. The sprite image changes as soon as you edit
the work area.
In multi-color mode, the 2 key fills two character positions in the work
area with the multi-color 1 color, the 3 key fills two character positions with
the multi-color 2 color.
You can turn off (color the pixel in the background color) filled areas
within the work area with the 1 key. In multi-color mode, the 1 key turns
off two character positions at a time.
While constructing your sprite, you can move freely in the work area
without turning on or off any pixels using the RETURN, HOME and cursor
keys.
At any time, you may expand your sprite in both the vertical and horizontal
directions. To expand vertically, press the Y key. To expand horizontally,
press the X key. To return to the normal size sprite display, press the X or Y
key again.
When a key turns on AND off the same control, it is referred to as
toggling, so the X and Y keys toggle the vertical and horizontal expansion of
the sprite.
When you are finished creating your sprite and are happy with the way it
looks, save it in memory by holding down the SHIFT key and pressing the
RETURN key. The Commodore 128 stores the sprites data in the appropriate sprite storage area. The displayed sprite in the upper right corner of the
screen is turned off and control is returned to the SPRITE NUMBER
prompt. If you want to create another sprite enter another sprite number and
edit the new sprite just as you did with the first one. If you want to display
the original sprite in the work area again, enter the original sprite number. If
you want to exit SPRite DEFinition mode, simply press RETURN at the
SPRITE NUMBER prompt.
You can copy one sprite into another with the O key.
If you do not want to SAVE your sprite, press the STOP key. The Commodore 128 turns off the displayed sprite and any changes you made are
cancelled. You are returned to the SPRITE NUMBER prompt.
To EXIT SPRite DEFinition mode, press the RETURN key while the
SPRITE NUMBER prompt is displayed on the screen without a sprite
number following it. You can exit under either of the following conditions:
Immediately after you SAVE your sprite in memory (shift RETURN)
Immediately after you press the STOP key

Once you have created a sprite and have exited SPRite DEFinition mode, your
sprite data is stored in the appropriate sprite storage area in the Commodore 128's

271

272

C O M M O D O R E 128

memory. Since you are now back in the control of the BASIC language, you have to
turn on your sprite in order to see it on the screen. To turn it on, use the SPRITE
command you learned. For example, you created sprite 1 in SPRDEF mode. To turn it
on in BASIC, color it blue and expand it in both the X and Y directions and enter this
command:
SPRITE 1,1,7,0,1,1,0
Now use the MOVSPR command to move it at a 90-degree angle at a speed of 5,
as follows:
MOVSPR 1, 90 # 5
Now you know all about SPRDEF mode. First, create the sprite, save the sprite
data and exit from SPRDEF mode to BASIC. Next, turn on your sprite with the SPRITE
command. Move it with the MOVSPR command. When you're finished programming,
SAVE your sprite data in a binary file with the BSAVE command as follows:
BSAVE "filename", B0, P3584 TO P4096 (This saves all 8 sprites.)

SPRITE
Turn on and off, color, expand and set screen priorities for a sprite
SPRITE number> [,on/off][,fngd][,priority] [,x^xp] [,y^xp] [,mode]
The SPRITE statement controls most of the characteristics of a sprite. The
brackets signify optional parameters. If you omit a parameter, you still must include a
comma in its place.

PARAMETER

DESCRIPTION

number
on/off
foreground
priority

Sprite number (1-8)

Turn sprite on (1) or off (0)
Sprite foreground color (1-16)
Priority is 0 if sprites appear in front of objects on the screen. Priority
is 1 if sprites appear in back of objects on the screen.
Horizontal expansion on (1) or off (0)
Vertical expansion on (1) or off (0)
Select standard sprite (0)
or multi-color sprite (1)

x^xp
y^xp
mode

Unspecified parameters in subsequent sprite statements take on the characteristics of the

previous SPRITE statement. You may check the characteristics of a SPRITE with the
RSPRITE function.
EXAMPLES:
SPRITE 1,1,3

Turn on sprite number 1 and color it red.

SPRITES

SPRITE 2,1,7,1,1,1

Turn on sprite number 2, color it blue, make it pass behind

objects on the screen and expand it in the vertical and
horizontal directions.

SPRITE 6,1,1,0,0,1,1

Turn on SPRITE number 6, color it black. The first 0

tells the computer to display the sprites in front of objects
on the screen. The second 0 and the 1 following it tell the
C128 to expand the sprite vertically only. The last 1
specifies multi-color mode. Use the SPRCOLOR command to select the sprite's multi-colors.

SPRSAV
Store sprite data from a text string variable into a sprite storage area or vice versa.
SPRSAV origin>, destination>
This command copies a sprite image from a string variable to a sprite storage area.
It also copies the data from the sprite storage area into a string variable. Either the origin
or the destination can be a sprite number or a string variable but both cannot be string
variables. If you are copying a string into a sprite, only the first 63 bytes of data are
used. The rest are ignored since a sprite can only hold 63 data bytes.
EXAMPLES:
SPRSAV l,A$

Copies the bit pattern from sprite 1 to the string variable A$.

SPRSAV B$,2

Copies the data from string variable B$ into sprite 2.

SPRSAV 2,3

Copies the data from sprite 2 to sprite 3.

SSHAPE
Save/retrieve shapes to/from string variables
SSHAPE and GSHAPE are used to save and load rectangular areas of multi-color
or bit-mapped screens to/from BASIC string variables. The command to save an area of
the screen into a string variable is:
SSHAPE string variable, XI, Y1 [,X2,Y2]
where:
string variable
X1,Y1
X2,Y2

String name to save data in

Corner coordinate (0,0 through 319,199) (scaled)
Corner coordinate opposite (X1,Y1) (default is the PC)

Also see the LOCATE command described in Chapter 3 for information on the
pixel cursor.

273

274

COMMODORE 128

EXAMPLES:
SSHAPE A$,10,10

SSHAPE B$,20,30,47,51

SSHAPE D $ , + 10, + 10

Saves a rectangular area from the coordinates 10,10 to

the location of the pixel cursor, into string variable A$.
Saves a rectangular area from top left coordinate
(20,30) through bottom right coordinate (47,51) into
string variable B$.
Saves a rectangular area 10 pixels to the right and 10
pixels down from the current position ofthe pixel cursor.

ADJOINING SPRITES
The following program is an example of adjoining sprites. The program creates an outer
space environment. It draws stars, a planet and a spacecraft similar to Apollo. The spacecraft
is drawn, then stored into two data strings, A$ and B$. The front of the spaceship, the capsule, is stored in sprite 1. The back half of the spaceship, the retro rocket, is stored in
sprite 2. The spacecraft flies slowly across the screen twice. Since it is traveling so slowly
and is very far from Earth, it needs to be launched earthward with the retro rockets. After the
second trip across the screen, the retro rockets fire and propel the capsule safely toward Earth.
Here's the program listing:
5 COLOR 4,1:COLOR O,l:COLOR l,2:REM SELECT BLACK BORDER & BKGRND, WHITE FRGRD
10 GRAPHIC l,l:REM SET HI RES MODE
17 FOR I=lT04 0
18 X = INT(RND(1 )* 3 2 0 )+1 :REM DRAW STARS
19 Y=INT(RND(l)*200)+l:REM DRAW STARS
21 DRAW l,X,Y:NEXT
:REM DRAW STARS
22 BOX 0,0,5,70,40,,l:REM CLEAR BOX
23 BOX l,l,5,70,40:REM BOX-IN SPACESHIP
24 COLOR 1,8:CIRCLE l,190,90,35,25:PAINT l,190,95:REM DRAW & PAINT PLANET
25 CIRCLE 1 , 190 , 90 , 65 , 10 :CIRCLE l, 190 , 93 , 65 , 10 :CIRCLE l, 190 , 95 , 65 , 10:COLOR 0,1
26 DRAW 1,10,17 TO 16,17 TO 32,10 TO 33,20 TO 32,30 TO 16,23 TO 10,23 TO 10,17
28 DRAW 1,19,24 TO 20,21 TO 27,25 TO 26,28:REM BOTTOM WINDOW
3 5 DRAW 1,20,19 TO 2 0,17 TO 29,13 TO 30,18 TO 28,23 TO 20,19:REM TOP WINDOW
38 PAINT l,13,20:REM PAINT SPACESHIP
40 DRAW 1,34,10 TO 36,20 TO 34,30 TO 45,30 TO 46,20 TO 45,10 TO 34,10:REM SP1
42 DRAW 1,45,10 TO 51,12 TO 57,10 TO 57,17 TO 51,15 TO 46,17:REM ENG1
4 3 DRAW 1,46,22 TO 51,24 TO 57,22 TO 57,29 TO 51,27 TO 45,29:REM ENG2
4 4 PAINT 1,4 0,15:PAINT l,47,12:PAINT l, 47 , 26 :DRAW 0 , 45 , 30 TO 46 , 20 TO 45,10
4 5 DRAW 0,3 4,14 TO 4 4,14 :DRAW 0 , 3 4 , 21 TO 4 4,21:DRAW 0 , 3 4 , 2 8 TO 4 4,2 8
47 SSHAPE A $, 10 , 10,3 3 , 3 2 :REM SAVE SPRITE IN A$
48 SSHAPE B$, 34 , 10, 57 , 32:REM SAVE SPRITE IN B$
50 SPRSAV A$,l:REM SPRl DATA
55 SPRSAV B$,2:REM SPR2 DATA
60 SPRITE 1,1,3,0,0,0,0:REM SET SPRl ATTRIBUTES
65 SPRITE 2,1,7,0,0,0,0:REM SET SPR2 ATTRIBUTES
82 MOVSPR 1,150 ,150:REM ORIGINAL POSITION OF SPRl
83 MOVSPR 2,172 ,150:REM ORIGINAL POSITION OF SPR2
85 MOVSPR 1,270 # 5 :REM MOVE SPRl ACROSS SCREEN
87 MOVSPR 2,270 # 5 :REM MOVE SPR2 ACROSS SCREEN
90 FOR I = lTO 5950:NEXT:REM DELAY
92 MOVSPR 1 , 150, 150:REM POSITION SPRl FOR RETRO ROCKET LAUNCH
9 3 MOVSPR 2, 174, 150:REM POSITION SPR2 FOR RETRO ROCKET LAUNCH
95 MOVSPR 1,270 # 10 :REM SPLIT ROCKET
9 6 MOVSPR 2, 9 0 # 5 :REM SPLIT ROCKET
97 FOR I = lTO 1200 :NEXT:REM DELAY
98 SPRITE 2,0:REM TURN OFF RETRO ROCKET (SPR2)
99 FOR I = lTO 20500:NEXT:REM DELAY
100 GRAPHIC 0,1:REM RETURN TO TEXT MODE

SPRITES

Here's an explanation of the program:

Line 5 COLORs the background black and the foreground white.

Line 10 selects standard bit map mode and clears the bit map screen.
Lines 17 through 21 DRAW the stars.
Line 23 BOXes in a display area for the picture of the spacecraft in the top-left
corner of the screen.
Line 24 DRAWs and PAINTs the planet.
Line 25 DRAWs the CIRCLEs around the planet.
Line 26 DRAWs the outline of the capsule portion of the spacecraft.
Line 28 DRAWs the bottom window of the space capsule.
Line 35 DRAWs the top window of the space capsule.
Line 38 PAINTs the space capsule white.
Line 40 DRAWs the outline of the retro rocket portion of the spacecraft.
Line 42 and 43 DRAW the retro rocket engines on the back of the spacecraft.
Line 44 PAINTs the retro rocket engines and DRAWs an outline of the back of the retro
rocket in the background color.
Line 45 DRAWs lines on the retro rocket portion of the spacecraft in the background
color. (At this point, you have displayed only pictures on the screen. You have
not used any sprite statements, so your rocketship is not yet a sprite.)
Line 47 positions the SSHAPE coordinates above the first half (24 by 21 pixels) of the
capsule of the spacecraft and stores it in a data string, A$.
Line 48 positions the SSHAPE coordinates above the second half (24 by 21 pixels) of
the spacecraft and stores it in a data string, B$.
Line 50 transfers the data from A$ into sprite 1.
Line 55 transfers the data from B$ into sprite 2.
Line 60 turns on sprite 1 and colors it red.
Line 65 turns on sprite 2 and colors it blue.
Line 82 positions sprite 1 at coordinate 150,150.
Line 83 positions sprite 2, 23 pixels to the right of the starting coordinate of
sprite 1.
Lines 82 and 83 actually join the two sprites.
Lines 85 and 87 move the joined sprites across the screen.
Line 90 delays the program. This time, delay is necessary for the sprites to complete the
two trips across the screen. If you leave out the delay, the sprites do not have
enough time to move across the screen.
Lines 92 and 93 position the sprites in the center of the screen, and prepare the
spacecraft to fire the retro rockets.
Line 95 propels sprite 1, the space capsule, forward. The number 10 in line 95 specifies
the speed in which the sprite moves. The speed ranges from 0 (stop ) to 15
(fastest).
Line 96 moves the expired retro rocket portion of the spacecraft backward and off the
screen.

275

276

COMMODORE 128

Line 97 is another time delay so the retro rocket, sprite 2, has time to move off
the screen.
Line 98 turns off sprite 2, once it is off the screen.
Line 99 is another delay so the capsule can continue to move across the screen.
Line 100 returns you to text mode.

SPRITE PROGRAM EXAMPLES

The best way to create sprites is with SPRDEF. The following examples assume you
have created your sprites in SPRDEF mode.
The first example sprite program illustrates the use of the SPRITE and MOVSPR
commands. It positions all eight sprites so they appear to converge on one screen
location, then scatter in all eight directions. Here's the listing:
10
20
30
40
50
60
70
80

REM MOVE SPRITE EXAMPLE

FOR 1=1 TO 8
MOVSPR 1,100,100
NEXT
FOR 1=1 TO 8
SPRITE 1, 1,1, 1 , 1 , 1 , 0
MOVSPR I,I*30 # I
NEXT

Lines 20 through 40 place all eight sprites at sprite coordinate location 100,100.
At this point, the sprites are not yet enabled, but when they are, all eight are on top of
one another.
Lines 50 and 60 turn on each of the eight sprites in eight different colors. The first
" I " is the sprite number parameter. The first " 1 " in line 60 signifies the enabling of
each sprite. The second ' T " specifies the color code for each sprite. The second " 1 "
(the fourth parameter) sets the display priority for all the sprites. A display priority of
one tells the C128 to display the sprites behind objects on the screen. A zero display
priority enables sprites to pass in front of objects on the text or bit-map screen. The fifth
and sixth parameters, both of which are ones (1), expand the sprites' size in both the
vertical and horizontal directions to twice their original size. The final parameter in the
SPRITE statement selects the graphics display mode for the sprites; either standard
bit-map sprites (0) or multi-color bit-map sprites (1). In this example, the sprites are
displayed as standard bit-map sprites.
Line 70 moves the sprites on the screen. The first parameter, I, represents the
sprite number. The second parameter, "1*30", defines the angle at which the sprites
travel on the screen. The pound sign ( # ) notation signifies that the sprites move
according to a particular angle and speed. The final parameter " I " specifies the speed at
which the sprites travel on the screen. In this example, sprite 1 moves at the slowest rate
of 1, sprite 2 moves at the next highest speed of 2, while sprite 8 moves the fastest of
the eight sprites at speed 8. The highest speed a sprite can move is 15.
Finally, line 80 completes the FOR . . . NEXT structure of the loop.

SPRITES

Notice that the sprites move continuously even after the program has stopped
RUNning. The reason for this is that sprites are wedged into the interrupt processing of
the C128. To turn off and stop the sprites on the screen, either issue a SPRITE
command that turns them off, or press RUN/STOP and RESTORE.
The second sprite program example provides a simplified adjoining sprite algorithm. It moves two adjoined sprites across the screen at a ninety-degree angle,
assuming that your sprites already reside in the sprite storage range between 3584
($0E00) and 4095 ($0FFF). For simplicity, if you don't have any actual sprite images
stored in the sprite data area, fill the sprite data area with 255 ($FF) from within the
Machine Language Monitor with this command:
F 0E00 0FFF FF
For now, this command turns on all pixels within each sprite. Now you can see
how the adjoining algorithm places and moves sprites 7 and 8 side by side.
Here's the listing:
10 REM ADJOINING SPRITE ALGORITHM
20 REM THIS PROGRAM ASSUMES YOUR SPRITES ALREADY EXIST IN SPRITE STORAGE
30 1=1 :REM INITIALIZE DISTANCE I
3 5 SCNCLR
40 MOVSPR 8,50,100:REM SET ORIG POSITION OF SPRITE 8
50 MOVSPR 7,7 3,100:REM SET ORIG POSITION OF SPRITE 7 TO ADJOIN SPR 8
60 DO
70 SPRITE 8,1,3:REM ENABLE SPR 8
80 SPRITE 7,l,4:REM ENABLE SPR 7
90 MOVSPR 8,1 ;90:REM MOVE SPR 8 I UNITS AT A 9 0 DEGREE ANGLE
100 MOVSPR 7,1 ;90:REM MOVE SPR 8 I UNITS AT A 9 0 DEGREE ANGLE
110 1=1+1 :REM INCREMENT LOOP
120 LOOP

Line 30 initializes the distance variable I to 1.

Line 40 positions sprite 8 at absolute coordinates 50,100. Since this program
moves two adjoining sprites from the left to right at a ninety-degree angle, sprite 7,
which is attached to sprite 8 must be positioned in such a way that it is touching the right
edge of sprite 8. Line 50 places sprite 7 on the exact right edge of sprite 8. Since a sprite
is 24 pixels wide (before expansion), to adjoin two sprites together, place the ajoining
sprite exactly 24 pixels to the right of the top left corner coordinate position of sprite 8.
The position of a sprite is placed on the sprite coordinate plane according to the upper
leftmost pixel of the sprite. Since the original position of sprite 8 is 50,100, add 24
(inclusive) to the X (horizontal) coordinate to make them join exactly on the respective
edges of both sprites. This is provided your sprites are exactly 24 pixels wide. If you
don't fill the entire dimensions of a sprite, you may have to adjust the coordinates so
that they meet correctly.
At this point, the sprite coordinates are perfectly adjoined. Line 60 initiates a loop,
so that the distance can be updated to enable the sprites' movement across the screen.
Lines 70 and 80 enable sprites 8 and 7 and color them red and cyan, respectively.
Lines 90 and 100 move sprite 8 and 7, respectively, at a 90-degree angle
according to the distance specified by the variable I. Line 110 updates the distance of 1
each cycle through the loop. Line 120 circulates the loop until the distance variable I is
equal to 320.

277

278

COMMODORE 128

The third sprite example provides an algorithm to overlay two sprites and move
them on the screen on a 45-degree angle. Again, this program assumes your sprite data
resides in sprite storage. If your sprite images are not stored there, fill the sprites with
data as you did in the last adjoining example.
Here's the listing:
10 REM OVERLAY EXAMPLE
20 REM THIS PROGRAM ASSUMES SPRITE DATA RESIDES IN SPRITE STORAGE
30 1=1 :REM INITIALIZE DISTANCE I
3 5 SCNCLR
40 MOVSPR 8,50,10 0:REM SET ORIG POSITION OF SPRITE 8
50 MOVSPR 7,50,100:REM SET ORIG POSITION OF SPRITE 7 TO OVERLAY SPR 8
60 DO
70 SPRITE 8,1,3
:REM ENABLE SPR 8
8 0 MOVSPR 8,I;45 :REM MOVE SPR 8 I UNITS AT A 4 5 DEGREE ANGLE
90 SPRITE 8,0,3
:REM TURN OFF SPR8
100 SPRITE 7,1,4 :REM ENABLE SPR 7
110 MOVSPR 7,I;45 :REM MOVE SPR 8 I UNITS AT A 4 5 DEGREE ANGLE
120 SPRITE 7,0,3 :REM TURN OFF SPR 7
14 0 LOOP

As in the last program, line 30 initializes the distance variable I to 1.

Lines 40 and 50 position sprites 8 and 7, respectively, at coordinate 50,100. At
this point the sprites are not yet enabled, but when they are, sprite 7 will overlay sprite 8
since the lower sprite number has display priority over the higher sprite number.
Line 60 initiates a DO loop to move the sprites along the sprite coordinate plane.
Line 70 enables sprite 8 and colors it red. Line 80 moves sprite 8 a distance of one
coordinate according to the current value of I. Line 90 disables sprite 8.
Lines 100 through 120 perform the same operations for sprite 7 as lines 70 through
90 did for sprite 8: enable, move a single distance coordinate according to I and disable.
Line 140 repeats the process.
Since this process is repeated so quickly, it appears as though the two sprites
alternate movements. When you create the actual images you will use in your overlay
sprite program, the images between which you alternate will be ones that simulate the
movement of two images and create one animated image.
Create two sprites that appear to form a single animated image. You may have to
perfect the timing of the enabling and disabling of the images to make the animated
image appear more smooth. Nonetheless, you have a basis for animating two objects
into one single moving object.
Although these program examples are written in BASIC, the algorithms are the
same whether you are programming in BASIC or machine language. The next section
discusses sprite operations independent of the BASIC language. Since this section
explained sprites according to BASIC, the next section elaborates on the inner workings
of sprites from a machine level (language) perspective.

SPRITES

THE INNER WORKINGS OF SPRITES

You have seen how to create, move, color and expand sprites with the BASIC 7.0 sprite
commands. This section explains how to control sprites outside of the BASIC sprite
commands (except SPRDEF). This tells you which VIC registers are affected and the
specific bits that must be set or cleared to manipulate the sprite features.
Registers of the VIC chip control all aspects of sprites. The enabling of specific
bits in certain VIC registers turns on the features of the eight available sprites. The order
in which you turn on these features is critical to sprite animation. Following is a
summary of the steps necessary to display, color, move and expand sprites. Next to each
step is the VIC chip register or other memory location involved in each element of sprite
programming.

SPRITE PROGRAMMING SEQUENCE

REGISTERS INVOLVED

1.

Create the sprite image

Sprite Data Storage: 3584^095 ($0E00-$0FFF)

This is also programmable. You must change the sprite
pointer values.

2.

Point to the sprite data

Sprite Data Pointers: 2040-2047 ($07F8-$07FF), or

8184^191 ($lFF8-$lFFF) when the bit map screen has
been cleared with GRAPHIC 1,1

3.

Enable (turn on) the sprite

53269 ($D015) (bits 7-0, depending on sprite number)

4.

Color the sprite

Standard 53287-53294 ($D027-$D02E)

Multi-color 53276 ($D01C), 53285 ($D025), 53286 ($D026)

5.

Position the sprite

53248-53264 ($D000-$D010)

6.

Expand the sprite

53271 ($D017) (Y direction), 53277 ($D01D) (X direction)

7.

Define sprite display priorities

53275 ($D01B)

8.

Define sprite collision priorities

53278 ($D01E), 53279 ($D01F)

These registers control most sprite characteristics. Once you learn these programming
steps, you will be able to exercise full control over the display and movement of sprites.

CREATING THE SPRITE IMAGE

An easy way to create sprites on the C128 is through SPRite DEFinition mode
(SPRDEF). For an explanation of SPRDEF see the SPRDEF entry in the beginning of
this chapter. This section assumes your sprite image is already created, and it resides in
the sprite data storage area. Before leaving SPRDEF, remember to press the SHIFT key
and RETURN at the same time; this allows SPRDEF to store the sprite data in the sprite
data storage area. Press RETURN a second time to exit SPRDEF.
The Commodore 128 has a dedicated portion of memory ranging from decimal
address 3584 ($0E00) through 4095 ($0FFF), where sprite data is stored. This portion of

279

280

COMMODORE 128

memory takes up512 bytes. As you know, a sprite is 24 pixels wide by 21 pixels tall. In
standard sprites, each pixel corresponds to one bit in memory. If the bit in a sprite is off
(equal to 0), the corresponding pixel on the screen is transparent, which allows the
background to pass through the sprite. If a bit within a sprite is on (equal to 1), the
corresponding pixel on the screen is turned on in the foreground color as determined by
the sprite color registers. The combination of zeroes and ones produces the image you
see on the screen. Multi-color sprites assign colors differently. See the multi-color sprite
section later in this chapter for details.
Since a sprite is 24 by 21 pixels and each pixel is represented by one bit of storage
in memory, one sprite uses up 63 bytes of memory. See Figure 9 - 2 to understand the
storage requirements for a sprite's data.

12345678

12345678

12345678

1
2
3
4
5
6
7
8
9
10
11

12
13
14
15
16
17
18
19
20
21
Each Row = 24 bits = 3 bytes
Figure 9-2. Sprite Data Requirements
A sprite requires 63 bytes of data. Each sprite block is actually made up of 64
bytes; the extra byte is not used. Since the Commodore 128 has eight sprites and each
one consists of a 64-byte sprite block, the computer needs 512 ( 8 x 6 4 ) bytes to
represent the data of all eight sprite images.
The area where all eight sprite blocks reside starts at memory location 3584
($0E00) and ends at location 4095 ($0FFF). Figure 9 - 3 lists the memory address ranges
where each individual sprite stores its data.

SPRITES

$0FFF (4095 Decimal)

]Sprite 8
$0FC0
]Sprite 7
$0F80
]Sprite 6
$0F40
]Sprite 5
$0F00
]Sprite 4
$0EC0
]Sprite 3
$0E80
]Sprite 2
$0E40
]Sprite 1
$0E00 (3584 Decimal)
Figure 9-3. Memory Address Ranges for Sprite Storage
Keep in mind that sprites are referred to as 1 through 8 in BASIC, but 0 through 7
in machine language.

SPRITE POINTERS
The VIC chip needs to know where to look for the bit patterns (data) that make up the
sprite image in memory. The sprite pointers are used explicitly for this purpose.
Unlike the Commodore 64, the C128 has automatically filled the sprite data
pointers with values that direct the VIC chip to point to the data stored in the sprite data
range 3584 ($0E00) through 4095 ($0FFF). These sprite data pointers are located at
2040 ($07F8) through 2047 ($07FF) for sprites 0 and 7 respectively. They are also located
in the address range 8184 ($lFF8) through 8191 ($lFFF), once the bit map screen is
cleared with the GRAPHIC 1,1 command. The default contents of these locations are:
Hexadecimal
Decimal

38
56

39
57

3A 3B
58 59

3C
60

3D 3E
61 62

3F
63

To find the actual location where the sprite data pointers are looking for data in
memory, multiply the contents of the sprite data pointer by 64 (decimal). By multiplying
these values, you'll see that the pointers look for data in the default sprite storage
locations in Figure 9-3. See Figure 9 ^ for an illustration.
The way the Commodore 128 automatically points to the correct sprite data is convenient for programming, since it eliminates a step (provided the original values of the sprite
pointers have not been modified). If you want to store sprite data somewhere else in
memory, however, you'll have to change the original value of the sprite pointer (from
location 2040 through 2047, or 6184 through 8191) to a value that is equal to:
Start of Sprite Data / 64 = new contents of sprite pointer

281

292

COMMODORE 128

DATA POINTER

START OF

CONTENTS**

SPRITE DATA

Sprite 0 Data Pointer = 56

Sprite 1 Data Pointer = 57
Sprite 2 Data Pointer = 58
Sprite 3 Data Pointer = 59
Sprite 4 Data Pointer = 60
Sprite 5 Data Pointer = 61
Sprite 6 Data Pointer = 62
Sprite 7 Data Pointer = 63
** = This applies to video bank 0 only.

*
*
*
*

*
*
*

64
64
64
64
64
64
64
64

=
=
=
=
=
=
=
=

3584
3648
3712
3776
3840
3904
3968
4032

($0E00)
($0E40)
($0E80)
($0EC0)
($0F00)
($0F40)
($0F80)
($0FC0)

Figure 9-4. Sprite Data Locations

The start of sprite data is divided by 64 because the data area is allocated in 64-byte
sections. For example, you want to place your sprite 0 data in the new location 6144
($1800). Divide 6144 by 64 to get 96. Place the value 96 ($60) in address 2040 ($078F).

ENABLING A SPRITE
Once the sprite image has been defined, and the data pointer is pointing to the correct
data, you can turn on the sprite. You do this by placing a value in the Sprite Enable
Register, location 53269 ($D015). The value placed in this register depends on which
sprite(s) you want to turn on. Bits 0 through 7 correspond to sprites 0 through 7. To
enable sprite 0, set bit 0. To enable sprite 1, set bit 1 and so on. The value you
place in the sprite enable register is equal to two raised to the bit position in decimal.
If you are programming in machine language and want to enable more than one
sprite at a time, add the values of two raised to the bit positions together and store the
result in the sprite enable register. For example, to enable sprite 5, raise two to the fifth
power (32 ($20)) and store it as follows:
LDA # $ 2 0
STA $D015
To enable sprites 5 and 7, raise two to the fifth (32 ($20)) and add it to two to the
seventh (128($80)) to obtain the result 160 ($A0):
LDA $A0
STA $D015
An easier way of perceiving the idea is through binary notation in the Machine
Language Monitor as follows:
LDA
STA

# % 10100000
$D015

To disable the sprite display, clear the bits in the sprite enable register.

SPRITES

ASSIGNING COLOR T O SPRITES

Sprites have two kinds of color displays: standard bit-map and multi-color bit-map
sprites. The color assignments to the pixels within the sprites work in a similar way to
standard bit-map and multi-color bit-map modes for the screen.

STANDARD BIT-MAP SPRITES

Standard bit-map sprites each have their own color register. The lower four bits of each
sprite color register determine the sprite color as specified by the sixteen C128 color
codes. Figure 9 - 5 shows the standard bit-map sprite color registers.

ADDRESS

53287
53288
53289
53290
53291
53292
53293
53294

DESCRIPTION

($D027)
($D028)
($D029)
($D02A)
($D02B)
($D02C)
($D02D)
($D02E)

SPRITE
SPRITE
SPRITE
SPRITE
SPRITE
SPRITE
SPRITE
SPRITE

0 COLOR
1 COLOR
2 COLOR
3 COLOR
4 COLOR
5 COLOR
6 COLOR
7 COLOR

REGISTER
REGISTER
REGISTER
REGISTER
REGISTER
REGISTER
REGISTER
REGISTER

Figure 9-5. Standard Bit Map Sprite Color Registers

Figure 9 - 6 lists the color codes that are placed in the standard bit-map sprite color
registers:

0
1
2
3
4
5
6
7

Black
White
Red
Cyan
Purple
Green
Blue
Yellow

8
9
10
11
12
13
14
15

Orange
Brown
Light Red
Dark Gray
Medium Gray
Light Green
Light Blue
Light Gray

Figure 9-6. Sprite Color Codes

In standard bit-map sprites, the data in the sprite block determine how the colors
are assigned to the pixels on the screen within the visible sprite. If the bit in the
sprite storage block is equal to 1, the corresponding pixel on the screen is assigned
the color from the standard sprite color register. If the bit in the sprite data block

283

290

C O M M O D O R E 128

is equal to zero, those pixels on the sprite are transparent and the background data
from the screen passes through the sprite.

MULTI-COLOR SPRITES
Multi-color sprites offer a degree of freedom in the use of color, but you trade the
higher resolution of standard sprites for the added color. Multi-color sprites are displayed
in three colors plus a background color. Multi-color bit-map sprites are assigned colors
similar to the way the other multi-color modes work. Before you can assign a sprite
multiple colors, you must first enable the multi-color sprite. The sprite multi-color
register in location 53276 ($D01C) operates in the same manner as the sprite enable
register. Bits 0 through 7 pertain to sprites 0 through 7. To select a multi-color sprite,
set the bit number that corresponds to the sprite number. This requires that you raise
two to the bit position of the sprite that you want displayed in multi-color. For example,
to select sprite 4 as a multi-color sprite, raise two to the fourth power (16) and place
it in the multi-color sprite register. In machine language, perform the following
instructions:
LDA
STA

#$10
$D01C

To select more than one multi-color sprite, add the values of two raised to the bit
positions together and store the value in the multi-color sprite register.
The VIC chip provides two multi-color registers (0 and 1), in which to place color
codes. These are the locations of the sprite multi-color registers:

ADDRESS

Sprite Multi-Color Register 0

Sprite Multi-Color Register 1

53285 ($D025)
53286 ($D026)

The color codes are those listed in Figure 9 ^ .

Like multi-color character mode, the pixels in the multi-color sprites are assigned
color according to the bit patterns in the sprite storage block. In this mode, the bits in
the sprite block are grouped in pairs. The bit pair determines how the pixels are assigned
their individual colors, as follows:

BIT PAIR

00
01
10
11

DESCRIPTION

TRANSPARENT (SCREEN COLOR)

SPRITE MULTI-COLOR REGISTER # 0 (53285) ($D025)
SPRITE COLOR REGISTER
SPRITE MULTI-COLOR REGISTER #1 (53286) ($D026)

SPRITES

If the bit pair is equal to 00, the pixels are transparent and the background from
the screen passes through the sprite. If the bit pattern equals 10 (binary), the color is
taken from the sprite color register (locations 53287-53294) of the sprite being defined.
Otherwise, the other two bit pair possibilities (01 and 11) are taken from sprite
multi-color registers 0 and 1 respectively.

POSITIONING SPRITES O N THE SCREEN

Each sprite has two position registers to control the sprite's position on the visible screen:
horizontal (X coordinate) and vertical (Y coordinate) positions. Figure 9 - 7 gives the
memory locations of the sprite position registers as they appear in the C128 memory.

L O C A T IO N
DECIMAL

HEX

DESCRIPTION

53248
53249
53250
53251
53252
53253
53254
53255
53256
53257
53258
53259
53260
53261
53262
53263
53264

($D000)
($D001)
($D002)
($D003)
($D004)
($D005)
($D006)
($D007)
($D008)
($D009)
($D00A)
($D00B)
($D00C)
($D00D)
($D00E)
($D00F)
($D010)

SPRITE 0 X POSITION REGISTER

SPRITE 0 Y POSITION REGISTER
SPRITE 1 X POSITION REGISTER
SPRITE 1 Y POSITION REGISTER
SPRITE 2 X POSITION REGISTER
SPRITE 2 Y POSITION REGISTER
SPRITE 3 X POSITION REGISTER
SPRITE 3 Y POSITION REGISTER
SPRITE 4 X POSITION REGISTER
SPRITE 4 Y POSITION REGISTER
SPRITE 5 X POSITION REGISTER
SPRITE 5 Y POSITION REGISTER
SPRITE 6 X POSITION REGISTER
SPRITE 6 Y POSITION REGISTER
SPRITE 7 X POSITION REGISTER
SPRITE 7 Y POSITION REGISTER
SPRITE X MSB REGISTER

Figure 9-7. Memory Location of Sprite Position Register

The sprite position registers together plot the sprite on a vertical and horizontal
coordinate. The position of reference for the calculated vertical and horizontal coordinate is taken from the upper-left corner pixel within the sprite. Whenever you want to
place the sprite on a particular screen position, calculate the position using the upper left
corner pixel within the sprite. The sprite coordinate plane is not the same as the bit-map
coordinate plane. The bit-map coordinate plane starts in the upper-left corner of the
screen at coordinate 0,0. The lower right corner of the bit map coordinate plane is point
319,199. The sprite coordinate plane starts at point 24,50 in the top-left corner of the
visible screen. The final visible point on the sprite coordinate plane at the bottom-right
corner of the screen is 343,249. Figure 9 - 8 shows how the sprite coordinate plane
relates to the visible screen.

285

286

COMMODORE 128

0 ($00)

296 ($128)

24 ($18)

344

($158)

29

($1D)

50

($32) -

($08)

- - 50

($32)

VISIBLE VIEWING AREA

208

250

NTSC*
40 COLUMNS
25 ROWS

($D0)-

($FA)-

I
488

($1E8)

24 ($18)

320

($140)

229

($E5>

250

($FA)

I
344

($158)

' N o r t h American television transmission standards for your home TV.

Figure 9-8. Visible Sprite Coordinates

After seeing the sprite coordinate plane, you may have noticed something unusual.
The vertical coordinate positions have a range of 200. The horizontal coordinate
positions have a range of 320 coordinates. Since the Cl28 is an 8-bit computer, the
highest value any register can represent is 255.
How do you position a sprite past the 255th horizontal screen position? The
answer is, you have to borrow a bit from another register in order to represent a value
greater than 255.
An extra bit is already set aside in the Commodore 128 memory in case you want
to move a sprite past the 255th horizontal coordinate. Location 53264 controls sprite
movement past position 255. Each of the 8 bits in 53264 controls a sprite. Bit 0 controls
sprite 0, bit 1 controls sprite 1 and so on. For example, if bit 7 is set, sprite 7 can move
past the 255th horizontal position.
Each time you want a sprite to move across the entire screen, turn on the borrowed
bit in location 53264 when the sprite reaches horizontal position 255. Once the sprite
moves off the right edge of the screen, turn off the borrowed bit so the sprite can move
back onto the left edge of the screen. The following commands allow sprite seven to
move past the 255th horizontal position:

SPRITES

LDA
ORA
STA

$D010
#$80
$D010

The number 128 is the resulting decimal value from setting bit 7. You arrive at this
value by raising two to the seventh power. If you want to enable bit 5, raise two to the
fifth power, which, of course, is 32. The general rule is to raise two to the power of the
sprite number that you want to move past the 255th horizontal screen position. Now you
can borrow the extra bit you need to move a sprite all the way across the screen. To
allow the sprite to reappear on the left side of the screen, turn off bit seven again, as
follows:
LDA
AND
STA

$D010
#$7F
$D010

Not all of the horizontal (X) and vertical (Y) positions are visible on the screen.
Only vertical positions 50 through 249 and horizontal positions 24 through 343 are
visible. Location 0,0 is off the screen as is any horizontal location less than 24 and
greater than 343. Any vertical location less than 50 and greater than 249 is also off the
screen. The off-screen locations are set aside so that an animated image can move
smoothly on and off the screen.

EXPANDING THE SIZE OF SPRITES

The VIC chip offers a feature that allows sprites to be expanded in size, in both the
horizontal and vertical directions. When the sprite is expanded, the sprite resolution
does not increase, the pixels within the sprite just cover twice as much area; therefore,
the sprite is twice as large. Here are the locations in memory for vertical and horizontal
sprite expansion:

ADDRESS

Vertical (Y) Sprite Expansion Register

Horizontal (X) Sprite Expansion Register

53271 ($D017)
53277 ($D01D)

These registers operate in the same manner as the sprite enable register.
Bits 0 through 7 pertain to sprites 0 through 7. To expand the sprite size in either
direction, raise two to the bit position and place it in the expansion register(s). For
example, to expand sprite 7 in both directions, perform these machine language
instructions:
LDA
STA
STA

# $ 8 0 (%10000000 = binary notation in the Monitor)

$D017
$D01D

287

288

COMMODORE 128

To expand more than one sprite, add two raised to the bit position for the sprite
numbers you want to expand, and store the result in the expansion registers.
To return the sprites to their original size, clear the bits in the expansion
registers.

SPRITE DISPLAY PRIORITIES

In your sprite programs, you have the option of displaying sprites in front of or behind
other sprites or objects on the screen. This is known as defining the sprite's display
priorities. The VIC chip defines two distinct sprite display priorities:
1.
2.

Sprite-to-sprite
Sprite-to-data

SPRITE-TO-SPRITE DISPLAY PRIORITIES

Each of the eight sprites available on the Commodore 128 is assigned its own plane in
which it moves independent of other sprites or of the pictures on the screen background.
Visualize the sprite planes as in Figure 9-9.

Screen
Background
Plane
Sprite plane 7
Sprite plane 6
Sprite plane 5
Sprite plane 4
Sprite plane 3
Sprite plane 2

Sprite plane 1
Sprite plane 0
Figure 9-9. Relationship of Sprite Planes

The display priority of each sprite plane depends on the sprite number. The
sprite-to-sprite display priorities are predefined according to the sprite number. This

SPRITES

feature is preset by the C128 hardware, and is not controlled through a software
register. The lower the sprite number, the higher the priority. The higher priority sprite
passes in front of the lower priority sprite. Sprite 0 has the highest priority; therefore, it
passes in front of any other sprites that may be on the screen should they meet at a
particular screen location. For example, sprites 1 and 5 are moving toward a common
location on the screen. When the sprites reach the common location, sprite 1 passes in
front of sprite 5, since the lower sprite number has the higher display priority. Keep this
in mind when you want sprites to intersect paths and pass behind or in front of one
another. This is important when overlaying sprites. Assign the sprite you want to pass in
front of other sprites to the lower sprite number.
Portions of sprites (pixels) that are not assigned color (the bits in the sprite storage
block corresponding to those pixels are equal to zero) are transparent. Holes in these
sprites allow background data to pass through the transparent area and create a "wind o w " effect. The same window effect occurs when a higher priority sprite with " h o l e s "
passes in front of a lower priority sprite. Even though one sprite has a higher priority,
if portions of that higher priority sprite are transparent, the lower priority sprite or
the background display data is allowed to pass through the higher priority sprite.

SPRITE-TO-DATA DISPLAY PRIORITIES

The sprite to data (background screen) priority is selected through a software register
within the VIC chip. The Sprite to Background Display Priority Register (location
53275 ($D01B)) specifies whether a sprite passes in front of or behind the objects on the
screen background plane. This feature makes sprites seem more realistic. The default
value of this register is zero; therefore, all sprites pass in front of objects on the screen
background unless you change the bit values in this register. In other words, upon
power-up, all sprites have a higher priority than the screen background.
Bits 0 through 7 pertain to sprites 0 through 7. lf a bit in this register is set,
the sprite passes behind the objects on the screen background. The bit number correspondence to the sprite number works the same way as the sprite enable register and
many of the other sprite registers. To set these bits, raise two to the power of the bit
position for the sprite number that you want to pass behind the screen background
objects. For instance, to cause sprite 6 to pass behind objects on the screen background,
raise 2 to the sixth power and place the hexadecimal equivalent in location 53275
($D01B) in machine language as follows:
LDA
STA

# $ 4 0 (%01000000 = binary rotation in the Monitor)

$D01B

To set the sprite-to-data display priorities for more than one sprite, add the values
together for two raised to the respective bit positions and store the result in location
53275 ($D01B).

SPRITE COLLISION PRIORITIES

The VIC chip has a feature that enables you to detect when a collision occurs between
sprites, or between a sprite and screen objects.

289

290

COMMODORE 128

SPRITE-TO-SPRITE COLLISIONS
A sprite-to-sprite collision occurs when an enabled pixel in the foreground of one sprite
overlaps an enabled pixel from the foreground of another sprite at any point on the sprite
coordinate plane. The collision may also occur at an off-screen coordinate location.
Location 53278 ($D01E) flags whether a sprite-to-sprite collision has occurred. This
register, like most of the sprite registers, has a bit which detects a collision for each
sprite. Bits 0 through 7 pertain to sprites 0 through 7. If a sprite is involved in a
sprite-to-sprite collision, the bit corresponding to the sprite involved in the collision is
set; therefore, at least two bits are always set in a sprite-to-sprite collision. These bits
remain set until they are read at which time the VIC clears the register. You should store
the value of this register in a variable until the collision or conditional code depending
on the collision is fully processed.
Once a sprite-to-sprite collision is detected, the sprite-to-sprite collision Interrupt
Request (IRQ) flag, bit 2 of location 53273 ($D019), is set and an interrupt occurs if
enabled in the IRQ Mask Register at 53274 ($D01A). When this occurs, you can
incorporate an interrupt routine to be activated upon the collision of two sprites.
Therefore, your sprite-to-sprite collision interrupt routine is only executed upon the
condition that two sprites collide. This built-in feature gives you a way to conditionally
wedge an interrupt (lRQ) routine into your application program, depending on the
behavior of the sprites on the screen.

SPRITE-TO-DATA COLLISIONS
A sprite-to-data collision occurs when an enabled pixel in the foreground of a sprite
overlaps a pixel from the foreground of an object on the screen. Location 53279
($D01F) flags whether a sprite-to-data collision has occurred. This register has a bit
which detects a collision for each sprite. Bits 0 through 7 pertain to sprites 0 through 7.
If a sprite is involved in a sprite-to-data collision, the bit corresponding to the sprite
involved in the collision is set. These bits remain set until they are read at which time
the VIC chip clears the entire register. A recommended programming practice is to store
the value of this register in a variable until the collision or conditional code depending
on the collision is fully processed.
Once a sprite-to-data collision is detected, the sprite-to-data collision IRQ flag in
bit 1 of location 53273 ($D019) is set and an interrupt occurs if enabled in the IRQ
Mask Register at 53274 ($D01A). When this occurs, you can incorporate an interrupt
routine to be activated upon the collision of two sprites. Therefore, your sprite-to-data
collision interrupt routine is only executed upon the condition that a sprite has collided
with an object on the screen foreground. Again, this gives you a way to conditionally
wedge an IRQ routine into your application program depending on the behavior of your
animated graphic objects on the screen.
Note that sprite-to-data collisions do not occur with multi-color bit pair 01
(binary). This permits those bits to be interpreted as background display data, without
interfering with sprite-to-data collisions.

JO
PROGRAMMING
THE 8O-COLUMN
(8563) CHIP

291

292

COMMODORE 128

The Commodore 128 computer offers two types of video output: 40-column, composite
video through the VIC chip and 80-column, RGBI through the 8563 chip. The 80-column
display adds an important feature to the Commodore family of home and business
computers: The C128 can be regarded as a business machine. The 8563 chip enables the
C128 to display spreadsheets, wordprocessors, database managers and existing CP/M
applications in 80 columns. Now, the latest in the family of inexpensive Commodore
computers runs the Perfect series of business applications, and many other business
applications in C128 mode. In CP/M mode, the C128 runs Wordstar, and many other
popular business applications. In addition, the C128 supports all the hardware and
software available for the Commodore 64. The Commodore 128 is truly the complete
personal computer.

THE 8563 VIDEO CHIP

FEATURES
The primary purpose of the 8563 video chip is to display characters on the screen. The
8563 has two sets of characters, each with 256 elements. Unlike the VIC chip, however,
the 8563 can display all 512 characters simultaneously. The VIC chip displays only one
character set at a time.
The 8563 chip supports a limited bit map mode. Bit mapping can be achieved
through your own programs, preferably machine language. The BASIC 7.0 graphics
commands do not support the 80-column screen. Programming the bit-mapped screen in
BASIC is not recommended, since the language is not geared to manipulating single
display bits at a time. Later in this chapter, bit mapping the 80-column screen is
illustrated in machine language.
Another feature of the 8563 is smooth scrolling in the vertical and horizontal
directions. The 8563 chip is equipped with a set of scrolling registers that enable text to
be scrolled up, down, left or right. This is discussed later in the chapter.

PROGRAMMING THE
80-CQLUMN (8563) CHIP
Programming the 8563 video chip is a quite different from programming the VIC chip.
As you know, the registers of the VIC chip are located in the range 53248 ($D000)
through 53296 ($D030) in bank 15. Unlike the VIC chip, the 8563 has only two
memory locations in Commodore 128 I/O memory. $D600 and $D601. This means that
only two memory locations in the Commodore 128 I/O memory pertain to the 8563
video chip. Internally, the 8563 has thirty-seven internal registers, though they are not
addressable in C128 I/O memory. In addition, the 8563 has 16K of RAM of its own that

PROGRAMMING T H E 8O-COLUMN (8563) CHIP

is independent of the Commodore 128 RAM. You must address locations $D600 and
$D601 as the gateways through which you indirectly address the thirty-seven internal
registers and 16K of 8563 RAM. You cannot directly access any of the thirty-seven
internal registers or the 16K of 8563 RAM.
Location $D600 is the Address Register, and $D601 is the Data Register.
Generally, you place an 8563 register number in the address register ($D600) then either
write to or read from the data register in location $D601. This is a simplified explanation
the more-detailed information given in the following sections is needed to program the
8563 successfully.

8563 NOTES:
1. You cannot use BASIC PEEK, POKE, or WAIT instructions to access
the 8563, because these commands are implemented using indirect
operations. Any indirect machine instructions (such as LDA ( ),Y or
STA( ),Y) must be avoided because they result in 'false' bus states
which are sensed by the 8563 and subsequently acted upon as though
they were valid instructions.
2. You should not, directly or indirectly, access the 8563 during interrupts, because there is no way to save and restore the 8563 registers
without disrupting any I/O that might have been in progress at the
time of the interrupt.

DETAILS BEHIND PROGRAMMING

THE 8O-COLUMN CHIP
So far, you have learned that the 8563 chip has:
1.
2.
3.

Thirty-seven internal registers.

16K of independent RAM (that is not addressable in the C128 memory map).
An address register ($D600 and a data register $D601) in C128 I/O memory.

Figure 10-1 is a summary of the 8563 registers, in the form of a register map:

293

294

COMMODORE 128

BITS
REG

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

HT7
HD7
HP7
VW3
VT7

VD7
VP7

HT6
HD6
HP6
VW2
VT6

HT5
HD5
HP5
VW1
VT5

VD6
VP6

VD5
VP5

DS15
DS7
CP15
CP7
LPV7
LPH7
UA15
UA7
AA15
AA7
CTH3

COPY
TEXT
FG3
AI7
CB15

WC7
DA7
BA15
BA7
DEB7
DEE7

CM1

CM0

DS14
DS6
CP14
CP6
LPV6
LPH6
UA14
UA6
AA14
AA6
CTH2

DS13
DS5
CP13
CP5
LPV5
LPH5
UA13
UA5
AA13
AA5
CTH1

RVS
ATR
FG2
AI6
CB14

CBRATE
SEMI
FG1
AI5
CB13

WC6
DA6
BA14
BA6
DEB6
DEE6

WC5
DA5
BA13
BA5
DEB5
DEE5

HSyNCVSyNC

HT4
HD4
HP4
VW0
VT4
VA4
VD4
VP4

CTV4
CS4
CE4
DS12
DS4
CP12
CP4
LPV4
LPH4
UA12
UA4
AA12
AA4
CTH0
CDV4
VSS4
DBL
FG0
AI4
RAM
UL4
WC4
DA4
BA12
BA4
DEB4
DEE4

HT3
HD3
HP3
HW3
VT3
VA3
VD3
VP3

CTV3
CS3
CE3
DS11
DS3
CP11
CP3
LPV3
LPH3
UA11
UA3
AA11
AA3
CDH3
CDV3
VSS3
HSS3
BG3
AI3

UL3
WC3
DA3
BA11
BA3
DEB3
DEE3
DRR3

HT2
HD2
HP2
HW2
VT2
VA2
VD2
VP2

CTV2
CS2
CE2
DS10
DS2
CP10
CP2
LPY2
LPH2
UA10
UA2
AA10
AA2
CDH2
CDY2
VSS2
HSS2
BG2
AI2

UL2
WC2
DA2
BA10
BA2
DEB2
DEE2
DRR2

HT1 HT0
HD1 HD0
HP1 HP0
HW1 HW0
VT1 YT0
VA1 VA0
VD1 VD0
VP1 VP0
IM1 IM0
CTY1 CTY0
CS1 CS0
CE1 CEO
DS9 DS8
DS1 DS0
CP9 CP8
CP1 CP0
LPY1 LPV0
LPH1 LPH0
UA9 UA8
UA1 UA0
AA9 AA8
AA1 AA0
CDH1CDH0
CDY1CDV0
VSS1 VSS0
HSS1 HSS0
BG1 BG0
AI0
All

UL1 UL0
WC1 WC0
DA1 DA0
BA9 BA8
BA1 BA0
DEB1 DEB0
DEE1 DEE0
DRR1DRR0

Horizontal Total
Horizontal Displayed
Horizontal Sync Position
Vert/Horiz Sync Width
Vertical Total
Vertical Total Adjust
Vertical Displayed
Vertical Sync Position
Interlace Mode
Character Total Vertical
Cursor Mode, Start Scan
Cursor End Scan Line
Display Start Address hi
Display Start Address Io
Cursor Position hi
Cursor Position lo
Light Pen Vertical
Light Pen Horizontal
Update Address hi
Update Address lo
Attribute Start Adr hi
Attribute Start Adr lo
Character Tot(h), Dsp(V)
Character Dsp(v)
Vertical smooth scroll
Horizontal smooth scroll
Foregnd/Bgnd Color
Address Increment / Row
Character Base Address
Underline scan line
Word Count
Data
Block Start Address hi
Block Start Address lo
Display Enable Begin
Display Enable End
DRAM Refresh rate
Horiz, Vert Sync Polarity

Figure 10-1. 8563 VDC Register Map

The numbers in the left columr are the register numbers. When programming the
8563, the registers are referenced by number only, since they have no actual address in
the C128 memory map. Within the register map, columns 7 through 0 apply to the bits
within the registers. To the right are the register names, by function. Many of the
registers control more than one operation of the chip, so the names only reference the
primary purpose of the register. These registers are discussed individually at the end of
this chapter. Certain key registers are discussed in the next section. For an explanation
of each register, see the register-by-register description in the back of this chapter.

P R O G R A M M I N G T H E 8 O - C O L U M N (8563) C H I P

The 16K of 8563 RAM is organized by the Kernal in the following default
structure:

TYPE OF MEMORY

8563 RAM LOCATION

Character Display area (screen)

Character Attributes (color)
Character Definitions

$0000-$07FF
$0800-$0FFF
$2000-$3FFF

The layout can be changed by your application program. Registers 12 and 13 (high
byte/low byte) specify the start of the character display area, which is comparable to
screen RAM in the VIC chip. Registers 20 and 21 (high byte/low byte) specify the
character attribute base address. These registers determine the starting address of display
characteristics of a character such as reverse video, underlining, flashing and color.
Register 28 determines the character set base address, the start of the character definitions in 8563 RAM.
As you can see, the 8563 display has the same three components as the
VIC display: screen memory, color memory, and character definitions. All three lie
in the 16K of 8563 RAM and do not show up in the C128 memory map. These
components of the 8563 video display are discussed in greater detail in the next
section.
The third element of 8563 programming is the address and data registers that
are located in locations $D600 and $D601. These locations are the transitions, the
doorways in and out of the 8563 chip. You cannot directly reference an 8563
register or RAM location. You must indirectly read or write to $D600 and $D601 in
order to communicate between the 8563 chip and the rest of the Commodore 128.
Figure 10-2 gives description of each of the mapped registers and the bits within
them:

$D600^

address (write):

R5
R4 R3 R2
R1
R0
status (read) : STATUS LP VBLANK VER0 VER1VER2

$D601 ^

data

(r/w) :

D7

D6

D5

D4 D3

D3

D2

DO

Figure 10-2. Mapped Registers

In location $D600, bit 7 acts as a status bit. When you require a read or write
operation to the 8563 RAM or a register, you must check the value of bit 7 of
$D600. While it is 0, no read or write operations may take place.

295

296

COMMODORE 128

This is the sequence of steps to perform a read or write operation:

1.
2.
3.

Address the registers (by number) or internal RAM location.

Check the value of bit 7 until it equals 1 in order for the data to be
valid.
Once bit 7 becomes high (1), perform the read or write operation.

Later in this chapter, you'll see example programs that illustrate the behavior of
these registers.
The rest of the bits in $D600 except bit 6, which involves a light pen are used to
represent a register number for read or write access. Six bits are necessary since the
8563 has 37 registers; therefore, enough bits are needed to represent numbers up to 37.
Location $D601 is strictly a data register that passes values between the 8563
and the 8502 during read and write operations respectively. Each bit in this register
is a data bit. All data that passes between 8563 and the 8502 must pass through this
register.

FUNDAMENTAL BACKGROUND
ABOUT THE 8563 CHIP
CHARACTERS
As you know, the 8563 chip is primarily designed for displaying characters within an 80
by 25 character matrix. The visible character is an 8 by 8 pixel matrix. The character
can be defined by 16 or 32 bytes and can be displayed less than 8 by 8 pixels.

PROGRAMMING T H E 8O-COLUMN (8563) CHIP

a. Visible 8 by 8 pixel character.

b. Horizontal intercharacter spacing.
c. Vertical intercharacter spacing.
Figure 10-3.

The horizontal unit of measure within a character is a pixel. The vertical unit of
measure within a character is called a scan line. A scan line is a single horizontal row of
scanned pixels referred to as one raster. The pixel and the scan line are the smallest units
of measurement by the 8563 chip in the horizontal and the vertical directions, respectively. The size of the displayed character image in both pixels and scan lines is
programmable and determined by four registers within the 8563: the Character Total
(R9) (vertical), Character Total (R22) (horizontal), Character Displayed (R23) (vertical)
and Character Displayed (R22) (horizontal) Registers. These registers are described in
the register by register description at the end of this chapter.

FRAMES
A frame is a two-dimensional array (matrix) of characters, also referred to as simply the
screen. The default frame is the 80-column by 25-line screen in which characters are
displayed. Each character on the frame has a character pointer (a Display RAM byte)
that tells the 8563 which character to display in each character position within the frame.
Think of a frame as a framed picture on a wall containing a two-dimensional array
(matrix) of characters. For example, a frame specified to be 16 by 12 characters is filled
with characters as in Figure 10-4.
The frame also contains the vertical retrace and all other nonvisible portions of the
screen. The frame is programmable in size, similar to a window. The screen frame
determines the size of the viewed image, like the frame surrounding a window.

297

308

COMMODORE 128

^
HASADKHADKSFDKHA
HASADKHADKSFDKHA
HASADKHADKSFDKHA
HASADKHADKSFDKHA
HASADKHADKSFDKHA
HASADKHADKSFDKHA
HASADKHADKSFDKHA
HASADKHADKSFDKHA
HASADKHADKSFDKHA
HASADKHADKSFDKHA
HASADKHADKSFDKHA
HASADKHADKSFDKHA
N
Figure 10-4.

The default frame size is 80 columns by 25 lines. However, the frame size and
characteristics are programmable, so you can change them. The 8563 has several
registers that determine the size and characteristics of the frame. These registers are as
follows:
Horizontal Total (R0)
Horizontal Displayed (R1)
Horizontal Sync Position (R2)
Horizontal Sync Width (R3)
Vertical Total (R4)
Vertical Total Adjust (R5)
Vertical Displayed (R6)
Vertical Sync Position (R7)
Vertical Sync Width (R3)
DRAM Refresh/Scan Line (R36)
These registers are covered in the register-by-register description at the end of the
chapter.

PROGRAMMING T H E 8O-COLUMN (8563) CHIP

UNDERSTANDING THE 8O-COLUMN

CHARACTER DISPLAY AND
ATTRIBUTE MEMORY
As you learned earlier in this chapter, the 8563 has three areas of memory that control
the 80-column display; character definitions, character attributes and display screen
memory.
In a previous section, the three main elements of programming the 80-column chip
were introduced: (1) the address and data registers $D600 and $D601 that map into the
C128 RAM memory map, (2) the 16K of independent 8563 RAM, and (3) the 37
internal registers. The 16K of independent 8563 RAM provide the main elements of
video display information: display memory, character attributes and character definitions.
The display memory is comparable to screen memory in the VIC chip. The character
attributes supply color and other information for the characters and parallel the function
of VIC color RAM. The 8563 character definitions correspond to the VIC character
ROM. Though the VIC and 8563 video memory are similar, the operations of the two
are different. This provides a frame of reference to the VIC chip characteristics, so you
can understand the comparison between the operation of both the VIC and 8563 video
processors.
All these video components are stored in the 16K of independent 8563 RAM.
Again, here is the breakdown of the locations where the three sections of video memory
are stored in the 8563 RAM:

TYPE OF MEMORY

8563 RAM LOCATION

Display Memory
Character Attributes
Character Definitions

$0000-$07FF
$0800-$0FFF
$2000-$3FFF

All of the 8563 video display memory resides in the 16K section of independent
RAM. The 8563 character definitions in RAM require up to 32 bytes per character. If 32
bytes per character are used, the 8563 character definitions use 8K of memory per
character set, or a total of 16K. Otherwise, each character set occupies 4K of independent 8563 RAM, or a total of 8K for both character sets. The VIC chip requires a total
of 4K of character ROM to represent all the characters, since the VIC chip only requires
8 bytes to represent a character.
The rest of the section describes how the character display area, the character
attributes and the character definitions are addressed and interpreted.

299

306

COMMODORE 128

UNDERSTANDING
DISPLAY MEMORY
The frame, which was introduced earlier in this chapter, pertains to display memory, the
portion of memory you can see on the screen. Display memory resides in the range
$0000-$07FF in the 16K independent 8563 RAM. Think of the screen as a frame of 25
rows of 80 characters each. A frame may have different proportions, but for the
purposes of this discussion, assume that the frame is 80 by 25.
Each character position (display memory location) within a frame contains a
code that acts as a pointer into the character definitions that tells the 8563 which
character to display in that particular character position within the frame. For the
defined screen of frame size 25 rows by 80 columns, the first 80 pointers define the
character codes for the 80-character positions in the top row of the screen (frame).
Locations 81 through 160 define which characters are displayed in the second row of
the screen (frame), and so on. For the defined screen frame of 80 by 25, 2000
display memory locations are necessary to display the 2000 possible character positions
of the screen.
In text mode, the contents of display RAM are screen display codes like the
ones the VIC chip uses. These are not ASCII CHR$ codes. Screen codes are actually
indexes into the 8563 character RAM definitions, like the screen codes used as indexes
into the VIC character ROM. Since the first character in 8563 character RAM is
the at-sign character, it is assigned screen code 0. The A is the second character,
so it is assigned the screen code 1, and so on. For a complete list of screen codes,
see Appendix D.

ADDRESSING
DISPLAY MEMORY
The contents of registers 12 (high-byte) and 13 (low-byte) define the 16-bit start address
of the first (top-left) character in the frame (display memory). The default start address
of display memory is $0000. The address of the second character position on the
frame, that is, the character in column two, row one, is defined by the contents of
registers 12 and 13 plus 1. Add an index to the contents of registers 12 and 13 to arrive
at the address of subsequent character positions on the frame. For example, to find the
address of the character position in the first column of the second row of an 80 by 25
frame, add an offset of 80 to the contents of registers 12 and 13. To find the address of
the character position in column 1, row 3, add 160 to the contents of registers 12
and 13.

PROGRAMMING T H E 8O-COLUMN (8563) CHIP

In general, add an offset of 1 for each character position to the right of the
upper-left corner of the frame. To reach the same column in the row below the current
character position, add an offset of 80. Although the screen (frame) appears as a
two-dimensional matrix of characters, the address references in memory are accessed
linearly in sequence. For example, although the character in the top-left corner of the
screen is only 24 character rows away from the character in the lower-left corner of the
screen, in memory, the locations of those characters are really 1920 (24 x 80) memory
locations apart. So a frame, the size of the default screen (80 x 25) requires 2000
memory locations to store the contents of the 2000 character positions on the
frame. The contents of each display RAM location (acting as an indexed pointer into the
character definitions) tells the 8563 which character, out of the 256 available characters
in either character set, to place at any particular position on the 80 by 25 character
frame.

CHARACTER ATTRIBUTES
The character attributes are a set of 8563 RAM locations that assign video enhancement qualities to the characters in the frame. Each character position in the frame
is assigned its own attribute byte, so a frame (screen) of 80 columns by 25 lines
requires 2000 attribute bytes. The default location of the attribute bytes for the 80
by 25 frame is stored in the range $0800 through $0FCF in the 16K of independent
8563 RAM.
The attributes (and the corresponding bits) that enhance the video qualities of the
characters in the frame are as follows:

BIT

7
6
5
4
3
2
1
0

ATTRIBUTE

Alternate Character Set

Reverse Video Attribute
Underline Attribute
Blink Attribute
Red
Green
Blue
Intensity

The ALTERNATE CHARACTER SET (bit 7), when high (1), enables an
additional 256 characters to be displayed within the frame.

301

302

COMMODORE 128

The REVERSE VIDEO ATTRIBUTE (bit 6), when high (1), reverses the
foreground and background colors for the corresponding character in display memory.
See also the register-by-register description of the 8563 chip for all the details about
register 24, the Reverse Screen Register.
The UNDERLINE ATTRIBUTE (bit 5), when high (1), enables the UNDERLINE SCAN LINE (as defined by bits 0 through 4 of register 29) in the foreground
color for that character within the frame. The underline scan line may be any scan line
within the character as determined by the lower four bits of register 29.
When the BLINK ATTRIBUTE (bit 4) is equal to 1, the character associated
with this attribute byte blinks. The blinking is achieved by repeatedly switching back
and forth between the foreground and background colors. The blink rate is determined
by bit 5 of register 24.
Attribute bits 3 through 0 determine the foreground color for the R, G, B and I
respectively. The character within the associated display memory appears in the foreground color determined by the R, G, B and I bits. The foreground color of each
character cell can be one of 16 colors. The actual colors on the screen can be more than
red, green and blue. The RGBI signals coming from each input and the combination of
these signals determine the actual screen color. Here are the available colors and
associated color codes. The characters' background color is determined by bits 0
through 3 of register 26. These bits in register 26 specify the background color for all
the characters on the screen. Note, however, that in machine language these codes are
one less than the BASIC codes.

1
2
3
4
5
6
7
8

Black
White
Dark Red
Light Cyan
Light Purple
Dark Green
Dark Blue
Light Yellow

9
10
11
12
13
14
15
16

Dark Purple
Dark Yellow
Light Red
Dark Cyan
Medium Gray
Light Green
Light Blue
Light Gray

BASIC Color Codes in 80-Column Output

ADDRESSING CHARACTER ATTRIBUTES

The contents of registers 20 (high-byte) and 21 (low-byte) define the address of the start
of attribute storage. The default start address of attribute storage is $0800. The
contents of these two registers form the 16-bit address that marks the start of attribute
storage.
Address these attributes in the same way as addressing display memory.
To address subsequent character attributes to the right of the character in the HOME
(upper-left) position of the frame, add an offset of 1 to the contents of registers

PROGRAMMING THE 8O-COLUMN (8563) CHIP

20 and 21 for each character attribute to the right of the HOME position. To address the
character attribute directly below the HOME position (row 2, column 1), add an offset
of 80 to the contents of registers 20 and 21. To address the character attribute of the
character in the lower-left corner of the 80 by 25 frame, add a decimal offset of 1920
(24 X 80).

DISABLING CHARACTER ATTRIBUTES

Many applications programs for the 8563 chip do not need to assign the character
attributes. The 8563 has a bit that allows attributes to be disabled, saving a considerable
amount of RAM. Bit 6 of register 25 determines whether or not attributes are enabled. If
bit 6 is set (1), attributes are enabled: if the value of bit 6 is 0, attributes are disabled.
When attributes are disabled, the attribute portion of 8563 RAM may be used for other
purposes. If attributes are disabled, only one set of 256 characters is available, and
underlined, blinking and reverse video attributes are not available. In addition, all
characters are displayed in the same foreground color as determined by bit 4 through 7
of register 26. The background color is still determined by the lower four bits (3-0) of
register 26, regardless of whether attributes are enabled or not. The screen border and
the vertical and horizontal intercharacter spaces default to the background color.
Display memory may contain more memory locations and attributes than can be
displayed at a single time in an 80 by 25 frame. This portion of display memory may be
displayed by changing the contents of registers 12 and 13, the Display Start address, and
registers 20 and 21, the Attribute Start address, to reflect a new start of display memory
and attribute storage. The screen (frame) may be scrolled vertically by incrementing or
decrementing the values of the display memory pointer and attribute start addresses.
This provides a way to vertically scroll forward or backward through display memory.
In addition to scrolling vertically through display memory, the 8563 has a feature
that allows scrolling through display memory in the horizontal direction. Both of these
topics are covered later in this chapter.

CHARACTER DEFINITIONS
The character definitions residing in 8563 RAM specify the character patterns you see
on the 80-column screen. The character patterns in memory define the pixel formation
of each member of the character set visually represented on the screen. The character
definitions can be redefined by your application program.
The default memory range for the character definitions is locations $2000 through
$3FFF in 8563 RAM. This range is a total of 8K (8192 bytes). This is enough memory
to represent two character sets of 256 characters each. The attribute bit 7 of each
attribute byte selects either of the character sets for each character position within a
frame.
The 8563 characters are represented by either 16 or 32 bytes, depending on the
value of the lower five bits (40) of register 9. If the value of the lower five bits of

303

304

COMMODORE 128

register 9 is less than 16, each character is defined by 16 bytes in character storage.
Therefore, each character set requires a total of 4096 bytes of 8563 RAM. If the value
of the lower five bits of register 9 is greater than or equal to 16, each character is
defined by 32 bytes of 8563 character RAM. In this case, each character set occupies
8192 bytes (8K) of 8563 character RAM memory and the defined characters are
displayed using more than 16 scan lines each. This occupies the full 16K of 8563 RAM
and leaves no space for attributes. These taller characters are rarely used, however,
because the characters are twice as tall as they are wide and seem out of proportion.
The first byte of each character definition in memory represents the top horizontal
scan line of the character displayed on the screen. Depending on the value of the lower
five bits of register 9, a character will have either 16 or 32 scan lines, each being 8 bits
(pixels) wide.
Although the character definitions in 8563 character RAM are defined by either 16
or 32 8-bit bytes stacked one on top of another, the Display Data Bus is only 8 bits
wide, which limits the actual image of the character to 8 horizontal pixels. The total
width of the character including the horizontal intercharacter spacing may exceed 8
pixels. See the definition of a character in the beginning of the chapter and the
register-by-register description at the end of this chapter for details.

ADDRESSING THE
CHARACTER SET PATTERNS
The default location of the character definition start at address $2000 in 8563 RAM, and
since the starting location is programmable, you may change it. The starting location of
the character set definitions is determined by bits 5 through 7 of register 28. These are
the most significant three bits of the 16-bit address that points to the start of the
character definitions in 8563 RAM. Bits 4 through 0 of register 9 make up the five least
significant bits for the address that points to the start of the 8563 character definitions.
However, if the value of bits 4 through 0 in register 9 is greater than or equal to 16, only
bits 7 through 5 are significant, since the characters are made up of 32 bytes each and
the full 16K of 8563 RAM memory is allocated for the two character sets, 8K for each
set.

READING 8563
(RAM AND) REGISTERS
As you know, the 8563 chip has its own 16K of RAM and its own set of registers.
Neither of these appear in the standard Commodore 128 memory map. The only
memory locations that apply to the 8563 chip in Commodore 128 memory are the locations

PROGRAMMING T H E 8O-COLUMN (8563) CHIP

D600 and $D601. These are the 8563 address and data registers, respectively. In order
to read or write to 8563 RAM or registers, you must pass data through the address and
data registers. This section explains how to read the 8563 registers. The next section
illustrates how to write to the 8563 registers and RAM.

READING A N 8563 REGISTER

Reading an 8563 register requires five distinct programming steps. Although this may be
accomplished in BASIC, it is strongly recommended that you program the 8563 in
machine language. Briefly, here are the five machine language programming steps, the
algorithm, to read an 8563 register. A more detailed explanation and a program to read
an 8563 register follows.
1.
2.
3.
4.
5.

Load (immediate) the X register with the register number that you want to
read.
Store the contents of the X register (the 8563 register number) into the 8563
address register ($D600).
Check the status bit, bit 7 of address register $D600, until it is high (1).
If the status bit is low (0), go back and check it again.
Otherwise, load the accumulator with the contents of the 8563 data register
$D601. Store the contents of the data register into a C128 RAM location (a
variable) for future use and print the variable value.

Sinee many of the 8563 registers are pointers to a 16-bit address, a register pair is
required, one register for the high byte and one for the low byte. In this case, simply
increment the X register and repeat the five-step process to read the register contents of
the low byte. The high-byte register comes first in the register order, therefore the first
read is the high byte of a register pair, increment the X register and repeat the
process for the low byte. When the 8502 uses a register pair to point to a 16-bit
address, the high byte is the low byte plus 1.
Here's a program that reads the high- (R20) and low- (R21) byte register pair that
acts as a pointer to the start of the attribute storage in the 8563 RAM. The value stored
in locations $FB and $FC return the default start (high/low byte) of the attribute storage.
This pointer can be relocated to point to a section of 8563 RAM in which you define, as
is the case for display RAM and the character patterns.
EXAMPLE:
Reading a register (attribute base address)

305

306

COMMODORE 128

10
20
30
40
50
60
70
80
90

SYS DEC("1800")
A$=HEX$(PEEK(251) )
B$=HEX$(PEEK( 252 ) )
C$=RIGHT$(A$,2)
D$=RIGHT$(B$,2)
E$=C$+D$
F$="$"
G$=F$+E$
PRINT "START ADDRESS = ";G$

READY.
MONITOR
PC SR AC ;KR YR SP
i 00 Fi
; FB000 00 I30 00
.
.
.
.
.
.
.
.
.
.
.
.
.

01800
01802
01805
01807
01808
0180B
0180D
0180E
0180F
01812
01815
01817
018lA

A2
20
85
E8
20
85
60
00
8E
2C
10
AD
60

14
LDX
0F 18 JSR
FB
STA
INX
0F 18 JSR
STA
FC
RTS
BRK
00 D6 STX
00 D6 BIT
FB
BPL
01 D6 LDA
RTS

#$14
$180F
$FB
$180F
$ FC
$D600
$D600
$1812
$D601

Here are the details behind each instruction.

The first instruction ($1800) loads the X register with register number 20 ($14),
the high byte of the attribute start address.
The second instruction jumps to the subroutine at $180F.
The first instruction of the subroutine stores the contents of the X register,
($14), into the 8563 address register (location $D600 in C128 I/O memory).
The second instruction of the subroutine (BIT $D600) tests the UPDATE
READY status bit (7) of the 8563 address register. This is necessary since a
read or write operation does not take place as soon as those instructions are issued.
The Update Ready bit (bit 7) of the 8563 Address register determines when the
read (or write) instruction can be executed. The read operation is pending according
to the value of bit 7 of the address register. While the read operation is pending
(in prelatch), the value of bit 7 is 0. This indicates that the read (or write)
operation data placed in register 31, is not yet valid. Only when the value o f b i t
7 in the address register is equal to 1, is the data in the data register ($D601) valid.

The behavior of the 8563 chip and the way data is transferred between the 8563
registers and the address and data registers suggests the use of the BIT instruction. The
nature of the 8502 BIT instruction is tailor-made for checking the Update Ready bit
status of location $D600. When the BIT instruction is encountered by the microprocessor, the value of bit 7 is transferred into the negative flag bit of the 8502 status register.
If the value is equal to 0, the negative condition does not exist. If the value is equal to 1,
a negative condition does exist. Depending upon the value of this bit, you can conditionally branch to instructions that carry out an operation according to the value of this flag.
That's where the third instruction in the above subroutine ($1815) comes into play.

PROGRAMMING T H E 8O-COLUMN (8563) CHIP

Instruction 3 (BPL $1812) is a conditional instruction that branches depending

upon the value of the negative flag bit in the 8502 status register. In this
program, the BPL (Branch on Result Plus) instruction branches back to
location $1812 and executes the BIT instruction while the negative flag bit is
equal to 0. The BIT instruction is again performed, and the value in bit 7 is
again transferred to the negative flag bit in the 8502 status register. Then the
BPL instruction is encountered in the loop for a second time. If the value of the
status bit is still equal to 0, the branch is performed again. The loop continues
until the negative status bit is equal to one. Only when the status bit is equal to
1 does the loop fall through to the instruction immediately following the branch
instruction.
Prior to the loop falling through to the instruction after the branch, the
Update Ready status bit becomes a 1, it is transferred to the negative flag bit in
the 8502 status register, the branch is skipped, and the data can be read (loaded
with the fourth instruction of the subroutine ($1817) into $D601. Only after the
status bit becomes high (1) is the data in $D601 valid. This is the point where the
data is communicated from the 8563 chip to the Commodore 128 memory. Now
you can read and act upon the contents of the address within register $14 of the
8563 chip.
The fourth instruction loads the value stored in the 8563 data register ($D601)
into the accumulator.
The third instruction of the main program stores the value of the data register
into location $FB for future use. Subsequent read operations from ($D601)
destroy the original value, so it is always a good practice to store the contents of
$D60I into a variable or available RAM location.
The next instruction, INX, increments the contents of the X register, which
selects the next register number, $15, so the low byte of the 16-bit address
of the start of attribute storage can be read.
The rest of the program performs the same sequence of steps above for the
low byte of the start of attribute storage except for the RTS instruction. The
RTS instruction returns program control back to a main program.

The BASIC portion of the program prints the high and low bytes of the 16-bit
address that defines the start of attribute storage.
To find the actual address in 8563 RAM of the start of attribute storage, put the
high byte and low byte together, and the four-digit hexadecimal number defines the start
of attribute storage. Within the monitor, issue this memory command:
M FB
The contents of $FB and $FC (high/low bytes) mark the start of attribute storage.

307

308

COMMODORE 128

WRITING TO A N
8563 REGISTER
The five-step algorithm to read data from an 8563 register is similar to writing to an
8563 register. In the last section, Step 5 in the read algorithm loaded the accumulator
with the value contained in the 8563 data register ($D601). When writing, perform the
opposite operation. Instead of loading the accumulator as in a read operation, store the
accumulator value into the data register.
Here's an algorithm to write to an 8563 register:
1.
2.
3.
4.
5.
6.

Load the X register with the register number in which you want to write.
Load the accumulator with a value that you are writing to the 8563 register.
Store the contents of the X register into the 8563 address register at $D600.
Check bit 7, the status bit, of the Address Register until it is high (1).
If the status is low (0), loop back and check it again until it is high.
When the status bit (7) is high, store the value contained in the accumulator
into the 8563 data register ($D601).

Here's a sample program that writes to register pair R18 and R19, the Update RAM
location. Register pair R18 and R19 is the gateway into the independent 8563 RAM. For
now we'll illustrate how to write to an 8563 register. Later in this chapter, we'll take
it a step farther to explain how to read and write to the 16K of independent 8563 RAM.
READY.
MONITOR
PC SR AC XR YR SP
; FB000 00 00 00 00 F8
01800
01802
01804
01807
01808
0180A
0180D
0180E
01810
01813
01815
01816
01819
01 81B
0181C
0181D
0181E
01821
01824
01826
01829
0182A
0182B
0182C
0182F
01832
01834
01837

A2
A9
20
E8
A9
20
EA
A2
20
85
E8
20
85
60
00
00
8E
2C
10
8D
60
EA
EA
8E
2C
10
AD
60

12
LDX # $ 12
LDA #$20
20
lE 18 JSR $181E
INX
00
LDA #$00
lE 18 JSR $181E
NOP
12
LDX #$12
2C 18 JSR $182C
FB
STA $FB
INX
2C 18 JSR $182C
STA $FC
FC
RTS
BRK
BRK
00 D6 STX $D600
00 D6 BIT $D600
FB
BPL $1821
01 D6 STA $D601
RTS
NOP
NOP
D6
STX $D600
00
00 D6 BIT $D600
FB
BPL $182F
01 D6 LDA $D601
RTS

PROGRAMMING THE 8O-COLUMN (8563) CHIP

The first instruction (at $1800) loads the X register with the register number
18 ($12).
The next instruction loads the accumulator with the high byte of the value you
are placing in register 18 ($20).
Instruction 3 calls the subroutine at location $181E, which is essentially the
same routine as in the read register example in the last section, with one
exception. The instruction in the subroutine immediately before the RTS is a
store instruction to the 8563 data register at $D601. The two instructions before
it form a loop that continually checks the Update Ready status bit pending the
write operation, just as the read program did. The write operation (STA
$D601) is not performed until the status bit 7 in the address register becomes
high (1). Once the status bit becomes equal to a 1, the high byte of the address
in register 18 is written to the data register ($D601). The subroutine returns
control to the main body of the program with the RTS instruction.
The program resumes with the fourth instruction INX. This increments the
register number.
The fifth instruction (LDA # 0 0 ) loads the value of the low byte of the address
to be written to register 19 ($13) into the accumulator.
The subroutine at $181E is called again, and the same process is repeated.
Upon return of the subroutine, the same read routine example from the last
section is performed (the subroutine between $182C-$1837) to ensure that the
values that were written to registers 18 and 19 are valid. These values are
printed by the BASIC routine. To see those values, use the memory command
within the monitor as follows:
M FB
The first two bytes displayed are:

20 00
This shows that the address in the update location register pair (R18, R19) has
been written to successfully and is valid.

WRITING TO 8563 RAM

Now take the example from the last section one step farther. The last example illustrated
how to write to an 8563 register. It just so happens that the register chosen for the
example is the update location register pair (R18, R19). This is the register pair that
enables you to write to and read from the 16K of independent 8563 RAM. This section
expands on the previous example and shows you how to write to the 16K of 8563 RAM.
The program given below fills display memory in 8563 RAM with characters, in
the process displaying the characters on the screen. The program fills display RAM
located in the default range $0000 through $07CF, with screen code character 102
($66). See Appendix D for a complete list of screen code characters.
Here's the listing:

309

330

COMMODORE 128

READY.
MONITOR
PC SR AC XR YR SP
; FB0 0 0 0 0 0 0 0 0 0 0 F8
01800
01802
01804
01807
01808
0180B
0180D
0180F
01811
01813
01816
01817
01819
0181B
018lD
018lE
0181F
01821
01824
01827
01829
0182C

A2
A9
20
E8
20
A0
A9
85
A9
20
C8
D0
C6
D0
00
00
A2
8E
2C
10
8D
60

12
LDX # $ 12
00
LDA #$00
21 18 JSR $1821
INX
21 18 JSR $1821
00
LDY #$00
08
LDA #$08
FA
STA $FA
66
LDA #$66
1F 18 JSR $181F
INY
FA
BNE $1813
FA
DEC $FA
F6
BNE $1813
BRK
BRK
1F
LDX #$lF
00 D6 STX $D600
00 D6 BIT $D600
FB
BPL $1824
01 D6 STA $D601
RTS

To execute this program, issue the Go (G) command within the Machine Language Monitor. In order for this program to operate, I/O memory must be in context in
the currently selected monitor configuration. I/O memory is always in context within
configuration 15 ($F), so issue this command to execute the program:
G F1800
The first five instructions (memory $1800-$1808) and the subroutine stored in
memory locations $1821 through $182C are the same instructions contained in the program
that wrote to registers 18 and 19 in the last section. However, instead of placing the address
$2000 in register pair 18 and 19 as in the last section, the address $0000 is placed
there to mark the default starting location of display memory in 8563 RAM. This is where
the program begins to place screen code 102 in display RAM. The full 2000 bytes (8 pages
of memory minus 48 bytes) of display RAM are filled with this character screen code.
Here's how the rest of the program works. The instruction stored at location
$180B, LDY # $ 0 0 , initializes the Y register to 0. The next instruction, LDA # $ 0 8
loads the accumulator with the value 8. Then, STA $FA, stores the contents of the
accumulator, which initializes this location to 8. Location $FA is used later in the
program as a counter for the number of pages to fill with screen code 102. The
instruction stored at $1811, LDA # $ 6 6 , loads the accumulator with the hexadecimal
value ($66) of decimal screen code 102.
The instruction starting in location $1813, JSR $181F, calls the subroutine located
at address $181F. This subroutine is the crux of the program and actually writes the data
to the display memory (screen). This is essentially the same routine as the subroutine
located between $181E and $1829, the one from the last section. However, there is one
key difference. The first instruction of the subroutine stored starting at $181F, LDX
# $ l F , loads the X register with the register number 31 ($lF). When writing to 8563

PROGRAMMING THE 8O-COLUMN (8563) CHIP

RAM, you must address register 31 because it acts as the internal data register of the
8563 chip. All data that will be written to the 8563 RAM must pass through register 31.
The next three instructions:
STX $D600
BIT $D600
BPL $1824
check the status bit (7) of the address register until the value becomes equal to 1
(high). These are the same three instructions used in the last two sections when reading
or writing to a register and in the first subroutine of this program.
Once the status bit of the 8563 address register becomes high, the data residing in
the accumulator (in this case) is written to the external 8563 data register at address
$D601, as in the instruction stored at location $1829. In addition, the data in the
accumulator is written to the address contained in the update register pair (R18, R19).
This occurs since you addressed the internal data register 31 by placing the value 31 in
the 8563 address register at $D600. Upon the status bit becoming high, all data in
register 31 is placed in the current address of 8563 RAM specified by the update register
pair (R18, R19). You placed this address in the update register pair in the very
beginning of the program.
At this point, the 8563 hardware takes over. It automatically increments the
address contained in the update register pair (R18, R19). You as the programmer do not
increment the update register pair's contents; the 8563 chip does this for you automatically. You can say that the update register pair is auto-incrementing. In addition, the
8563 reads the data from the incremented address within 8563 RAM, and places the
contents in the internal 8563 register 31. This also saves programming effort. Remember, both of these tasks are performed by the 8563 hardware, not the programmer.
Since the update register pair automatically increments the 8563 RAM addresses,
all you have to do is continually call the subroutine that writes the data to each
successive display RAM location. That's what the instructions between addresses $1813
and $181B do in the program. These instructions call the subroutine for eight pages of
display RAM, or a total of 2048 times. The write subroutine writes only one character to
the screen per call, so to fill the entire screen, it must be called 2000 (80 x 25) times.
This sample BASIC program shows how to properly read and write the 8563
registers, and read, modify, write any location in 8563 RAM. The two ML subroutines
are the key- and they can be used from either BASIC as shown here, or from your ML
program.

311

318

COMMODORE 128

VI=DEC("1800"):VO=DEC("180C"):BANKl5
READ A$
DO UNTIL A $ = " E N D "
POKE V I + I , D E C ( A $ )

(install ML routines)

I =I +1
READ A$
LOOP
DATA 8 E , 0 0 , D 6 , 2 C , 0 0 , D 6 , 1 0 , F B , A D , 0 1 , D 6 , 6 0
DATA 8 E , 0 0 , D 6 , 2 C , 0 0 , D 6 , 1 0 , F B , 8 D , 0 1 , D 6 , 6 0 , E N D
DO
PRINT
INPUT"ADDRESS (0-16383)";AD
SYS VO, AD/256,
18
SYS V0, A D A N D 2 5 5 , 1 9
SYS VI,,31
RREG A
PRINT"THE 8563 MEMORY A T " ; A D ; "
INPUT"NEW DATA (0-255) ";A
SYS V0, A D / 2 5 6 ,
18
SYS V0, A D A N D 2 55,19
SYS VO, A
,31
LOOP

(update location HIGH)

(update location LOW)
(READ memory data)
(update location HIGH)
(update location LOW)
(WRITE memory data)

IS";A

The following disassembly shows the two ML routines used in the previous BASIC
program and in the Read register, Write register and Write to RAM examples in the
preceding sections. They are relocatable.
01800
01803
01806
01808
0180B

8E
2C
10
AD
60

00 D6
00 D6
FB
01 D6

STX
BIT
BPL
LDA
RTS

$D600
$D600
$1803
$D601

0180C
0180F
01812
01814
01817

8E
2C
10
8D
60

00 D6
00 D6
FB
01 D6

STX
BIT
BPL
STA
RTS

$D600
$D600
$180F
$D601

(routine to READ 8563 register in .X)

(routine to WRITE .A register in .X)

BLOCK WRITE AND BLOCK COPY

The 8563 chip's Block Write and Block Copy features are extensions of the write
operation described in the last section. The Block Write feature writes the same data
contained in the accumulator into a specified number of successive 8563 memory
locations. Here's the procedure:
1.
2.
3.
4.

5.

Place the initial address, where writing in RAM begins, into registers 18
(high byte) and 19 (low byte).
Next, load the accumulator with the data you want to place in successive 8563
RAM locations.
Load the X register with the number 31 which specifies the data register
within the 8563.
Wait for the Update Status Ready bit to become high (1). So far this is the
same procedure as writing to 8563 RAM which was described in the Writing
to 8563 RAM section.
To select the Block Write feature, clear (0) bit 7 of register 24, using the
same procedure you use to write to a register.

PROGRAMMING T H E 8O-COLUMN (8563) CHIP

6.

Finally, place the number of successive memory locations you want to write
to 8563 RAM in register 30.

At this point, the 8563 writes the data in register 31 starting from the location determined by registers 18 and 19 through the number of successive memory locations specified
by register 30. The contents of registers 18 and 19 are automatically incremented to access
the next location to be written. Upon completion of the Block Write, registers 18 and 19
contain the last address plus one of the 8563 RAM locations in which it was written.
Note that one write cycle follows the initial write operation to register 31;
therefore, the quantity written to register 30 should be one less than the number of 8563
memory locations in which you want to write.

BLOCK COPY
The Block Copy feature copies (reads and writes) data from one section of 8563 RAM
to another. To copy a block of 8563 RAM:
1.

Place the destination address, where copying in RAM begins, into registers
18 (high byte) and 19 (low byte).
Wait for the Update Status Ready bit to become high (1).
Set (1) bit 7 of register 24, which selects the Block Copy feature. At this
point, the 8502 writes the initial source address for the block copy to registers
32 (high byte) and 33 (low byte).
Place the number of successive memory locations to copy into register 30.

2.
3.

4.

The 8563 reads the contents of the first source address and writes the data to the
first destination address. The 8563 RAM addresses are automatically incremented and
copying continues until the number of memory locations specified by register 30 are copied.

READING FROM 8563 RAM

The process of reading from 8563 RAM is the same as reading from a register, except
you read from the data register, register 31.

PROGRAMMING THE 8563 CURSOR

The 80-column cursor is programmable in its image and movement. First, the cursor
image may be programmed in four different ways. Bits 6 and 5 of register 10 control the
following four characteristics of the cursor:

BIT VALUE

CHARACTERISTIC

0 0
0 1
1 0
1 1

Solid cursor
No visible cursor
Slow cursor blink rate ('/i6 the frame rate)
Fast cursor blink rate (V32the frame rate)

313

320

COMMODORE 128

Bits 4 through 0 in register 10 determine the bottom scan line in which the cursor
definition begins within the 8 scan line cursor character block. Scan line 0 is at the top
of the cursor character block, while scan line 8 is at the bottom.
The interrupt-driven screen editor has an indirect location which controls the
cursor programming mode. Location $0A2B in C128 RAM is the shadow register which
controls the different ways to program the 8563 cursor.
Bits 4 through 0 in register 11 specify the top scan line in which the cursor
definition ends within the 8 scan line cursor character block. Bits 4 through 0 in registers
10 and 11 specify the height of the cursor. These registers enable you to program the
cursor as a solid block cursor (by default) or as an underlined cursor.

CURSOR POSITIONING
Register 14 (high byte) and 15 (low byte) determine the position of the cursor within the
displayed frame (screen). This register pair indicates the address of the cursor within
8563 display memory. The address of the cursor can be one that is not in the display
area of the current frame. If this address is within the address range of the current frame
(screen), the character position where the cursor is displayed appears in flashing reverse
video, as do most cursors.
The interrupt driven screen editor also has an indirect location that controls the
cursor column and row positioning. Location $OA35 in C128 RAM is the shadow
register for the 8563 cursor column and row selection.

BIT-MAPPING THE
8O-COLUMN DISPLAY
The 8563 chip supports a bit-map mode. The resolution of the 80-column bit-map screen
is 640 by 400 pixels. The 8563 addresses the bytes that make up the bit map across the
width of the screen, instead of in 8 by 8 character cells as with the VIC chip.
Bit-map mode is selected by setting bit 7 of register 25. The Kernal initializes
bit 7 to 0 to select text mode.
The three main components of an 8563 bit-map display, bit-map data, display
memory and color, are similar to the VIC chip in some ways but differ in others. For
example, the VIC has an 8000-byte RAM bit map, in which each bit is assigned an
individual pixel on the visual screen. Since the 8563 bit map is twice the resolution of the
VIC screen, it uses twice the memory: 16,000 bytes (a little less than 16K). The
one-to-one correspondence between bits in memory and pixels on the screen is similar,
but they are addressed differently. The addresses to access those bits are laid out
differently in memory.
Figure 8-25 in chapter 8 illustrates how the VIC bit map is stored in memory. The
VIC screen stores 8 bytes of the bit-map in the 8 bytes that would normally make up a
character in character mode. For instance, the first 8 bytes of the visual bit map are
stored in the first (HOME) character position, which defaults to 8192 ($2000) to 8199
($2007), or the first eight pixels of the first eight raster rows. The character to the
immediate right of the HOME position stores the second eight pixels of the first eight
visual raster rows. The 200 visible VIC screen raster rows are 320 pixels wide. The 200

PROGRAMMING THE 8O-COLUMN (8563) CHIP

visible 8563 raster rows are 640 pixels wide. Both the VIC and 8563 screens have
raster rows which are not visible on the screen. This portion is known as the vertical retrace.
The 8563 screen is stored byte by byte across a raster row. The first eight pixels of
the first raster row are stored in the first byte of the 8563 bit-map byte, address $0000 in
8563 RAM. The second eight pixels of the first row are stored in the second byte of the
bit map ($0001 in 8563 RAM). The third eight pixels are stored in location $0002 and
so on. The first raster row is stored in the first eighty memory locations in 8563 RAM,
the second raster row is stored in the second eighty (80-159) 8563 RAM addresses and
so on. See Figure 10-5 below for an illustration.
8563 CHARACTER COLUMNS
RASTER
ROW

10

11

80

1
2
3
4

$0000 $0001 $0003 $40004 $0005 $0006 $0007 $0009 $000A$000B$000C.. . $004F
$0050 $0051 $0052 $0053 $0054$0055$0056$0057
$009F
$00A0
$00F0

25

$3E30

$3E7F

Figure 10-5. The Relationship Between 8563 Bit Map Data and Screen Pixels

The collection of the 640 by 200 pixels on the screen form the image in this way: bits
that are set (1) enable screen pixels in the foreground color and clear (0) bits take on the
background color.

THE BIT-MAP POINTER

The pointer to the start of the 8563 bit map defaults to the start of display memory at
8563 RAM location $0000. The display memory start address is contained in registers
12 (high) byte and 13 (low byte). The contents of this address mark the address of
the first eight pixels of the top raster row on the 8563 screen (frame). Add an index to
access successive pixels in successive raster rows.
Since the full 640-by-200 bit map uses almost all of the 16K available in 8563
RAM, there is no room available in memory for attributes such as color.

COLOR ASSIGNMENTS
The pixel color assignments for the 8563 bit map are based on the value of the bit in
memory which corresponds to the pixel on the screen. If the value of the bit in memory
is equal to zero, the pixel is colored in the background color according to the value of
bits 0 through 3 in 8563 register 26. If the value of the bit in memory corresponding to
the screen pixel is equal to one, the pixel is assigned the foreground color determined by
bits 4 through 7 in register 26.
The full-sized 640-by-200 pixel bit map bit takes up almost the full 16K of 8563 RAM.
You may wonder how you can use the attributes for the corresponding screen locations.

315

322

COMMODORE 128

You have two choices: either disable the attributes or reduce the size of your bit
map by 2000 bytes, then define and enable the attributes. With a full-size bit map, you
cannot implement the attributes, because there is simply not enough independent 8563 RAM
to do both. If attributes are disabled, the 8563 bit-map screen uses only two colors, as
specified by the background and foreground color codes in register 26.
If you decide to reduce the size of the 8563 bit map and you want to implement
the attributes, set bit 6 of register 25 to enable attributes. Then place the high-byte
and low-byte addresses in registers 20 and 21, respectively, to define the start of
attribute storage. See the Character Attributes section for more information on attributes.

THE BIT-MAP FRAME SIZE

The size of the bit-map frame defaults to the 640 by 200 raster row dimensions. This
frame (screen) size may be reduced. See the Register-by-Register Description for details
on altering the size of the visual bit-map image.
The next section provides an example of a bit-map program in machine language
containing a program listing and details about the important routines.

8563 BIT MAP PROGRAM

As you know, the 8563 supports bit map mode; however, the BASIC graphics commands are not displayed on the 8563 screen. This section contains a program which
transfers the 40-column VIC screen to the 8563 display screen. The screen is still 40
columns wide, though it provides the vehicle with which to understand how the 8563 bit
map screen is addressed. For easier programming, more graphics features and general
functional design use the VIC chip when bit mapping high resolution graphics. The VIC
chip is principally designed for these purposes. The 8563 is primarily designed for the
80-character column display capability.
Here's the program listing as it appears in the Machine Language Monitor. Enter
the Monitor and start entering the program at address $1800.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

01800 20 B3
01803 A2 19
01805 A9 80
01807 20 77
0180A A9 20
0180C 85 FB
0180E A9 00
01810 85 FA
01812 A2 12
01814 20 77
01817 E8
01818 20 77
0181B A9 00
0181D 85 Bl
0181F A9 19
01821 85 9B
01823 A9 07
01825 85 9C
01827 A9 27

18 JSR
LDX
LDA
18 JSR
LDA
STA
LDA
STA
LDX
18 JSR
INX
18 JSR
LDA
STA
LDA
STA
LDA
STA
LDA

$18B3
# $ 19
#$80
$1877
#$20
$FB
#$00
$FA
#$12
$1877
$1877
#$00
$Bl
#$19
$9B
#$07
$9C
#$27

PROGRAMMING T H E 8O-COLUMN (8563) CHIP

01829
0182B
0182C
0182D
0182F
01831
01834
01837
01838
01839
0183A
0183C
0183E
01840
01842
01843
01844
01845
01847
01849
0184C
0184F
01852
01854
01856
01858
0185A
0185D
0185E
01860
01862
01864
01866
01869
0186C
0186F
01871
01873
01874
01875
01877
0187A
0187D
0187F
01882
01883
01884
01886
01888
0188A
0188C
0188E
0188F
01891
01893
01896
01897
01899
0189A
0189B
0189C
0189E
018A0
018A2
018A4
018A6
018A8
018A9
018AB
018AD

85
EA
EA
A2
A1
20
20
EA
EA
EA
C6
DO
A5
DO
EA
EA
EA
A2
A1
20
20
20
C6
DO
A9
85
4C
EA
A9
85
A2
A1
20
20
20
C6
DO
00
00
A2
8E
2C
10
8D
60
18
A5
69
85
90
E6
60
AO
A9
20
88
DO
60
EA
38
A5
E9
85
A5
E9
85
60
E6
DO
E6

FE
00
FA
75 18
83 18

FE
EF
B1
lC

00
FA
75
8F
9B
9C
D1
01
B1
27

18
18
18

18

00
B1
00
FA
75 18
8F 18
A9 18
9B
BO
1F
00 D6
00 D6
FB
01 D6
FA
08
FA
02
FB
28
00
75 18
F8

FB
01
FB
FA
37
FA
FA
02
FB

STA
NOP
NOP
LDX
LDA
JSR
JSR
NOP
NOP
NOP
DEC
BNE
LDA
BNE
NOP
NOP
NOP
LDX
LDA
JSR
JSR
JSR
DEC
BNE
LDA
STA
JMP
NOP
LDA
STA
LDX
LDA
JSR
JSR
JSR
DEC
BNE
BRK
BRK
LDX
STX
BIT
BPL
STA
RTS
CLC
LDA
ADC
STA
BCC
INC
RTS
LDY
LDA
JSR
DEY
BNE
RTS
NOP
SEC
LDA
SBC
STA
LDA
SBC
STA
RTS
INC
BNE
INC

$FE
#$00
($FA,X)
$1875
$1883

$FE
$182D
$Bl
$185E

#$00
($ FA,X)
$1875
$188F
$189B
$9C
$1827
#$01
$Bl
$1827
#$00
$Bl
#$00
($FA,X)
$1875
$188F
$18A9
$9B
$1823
#$lF
$D600
$D600
$187A
$D601
$FA
#$08
$FA
$188E
$FB
#$28
#$00
$1875
$1891

$FB
#$01
$FB
$FA
#$37
$FA
$FA
$18AF
$FB

317

324

COMMODORE 128

018AF
018B0
018B1
018B2
018B3
018B5
018B7
018B9
018BB
018BD
018BF
018C2
018C3
018C4
018C6
018C8
018CB
018CC
018CD
018CE
018Dl
018D3
018D6
018D8
018DA
018DC
018DE

60
EA
EA
EA
A9
85
A9
85
A2
A9
20
EA
EA
A9
A2
20
E8
EA
EA
20
A9
20
C6
D0
C6
D0
60

00
FC
3F
FD
19
80
77
00
12
77

77
00
75
FC
F7
FD
F3

RTS
NOP
NOP
NOP
LDA
STA
LDA
STA
LDX
LDA
18: JSR
NOP
NOP
LDA
LDX
18 JSR
INX
NOP
NOP
18 JSR
LDA
18 JSR
DEC
BNE
DEC
BNE
RTS

#$00
$FC
# $ 3F
$FD
#$19
#$80
$1877
#$00
# $ 12
$1877

$1877
#$00
$1875
$FC
$18D1
$FD
$18D1

The instructions in this explanation are referenced by the memory addresses that
appear in the left column of the machine language monitor output as in the other
machine language program explanations.
The first instruction (J$R $18B3) jumps to a subroutine to clear the bit map (8563)
screen.
The next sequence of instructions ($1803-$1809) set bit 7 of 8563 register 25 to
select bit map mode. This bit defaults to 0 for text display. The subroutine starting at
$1877 is the familiar register write routine you have seen earlier in the chapter. Notice
that if the subroutine had started at location $1875, it would have written to 8563 RAM
instead of an 8563 register. This routine is called to do so later in the program.
The trick to the success of this program is addressing both the VIC screen and the
8563 screen correctly. The second sequence of instructions ($180A-$1816) define the
high byte of the 16-bit address for the start of both the VIC and 8563 screens. First the
X register is loaded with the value 18 ($12) which selects 8563 register 18, the 8563
RAM address high pointer. The accumulator is loaded with the value $20, which is
stored in location $FB, the VIC bit map pointer (high byte). Now the accumulator is
cleared to zero and the write register subroutine places the value zero into the 8563 bit
map (high byte) pointer.
The instructions $1817 through $181A perform the same operation for the low
byte of both the VIC and 8563 bit map pointers.
The instructions between $1820 and $1827 initialize the variables $FC, $FD, $B1
and $9C to zero. The variables $FC and $FD are the low and high byte pointers for the
8563 bit map RAM addresses. The variable $B1 is the column counter for the VIC
screen. The variable $9C is the counter that keeps track of how many addresses to skip
in 8563 RAM. This is explained later in the program.

PROGRAMMING T H E 8O-COLUMN (8563) CHIP

Here's where a major difference between the two video chips becomes important
the way the bit map corresponds to the image on the screen. As you know, the VIC
screen stores eight rows of 8 pixels each to make up one character cell. Each row of the
eight pixels in a character on the screen are stored consecutively in memory. For
example, the HOME character position is stored in default locations $2000 through
$2007 for the bit map. The next character position (as if the display was standard text)
to the right of the HOME Position is stored between $2008 and $2015. So the first
character row is stored between $2000 and $2A00 ($2000 plus (8*8) * 40 =2560). This
is represented graphically in the preceding section (Figure 10-5).
On the other hand, the 8563 stores a bit map across raster rows on the screen.
Each set of eight pixels of a raster row is stored in a memory location in 8563 RAM
starting at $0000. For example, the first raster row is stored in locations $0000 through
$0050, one location for each group of eight pixels. The 8563 screen is 640 pixels across;
therefore each row needs 80 bytes of storage in 8563 RAM.
Now you see how the two bit maps are addressed differently. To fully understand
how this program gets data from the VIC bit map and places it in the correct spot on the
8563 bit map, this algorithm is provided. The actual instructions to perform these steps
are added later. Here's the general scheme you need to follow:
1.
2.
3.
4.
5.

Start at the beginning of both the VIC and 8563 bit map locations.
Get a VIC bit map byte.
Store it in the 8563 bit map.
Increment the VIC bit map pointer 8 times (the 8563 pointer increments itself
after a write).
Do steps 2, 3 and 4 thirty-nine times.

At this point, you have just transferred the first raster row of the VIC bit map onto
the 8563 bit map.
6.

7.

After each raster row is transferred, subtract311 from the VIC bit map pointer.
This is done 7 times. On the eighth time, the VIC bit map pointer is
incremented by 1 to get the to the start of the next VIC character cell.
Perform 40 blank write operations (write zeros to the 40 blank columns) to
get to the beginning of an 8563 raster row. Remember, the 8563 bit map
pointer must be relative to the VIC screen bit map pointer.

If the VIC column counter equals 39, increment the 8563 bit map pointer 41
times to place its relative position at the start of a new character row according to the
VIC bit map.
8.

Now repeat the process 25 times, once for each character row.

319

326

COMMODORE 128

In the program, as discussed, the instructions in $180A through $181A start the
VIC and 8563 bit maps at locations $2000 and $0000 respectively. All these instructions
encompass step 1 of the algorithm.
The instructions that perform step 2 of the algorithm are stored at locations
$182D-$1830.
Step 3 stores the VIC bit map byte at the 8563 bit map position and is performed
by the instruction $1831 and the subroutine stored between $1875 and $1882. This
subroutine writes the value stored in the accumulator into the appropriate address in
8563 RAM as specified by the contents of 8563 registers 18 ($12) and 19 ($13).
The instructions stored at $183A through $183D perform the fourth step of the
algorithm.
The stored in $1883 through $188E update the VIC bit map pointer by 8.
Steps 2, 3 and 4 are performed while the pixel row counter in $9C is less than
seven. If it is less than seven, the next byte of the VIC bit map is loaded and stored into
the 8563 bit map.
Step 6 is contained in the subroutine starting at ($189B). This decrements the VIC
bit map pointer by 311 locations.
Step 7 of the algorithm is contained in the subroutine stored in locations $188F
through $1899.
Finally, step 8 of the algorithm is performed by the instructions $186F through
$1872.
This program allows you to transfer one bit map to the other, but leaves the VIC
bit map as 40 columns. Expand on the algorithm in this section and center the bit map
on the 80-column screen. Write a routine that proportionally spaces the 40-column bit
map and places it on the entire 80-column screen. Also add a routine that clears the
other half of the 80-column bit map. Add these routines to any business application, and
you'll have a valuable business tool which you can use completely within the 8563 chip
that display your character and bit map data.

SCROLLING THE 8563 SCREEN

The 8563 has a feature that allows the screen to scroll smoothly either vertically (up or
down) or horizontally (left or right). The 8563 scrolling feature can be thought of as a
small virtual screen window which is displayed on a portion of a full size 80-by-25
character screen. The virtual screen is only visible through the window you define at the
specified position of the full-sized screen. Both screens however do exist in the 8563
character RAM storage locations.

PROGRAMMING T H E 8O-COLUMN (8563) CHIP

VERTICAL SCROLLING
Scrolling in the vertical direction is easier than scrolling horizontally. The general
algorithm to scroll vertically is as follows:
1.

2.

3.

4.

5.

6.

Set the default start of the character RAM storage to $2000 in 8563 RAM.
This is done through writing to (or using the default contents of) registers
12 ($0C) and 13 ($0D). Now location $2000 in 8563 RAM marks the start
of the first character in the upper left corner of display memory (the HOME
position).
At this point, the size of the screen is 80-by--25 and the screen RAM
locations are from $2000 through $27CF in 8563 RAM. Therefore, the first
80 bytes store the first 80 characters in the top row of the 8563 screen.
Now add 80 ($50) to the low byte of the display RAM Pointer, register 13.
Now the second 80 bytes of the display RAM memory are displayed as the
first character row. The screen is now defined by locations $2050 through
$281F in 8563 memory. This moves the characters up one character row. The
" o l d " first character row has moved off the top of the screen and the " n e w "
character row has moved onto the last character row of the screen from a
previously non-visible range in display area. The new character row should be
defined in 8563 RAM before it is moved onto the screen as the last character
row.
Though this moves an entire character row of display RAM up by one row,
the movement is sudden, abrupt and not smooth. The 8563 allows smooth
scrolling to occur vertically, through the lower four bits of register 24 ($18) in
the 8563.
To scroll smoothly one scan line at a time, write the value 1 to register
24. This moves the entire screen up by one scan line. The first previously
visible scan line is now off screen at the top and a new scan line is scrolled
from an off screen location from the bottom onto the last visible scan line of
the screen.
To scroll subsequent scan lines, increment the value of the lower four bits of
register 24. By incrementing this value to 2, the entire screen is smoothly scrolled
an additional scan line.
Continue to increment the value in register 24 until the value equals the value
stored in the lower four bits of register 9, the total number of vertical scan
lines of a character. Once these values are equal, only the bottom scan line of
the first character row is visible at the top of the screen, and all but the
last scan line of the newly scrolled data is visible at the bottom of the screen.
To continue to scroll, reset the value in the lower four bits of register 24 to
zero and add 80 more locations to the contents of the display RAM pointer as
you did in step 2.
If you plan to use attributes, you must increase the value of the attribute
start pointer also to keep up with the display RAM pointer.

321

328

COMMODORE 128

01800
01802
01804
01806
01809
0180A
0180C
0180E
01811
01812
01814
01816
01817
0181A
0181B
0181C
0181D
0181F
01821
01822
01823
01825
01828
0182A
0182C
0182E
01830
01831
01833
01835
01837
01839
0183C
0183D
01 8 3 F
01842
01844
01846
01848
0184A
0184C
0184E
01850
01852
01 8 5 4
01856
01859
0185A
0185B
0185C
0185D
0185E
0185F
01860
01863
01866
01868
0186B

A2
A9
85
20
E8
A9
85
20
EA
A2
A9
A8
20
EA
C8
98
CO
DO
EA
EA
A9
20
AO
E6
DO
E6
C8
CO
DO
A2
A5
20
E8
A5
20
A9
85
A9
85
E6
DO
E6
A5
C9
DO
4C
EA
EA
EA
EA
EA
EA
EA
8E
2C
10
8D
60

0C
20
FB
60 18
00
FA
60 18
18
01
60 18

08
F6
00
60 18
00
FA
02
FB
50
F5
0C
FB
60 18
FA
60 18
00
FD
00
FC
FC
FC

FD
FD
AO
F0
12 18

00 D6
00 D6
FB
01 D6

LDX
LDA
STA
JSR
INX
LDA
STA
JSR
NOP
LDX
LDA
TAY
JSR
NOP
INY
TYA
CPY
BNE
NOP
NOP
LDA
JSR
LDY
INC
BNE
INC
INY
CPY
BNE
LDX
LDA
JSR
INX
LDA
JSR
LDA
STA
LDA
STA
INC
BNE
INC
LDA
CMP
BNE
JMP
NOP
NOP
NOP
NOP
NOP
NOP
NOP
STX
BIT
BPL
STA
RTS

#$0C
# $ 20
$FB
$1860
#$00
$FA
$1860
#$18
#$01
$1860

#$08
$1817
#$00
$1860
#$00
$FA
$1830
$FB
# $ 50
$182A
#$0C
$FB
$1860
$FA

$1860
#$00
$FD
#$00
$FC
$FC
$184A
$FD
$FD
# $ A0
$1846
$1812

$D600
$D6 00
$1863
$D601

HORIZONTAL SCROLLING
Horizontal scrolling is more complex than vertical scrolling. First, the Display RAM
memory must be set up to match the "virtual" screen size. If the "virtual" screen is
132 characters wide, then the Display RAM memory must be organized as if 132
characters were to be displayed, even if only 80 horizontal characters will be displayed

PROGRAMMING T H E 8O-COLUMN (8563) CHIP

in the 8563 " w i n d o w . " This means that to display a window of 25 rows of 80
characters of a virtual screen of width 132 characters, the Display RAM memory must
have at least 3300 (132 x 25) memory locations and the same number of attributes.
To display a horizontal " w i n d o w " of 80 characters, the 8563 must first read the
first 80 display memory locations and attributes from the first 132-character row, and
then " s k i p " the next 52 (132-80) and proceed to read the next 80 pointers and attributes
from the second 132-character row. The amount of the " s k i p " must be written to R27.
In this case " 5 2 " is written to R27 at system initialization.
When horizontal scrolling is not used, a " z e r o " written to R27 will cause the
8563 to skip no display memory locations or attributes, allowing the "virtual" screen in
Display RAM memory to be the same width as the 8563 window.
Now that the 8563 has been set up to view a window 80 characters wide out of a
virtual screen of 132 characters wide, horizontal scrolling may occur by modifying the
address in R12/R13 (DISPLAY START ADDRESS) and R20/R21 (ATTRIBUTE START
ADDRESS). Increasing these addresses by one will scroll the entire screen " l e f t " one
character. The first character of each character row will be scrolled " o f f " the left side
of the screen, all characters on the screen will be moved one space to the left, and one
extra character will be scrolled onto the right side of the screen. Simple manipulation of
the address in R12/R13 and R20/R21 will scroll the window to the left or right.

SMOOTH HORIZONTAL SCROLLING

The 8563 has the ability to scroll smoothly in the horizontal direction. Horizontal
smooth scrolling moves all characters on the screen the desired number of pixels to the
" l e f t , " up to the width of one character. Before horizontal smooth scrolling can occur,
the 8563 must have something to scroll " o n t o " the right side of the screen, so R27 must
be greater than zero. This sets up a virtual screen at least one character greater than the
displayed screen.
The screen is scrolled left by one pixel by changing the contents of R25(3-0) to
" o n e " and increasing the contents of R22(3-0) by one. Both registers must be changed
to scroll horizontally.
The number in R25(3-0) and R22(3-0) may be increased, increasing the number
of pixels scrolled, until R25(3-0) equals R 2 2 ( 7 ^ ) . This is the maximum amount of
horizontal smooth scrolling allowed. At this point, only one (the right) pixel will exist
for the first character of each character row and the last character will have scrolled onto
the row with only the one (the right) pixel still not visible. To scroll further, the CPU
must change R25(3-0) back to zero and increase R12/R13 (DISPLAY START ADDRESS) and R20/R21 (ATTRIBUTE START ADDRESS) each by one to scroll horizontally by one character. This sequence will have smooth-scrolled left by one character.

323

324

COMMODORE 128

REGISTER-BY-REGISTER
DESCRIPTION
This section describes each 8563 register in detail by register number. The significant
bits are isolated and explained separately.
The conventions used in the register descriptions are as follows:
Rn (msb-lsb)
The R stands for "register." The letter n represents the register number, ranging
from 0 through 36. The msb stands for "most significant bit" in that particular
description. Often the most significant bit is assumed to be bit 7; however, in this
discussion, bit 7 is not always the most significant.
The notation lsb stands for "least significant bit" in the particular register
description. Generally, the least significant bit is assumed to be 0; however, in this
description 0 is not always the least significant.
If a single bit number is enclosed in parentheses, then this is the only bit explained
for that particular function.
Consult this section as a quick reference. See the main body of the chapter for
additional background on programming the 80-column display.

R0

HORIZONTAL TOTAL

The number of characters, minus 1, between successive horizontal sync pulses. This
number includes the displayed part of a character row, the horizontal border and the
blanking interval during horizontal sync pulses.

Rl

HORIZONTAL DISPLAYED

The number of characters displayed on each character row. This number sets the width
of the displayed part of the character row.

R2

HORIZONTAL SYNC POSITION

The number of characters from the beginning of the displayed part of a character row to
the start of the horizontal sync pulse. This register controls the horizontal position of the
text on the CRT screen. This number should be greater than the number in R l
(horizontal displayed).

R3(3-0)

HORIZONTAL SYNC WIDTH

The width of the horizontal sync pulse in characters, plus 1.

R3(7-4)

VERTICAL SYNC WIDTH

The width of the vertical sync pulse in scan lines. This number sets the duration of the
vertical sync pulse, which may extend past the end of the current frame into the next
frame. In the interlaced sync and video mode, this register should be programmed with a
value equal to twice the number of scan lines desired.

PROGRAMMING THE 8O-COLUMN (8563) CHIP

R4

VERTICAL TOTAL

The number of character rows, minus 1, between successive vertical sync pulses. This
number includes the displayed rows, vertical border and the blanking interval during the
vertical sync pulse and determines the vertical sync rate.

R5(4-0)

VERTICAL TOTAL ADJUST

The number of scan lines added to the end of the frame for fine adjustment of the
vertical sync rate. In the interlaced sync and video mode, this register should be
programmed with a value equal to twice the number of scan lines desired.

R6

VERTICAL DISPLAYED

The number of character rows displayed in a frame. This number sets the height of the
displayed part of the frame.

R7

VERTICAL SYNC POSITION

The number of character rows, plus 1, from the first displayed character row to the
start of the vertical sync pulse. This number should be greater than the number in R6
(vertical displayed).

R8(l-0)

INTERLACE MODE CONTROL

There are three raster-scan display modes: non-interlaced, interlaced sync, and interlaced
sync and video. The non-interlaced mode has been described above. In this mode, each
scan line is refreshed at the vertical sync rate. This mode is selected by setting R 8 ( l - 0 )
equal to 00 or 10.
In the interlaced sync mode [R8(l-0) = 01], even and odd fields alternate to
generate frames. The same information is displayed in both odd and even fields but the
vertical sync timing causes the scan lines in the odd fields to be displaced from those in
the even fields by one-half scan line. The spaces between adjacent scan lines are filled,
resulting in a higher-quality character on monitors designed to receive interlaced video.
In the interlaced sync and video mode [R8(l-0) = 11] even and odd fields
alternate to generate frames. Odd fields display odd scan lines, and even fields display
even scan lines. This doubles the vertical character density on the screen. To display
twice as many character rows, the user must re-initialize the 8563 registers. In this
mode, the vertical sync width [ R 3 ( 7 ^ ) ] and the vertical total adjust [R5(4-0)] should be
programmed with even values. The duration of each of these events (in scan lines) will
be one half the value programmed into the registers.

R9(4-0)

CHARACTER TOTAL, VERTICAL

The number of scan lines, minus 1, in a character. This number includes the displayed
part of a character and the vertical intercharacter spacing below the displayed part. This
register sets the vertical dimension of a character and the vertical dimension of a
character row.

325

326

COMMODORE 128

RI0(4-0)

CURSOR START SCAN LINE

The number of the first (top) scan line of the reverse-video cursor. The number 0 refers
to the first (top) scan line of the character. This register and register 11 (below) define
the cursor height, and can create a variety of effects, from a block cursor to an underline
cursor.

RI0(6-5)

CURSOR MODE

The cursor can be programmed to four different modes by programming R10(6-5) to a

00 (solid cursor), 01 (no cursor), 10 (cursor blinking at one sixteenth the frame rate), or
11 (cursor blinking at one thirty-second the frame rate).

Rl 1(4-0)

CURSOR END SCAN LINE

The number of the last (bottom) scan line of the reverse-video cursor, plus 1.

RI2, RI3

DISPLAY START ADDRESS (HIGH, LOW)

The address of the first (left) 8 pixels of the top scan line of the frame is defined by R12
and R13. The most significant 8 bits are in R12, the least significant in R13. These set
the complete 16-bit address for the first 8 pixels. The address of subsequent sets of 8
pixels on that scan line are incremented from the previous address. The bit-mapped pixel
data for a scan line is fetched from adjacent memory locations. A frame of 640
horizontal by 200 vertical pixels will use 16,000 bytes of display 8563 RAM memory
locations (R12, R13) through (R12, R13 + 15999).
The bit map attributes are a set of Display RAM bytes, each of which
corresponds to a character position on the frame. The 8-bit attribute defines additional
characteristics of the character area at that position on the frame. These characteristics
(attributes) are as follows: Bits 3 - 0 are foreground R, G, B and I, respectively. Bits 1-4
are background R, G, B and I, respectively. For a frame of i rows of j characters each,
the first j attributes will define the attributes for the first (top) character row, and (i X j)
attributes will need to be defined in display 8563 RAM. For a bit-mapped frame of 25
characters high and 80 characters wide, 2000 attributes will be needed.

RI2, RI3

DISPLAY START ADDRESS (HIGH, LOW)

The address for the pointer of the first (top-left) character of the frame is defined in R12
and R13. The most significant eight bits is in R12, the least significant in R13. These
set the complete 16-bit address for that first pointer. The address of pointers of
subsequent characters are incremented from the previous address, so horizontally adjacent characters have pointers in adjacent memory locations. A frame of 25 character
rows of 80 characters each will use 2000 pointers of display 8563 RAM memory
locations (R12/13) through (R12/13 + 1999).

RI4, RI5

CURSOR POSITION

The position of the cursor is set by R14 and R15. These two registers contain the 16-bit
address of the cursor. R14 is the most significant byte, R15 the least significant. If the
address of R14/R15 is the address of a character within the displayed part of the frame,
then that character will be displayed in reverse video for those scan lines determined by

PROGRAMMING T H E 8O-COLUMN (8563) CHIP

R10(4-0) and R l l ( 4 - 0 ) . These registers allow the 8563 to be programmed for a

reverse-video " b l o c k " cursor, or for an "underline" cursor. The location of the cursor
can be changed by changing the contents of registers R14 and R15.

RI6, RI7

LIGHT PEN VERTICAL, HORIZONTAL

The 8563 supports a light pen function. When the LPEN input pin transitions from a low
to high, the 8563 latches the current vertical and horizontal character counts in the two
light pen registers. The vertical count is latched in R16. LPEN transitions that occur
during the row at the top of the frame will latch a 1 in R16. Transitions on subsequent
rows will latch 2, 3, etc. The horizontal count is latched in R17. LPEN transitions that
occur during the leftmost character column will latch an 8. Transitions on subsequent
columns will latch 9, 10, etc. The condition of the light pen registers is latched in bit 6 of
the status register. If 0, the light pen registers have not been latched and contain invalid
data. If 1, the registers contain valid latched data. A CPU read of R16 or R17 resets
the Status Register bit.

READ A N D WRITE DISPLAY

8563 RAM MEMORY
RI8, RI9
R3l

UPDATE LOCATION
CPU DATA

The CPU communicates to the 8563 RAM memory via address and data registers in
the 8563. For the CPU to read a memory location, it must place that address in registers
R18 (most significant byte) and R19 (least significant). The 8563 responds by executing
a read of that memory location and placing that data into R31, which the CPU may then
read. During the time that the " r e a d " is pending and data is not yet valid in R31, the
Update Ready bit of the status register (bit 7) will be 0. Upon completion of the read
cycle, data will be valid in R31 and the bit will be 1. When the CPU reads the data in
R31, the 8563 increments the address in R18/R19 and performs a read of that address.
This allows the CPU to read successive memory locations without repeatedly changing
the addresses in R18/R19.
For the CPU to write data to a memory location, the address must be written to
R18/R19 as in a " r e a d " described above. Following the automatic read and after the
Update Ready bit is a 1, the CPU should write the desired data to R31. The 8563 then
writes the data to 8563 Memory at the address defined by R18/R19, increments the
address in R18/R19, reads the data from the incremented memory location and places it
in R31. The 8563 then sets the Update Ready bit to a 1. At all times, if the Update
Ready bit is a 0, then CPU access to 8563 memory is pending. Additional access of R18,
R19 or R31 should be avoided until the Update Ready bit is a 1.

R20, R2l

ATTRIBUTE START ADDRESS (HIGH, LOW)

The address for the attribute of the first (top-left) character of the frame is defined in
R20 and R21. The most significant 8 bits is in R20, the least significant in R21. These
set the complete 16-bit address for that first attribute. The address of attributes of

327

328

COMMODORE 128

subsequent characters are incremented from the previous address, so horizontally adjacent
characters have attributes in adjacent memory locations. A frame of 25 character rows of
80 characters each will use 2000 attributes at display 8563 RAM memory locations
(R20/R21) through (R20/R21 + 1999).

R22(3-0)

CHARACTER DISPLAYED, HORIZONTAL

This number sets the width of the displayed part of the character, and defines the
horizontal intercharacter spacing to the right of the displayed part.
If the defined character is to have no horizontal intercharacter spacing, then
R22(3-0) should be initialized with a value equal to (the value of R22(7-4) plus 1). This
value may remain constant even with the use of horizontal smooth scrolling.
If the defined character is to have horizontal intercharacter spacing, then R22(3-0)
should be initialized with a value equal to the number of pixels (horizontal) in the displayed
part of a character, minus 1. In this case, the value of R22(3-0) must be changed along
with R25(3-0) to implement horizontal smooth scrolling.
In the pixel double-width mode, the value written to R22(3-0) should be 1 larger
than the numbers described above.

R22(7-4)

CHARACTER TOTAL, HORIZONTAL

The number of pixels (horizontal) in a character, minus 1. This number includes the
displayed part of a character and the horizontal intercharacter spacing to the right of
the displayed part. This register sets the horizontal dimension of a character.
In the pixel double-width mode, the value written to R 2 2 ( 7 ^ ) should be the number of
pixels (horizontal) in a character. Do not subtract 1 from the value in this mode.

R23(4-0)

CHARACTER DISPLAYED, VERTICAL

The number of scan lines, minus 1, of the displayed part of a character. This number
sets the height of the displayed part of the character, and defines the vertical intercharacter
spacing below the displayed part.
R23(4-0) can be equal to or less than R9(4-0). If they are equal, then the
displayed part of the character is equal to the total character, and the entire character is
displayed, with no vertical intercharacter spacing.

R24(4-0)

VERTICAL SMOOTH SCROLL

The sudden scroll of an entire character row is too abrupt a change for some applications. The 8563 supports a method of vertically scrolling the screen one scan line at a
time, up to one full character row. This is called vertical smooth scroll. This operates
along with vertical scrolling to allow the screen to be scrolled up or down smoothly for
as many character rows as desired.
To scroll the screen one scan line 'up' vertically, the CPU should write a 1 to
R24(4-0). This will skip the first scan line of the first character row. The first character
row will then begin with the second scan line, moving it 'up' one scan line. All
character rows on the frame will be movqd 'up' one scan line also. At the bottom of the
Frame, one additional scan line will be displayed of a 'new' character row. This will
actually display parts of " N + 1" character rows instead of the standard N.

PROGRAMMING T H E 8O-COLUMN (8563) CHIP

The number in R24(4-0) can be increased, increasing the number of scan lines
scrolled, until R24(4-0) equals R9(4-0). This is the maximum amount of smooth scroll
allowed. At this point, only one (the bottom) scan line will exist for the first character
row and the last character row will have scrolled onto the frame with only the last scan
line not visible. To scroll further, the CPU must change R24(4-0) back to 0, and
increase R12/R13 (display start address) and R20/R21 (attribute start address) to scroll
vertically by one character row. This sequence will have smooth scrolled by one
character row.

R24(5)

CHARACTER BLINK RATE

When attributes are enabled, the attribute byte for each character contains a bit that
controls the blinking of that character. The rate at which the characters blink is
determined by R24(5). If this bit is a 0, then the character blink rate is one-sixteenth of
the frame rate, if 1, then one thirty-second of the frame rate.

R24(6)

REVERSE SCREEN

The complete screen can be reversed (foreground and background colors reversed) by
changing R24(6). With this bit 0, the screen will be displayed with normal foreground/
background colors. A 1 will reverse the foreground and background colors for each
character on the screen. This reversal will re-reverse any character normally reversed by
the cursor and/or the individual character reverse attribute.

R24(7)
R30

BLOCK COPY
WORD C O U N T

To further improve the speed at which the CPU can manipulate 8563 memory, two
additional features have been added to the 8563: Block Write and Block Copy. Block
Write is an extension of the CPU write cycle except that Block Write writes the same
data to more than one successive memory location. This operation is set up by writing
the initial address to R18/R19, waiting for the Update Ready Status bit to be 1, writing
the data to R31 and again waiting for the Update Ready Status bit to be 1. This is the
same as CPU write (above). The CPU must then write a 0 to R24(7) selecting the Block
Write mode, then write to R30 the number of successive memory locations the 8563
should write. Following the write to R30, the 8563 will initiate one or more write cycles
to 8563 memory, writing the data in R31 to successive memory locations. The contents
ofR18/R19 will increment with the addresses being written. After the Block Writes are
completed, R18/R19 will contain the address following the last memory location written.
NOTE: One write cycle will follow the initial write of data to R31, so
the quantity written to R30 should be one less than the total number of
memory locations desired to be written.

R25(3-0)

SMOOTH HORIZONTAL SCROLL

The 8563 has the ability to scroll smoothly in the horizontal direction. Horizontal
smooth scrolling moves all characters on the screen to the 'left' the desired number of

329

330

COMMODORE 128

pixels, up to the width of one character. Before horizontal smooth scrolling can occur,
the 8563 must have something to scroll 'onto' the right side of the screen, so R27 must
be greater than 0. This sets up a virtual screen at least one character greater than the
displayed screen.
An unscrolled screen is obtained with the value of R25(3-0) equal to the value of
R22(7-4) (character total, horizontal). The screen is scrolled left by one pixel by
decreasing the contents of R25(3-0) by 1. Additional scrolling occurs with decreasing
values programmed. Maximum scrolling is achieved with a value of 0 in R25(3-0). At
this point, only one (the right) pixel will exist for the first character of each character
row and the last character will have scrolled onto the row with only one (the right) pixel
still not visible. To scroll further, the CPU must change R25(3-0) back to its maximum
value and increase R12/R13 (Display Start Address) and R20/R21 (Attribute Start
Address) each by 1 to scroll horizontally by one character. This sequence will have
smooth scrolled left by one character.
If the character has any nondisplayed pixels {R22(3-0) less than [R22(7-4) plus
one]} then the value of R22(3-0) (character displayed, horizontal) must be changed
along with R25(3-0) for horizontal scrolling. The value of R22(3-0) should be equal to
[(the number of horizontal pixels in the displayed part of a character) plus (the value of
R25(3-0), horizontal smooth scroll)] modulo [(the value of R22(7-4), character total,
horizontal) plus 1]. In this case both registers R25(3-0) and R22(3-0) must be changed
to scroll horizontally.
For example, for a character 8 pixels wide with 5 pixels wide displayed:

Unscrolled
Scroll 1
Scroll 2
Scroll 3
Scroll 4
Scroll 5
Scroll 6
Scroll 7

R22(7^4)

R25(rt)

R22(M)

7
7
7
7
7
7
7
7

7
6
5
4
3
2
1
0

4
3
2
1
0
7
6
5

There are two different versions of the 8563 chip (80-column RGBI) in production, requiring slightly different register initialization values.
The difference between the 8563-R7A and subsequent revisions (8563-R8 and
8563-R9) is in the horizontal smooth scroll feature, represented by bits 0 - 3 of register
25. Even if this feature is not utilized, the correct value must be placed into this register
for a normal 80-column display. Software designed specifically for 8563-R7As will
exhibit a problem with the leftmost side of the display when run on a system with R8s or
R9s, and software designed specifically for 8563-R8s and R9s will exhibit a problem
with the rightmost side of the display when run on a system with R7A. To run correctly
on any system, the software must initialize register 25 with the correct data for the

P R O G R A M M I N G T H E 8 O - C O L U M N (8563) C H I P

particular 8563 version in the system. The 8563 version can be easily ascertained
through software by reading the 8563 status register, located at $D600 in 1/0 memory.
Bits 0 - 2 contain the version number. Refer to the table below for the actual data to be
used.

8563 rev

version ($D600)

register 25 value

7A
8
9

0
1
1

$40
$47
$47

This situation does not directly affect software which utilizes the resident C128
operating system (Kernal). The Kernal correctly determines which version of the 8563 is
present and initializes it accordingly. Software which relies on the Kernal IOINlT
routine to accomplish this initialization will not have any problems. Software which
performs the initialization itself, or alters the contents of the affected register, may
exhibit the 80-column display anomalies described above, but will otherwise function
normally.

R25(5)

PIXEL DOUBLE WIDTH

A change from an 80-column frame to a 40-column frame requires the registers of the
8563 to be initialized differently and requires a different pixel rate. To simplify this
change, a control bit on the 8563 causes the DCLK input signal to be divided by 2. If
R25(4) is a 0, then the pixel width is one DCLK period. If it is a 1, then the pixel width
is two DCLK periods and the internal character clock period is twice the normal period.
The AC timing is the same as normal. The 8563 RAM bus cycles occur at half the
normal rate, with the " i d l e " time spent with RAS and CAS " h i g h . " Note that the
contents of the horizontal initialization registers, and the contents of R22(7^t) and
R22(3-0) must be initialized with different values in this mode.

R25(5)

SEMIGRAPHIC MODE

The displayed part of a character is limited to 8 pixels wide owing to the width of the
Display Data Bus (DD0-DD7). Low-resolution graphics regularly use a "block-graphics"
character set that may exceed 8 pixels in width. The 8563 allows this in a limited way
by allowing the last displayed pixel of a character to be repeated in the horizontal
intercharacter space, which is normally forced to the background color. If the control bit
R25(5) (semigraphic mode) is a 0, then normal character operation occurs. If it is a 1,
then semigraphics operation occurs, allowing characters to extend into the horizontal
intercharacter space, touching the next character.

R25(6)

ATTRIBUTE ENABLE

In some applications, attributes are not necessary. In these cases, the amount of 8563
RAM memory used by the attributes may be excessive, so the 8563 has a control bit to

331

332

COMMODORE 128

disable attribute usage. If R25(6) is a 0, then attributes will not be fetched by the 8563
and the RAM memory may be used for other purposes. In this case, no character may be
underlined, individually reversed or blinked. Only one character set of 256 characters
may be used. The foreground color of all characters will be the same and will be
determined by R 2 6 ( 7 ^ ) . The background color will still be set by R26(3-0). If R25(6)
is a 1, then attributes will be used normally.

R25(7)

MODE SELECT (Text/Bit Map)

The 8563 is primarily a text display device, but it does support a limited bit-mapped
graphics mode. In the text mode, the displayed frame is an array of characters, each
with a unique pointer to reference the character, and an attribute to define additional
display characteristics. In the bit-mapped mode each pixel is controlled by a unique bit
in 8563 RAM memory. For text operation, bit 7 is initialized to a 0; for bit-mapped
operation, set bit 7. Refer to the Bit-Mapping the 80-column Display section in this
chapter for more information.

R26(3-0)

BACKGROUND R, G, B, I

In all cases, the background color is determined by R26(3-0). The borders surrounding
the screen and the vertical and horizontal intercharacter spaces are displayed at the
background color.

R26(7-4)

FOREGROUND R, G, B, I

When attributes are disabled, the foreground color for all characters is determined by
R26(7-4).

R27

ADDRESS INCREMENT PER ROW

An additional feature of the 8563 is the ability to scroll horizontally, both left and right
through display 8563 RAM memory. To scroll a window of i horizontal bytes by j
vertical scan lines across a virtual screen of k horizontal by 1 vertical (i < k) there must
be (k x 1) bytes of bit-mapped data in display 8563 RAM memory. The 8563 must
" s k i p " (k-i) bytes on every scan line, because only i bytes are displayed of a virtual
line of k bytes in display 8563 RAM memory. The 8563 has the ability to skip a number
of bytes, set by writing to R27. If R27 is 0, then no bytes will be skipped. A nonzero
value in R27 is necessary to allow horizontal smooth-scrolling.
The value in R27 is used to increment the address of the bit-mapped data from one
scan line to the next and to increment the address of the attributes from one character row
to the next. Both the bit-mapped data and the attributes will be incremented by the same
amount, the value of R27.

R28(4)

8563 RAM TYPE (4416/4164)

The data for the displayed text is stored in a dynamic RAM dedicated to the display and
external to the 8563. The CPU accesses this 8563 RAM display memory indirectly
through the 8563 internal registers. The 8563 internally calculates 16-bit RAM addresses, so can address up to 64K bytes of 8563 RAM. The 8563 RAM addresses may

PROGRAMMING T H E 8O-COLUMN (8563) CHIP

be configured to be compatible with 4164 8563 RAMs (64K by 1) or with 4416 8563
RAMs (16K X 4). Register 28, bit 4 should be initialized to a 0 for operation with
4416s a 1 for operation with 4164s.
4416: Row/Col - A7/A15, A6/A13, A5/A12, A4/A11, A3/A10, A2/A9, Al/A8,
A0/A8
4164: Row/Col = A7/A15, A6/A14, A5/A13, A4/A12, A 3 / A l l , A 2 / A 1 0 , Al/A9,
A0/A8

R28(7-5)

CHARACTER SET START ADDRESS

The starting location of the character set in display 8563 RAM is determined by
R28(7-5). These bits form the most significant 3 bits of the 16-bit address used to
access character data. If R9(4-0) is greater than 15, then only bits 7 - 6 of R28 will be
used, because each character set will occupy 8192 bytes of 8563 RAM memory.
The character pointers correspond to a displayed character position on the frame.
The 8-bit pointer selects one of the 256 characters in the character set to be displayed at
that position on the frame. For a frame of i rows of j characters each, the first j pointers
will define the characters in the first (top) character row, and (i x j) pointers will need
to be defined in display 8563 RAM. For 25 character rows of 80 characters each, 2000
pointers will be needed.

R29(4-0)

UNDERLINE SCAN LINE C O U N T

The number of the scan line used for underline. The underline is defined as a single scan
line. Scan line 0 refers to the scan line at the top of the character.

R32, R33

BLOCK COPY SOURCE ADDRESS

Block Copy is similar to Block Write, except that the data written to 8563 memory is
obtained from other successive memory locations. The Block Copy actually 'copies'
one part of 8563 memory to another. To set this operation up, the CPU writes the initial
Destination Address to R18/R19, waits for the Update Ready Status bit to be 1 and
writes a 1, to R24(7) selecting the Block Copy mode. The CPU then writes the initial
source address to R32 (most significant byte) and R33 (least significant), then the
number of successive memory locations to be copied should be written to R30. The
8563 will then read the contents of the first source address and write that data to the first
destination address. Additional copies will occur at addresses incremented from the
source and destination addresses, for as many words as are defined in R30.

R34, R35

DISPLAY ENABLE BEGIN, END

During the horizontal and vertical synchronization pulses, the R, G, B and I signals must
be blanked (brought to a low level) to prevent the display of the scanning beam during
retrace times. Two registers allow the user to adjust the beginning (R34) and end (R35)
of the horizontal blanking interval.
Register R34 is programmed with the number of characters from the first displayed character of a row to the first blanked character in that row. Register R35 is
programmed with the number of characters from the first displayed character of a row to
the last blanked character in that row. Blanking occurs on all scan lines of a frame.

333

334

COMMODORE 128

R36(3-0)

8563 RAM REFRESH/SCAN LINE

The number of Dynamic RAM refresh cycles every scan line. These refresh cycles occur
on displayed and nondisplayed scan lines, during the displayed part of the screen and
nondisplayed parts (blanked scan lines, vertical borders and vertical sync). Each refresh
address is incremented from the previous refresh address, incrementing through all
65,536 addresses. The least significant byte of the 16-bit Display 8563 RAM memory
address is used as the row address to the 8563 RAM. As the 16-bit refresh address is
incremented, successive rows of the 8563 RAM are refreshed.

SOUND AND
MUSIC O N THE
COMMODORE 128

335

336

COMMODORE 128

INTRODUCTION
The Commodore 128 has one of the most sophisticated built-in sound synthesizers
available in a personal computer. The synthesizer, called the Sound Interface Device
(SID), is a chip dedicated solely to generating sound and music. The SID chip is capable
of producing three independent voices (sounds) simultaneously. Each of the voices can
be played in one of four types of sounds, called waveforms. The SID chip also has
programmable Attack, Decay, Sustain and Release (ADSR) parameters. These parameters define the quality of a sound. In addition, the synthesizer has a filter you can use to
choose certain sounds, eliminate others, or modify the characteristics of a sound or sounds.
All these features add up to a powerful and versatile synthesizer.
To make it easy for you to select and manipulate the many capabilities of the SID
chip, Commodore has developed new and powerful BASIC music statements.
Here are the new sound and music statements available on the Commodore 128:
SOUND
ENVELOPE
VOL
TEMPO
PLAY
FILTER
The beginning of this section explains these sound statements, in an encyclopedia
format. The second half describes how to program the SID chip in machine
language.

ENVELOPE
Define a musical instrument envelope
ENVELOPE n,[,atk] [,dec] [,sus] [reI][,wf] [,pw]
where:
n
atk
dec
sus
rel
wf

pw

Envelope number (0-9)

Attack rate (0-15)
Decay rate (0-15)
Sustain (0-15)
Release rate (0-15)
Waveform: 0 = triangle
1 = sawtooth
2 = variable pulse (square)
3 = noise
4 = ring modulation
Pulse width (CM095)

SOUND A N D MUSIC O N THE COMMODORE 128

A parameter that is not specified will retain its predefined or currently redefined
value. Pulse width applies to the width of the variable pulse waveform (wf = 2) only.
The Commodore 128 has initialized the following ten envelopes:

wf

pw

ENVELOPE

0,

0,

9,

0,

0,

2,

1536

ENVELOPE

1,

12,

0,

12,

0,

accordion

ENVELOPE

2,

0,

0,

15,

0,

calliope

ENVELOPE

3,

0,

5,

5,

0,

drum

ENVELOPE

4,

9,

4,

4,

3
0

flute

ENVELOPE

5,

0,

9,

2,

1,

guitar

ENVELOPE

6,

0,

9,

0,

0,

2,

512

ENVELOPE

7,

0,

9,

9,

0,

2,

2048

ENVELOPE

8,

8,

9,

4,

1,

2,

512

ENVELOPE

9,

0,

9,

0,

0,

instrument

piano

harpsichord
organ
trumpet
xylophone

FILTER
Define sound (SID chip) filter parameters
FILTER [freq], [,lp] [,bp] [,hp] [,res]
where:
freq
lp
bp
hp
res

Filter cut-off frequency (0-2047)

Low-pass filter on (1), off (0)
Band-pass filter on (1), off (0)
High-pass filter on (1), off (0)
Resonance (0-15)

Unspecified parameters result in no change to the current value.

You can use more than one type of filter at a time. For example, both low-pass
and high-pass filters can be used together to produce a notch-(or band-reject) filter
response. For the filter to have an audible effect, at least one type of filter must be
selected and at least one voice must be routed through the filter.

337

338

COMMODORE 128

EXAMPLES:
FILTER 1024,0,1,0,2

Set the cutoff frequency at 1024, select the band pass

filter and a resonance level of 2.

FILTER 2000,1,0,1,10

Set the cutoff frequency at 2000, select both the low pass
and high pass filters (to form a notch reject) and set
the resonance level at 10.

PLAY
Defines and plays musical notes and elements
PLAY "Vn,On,Tn,Un,Xn,elements"
Vn Voice (n = 1-3)
On Octave (n = 0 - 6 )
TN Tune Envelope Defaults (n = 0 - 9 )
0 = piano
1 = accordion
2 = calliope
3 = drum
4 = flute
5 = guitar
6 = harpsichord
7 = organ
8 = trumpet
9 = xylophone
Un Volume (n = 0-15)
Xn Filter on (n - 1), off (n = 0)
Notes:
A,B,C,D,E,F,G
Sharp
Elements:
#
Flat
$
Whole note
w
Half note
H
Quarter note
Q
Eighth note
I
Sixteenth note
s
Dotted
Rest
R
Wait for all voices currently playing to
M
end current measure

The PLAY statement gives

envelope (including ten predefined
notes you want to PLAY. All these
All elements except R and M

you the power to select voice, octave and tune

musical instrument envelopes), the volume and the
controls are enclosed in quotes.
precede the musical notes in a PLAY string.

SOUND A N D MUSIC O N THE COMMODORE 128

EXAMPLES:
PLAY "VlO4T0U5X0CDEFGAB"

Play the notes C,D,E,F,G,A and

B in voice 1, octave 4, tune envelope 0 (piano), at volume 5, with
the filter off.

PLAY "V305T6U7Xl#B$AW.CHDQEIF"

Play the notes B-sharp, A-flat,

a whole dotted-C note, a half
D-note, a quarter E-note and an
eighth F-note.

SOUND
Create sound effects and musical notes
SOUND v,f,d[,dir][,m][,s][,w][,p]
where:
v
f
d
dir
m
s
w
p

voice (1-3)
frequency value (0-65535)
duration (0-32767)
step direction (0(up), l(down) or 2(oscillate)) default = 0
minimum frequency (if sweep is used) (0-65535) default = 0
step value for sweep (0-32767) default = 0
waveform (0 = triangle, 1 = sawtooth, 2 = variable, 3 = noise) default = 2
pulse width (0^4095) default = 2048

The SOUND command is a fast and easy way to create sound effects and
musical tones. The three required parameters v,f and d select the voice, frequency
and duration of the sound. The duration is in units called jiffies. Sixty jiffies equals
1 second.
The SOUND command can sweep through a series of frequencies which allows
sound effects to pass through a range of notes. Specify the direction of the sweep with
the DIR parameter. Set the minimum frequency of the sweep with M and the step value
of the sweep with S. Select the appropriate waveform with W and specify P as the width
of the variable pulse waveform if selected in W.
EXAMPLES:
SOUND 1,40960,60

Play a SOUND at frequency 40960 in voice 1

for 1 second.

SOUND 2,20000,50,0,2000,100

Output a sound by sweeping through frequencies starting at 2000 and incrementing upward
in units of 100. Each frequency is played for
50 jiffies.

339

340

COMMODORE 128

SOUND 3,5000,90,2,3000,500,1

This example outputs a range of sounds starting at a minimum frequency of 3000, through
5000, in increments of 500. The direction of
the sweep is back and forth (oscillating). The
selected waveform is sawtooth and the voice
selected is 3.

EXAMPLES:
SOUND 1, 49152, 240, 1, 0, 100, 1, 0
A.

A.

A.

A^ A.

Voice
Frequency
Duration
Sweep Direction
Minimum Sweep Frequency
Step Value for Sweep
Waveform
Pulse Width for Variable Width Waveform

DO
PRINT"VC FREQ DIR MIN
SV
WF
V=INT(RMD(1)*3)+l
REM VOICE
F = INT(RND( 1 )*65535 ) REM FREQ
D=INT(RND( 1 )*32767 ) REM DURATION
60 DIR=INT(RND(1)*3)
REM STEP DIR
70 M=INT(RND(1)*65535)
REM MIN FREQ
80 S = INT(RND(1 )*32767 )
REM STEP VAL
90 W=INT(RND(1)*4)
REM WAVEFORM
100 F=INT(RND(1)*4 0 95)
REM PLJLSE W
110 PRINT V; F;DIR;M;S; W;P:PRINT:PRINT
120 SOUND V, F, D, DIR, M, S, W, P
130 SLEEP 4
140 SOUND V, 0, 0, DIR, 0, 0, W,
150 LOOP
10
20
30
40
50

PW ":PRINT

TEMPO
Define the speed of the song being played
TEMPO n
where n is a relative duration between (0 and 255)
The actual duration for a whole note is determined by using the formula given
below:
whole note duration = 19.22/n seconds
The default value is 8, and note duration increases with n.

SOUND A N D MUSIC O N THE COMMODORE 128

EXAMPLES:
TEMPO 16 Defines the TEMPO at 16.
TEMPO 1 Defines the TEMPO at the slowest speed.
TEMPO 250 Defines the TEMPO at 250.

VOL
Define output level of sound
VOL volume level
This statement sets the volume for SOUND and PLAY statements. VOLUME
level can be set from 0 to 15, where 15 is the maximum volume, and 0 is off. V O L
affects all voices.
EXAMPLES:
VOL 0
VOL 15

Sets volume to its lowest level.

Sets volume for SOUND and PLAY statements to its highest output.

CODING A SONG
FROM SHEET MUSIC
This section provides a sample piece of sheet music and illustrates how to decode notes
from a musical staff and translate them into a form the Commodore 128 can understand.
This exercise is substantially faster and easier if you know how to read music. However,
you don't have to be a musician to be able to play the tune on your Commodore 128.
For those of you who cannot read music, Figure 11-1 shows how a typical musical staff
is arranged and how the notes on the staff are related to the keys on a piano.

IIIIIIINIIIIIII
Middle

C
Figure l l - l . Musical Staff

341

342

COMMODORE 128

Figure 11-2 is an excerpt from a composition titled Invention 13 (Inventio 13 in

Italian), by Johann Sebastian Bach. Although this composition was written a few
hundred years ago, it can be played and enjoyed on the most modern of computer
synthesizers, such as the SlD chip in the Commodore 128. Here are the opening
measures of Invention 13.

Inventio 13

?rr"

Figure 11-2. Part of Bach's Invention

13

The best way to start coding a song on your Commodore 128 is to break the notes
down into an intermediate code. Write down the upper staff notes on a piece of paper.
Now write down the notes for the lower staff. Precede the note values with a duration
code. For instance, precede an eighth note with an 8, precede a sixteenth note with a 16,
and so on. Next, separate the notes so the notes on the upper staff for one measure are
proportional in time with the notes for one measure on the lower staff.
If the musical composition had a third staff, you would separate it so the duration
would be proportional to the two other upper staffs. Once the notes for all the staffs are
separated into equal durations, a separate and dedicated voice plays each note for a
particular staff. For example, voice 1 plays the upper staff, voice 2 plays the second
staff and voice 3 plays the lowest staff.
Let's say the upper staff begins with a string of four eighth notes. In addition, say
the lower staff begins with a string of eight sixteenth notes. Since an eighth note is
proportional in time to two sixteenth notes, separate the notes as shown in Figure 11-3.

VI V2 =

8A
16D 16E

8B
16F 16G

8C
16A 16B

8D
16C 16D

Figure 11-3. Synchronizing Notes for T w o Voices

SOUND A N D MUSIC O N THE COMMODORE 128

The synchronization and timing in a musical composition are critical so you must
make sure the notes in the upper staff for voice 1, for example, are in time agreement
with the notes in the lower staff for voice 2. The first note in the upper staff in Figure
11-3 is an A eighth note. The first two notes for voice 2 are D and E sixteenth notes. In
this case, you must enter the voice 1 eighth note in the PLAY string first, then follow
the voice 2 sixteenth notes immediately after it. To continue the example, the second
note in Figure 11-3 for voice 1 (the upper staff) is a B eighth note. The B eighth note is
equal in time to the two sixteenth notes, F and G, which appear in the bottom staff for
voice 2. In order to coordinate the time, enter the B eighth note in the string for voice 1
and follow it with the two sixteenth notes, F and G, for voice 2.
As a rule, always start with the note with the longer duration. For example, if a
bar starts with a series of two sixteenth notes on the lower staff for voice 2 and the upper
staff starts with an eighth note for voice 1, enter the eighth note in the string first since it
must play for the duration while the two sixteenth notes are being fetched by the
Commodore 128. You must give the computer time to play the longer note first, and
then PLAY the notes of shorter duration, or else the composition will not be synchronized.
Here's the program that plays Invention 13. Spaces are omitted in the PLAY string
to conserve space. For readability in your programs, add space between elements in the
string. Enter it into your C128 and SAVE it for future use. Now RUN it and sit back
and enjoy the music!
10 REM INVENTION 13 BACH
2 0 TEMPO 6
30 PLAY"VlO4T7U8X0":REM VOICE l=ORGAN
40 PLAY"V2O4T0U8X0":REM VOICE 2=PIANO
50 REM FIRST MEASURE
6 0 A$ ="V201IAVl03lEV202QAVl03SA04C03BEV202I#GVl03SB04DVl04ICV202SAEM"
7 0 B$="Vl04IEV202SA03CVl03I#GV202SBEVl04IEV202SB03D"
80 REM SECOND MEASURE
9 0 C$= "V203lCVl03SAEV202lAVl03SA04CV202.I#GV103SBEV202IEVl03SB04D"
100 D$="Vl04lCV202SAEVl03lAV202 SA0 3CVl04QRV202 SBEB03D"
110 REM
REM THIRD MEASURE
120 E$="V203lCV104SREV202lAVl04SCEV203ICVl03SA04CV20 2lAVl0 2SEG"
130 F$="Vl03IFV203SD02AVl03lAV202SFAV]04lDV202SDFVl04IFV201SA02C"
140 REM FOURTH MEASURE
150 G$ = "V20lIBVl04SFDV202lDV103SBO4DV202IGVl0 3SGBV202IBVlO3SDF"
160 H$ = "Vl03lEV202SGEVl03lGV202SEGVl04ICV202SCEVl041EV201SGB"
170 REM FIFTH MEASURE
180 I$="V20lIAVl04SECV202ICVl03SA04CVl0 3IFV202SDFVl04IDV201SB02D"
190 J$="V20lIGVl03SDBV20lIBV103 SGBVl03lEV202 SCEVl04lCV201SA02C"
200 REM SIXTH MEASURE
210 K$ = "V20lIFV104SC03AV201IDVl03SFAVl03IDV20lSG02GVl03IBV202SFG"
22 0 M$="V201IAV104SC03AV202I#EVl04SCEV201IBVl04SD03BV202l#GVI04SDF"
230 REM SEVENTH MEASURE
2 40 N$="V202lCVl04SECV202lAV104SEGV202IDVl04SFEV202I$BVl04SDC"
2 50 0$="V202l#GVl03SB04CV202lFVl04SDEV202IDVl04SFDV201IBVl04S#GD"
260 REM EIGHTH MEASURE
27 0 P$="V202I#GVl04SBDV202IAVl04SCAV202lDV104SFDV202lEVl03SB04D"
28 0 Q$-"V202IFV103S#GBV202I#DY104SC03AV202lEVl03SEAV202lEV103SB#G"
290 REM NINTH MEASURE
300 R$="V201HAV103SAECE02QA"
310 PLAY A$:PLAY B$:PLAY C$:PLAY D$:PLAY E$
320 PLAY F$:PLAY G$:PLAY H$:PLAY I$:PLAY J$
330 PLAY K$:PLAY M$:PLAY N$:PLAY 0$:PLAY P$
340 PLAY Q$:PLAY R$

343

344

COMMODORE 128

Here are two sample sounds programs that you can try:
10 REM SOUND LOOPS
2 0 REM CHANGES STEP VALUE, DIRECTION AND WAVEFORM
3 0 SV=1000:REM STEP VALUE
4 0 DO
50 PRINT:PRINT "SV=";SV:PRINT
60 :
DIR=0 :REM SWEEP DIRECTION
70 :
DO
80 :
WF=0:REM WAVEFORM
90 :
DO
100 :
SOUND l,40000,120,DIR,2000,SV,WF
110 :
PRINT "WF=";WF;:WF=WF+1
120
130

:
:

PRINT

LOOP U N T I L W F = 4
"DIR=";DIR:DIR=DIR+1

140 :
LOOP UNTIL DIR = 3
150 SV=SV+2000
160 LOOP UNTIL SV > 20000
10
20
30
40
50
60
70
80

REM C128-MODE JOYSTICK MUSICIAN

REM
PLAYS NOTES C THROUGH A IN EACH OCTAVE
REM
TO INCREASE THE NOTE VALUE, PUSH JOYSTICK FORWARD
REM
TO DECREASE NOTE VALUE, PULL BACK
REM
TO INCREASE OCTAVE VALUE, PUSH JOYSTICK TO THE RIGHT
REM
TO DECREASE OCTAVE VALUE, PUSH JOYSTICK TO THE LEFT
A$(1)="C":A$(2)="D":A$(3)="E":A$(4)="F":A$(5)="G":A$(6)="A":A$(7)="B"
Z=4:REM INITIALIZE TO FOURTH OCTAVE

9 0 SCNCLR

:REM CLEAR

SCREEN

100 INPUT"ENTER VOICE 1 INSTRUMENT NUMBER (0-9)";N$

110 INPUT"ENTER VOICE 2 INSTRUMENT NUMBER (0-9)";0$
120 INPUT"ENTER VOICE 3 INSTRUMENT NUMBER (0-9)";P$
130 P R I N T : P R I N T : P R I N T : P R I N T : P R I N T : P R I N T "
140 P R I N T : P R I N T "
" " : P R I N T

INCREASE

NOTE"

150 PRINT"DECREASE OCTAVE <-- --> INCREASE OCTAVE"

160 P R I N T : P R I N T "
170 P R I N T : P R I N T "

V":PRINT
DECREASE N O T E " : P R I N T

180
190
200
210
220
230
240
25 0
260
27 0

PRINT: PRINT"TO INCREASE OR DECREASE NOTE OR OCTAVE";

PRINT: PRINT"WITHOUT PLAYING NOTES,HOLD DOWN THE ";
PRINT"FIRE BUTTON WHILE POSITIONING THE";
PRINT:PRINT"JOYSTICK IN THE APPROPRIATE DIRECTION";
Q$="Vl"+"T"+N$:REM VOICE 1 INSTRUMENT
R$="V2"+"T"+0$:REM VOICE 2 INSTRUMENT
S$="V3"+"T"+P$:REM VOICE 3 INSTRUMENT
DO
: DO
:
A=JOY(l):REM GET JOY VALUE

280
290
300

:
:
:

310
320
330
340
350

:
:
:
:
:

360
37 0
380

:
:
:

390
400
410
420
430
440
450
460

:
:
IF (A=1 OR A=129) AND (I<8) THEN I=I+l:REM INCREMENT NOTE VALUE
:
IF (A=5 OR A=133) AND (I>0) THEN I=I-1 :REM DECREMENT NOTE VALUE
:
IF (A= 3 OR A=131) AND (Z<6) THEN Z=Z+l:REM INCREMENT OCTAVE
:
IF (A=7 OR A=135) AND (Z>0) THEN Z=Z-l:REM DECREMENT OCTAVE
:
A=JOY(1):REM GET NEXT JOY VALUE
: LOOP WHILE A=B
LOOP:REM DO IT AGAIN

I F A = 0 THEN L O O P : R E M I F ZERO LOOP AND GET ANOTHER

B=A
:REM S T O R E THE VALUE FOR LATER C H E C K I N G
Z $ = " 0 " + S T R $ ( Z ) : R E M UPDATE OCTAVE

T$=Z$+Q$+A$(I):REM CONSTRUCT VOICE 1 PLAY STRING

U$=Z$+R$+A$(I):REM CONSTRUCT VOICE 2 PLAY STRING
V$=Z$+S$+A$(I):REM CONSTRUCT VOICE 3 PLAY STRING
I F (A AND 128)=128 THEN 400
PLAY T $ : R E M
PLAY U $ : R E M
PLAY V $ : R E M

PLAY V O I C E
PLAY V O I C E
PLAY V O I C E

1
2
3

SOUND A N D MUSIC O N THE COMMODORE 128

SOUND AND MUSIC

IN CI28 MODE
BACKGROUND:
THE CHARACTERISTICS OF SOUND
Every sound you hear is actually a sound wave traveling through the air. Like any wave,
a sound (sine) wave can be represented graphically and mathematically (see Figure 1 1 ^ ) .

Figure 11-4. Sine Wave

The sound wave moves (oscillates) at a particular rate (frequency) which determines the overall pitch (the highness or lowness of the sound).
The sound is also made up of harmonics, which are accompanying multiples of the
overall frequency o f t h e sound or note. The combination of these harmonic sound waves
give the note its qualities, called timbre. Figures 11-5 shows the relationship of basic
sound frequencies and harmonics.

Figure 11-5. Frequency and Harmonics

The timbre of a musical tone (i.e., the way a tone sounds) is determined by the
tone's waveform. The Commodore 128 can generate four types of waveforms: triangle,
sawtooth, variable pulse and noise. See Figure 11-6 for a graphic representation of these
four waveforms.

345

346

COMMODORE 128

^ PULSE WIDTH

Figure 11-6. Sound W a v e f o r m Types

SOUND A N D MUSIC O N THE COMMODORE 128

The volume of a sound changes throughout the duration of the note, from when
you first hear it until it is no longer audible. These volume qualities are referred to as
Attack, Decay, Sustain and Release (ADSR). Attack is the rate at which a musical note
reaches its peak volume. Decay is the rate at which a musical note decreases from its
peak volume to its midranged (sustain) level. Sustain is the level at which a musical note
is played at its midrange volume. Release is the rate at which a musical note decreases
from its sustain level to zero volume. The ENVELOPE generator controls the ADSR
parameters of sound. See Figure 11-7 for a graphical representation of ADSR. The
Commodore 128 can change each ADSR parameter to sixteen different levels. This
gives you absolute flexibility over the ENVELOPE generator and the resulting properties of the volume of the sound.

Figure 11-7. A D S R Phases

One of the most powerful Commodore 128 sound statementsthe one that
controls the ADSR and waveformis the ENVELOPE statement. The ENVELOPE
statement sets the different controls in the synthesizer which make each sound unique.
The ENVELOPE gives you the power to manipulate the SID synthesizer.

Here are the definitions of the parameters within the Envelope statement:
Envelope The properties of a musical note specified by the waveform and the attack,
decay, sustain and release settings of the note. For example, the envelope for a
guitar note has a different ADSR and waveform than that for a flute.
Waveform The type of sound wave created by the combination of accompanying
musical harmonics of a tone. The accompanying harmonic sound waves are
multiples of, and are based on the overall frequency of the tone. The qualities of
the tone generated by each waveform are recognizably different from one another
and are represented graphically in Figure 11-6.
Pulse Width The length of time between notes, generated by the pulse waveform.
The Commodore 128 has ten predefined envelopes for ten different musical
instruments. In using the predefined envelopes you do not have to specify the ADSR
parameters, waveform and pulse width settingsthis is already done for you. All you
have to do is specify the envelope number. The rest of the parameters are chosen

347

348

COMMODORE 128

automatically by the Commodore 128. Here are the preselected envelopes for different
types of musical instruments:

ENVELOPE
NUMBER

INSTRUMENT

ATTACK

DECAY

SUSTAIN

RELEASE

WAVEFORM

0
1
2
3
4
5
6
7
8
9

Piano
Accordion
Calliope
Drum
Flute
Guitar
Harpsichord
Organ
Trumpet
Xylophone

0
12
0
0
9
0
0
0
8
0

9
0
0
5
4
9
9
9
9
9

0
12
15
5
4
2
0
9
4
0

0
0
0
0
0
1
0
0
1
0

2
1
0
3
0
1
2
2
2
0

WIDTH

1536

512
2048
512

Figure 11-8. Default Parameters for ENVELOPE Statement

THE SID FILTER

Once you have selected the ENVELOPE, ADSR, VOLume and TEMPO, use the
FILTER to perfect your synthesized sounds. In your program, the FILTER statement
will precede the PLAY statement. First you should become comfortable with generating
the sound and worry about FILTERing last. Since the SID chip has only one filter, it
applies to all three voices. Your computerized tunes will play without FILTERing, but
to take full advantage of the music synthesizer, use the FILTER statement to increase
the sharpness and quality of the sound.
In the first paragraph of this section, The Characteristics ofSound, we defined a
sound as a wave traveling (oscillating) through the air at a particular rate. The rate at
which a sound wave oscillates is called the wave's frequency. Recall that a sound wave
is made up of an overall frequency and accompanying harmonics, which are multiples of
the overall frequency. See Figure 11-5. The accompanying harmonics give the sound its
timbre, the qualities of the sound which are determined by the waveform. The filter
within the SID chip gives you the ability to accent and eliminate the harmonics of a
waveform and change its timbre.
The SID chip filters sounds in three ways: low-pass, band-pass and high-pass
filtering. These filtering methods are additive, meaning you can use more than one filter
at a time. Low-pass filters out frequencies above a certain level you specify, called the
cutoff frequency. The cutoff frequency is the dividing line that marks the boundary of
which frequency level will be played and which will not. In low-pass filtering, the SID
chip plays all frequencies below the cutoff frequency and filters out the frequencies
above it. As the name implies, the low frequencies are allowed to pass through the
filter and the high ones are not. The low-pass filter produces full, solid sounds.
See Figure 11-9.

SOUND A N D MUSIC O N THE COMMODORE 128

I
FREQUENCY

Figure 11-9. Low-pass Filter

Conversely, the high-pass filter allows all the frequencies above the cutoff frequency to pass through the chip. All the ones below it are filtered out. See Figure 11-10.
The high-pass filter produces tinny, hollow sounds.

FREQUENCY

Figure 11-10. High-pass Filter

The band-pass filter allows a range of frequencies partially above and below the
cutoff frequency to pass through the SID chip. All other frequencies above and below
the band surrounding the cutoff frequency are filtered out. See Figure 11-11.

349

350

COMMODORE 128

Figure 11-11. Band-pass Filter

ADVANCED FILTERING
Each of the previous FILTERing examples used only one type of filtering at a time. You
can combine the SID chip's three methods of filtering with each other to achieve
different filtering effects. For example, you can enable the low-pass and high-pass filters
at the same time to form a notch reject filter. A notch reject filter allows the frequencies
below and above the cutoff to pass through the SID chip, while the frequencies close to
the cutoff frequency are filtered out. See Figure 11-12 for a graphic representation of a
notch reject filter.

CUTOFF
FREQUENCY

Figure 11-12. Notch Reject Filter

You can also add either the low-pass or high-pass filter to the band-pass filter to
obtain interesting effects. By mixing the band-pass filter with the low-pass filter, you
can select the band of frequencies beneath the cutoff frequency and below. The rest are
filtered out.
By mixing the band-pass and the high-pass filters, you can select the band of
frequencies above the cutoff frequency and higher. All the frequencies below the cutoff
are filtered out.

SOUND A N D MUSIC O N THE COMMODORE 128

Experiment with the different combinations of filters to see all the different types
of accents you can place on your musical notes and sound effects. The filters are
designed to perfect the sounds created by the other components of the SID chip. Once
you have created the musical notes or sound effects with the SID chip, go back and add
the FILTERing to your programs to make them as crisp and clean as possible.
Now you have all the information you need to write your own musical programs in
Commodore 128 BASIC. Experiment with the different waveforms, ADSR settings,
TEMPOs and FILTERing. Look in a book of sheet music and enter the notes from a
musical scale in sequence within a play string. Accent the notes in the string with the
SID control characters. You can combine your Commodore 128 music synthesizer with
C128 mode graphics to make your own videos or " m o v i e s " complete with sound
tracks.

AUDIO INPUT TO THE SID CHIP

The SID chip has a little known additional feature that most computers do not offer:
audio input. This allows you to channel your own music, such as an electric guitar, your
voice through a microphone or any other (high impedence, line level) instrumentyou
can actually " j a m " with the C128.
In order to connect properly to the computer, you must devise your own cable or
buy one with the correct connections. Get a cable with an 8-pin DIN connector on the
end you are plugging into the C128. Connect pins 2 (ground), 3 (audio out), and 5 (audio
in) on the 8-pin end.
Here's the pinout:
Video ConnectorThis DIN connector supplies direct audio and composite video
signals. These can be connected to the Commodore monitor or used with separate
components. This is the 40-column output connector.

351

352

COMMODORE 128

PIN

1
2
3
4
5
6
7
8

TYPE

NOTE

LUM/SYNC
GND
AUDIO OUT
VIDEO OUT
AUDIO IN
COLOR OUT
NC
NC

Luminance/SYNC output

Composite signal output

Chroma signal output
No connection
No connection

Run the three connecting wires inside the cable to attach to the audio in, audio out
and ground on the end of your component.
You can connect the C128 to your stereo system or VCR and channel sound
through your speakers. Be careful, however, not to exceed the standard electrical
restrictions. See the SID chip specs in Chapter 16 under the description EXT IN
(Pin 26).
Using the C128 in these ways opens your eyes to how flexible a personal computer
can be and how it can communicate with a wide range of devices in your home,
including your telephone (with an additional modem), VCR, stereo, TVand don't
forget the electric guitar!

PROGRAMMING THE SID CHIP

IN MACHINE LANGUAGE
This section provides an algorithm and the coded program procedure to play music on
the C128.
First you need to know the key SID locations in the C128 memory map. Here's an
abbreviated SID memory map, which is exactly the same in both C128 and C64 modes.
Register 0 is located at address 54272 ($D400).

SOUND A N D MUSIC O N THE COMMODORE 128

>

>

>

>

>- >

>

>

>

>

>- >

>

>

>

2
o

2
o

2
o

2
o

z
o

z
o

2
p

2
o

2
o

2
o

2
o

2
p

z
o

2
o

2
p

E
5

E
5

LU UJ LU LU LU LU UJ
E E E s E E

UJ LU LU UJ UJ LU UJ
5

*- a> o
a> O O
O UJ UJ
o
UJ .HoujocS
LL Q. 5Q.oO . < _CO o tr tr

u_

LL~

^i

."
uT

uT

uf

1^n1 oQ

6^ -

- I

*i :

i^^

<

*i

- 1

uT

3
|C
Si Q3^
Q- | O

o o o o o

<g
O

*- T-

>
^ <

?
co

o *- cv< co *j tn to

tr

cr cc tr

<

co

cr 5

a.

Q-

rt

^ uT rL1 |a,l Xo
5o
o ^cr

a>
Z

,r
- iLfc ^
o <C
$C
"- uQ. 3
-hQ

Q
-^g

L<

^ uT i|

5)

d
?
s < co

1 i ^ z

\^ < co
3
b0

1
f ic ^ 2
~$M
Q < C0 ^ L^ 5 _ < to

^ g
* f i

w ^

z5

O ^

^ 1i 2
< ^ z
^ifl:
rc < CO
CT> < CD O

^
00 OJ < 03 o O
O O O O o o o

T-

J o o o o o o o
o o o o o o o

>j >
z 2
o p
LL) W
Ec E

o o

- .= i 7 s\ 7< 7co

co

E
5

2
p
K
E

S Qf 5cr3
I a^ (

co o

2 <

>

^ o> rt >" CO
o> O ^" ^
OJ
I C
>OQ- ^ - - 5 M ^
0 o
CC
-

co

_ < CO

I 22 *
1

o o o o

- -' i

_
*1 21
J t~ t-

>

2
p
LU
E
5

^ t5 8 !

O Q cc

co

uj

o QC CL a.

til<

s*
cr

l^e 8 ^

u.

o >* co1

u. u.*

2
i

: l i

u.

^
a

C
M 2 og > o ?

>

> >j
2 2 2
p o p
LU UJ LU

>

aO> LUO

tr

:^CT)<i >C0
"

LL

- co D

>

2 2
p p
LU LU UJ w
E E E E
5 5

u
0 UJ o o
O
> p
CO
oo >
; oo -L^
O CO o? >
t o>^co u.o LL
> <
L2 5

U O o
s-c >- C^0
-

>

2
p

o o o o o o

o o o o -

- ^- - o

o o o o

o o o -

o o o

353

354

COMMODORE 128

Here's the general algorithm to output sound from the SID chip in voice 1.
1.
2.
3.
4.
5.
6.

Clear the sound chip (For $D400-$D41C)

Select ATTACK and DECAY for each voice ($D405)vl
Select SUSTAIN and release for each voice ($D406) v l
Select a waveform ($D404 for v l )
Set the volume ($D418)
Set the frequency of the note with a low byte ($D400) and high byte
($D401) from the Musical Note Table in Figure 11-15 at the end of this chapter.

If you want to output a certain frequency level, use this equation:

F n = F out/.06097
Round off the (F n ) frequency with the integer function and divide the result into the
low byte and high byte.
In decimal:
Fni = F n /256 is the high byte
and:
Fiow = F n - ( 2 5 6 * F hi ) is the low byte
To get a feel for the ranges of notes, experiment with the SOUND command in
BASIC.
7.
8.
9.

10.
11.

Place the high byte in Frequency Control Register (in $D401) for the
appropriate voice.
Place the low byte in the (low byte) frequency control register for the
appropriate voice ($D400).
Initiate (GATE) the note or tone. Gating means to start the ATTACK,
DECAY and SUSTAIN cycle of the tone. Set bit 0 of $D404 (VI), $D40B(V2)
and $D412(V3), respectively.
Leave bit 0 set for the duration you wish to play the note or tone.
Clear the GATE bit.

The durations of the standard musical notes are as follows:

NOTE TYPE

DOTTED
'/4 +
DOTTED
y2 +
'/2 +
DOTTED
WHOLE

DURATION

'/l6
y*
'/8
'/4
Vl6
%
y2
'/l6
y*
Vi

128
256
384
512
640
768
1024
1152
1280
1536
2048

SOUND A N D MUSIC O N T H E COMMODORE 128

To synchronize three voices, divide each measure into sixteen equal parts. Play
(Gate) the notes with longer duration first, then gate the values of smaller duration, but
of equal proportion, next. For example, one staff has an eighth note. The staff below it
has two sixteenth notes. Play the note of longer duration so they can be gated while the
other faster notes are being fetched.
The following machine language program plays musical notes in one voice. The
musical note data begins at location $1890. The data for each note is stored in the four
byte format starting at $1890 as follows:
Frequency (low byte/high byte)
Duration (low byte/high byte)
For example, the data for the second note starts at location $1894, data for the
third note begins at location $1898 and so on.
For now, sample data has been supplied. Eventually, place your own data beginning
at location $1890. See Figure 11-15 at the end of this chapter for the low- and high-byte
frequency values to place in the SID frequency control registers. Refer to the duration
table on page 354 for the byte values for the note duration.
The NOP instructions are added between instruction sequences for readability.
Here's the program listing as it appears in the Machine Language Monitor:
READY.
MONITOR
PC SR AC XR 1YR SP
; FB000 00 00 00 00 F8
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

01800
01802
01803
01806
01807
01809
0180B
0180C
0180D
0180E
01810
01812
01815
01816
01817
01818
0181A
0181C
0181F
01820
01821
01822
01823
01825
01827
0182A
0182B
0182C
0182D
0182F
01831

A2
8A
9D
E8
E0
D0
EA
EA
EA
A2
A9
9D
EA
EA
EA
A2
A9
9D
EA
EA
EA
EA
A2
A9
9D
EA
EA
EA
A0
A2
B9

00
00 D4
19
F8

05
F5
00 D4

06
A3
00 D4

18
0F
00 D4

00
00
90 18

LDX
TXA
STA
INX
CPX
BNE
NOP
NOP
NOP
LDX
LDA
STA
NOP
NOP
NOP
LDX
LDA
STA
NOP
NOP
NOP
NOP
LDX
LDA
STA
NOP
NOP
NOP
LDY
LDX
LDA

#$00
$D400,X
#$1 9
$1803

#$05
#$F5
$D400,X

# $ 06
#$A3
$D4 00,X

#$18
#$0F
$D400,X

#$00
#$00
$1890 ,Y

355

356

COMMODORE 128

01834
01836
01839
0183A
0183B
0183E
01841
01842
01843
01844
01845
01848
0184A
0184B
0184E
01850
01852
01854
01857
01858
01859
0185A
0185B
0185D
0185F
01861
01863
01864
01866
01868
0186B
0186C
0186D
0186E
0186F
01872
01873
01874
01875
01877
01879
0187C

>01890
>01898
>018A0
>018A8
>018B0
>018B8
>018C0
>018C8
>018D0
>018D8
>018E0
>018E8

F0
9D
E8
C8
B9
9D
EA
EA
EA
C8
B9
85
C8
B9
85
A2
A9
9D
EA
EA
EA
EA
C6
DO
C6
DO
EA
A2
A9
9D
EA
EA
EA
C8
4C
EA
EA
EA
A2
A9
9D
00

lE
lE
lE
lE
lE
lE
lE
lE
lE
21
0D
8D

3F
BEQ $1875
00 D4 STA $D4 00 ,X
INX
INY
90 18 LDA $1890 , Y
00 D4 STA $D4 00,r X
NOP
NOP
NOP
INY
90 18 LDA $1890,r Y
FA
STA $FA
INY
90 18 LDA $ 1890 rjY
FB
STA $ F B
04
LDX # $ 04
21
LDA # $ 21
00 D4 STA $D400,J
NOP
NOP
NOP
NOP
FA
DEC $FA
BNE $185B
FC
FB
DEC $FB
BNE $185B
F8
NOP
04
LDX # $ 04
20
LDA # $ 2 0
00 D4 STA $D400,,X
NOP
NOP
NOP
INY
2F 18 JMP $182F
NOP
NOP
NOP
18
LDX # $ 1 8
00
LDA #$00
00 D4 STA $D4 00,, x
BRK

19
19
19
19
19
19
19
19
19
21
54
6C

80
80
80
80
80
80
80
80
80
00
08
08

00
00
00
00
00
01
04
04
00
00
DO
AD

lC
lC
lC
lC
lE
lE

lC
lC
lC
00
D7
7C

41
41
41
41
19
19
19
41
41
00
AD
08

80
80
00
80
80
80
80
80
00
00
7B
8D

00
00
00
00
00
01
04
00
00
00
08
6D

Enter the program in memory with the Machine Language Monitor and save it.
Run the program with the following command:
G F1800

SOUND A N D MUSIC O N THE COMMODORE 128

The program plays a series of notes in a single voice (voice 1). Here's a line by
line description of the instructions in the program.
The instructions stored in locations $1800 through $180A clear the SlD registers
($D400-$D418) to zero. This is a recommended programming practice, so you can
assume that all the SID registers are initialized to zero.
The instructions stored in locations $180E through $1814 assign the attack/decay
values in the SID envelope generator. In this program, attack is set at (15:$0F) and the
decay is set at 5. This attack setting makes the sounds seem as if they are far away and
traveling closer, similar to the way a train sounds as it approaches from far away.
The instructions stored in locations $1818 through $181E select the sustain/release
values for the voice 1 envelope generator. In this case the sustain duration is set on 10
($0A) and the release rate is set to 3. For more information on the ADSR settings, see
the beginning of the chapter.
The next sequence of instructions ($ 1823$ 1829) sets the volume to maximum
output (15:$0F). Notice that the last three instruction sequences loaded the X register
with the register number, loaded the accumulator with the appropriate value and stored
the value in the location of the start of the SID plus an offset in the X register. This
programming style is easy to follow and is standardized throughout the program.
The instructions stored in locations $182D through $183E get the low- and
high-byte frequency values for the musical note data, and place them into the low- and
high-byte frequency control registers for voice 1. First the X and Y registers are cleared
to zero. The Y register is used as an index to the musical note data in memory starting at
location $1890. To access successive bytes for frequency and duration, the Y index
register is incremented. The X register is used as an index to access the low- and
high-byte frequency control registers at locations $D400 and $D401. In this program
segment, the X register can only have one of two values; 0 to access location $D400 and
1 to access location $D401.
The first time through the loop, the instruction starting at location $1831 (LDA
$1890,Y) loads the musical data value (low byte frequency) into the accumulator. The
next instruction (BEQ $1875) checks to see if this value is equal to zero. If it is, control
passes to location $1875, the volume is cleared to zero, and the program ends. This
suggests that to end the program, place a zero in the low byte data element. This
mechanism acts as a data terminator, since no additional data is read if the low-byte
value of a musical note equals zero. If the data value does not equal zero, it is stored in
the low byte frequency control register for voice 1.
Both the X and Y registers are incremented, and the next musical data value, this
time at $1891, is loaded into the accumulator with the instruction beginning at location
$183B. The next instruction (STA $D400,X) stores the data value in the high-byte
frequency control register ($D401) for voice 1.
The instruction at location $1844 increments the Y register. The next load
instruction starting at location $1845 loads the accumulator with the next data element in
memory, this time the low byte for the duration of the note. The duration note table is
found on page 252. The low-byte duration is stored in zero page location $FA. The Y

357

358

COMMODORE 128

register is incremented again and the high byte duration is loaded into the accumulator
and stored in zero page location $FB. These two locations are decremented in the
instructions stored in location $185B through $1862.
The instructions stored in locations $1850 through $1857 GATE the note, in other
words play the note. To output audible notes, each voice has a gate bit which initiates the
sound from the envelope generator for a particular voice. Bit 0 of location $D404 is the
gate bit for voice 1. To gate a bit, set bit 0 and also set the bit for the desired waveform at the same time. In this case, the sawtooth waveform is gated on ( 3 2 + 1 = $21).
At this point, the sawtooth waveform is gated on and is playing in the voice 1
envelope generator. The selected frequency is output until you turn off the gate bit.
Here's where the duration of the note comes into play. The instructions stored in
locations $185B through $1862 decrement the low and high byte duration value stored
in zero page locations $FA and $FB respectively. These instructions act as a time delay
which count through the loops using the duration values from page 354 that are stored in
the musical data region starting at $1890 in memory. When both $FA and $FB are equal
to zero, program control drops through to the instructions stored at $1864 through
$186A. These instructions clear the voice 1 gate bit and stop the envelope generator
from outputting sound.
At this point, the Y register is incremented ($186E) and the program jumps to
$182F where the X register is cleared to zero. Since the Y register was already
incremented before the JMP instruction in location $186F-71, the low byte frequency
value for the second note is already pointed to by the Y register plus the base address of
$1890. The program then loads that low-byte value and stores it in the location $D400
plus the offset of the X register, in this case 0. That gives the appropriate address $D400
for the voice 1 (low byte) frequency control register. These instructions are executed
repetitively until a low-byte frequency of zero is encountered. When the low-byte
frequency equals zero, control is passed to location $1875, the volume is cleared to
zero, and the program breaks.
This program plays 19 notes, and on the 20th a zero is detected as the low-byte
frequency value (in location $18DC), so volume is set to zero and the program ends.
This data is entered as an example. Place your data there instead according to the note
table in Figure 11-15 at the end of the chapter and the duration table on page 354.
Expand on this example. Add multiple voices using different waveforms. Utilize
the filter to perfect the quality of the musical notes. Use this program as a basis for your
own full-featured musical program.

SYNCHRONIZATION AND
RING MODULATION
The 6581 SID chip lets you create more complex harmonic structures through synchronization or ring modulation of two voices.
The process of synchronization is basically a logical ANDing of two wave forms.
When either is zero, the output is zero.
Here's a synchronization algorithm:

SOUND A N D MUSIC O N THE COMMODORE 128

1
2
3
4
5
6
7
8
9

Clear sound chip registers.

Set high frequency voice 1.
Set Attack/Decay for voice 1 (A = 13, D = 11).
Set high frequency voice 3.
Set volume 15.
Set start triangle, sync waveform control for voice 1.
Timing loop.
Clear triangle, sync waveform control for voice 1.
Wait, then turn off volume.

The synchronization feature is enabled (turned on) in step 6, where bits 0, 1, and 4
of register $D404 are set. Bit 1 enables the syncing function between voice 1 and voice
3. Bits 0 and 4 have their usual functions of gating voice 1 and setting the triangular
waveform.
Ring modulation (accomplished for voice 1 by setting bit 2 of register $D404 in
step 6 of the algorithm) replaces the triangular output of oscillator 1 with a "ring
modulated" combination of oscillators 1 and 3. This produces non-harmonic overtone
structures for use in mimicking bell or gong sounds.

SID REGISTER DESCRIPTION

Following is a register-by-register description of the SID chip in numerical order.

VOICE I
FREQ LO/FREQ HI (Registers 00,01)
Together these registers form a 16-bit number which linearly controls the frequency of
Oscillator 1. The frequency is determined by the following equation:
Fout -

(F x F c l k /16777216) Hz

Where F n is the 16-bit number in the Frequency registers and F clk is the system clock
applied to the 02 input (pin 6). For a standard 1.0-MHz clock, the frequency is given
by:
F o u t

( F n

X 0.06097) Hz

A complete table of values for generating eight octaves of the equally tempered
musical scale with concert A (440 Hz) tuning is provided in Figure 11-15. It should be
noted that the frequency resolution of SID is sufficient for any tuning scale and allows
sweeping from note to note (portamento) with no discernable frequency steps.

PW LO/PW HI (Registers 02,03)

Together these registers form a 12-bit number (bits 4 - 7 of PW HI are not used) which
linearly controls the Pulse Width (duty cycle) of the Pulse waveform on Oscillator 1.
The pulse width is determined by the following equation:

359

360

COMMODORE 128

PW o u t = (PWn/40.95) %
Where PW n is the 12-bit number in the Pulse Width registers.
The pulse width resolution allows the width to be smoothly swept with no discernable stepping. Note that the Pulse waveform on Oscillator 1 must be selected in order
for the Pulse Width registers to have any audible effect. A value of 0 or 4095 ($FFF) in
the Pulse Width registers will produce a constant DC output, while a value of 2048
($800) will produce a square wave.

CONTROL REGISTER (Register 04)

This register contains eight control bits which select various options on Oscillator 1.
G A T E (Bit 0): The GATE bit controls the Envelope Generator for Voice 1. When this
bit is set to a one, the Envelope Generator is Gated (triggered) and the ATTACK/
DECAY/SUSTAIN cycle is initiated. When the bit is reset to a zero, the RELEASE cycle begins. The Envelope Generator controls the amplitude of Oscillator
1 appearing at the audio output, therefore, the GATE bit must be set (along with
suitable envelope parameters) for the selected output of Oscillator 1 to be audible.
A detailed discussion of the Envelope Generator can be found in this book in the
chapter on Hardware Overview.
S Y N C (Bit I): The SYNC bit, when set to a one, synchronizes the fundamental
frequency of Oscillator 1 with the fundamental frequency of Oscillator 3, producing " H a r d S y n c " effects.
Varying the frequency of Oscillator 1 with respect to Oscillator 3 produces a
wide range of complex harmonic structures from Voice 1 at the frequency of
Oscillator 3. ln order for sync to occur, Oscillator 3 must be set to some
frequency other than zero but preferably lower than the frequency of Oscillator 1.
No other parameters of Voice 3 have any effect on sync.
R I N G M O D (Bit 2): The RING MOD bit, when set to a one, replaces the Triangle
waveform output of Oscillator 1 with a "Ring Modulated" combination of
Oscillators 1 and 3. Varying the frequency of Oscillator 1 with respect to
Oscillator 3 produces a wide range of non-harmonic overtone structures for
creating bell or gong sounds and for special effects. In order for ring modulation
to be audible, the Triangle waveform of Oscillator 1 must be selected and
Oscillator 3 must be set to some frequency other than zero. No other parameters of
Voice 3 have any effect on ring modulation.
T E S T (Bit 3): The TEST bit, when set to a one, resets and locks Oscillator 1 at zero until
the TEST bit is cleared. The Noise waveform output of Oscillator 1 is also reset and
the Pulse waveform output is held at a DC level. Normally this bit is used for testing
purposes, however, it can be used to synchronize Oscillator 1 to external events, allowing the generation of highly complex waveforms under real-time software control.
(Bit 4): When set to a one, the Triangle waveform output of Oscillator 1 is selected.
The Triangle waveform is low in harmonics and has a mellow, flute-like quality.
(Bit 5): When set to a one, the Sawtooth waveform output of Oscillator 1 is selected.
The Sawtooth waveform is rich in even and odd harmonics and has a bright,
brassy quality.

SOUND A N D MUSIC O N THE COMMODORE 128

(Bit 6): When set to a one, the Pulse waveform output of Oscillator 1 is selected. The
harmonic content of this waveform can be adjusted by the Pulse Width registers,
producing tone qualities ranging from a bright, hollow square wave to a nasal,
reedy pulse. Sweeping the pulse width in real-time produces a dynamic "phasing" effect which adds a sense of motion to the sound. Rapidly jumping between
different pulse widths can produce interesting harmonic sequences.
NOISE (Bit 7): When set to a one, the Noise output waveform of Oscillator 1 is
selected. This output is a random signal which changes at the frequency of
Oscillator 1. The sound quality can be varied from a low rumbling to hissing
white noise via the Oscillator 1 Frequency registers. Noise is useful in creating
explosions, gunshots, jet engines, wind, surf and other unpitched sounds, as well
as snare drums and cymbals. Sweeping the oscillator frequency with Noise
selected produces a dramatic rushing effect.
One of the output waveforms must be selected for Oscillator 1 to be audible,
however, it is NOT necessary to de-select waveforms to silence the output of
Voice 1. The amplitude of Voice 1 at the final output is a function of the Envelope
Generator only.
NOTE: The oscillator output waveforms are NOT additive. If more than
one output waveform is selected simultaneously, the result will be a
logical ANDing of the waveforms. Although this technique can be used
to generate additional waveforms beyond the four listed above, it must be
used with care. If any other waveform is selected while Noise is on, the
Noise output can "lock u p . " If this occurs, the Noise output will remain
silent until reset by the TEST bit or by bringing RES (pin 5) low.

ATTACK/DECAY (Register 05)

Bits 4-7 of this register (ATK0-ATK3) select 1 of 16 ATTACK rates for the Voice 1
Envelope Generator. The ATTACK rate determines how rapidly the output of Voice 1
rises from zero to peak amplitude when the Envelope Generator is gated. The 16
ATTACK rates are listed in Figure 11-14.
Bits 0 - 3 (DCY0-DCY3) select 1 of 16 DECAY rates for the Envelope Generator.
The DECAY cycle follows the ATTACK cycle and the DECAY rate determines how
rapidly the output falls from the peak amplitude to the selected SUSTAIN level. The 16
DECAY rates are listed in Figure 11-14.

SUSTAIN/RELEASE (Register 06)

Bits 4-7 of this register (STN0-STN3) select 1 of 16 SUSTAIN levels for the Envelope
Generator. The SUSTAIN cycle follows the DECAY cycle and the output of Voice 1
will remain at the selected SUSTAIN amplitude as long as the gate bit remains set. The
SUSTAIN levels range from zero to peak amplitude in sixteen linear steps, with a
SUSTAIN value of 0 selecting zero amplitude and a SUSTAIN value of 15 ($F)
selecting the peak amplitude. A SUSTAIN value of 8 would cause Voice 1 to SUSTAIN
at an amplitude one-half the peak amplitude reached by the ATTACK cycle.

361

362

COMMODORE 128

Bits 0 - 3 (RLS0-RLS3) select 1 of 16 RELEASE rates for the Envelope Generator. The RELEASE cycle follows the SUSTAIN cycle when the Gate bit is reset to zero.
At this time, the output of Voice 1 will fall from the SUSTAIN amplitude to zero
amplitude at the selected RELEASE rate. The 16 RELEASE rates are identical to the
DECAY rates as listed in Figure 11-14.
NOTE: The cycling of the Envelope Generator can be altered at any
point via the Gate bit. The Envelope Generator can be gated and released without restriction. For example, if the gate bit is reset before the
envelope has finished the ATTACK cycle, the RELEASE cycle will
immediately begin, starting from whatever amplitude had been reached.
If the envelope is then gated again (before the RELEASE cycle has
reached zero amplitude), another ATTACK cycle will begin, starting
from whatever amplitude had been reached. This technique can be used
to generate complex amplitude envelopes via real-time software control.

V A L U E
DEC (HEX)

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

(0)
(1)
(2)
(3)
(4)
(5)
(6)
(7)
(8)
(9)
(A)
(B)
(C)
(D)
(E)
(F)

A T T AC K

R AT E

(TIME/CYCLE)

2 ms
8 ms
16 ms
24 ms
38 ms
56 ms
68 ms
80 ms
100 ms
250 ms
500 ms
800 ms
1s
3s
5s
8s

DECAY/RELEASE

RATE

TIME/CYCLE)

6 ms
24 ms
48 ms
72 ms
114 ms
168 ms
204 ms
240 ms
300 ms
750 ms
1.5 s
2.4 s
3s
9s
15 s
24 s

NOTE: Envelope rates are based on a 1.0-MHz 02 clock. For other 02

frequencies, multiply the given rate by 1 MHz/02. The rates refer to the
amount of time per cycle. For example, given an ATTACK value of 2,
the ATTACK cycle would take 16 ms to rise from zero to peak amplitude. The DECAY/RELEASE rates refer to the amount of time these
cycles would take to fall from peak amplitude to zero.

Figure 11-14. Envelope Rates

SOUND A N D MUSIC O N THE COMMODORE 128

VOICE 2
Registers $07-$0D control Voice 2 and are functionally identical to registers $00-$06
with these exceptions:
1.
2.

When selected, SYNC synchronizes Oscillator 2 with Oscillator 1.

When selected, RING MOD replaces the Triangle output of Oscillator 2 with
the ring modulated combination of Oscillators 2 and 1.

VOICE 3
Registers $0E-$14 control Voice 3 and are functionally identical to registers $00-$06
with these exceptions:
1.
2.

When selected, SYNC synchronizes Oscillator 3 with Oscillator 2.

When selected, RING MOD replaces the Triangle output of Oscillator 3 with
the ring modulated combination of Oscillators 3 and 2.

Typical operation of a voice consists of selecting the desired parameters: frequency, waveform, effects (SYNC, RING MOD) and envelope rates, then gating the
voice whenever the sound is desired. The sound can be sustained for any length of time
and terminated by clearing the gate bit. Each voice can be used separately, with
independent parameters and gating, or in unison to create a single, powerful voice.
When used in unison, a slight detuning of each oscillator or tuning to musical intervals
creates a rich, animated sound.

FILTER
FC LO/FC HI (REGISTERS $I5,$I6)
Together these registers form an 11-bit number (bits 3-7 of FC LO are not used) which
literally controls the Cutoff (or Center) Frequency of the programmable Filter. The
approximate Cutoff Frequency ranges from 30 Hz to 12 KHz.

RES/FILT (REGISTER $17)

Bits 4-7 of this register (RES0-RES3) control the resonance of the filter. Resonance is a
peaking effect which emphasizes frequency components at the Cutoff Frequency of the
Filter, causing a sharper sound. There are sixteen resonance settings ranging linearly
from no resonance (0) to maximum resonance (15 or $F). Bits 0 - 3 determine which
signals will be routed through the Filter:
FILT I (Bit 0): When set to a zero, Voice 1 appears directly at the audio output and the
Filter has no effect on it. When set to a one, Voice 1 will be processed through
the Filter and the harmonic content of Voice 1 will be altered according to the
selected Filter parameters.

363

364

COMMODORE 128

FILT 2 (Bit I): Same as bit 0 for Voice 2.

F I L T 3 (Bit 2): Same as bit 0 for Voice 3.
F I L T E X (Bit 3): Same as bit 0 for External audio input (pin 26).

MODE/VOL (REGISTER $18)

Bits 4-7 of this register select various Filter mode and output options:
LP (Bit 4): When set to a one, the Low-Pass output of the Filter is selected and sent to
the audio output. For a given Filter input signal, all frequency components below
the Filter Cutoff Frequency are passed unaltered, while all frequency components
above the Cutoff are attenuated at a rate of 12 dB/Octave. The Low-Pass mode
produces full-bodied sounds.
BP (Bit 5): Same as bit 4 for the Bandpass output. All frequency components above
and below the Cutoff are attenuated at a rate of 6 dB/Octave. The Bandpass mode
produces thin, open sounds.
H P (Bit 6): Same as bit 4 for the High-Pass output. All frequency components above
the Cutoff are passed unaltered, while all frequency components below the Cutoff
are attenuated at a rate of 12 dB/Octave. The High-Pass mode produces tinny,
buzzy sounds.
3 OFF (Bit 7): When set to a one, the output of Voice 3 is disconnected from the direct
audio path. Setting Voice 3 to bypass the Filter (FILT 3 = 0) and setting 3 OFF
to a one prevents Voice 3 from reaching the audio output. This allows Voice 3 to
be used for modulation purposes without any undesirable output.
NOTE: The Filter output modes ARE additive and multiple Filter modes
may be selected simultaneously. For example, both LP and HP modes
can be selected to produce a Notch (or Band Reject) Filter response. In
order for the Filter to have any audible effect, at least one Filter output
must be selected and at least one Voice must be routed through the Filter.
The Filter is, perhaps, the most important element in SID as it allows the
generation of complex tone colors via subtractive synthesis (the Filter is
used to eliminate specific frequency components from a harmonically rich
input signal). The best results are achieved by varying the Cutoff Frequency in real-time.

Bits 0 - 3 (VOLO-VOL3) select 1 of 16 overall Volume levels for the final composite
audio output. The output volume levels range from no output (0) to maximum
volume (15 or $F) in sixteen linear steps. This control can be used as a static
volume control for balancing levels in multi-chip systems or for creating dynamic
volume effects, such as Tremolo. Some Volume level other than zero must be
selected in order for SID to produce any sound.

SOUND A N D MUSIC O N THE COMMODORE 128

MISCELLANEOUS
POTX (REGISTER $19)
This register allows the microprocessor to read the position of the potentiometer tied to
POTX (pin 24), with values ranging from 0 at minimum resistance, to 255 ($FF) at
maximum resistance. The value is always valid and is updated every 512 02 clock
cycles. See the Pin Description section for information on pot and capacitor values.

POTY (REGISTER $IA)

Same as POTX for the pot tied to POTY (pin 23).

OSC 3/RANDOM (REGISTER $IB)

This register allows the microprocessor to read the upper 8 output bits of Oscillator 3.
The character of the numbers generated is directly related to the waveform selected. If
the Sawtooth waveform of Oscillator 3 is selected, this register will present a series of
numbers incrementing from 0 to 255 ($FF) at a rate determined by the frequency of
Oscillator 3. If the Triangle waveform is selected, the output will increment from 0 up
to 255, then decrement down to 0. If the Pulse waveform is selected, the output will
jump between 0 and 255. Selecting the Noise waveform will produce a series of random
numbers, therefore, this register can be used as a random number generator for games.
There are numerous timing and sequencing applications for the OSC 3 register; however, the chief function is probably that of a modulation generator. The numbers
generated by this register can be added, via software, to the Oscillator or Filter
Frequency registers or the Pulse Width registers in real-time. Many dynamic effects can
be generated in this manner. Siren-like sounds can be created by adding the OSC 3
Sawtooth output to the frequency control of another oscillator. Synthesizer "Sample
and Hold" effects can be produced by adding the OSC 3 Noise output to the Filter
Frequency control registers. Vibrato can be produced by setting Oscillator 3 to a
frequency around 7 Hz and adding the OSC 3 Triangle output (with proper scaling) to
the Frequency control of another oscillator. An unlimited range of effects are available
by altering the frequency of Oscillator 3 and scaling the OSC 3 output. Normally, when
Oscillator 3 is used for modulation, the audio output of Voice 3 should be eliminated (3
OFF - 1).

ENV 3 (Register $IC)

Same as OSC 3, but this register allows the microprocessor to read the output of the
Voice 3 Envelope Generator. This output can be added to the Filter Frequency to
produce harmonic envelopes, WAH-WAH, and similar effects. "Phaser" sounds can be
created by adding this output to the frequency control registers of an oscillator. The
Voice 3 Envelope Generator must be Gated in order to produce any output from this
register. The OSC 3 register, however, always reflects the changing output of the
oscillator and is not affected in any way by the Envelope Generator.

365

366

COMMODORE 128

EQUAL-TEMPERED
MUSICAL SCALE VALUES
The table in Figure 11-15 lists the numerical values which must be stored in the SID
Oscillator frequency control registers to produce the notes of the equal-tempered musical
scale. The equal-tempered scale consists of an octave containing twelve semitones
(notes): C,D,E,F,G,A,B and C # , D # , F # , G # , A # . The frequency o f e a c h semitone is
exactly the 12th root of 2 (^v 2 ) times the frequency of the previous semitone. The
table is based on a 02 clock of 1.02 MHz. Refer to the equation given in the Register
Description for use of other master clock frequencies. The scale selected is concert
pitch, in which A^4 = 440 Hz. Transpositions of this scale and scales other than the
equal-tempered scale are also possible.
Although the table in Figure 11-15 provides a simple and quick method for
generating the equal-tempered scale, it is very memory inefficient as it requires 192
bytes for the table alone. Memory efficiency can be improved by determining the note
value algorithmically. Using the fact that each note in an octave is exactly half the
frequency of that note in the next octave, the note look-up table can be reduced from
ninety-six entries to twelve entries, as there are twelve notes per octave. If the twelve
entries (24 bytes) consist of the 16-bit values for the eighth octave (C-7 through B-7),
then notes in lower octaves can be derived by choosing the appropriate note in the eighth
octave and dividing the 16-bit value by two for each octave of difference. As division by
two is nothing more than a right-shift of the value, the calculation can easily be
accomplished by a simple software routine. Although note B-7 is beyond the range of
the oscillators, this value should still be included in the table for calculation purposes (the
MSB of B-7 would require a special software case, such as generating this bit in the
CARRY before shifting). Each note must be specified in a form which indicates which
of the twelve semitones is desired, and which of the eight octaves the semitone is in.
Since 4 bits are necessary to select one of twelve semitones and 3 bits are necessary to
select one of eight octaves, the information can fit in one byte, with the lower nybble
selecting the semitone (by addressing the look-up table) and the upper nybble being
used by the division routine to determine how many times the table value must be
right-shifted.

MUSIC NOTE VALUES

Figure 11-15 contains a complete list of N o t e # , actual note, and the values to be stored
into the HI FREQ and LOW FREQ registers of the sound chip to produce the indicated
note.

SOUND AND MUSIC O N THE COMMODORE 128

Figure 1115. Music N o t e Values

MUSICAL
NOTE

0
1
2
3
4
5
6
7
8
9
10
11
16
17
18
19
20
21
22
23
24
25
26
27
32
33
34
35
36
37
38
39
40
41
42
43
48
49
50
51
52
53
54
55
56

NOTE

OCTAVE

C-0
C#-0
D-0
D#-0
EM)
F-0
F#^)
G-0
G#^)
A-0
A#-0
B~0
C-1
C#-1
D-1
D#-1
E-1
F-1
F#-1
G-1
G#-1
A-1
A#-1
B-1
C-2
C#-2
I)-2
D#-2
E-2
F-2
F#-2
G-2
G#-2
A-2
A#-2
B-2
C-3
C#-3
l)-3
D#-3
E-3
F-3
F#-3
G-3
G#-3

OSCILLATOR
DECIMAL

268
284
301
318
337
358
379
401
425
451
477
506
536
568
602
637
675
716
758
803
851
902
955
1012
1072
1136
1204
1275
1351
1432
1517
1607
1703
1804
1911
2025
2145
2273
2408
2551
2703
2864
3034
3215
3406

HI

1
1
1
1
1
1
1
1
1
1
1
1
2
2
2
2
2
2
2
3
3
3
3
3
4
4
4
4
5
5
5
6
6
7
7
7
8
8
9
9
10
11
11
12
13

FREQ
LOW

12
28
45
62
81
102
123
145
169
195
221
250
24
56
90
125
163
204
246
35
83
134
187
244
48
112
180
251
71
152
237
71
167
12
119
233
97
225
104
247
143
48
218
143
78

367

368

COMMODORE 128

Figure 11-15. Music N o t e Values (continued)

MUSICAL NOTE

OSCILLATOR

FREQ

NOTE

OCTAVE

DECIMAL

HI

LOW

57
58
59
64
65
66
67
68
69
70
71
72
73
74
75
80
81
82
83
84
85
86
87
88
89
90
91
96
97
98
99
100
101
102
103
104
105
106
107
112
113
114
115
116

A-3
A#-3
B-3
C^
C#^l
D^4
D#^4
E^4
F^4
F#-4
GM
G#^l
A^4
A#^
B^4
C-5
C#-5
C-0
C#-0
D-0
F-5
F#-5
G-5
G#-5
A-5
A#-5
B-5
C^
C#^
D^>
D#-6
E^6
F^
F#^>
G^
G#^
A-6
A#-6
B^
C-7
C#-7
D-7
D#-7
E-7

3608
3823
4050
4291
4547
4817
5103
5407
5728
6069
6430
6812
7217
7647
8101
8583
9094
9634
10207
10814
11457
12139
12860
13625
14435
15294
16203
17167
18188
19269
20415
21629
22915
24278
25721
27251
28871
30588
32407
34334
36376
38539
40830
43258

14
14
15
16
17
18
19
21
22
23
25
26
28
29
31
33
35
37
39
42
44
47
50
53
56
59
63
67
71
75
79
84
89
94
100
106
112
119
126
134
142
150
159
168

24
239
210
195
195
209
239
31
96
181
30
156
49
223
165
135
134
162
223
62
193
107
60
57
99
190
75
15
12
69
191
125
131
214
121
115
199
124
151
30
24
139
126
250

SOUND AND MUSIC O N THE COMMODORE 128

MUSICAL NOTE

OSCILLATOR

FREQ

NOTE

OCTAVE

DECIMAL

HI

LOW

117
118
119
120
121
122
123

F-7
F#-7
G~7
G#-7
A-7
A#-7
B-7

45830
48556
51443
54502
57743
61176
64814

179
189
200
212
225
238
253

6
172
243
230
143
248
46

Figure 11-15. Music N o t e Values (continued)

FILTER

SETTINGS

LOCATION

CONTENTS

54293

Low cutoff frequency (0-7)

54294

High cutoff frequency (0-255)

54295

Resonance (bits 4-7)

Filter voice 3 (bit 2)
Filter voice 2 (bit 1)
Filter voice 1 (bit 0)
High pass (bit 6)
Bandpass (bit 5)
Low pass (bit 4)
Volume (bits 0-3)

54296

Figure 11-16. Filter Settings

369

J2
INPUT/OUTPUT
GUIDE

371

372

COMMODORE 128

INTRODUCTION
Besides being a calculator and a data manipulator, the Commodore 128 is a communicator. Through the various connecting ports, it can transmit and receive information to
many different kinds of peripheral equipment. Because of the variety of devices, each
must have its unique access codes and specific instructions (software). This chapter
includes the details of each connection and the associated technique of communicating
with various devices.

INPUT/OUTPUT PORTS
Most of the connections are considered as input and output because information is
transmitted in both directions. These connections include the Commodore Serial Port for
the disk drive(s) and printer(s), the User Port for external communication with modems,
an expansion port for additional memory, a Datassette connector for a tape storage
device, two monitor ports for both the composite video and the RGBI monitors, a TV
connector, and game ports for various control devices such as joysticks, paddles and
graphics tablets. The port pinout details begin on page 394.

DISK DRIVE
The disk drive is the most popular information storage device today. It stores programs
and data as magnetic signals on a floppy disk of flexible plastic coated with iron oxide.
Information (characters, letters and numbers) represented by a series of binary digits is
magnetically impressed upon the disk in one of thirty-five concentric ring tracks. Each
ring is divided into 17 to 21 sectors each. Each ring can store about 5000 bytes per
track. A 1541 disk drive has a capacity of about 170K. The 1571 disk drive is
double-sided, so a disk formatted on the 1571 holds twice as much data, about 340K.

FORMATTING A DISK
Blank disks from the factory are not assigned tracks or sectors. A disk must be
formatted by your computer/disk drive according to the disk operating system. You
cannot store anything on a brand-new disk until this process, called Formatting or
newing, is completed. The Commodore disk drive has built-in microprocessors that
properly organize a blank disk when instructed to do so by the computer. The eighteenth
track is used as a directory for the disk drive. All the addresses for all the blocks (over
600) are stored on track 18 as the Block Allocation Map, or more simply the directory.
Prior to formatting a disk, decide on an identification name and a two-digit code.
Select a name of up to 16 characters that will help identify your disk. For example, the
disk name could be your name, or a topic such as games. The two-digit code can be almost
any letter-number combination. This code immediately alerts the disk drive whenever

I N P U T / O U T P U T GUIDE

you change disksso, for your own protection, try to assign each disk a unique code.
The format command for C128 mode is as follows:
HEADER "disk name", Ixy,DO,ON U8
For C64 or C128 modes, use:
OPEN 15,8,15, "NO:diskname, x y "
Note that xy is any two-digit code you select, such as 01, 45, W3, 40, or WD.
The 0 after the D or N represents the default drive number for a single disk drive or the
first drive of a dual drive unit where both share a common device number. The 8 in each
statement represents the device number. A second drive would be set to number 9, a
third drive to 10, etc. With a single drive, the HEADER command can simply be:
HEADER"disk name",Ixy
The formatting process typically takes about 80 seconds on the 1541 disk drive,
and considerably less on the 1571 drive. Once this operation is completed, this disk can
be used for storing programs and data. Do not format it againotherwise everything
saved on it will be erased. To simply " w i p e " an already formatted disk, use the above
instructions but do not include the comma followed by an identification number. This
process will maintain the original format, use the new name and wipe the directory
cleana process considerably faster than total formatting.
The OPEN command establishes a communication link between the computer and
a specific device number. Disk drives are factory set as device number 8 and can be
converted to device 9, 10, 11 or 12. See your disk drive manual for details.
To verify you have properly formatted the disk, see the section below on reading
the directory.

SAVING PROGRAMS
The saving process for
the computer. It simply
the disk drive. Nothing
disk with the following

storing programs on a disk does not remove the program from

"copies" the program or file from the computer onto the disk in
is lost in the process. BASIC programs are saved to a formatted
commands:

C128 or C64

SAVE"program name",8

C128 only

DSAVE"program name"
DSAVE"program name",D0,U9

(if the drive is device number 9).

In C128 mode, machine language programs or binary files can be saved through
these BASIC commands:
BSAVE"filename",Bb,Ps TO Pe
or BSAVE"filename",D0,U9,Bb,Ps TO Pe
(if the drive is device number 9).

373

374

COMMODORE 128

In these formats:
" b " is the memory bank number (0 through 15)
' V ' is the starting address
" e " is the ending address
EXAMPLE:
B S A V E ' ' f i l e n a m e " , B 2 , P 3 5 8 4 TO P4096
This saves the binary file named " f i l e n a m e " from memory bank 2, in the range of
memory between 3584 to 4096 decimal.
The following command saves a BASIC program in either C128 or C64 modes:
SAVE " f i l e n a m e " , 8
where 8 represents the device number.

REPLACING A FILE OR PROGRAM

When re-saving a program under the same filename, you must use the at sign (@) in the
SAVE command format, as follows:
In BASIC 7.0: D S A V E " @ p r o g r a m n a m e "
In BASIC 2.0: SAVE"@0:program n a m e " , 8
The @ symbol tells the computer to store this program in place of the one of the
same name. Without this symbol, the disk drive will not allow the new program to be
stored. Note that during the replace process, the new program is saved first, then the old
one is automatically deleted and the directory updated. Use VERIFY to make sure you
are saving correctly.

VERIFYING A PROGRAM OR FILE

You may want to verify that a program was accurately saved on the disk. The VERIFY
command compares the program in memory with the program on the disk. If the
programs are identical byte for byte, an OK message is displayed.
In BASIC 7.0, use the following:
DVERIFY 4 4 filename''
or
DVERIFY' 4 filename'', D0, U9
The first command above verifies a program using a single disk drive assigned as Unit 8,
and the second command above verifies a program using a single disk drive assigned as
unit 9.
In 2.0 BASIC, use:
VERIFY' 'filename'' ,8
or

VERIFY'' filename'', 8,1

I N P U T / O U T P U T GUIDE

(to verify the program from the memory location from which it was SAVEd, primarily
machine language programs).
After your program has been saved and verified, it is stored on your disk for future
use.

THE DIRECTORY
Once a disk is formatted, it has a directory, or catalog listing of the files stored on the
disk. Prior to loading a program, you may want to view the directory to find out exactly
what is stored on the disk. When you call for the directory, the screen displays the disk
name and identification number followed by a list of programs or files presently stored.
Of course, a newly formatted disk will display only its name and number. To see the
directory, use the commands listed below.
In BASIC 7.0, use the following:
or
or
or

DIRECTORY
CATALOG
CATALOG D0,U9
DIRECTORY D0,U9 (for a dual disk drive, device number 9)

The program in memory is not affected by this command.

In BASIC 2.0, use the following command:
L O A D " $ 0 ' ' ,8:LIST
This command erases the resident program. The 0 is optional with a single-drive
unit.
To print a hard copy of a directory, you must use the BASIC 2.0 method. You
must first open a channel to the printer. This is covered below in the section Output to a
Printer.

RETRIEVING PROGRAMS OR
FILES FROM DISKS
Once you have files or programs stored on a disk, you retrieve them with an appropriate
version of the LOAD command.
In BASIC 7.0, use the following command:
DLOAD"filename"
or

DLOAD'' filename'' ,D0,U9

(for disk drive unit 9, drive 0)

To retrieve a program or binary file saved by the BSAVE command or by the

machine language monitor, use the following BASIC 7.0 command:
BLOAD' 'filename" ,Bb,Ps

375

376

COMMODORE 128

or

BLOAD 4 4 fi lename'', DO, U9, B b, Ps

(for disk drive unit 9, drive 0)

where b is the bank number and s is the starting address.

In BASIC 2.0, use the following command formats:
To load a BASIC program: LOAD"filename",8
To load a machine language program: LOAD"filename",8,l
The relocate flag is either a 1 or a 0, which is the default value. The 1 tells the
computer to LOAD from the point where it was SAVEd.

CREATING AND STORING FILES

A file is a series of related data: characters, numbers and letters. Anything stored on the
disk is considered a file. A program is a specific type of file that can be executed or run.
Data files are files that contain raw data used by a program. These files are classified as
either sequential, relative, user or random. The directory lists all the files and indicates
the type of file: PRG for program, SEQ for sequential file, REL for relative file and
USR for user files.
A program is a file that contains operating instructions for the computer. A
sequential file is a series of data stored in sequence and can be read only in sequential
order. A relative file is a file stored in sequential order and can be accessed directly at
any location using a pointer.
The creation of a sequential file is initiated with an OPEN statement. A file is
OPENed with the following information:

File number: 0 through 255; 15 is reserved for special commands and error
checking.
Device number: default is 8 for a disk drive; 4 for a printer (4-30 are available
for serial bus devices).
Channel number: 0 through 255; the line of communication established between
devices (also known as secondary address)

Additional (optional) information may also be specified with quotes:

Drive number followed by a colon: default is 0 for a single drive; 1 may be

specified on a dual drive.
Filename: the name of the file, up to 16 characters.
Filetype: SEQ sequential, PRG = program, REL = relative, USR = user
Operation: (R = read, W = write)

The following command:

OPEN 111, 8, I2,"0:NAME, S , W "

INPUT/OUTPUT GUIDE

opens file number 111 on device number 8, using channel 12. The file is opened to
default drive 0, with the filename " N A M E , " as a sequential file. The W specifies that a
write operation will take place. To store data, it is "written" on the disk. Data is
retrieved by "reading" the disk.
Enter, save and run the following programs as sample routines to create, save and
read a sequential file. See your disk drive manual for more information.
10
11
20
25
30
40
50
60

REM STORE DATA

REM NOTE PROGRAM STOPS WHEN YOU RESPOND WITH " E N D " .
OPEN 5 , 8 , 5 , " E X A M P L E , S , W "
DO
INPUT " N A M E OF A FRIEND'';N$
PRINT#5,N$
IF N $ = " E N D " T H E N CLOSE 5:END
LOOP

NOTE: In C128 mode, the Commodore 128 has a set of disk input/
output commands. These include the DLOAD and DSAVE commands
already described, as well as the DOPEN, DCLOSE and other commands. See the BASIC 7.0 Encyclopedia in Chapter 2 or your disk drive
manual for details on any of these commands.

Line 20 tells the disk drive to open a sequential file for writing data. Line 30
obtains the information from the keyboard by requesting it on the screen. The PRINT#
statement in line 40 specifies the file number where the information is to be written.
Line 40 is the statement that actually writes the data to the channel and creates the
contents of the file. Line 50 also puts a recognizable end-of-file markerthe word
" e n d " at the end of the file. Line 50 closes the file after all data has been written.
Here's a program that reads the data from the sequential file you just created:
10
20
25
30
40
50
60

REM RETRIEVE FILES

OPEN 6,8,6,"EXAMPLE,S,R"
DO
INPUT#6,L$
IF L$ = " E N D " T H E N CLOSE6:END
PRINT L$
LOOP

Line 20 opens a channel to the sequential file called EXAMPLE for reading. Once
the end item is found, the file is properly closed. As each item is retrieved using the
INPUT# statement, it is printed to the screen with a simple PRINT statement. Any
sequential file in which all writing has been completed and which is already closed can
be opened only as a read file; it cannot be written to unless an APPEND operation is
specified or the @ prefix is used.
Files can be expanded in size with the BASIC 7.0 APPEND command as follows:

377

378

COMMODORE 128

A P P E N D # 7 , ' 'EXAMPLE"
This command opens the file called " E X A M P L E . " Any data sent to it in a PRINT#7
statement will be appended. Any file number may be specified as long as the PRINT file
number matches the APPEND file number.
Once all the data is sent, the channel is closed with
DCLOSE#7
In BASIC 2.0, use this command:
OPEN7,8,7, "0:EXAMPLE,A"
The letter A allows subsequent PRINT# statements to enter data at the end of the
file "Example." This BASIC 2.0 technique also requires a CLOSE statement: CLOSE7.

OTHER FILES
C128 BASIC includes several direct disk drive housekeeping commands including
SCRATCH, RENAME, CONCAT, COPY and COLLECT as well as a relative file
command RECORD. Note that these operations are also available in the C64 mode if
combined with an OPEN statement on channel 15. See your C128 System Guide
Encyclopedia or disk drive manual for details.
In addition, see your disk drive manual for details on relative files, random files
and direct program access to the disk drive microprocessor via channel 15.

CHANGING THE DISK DRIVE

DEVICE NUMBER
The disk drive device number is usually 8, but it can be changed to be device 9, 10, or
11 by either a hardware or software change. The following command changes your drive
to unit 9 through software until power is turned off:
OPEN 15,8,15:PRINT# 15,'' M-W'' CHR$( 119)CHR$(0)CHR$(2)
CHR$(41)CHR$(73):CLOSE15
The 1571 has a device number switch on the back.

OUTPUT TO A PRINTER
Your Commodore 128 computer transmits data over the serial port to many different
styles of printers. The most popular Commodore printers today are the daisy wheel and
dot matrix types. The daisy wheel system uses metal or plastic molded letters similar to
those on a typewriter and produces the finest impressions. The fingers that hold these
characters are mounted on a center post, and the wheel resembles a daisy flower. The
printer head spins the wheel until the correct letter is in position behind a hammer,
which presses it against a ribbon onto the paper.
The more versatile system is the dot matrix. Using a column of metal pins, a

I N P U T / O U T P U T GUIDE

series of dots is impressed on paper through an inked ribbon as the printer head moves
across the page. The pattern of dots is based upon the binary code of each character.
The infinite number of potential dot patterns makes it possible to print any style
character imaginable from italics to Japanese depending only upon the printer's internal
software (firmware).
Although many printer manufacturers claim their system is compatible with the
Commodore 128 computer, if Commodore does not authorize the use, a special printer
interface may be required. Printers cited as Centronics parallel or Serial do not directly
match any of the Commodore computer ports. Commodore does not support any thirdparty printers or printer interfaces. The Commodore Serial Port is unique and not the
same as the RS232 Serial Port, which many printer manufacturers specify.
The Commodore computer can display 512 characters. The second set of 256
includes both upper and lower case letters; the first includes upper case only with
graphics. This is possible by using identical codes accessed separately. Consequently,
only Commodore dot matrix printers are preprogrammed to print all the available
Commodore characters. Owing to these differences, Commodore's ASCII codes are not
identical to the true ASCII standard. Therefore, special modifications are required when
interfacing with non-Commodore equipment.
In order to operate a printer, a line of communication with the computer must be
opened using the OPEN statement. The printer is usually device number 4, though often
switch selectable to 5. The command:
OPEN 3,4
establishes a link to the printer as device number 4. The first number can be any
number between 1 and 255. Numbers beyond 128 force a line feed after a carriage return.

PRINTING A PROGRAM LISTING

The following commands will produce a printed listing:
OPEN3,4:CMD3:LIST
The CMD command redirects all screen output to the printer. Any subsequent
output is sent to the printer until turned off with:
PRINT#3:CLOSE3
These statements are necessary to clear the channel and ensure that all commands
have been properly sent to the printer.

NOTE: To print a listing with double spacing, a line feed can be forced
using a file number greater than 127 such as:

OPEN 131,4:CMD 131 :LIST:PRINT# 131 :CLOSEl 31

379

380

COMMODORE 128

PRINTING A TYPED LINE

A PRINT# command to an opened print file number outputs the associated data to the
printer. The following commands output whatever is typed:
OPEN3,4:PRINT#3, 4 T Y P E ANYTHING''
After R E T U R N is depressed, the line is sent to the printer and anything
under quotes is printed on paper.

PRINTING THROUGH A PROGRAM

Instructions to a printer require a PRINT# statement and can be mixed with the
PRINT statement for video display. The following program prints five lines of text for
each PRINT# statement while using the screen display to obtain the input:
10
20
25
30
40
50
60
70

OPEN 3,4,7
DO UNTIL L = 5
IF L - 0THEN30 :ELSE INPUTA$:GOT040
INPUT"PLEASE TYPE'' ;A$
PRINT#3,A$
L = L+1
LOOP
CLOSE3

This is the beginning of a simple word processor and could be expanded into a
complex system through printer control.

CONTROLLING YOUR PRINTER

Each printer capability (such as lower case characters, line feed, double width characters, reverse characters, dot graphics and special print fonts) is controlled by sending the
proper control code from the computer. Depending upon the printer being used, there
are two ways of sending codeeither via the CHR$ function or the secondary address.
Standard codes are sent via the BASIC CHR$(X) function. ASCII codes under 27
are generally reserved for printer codes (such as 14 for the double width feature). Codes
over 27 represent specific keyboard characters. Printer control codes over 27 (e.g., 145)
are preceded with the ESCape code 27. Some systems will accept CHR$(27) followed
by either CHR$(X) or the equivalent character within quotes. Thus, boldface type
represented by Code 33 could be turned on with:
or

PRINT#3, CHR$(27)CHR$(33)
PRINT#3, CHR$(27)"!"

and turned off with:

PRINT#3, CHR$ (27)CHR$(34)
assuming channel 3 was previously opened.

I N P U T / O U T P U T GUIDE

Many word processors can accommodate special printer controls with at least one
of these methods. Refer to your printer and word processing manuals for the technique
of sending control characters to your printer.
The alternate method of sending control codes to a printer is via the secondary
address in the OPEN statement. An OPEN statement without a secondary address
defaults to 0. Hence OPEN3,4 is the same as OPEN3,4,0. Generally a secondary
address of 7 will cause the printer to print with upper case and lower case characters:
OPEN3,4,7
Other secondary addresses are often available and will perform various duties in
accordance with your printer's design. See your manual for specifics. Most word
processors allow the use of secondary addresses as embedded codes.
The following program will open a channel to a sequential file on disk, read data
and output to a printer:
10
20
25
30
40
50
60
70
80

OPEN 3,8,3,"EXAMPLE,S,R"
OPEN 4,4,0
DO
INPUT#3,L$
IF L$ = " E N D ' 'THEN80ELSE50
PRINT#4,L$
PRINT L$
LOOP
CLOSE4:DCLOSE3:END

OUTPUT TO A MODEM
A modem is a device used to transmit and receive data across telephone lines.
Generally, a computer uses an RS232 port to communicate with the external
world. Commodore's RS232C Port (also known as the User Port) is a variation of the
RS232 standard port. The RS232 has 0 to 5 TTL voltage levels rather than the standard
plus/minus 12 volts.
The OPEN statement for the modem (device 2) sets up the parameters to match the
speed (baud rate) and format (number of data and stop bits) of the host computer by
sending a Control Register code. A second required code, the Command Register code,
defines the parity, duplex and handshake. For example:
OPEN3,2,0,CHR$(6)CHR$(112)
opens a channel to the User Port (device # 2 ) and establishes a 300-baud rate, 8-bit
word, single stop bit (Control Register (6)), even parity and half duplex (Command
Register (112)). See Figure 12-1, the Control Register Map, and Figure 12-2, the
Command Register Map.

381

382

COMMODORE 128

THE RS-232 CHANNEL

The RS-232 capabilities can be accessed from either BASIC or machine language.
The BASIC commands INPUT# and G E T # are used to fetch data from the receiving
buffer while P R I N T # and CMD place data into the transmitting buffer.
The RS-232 Kernal routines run under the control of the 6526 CIA # 2 device
timers and interrupts. The 6526 chip generates NMI (Non-Maskable Interrupt) requests
for RS-232 processing. This allows background RS-232 processing to take place during
BASIC and machine language programs. There are built-in hold-offs in the Kernal,
cassette and serial bus routines to prevent the disruption of data storage or transmission
by the NMIs that are generated by the RS-232 routines. During cassette or serial bus
activities, data can not be received from RS-232 devices. But because these hold-offs
are only local, (assuming you're careful about your programming) no interference
should result.
There are two buffers in the Commodore 128 memory to help prevent the
loss of data when transmitting or receiving RS-232 information.
The Commodore 128 RS-232 I/O buffers consist of two first-in/first-out (FIFO)
buffers, each 256 bytes long. In C128 mode, the RS-232 I/O buffers are permanently
allocated. The input buffer is located between 3072 and 3327 ($0C00-$0CFF). The
output buffer is located between 3328 and 3583 ($0D00-$0DFF). You cannot harm
program storage by opening and closing the RS-232 channel as can happen with the
Commodore 64. By permanently allocating the buffers in a fixed location, no " O U T OF
M E M O R Y " error can occur, and your program in memory will not get "stepped o n . "

OPENING THE RS-232 CHANNEL

Only one RS-232 channel should be open at any time; a second OPEN statement will
cause the buffer pointers to be reset. Any characters in either the transmit buffer or the
receive buffer will be lost.
Up to 4 characters can be sent in the filename field. The first two are the control
and command register characters; the other two are used for user-defined, non-standard
baud rates. Baud rate, parity and other options can be selected through this feature.
No error checking is done on the control word to detect a nonimplemented baud
rate. Any illegal control word will cause the system output to operate at a very slow rate
(below 50 baud).

BASIC SYNTAX
OPEN lfn,2,0"<control reg.> <command reg.> <opt baud l o w > <opt baud h i g h > "
The logical file number (lfn) then can be any number from 1 through 255. But be
aware of the fact that if you choose a logical file number that is greater than 127, then a
line feed will follow all carriage returns.

THE CONTROL REGISTER

The Control Register is a single-byte required to specify the baud rates and other RS-232

I N P U T / O U T P U T GUIDE

options. Select the parameters you want from the Control Register Map (Figure 12-1)
by placing the proper bit value in binary form. A selection, for example, from left to
right of two stop bits, 7-bit word and 1200-baud rate yields:
1010 1000 (in binary), which is decimal 168 ($A8) and results in
OPEN 3,2,0,CHR$(168)
defining these parameters.
128 64 32

16

0@

@@B@
BAUD RATE

STOP BITS

0-1 STOP BIT

1-2 STOP BITS

WORD LENGTH'
BIT
DATA
_6_ 5 WORD LENGTH

USER RATE

50 BAUD

75

110

134.5

150

300

600

1200

8 BITS

1800

[Nl]

7 BITS

2400

[Nl]

6 BITS

3600

[Nl]

5 BITS

4800

[Nl]

7200

[Nl]

9600

[Nl]

19200

[Nl]

UNUSED

Figure l 2 - l . Control Register Map

THE COMMAND REGISTER

The Command Register is a single byte that defines parity, duplex and handshaking.
Select the parameters from the Command Register Map in Figure 12-2 by creating the
binary code and converting it to a decimal value. Thus:

383

384

COMMODORE 128

OPEN3,4,0,CHR$(168)CHR$(32)
specifies odd parity, full duplex. A baud rate other than those listed in the Control
Register Map is also selectable by choosing 0000 for bits 0 through 3 in the Control
Register and including this rate in the OPEN statement as two bytes following the
Command Register.
The " o p t baud l o w " and high byte values are calculated from the desired
baud rate as a function of the system frequency (1.022727E6 for the USA NTSC
system or 0.985248E6 PAL European system). Divide the frequency by the desired
rate. Divide this in half and subtract 100. This represents a two-byte decimal number.
The high value is the number of times it can be divided by 256. The remainder is the
low byte.

PARITY OPTIONS
BIT BIT BIT
OPERATIONS
7
6
5
-

PARITY DISABLED, NONE

GENERATED/RECEIVED
ODD PARITY
RECEIVER/TRANSMITTER
EVEN PARITY
RECEIVER/TRANSMITTER
MARK TRANSMITTED
PARITY CHECK DISABLED
SPACE TRANSMITTED
PARITY CHECK DISABLED

DUPLEX
0-FULL DUPLEX
1-HALF DUPLEX
UNUSED
UNUSED
UNUSED

Figure 12-2. Command Register Map

"-HANDSHAKE
0-3 LINE
1-X LINE

INPUT/OUTPUT GUIDE

EXAMPLE:
1000 Baud: Divide the system frequency by the baud rate:
1022727/1000 1022.727
Divide by 2 and subtract 100: 1022.727/2 - 100 = 411.3635 (or rounded up to412)
Convert this into two byte values: Division by 256 results in 1 with a remainder of
156. The following statement therefore defines a 1000-baud, 7-bit, single stop bit, odd
parity, full duplex:
OPEN3,2,0,CHR$(32)CHR$(32)CHR$( 156)CHR$( 1)
where the Control Register value in binary is 00100000 and the Command Register in
binary is 00100000.
NOTE: In a C64 BASIC program, the RS-232 OPEN command should be
performed before creating any variables or arrays because an automatic
CLR is performed when an RS-232 channel is OPENed owing to the
allocation of 512 bytes at the top of memory. This is not the case in C128
mode, since the RS-232 I/O buffers are permanently allocated.

GETTING DATA FROM THE

RS-232 CHANNEL
The Commodore 128 receiver buffer ($0C0CM>0CFF) will hold up to 255 characters before
overflowing. This is indicated in the RS-232 status word ST. If an overflow occurs, subsequent characters are lost. Keep the buffer as clear as possible. To receive data at high
speeds, use machine language routines or use the FAST command to process at 2MHz
with the 80-column screen (in C128 mode only).
Use G E T # with the file number corresponding to the OPEN statement. Machine
code Kernal entries include BASIN and GETIN.

SENDING DATA TO THE

RS-232 CHANNEL
When sending data, the output buffer ($0D00-$0DFF) can hold 255 characters before a
full buffer hold-off occurs. The system will wait in the CHROUT routine until transmissionisallowedorthe R U N / S T O P
and R E S T O R E
keysareusedto
recover the system.
Use C M D or P R I N T # with the proper file number to send data. Acceptable
Kernal entries include BSOUT (CHROUT).

CLOSING THE RS-232 CHANNEL

Use CLOSE followed by the file number to close the RS-232 channel. Closing the file discards
all data in the buffers at the time of execution, stops all transmitting and receiving and sets
the RTS and transmitted data lines high. In C64 mode (only) CLOSE removes both buffers.

385

386

COMMODORE 128

NOTE: Care should be taken to ensure all data is transmitted before

closing the channel. A way to check this from BASIC is:
10 DO
20 LOOP WHILE PEEK (2575) and 3
30 CLOSE lfn
Location 2575 is the RS-232 " E N A B L " location.
Table 12-1 defines the User Port RS-232 channel lines.
(6526 DEVICE # 2 Loc. $DDOO-$DDOF)
PIN

6526

ID

ID

DESCRIPTION

EIA

ABV

OUT

c
D
E
F
H
J
K
L

PB0
PBI
PB2
PB3
PB4
PB5
PB6
PB7

Received Data
Request to Send
Data Terminal Ready
Ring Indicator
Received Line Signal
Unassigned
Clear to Send
Data Set Ready

(BB)
(CA)
(CD)
(CE)
(CF)
(CB)
(CC)

Sin
RTS
DTR
Rl
DCD
XXX
CTS
DSR

IN
OUT
OUT
IN
IN
IN
IN
IN

1 2
1*2
1*2
3
2
3
2
2

B
M

FLAG2
PA2

Received Data
Transmitted Data

(BB)
(BA)

Sin
S0ut

IN
OUT

1 2
1 2

A
N

GND
GND

Protective Ground
Signal Ground

(AA)
(AB)

GND
GND

IN/

( )

MODES

1 2
1 2 3

MODES:

1. 3-Line Interface (S in ,S out ,GND).

2. X-Line Interface.
3. User Available Only (Unused/unimplemented in code).
* These lines are held high during 3-Line mode.
Table 12-1. User Port Lines
[7] [6]

[5]

[4]

[3]

[2]

[1]

[ 0 ] (Machine Lang. RSSTAT)

:_PARITY ERROR BIT

:
:
:

FRAMING ERROR BIT

RECEIVER BUFFER OVERRUN BIT
RECEIVER BUFFER EMPTY
(USE TO TEST AFTER A GET#)

:
:

CTS SIGNAL MISSING BIT

UNUSED BIT
DSR SIGNAL MISSING BIT
BREAK DETECTED BIT

Figure 12-3. RS-232 Status Register

I N P U T / O U T P U T GUIDE

NOTES to Figure 12-3:

The RS-232 Status Register can be read with these statements.
If the STATUS = 0, then no error has been detected.
S = PEEK (2580): PRINT S : POKE 2580,0
If the RS-232 status is read by BASIC with the above statements or by
using the KERNAL READST routine, the RS-232 status word is cleared
when you exit. If multiple uses of the STATUS word are necessary, the
S variable above should be assigned to another variable. For example:
SR = S: REM ASSIGNS S TO SR
The RS-232 status is read (and cleared) only when the RS-232 channel
was the last external I/O used.

SAMPLE BASIC PROGRAM

USING RS-232 CHANNEL
This simple terminal program works in both C128 and C64 modes:
10 REM SIMPLE DUMB TERMINAL EMULATOR
20 REM THIS PROGRAM REQUIRES A MODEM
30 OPEN5,2,3,CHR$(6)+CHR$(0)
40 DIMF%( 2 5 5) ,T%( 255)
5 0 F0RJ=32T06 4:T%(J)=J:NEXT
6 0 T%(13)=13:T%(2 0)=8:RV=18:CT=0
7 0 FORJ=6 5T090:K=J + 3 2:T%(J)=K:NEXT
80 FORJ91T09 5:T%(J)=J:NEXT
9 0 FORJ=19 3T0218:K=J-12 8:T%(J)=K:NEXT
100 T%(146)~16:T%(13 3)=16
110 T%(13 7)-3:T%(13 4) = 17:T%(13 8)-19
120 FORJ=0TO255
130 K=T%(J)
140 IFK<>0THENF%(K)=J:F%(K+128)=J
150 NEXT
160 PRINT" "CHR$(147)
170 GET#5,A$
180 IFA$=""ORST<>0THEN220
190 PRINT" "CHR$(15 7) ;CHR$(F%(ASC(A$) ) ) ;
20 0 IFF%(ASC(A$))=3 4THENPOKE212,0
210 GOT0170
220 PRINTCHR$(RV)" "CHR$(157);CHR$(146);:GETA$
2 30 IFA$<>""THENPRINT# 5,CHR$(T%(ASC(A$) ) ) ;
240 CT=CT+1
250 IFCT=8THENCT=0:RV=164-RV
260 GOT0170

ZERO-PAGE MEMORY LOCATIONS AND

USAGE FOR RS-232 SYSTEM INTERFACE
The zero-page RS-232 storage locations for both C128 and C64 modes are as follows:
$00A7-INBITReceiver input bit temp storage.
$00A8-BITCIReceiver bit count in.
$OOA9-RINONEReceiver flag start bit check.

387

388

COMMODORE 128

$OOAA-RIDATAReceiver byte buffer/assembly location.

$OOAB-RIPRTYReceiver parity bit storage.
$00B4-BITTSTransmitter bit count out.
$00B5-NXTBITTransmitter next bit to be sent.
$OOB6-RODATATransmitter byte buffer/disassembly location.
All the above zero-page locations are used locally and are given only as a guide to
understand the associated routines. These cannot be used directly by the BASIC or
Kernal-level programmer to do RS-232-type programming functions. The system RS-232
routines must be used.

NONZERO-PAGE MEMORY LOCATIONS A N D

USAGE FOR RS-232 SYSTEM INTERFACE
The general (nonzero-page) RS-232 storage locations for C128 mode are as follows:
(The addresses in parentheses are for C64 mode.)
$0A 10($0293)-M5lCTRPseudo 6551 Control Register (see Figure 12-1).
$0A 11 ($0294)-M51CDRPseudo 6551 Command Register (see Figure 12-2).
$0A12($0295)-M51AJBTwo bytes following the Control and Command Registers in
the file name field. These locations contain the user-defined baud rate for the start
of the bit test during the interface activity, which, in turn, is used to calculate baud rate.
$0A14($0297)RSSTATThe RS-232 Status Register (see Figure 12-3).
$0A15($0298)-BITNUMThe number of bits to be sent/received.
$0A16($0299)-BAUDOFTwo bytes that are equal to the time of one bit cell (based on
system clock/baud rate).
$0A18($029B)-RIDBEThe byte index to the end of the receiver FIFO buffer.
$0A19($029C)-RIDBSThe byte index to the start of the receiver FIFO buffer.
$0AlA($029D)-RODBSThe byte index to the start of the transmitter FIFO buffer.
$0AlB($029E)-RODBEThe byte index to the end of the transmitter FIFO buffer.
$0A0F($02Al)-ENABLHolds current active interrupts in the CIA # 2 ICR. When bit
4 is turned on, the system is waiting for the Receiver Edge. When bit 1 is turned
on, then the system is receiving data. When bit 0 is turned on, then the system is
transmitting data.

OUTPUT T O A SCREEN
The most common form of computer output (called soft copy) is a display tube that
displays luminescent dots on a screen controlled by electrical signals. Although the
television is a specialized monitor and limited by the dot density prescribed by FCC
standards for proper reception, it is available in most homes and becomes a ready-to-use
output device for the home computer. The C128 computer sends radio frequency signals
through the TV port to the television's antenna and tuner.
Monitors for computers produce better-quality displays since they are direct-wired

I N P U T / O U T P U T GUIDE

and involve no tuners. The C128 includes a port to accept the traditional monitors as
well as Commodore's 40-column 1702 color monitor. The C128 80-column color
capability is enhanced with the new 40/80-column color monitor Model 1902. In
this RGBI monitor, signals separately control each of the three color guns (red, green,
blue) for maximum clarity and detail.
The screen can be accessed as an input or output device through the OPEN
command as device 3.
OPEN 1,3
The screen is the default output device on the C128. Typing on the keyboard (device 0)
results in a screen character display output whenever the monitor is powered up. No
special commands are normally required. However, once control is sent to another
device, reversion to the screen may be desired.
Control of the screen display is available primarily with the PRINT command;
associated punctuation including the quote and the semicolon and common, BASIC
functions including the TAB(X), SPC(X), and CHR$(X) as well as the POKE command. In addition, there are color controls, sprite animation and graphics keys.
If using the dual 1902 monitor or two separate 40- and 80-column monitors, it is
possible to swap control between the two screens via the 4 0 / 8 0 switch or pressing
the E S C and X keys. If one is used for text and the other for graphics, use the
GRAPHIC command.
The following command will also swap the display output device:
PRINT CHR$(27)"X"
In addition to a screen display, sound commands can be used through a Commodore
monitor or the television speakers. See Chapter 11, Sound and Music.

OUTPUT TO THE DATASSETTE

Commodore programs and files can also be stored on tape cassette using a special
recorder called the Datassette. Unlike most tape recorders, which store analog sinusoidal
signals, the Datassette stores digital pulse signals that are more distinct, resulting in
a reliable storage format. Compared to a disk storage system, tape is somewhat slower
and limited to program and sequential files. Access to the files on tape is sequential.
Just as DLOAD automatically loads a program from disk, LOAD loads a
program from tape. Similarly SAVE and VERIFY automatically default to tape. A
LOAD for machine code requiring a secondary address would be:
LOAD"NAME",l,l
Access to tape for sequential files is made with an OPEN statement to device 1:
OPENl,l
A secondary address of 0 (default value) assumes the file is opened for reading
(using INPUT# or G E T # ) . A secondary address for writing (PRINT# statements)
requires a 1 or 2, where 2 includes an end-of-tape marker.

389

390

COMMODORE 128

OPEN 1,1,2 4 4 FILENAME''

The end-of-tape marker prevents searching for files beyond the data file you are looking
for. It is written when the CLOSE command is given.
NOTE: Do not connect the Datassette and the 1571 disk drive to the C128
at the same time. If they are used at the same time, the data transfers may
not be reliable.

INPUT FROM THE

CONTROLLER PORTS
The C128 has two controller ports (numbered 1 and 2) that allow the use of control
devices such as a mouse, joystick, paddle or light pen. Each game port will accept either
one joystick, one mouse, or one paddle pair. A light pen can be plugged only into Port 1.

JOYSTICKS
A digital joystick has five distinct switches. Four of the switches are used for direction
and one is used for the fire button. The joystick switches are arranged as shown in
Figure 1 2 ^ .
(Top)
FIRE
(Switch 4)
UP
(Switch 0)
LEFT

RIGHT

(Switch 2)

(Switch 3)

DOWN
(Switch 1)

Figure 12-4. Joystick Switch Arrangement

These switches correspond to the lower 5 bits of the data in location 56320 or
56321. Normally the bit is set to a 1 if a direction is not chosen or the fire button is not
pressed. When the fire button is pressed, the bit (bit 4 in this case) changes to a 0. To
read the joystick from C64 BASIC, the following subroutine should be used:

INPUT/OUTPUT GUIDE

10
20
30
40
50
60

REM JOYSTICK READ ROUTINE FOR C128 OR C64 MODES

JV=PEEK(56 321)
IF (JV AND 15)<15 THEN PRINT 15-(JV AND 15)
FIRE=JV AND 16
IF FIRE<>16 THEN PRINT"FIRE"
GOTO 2 0

NOTE: For the firstjoystick, set JV = PEEK (56320).

The values for JV correspond to the joystick directions shown in Table 12-2.

JV EQUAL TO

0
1
2
3
4
5

DIRECTION

NONE
UP
DOWN
LEFT
UP & LEFT
DOWN & LEFT

8
9

10

RIGHT
UP & RIGHT
DOWN & RIGHT

T a b l e 12-2. Joystick D i r e c t i o n Values

A machine language routine that accomplishes the same task is given in the
section on shift and rotate instructions in Chapter 5, Machine Language on the
Commodore 128.
BASIC 7.0 includes specialjoystick functions. To determine the position ofjoystick
N, PRINT JOY(N) returns the position of the joystick. A number between 0 and 8
inclusive specifies the relative position where 0 is stationary and 1 through 8 represent
clockwise positions. Values between 128 and 136 signify the fire button is pressed as
well. Thus if JOY(2) returns 131, it means joystick number 2 fires to the right (position 3).
10 REM Cl28-MODE SPRITE-MOVE JOYSTICK ROUTINE
20 SPRITE l,l,7:REM ENABLE SPRITE 1
30 MOVSPR 1 , 160 , 15 0 :REM PLACE SPRITE 1 ON CENTER OF THE SCREEN
4 0 DO
50 : DO
60 :
A=JOY(1):REM GET JOYSTICK DIRECTION VALUE
70 :
IF A=0 THEN LOOP:REM LOOP IF ZERO - THIS KEEPS SPRITE STATIONARY
80 :
B=A:REM SET B EQUAL TO A
90 :
Z=(A-1)*4 5:REM CALCULATE ANGLE
100 :
MOVSPR l,5;Z:REM MOVE SPRITE 5 UNITS AT THE CALCULATED ANGLE
110 :
A=JOY(1):REM CHECK JOYSTICK VALUE AGAIN
120 : LOOP WHILE A=B:REM MOVE IN THE SAME DIRECTION WHILE NEW VAL=OLD JOY VALUE
130 LOOP:REM OTHERWISE CHECK JOY VALUE AGAIN AND MOVE IN DIFFERENT DIRECTION

391

392

COMMODORE 128

Using Boolean logic and the masking technique, a comparison can be made to
determine whether the fire button was depressed:
IF (JOY(N)AND 128) = 128 THEN PRINT"FIRE"

THE 1350 MOUSE

The Commodore 128 makes use of an additional new peripheral device known as a
mouse. The Commodore mouse is a user interface that allows you to control the
operations of a program, such as selecting menu or icon options, without the need to
type on the keyboard. It attaches to the controller ports like a joystick, paddle or light
pen. Programs that support a mouse usually have a pointer indicator to let you know
where the mouse is pointing on the screen. To move the pointer on the screen, place the
mouse on a flat surface and move it in the direction you want to move the pointer. Lift
the mouse off the surface and the screen indicator remains stationary. The left hand
button responds like a joystick fire button. The right hand button may have additional
functions as specified by a particular software package.
As far as BASIC is concerned, the mouse is supported by the JOY function, the
same way a joystick is controlled. The previous joystick program example, which
moves a sprite on the screen, also works with the mouse. The Joystick Musician
program in Chapter 11 also works with the mouse. Any BASIC program using the JOY
joystick function should operate with the Commodore mouse.
The mouse also works in C64 mode, the same way a joystick routine would in
C64 mode. The previous C64 mode joystick example program supports the mouse in
C64 mode.

PADDLES
A paddle is connected to both CIA-1 and the SID chip (MOS 6581 Sound Interface Device)
through a controller port. The paddle value is read via the SID registers 54297 ($D419) and
54298 ($D41A). Paddles are not reliable when readfrom BASIC alone! The best way to
use paddles, from BASIC or machine code, is to use a machine language routine (SYS
to it from BASIC then PEEK the memory locations used by the subroutine).
The following BASIC program moves a sprite with paddles:
10 REM C128-MODE SPRITE-MOVE PADDLE ROUTINE
2 0 REM PLACE DUAL PADDLES IN CONTROLLER PORT A
30 REM PADDLE 1 CONTROLS HORIZONTAL SPRITE MOVEMENT
4 0 REM PADDLE 2 CONTROLS VERTICAL MOVEMENT
50 SPRITE 1,1,7
60 DO
70 A=POT(1):REM GET POSITION (X) OF PADDLE 1
80 B=POT(2):REM GET POSITION (Y) OF PADDLE 2
90 PRINT A;B:REM PRINT VALUES
100 MOVSPR l,A,B:REM MOVE SPRITE 1 ACCORDING TO PADDLE VALUES
110 IF (A>255) OR (B>255) THEN BEGIN:REM CHECK FOR FIRE BUTTON
120 :
SOUND 2,64000,60,0,1000, 16000,3:REM FIRE
130 :
COLOR 0,3:REM CHANGE SCREEN COLOR
14 0 :
SLEEP 1 :REM DELAY
150 :
COLOR 0,1:REM CHANGE SCREEN COLOR BACK
160 BEND:REM END THE BEGIN/BEND STRUCTURE
170 LOOP:REM DO IT AGAIN

INPUT/OUTPUT GUIDE

LIGHT PEN
The light pen input latches the current screen position into a pair of registers (LPX,
LPY) on a low-going edge. The X position register 53267 ($D013) will contain the 8 MSB
of the X position at the time of transition. Since the X position is defined by a 512-state
counter (9 bits), resolution to two horizontal dots is provided. Similarly, the Y position
is latched in its register 53268 ($D014), but here 8 bits provide single raster resolution
within the visible display. The light pen latch may be triggered only once per frame, and
subsequent triggers within the same frame will have no effect. Therefore, you must take
several samples before turning the pen to the screen (three or more samples average),
depending upon the characteristics of your light pen. The following program is a light
pen draw routine in C128 mode:

10 REM Cl28 MODE LIGHT PEN DRAW ROUTINE

2 0 REM PLACE LIGHT PEN IN CONTROLLER PORT 1
30 COLOR 0,2:COLOR 4,2:COLOR l,l:REM SELECT SCREEN COLORS
40 GRAPHIC l,l:REM SELECT BIT MAP MODE
50 DO
60 :
X=PEN(0)
: REM GET HORIZONTAL COORDINATE
70 :
Y=PEN(1)
: REM GET VERTICAL COORDINATE
80 :
DRAW l,X,Y :REM PLOT POINT
9 0 LOOP :REM DO IT AGAIN
100

110
120
130
140

REM
REM
REM
REM

IF YOU LIKE THE DRAWING,

BREAK THE PROGRAM AND
SAVE IT AS A BINARY FILE
FROM $2000-$3FFF.

OUTPUT CONTROL T O
ALL DEVICES
Each peripheral device is identified by a device number, as listed in Table 12-3.

DEVICE

Keyboard
Datasette
Modem (RS232)
Screen
Printer
Disk Drive

DEVICE NUMBER

0
1
2
3
4 or 5
8,9,10,11

SECONDARY ADDRESSES

0,1,2
0
0,1
0,7,etc
2-14,15

Table 12-3. Device Numbers

Serial devices can be numbered 4 through 30, but they usually conform to the
above conventions. All devices can be accessed in a single OPEN statement by using
an integer variable:

393

394

COMMODORE 128

10 INPUT "SELECT DEVICE NUMBER";D%

20 INPUT "SELECT SECONDARY ADDRESS";S%
30 INPUT "NAME OF FILE OR CONTROL REGISTER";A$
40 OPEN 9,D%,S%,A$
50 GOSUB 80
60 CLOSE 9
70 END
80 REM PLACE SUBROUTINE HERE
9 0 RETURN

THE INPUT/OUTPUT
PINOUTS
THE SERIAL PORT
The Serial Port is a daisy ehain arrangement designed to let the Commodore 128 computer
communicate with more than one device, such as Commodore disk drives and printers.
Up to five devices can be connected at one time. The serial bus can transmit control
signals from the computer, send data onto the bus, and receive data from the bus. Data
or control signals are routed to the proper device by opening a specific bus address
ranging from 4 to 31. Typically, addresses 4 and 5 are reserved for printers, and
addresses 8 through 11 are for the disk drive.
Six lines are used in serial bus operationthree input and three output. The three
input lines bring data, control and timing signals into the computer. The three output
lines send data, control and timing signals from the computer to the external devices.
See Hardware Specifications (Chapter 16) for details on the C128 serial bus protocol.
SERIAL I/O
PIN

1
2
3
4

5
6

TYPE

SERIAL
GND
SERIAL
SERIAL
SERIAL
RESET

SRQIN
ATN IN/OUT
CLK IN/OUT
DATA IN/OUT

Figure 12-5. Serial Port Pinouts

USER PORT (RS-232 CHANNEL)

The User Port (RS-232 Channel) connects the Commodore 128 to the outside
world, such as another Commodore computer. It is directly connected to the 6526 CIA
# 1 chip. Figure 12-6 shows the User Port pinouts. Table 12^4 defines the pinouts.

INPUT/OUTPUT GUIDE

1 2

7 8

10 11 12

B C

L M N

Figure l 2 - 6 . User Port Pinouts

PIN
TOP SIDE

DESCRIPTION

1
2
3

GROUND
+ 5V
RESET

4
5
6
7
8
9

CNT1
SP1
CNT2
SP2
PC2
SERIAL
ATN IN
9 VAC + phase
9 VAC-phase
GROUND

10
11
12

NOTES

(100 mA MAX.)
By grounding this pin, the Commodore 128 will do
a cold start, resetting completely. The pointers to
a BASIC program will be reset, but memory will
not be cleared. This is also a RESET output for
the external devices.
Serial port counter from CIA-1 (see CIA specs).
Serial port from CIA-1 (see 6526 CIA specs).
Serial port counter from CIA-2 (see CIA specs).
Serial port from CIA-1 (see 6526 CIA specs).
Handshaking line from CIA-2 (see CIA specs).
This pin is connected to the ATN line of the serial
bus.
Connected directly to the Commodore 128 transformer (100 mA Max.).

BOTTOM SIDE

A
B
C
D
E
F
H
J
K
L
M
N

GROUND
FLAG2
PB0
PB1
PB2
PB3
PB4
PB5
PB6
PB7
PA2
GROUND

The Commodore 128 gives you control over Port

B on CIA chip 1. Eight lines for input or output
are available, as well as two lines for handshaking
with an outside device. The 1/0 lines for Port B
are controlled by two locations. One is the Port
itself, and is located at 56577 ($DD01 HEX).
Naturally you PEEK it to read an INPUT, or
POKE it to set an OUTPUT. Each of the eight
I/O lines can be set up as either an INPUT or an
OUTPUT by setting the Data Direction Register
properly.

Table l 2 ^ . User Port Pin Descriptions

The Data Direction Register has its location at 56579 ($DD03 hex). Each of the
eight lines in the port has a bit in the 8-bit Data Direction Register (DDR) that controls
whether that line will be an input or an output. If a bit in the DDR is a 1, the

395

396

COMMODORE 128

corresponding line of the port will be an output. If a bit in the DDR is a 0, the
corresponding line of the port will be an input. For example, if bit 3 of the DDR is set to 1,
then line 3 of the port will be an output. If the DDR is set like this:
BIT # : 7 6 5 4 3 2 1 0
VALUE: 0 0 1 1 1 0 0 0
lines 5, 4 and 3 will be outputs since those bits are l ' s . The rest of the lines will be
inputs, since those lines are 0's.
To PEEK or POKE the User Port, it is necessary to use both the DDR and the port
itself.
Remember that the PEEK and POKE statements need a number from 0 to 255.
The numbers given in the example must be translated into decimal before they can be
used. The value would be:
2 5 + 2 4 + 2 3 = 32 + 16 4- 8 = 56
Notice that the bit number for the DDR is the same number that is equal to 2 raised to a
power to turn the bit value on.

(16 = 2 | 4 = 2 x 2 x 2 x 2 , 8 = 2 | 3 = 2 x 2 x 2 )
The two other lines, flagl and PA2, are different from the rest of the User Port.
These two lines are mainly for handshaking, and are programmed differently from
port B.
Handshaking is needed when two devices communicate. Since one device may run
at a different speed than another device, it is necessary to give each device some way of
knowing what the other device is doing. Even when the devices are operating at the
same speed, handshaking is necessary to communicate when data is to be sent, and if it
has been received. The flagl line has special characteristics that make it well suited for
handshaking.
Flagl is a negative-edge-sensitive input that can be used as a general-purpose
interrupt input. Any negative transition on the flag line will set the flag interrupt
bit. If the flag interrupt is enabled, this will cause an Interrupt Request. If the
flag bit is not enabled, it can be polled from the Interrupt Register under program control.
PA2 is bit 2 of port A of the CIA. It is controlled like any other bit in the port.
The port is located at 56576 ($DD00). The Data Direction Register is located at 56578
($DD02).
For more information on the 6526, see the hardware chapter.

THE COMPOSITE
VIDEO CONNECTOR
This DIN connector supplies direct audio and composite video signals. These can
be connected to the Commodore monitor or used with separate components. This is the
40-column output connector. Figure 12-7 shows the pinouts for the composite video
connector. Table 12-5 describes the pinouts.

INPUT/OUTPUT GUIDE

PIN

1
2
3
4
5
6
7
8

TYPE

NOTE

LUM/SYNC
GND
AUDIO OUT
VIDEO OUT
AUDIO IN
COLOR OUT
NC
NC

Luminance/SYNC output

Composite signal output

Chroma signal output
No connection
No connection

Table 12-5. Composite Video Connector Pin Descriptions

THE RGBI
VIDEO CONNECTOR
The RGBI video connector is a 9-pin connector that supplies an RGBI (Red/Green/Blue/
Intensity) signal. This is the 80-column output. Figure 12-8 shows the RGBI pinouts.
Table 12-6 defines the RGBI pinouts.

Figure 12-8. RGBI Connector Pinouts

397

398

COMMODORE 128

SIGNAL

PIN

Ground
Ground
Red
Green
Blue
Intensity
Monochrome
Horizontal Sync
Vertical Sync

1
2
3
4
5
6
7
8
9

Table l 2 ^ . RGBI Connector Pin Descriptions

THE CASSETTE CONNECTOR

A 1530 Datassette recorder can be attached to the cassette port to store programs and
information. Figure 12-9 shows the cassette port pinouts. Table 12-7 describes the
pinouts.
1

Figure 12-9. Cassette Port Pinouts

PIN

TYPE

A-1
B-2
C-3
D-4
E-5
F-6

GND
+ 5V
CASSETTE
CASSETTE
CASSETTE
CASSETTE

MOTOR
READ
WRITE
SENSE

Table 12-7. Cassette Port Pin Descriptions

THE CONTROLLER PORTS

There are two controller ports, numbered 1 and 2. Each controller port can accept a
joystick, mouse or game controller paddle. A light pen can be plugged only into Port 1, the
port closest to the front of the computer. Use the ports as instructed with the software.
Figure 12-10 shows the Controller Port pinouts. Table 12-8 describes the pinouts.

INPUT/OUTPUT GUIDE

Figure 12-10. Controller Port Pinouts

C O N T R O L PORT 2

CONTROL PORT I
PIN

1
2
3
4
5
6
7
8
9

TYPE

NOTE

JOYAO
JOYAl
JOYA2
JOYA3
POT AY
BUTTON A/LP
+ 5V
MAX. 50mA
GND
POT AX

PIN

1
2
3
4
5
6
7
8
9

TYPE

JOYBO
JOYBl
JOYB2
JOYB3
POT BY
BUTTON B
+ 5V
GND
POT BX

NOTE

MAX. 50mA

Table l 2 ^ . Controller Port Pin Descriptions

THE EXPANSION PORT

Vhe expansion port connector is a 44-pin female edge connector accessing the computer's address and data buses. It accepts Commodore's preprogrammed game and utility
software cartridges. As a parallel port, it can accept Commodore's IEEE peripherals
with an IEEE interface for controlling instrumentation and other devices. RAM expansion modules will also connect to this port and accept the BASIC commands of FETCH,
STASH and SWAP.
x
Figure 12-11 shows the expansion port pinouts. Table 12-9 describes the pinouts.
22 21 20 1918 1 7 * 6 1 5 14 13 12 11 10 9 0 7 6 5 4 3 2 1

Z v * *r V u T s R p N M L K J H F E D C B A
(view of port from the back of the C128)

Figure l 2 - l I. Expansion Port Pinouts

399

400

COMMODORE 128

PIN

TYPE

PIN

TYPE

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

GND
4-5V
+ 5V
IRQ
R/W
Dot Clock
I/O 1
GAME
EXROM
1/0 2
ROML
BA
DMA
D7
D6
D5
D4
D3
D2
D1
D0
GND

A
B
C
D
E
F
H
J
K
L
M
N
P
R
S
T
U
V
w
X
Y
Z

GND
ROMH
RESET
NMI
S 02
A15
A14
A13
A12
All
A10
A9
A8
A7
A6
A5
A4
A3
A2
A1
A0
GND

Table 12-9. Expansion Port Pin Descriptions

J_3
THE
COMMODORE 128
OPERATING
SYSTEM

401

402

COMMODORE 128

The Commodore 128 operating system controls, directly or indirectly, all functions of
your computer. The Commodore 128 operating system is housed in a ROM chip called
the Kernal, which contains about 16K of machine language instructions. These instructions make up the routines that control all the machine's functionseven the ones you
take for granted. For instance, the Kernal controls all input and output functions,
including receiving the characters from the keyboard when you type, sending text to a
printer, and displaying graphics and text on the screen. Every task performed by the
computer other than application program activities is controlled by the Kernal. The
Kernal even manipulates and executes the application programs you load or type into
your computer's memory.

TAKING FULL ADVANTAGE OF THE

COMMODORE 28 OPERATING SYSTEM
The 16K of operating system instructions contained in the Kernal are available for use
with your own programs. Instead of "reinventing the w h e e l " and duplicating code, you
can call (that is, use) these Kernal routines in your own programs. You do this through
the Kernal Jump Table, which consists of a series of ROM entry points in which you
can call machine language routines already available in the Commodore 128 Kernal. By
calling these routines, which handle the most fundamental functions of the computer,
you avoid duplicating code. This helps you utilize your computer to its fullest potential.
The Kernal Jump Table also facilitates compatibility. If the Commodore 128
operating system is modified or upgraded, which happens frequently in the microcomputer industry, the entry points in the jump table are revised to reflect address changes
of Kernal subroutines. The key to keeping applications programs compatible from one
version of the operating system to another is to enter the operating system through the
Kernal Jump Table. Instead of jumping directly to a subroutine (JSR), use the Kernal
Jump Table as the entry point, since it contains the correct address vector to the
specified routine, regardless of the version of the Kernal being used. If you always enter
the operating system routines from the Kernal Jump Table, the address of the desired
routine will always be reached. On the other hand, if you bypass the Kernal Jump Table
and jump directly to the address where you think the routine resides, you may cause an
error, because the starting point of the desired routine may have changed from one
version of the operating system to another.

THE COMMODORE 128 OPERATING SYSTEM

HOW T O USE (CALL)

THE KERNAL ROUTINES IN
YOUR O W N PROGRAMS
Most of the system subroutines require specific parameters, or values, which must be
loaded into the accumulator, X or Y index registers. Some Kernal subroutines require
additional preparatory routines to be called before invoking the specific target routine.
Each Kernal subroutine terminates with an RTS instruction that tells the microprocessor
to return from the subroutine. Many of the Kernal routines return values that are placed
in the accumulator, X or Y registers. Some even return error codes in the status register,
which can be acted on in your applications program.
Here is the procedure for calling a Kernal subroutine:
1. Place the necessary preparatory values in the required registerseither the A,
X or Y registers.
2. Enable the appropriate system configuration. For example, if the routine
requires the Kernal to be present, invoke either configuration 12, 13, 14 or 15,
since these make the Kernal available. Bank 15 is the default configuration.
3. Call the subroutine with the JSR instruction, using the address of the jump
vector as shown in the Kernal Jump Table in Figure 13-1.
For example, the starting address of the routine ACPTR is stored, starting
in location $FFA5. Actually, the operation code (opcode) for the JMP instruction is stored at location $FFA5 and the address of the entry point of the
routine is stored at locations $FFA6 and $FFA7. What really happens is that
the JSR instruction in your application program transfers control to the jump
table address ($FFA5, for example); then the JMP instruction at $FFA5 jumps
to the subroutine at the address specified in locations $FFA6 and $FFA7. In
other words, when you issue a JSR instruction to the Kernal Jump Table, you
actually perform two jumps: one (JSR) to the jump table, and then a second
jump (JMP) to the actual starting address of the routine.
The routine terminates with an RTS instruction that is already part of the
Kernal subroutine. Your application program resumes with the instruction
immediately following the JSR instruction.
4. Upon return from the subroutine, check the status register for any error conditions. If
an error condition is present, take precautions in your application
program to handle the error and act on the value of the status register.
Figure 13-1 is the C128 system vector and jump table that includes the
name, address and function description of the operating system Kernal routines.

403

404

COMMODORE 128

C128 SYSTEM VECTORS

1. $FFFB
2. $FFFA
3.
4.

$FFFC
$FFFE

SYSTEM
NMI

;operating system vector (RAMI)

;processor NMI vector

RESET
IRQ

;processor RESET vector

;processor IRQ/BRK vector

CBM S T A N D A R D KERNAL JUMP TABLE CALLS

1. $FF81
2. $FF84
3. $FF87

JMP CINT
JMP IOINIT
JMP RAMTAS

;init screen editor and devices

;init I/O devices
;init RAM and buffers

4.
5.
6.

$FF8A
$FF8D
$FF90

JMP RESTOR
JMP VECTOR
JMP SETMSG

;init indirect vectors (system)

;init indirect vectors (user)
;kernal messages on/off

7.
8.
9.

$FF93
$FF96
$FF99

JMP SECND
JMP TKSA
JMP MEMTOP

;serial: send SA after LISTN

;serial: send SA after TALK
;set/read top of system RAM

10.
11.
12.

$FF9C
$FF9F
$FFA2

JMP MEMBOT
JMP KEY
JMP SETTMO

;set/read bottom of system RAM

;scan keyboard
;(reserved)

13.
14.
15.

$FFA5 JMP ACPTR

$FFA8 JMP CIOUT
$FFAB JMP UNTLK

;serial: byte input

;serial: byte output
;serial: send untalk

16.
17.
18.

$FFAE JMP UNLSN

$FFB1 JMP LISTN
$FFB4 JMP TALK

;serial: send unlisten

;serial: send listen
;serial: send talk

19.
20.
21.

$FFB7 JMP READSS

$FFBA JMP SETLFS
$FFBD JMP SETNAM

;read I/O status byte

;set channel LA, FA, SA
;set filename pointers

22.
23.
24.

$FFC0
$FFC3
$FFC6

;open logical file

;close logical file
;set input ehannel

25.
26.
27.

$FFC9 JMP (ICKOUT)

$FFCC JMP (ICLRCH)
$FFCF JMP (IBASIN)

;set output ehannel

;restore default channels
;input from channel

28.
29.
30.

$FFD2
$FFD5
$FFD8

;output to ehannel
;load from file
;save to file

31.
32.
33.

$FFDB JMP SETTIM

$FFDE JMP RDTIM
$FFE1 JMP (ISTOP)

JMP (IOPEN)
JMP (ICLOSE)
JMP (ICHKIN)

JMP (IBSOUT)
JMP LOAD
JMP SAVE

;set internal clock

;read internal clock
;scan STOP key

THE COMMODORE 128 OPERATING SYSTEM

34.
35.
36.

$FFE4 JMP (IGETIN)

$FFE7 JMP (ICLALL)
$FFEA JMP UDTIM

;readbuffereddata
;close all files and channels
;increment internal clock

37.
38.
39.

$FFED JMP SCRORG

$FFF0 JMP PLOT
$FFF3 JMP IOBASE

;get current screen window size

;read/set cursor position
;read base address of I/O block

N E W C I 2 8 K E R N A L JUMP T A B L E CALLS

1.

$FF47

JMP SPIN SPOUT

;setup fast serial ports for I/O

2.
3.
4.

$FF4A
$FF4D
$FF50

JMP CLOSE ALL

JMP C64MODE
JMP DMA CALL

;close all files on a device

;reconfigure system as a C64
;send command to DMA device

5.
6.
7.

$FF53
$FF56
$FF59

JMP BOOT CALL

JMP PHOENIX
JMP LKUPLA

;boot load program from disk

;init function cartridges
;search tables for given LA

8.
9.
10.

$FF5C
$FF5F
$FF62

JMP LKUPSA
JMP SWAPPER
JMP DLCHR

;search tables for given SA

;switch between 40 and 80 columns
;init 80-col character RAM

11.
12.
13.

$FF65
$FF68
$FF6B

JMP PFKEY
JMP SETBNK
JMP GETCFG

;program a function key

;set bank for I/O operations
;Iookup MMU data for given bank

14.
15.
16.

$FF6E
$FF71
$FF74

JMP JSRFAR
JMP JMPFAR
JMP INDFET

;gosub in another bank

;goto another bank
;LDA (fetvec),Y from any bank

17.
18.
19.

$FF77
$FF7A
$FF7D

JMP INDSTA
JMP INDCMP
JMP PRIMM

;STA (stavec),Y to any bank

;CMP (cmpvec),Y to any bank
;print immediate utility

Figure 13 I. User-Callable Kernal Routines

Figure 13-2 lists the conventions used in the description of each Kernal subroutine. The figure is followed by descriptions of the C128 system vectors and Kernal
subroutines. Included in each description are the subroutine name, call address, preparatory routines needed (if any), the registers affected, the error codes associated with each
routine, how to use them and an example of each kernal subroutine call.

405

406

COMMODORE 128

USER CALLABLE
KERNAL ROUTINE CONVENTIONS
Call Address: This is the call address of the Kernal routine, given in hexadecimal.
Function Name: Name of the Kernal routine.
Register: Registers, memory and flags listed under this heading are used to pass
parameters to and from the Kernal routines.
Preparatory Routines: Certain Kernal routines require that data be set up by preparatory routines before the target routine can be called. The necessary routines are
listed here.
Error Returns: A return from a Kernal routine with the carry set indicates an error
was encountered in processing. The accumulator will contain the number of the
error.
Error Codes: Below is a list of error messages that can occur when using the
Kernal routines. If an error occurs during a Kernal routine, the carry bit of the
accumulator is set, and the number of the error message is returned in the
accumulator.

NOTE: Some Kernal I/O routines do not use these codes for error
messages. Instead, errors are identified using the Kernal READST routine.

NUMBER

0
1
2
3
4
5
6
7
8
9
41

MEANING

Routine terminated by the STOP key

Too many open files
File already open
File not open
File not found
Device not present
File is not an input file
File is not an output file
File name is missing
Illegal device number
File read error

Registers Affected: All registers, memory and flags used by the Kernal routine are
listed here.
Examples: An example of each Kernal routine is listed.
Description: A short explanation of the function of the Kernal routine is given here.
Figure 13-2. User-Callable Kernal Routine Conventions

THE COMMODORE 128 OPERATING SYSTEM

C128 SYSTEM VECTORS

The vectors listed below, with the exception of the SYSTEM vector, are located not
only in system ROM but in each RAM bank. The beginning and end of the system
interrupt handlers are found in the top page ($FFxx) of all memory configurations as
well. The reason is simple: An interrupt can occur anytime, from any memory configuration. The registers and memory configuration must be preserved prior to bringing the
operating system into context to process the interrupt. They must similarly be restored
before control is finally returned to the interrupted code. Note that the system vectors
are indirect jumps, and are not usually called by the user since they terminate with an
RTI instruction, not an RTS instruction. In other words, they process interrupted events,
not subroutine calls.
1. $FFF8 SYSTEM ;operating system vector (RAMI)
The SYSTEM vector and accompanying KEY string provide applications software
with a means of regaining system control after a hardware reset. With this vector,
software may be protected from an otherwise unrecoverable situation. The KEY
string provides the distinction between a " w a r m " reset and a " c o l d " power-up. If
the system has just powered up, the KEY string is missing and thus the SYSTEM
vector is invalid; the CBM KEY is installed and the SYSTEM vector is set to C128
mode. If the system was reset (i.e., KEY was found), the SYSTEM vector is
moved to common RAM at $02 and an indirect JMP is performed. In most cases,
the user need only call IOINIT beore resuming control. The layout in RAM-1 is:
$FFF5
$FFF6
$FFF7
$FFF8
$FFF9

'C'
'B'
'M'
SYSTEM
SYSTEM

($43)
($42)
($4D)
vector low
vector high

For example, suppose a programmer set out to do some heavy-duty "hacking"

using the built-in Monitor. Fully realizing the likelihood of losing control in a crash,
the programmer could redirect the SYSTEM vector to the Monitor itself and thus
regain control with minimal RAM loss, simply by pressing the RESET button. To
accomplish this, the programmer would enter:
a.
b.

>lFFF8
A 1300

00
JSR
JMP

13
$FF84
$B000

:aimSYSTEMto$1300
:callIOINIT
:call Monitor

2. $FFFA NMI ;processor NMI vector

The Non-Maskable Interrupt (NMI) vector is activated whenever the processor
NMI pin detects a negative edge. There are two possible sources of NMI's under
normal conditions: the RESTORE key and RS-232 I/O. In the event of an
NMI, the operating system disables IRQ's, saves the registers and current memory

407

408

COMMODORE 128

configuration on the stack, brings the system configuration (ROM's, I/O, RAM0)
into context, and executes an indirect jump through the RAM vector located at
$318. The system NMI handler clears the ICR register of CIA-2, from which it
determines the source of the interrupt. If it is from timer A, control passes to the
RS-232 transceiver. If not, the RESTORE key is assumed, and for safety,
the CBM convention of requiring the STOP key to be simultaneously depressed is checked. If the STOP key is depressed, all system indirect vectors are
restored, IOINIT and CINT are called, and the SYSTEM_VECTOR (do not
confuse with the SYSTEM vector!) is taken. Control is returned upon restoration of
the registers and memory configuration. NMI's may be disabled by causing an initial
NMI from timer A, but never reading the ICR to clear it, thus keeping the NMI
signal grounded.
Application software can intercept an NMI event by modifying either of the
two RAM vectors mentioned above. The NMI indirect vector at $318 in common
RAM will pass control whenever an NMI occurs. The SYSTEM_VECTOR, located
at $A00 in RAM0, will pass control after STOP/RESTORE is detected and handled.
For example, suppose a situation similar to the one illustrated previously for
the SYSTEM vector occurs. To return control to the Monitor whenever STOP/
RESTORE is detected, enter:
a.

>A00

00 B0 :aim SYSTEM_VECTOR to Monitor

Similarly, to perform an action anytime an NMI occurs (e.g., RESTORE

alone), use the NMI indirect. For example, increment the VIC border color whenever you press R E S T O R E
(or cause any other NMI). Enter:
a.
b.

> 3 1 8 00 13
A 1300 INC $D020
JMP $FF33

:aim indirect to $1300

:change border color
:return from interrupt

3. $FFFC RESET ;processor RESET vector

The processor RESET vector is activated whenever the system RESET signal is
low. It is low at power-up, and is pulled low by pressing the RESET button. This
signal effects not only the processor but most of the I/O devices found in the
system. In fact, RESET is the one processor control signal that is shared between
the two processors (8502 and Z80) of the C128. The Z80 gains initial (default)
control of the system while the 8502 is held in a waiting state. When the 8502
finally starts after a reset, the Kernal initialization routine START always receives
control and immediately performs the following actions:
1.
2.
3.
4.
5.
6.

Brings the system map into context.

Disables IRQ's.
Resets the processor stack pointer.
Clears decimal mode.
Initializes the MMU.
INSTALLS the Kernal RAM code.

THE COMMODORE 128 OPERATING SYSTEM

Up to this point there is no provision for user code. The next two routines in the
initialization path actually look for installed user code:
7. SECURE: Check and initialize the SYSTEM vector.
8. POLL: Check for a ROM cartridge.
POLL first scans for any installed C64 cartridges. They are recognized by
either the GAME or EXROM signal being pulled low. If so, G 0 6 4 is executed
(see the Kernal jump entry for details). Polling for C64 cartridges is actually
redundant at this point since the Z80 processor, which powers up initially, did this
already. POLL then scans for installed C128 cartridges and function ROM's. They
are recognized by the existence of the O key in any of the four function ROM
slots (two internal, two external) and are polled in the order external low (16 or
32KB), external high (16KB), internal low (16 or 32KB), internal high (16KB).
The entire format is:
$x000
$x003
$x006
$x007
where

^ cold start entry

^> warm start entry (unused)
^ ID. ($01-$FF)
^ " C B M " key string
x = $8 or $C.

The ID of any C128 cartridge found is entered into the Physical Address Table
(PAT) located at SACl-SAC4. ID's must be non-zero. Cartridges may recognize
each other by examining the PAT for particular ID's. An ID of 1 indicates an
auto-start cartridge, and its cold start entry will be called immediately. All others
will be called later (see PHOENIX jump), as will any auto-starters that RTS is to
POLL. A cartridge can determine where it is installed by examining CURBNK,
located at $ACO. Because it is possible for a cartridge to be called with interrupts
enabled, the following diversion from the above format is recommended (the warm
start entry is never called by the system):
$x000
$x001
$x004
$x005

SEI
JMP STARTUP
NOP
NOP

The balance of the C128 initialization is:

9.
10.
11.
12.
13.
14.
15.

IOINIT: Initialize I/O devices.

Check for STOP AND O keys.
RAMTAS: Initialize system RAM.
RESTOR: Initialize system indirects.
CINT: Initialize video displays.
Enable IRQ's (except foreign systems).
Dispatch.

IOINIT is perhaps the major function of the Reset handler. It initializes both CIA's
(timers, keyboard, serial port, user port, cassette) and the 8502 port (keyboard,

409

410

COMMODORE 128

cassette, VIC bank). It distinguishes a PAL system from an NTSC one and sets
PALCNT ($A03) if PAL. The VIC, SID and 8563 devices are initialized, including
the downloading of character definitions to 8563 display RAM (if necessary). The
system 60Hz IRQ source (the VIC raster) is started. IOINIT is callable by the user
via the jump table.
During initialization, the user may press certain keys as a means of selecting
an operating mode. One key checked is the Commodore key C* , indicating C64
mode is desired. While this key was scanned much earlier by the Z80 to speed
the switchover to C64 mode, there is a redundant check for it here. The only other
key scanned at this time is the S T O P key, which signals a request by the user
to power up into the Monitor utility. Note that control does not pass from the
initialization process at this point; the Kernal needs to know if RAMTAS should be
skipped. Only if the STOP key is depressed and this was a " w a r m " reset
(vs. " c o l d " power-up) can RAMTAS be skipped.
RAMTAS clears all page-zero RAM, allocates the cassette and RS-232
buffers, sets pointers to the top and bottom of system RAM (RAM-0), and
installs the SYSTEM_VECTOR (discussed earlier under NMI) that points to BASIC cold start. Lastly it sets a flag, DEJAVU ($A02), to indicate to other routines
that system RAM has been initialized. This is the difference between a " c o l d "
and a " w a r m " system. If DEJAVU contains $A5, the system is " w a r m " and
SYSTEM_VECTOR is valid. Many programmers debugging code need to recover
from a system hang or crash via R E S E T but do not want RAM cleared. This
is why the STOP key is scanned, RAMTAS is skipped, and the Monitor
(rather than BASIC) is selected. RAMTAS is callable by the user via the jump
table.
RESTOR initializes the Kernal indirect vectors. This must be done before
many system routines will function. Applications that complement the operating
system via " w e d g e s " must install them after they are initialized. RESTOR is user
callable from the jump table (see also the VECTOR call).
CINT is the Editor's initialization routine. Both 40- and 80-column display
modes are prepared, editor indirect vectors installed, programmable key definitions
assigned, and the 40/80 key scnaned for default display determination. CINT is also
a jump table entry.
Finally, the IRQ's are enabled and control is passed to either BASIC
initialization, G 0 6 4 code, or the ML Monitor. BASIC will call the Kernal
PHOENIX routine upon the conclusion of its initialization, which will call any
installed C128 cartridges (any ID) and attempt to auto-boot an application from
disk.
An initialization status byte, INIT_STATUS ($A04), marks the progress of
the initialization process. It is cleared automatically at the beginning of the Reset
code, and as specific stages are completed, a particular bit is set. The layout is:
B7 ^
B6 ^
B0 ^

8563 characters installed

CINT performed
BASIC initialized

THE COMMODORE 128 OPERATING SYSTEM

Any IOINIT calls, including Reset, will not result in 8563 character RAM initialization if B7 is set. Similarly, CINT will not initialize the keyboard matrix lookup
tables and the programmable key definitions if B6 is set. This is how NMI's, for
example, can call IOINIT and CINT without destroying users' setups. Finally,
BASIC initialization must be complete before B0 is set. This determines whether
the IRQ handler, for example, should call the BASIC IRQ routines. Note that the
following sequence of events should be performed for a BASIC programmer to
recover from a crash via R E S E T
1.
2.
3.
4.
5.

Hold down S T O P key to enter Monitor.

Pressandrelease RESET button.
Release STOP key.
Enter: > A 0 4 C1 :re-enable BASIC IRQ.
Enter: X
:exit Monitor to BASIC.

This sequence is necessary because INIT_STATUS was cleared by the reset, and
the BASIC initialization was skipped, leaving B0 reset. If B0 had not been set,
BASIC IRQ routines such as SOUND, PLAY, and SPRITE handlers would not
have functioned, usually resulting in an apparent " h a n g . "

4. $FFFE IRQ

;processor IRQ/BRK vector

This hardware vector is taken whenever the IRQ pin of the processor is pulled low,
or the processor executes a BRK instruction. For proper operation an IRQ must
occur sixty times every second [NTSC (60Hz) presents no problems, but adjustments have to be made for PAL (50Hz) systems]. The usual source of IRQ's in the
C128 is the VIC raster, which is unleashed during system initialization by IOINIT.
In the event of an IRQ or BRK, the operating system saves the registers and current
memory configuration on the stack and brings the system bank (ROM's, I/O,
RAM0) into context. The processor status at the time of interruption is then read
from the system stack to determine if the interrupt was an IRQ or a BRK. The C128
uses the following code to accomplish this:
TSX
;get stack pointer
LDA $105,X ;retrieve processor status
AND # $ 1 0
;examine BRK flag
If the BRK flag is set, control passes to the ML Monitor through the BRK
indirect vector at $316, which usually points to the Monitor BREAK entry. Here
the program counter (PC), processor status, registers, memory configuration and
stack pointer are retrieved and displayed.
If the BRK flag is 0, an IRQ is assumed and control passes through the IRQ
indirect vector at $314, normally to the system IRQ handler. The following processes
are then performed in the order shown:

411

412

COMMODORE 128

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.

IRQ's disabled.
Editor: split screen handler.
Editor: clear VIC raster IRQ.
IRQ's enabled.
Editor: keyboard scan.
Editor: VIC cursor blink.
Kernal: " j i f f i e " clock.
Kernal: cassette switches.
Kernal: clear CIA-1 ICR.
BASIC: sprites, sounds, etc.
Returnfrominterrupt.

As indicated in the preceding description, the C128 operating system uses the
IRQ heavily. In particular, the Editor split screen handler has rather strict requirements that programmers must recognize and accommodate. An all-text screen or a
fully bit mapped screen presents no particular problem, but a split text and bit map
screen requires twice the IRQ frequency (two every sixtieth of a second). Thus, the
Editor (and consequently, IRQ-dependent applications) must distinguish between
the " m a i n " 60Hz IRQ and the " m i d d l e " IRQ. Only during the main IRQ will all
the actions listed above be performed; the middle IRQ is only used by the Editor to
split the screen. The Editor IRQ routine sets the carry flag to designate a main IRQ.
Moreover, there is no margin in the timing requirements of a split screen. Programmers should note the way the Editor uses the VIC during IRQ's and avoid direct VIC
I/O if the Editor screen operations are enabled. There is a flag byte called GRAPHM,
located at $D8, which can be set to $FF to disable the Editor's use of the VIC.
The Editor is also responsible for scanning the C128 keyboard. Programmers
should note that SCNKEY has two indirect jumps, KEYLOG and KEYPUT, it
takes during its execution. The keyboard is controlled via CIA-1 PRA, PRB, VIC
register # 4 7 (extended key matrix), and the 8502 port (bit 6 = CAPS LOCK). The
SCNKEY routine is callable from the jump table.
The balance of the IRQ routines up to calling BASIC are self-explanatory.
The Kernal software clock is maintained by UDTIM, which is in the jump table.
The IRQ processing makes one last call to BASIC_IRQ ($4006), but only if
INIT_STATUS bit 0 is set indicating BASIC is ready to handle IRQs (this was
discussed earlier in the RESET section). BASIC_IRQ is a heavy user of the VIC
and SID, and the same precautions should be taken regarding direct VIC and SID
I/O as with the Editor. BASIC_IRQ also utilizes a hold-off byte called I R Q _ W R A P
_ F L A G . It is normally used by the system to block IRQ-ed IRQ calls, but can be
set by the user with the effect of disabling the BASIC_IRQ handler. Alternatively
you could clear bit 0 of the INIT_STATUS byte as mentioned above and achieve
the same result.
The use of the IRQ indirect ($314) by an application usually requires more
care than most other wedges for several reasons. The likelihood of an IRQ occurring while the wedge is being installed is greater, there exists the possibility that the
user or some other software has already wedged the vector, and usually it is

THE COMMODORE 128 OPERATING SYSTEM

desirable for the system IRQ functions to continue normally (e.g., keyscan) as
opposed to replacing them totally with our own (as we did with the NMI examples).
The following examples accomplish these objectives as well as masking out all but
the main IRQ. First we must install our IRQ handler. This example converts the
4 0 / 8 0 key into a SLOW/FAST key:

A 1302 BIT
BPL
LDA
ORA
STA
LDA
AND
LDX
BIT
BPL
ORA
DEX
131E STX
STA
1324 JMP

$D011
$1324
$D505
#$80
$D505
$D011
#$6F
#$01
$D505
$131E
#$10
$D030
$D011
($1300)

;test VIC reg 17

;branch if wrong IRQ
;preparation
;b7 of MMU MCR
;set for input
;assume FAST setup
;blank VIC (RC8 = 0)
;2MHz
;test 4 0 / 8 0 key
;branch if down (FAST)
;unblank VIC
;lMHz
;set speed
;set blank bit
;continue system IRQ

Now we need a small routine to actually wedge our code into the system IRQ. The
following code saves the current IRQ vector for our handler above to exit through
and substitutes a pointer to our code:

A 1400 SEI
LDA
STA
LDA
STA
LDA
STA
LDA
STA
CLI
RTS

$314
$1300
$315
$1301
#$02
$314
#$13
$315

;prevent interruptions
;get current IRQ lsb
;and save it
;get current IRQ msb
;and save it
;get our IRQ lsb
;and substitute it
;get our IRQ msb
;and substitute it
;re-enable IRQ processing

Enable the wedge by typing J 1400, that's all there is to it. Depressing the
Locking 40/80 key now puts you in FAST mode; releasing it SLOWS you
down, and the keyscan, etc., continues to function. Note, however, that on this

413

414

COMMODORE 128

split screen our code throws off the timing, making for an unattractive display.
There are really only three things to watch out for when toying with the C128
system IRQ: First, be sure to keep the raster compare value on-screen to keep the
IRQ's happening (the best way is to keep RC8 zero as in example above); second,
never attempt to access the 8563 during an IRQ if there is any chance that it is in
use; finally, be sure the source of the IRQ is being cleared.

CBM STANDARD KERNAL CALLS

The following system calls make up the set of standard CBM system calls for the
Commodore 128 Personal Computer. Several of the calls, however, function somewhat
differently or may require slightly different setups than C64 mode. This was necessary
to accommodate specific features of the system, notably the 40/80 column windowing
Editor and banked memory facilities. As with all Kernal calls, the system configuration
(high ROM, RAM-0 and I/O) must be in context at the time of the call.

1. $FF81 CINT ;initialize screen editor and devices

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:

Memory:
Flags:

none
system map
none
none
.A used
.X used
.Y used
init Editor RAM
init Editor I/O
none

EXAMPLE:
SEI
JSR $FF81
CLI

;initialize screen editor

CINT is the Editor's initialization routine. Both 40- and 80-column display
modes are prepared, editor indirect vectors installed, programmable key definitions
assigned, and the 4 0 / 8 0 key scanned for default display determination. CINT
sets the VIC bank and VIC nybble bank, enables the character ROM, resets SID
volume, places both 40- and 80-column screens and clears them. The only thing it

T H E COMMODORE 128 OPERATING SYSTEM

does not do that pertains to the Editor is ^ 0 initialization, which is needed for IRQ's
(keyscan, VIC cursor blink, split screen modes), key lines, screen background
colors, etc. (see IOINIT). Because CINT updates Editor indirect vectors that are
used during IRQ processing, you should disable IRQ's prior to calling it. CINT
utilizes the status byte INIT_STATUS ($A04) as follows:
$A04 bit 6 = 0 ^
1 ^

Full initialization.
(set INIT_STATUS bit 6)
Partial initialization.
(not key matrix pointers)
(not program key definitions)

CINT is also an Editorjump table entry ($C000).

2. $FF84 IOINIT ;init I/O devices

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:

Memory:
Flags:

none
system map
none
none
.A used
.X used
.Y used
initialize I/O
none

EXAMPLE:
SEI
JSR $FF84
CLI

;initialize system I/O

IOINIT is perhaps the major function of the Reset handler. It initializes both
CIA's (timers, keyboard, serial port, user port, cassette) and the 8502 port (keyboard, cassette, VIC bank). It distinguishes a PAL system from an NTSC one and
sets PALCNT ($A03) if PAL. The VIC, SID and 8563 devices are initialized,
including the downloading of character definitions to 8563 display RAM (if necessary). The system 60Hz IRQ source, the VIC raster, is started (pending IRQs are
cleared). IOINIT utilizes the status byte INIT_STATUS ($A04) as follows:
$A04 bit 7 = 0 ^
= 1 ^

Full initialization.
(set INIT_STATUS bit 7)
Partial initialization.
(not 8563 character definitions)

415

416

COMMODORE 128

You should be sure IRQ's are disabled before calling IOINIT to avoid interrupts
while the various I/O devices are being initialized.

3. $FF87 RAMTAS ;init RAM and buffers

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:

Memory:
Flags:

none
system map
none
none

.A used
.X used
.Y used
initializes RAM
none

EXAMPLE:
JSR $FF87

;initialize system RAM

RAMTAS clears all page-zero RAM, allocates the cassette and RS-232
buffers, sets pointers to the top and bottom of system RAM (RAM 0) and points
the SYSTEM_VECTOR ($A00) to BASIC cold start ($4000). Finally, it sets a
flag, DEJAVU ($A02), to indicate to other routines that system RAM has been
initialized and that the SYSTEM_VECTOR is valid. It should be noted that the
C128 RAMTAS routine does not in any way test RAM.

4. $FF8A RESTOR ;init Kernal indirects

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:

Memory:
Flags:

none
system map
none
none

.A used
.X used
.Y used
Kernal indirects restored
none

THE COMMODORE 128 OPERATING SYSTEM

EXAMPLE:
SEI
JSR $FF8A
CLI

;restore Kernal indirects

RESTOR restores the default values of all the Kernal indirect vectors from
the Kernal ROM list. It does not affect any other vectors, such as those used by the
Editor (see CINT) and BASIC. Because it is possible for an interrupt (IRQ or NMI)
to occur during the updating of the interrupt indirect vectors, you should disable
interrupts prior to calling RESTOR. See also the VECTOR call.

5. $FF8D VECTOR ;init or copy indirects

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:
Memory:
Flags:

.X = adr (low) of user list

.Y = adr (high) of user list
system map
.C = 0 ^> load Kernal vectors
.C = 1 ^> copy Kernal vectors
none

.A used
.Y used
as per call
none

EXAMPLE:
LDX # s a v e _ l o
LDY # s a v e _ h i
SEC
JSR $FF87

;copy indirects to " s a v e '

VECTOR reads or writes the Kernal RAM indirect vectors. Calling VECTOR with the carry status set stores the current contents of the indirect vectors to
the RAM address passed in the .X and .Y registers (to the current RAM bank).
Calling VECTOR with the carry status clear updates the Kernal indirect vectors
from the user list passed in the .X and .Y registers (from the current RAM bank).
Interrupts (IRQ and NMI) should be disabled when updating the indirects. See also
the RESTOR call.

417

418

COMMODORE 128

6. $FF90 SETMSG ;Kernal messages on/off

PREPARATION:
Registers:
Memory:
Flags:
Calls:

.A = message control
system map
none
none

RESULTS:
Registers:
Memory:
Flags:

none
MSGFLG ($9D) updated
none

EXAMPLE:
LDA # 0
JSR $FF90

;turn OFF all Kernal messages

SETMSG updates the Kernal message flag byte MSGFLG ($9D) that determines whether system error and/or control messages will be displayed. BASIC
normally disables error messages always and disables control messages in Run
mode. Note that the Kernal error messages are not the verbose ones printed by
BASIC, but simply the I/O ERROR # message that you see when in the Monitor,
for example. Examples of Kernal control messages are LOADING, FOUND, and
PRESS PLAY ON TAPE. The MSGFLG control bits are:
MSGFLG bit 7 - 1 ^ enable CONTROL messages
bit 6 = 1 ^> enable ERROR messages

7. $FF93 SECND ;serial: send SA after LISTN

PREPARATION:
Registers:
Memory:
Flags:
Calls:

.A = SA (secondary address)
system map
none
LISTN

RESULTS:
Registers:
Memory:
Flags:

.A used
STATUS ($90)
none

EXAMPLE:
LDA # 8
JSR $FF81
LDA # 1 5
JSR $FF93

;LISTN device 8
;pass it SA # 1 5

T H E COMMODORE 128 OPERATING SYSTEM

SECND is a low-level serial routine used to send a secondary address (SA) to

a LISTNing device (see LISTN Kernal call). An SA is usually used to provide setup
information to a device before the actual data I/O operation begins. Attention is
released after a call to SECND. SECND is not used to send an SA to a TALKing
device (see TKSA). (Most applications should use the higher level I/O routines: see
OPEN and CKOUT).

$FF96 TKSA ;serial: send SA after TALK

PREPARATION:
Registers:
Memory:
Flags:
Calls:

.A = SA (secondary address)
system map
none
TALK

RESULTS:
Registers:
Memory:
Flags:

.A used
STATUS ($90)
none

EXAMPLE:
LDA # 8
JSR $FFB4
LDA # 1 5
JSR $FF93

;TALK device 8
;pass it SA # 1 5

TKSA is a low-level serial routine used to send a secondary address (SA) to a

device commanded to TALK (see TALK Kernal call). An SA is usually used to
provide setup information to a device before the actual data I/O operation
begins. (Most applications should use the higher-level I/O routines; see OPEN and
CHKIN).

9. $FF99 M E M T O P ;set/read top of system RAM

PREPARATION:
Registers:
Memory:
Flags:
Calls:

.X = lsb of MEMSIZ
.Y = msb of MEMSIZ
system map
.C = 0 ^> set top of memory
.C = 1 ^ read top of memory
none

419

420

COMMODORE 128

RESULTS:
Registers:
Memory:
Flags:

.X = lsb of MEMSIZ
.Y = msb of MEMSIZ
MEMSIZ ($A07)
none

EXAMPLE:
SEC
JSR $FF99
DEY
CLC
JSR $FF99

;get top of user RAM0

;lower it 1 block

M E M T O P is used to read or set the top of system RAM, pointed to by

MEMSIZ ($A07). This call is included in the C128 for completeness, but neither the
Kernal nor BASIC utilizes MEMTOP since it has little meaning in the banked
memory environment of the C128 (even the RS-232 buffers are permanently
allocated). Nonetheless, set the carry status to load MEMSIZ into .X and .Y, and
clear it to update the pointer from .X and .Y. Note that MEMSIZ references only
system RAM (RAM0). The Kernal initially sets MEMSIZ to $FF00 (MMU and
Kernal RAM code start here).

10. $FF9C M E M B O T ;set/read bottom of system RAM

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:
Memory:
Flags:

.X = lsb of MEMSTR
.Y = msb of MEMSTR
system map
.C = 0 ^> set bot of memory
.C = 1 ^ read bot of memory
none
.X = lsb of MEMSTR
.Y = msb of MEMSTR
MEMSTR ($A05)
none

EXAMPLE:
SEC
JSR $FF9C
INY
CLC
JSR $FF9C

;get bottom of user RAM0

;raise it 1 block

THE COMMODORE 128 OPERATING SYSTEM

M E M B O T is used to read or set the bottom of system R A M , pointed to by

MEMSTR ($A05). This eall is included in the C128 for completeness, but neither
the Kernal nor BASIC utilizes MEMBOT since it has little meaning in the banked
memory environment of the C128. Nonetheless, set the carry status to load MEMSTR
into .X and .Y, and clear it to update the pointer from .X and .Y. Note that
MEMSTR references only system RAM (RAM0). The Kernal initially sets MEMSTR
to $1000 (BASIC text starts here).

11. $FF9F KEY ;scan keyboard

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:
Memory:

none
system map
none
none
none
keyboard buffer
keyboard flags
none

Flags:
EXAMPLE:
JSR $FF9F

;scan the keyboard

KEY is an Editor routine that scans the entire C128 keyboard (except the
key). It distinguishes between ASCII keys, control keys, and programmable keys, setting keyboard status bytes and managing the keyboard buffer. After
decoding the key, KEY will manage such features as toggling cases, pauses or
delays, and key repeats. It is normally called by the operating system during the
60Hz IRQ processing. Upon conclusion, KEY leaves the keyboard hardware driving the keyline on which the STOP key is located.
There are two indirect RAM jumps encountered during a keyscan: KEYVEC
($33A) and KEYCHK ($33C). KEYVEC (alias KEYLOG) is taken whenever a key
depression is discovered, before the key in .A has been decoded. KEYCHK is taken
after the key has been decoded, just before putting it into the key buffer. KEYCHK
carries the ASCII character in .A, the keycode in .Y, and the shiftkey status in .X.
The keyboard decode matrices are addressed via indirect RAM vectors as
well, located at DECODE ($33E). The following table describes them:

40/80

$33E
$340
$342
$344
$346
$348

Mode
Mode
Mode
Mode
Mode
Mode

1
2
3
4
5
6

normal keys

SHIFT

O keys

keys

C O N T R O L keys
CAPS LOCK keys

ALT

keys

421

422

COMMODORE 128

The following list briefly describes some of the more vital variables utilized
or maintained by KEY:
ROWS
COLM
VIC # 4 7
8502 P6
NDX
KEYD
XMAX
SHFLAG
RPTFLG
LOCKS

$DC01
$DC00
$D02F
$0001
$D0
$34A
$A20
$D3
$A22
$F7

^>
^>

^>
^>
^ >

^>

^>
^ >

^>

I/O port outputting keys

I/O port driving C64 keys
I/O port driving new keys
I/O port sensing CAPS key
keyboard buffer index
keyboard buffer
keyboard buffer size
shift key status
repeat key enables
pause, mode disables

KEY is also found in the Editor jump table as SCNKEY at $C012

12. $FFA2 SETTMO ;(reserved)
PREPARATION:
Registers:
Memory:
Flags:
Calls:

none
system map
none
none

RESULTS:
Registers:
Memory:
Flags:

none
TIMOUT ($AOE)
none

EXAMPLE:
LDA # v a l u e
JSR $FFA2

;update TIMOUT byte

SETTMO is not used in the C128 but is included for compatibility and
completeness. It is used in the C64 by the IEEE communication cartridge to disable
I/O timeouts.
13. $FFA5 ACPTR ;serial:byte input
PREPARATION:
Registers:
Memory:
Flags:
Calls:

none
system map
none
TALK
TKSA (if necessary)

THE C O M M O D O R E 128 OPERATING SYSTEM

RESULTS:
Registers:
Memory:
Flags:

.A = data byte
STATUS ($90)
none

EXAMPLE:
JSR $FFA5
STA data

;input a byte from serial bus

ACPTR is a low-level serial I/O utility to accept a single byte from the
current serial bus TALKer using full handshaking. To prepare for this routine,
a device must first have been established as a TALKer (see TALK) and passed
a secondary address if necessary (see TKSA). The byte is returned in .A.
(Most applications should use the higher-level I/O routines; see BASIN and
GETIN).

14. $FFA8 CIOUT ;serial: byte output

PREPARATION:
Registers:
Memory:
Flags:
Calls:

RESULTS:
Registers:
Memory:
Flags:

.A = data byte
system map
none
LISTN
SECND (if necessary)

.A used
STATUS ($90)
none

EXAMPLE:
LDA data
JSR $FFA8

;send a byte via serial bus

CIOUT is a low-level serial I/O utility to transmit a single byte to the current
serial bus LISTNer using full handshaking. To prepare for this routine, a device
must first have been established as a LISTNer (see LISTN) and passed a secondary
address if necessary (see SECND). The byte is passed in .A. Serial output data is
buffered by one character, with the last character being transmitted with EOI after a
call to UNLSN. (Most applications should use the higher level I/O routines; see
BSOUT.)

423

424

COMMODORE 128

15. $FFAB UNTLK ;serial: send untalk

PREPARATION:
Registers:
Memory:
Flags:
Calls:

none
system map
none
none

RESULTS:
Registers:
Memory:
Flags:

.A used
STATUS ($90)
none

EXAMPLE:
JSR $FFAB

;UNTALK serial device

UNTLK is a low-level Kernal serial bus routine that sends an UNTALK

command to all serial bus devices. It commands all TALKing devices to stop
sending data. (Most applications should use the higher-level I/O routines; see
CLRCH.)

16. $FFAE UNLSN ;serial: send unlisten

PREPARATION:
Registers:
Memory:
Flags:
Calls:

none
system map
none
none

RESULTS:
Registers:
Memory:
Flags:

.A used
STATUS ($90)
none

EXAMPLE:
JSR $FFAE

;UNLISTEN serial device

UNLSN is a low-level Kernal serial bus routine that sends an UNLISTEN

command to all serial bus devices. It commands all LISTENing devices to stop
reading data. (Most applications should use the higher-level I/O routines; see
ICLRCH.)

THE COMMODORE 128 OPERATING SYSTEM

17. $FFB1 LISTN ;serial: send listen command

PREPARATION:
Registers:
Memory:
Flags:
Calls:

.A = device (0-31)
system map
none
none

RESULTS:
Registers:
Memory:
Flags:

.A used
STATUS ($90)
none

EXAMPLE:
JSR $FFB1

;command device to LISTEN

LISTN is a low-level Kernal serial bus routine that sends a LISTEN

command to the serial bus device in .A. It commands the device to start reading data. (Most applications should use the higher-level I/O routines; see
ICKOUT.)

18. $FFB4 TALK ;serial: send talk

PREPARATION:
Registers:
Memory:
Flags:
Calls:

.A = device (0-31)
system map
none
none

RESULTS:
Registers:
Memory:
Flags:

.A used
STATUS ($90)
none

EXAMPLE:
JSR $FFB4

;command device to TALK

TALK is a low-level Kernal serial bus routine that sends a TALK command
to the serial bus device in .A. It commands the device to start sending data. (Most
applications should use the higher-level I/O routines; see ICHKIN.)

425

426

COMMODORE 128

19. $FFB7 READSS ;read I/O status byte

PREPARATION:
Registers:
Memory:
Flags:
Calls:

none
system map
none
none

RESULTS:
Registers:
Memory:
Flags:

.A = STATUS ($90 or $A14)

STATUS cleared if RS-232
none

EXAMPLE:
JSR $FFB7

;STATUS for last I/O

READSS (alias READST) returns the status byte associated with the last I/O
operation (serial, cassette or RS-232) performed. Serial and cassette tape operations
update STATUS ($90) and RS-232 I/O updates RSSTAT ($A14). Note that to
simulate an ACIA, RSSTAT is cleared after it is read via READSS. The last I/O
operation is determined by the contents of FA ($BA); thus applications that drive
I/O devices using the lower-level Kernal calls should not use READSS.

20. $FFBA SETLFS ;set channel LA, FA, SA

PREPARATION:
Registers:

Memory:
Flags:
Calls:
RESULTS:
Registers:
Memory:
Flags:

.A = LA (logical # )
.X = FA (device # )
.Y = SA (secondary adr)
system map
none
none
none
LA, FA, SA updated
none

EXAMPLE:
See OPEN
SETLFS sets the logical file number (LA, $B8), device number (FA, $BA)
and secondary address (SA, $B9) for the higher-level Kernal I/O routines. The LA
must be unique among OPENed files and is used to identify specific files for I/O

THE COMMODORE 128 OPERATING SYSTEM

operations. The device number range is 0 to 31 and is used to target I/O. The SA is
a command to be sent to the indicated device, usually to place it in a particular
mode. If the SA is not needed, the .Y register should pass $FF. SETLFS is often
used along with SETNAM and SETBNK calls prior to OPENs. See the Kernal
OPEN, LOAD and SAVE calls for examples.

21. $FFBD SETNAM ;set filename pointers

PREPARATION:
Registers:

Memory:
Flags:
Calls:
RESULTS:
Registers:
Memory:
Flags:

.A = string length
.X = string adr low
.Y = string adr high
system map
none
SETBNK

none
FNLEN, FNADR updated
none

EXAMPLE:
See OPEN
SETNAM sets up the filename or command string for higher-level Kernal I/O
calls such as OPEN, LOAD and SAVE. The string (filename or command) length is
passed in .A and updates FNLEN ($B7). The address of the string is passed in .X
(low) and .Y (high). See the companion call, SETBNK, which specifies in which
RAM bank the string is found. If there is no string, SETNAM should still be called
and a null ($00) length specified (the address does not matter). SETNAM is often
used along with SETBNK and SETLFS calls prior to OPENs. See the Kernal
OPEN, LOAD and SAVE calls for examples.

22. $FFC0 OPEN ;open logical file

PREPARATION:
Registers:
Memory:
Flags:
Calls:

none
system map
none
SETLFS, SETNAM, SETBNK

427

428

COMMODORE 128

RESULTS:
Registers:

Flags:

.A = error code (if any)

.X used
.Y used
setup for I/O
STATUS, RSSTAT updated
.C = 1 ^ error

EXAMPLE:

OPEN l,8,15,"IO"

Memory:

LDA
LDX
LDY
JSR

#length
#<filename
#>filename
$FFBD

;fnlen
;fnadr (command)
;SETNAM

LDX # 0
JSR $FF68

;fnbank (Ram0)
;SETBNK

LDA
LDX
LDY
JSR

#1
#8
#15
$FFBA

;la
;fa
;sa
;SETLFS

JSR

$FFC0

;OPEN

BCS error
filename .BYTE TO'
length
= 2
OPEN prepares a logical file for I/O operations. It creates a unique entry in
the Kernal logical file tables LAT ($362), FAT ($36C) and SAT ($376) using its
index LDTND ($98) and data supplied by the user via SETLFS. There can be up to
ten logical files OPENed simultaneously. OPEN performs device-specific opening
tasks for serial, cassette and RS-232 devices, including clearing the previous status and
transmitting any given filename or command string supplied by the user via SETNAM
and SETBNK. The I/O status is updated appropriately and can be read via READSS.
The path to OPEN is through an indirect RAM vector at $31A. Applications
may therefore provide their own OPEN procedures or supplement the system's by
redirecting this vector to their own routine.

23. $FFC3 CLOSE ;close logical file

PREPARATION:
Registers:
Memory:
Flags:
Calls:

.A = LA (logical # )
system map
.C (see text below)
none

THE COMMODORE 128 OPERATING SYSTEM

RESULTS:
Registers:

Memory:
Flags:

.A = error code (if any)

.X used
.Y used
logical tables updated
STATUS, RSSTAT updated
.C = 1 ^ error

EXAMPLE:
LDA # 1
JSR $FFC3
BCS error

;la
;CLOSE
;(tape files only)

CLOSE removes the logical file (LA) passed in .A from the logical file tables
and performs device-specific closing tasks. Keyboard, screen and any unOPENed
files pass through. Cassette files opened for output are closed by writing the last
buffer and (optionally) an EOT mark. RS-232 I/O devices are reset, losing any
buffered data. Serial files are closed by transmitting a CLOSE command (if an SA
was given when it was opened), sending any buffered character, and UNLSTNing
the bus.
There is a special provision incorporated into the CLOSE routine of systems
featuring a BASIC DOS command. If the following conditions are all true, a full
CLOSE is not performed; the table entry is removed but a CLOSE command is not
transmitted to the device. This allows the disk command channel to be properly
OPENed and CLOSEd without the disk operating system closing all files on its
end:
.C = 1 ^> indicates special CLOSE
FA > = 8 ^> device is a disk
SA = 15 ^> command channel
The path to CLOSE is through an indirect RAM vector at $31C. Applications
may therefore provide their own CLOSE procedures or supplement the system's by
redirecting this vector to their own routine.

24. $FFC6 CHKIN ;set input channel

PREPARATION:
Registers:
Memory:
Flags:
Calls:

.X = LA (logical # )
system map
none
OPEN

429

430

COMMODORE 128

RESULTS:
Registers:

Memory:
Flags:

.A = error code (if any)

.X used
.Y used
LA, FA, SA, DFLTN
STATUS, RSSTAT updated
.C = 1 ^ error

EXAMPLE:
LDX # 1
JSR $FFC6
BCS error

;la
;CHKIN

CHKIN establishes an input channel to the device associated with the logical
address (LA) passed in .X, in preparation for a call to BASIN or GETIN. The
Kernal variable DFLTN ($99) is updated to indicate the current input device and the
variables LA, FA and SA are updated with the file's parameters from its entry in
the logical file tables (put there by OPEN). CHKIN performs certain device specific
tasks: screen and keyboard channels pass through, cassette files are confirmed for
input, and serial channels are sent a TALK command and the SA transmitted (if
necessary). Call CLRCH to restore normal I/O channels.
CHKIN is required for all input except the keyboard. If keyboard input is
desired and no other input channel is established, you do not need to call CHKIN or
OPEN. The keyboard is the default input device for BASIN and GETIN.
The path to CHKIN is through an indirect RAM vector at $31E. Applications
may therefore provide their own CHKIN procedures or supplement the system's by
redirecting this vector to their own routine.

25. $FFC9 CKOUT ;set output channel

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:

Memory:
Flags:

.X = LA (logical # )
system map
none
OPEN
.A = error code (if any)
.X used
.Y used
LA, FA, SA, DFLTO
STATUS, RSSTAT updated
.C = 1 ^ error

THE COMMODORE 128 OPERATING SYSTEM

EXAMPLE:
LDX # 1
JSR $FFC9
BCS error

;la
;CKOUT

CKOUT establishes an output channel to the device associated with the

logical address (LA) passed in .X, in preparation for a call to BSOUT. The Kernal
variable DFLTO ($9A) is updated to indicate the current output device and the
variables LA, FA and SA are updated with the file's parameters from its entry in
the logical file tables (put there by OPEN). CKOUT performs certain device
specific tasks: keyboard channels are illegal, screen channels pass through, cassette
files are confirmed for output, and serial channels are sent a LISTN command and
the SA transmitted (if necessary). Call CLRCH to restore normal I/O channels.
CKOUT is required for all output except the screen. If screen output is
desired and no other output channel is established, you do not need to call CKOUT
or OPEN. The screen is the default output device for BSOUT.
The path to CKOUT is through an indirect RAM vector at $320. Applications
may therefore provide their own CKOUT procedures or supplement the system's by
redirecting this vector to their own routine.

26. $FFCC CLRCH ;restore default channels

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:
Memory :
Flags:

none
system map
none
none
.A used
.X used
DFLTI, DFLTO updated
none

EXAMPLE:
JSR $FFCC

;restore default I/O

CLRCH (alias CLRCHN) is used to clear all open channels and restore the
system default I/O channels after other channels have been established via CHKIN
and/or CHKOUT. The keyboard is the default input device and the screen is the
default output device. If the input channel was to a serial device, CLRCH first
UNTLKs it. If the output channel was to a serial device, it is UNLSNed first.

431

432

COMMODORE 128

The path to CLRCH is through an indirect RAM vector at $322. Applications

may therefore provide their own CLRCH procedures or supplement the system's by
redirecting this vector to their own routine.

27. $FFCF BASIN ;input from channel

PREPARATION:
Registers:
Memory:
Flags:
Calls:

none
system map
none
CHKIN (if necessary)

RESULTS:
Registers:
Memory:
Flags:

.A = character (or error code)

STATUS, RSSTAT updated
.C = 1 if error

EXAMPLE:
LDY # 0
MORE JSR $FFCF
STA data,Y
INY
CMP # $ 0 D
BNE MORE

;index
;input a character
;buffer it
;carriage return?

BASIN (alias CHRIN) reads a character from the current input device (DFLTN
$99) and returns it in .A. Input from devices other than the keyboard (the default
input device) must be OPENed and CHKINed. The character is read from the input
buffer associated with the current input channel:
a. Cassette data is returned a character at a time from the cassette buffer at $B00,
with additional tape blocks being read when necessary.
b. RS-232 data is returned a character at a time from the RS-232 input buffer at $C00,
waiting until a character is received if necessary. If RSSTAT ($A14) is bad from
a prior operation, input is skipped and null input (carriage return) is substituted.
c. Serial data is returned a character at a time directly from the serial bus, waiting
until a character is sent if necessary. If STATUS ($90) is bad from a prior
operation, input is skipped and null input (carriage return) is substituted.
d. Screen data is read from screen RAM starting at the current cursor position and
ending with a pseudo carriage return at the end of the logical screen line. The
way the BASIN routine is written, the end of line (EOL) is not recognized. Users must therefore count characters themselves or otherwise detect
when the logical EOL has been reached.

THE COMMODORE 128 OPERATING SYSTEM

e. Keyboard data is input by turning on the cursor, reading characters from the
keyboard buffer, and echoing them on the screen until a carriage return is
encountered. Characters are then returned one at a time from the screen until
all characters input have been passed, including the carriage return. Any calls
after the EOL will start the process over again.
The path to BASIN is through an indirect RAM vector at $324. Applications
may therefore provide their own BASIN procedures or supplement the system's by
redirecting this vector to their own routine.

28. $FFD2 BSOUT ;output to channel

PREPARATION:
Registers:
Memory:
Flags:
Calls:

.A = character
system map
none
CKOUT (if necessary)

RESULTS:
Registers:
Memory:
Flags:

.A = error code (if any)

STATUS, RSSTAT updated
.C = 1 if error

EXAMPLE:
LDA #character
JSR $FFD2

;output a character

BSOUT (alias CHROUT) writes the character in .A to the current output

device (DFLTO $9A). Output to devices other than the screen (the default output
device) must be OPENed and CKOUTed. The character is written to the output
buffer associated with the current output channel:
a. Cassette data is put a character at a time into the cassette buffer at $B00, with
tape blocks being written when necessary.
b. RS-232 data is put a character at a time into the RS-232 output buffer at $D00,
waiting until there is room if necessary.
c. Serial data is passed to CIOUT, which buffers one character and sends the
previous character.
d. Screen data is put into screen RAM at the current cursor position.
e. Keyboard output is illegal.
The path to BSOUT is through an indirect RAM vector at $326. Applications
may therefore provide their own BSOUT procedures or supplement the system's by
redirecting this vector to their own routine.

433

434

COMMODORE 128

29. $FFD5 LOAD ;load from file

PREPARATION:
Registers:

Memory:
Flags:
Calls:
RESULTS:
Registers:

Memory:
Flags:
EXAMPLE:

.A = 0 ^ LOAD
.A > 0 ^ VERIFY
.X = load adrlo (ifSA = 0)
.Y = load adrhi (ifSA = 0)
system map
none
SETLFS, SETNAM, SETBNK
.A = error code (if any)
.X = ending adr lo
.Y = ending adr hi
per command
STATUS updated
.C = 1 ^ error
LOAD "program",8,l

LDA #length
;fnlen
LDX #<filename ;fnadr
LDY #>filename
JSR $FFBD
SETNAM
LDA # 0
LDX # 0
JSR $FF68

load/verify bank (RAM 0)

fnbank (RAM 0)
SETBNK

LDA # 0
LDX # 8
LDY # $ F F
JSR $FFBA

la (not used)
fa
sa (SA>0 normal load)
SETLFS

LDA # 0
LDX # < l o a d adr
LDY # > l o a d adr
JSR $FFD5
BCS error
STX end lo
STY end hi

load, not verify

(used only if SA = 0)
(used only if SA = 0)
LOAD

filename .BYTE "program"

length
=7
This routine LOADs data from an input device into C128 memory. It can also
be used to VERIFY that data in memory matches that in a file. LOAD performs

THE COMMODORE 128 OPERATING SYSTEM

device-specific tasks for serial and cassette LOADs. You cannot LOAD from
RS-232 devices, the screen or the keyboard. While LOAD performs all the tasks of
an OPEN, it does not create any logical files as an OPEN does. Also note that LOAD
cannot "wrap" memory banks. As with any FO, the I/O status is updated appropriately
and can be read via READSS. LOAD has two options that the user must select:
a. LOAD vs. VERIFY: The contents of .A passed at the call to LOAD determines which mode is in effect. If .A is zero, a LOAD operation will be
performed and memory will be overwritten. If .A is nonzero, a VERIFY
operation will be performed and the result passed via the error mechanism.
b. LOAD ADDRESS: the secondary address (SA) setup by the call to SETLFS
determines where the LOAD starting address comes from. If the SA is zero,
the user wants the address in .X and .Y at the time of the call to be used. If the
SA is nonzero, the LOAD starting address is read from the file header itself
and the file is loaded into the same place from which it was SAVEd.
The C128 serial LOAD routine automatically attempts to BURST load a file,
and resorts to the normal load mechanism (but still using the FAST serial routines)
if the BURST handshake is not returned.
The path to LOAD is through an indirect RAM vector at $330. Applications
may therefore provide their own LOAD procedures or supplement the system
procedures by redirecting this vector to their own routine.

30. $FFD8 SAVE ;save to file

PREPARATION:
Registers:

Memory:
Flags:
Calls:
RESULTS:
Registers:

Memory:
Flags:
EXAMPLE:

.A = pointer to start adr

.X = end adr lo
.Y = end adr hi
system map
none
SETLFS, SETNAM, SETBNK
.A = error code (if any)
.X = used
.Y = used
STATUS updated
.C = 1 ^ error
SAVE 4 'program'',8

LDA #length
;fnlen
LDX #<filename ;fnadr
LDY #>filename
JSR $FFBD
;SETNAM

435

436

COMMODORE 128

filename
length
start
end

LDA # 0
LDX # 0
JSR $FF68

;save from bank (RAM 0)

;fnbank (RAM 0)
;SETBNK

LDA # 0
LDX # 8
LDY # 0
JSR $FFBA

;la (not used)

;fa
;sa (cassette only)
;SETLFS

LDA #start
LDX end
LDY end + 1
JSR $FFD8
BCS error

;pointer to start address

;ending address lo
;ending adr hi
;SAVE

.BYTE "program"
= 7
.WORD addressl ;page-0
.WORD address2

This routine SAVEs data from C128 memory to an output device. SAVE performs device-specific tasks for serial and cassette SAVEs. You cannot SAVE from
RS-232 devices, the screen or the keyboard. While SAVE performs all the tasks of an
OPEN, it does not create any logical files as an OPEN does. The starting address of
the area to be SAVEd must be placed in a zero-page vector and the address of this
vector passed to SAVE in .A at the time of the call. The address of the last byte
to be SAVEd PLUS ONE is passed in .X and .Y at the same time. Cassette SAVEs
utilize the secondary address (SA) to specify the type of tape header(s) to be generated:
SA (bit 0) =
=
SA (bit 1) =
=

0 ^
1^
0 ^
1 ^>

relocatable (blf) file

absolute
(plf) file
normal end
write EOT header at end

There is no BURST save; the normal FAST serial routines are used. As with
any I/O, the I/O status will be updated appropriately and can be read via READSS.
The path to SAVE is through an indirect RAM vector at $332. Applications
may therefore provide their own SAVE procedures or supplement the system's by
redirecting this vector to their own routine.

31. $FFDB SETTIM ;set internal clock

PREPARATION:
Registers:

Memory:
Flags:
Calls:

.A = low byte
.X = middle byte
.Y = high byte
system map
none
none

T H E COMMODORE 128 OPERATING SYSTEM

RESULTS:
Registers:
Memory:
Flags:

none
TIME ($A0) updated
none

EXAMPLE:
LDA # 0
TAX
TAY
JSR $FFDB

;reset clock

;SETTIM

SETTIM sets the system software 0 i ^ e ) clock, which counts sixtieths (1/60)
of a second. The timer is incremented during system IRQ processing (see UDTIM),
and reset at the 24-hour point. SETTIM disables IRQ's, updates the three-byte timer
with the contents of .A, .X and .Y, and re-enables IRQ's.
32. $FFDE RDTIM ;read internal clock
PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:

Memory:
Flags:

none
system map
none
none
.A = low byte
.X = middle byte
.Y = high byte
none
none

EXAMPLE:
JSR $FFDE

;RDTIM

RDTIM reads the system software Oiffie) clock, which counts sixtieths (1/60)
of a second. The timer is incremented during system IRQ processing (see UDTIM),
and reset at the 24-hour point. RDTIM disables IRQ's, loads .A, .X and .Y with the
contents of the 3-byte timer, and re-enables IRQ's.

33. $FFE1 STOP ;scan STOP key

PREPARATION:
Registers:
Memory:
Flags:
Calls:

none
system map
none
none

437

438

COMMODORE 128

RESULTS:
Registers:

.A = last keyboard row

.X = used (if STOP key)
none
status valid

Memory:
Flags:
EXAMPLE:
JSR $FFE1
BEQ stop

;scan STOP key

;branch if down

STOP checks a Kernal variable STKEY ($91), which is updated by UDTIM

during normal IRQ processing and contains the last scan of keyboard column C7.
The STOP key is bit 7, which will be 0 if the key is down. If it is, default I/O
channels are restored via CLRCH and the keyboard queue is flushed by resetting
NDX ($D0). The keys on keyboard line C7 are:
Bit:
Key:

7
STOP

6
Q

5
fr

4
SPACE

3
2

2
CTRL

1
-

0
1

The path to STOP is through an indirect RAM vector at $328. Applications

may therefore provide their own STOP procedures or supplement the system's by
redirecting this vector to their own routine.

34. $FFE4 GETIN ;read buffered data

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:

Memory:
Flags:

none
system map
none
CHKIN (if necessary)
.A = character (or error code)
.X used
.Y used
STATUS, RSSTAT updated
.C = 1 if error

EXAMPLE:
wait JSR $FFE4
BEQ wait
STA character

;get any key

GETIN reads a character from the current input device (DFLTN ($99)) buffer
and returns it in .A. Input from devices other than the keyboard (the default input
device) must be OPENed and CHKINed. The character is read from the input buffer
associated with the current input channel:

THE COMMODORE 128 OPERATING SYSTEM

a. Keyboard input: A character is removed from the keyboard buffer and passed
in .A. If the buffer is empty, a null ($00) is returned.
b. RS-232 input: A character is removed from the RS-232 input buffer at $C00
and passed in .A. If the buffer is empty, a null ($00) is returned (use READSS
to check validity).
c. Serial input: GETIN automaticallyjumps to BASIN. See BASIN serial I/O.
d. Cassette input: GETIN automatically jumps to BASIN. See BASIN cassette
I/O.
e. Screen input: GETIN automaticallyjumps to BASIN. See BASIN serial I/O.
The path to GETIN is through an indirect RAM vector at $32A. Applications
may therefore provide their own GETIN procedures or supplement the system's by
redirecting this vector to their own routine.

35. $FFE7 CLALL ;close all files and channels

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:
Memory:
Flags:

none
system map
none
none
.A used
.X used
LDTND, DFLTN, DFLTO updated
none

EXAMPLE:
JSR $FFE7

;close files

CLALL deletes all logical file table entries by resetting the table index,
LDTND ($98). It clears current serial channels (if any) and restores the default I/O
channels via CLRCH.
The path to CLALL is through an indirect RAM vector at $32C. Applications
may therefore provide their own CLALL procedures or supplement the system's by
redirecting this vector to their own routine.

36. $FFEA UDTIM ;increment internal clock

PREPARATION:
Registers:
Memory:
Flags:
Calls:

none
system map
none
none

439

440

COMMODORE 128

RESULTS:
Registers:
Memory:
Flags:

.A used
.X used
TIME, TIMER, STKEY updated
none

EXAMPLE:
SEI
JSR $FFEA
CLI

;UDTIM

UDTIM increments the system software Qiffie) clock, which counts sixtieths
(1/60) of a second when called by the system 60Hz IRQ. TIME, a 3-byte counter
located at $A0, is reset at the 24-hour point. UDTIM also decrements TIMER, also
a 3-byte counter, located at $AlD (BASIC uses this for the SLEEP command, for
example). You should be sure IRQ's are disabled before calling UDTIM to prevent
system calls to UDTIM while you are modifying TIME and TIMER.
UDTIM also scans key line C7, on which the STOP key lies, and stores the
result in STKEY ($91). The Kernal routine STOP utilizes this variable.
37. $FFED SCRORG ;get current screen window size
PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:

Memory:
Flags:

none
system map
none
none
.A = screen width
.X = window width
.Y = window height
none
none

EXAMPLE:
JSR $FFED

;SCRORG

SCRORG is an Editor routine that has been slightly changed from previous
CBM systems. Instead of returning the maximum SCREEN dimensions in .X and
.Y, the C128 SCRORG returns the current WINDOW dimensions. It does return
the maximum SCREEN width in .A. These changes make it possible for applications to " f i t " themselves on the current screen window. SCRORG is also an Editor
jump table entry ($C00F).

THE COMMODORE 128 OPERATING SYSTEM

38. $FFF0 PLOT ;read/set cursor position

PREPARATION:
Registers:

.X = cursor line
.Y = cursor column
system map
.C = 0 ^ set cursor position
.C = 1 ^ get cursor position
none

Memory:
Flags:
Calls:
RESULTS:
Registers:

.X = cursor line
.Y = cursor column
TBLX, PNTR updated
.C = 1 ^ error

Memory:
Flags:
EXAMPLE:
SEC
JSR $FFF0
INX
INY
CLC
JSR $FFF0
BCS error

;read current position

;move down one line
;move right one space
;set cursor position
;new position outside window

PLOT is an Editor routine that has been slightly changed from previous CBM
systems. Instead of using absolute coordinates when referencing the cursor position,
PLOT now uses relative coordinates, based upon the current screen window. The
following local Editor variables are useful:
SCBOT
SCTOP
SCLF
SCRT
TBLX
PNTR
LINES
COLUMNS

$E4
$E5
$E6
$E7
$EB
$EC
$ED
$EE

^
~

^
^
^
^
^
^

window bottom
window top
window left side
window right side
cursor line
cursor column
maximum screen height
maximum screen width

When called with the carry status set, PLOT returns the current cursor
position relative to the current window origin (not screen origin). When called with
the carry status clear, PLOT attempts to move the cursor to the indicated line and
column relative to the current window origin (not screen origin). PLOT will return a
clear carry status if the cursor was moved, and a set carry status if the requested
position was outside the current window (no change has been made).

441

442

COMMODORE 128

39. $FFF3 IOBASE ;read base address of I/O block

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:
Memory:
Flags:

none
system map
none
none
.X = lsb of I/O block
.Y = msb of I/O block
none
none

EXAMPLE:
JSR $FFF3

;find the I/O block

IOBASE is not used in the C128 but is included for compatibility and completeness. It returns the address of the I/O block in .X and .Y.

NEW CI28 KERNAL CALLS

The following system calls are a set of extensions to the standard CBM jump table.
They are specifically for the C128 and as such should not be considered as permanent
additions to the standardjump table. With the exception of C64 MODE, they are all true
subroutines and will terminate via an RTS. As with all Kernal calls, the system
configuration (high ROM, RAM-0 and I/O) must be in context at the time of the
call.

1. $FF47 SPIN SPOUT ;setup fast serial ports for I/O

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:
Memory:
Flags:

none
system map
.C = 0 ^ select SPINP
.C = 1 ^ select SPOUT
none
.A used
CIA-1, MMU
none

THE COMMODORE 128 OPERATING SYSTEM

EXAMPLE:
CLC
JSR $FF47

;setup for fast serial input

The C128/1571 fast serial protocol utilizes CIA 1 (6526 at $DC00) and a
special driver circuit controlled in part by the MMU (at $D500). SPINP and
SPOUT are routines used by the system to set up the CIA and fast serial driver
circuit for input or output. SPINP sets up CRA (CIA 1 register 14) and clears the
FSDIR bit (MMU register 5) for input. SPOUT sets up CRA, ICR (CIA 1 register
13), timer A (CIA 1 registers 4 and 5), and sets the FSDIR bit for output. Note the
state of the TODIN bit of CRA is always preserved, but the state of the GAME,
EXROM and SENSE40 outputs of the MMU are not (reading these ports return the
state of the port and not the register valuesconsequently they cannot be preserved). These routines are required only by applications driving the fast serial bus
themselves from the lowest level.

2. $FF4A CLOSE ALL ;close all files on a device

PREPARATION.
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:

Memory:
Flags:

.A ^ device # (FA: 0-31)

system map
none
none
.A used
.X used
.Y used
none
none

EXAMPLE:
LDA # $ 0 8
JSR $FF4A

;close all files on device 8

The FAT is searched for the given FA. A proper CLOSE is performed for all
matches. If one of the CLOSEd channels is the current I/O channel, then the default
channel is restored.
This call is utilized, for example, by the BASIC command DCLOSE. It is
also called by the Kernal BOOT routine.

443

444

COMMODORE 128

3. $FF4D C64MODE ;reconfigure system as a C64

PREPARATION:
Registers:
Memory:
Flags:
Calls:

none
system map
none
none

RESULTS:
Registers:
Memory:
Flags:

none
none
none

EXAMPLE:
JMP $FF4D

;switch to C64 mode

There is no returnfrom this routine. The 8502 DDR and port are initialized,
and the VIC is set to lMHz (slow) mode. Control is passed to code in common
(shared) RAM, which sets the MMU mode register (#5) to C64 mode. From this
point on, the MMU and C128 ROMs are not accessible. The routine exits via an
indirect jump through the C64 RESET vector.
Since C64 operation does not allow for MMU access, all MMU registers must
be configured for proper operation before the C64 mode bit is set. Similarly,
because the start-up of the C64 operating system is not from a true hardware reset,
there is the possibility that unusual I/O states in effect prior to C64MODE calls can
cause unpredictable and presumably undesirable situations once in C64 mode.
There is no way to switch from C64 mode back to C128 mode; only a
hardware reset or power off/on will restore the C128 mode of operation. A reset
will always initiate C128 mode, although altering the SYSTEM vector beforehand
is one way to automatically "throw" a system back to C64 mode.

4. $FF50 DMA CALL ;send command to DMA device

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:
Memory:
Flags:

.X = bank (0-15)
.Y = DMA controller command
DMA registers set up system map
none
none
.A used
.X used
changed as per command
none

THE COMMODORE 128 OPERATING SYSTEM

EXAMPLE:
LDA
STA
LDA
STA

#$00
$DF02
#$20
$DF03

;high

LDA
STA
STA
STA

#$00
$DF04
$DF05
$DF06

;setup expansion RAM address

;low
;high
;bank (0-n, where n = 3 if 256K)

LDA
STA
LDA
STA

#$40
$DF07
#$lF
$DF08

;setup number of bytes

;low

LDX # $ 0 0
LDY #$84
JSR $FF50

;setup C128 base address

;low

;high
;C128 bank
;DMA command to " S T A S H "
;execute DMA command

DMA CALL is designed to communicate with an external expansion cartridge capable of DMA and mapped into system memory at 102 ($DFxx). The
DMA CALL converts the logical C128 bank parameter to MMU configuration via
GETCFG, OR's in the I/O enable bit, and transfers control to RAM code at $3F0.
Here the C128 bank specified is brought into context, and the user's command is
issued to the DMA controller. The actual DMA transfer is performed at this point,
with the 8502 kept off the bus in a wait state. As soon as the DMA controller
releases the processor, memory is reconfigured to the state it was in at the time of
the call and control is returned to the caller. The user must analyze the completion
status by reading the DMA status register at $DF00.
Care should be taken in the utilization of the C128 RAM expansion product
by any application using the built-in Kernal interface. This includes especially the
use of the C128 BASIC commands FETCH, STASH and SWAP. In the routine that
prepares a DMA request for the user, the Kernal forces the I/O block to be always
in context. Consequently, data from the DMA device is likely to corrupt sensitive
I/O devices. Users should either bypass the Kernal DMA routine by providing
their own interface, or limit the DMA data transfers to the areas above and below the
I/O block. Only strict observance of the latter will guarantee proper utilization of
the BASIC commands. The following code, used instead of the DMA CALL in the
above example, illustrates a work-around:
LDX
LDY
JSR
TAX
JSR

# $ 0 0 ;C128 bank
# $ 8 4 ;DMA command to 'STASH'
$FF6B ;GETCFG
$3F0

;execute DMA command

445

446

COMMODORE 128

5. $FF53 BOOT CALL ;boot load program from disk

PREPARATION:
Registers:

.A = drive number (ASCII)

.X = device number (0-31)
system map
none
none

Memory:
Flags:
Calls:
RESULTS:
Registers:

.A used
.X used
.Y used
changed as per command
.C ^ 1 if I/O error

Memory:
Flags:
EXAMPLE:

LDA # $ 3 0
;drive 0
LDX #$08
;device 8
JSR $FF53
;BOOT
BCS 10 ERROR
BCC NO BOOT SECTOR
BOOT attempts to load and execute the boot sector from an auto-boot disk in
the given drive and device. The BOOT protocol is as follows:
a.
b.
c.
d.

Close all open files on boot device.

Read track 1 sector 0 into TBUFFR ($B00).
Check for auto-boot header, RTS if not.
If (blk# > 0), BLOCK READ sequential sectors into RAM at given (adrl,
adrh, bank) location.
e. If LEN(filename) > 0, LOAD file into RAM-0 (normal load).
f. JSR to user code at location C above.
On any error, the BOOT operation is aborted and the UI command is issued
to the disk. A return may or may not be made to the caller depending upon the
completion status and the BOOTed code. The BOOT sector has the following
layout:
$00
C

$01
B

where:

$02
M

A=
B=
C=

$03
adrl

$04
adrh

$05
bank

$07 + LEN(title)
A + LEN(filename)
B + 1

$06
blk#

title

A
0

file

B
0

C
code

THE COMMODORE 128 OPERATING SYSTEM

The following examples illustrate the flexibility of this layout. This loads and runs a
BASIC program:
$00
$03
$07
$0C
$0D
$14
$20

^
^
^
^
^ >

CBM
$00,$00,$00,$00
NAME,$00
$00
$A2,$13,$AO,$OB
$4C,$A5,$AF
R U N ' ' PROGRAM''
$00

:key
:no other BOOT sector
:message " N A M E "
:no filename
:code
:data (BASIC stmt)

This results in the message Booting NAME... being displayed and, utilizing a
C128 BASIC jump table entry that finds and executes a BASIC statement, loads
and runs the BASIC program named " P R O G R A M . " The same header can be used
to load and execute a binary (machine code) program by simply changing RUN to
BOOT. (While the file auto-load feature of the boot header could be used to load
binary files simply by furnishing a filename, to execute it you must know the
starting address and JMP to it. BASIC's BOOT command does that, and allows a
more generic mechanism.) In the next example, a menu is displayed and you are
asked to select the operating mode. Nothing else is loaded in this "configure"-type
header:

$00
$03
$07
$0C
$0D

^
^
^>
^
^

CBM
:key
$00,$00,$00,$00
:no other BOOT sector
$00
:no message
$00
:no filename
$20,$7D, $FF,$0D, $53, $45,$4C, $45
$43, $54, $20,$4D, $4F, $44, $45,$3A
$0D,$0D, $20, $31,$2E, $20, $43, $36
$34, $20, $20, $42, $41, $53, $49, $43
$0D, $20, $32,$2E, $20, $43, $31, $32
$38, $20, $42, $41, $53, $49, $43,$0D
$20, $33,$2E, $20, $43, $31, $32, $38
$20,$4D, $4F, $4E, $49, $54, $4F, $52
$0D,$0D, $00, $20,$E4,$FF,$C9, $31
$D0, $03,$4C,$4D,$FF,$C9, $32,$D0
$03,$4C, $03, $40,$C9, $33,$DO, $E3
$4C, $00,$B0

The loading of sequential sectors is designed primarily for specialized applications

(such as CP/M or games) that do not need a disk directory entry.

447

448

COMMODORE 128

6. $FF56 PHOENIX ;init function cartridges

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:

Memory:
Flags:

none
cartridge map
none
none
.A used
.X used
.Y used
changed as per command
none

EXAMPLE:
JSR $FF56

;PHOENIX

The C128 Kernal initialization routine POLL creates a Physical Address

Table (PAT) containing the ID's ofall installed function ROM cartridges. PHOENIX
calls each logged cartridge's cold-start entry in the order: external low/high, and
internal low/high. After calling the cartridges (if any), PHOENIX calls the Kernal
BOOT routine to look for an auto-boot disk in drive 0 of device 8 (see BOOT CALL).
Control may or may not be returned to the user. PHOENIX is called by BASIC at
the conclusion of its cold initialization.
7. $FF59 LKUPLA ;search tables for given LA
8. $FF5C LKUPSA ;search tables for given SA
PREPARATION:
Registers:

Memory:
Flags:
Calls:
RESULTS:
Registers:

Memory:
Flags:

. A = LA (logical file number)

if LKUPLA
. Y = SA (secondary address)
if LKUPSA
system map
none
none
.A =
.X =
.Y =
none
.C =
.C =

LA (only if found)
FA (only if found)
SA (only iffound)
0 if found
1 if not found

THE COMMODORE 128 OPERATING SYSTEM

EXAMPLE:
LDY
AGAIN INY
CPY
BCS
JSR
BCC

#$60

;find an available SA

#$6F
TOO MANY
$FF5C
AGAIN

;too many files open

;LKUPSA
;get another if in use

LKUPLA and LKUPSA are Kernal routines used primarily by BASIC DOS
commands to work around a user's open disk channels. The Kernal requires unique
logical device numbers (LA's), and the disk requires unique secondary addresses
(SA's); therefore BASIC must find alternative unused values whenever it needs to
establish a disk channel.

9. $FF5F SWAPPER ;switch between 40 and 80 columns

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:

Memory:
Flags:

none
system map
none
none
.A used
.X used
.Y used
local variables swapped
none

EXAMPLE:
LDA $D7
BMI is_80
JSR $FF5F

;check display mode

;branch if 80-column
;switch from 40 to 80

SWAPPER is an Editor utility used to switch between the 40-column VIC

(composite) video display and the 80-column 8563 (RGBI) video display. The
routine simply swaps local (associated with a particular screen) variables, TAB
tables and line wrap maps with those describing the other screen. The MSB of
MODE, location $D7, is toggled by SWAPPER to indicate the current display
mode: $80= 80-column, $00= 40-column.

449

450

COMMODORE 128

10. $FF62 DLCHR ;init 80-col character RAM

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:

Memory:
Flags:

none
system map
none
none
.A used
.X used
.Y used
8563 character RAM initialized
none

EXAMPLE:
JSR $FF62

;initialize 8563 char, defns.

DLCHR (alias INIT80) is an Editor utility to copy the VIC character

definitions from ROM ($D000-$DFFF, bank 14) to 8563 display RAM ($2000$3FFF, local to 8563-not in processor address space). The 8 by 8 VIC character
cells are padded with nulls ($00) to fill out the 8 by 16 8563 character cells.
Refer to Chapter 10, Programming the 80-Column (8563) Chip for details concerning
the 8563 font layout.

11. $FF65 PFKEY ;program a function key

PREPARATION:
Registers:

Memory:
Flags:
Calls:
RESULTS:
Registers:

Memory:
Flags:

.A = pointer to string adr

(lo/hi/bank)
.Y = string length
.X = key number (1-10)
system map
none
none
.A used
.X used
.Y used
PKYBUF, PKYDEF tables updated
.C = 0 if successful
.C = 1 if no room available

THE COMMODORE 128 OPERATING SYSTEM

EXAMPLE:
LDA
LDY
LDX
JSR
BCS

#$FA
#$06
#$0A
$FF65
NO ROOM

pointer to string address

length
key # (HELP key)
install new key def'n

>000FA 00 13 00
:ptr to $1300 bank 0
>01300 53 54 52 49 4E 47 :"string"
PFKEY (alias KEYSET) is an Editor utility to replace a C128 function key
string with a user's string. Keys 1-8 are F l - F 8 , 9 is the S H I F T
RUN string,
and 10 is the HELP string. The example above replaces the "help"
RETURN
string assigned at system initialization to the H E L P key with the string "string."
Both the key length table, PKYBUF ($1000-$1009), and the definition area,
PKYDEF ($100A-$10FF) are compressed and updated. The maximum length of all
ten strings is 246 characters. No change is made if there is insufficient room for a
new definition.

12. $FF68 SETBNK ;set bank for I/O operations

PREPARATION:
Registers:
Memory:
Flags:
Calls:
RESULTS:
Registers:
Memory:
Flags:

.A = BA, memory bank (0-15)

.X = FNBANK, filename bank
system map
none
SETNAM
none
BA, FNBANK updated
none

EXAMPLE:
See OPEN
SETBNK is a prerequisite for any memory I/O operations, and must be used
along with SETLFS and SETNAM prior to OPENing files, etc. BA ($C6) sets the
current 64KB memory bank for LOAD/SAVE/VERIFY operations. FNBANK ($C7)
indicates the bank in which the filename string is found. The Kernal routine
GETCFG is used to translate the given logical bank numbers (0-15). SETBNK is
often used along with SETNAM and SETLFS calls prior to OPEN's. See the Kernal
OPEN, LOAD and SAVE calls for examples.

451

452

COMMODORE 128

13. $FF6B GETCFG ;lookup MMU data for given bank

PREPARATION:
Registers:
Memory:
Flags:
Calls:

.X = logical bank # (0-15)

system map
none
none

RESULTS:
Registers:
Memory:
Flags:

.A = MMU configuration data

none
none

EXAMPLE:
LDX # $ 0 0
JSR $FF6B
STA $FF01

;logical bank 0 (RAM O)

;GETCFG
;setup MMU pre-config # 1

GETCFG allows a universal, logical approach to physical bank numbers by

providing a simple lookup conversion for obtaining the actual MMU configuration
data. In all cases where a bank number 0-15 is required, you can expect GETCFG
to be called to convert that number accordingly. There is no error checking; if the
given logical bank number is out of range the result is invalid. Refer to the Memory
Management Unit in the Commodore 128 section later in this chapter for details concerning memory configuration. The C128 Kernal memory banks are assigned as follows:
0.
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.

%00111111
%01111111
%10111111
%11111111
%00010110
%01010110
%10010110
%11010110
%00101010
%01101010
%10101010
%11101010
%00000110
%00001010
%00000001
%00000000

RAM 0 only
RAM 1 only
RAM 2 only
RAM 3 only
INT ROM, RAM 0,
INT ROM, RAM 1,
INT ROM, RAM 2,
INT ROM, RAM 3,
EXT ROM, RAM 0,
EXT ROM, RAM 1,
EXT ROM, RAM 2,
EXT ROM, RAM 3,
KERNAL, INT LO,
KERNAL, EXT LO,
KERNAL, BASIC,
KERNAL, BASIC,

I/O
I/O
I/O
I/O
I/O
I/O
I/O
I/O
RAM 0, I/O
RAM 0, I/O
RAM 0, CHAR ROM
RAM 0, I/O

THE COMMODORE 128 OPERATING SYSTEM

14. $FF6E JSRFAR ;gosub in another bank

15. $FF71 JMPFAR ;goto another bank

PREPARATION:
Registers:
Memory:

Flags:
Calls:
RESULTS:
Registers:
Memory:

Flags:

none
system
$02$03 $04 $05 $06 $07 $08 none
none

map, also:
bank (0-15)
PC high
PC low
.S (status)
.A
.X
.Y

none
as per call, also:
$05 ^ .S (status)
$06 ^ .A
$07 ^ .X
$08 ^ .Y
none

The two routines, JSRFAR and JMPFAR, enable code executing in the
system bank of memory to call (or JMP to) a routine in any other bank. In the case
of JSRFAR, a return will be made to the caller's bank. It should be noted that
JSRFAR calls JMPFAR, which calls GETCFG. When calling a non-system bank,
the user should take necessary precautions to ensure that interrupts (IRQ's and NMI's)
will be handled properly (or disabled beforehand). Both JSRFAR and JMPFAR are
RAM-based routines located in common (shared) RAM at $2CD and $2E3
respectively.
The following code illustrates how to call a subroutine in the second RAM
bank from the system bank. Note that we need not worry about IRQ's and NMI's in
this case because the system will handle them properly in any configuration that has
the Kernal ROM or any valid RAM bank in context at the top page of memory.
STY
STX
STA
PHP
PLA
STA

$08
$07
$06

$05

;assumes registers and status

;already setup for call

453

454

COMMODORE 128

LDA
LDY
LDX
STA
STY
STX

#1
#$20
#$00
$02
$03
$04

;want to call $2000 in bank 1

JSR $FF6E

;JSRFAR

LDA
PHA
LDA
LDX
LDY
PLP

;restore status and registers

$05
$06
$07
$08

16. $FF74 INDFET ;LDA (fetvec),Y from any bank

PREPARATION:
Registers:

Memory:
Flags:
Calls:
RESULTS:
Registers:
Memory:
Flags:

.A =
.X =
.Y =
setup
none
none

pointer to address
bank (0-15)
index
indirect vector

.A = data
.X used
none
status valid

EXAMPLE:
LDA
STA
LDA
STA
LDA
LDX
LDY
JSR
BEQ

#$00
$FA
#$20
$FB
#$FA
#$01
#$00
$FF74
etc

;setup to read $2000

;in bank 1
;LDA ($FA,RAM l),Y

INDFET enables applications to read data from any other bank. It sets up
FETVEC ($2AA), calls GETCFG to convert the bank number, and JMPs to code in

THE COMMODORE 128 OPERATING SYSTEM

common (shared) RAM at $2A2 which switches banks, loads the data, restores the
user's bank, and returns. When calling a non-system bank, the user should take
necessary precautions to ensure that interrupts (IRQ's and NMI's) will be handled
properly (or disabled beforehand).

17. $FF77 INDSTA ;STA (stavec),Y to any bank

PREPARATION:
Registers:

Memory:
Flags:
Calls:
RESULTS:
Registers:
Memory:
Flags:

.A =
.X =
.Y =
setup
setup
none
none

data
bank (0-15)
index
indirect vector
STAVEC ($2B9) pointer

.X used
changed per call
status invalid

EXAMPLE:
LDA
STA
LDA
STA
LDA
STA
LDA
LDX
LDY
JSR

#$00
$FA
#$20
$FB
#$FA
$2B9
data
#$01
#$00
$FF77

;setup write to $2000

;in bank 1
;STA ($FA,RAM l),Y

INDSTA enables applications to write data to any other bank. After you set
up STAVEC ($2B9), it calls GETCFG to convert the bank number and JMPs to
code in common (shared) RAM at $2AF which switches banks, stores the data,
restores your bank, and returns. When calling a nonsystem bank, the user should
take necessary precautions to ensure that interrupts (IRQ's and NMI's) will be
handled properly (or disabled beforehand).

455

456

COMMODORE 128

18. $FF7A INDCMP ;CMP (cmpvec),Y to any bank

PREPARATION:
Registers:

Memory:
Flags:
Calls:
RESULTS:
Registers:
Memory:
Flags:

.A =
.X =
.Y =
setup
setup
none
none

data
bank (0-15)
index
indirect vector
CMPVEC ($2C8) pointer

.X used
none
status valid

EXAMPLE:
LDA
STA
LDA
STA
LDA
STA
LDA
LDX
LDY
JSR
BEQ

#$00
$FA
#$20
$FB
#$FA
$2C3
data
#$01
#$00
$FF7A
same

;setup to verify $2000

;in bank 1
;CMP ($FA,RAM l),Y

CMPSTA enables applications to compare data to any other bank. After you
set up CMPVEC ($2C8), it calls GETCFG to convert the bank number and JMP's to
code in common (shared) RAM at $2BE which switches banks, compares the data,
restores your bank, and returns. When calling a nonsystem bank, the user should
take necessary precautions to ensure that interrupts (IRQ's and NMI's) will be
handled properly (or disabled beforehand).

19. $FF7D PRIMM ;print immediate utility

PREPARATION:
Registers:
Memory:
Flags:
Calls:

none
none
none
none

THE COMMODORE 128 OPERATING SYSTEM

RESULTS:
Registers:
Memory:
Flags:

none
none
none

EXAMPLE:
JSR $FF7D

;display following text

.BYTE "message"
.BYTE $00
;terminator
JMP continue

;execution resumes here

PRIMM is a Kernal utility used to print (to the default output device) an
ASCII string which immediately follows the call. The string must be no longer than
255 characters and is terminated by a null ($00) character. It cannot contain any
embedded null characters. Because PRIMM uses the system stack to find the string
and a return address, you must not JMP to PRIMM. There must be a valid address
on the stack.

CI28 DEVICE NUMBERS

The following are the device numbers for the Commodore 128:
0 ^
1^
2 ^
3 ~
4 ^

Keyboard
Cassette
RS-232
Screen (current)
Serial bus device:
4-1 usually printers
8-30 usually disks

Device number 31 should not be used. While it is specified to be a valid serial bus
address, when it is ORed with certain serial commands it results in a bad command,
hanging the bus and the serial drivers.

457

458

C O M M O D O R E 128

MEMORY MANAGEMENT IN
THE COMMODORE 128
COMMODORE 128 MODE
In Commodore 128 mode, all memory management organization depends on the currently selected memory configuration. In C128 BASIC and the Machine Language
Monitor, the memory is organized into sixteen default memory configurations. Different
portions of memory are present depending on the memory configuration. Figure 13-3
lists the default memory configurations of the C128 on system power-up.

BANK

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

CONFIGURATION

RAM(0) only
RAM(1) only
RAM(2) only (same as 0)
RAM(3) only (same as 1)
Internal ROM,RAM(O),I/O
Internal ROM,RAM(l),I/O
Internal R0M,RAM(2),I/0 (same as 4)
Internal R0M,RAM(3),I/0 (same as 5)
External ROM,RAM(O),I/O
External R0M,RAM(l),I/0
External R0M,RAM(2),I/0 (same as 8)
External R0M,RAM(3),I/0 (same as 9)
Kernal and Internal ROM (LOW), RAM(0),I/0
Kernal and External ROM (LOW), RAM(0),I/0
KernaI and BASIC ROM, RAM (0), Character ROM
Kernal and BASIC ROM, RAM(0), I/O

Figure 13-3. Memory Configuration (Bank) Table

THE MEMORY MANAGEMENT

UNIT (MMU)
In Commodore 128 mode, all memory management is controlled through a series of
I/O registers called the Memory Management Unit (MMU). The Memory Management Unit consists of memory locations that reside between $D500 and $D50B and
$FF00 and $FF04. The configuration register appears twice, once at $D500 and again at
$FF00. This is done in case I/O is switched out of the $D000-$DFFF memory range,
which makes the MMU registers from $D500-$D50B inaccessible.

THE COMMODORE 128 OPERATING SYSTEM

When this occurs, some features of the MMU are no longer available to the
programmer. So before switching out I/O in the $DOOO-$DFFF range, make sure you
have made all the manipulations you need on the MMU (particularly, preselecting the
preconfiguration register values for the load configuration registers). See Figure 13-4 for
a graphic depiction of the way the MMU registers map into memory.

$FF04

LCRD

- L0AD

CONFIGURATION

REG

$FFQ3

LCRC

- L0AD

C O N F I G U R A T I O N REG

$FF02

LCRB

- L0AD

C O N F I G U R A T I O N REG

$FF01

LCRA
CR

C O N F I G U R A T I O N REG
7 - L0AD
7 CONFIGURATION
REGISTER

$FF00

$D5QB

VR

$D50fl

-VERSION

REGISTER

PlH

PRGE

POINTER

HIGH

$D5Q9

PlL

PRGE

POINTER

L0W

$D5Q8

P0H

PRGE

POINTER

HIGH

$0507

P0L

POINTER

L0W

PRGE
RAM

C0NFIGURRTI0N

REGISTER

$0506

RCR

$D505

MCR

$D504

PCRD

PRECONFIGURATION

REGISTER

$D5Q3

PCRC

PRECONFIGURATION

REGISTER

$D502

M0DE

C0NFIGURRTI0N

REGISTER

PCRB

PRECONFIGURATION

REGISTER

$D501

PCRH

PRECONFIGURATION

REGISTER

$0500

CR

CONFIGURATION

REGISTER

Figure 13-4. MMU Register Map

HOW T O SWITCH BANKS

In BASIC, type the BANK command to switch from one bank to another as follows:
BANK n
where n is a digit between 0 and 15. When your application program needs to access a
bank in which the microprocessor is not in context (for SYS, PEEK, POKE, and WAIT
commands) use the BANK command to reach layers of the computer's memory that are
not accessible in the current bank. For instance, suppose you want to access the VIC
chip when you are doing graphics in the first part of your program. The next segment

459

460

COMMODORE 128

of your program needs to access the character ROM, which is only visible to the 8502 in
bank 14. Change to bank 14; then read the character ROM data, which makes up the
images of the characters in the character sets. While the microprocessor is "looking" in
bank 14, the VIC chip is not available to the microprocessor, so you must issue another
BANK command in order to return to (a configuration containing I/O and) processing
VIC video information.
In machine language, switching banks is a little more difficult. You must change
the value of the registers [in particular the Configuration Register (CR), Load Configuration Register (LCR) and Preconfiguration Register (PCR)], either directly or
indirectly. The Kernal routine GETCFG allows you to change configurations and
maintains the same ones used by BASIC and the Monitor as they appear in Figure 13-3.
There are four PCR's and four LCR's (as shown in Figure 13-4). Each PCR corresponds
directly to a LCR. PCR A pertains to LCR A, PCR B corresponds to LCR B, and so on.
To change the value of the Configuration Register directly, perform a write
operation (STA, STX, STY) to the Configuration Register.
To change the value of the Configuration Register indirectly, write a value
specifying a memory configuration to the Preconfiguration Register. When a subsequent
store instruction is performed to the corresponding Load Configuration Register, the
value previously stored in the corresponding PCR is loaded into the CR. When a store
instruction is executed on an LCR, the value in the corresponding PCR is loaded into the
CR and the memory management organization conforms to the values associated with
that memory management scheme. The value written to the LCR is of no consequence;
any value triggers the preconfiguration mechanism.

NOTE: Basic expects the LCR's and PCR's to be left alone. If you use
them to manage memory in your application, do not plan on using BASIC.

THE CONFIGURATION REGISTER

The Configuration Register (CR) is the most important register in the MMU. It specifies
and organizes the ROM, RAM and input/output configurations for the entire Commodore 128 memory in C128 mode. (The MMU is not present at all in the C64 memory
map.) The CR is located at address $D500 when I/O is available and at address $FF00 at
all times. When I/O functions are disabled, the MMU memory disappears between
$D500 and $D50B. The MMU memory is always present between $FF00 and $FF04.
Each of the eight bits in the CR controls a separate memory function.
Bit 0 (zero) in the Configuration Register specifies whether I/O Registers are
available, or whether ROM (High) is present in the memory range $D000 through
$DFFF. The I/O Registers consist of the registers of the VIC chip, SID chip, MMU
(from $D500 through $D50B); CIA number 1, which controls the joystick port; and CIA
number 2, which controls the serial bus and user port. If bit 0 is high (equal to 1), ROM
or RAM is present in the range $D000 through $DFFF, depending upon the values of
the ROM HIGH bits (4 and 5) in this register. If bit 0 is low (equal to 0), I/O is present
in this range. The value of bit 0 on power-up is 0.

THE COMMODORE 128 OPERATING SYSTEM

When I/O is switched out of (not present in) this range, the registers in the MMU
disappear from the memory map in the range $D500 through $D50B. The memory management is then controlled through the MMU registers at locations $FF00 through $FF04. Any
write operation to an LCR ($FF01-$FF04) loads the corresponding PCR value (currently
invisible to the 8502) into the CR. Reading an LCR returns the value stored in the
currently inaccessible PCR. The MMU registers ranging from $FF00 through $FF04 are
always present in the Commodore 128 memory, regardless of the memory configuration.
Bit 1 in the CR specifies how the microprocessor accesses the address range $4000
through $7FFF, called ROM LOW memory. If bit 1 is high, the microprocessor
accesses RAM in this range. If bit 1 is low (equal to 0), the microprocessor maps in the
BASIC LOW ROM in that range. Upon power-up or reset, this bit is set low, so
BASIC is available to the user as soon as the computer is turned on.
Bits 2 and 3 determine the type of memory that resides in the midrange of memory,
the address range $8000 through $BFFF. If both bits 2 and 3 are set high, RAM is
placed in this range. If bit 2 is high and 3 is low, INTERNAL FUNCTION ROM is
placed here. If bit 2 is low and 3 is high, EXTERNAL FUNCTION ROM appears. If
bits 2 and 3 are low, the BASIC HIGH ROM is placed here. Upon power-up or reset,
the MMU sets both bits 2 and 3 low, so BASIC is available to the user immediately.
Bits 4 and 5 work similarly to bits 2 and 3 and specify memory in the range $C000
through $FFFF, referred to as HIGH memory. If bits 4 and 5 are set high, RAM is
placed in this range. If bit 4 is high and 5 is low, INTERNAL FUNCTION ROM is
placed. If bit 4 is low and 5 is high, EXTERNAL FUNCTION ROM appears. If bits 4
and 5 are low, the Kernal and character ROMs are placed here. Upon power-up or reset,
bits 4 and 5 are set low, so the Kernal and character ROM are available to the user at once.
Note that bit 0 in the Configuration Register, the bit that switches in and out I/O in
address range $D000 through $DFFF, overrides the memory organization for bits 4 and 5.
If bit 0 is set high (1), the I/O Registers are not in place in the address range $D000
through $DFFF. Either the character ROM, internal or external function ROM or RAM
is located in this range, depending on the value of bits 4 and 5 of the configuration
register. If bit 0 in the Configuration Register is set low (0), the Input/Output registers
are present between $D000 through $DFFF, regardless of the value of bits 4 and 5 of the
configuration register. This means no matter what memory configuration is chosen
between $C000 and $FFFF with bits 4 and 5, if bit 0 is set low (0), the character ROM
(or whatever was originally in this address range) is overlaid by the I/O registers and
becomes unavailable to the microprocessor. This is why the character ROM and the I/O
registers are never available at the same time.
Finally, the last two bits of the MMU, 6 and 7, determine the RAM BANK
selection. For the base system of 128K, only bit 6 is significant; bit 7 is not implemented. When bit 6 is high (1), RAM bank 1 is selected. When bit 6 is low (0), RAM
bank 0 is selected.
The 128K of RAM is organized into two 64K RAM banks. The microprocessor
only addresses 64K at a time, but since the two 64K RAM banks can be switched in and
out so quickly, the computer acts as though it addresses 128K at the same time. When
one RAM bank is being addressed by the microprocessor, the other bank stores
information to be processed once it is banked in. Portions of both banks can be shared in
memory at the same time. This is called Common RAM, and is discussed in the section

461

462

COMMODORE 128

The RAM Configuration Register. RAM bank 0 is used typically for BASIC text area,
while RAM bank 1 is used for BASIC arrays and variable storage.
As indicated above, the MMU has a feature that allows a portion of RAM to be
common for the two RAM banks. The RAM Configuration Register controls the amount
of common RAM. This is discussed in detail later in this section under the description of
the RAM Configuration Register.
Figure 13-5 is a diagram of the Configuration Register, showing how the bits
control each memory organization.

BANK SELECT

00 = RAM BANK 0
01 = RAM BANK 1
10 = EXPANSION BANK 2
11 = EXPANSION BANK 3

H I SPACE
($C000-$FFFF)

MID-SPACE
($8000-$BFFF)

00 = KERNAL ROM
01 = I N T . FUNCTION ROM
10 = EXT. FUNCTION ROM
11 = RAM

00 = BASIC ROM H I
01 = I N T . FUNCTION ROM
10 = EXT. FUNCTION ROM
ll=RAM

LO-SPACE
($4000$7FFF)

I/O SPACE
($D000$DFFF)

0 = BASIC
ROM LO
l=RAM

0 = 1/0
REGISTERS
1 = RAM^ROM

Figure 13-5. Configuration Register

PRECONFIGURING COMMODORE 128 MEMORY

As noted, the Configuration Register in the MMU is the means by which the Commodore 128 organizes the memory layout. Commodore 128 memory management has a
mechanism that allows the programmer to set up four predefined memory configurations besides the one already operating. The four Preconfiguration Registers (PCR)
and the four Load Configuration Registers (LCR) are designed to provide this feature.
When a different memory management structure is desired, a previously defined
configuration in one of the Preconfiguration Registers can be chosen easily and
instantly.
This mechanism allows the programmer to preset several memory configurations
and, with a single store instruction to an LCR, reorganize the entire memory layout
instantly. This enables the programmer to use several memory organizations interchangeably; thus, if one part of your program requires one memory configuration and
another part requires a different configuration, you can switch back and forth between
the two, each with a single store instruction, once you predefine the alternate memory
setup in one of the Preconfiguration Registers.
To alter memory management through this preconfiguration mechanism, you
must change the value of the Preconfiguration Register. The four PCR's and four
LCR's of the MMU are shown in the MMU Register Map in Figure 13-6. Each
PCR corresponds directly to an LCR (i.e., PCR A pertains to LCR A, PCR B

THE COMMODORE 128 OPERATING SYSTEM

corresponds to LCR B, and so on). The format for the Load Configuration and
Preconfiguration Registers is the same as for the Configuration Register. The four LCRs
and four PCRs are all initialized to zero.

$FF04

LCRD

$FF03

LCRC

$FFQ2

LCRB"

$FFQ1

LCRR

$FF0O

CR

$D50B

VR

$D50R

PlH

$D509

PlL

$D508

PGH

$D507

PQL

$D506

RCR

$D505

MCR

$D504

PCRD

$D503

PCRC

$D502

PCRB

$D501-

"PCRR

$D50O

CR

LORD

C O N F I G U R R T I ON

C O N F I G U R R T I ON

REG

REGISTER

P R E C O N F I G U R R T I ON R E G I S T E R
C O N F I G O R R T I ON R E G I S T E R

fl

Figure l 3 ^ . MMU Register Map

To directly change the value of the Configuration Register (therefore bypassing
the preconfiguration mechanism), perform a write operation (STA, STX, STY) directly
to the Configuration Register at either $D500 or $FF00.
To indirectly change the value of the Configuration Register (therefore utilizing
the preconfiguration mechanism), perform a write operation (STA, STX, STY) to the
Preconfiguration Register. This loads a value into the PCR. When a subsequent store
instruction is performed to the corresponding Load Configuration Register, the value
that was previously stored in the corresponding PCR is loaded into the CR. The store
instruction acts as a triggering mechanism that passes the contents of a PCR into the CR.
When a store instruction is executed upon an LCR, the value in the corresponding PCR
is loaded into the CR and memory management organization conforms to the value
associated with that PCR.
For example, to alter the memory management organization specified on power-up,
use the following machine language segment:

463

464

C O M M O D O R E 128

PART 1

PART 2

LDA # $ 0 E

STA $D501

Load accumulator with 14

This selects
I/O ($DOOO-$DFFF)
RAM ($4000-$7FFF, $8000-$BFFF)
Kernal and Character ROM ($C000-$FFFF)
RAM Bank 0
Store in PCR Ano immediate results

STA $FF01

Place interim part of the program here

Write to LCR A, selects above configuration

In this program segment, PART 1 initializes PCR A ($D501) with the value 14
($0E), which performs no immediate result. When PART 2 is encountered, the STA
instruction performs a write operation to location $FF01, which triggers the preconfiguration
mechanism and loads the value from PCR A into the Configuration Register. The store
instruction value is not significant; it must operate only on the address, and any store
instruction works. Once this instruction is executed, the memory management organization is immediately changed according to the value in the appropriate PCR, in this case
PCR A ($D501).
The value 14 ($0E) loaded into PCR A selects the following memory organization:

TYPE

ADDRESS RANGE

BIT(S) AFFECTED IN CR

I/O
RAM
RAM
Kernal, Char
RAM BANK 0

$D000-$DFFF
$4000-$7FFF
$8000-$BFFF
$C000-$FFFF

0
1
2,3
4,5
6,7

14 = $0E = 0000 1110 (binary)

It is good practice to initialize the PCR's in the beginning of your program, as in

PART 1 of the above program segment. Then place the interim portion of your program
in memory. PART 2 marks the place in your program where you are actually going
to alter the memory management setup. For the utmost speed and processor efficiency,
use absolute addressing for the MMU registers, as in the above example.
As previously noted, when the Input/Output Registers are switched out, the registers
of the MMU that appear in memory range $D500-$D50B are unavailable to the microprocessor. When this occurs, a write operation to an LCR still loads the corresponding PCR
value (currently invisible to the 8502) into the CR, even though the PCR's are not accessible to the microprocessor when I/O is switched out. If you switch out I/O, make sure to
set up the PCR's first, which are present when bit 0 of the Configuration Register is equal
to 0. However, the Load Configuration Registers are available at all times since they
appear in the address range $FF00-$FF04. If I/O is switched out, the PCR's must be

THE COMMODORE 128 OPERATING SYSTEM

set prior to switching out I/O in order for them to be of any service. Note that BASIC uses
the PCRs; if you alter them while BASIC is resident, you may obtain unpredictable results.
The MMU registers control the memory organization for RAM, BASIC, Kernal
and character ROM, internal and external function ROM, and I/O. The MMU has
additional registers that determine the mode (C128, C64 or CP/M) in which the
Commodore 128 operates, the common RAM configurations, and the location of pages
0 and 1. The registers in the MMU that control these operations are the Mode
Configuration Register (MCR), the RAM Configuration Register (RCR), and the
Page Pointers respectively. The following sections explain how these additional registers of the Memory Management Unit operate.

THE MODE CONFIGURATION REGISTER

The Mode Configuration Register (MCR) specifies which microprocessor is currently in
operation (8502, Z80A) and which operating system mode is currently invoked (C128 or
C64). The MCR is located at address $D505. As in the other registers in the MMU,
each bit in the Mode Configuration Register controls a separate and independent
operation.
Bit 0 determines which microprocessor is in control of the Commodore 128. Bit 0 is
powered-up low so the Z80 microprocessor initiates control of the computer. The Z80
performs a small start-up procedure, then bit 0 is set to a 1 and the 8502 takes over
if no CP/M system disk is present in the disk drive.
When the Commodore 128 is first powered-up or reset and the disk drive detects
the CP/M operating system diskette in the drive, the Z80A microprocessor BOOTs the
CP/M operating system from disk. The value of bit 0 in the Mode Configuration
Register in this case is 0. When the Z80A takes control of the Commodore 128, all
memory references from $0000 through $0FFF are translated to $D000 through $DFFF,
where the CP/M BIOS exists in ROM. For memory accesses in the range $0000 through
$0FFF in the Z80 BIOS, the memory status lines MS0 and MS1 are brought low to
reflect ROM; otherwise they are high. Note that C64 mode and Z80A mode is an
undefined configuration.
Bits 1 and 2 are not used. They are reserved for future expansion. IF0, bit 3 sets
an input for FAST serial. It is not used as an input port at all.
Bit 3 is the fast serial (FSDIR) disk drive control bit. It acts like a bit in a
bidirectional 6529 port, which means it acts differently depending upon whether the bit
is used for input or output operation. As an output signal, bit 3 controls the direction of
the data in the disk drive data buffer. The MMU pin FSDIR reflects the status of bit 3,
which is reset to zero upon power-up. If bit 3 is equal to 1, an output operation occurs;
selecting a data direction for the data in the serial bus buffer. If zero, bit 3 sets
an input for FAST serial. It is not used as an input port at all.
Bits 4 and 5 are the /GAME and /EXROM sense bits respectively. These cartridge
control lines initiate Commodore 64 mode and act as the /GAME and /EXROM
hardware lines as in the Commodore 64. When these control lines detect a cartridge in
the Commodore 128 expansion port, C64 mode is instantly enabled, the computer acts
as a Commodore 64 and takes its instructions from the software built into the cartridge.
Upon power-up, /GAME and /EXROM are pulled as inputs. If either one is low, C64

465

466

C O M M O D O R E 128

mode is selected. Thus, a C128 cartridge should not pull these lines low on power-up.
In C128 mode, these lines are active as I/O lines (latched) to the expansion port. These
can be used as input or output lines, but make sure they are not brought low upon
power-up in C128 mode.
Bit 6 selects the operating system that takes over the Commodore 128. Upon
power-up or reset, this bit is cleared (0) to enable all of the MMU registers and
Commodore 128 mode features. Setting this bit high (1) initiates C64 mode.
Bit 7, a read-only bit, indicates whether the 4 0 / 8 0 D I S P L A Y key is in
the up (40-column) or down (80-column) position. The value of bit 7 is high (1) if
the 4 0 / 8 0 key is in the up position. The value of bit 7 is low (0) if the 4 0 / 8 0
D I S P L A Y key is in the down position.
This is useful in certain application programs that utilize both the 40- and
80-column displays. For instance, check the value of this bit to see if the user is viewing
the VIC screen. If so, carry on with the program; otherwise display a message telling the
user to switch from the 80-column screen to the VIC (40-column) screen in order to
display a VIC bit map. This may be invalid if the user typed < E S C > X to switch
screens. See the SCORG Kernal routine.
See Figure 13-7 for a summary of Mode Configuration Register activities.

$D505

Mode Configuration Register

VALUE
BIT

0
1
2
3
4
5

FUNCTION DESCRIPTION

HIGH

/Select microprocessor
8502

Unused

Unused
Fast serial DD control
Fast serial out
/GAME Access game cartridge
(C64 mode only)
/EXROM Access external
software cartridge (C64 mode
only)
Select operating system
C64 mode
(MMU disappears
from memory map)
Read 4 0 / 8 0 key
40/80 column
position
key is UP

Figure 13-7. Mode Configuration Register Summary

LOW

Z80A (inverted)

Fast serial in
C64 mode set
on power up
C64 mode set
on power up
C128 mode,
assert MMU
registers
40/80 column
key is DOWN

THE COMMODORE 128 OPERATING SYSTEM

THE RAM CONFIGURATION REGISTER

The RAM Configuration Register (RCR) in the MMU specifies the amount of Common
RAM shared between the two 64K RAM banks, how the RAM is shared, and which
bank is delegated for the VIC chip. The value of the bits in the RCR determine how
each RAM bank is allocated for specific purposes. The RAM Configuration Register is
located within the I/O block at address $D506.
Bits 0 and 1 determine the amount of shared RAM between banks. If both bits 0
and 1 equal 0, lK of RAM becomes common. If bit 0 is equal to 1 (high) and bit 1 is
low (0), then 4K of common RAM is shared between banks. If bit 0 is low (0) and bit 1
is high (1), then 8K is common, and if both bits 2 and 3 are high (1), then 16K of RAM
becomes common. (These bits have no effect in Commodore 64 mode). The reset values
of these bits are both 0. See Figure 13-8 to understand how the two RAM banks share
common RAM.

467

468

COMMODORE 128

BANK 0

BANK 0

BANK 1

BANK 1

Hi Common RAM

Hi Common RAM

$F000 -

$F000

$OFFF
Low Common RAM

$03FF
Low Common RAM

4KCOMMON RAM

1K COMMON RAM

BANK 0

BANK 0

BANK 1

Hi Common
RAM

BANK 1

Hi
Common
RAM

$E000

$cooo -

$OFFF

$03FF
Low Common
RAM

8K COMMON RAM

Low
Common
RAM

16K COMMON RAM

Figure 13-8. Common RAM

Bits 2 and 3 specify which portions of the two RAM banks are common, if at all. If
both bits are low (0), no RAM sharing occurs. If bit 2 is set high (1) and bit 3 is low (0),

T H E C O M M O D O R E 128 O P E R A T I N G S Y S T E M

a section of the bottom of RAM bank 0 replaces the corresponding section of RAM bank
1 for all RAM address accesses. If bit 3 is set high (1) and bit 2 is set low (0), a section
of the top RAM bank 0 replaces the corresponding section of RAM bank 1 for all RAM
address accesses. If both bits 2 and 3 equal 1 (high), RAM is common to both the top
and bottom of the RAM banks. Upon power-up or reset, bits 2 and 3 are set to 0, and no
RAM is shared between banks. From a hardware standpoint, the 128K MMU selects the
common RAM by forcing the CAS0 enable line low and CAS1 enable line high for all
common memory accesses.
Bits 4 and 5 have no assigned function. They are reserved for future expansion.
Bits 6 and 7 in the RCR operate as a RAM bank pointer to tell the VIC chip which
portion of RAM to use. At the present time, bit 7 is ignored. It too is reserved for
future RAM expansion. When bit 6 is low (0) (driving CAS0 low), the VIC chip is told
to look in RAM bank 0. When bit 6 is set high (1) (driving CAS1 low), the VIC chip is
steered into RAM bank 1. Either setup allows the VIC chip RAM bank to be selected
from the microprocessor RAM bank independently.
When the microprocessor speed is increased to 2MHz, the VIC chip is disabled
and the 80-column (8563) chip takes over the video processing. The VIC chip is
affected by holding the AEC hardware line high. The disabling of the VIC chip is not
directly affected by the actions of the MMU.
Figure 13-9 summarizes the RAM Configuration Register activities.

$D506

RAM Configuration Register

BITS

FUNCTIONAL DESCRIPTION

0 - Determine amount of shared RAM between RAM banks

0 0 = lK
0 1 = 4K
1 0 = 8K
1 1 = 16K
3

common
common
common
common

RAM
RAM
RAM
RAM

2 Determine which portions of RAM are shared

0 0 = No common RAM
0 1 = Bottom of RAM bank 0 is common
1 0 = Top of RAM bank 0 is common
1 1 = Both top and bottom of RAM bank 0 are common
5

4 - Not implemented; reserved for future expansion

6 - Selects RAM bank for the VIC chip (Bit 7 is ignored)

X 0 - Select Bank 0 for VIC chip

X 1 = Select Bank 1 for VIC chip
Note: X = not implemented

Figure 13-9. RAM Configuration Register Summary

469

470

COMMODORE 128

THE PAGE POINTERS

The Commodore 128 has a feature that allows you to relocate page 0 ($00-$FF) and
page 1 ($100-$lFF) of memory. Certain applications may require you to keep page 0
intact while running BASIC, switch out the BASIC ROM, resume processing within the
control of your machine language program, and then switch 0 page and the BASIC
ROM back in. Instead of transferring 0 page with the machine language monitor, the
page pointers make it easy to relocate pages 0 and 1. Four registers within the MMU,
called the page pointers, allow you to do this. The page pointers are located within the
I/O block in the range $D507 through $D50A. The page pointers follow the standard
8502 low-byte/high-byte format. Here are the actual addresses of the high and low bytes
of the page pointers:
$D507
$D508
$D509
$D50A

Page
Page
Page
Page

0 Pointer
0 Pointer
1 Pointer
1 Pointer

(low)
(high)
(low)
(high)

Bit 0 of the high byte page pointers corresponds to the RAM bank number
for any page 0 address access. Bit 0 controls the generation of the CAS0 hardware
control line if it is low and the CAS1 line if it is high, and bits 1 and 3 are
ignored.
To relocate page 0, perform a write operation on the high-byte 0 page pointer.
This is stored in the high-byte page pointer location and has no direct result until a write
operation is performed on the low-byte 0 page pointer. When this occurs, bits 0 through
7 of the low-byte page pointer correspond to the Translated Address lines TA8 through
TA15 for any 0 page address reference, which relocates the 0 page. Any subsequent 0
page address is relayed to the new page zero.
The page 1 pointer works the same way. Both pairs of pointers are initialized to 0
upon power-up, placing pages 0 and 1 in actual page 0 and page 1 locations.
It is important to note that memory addresses 0 and 1 are always available at those
absolute address references, regardless of whether pages zero or one are relocated.
The page zero low-byte pointer directly replaces the high-order address of zero
page (normally 00). When pages zero and one are directed to locations in RAM memory
above page one, the MMU translates the addresses back to the normal locations of pages
zero and one, effectively swapping those two pages of memory. This address translation
applies only to RAM; ROM and I/O registers are not back-translated. VIC chip
addresses are not translated back to their original memory locations, so you must ensure
that you do not place page zero or one in the address of the VIC chip. The ROM
appearing in these address ranges still overlays the RAM regardless of whether the RAM
is zero page, page one or any other page of RAM memory. If you need to use the
Kernal, the necessary variables required for the Kernal routine must be placed in
memory where the Kernal is in context, Machine Language Monitor bank 15 ($0F) for
example.

THE COMMODORE 128 OPERATING SYSTEM

Bit 0 of both high-byte page pointers (0 and 1) corresponds to the RAM bank
number for any address access in page zero or one. The page zero high byte (bit 0)
normally overrides the RAM bank set by the configuration register. However, if
common RAM (at the bottom of RAM bank 0) is specified, the high-byte pointer for
pages zero and one is ignored and pages zero and one appear in common RAM. Otherwise, if common RAM is not allocated, pages zero and one appear where you specify
according to the contents of the page pointers. In other words, common RAM takes priority
over the page pointers, if common RAM is allocated by the RAM configuration register.
This feature of relocatable page zero and page one provides many benefits to the
programmer. This allows machine language programs to create several pages of zero
page variables or several different stacks. When you need to access the additional zero
page variables or extra 256 bytes of the stack, simply change the pointer to look at the
next page. This provides additional speed in your programs since you may use zero page
addressing for subsequent zero pages. You can even place zero page in screen memory
for extra fast writing to the screen. In addition, it gives you a way to implement deeper
levels of subroutines since you have a larger stack area. Remember, though, to leave
three bytes on the top of the stack for interrupt requests and servicing.

THE SYSTEM VERSION REGISTER

The System Version Register, located in address $D50B, contains a value that tells the
user which version of the MMU is inside the C128 and how large the memory is. Bits 0
through 3 contain the MMU version number. Bits 4 through 7 contain a value (in
memory blocks) pertaining to the size of the C128 memory. This allows the programmer
to check the version of the C128 and the memory size, and make it compatible with
systems that will be expanded in the future. The current version of the C128 contains the
value $20, signifying two 64K blocks.

AUTO STARTING A ROM

APPLICATION CARTRIDGE
Many of you may want to place your application program in a cartridge which plugs into
the expansion port. In order to automatically start the program as soon as you turn on
the computer, you must place a particular coded sequence in the first 6 bytes where the
external (or internal) ROM cartridge maps into memory. Here's the auto start sequence
in both C128 and C64 modes.

COMMODORE 128 MODE

Any C64 cartridge is asserted automatically if the system recognizes the /GAME or
/EXROM as being pulled low.
If any C128 cartridges are installed into the expansion port:
1. Log the cartridge I.D. into the Physical Address Table (PAT).
2. If the I.D. equals 1, call the cold start vector (which may RTS).

471

472

COMMODORE 128

The first 9 bytes of the Commodore 128 auto start sequence are:

BYTE

$X000
$X003
$X006
$X007
$X008
$X009

Cold Start Vector

Warm Start Vector (not used but must be specified)
Cartridge I.D. (The I.D. = 1 for an auto start card)
The ASCII Character "C" with the high bit set
The ASCII Character "B" with the high bit set
The ASCII Character "M" with the high bit set

where X is the hexadecimal digit " 8 " for $8000 or " C " for $C000.
There are four slots where cartridges (ROM's) may plug in (two internal, two
external). They must follow the sequence described above, whether they are internal or
external.

COMMODORE 64 MODE
The first 10 bytes of the Commodore 64 auto start sequence are:

BYTE

$X000
$X003
$X006
$X007
$X008
$X009
$X00A

Cold Start Vector

Warm Start Vector
The ASCII Character "C" with the high bit set
The ASCII Character "B" with the high bit set
The ASCII Character "M"' with the high bit set
The ASCII Character "8" with the high bit set
The ASCII Character "0" with the high bit set

where X is the hexadecimal digit " 8 " for $8000 or " C " for $C000.
The recommended cartridge header for both operational modes is as follows:
SEI
JMP START
NOP
NOP

This header is recommended so that the interrupt disable status bit is set when
control is passed to the software in the cartridge ROM.

THE COMMODORE 128 OPERATING SYSTEM

THE COMMODORE 128

SCREEN EDITOR
The Commodore screen editor is among the easiest to use of all screen editors. As soon
as you turn on the computer, the screen editor is available to you. You don't have to call
any additional text editors. Using the keys for manipulating text, the screen editor gives
you more freedom than most other editors.

CI28 EDITOR ESCAPE CODES

To use the following ESCAPE functions, press the
the key for the function you want.

ESC A P E

key and then press

KEY

FUNCTION

A
B
C
D
E
F
G
H
I
J
K
L
M
N

Enable auto-insert mode

Set bottom right of screen window at cursor position
Disable auto-insert mode
Delete current line
Set cursor to nonflashing mode
Set cursor to flashing mode
Enable bell (control-G)
Disable bell
Insert line
Move to start of current line
Move to end of current line
Enable scrolling
Disable scrolling
Return screen to normal (nonreverse video) state (80-column screen only)
Cancel insert, quote, underline, flash and reverse modes
Erase to start of current line
Erase to end of current line
Set screen to reverse video (80-column screen only)
Change to block cursor (80-column screen only)
Set top left of screen window at cursor position
Change to underline cursor (80-column screen only)
Scroll up
Scroll down
Swap 40/80-column display output device
Set default tab stops (8 spaces)
Clear all tab stops
Clear to end of screen

Q
R
S
T
U
V

w
X
Y
Z

473

474

C O M M O D O R E 128

CI28 EDITOR CONTROL CODES

The following control characters in the CBM ASCII table have been added or changed
from those found in the C64. Codes not shown in this table have the same function as
found in the C64.

CHR$

KEYBOARD

VALUE

CONTROL

CHARACTER FUNCTION

2
7
9
10
11
12
15
24
27
130
143

B
G
I
J
K
L
0
X

Underline ON (80-coIumn screen only)

Produces bell tone
Tab character
Line feed character
Disable shift Commodore key (formerly code 9)
Enable shift Commodore key (formerly code 8)
Turn ON flash on (80-column screen only)
Tab set/clear
Escape character
Underline OFF (80-column screen only)
Turn flash OFF (80-column screen only)

CI28 EDITOR JUMP TABLE

The editor calls listed below are a set of extensions to the standard CBM jump table.
They are specifically for the C128 and should not be considered as permanent additions
to the standard jump table. They are all true subroutines and terminate with the RTS
instruction. As with all Kernal calls, the system configuration (high ROM, RAM-0 and
I/O) must be in context at the time of the call.

THE COMMODORE 128 OPERATING SYSTEM

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.

$C000
$C003
$C006
$C009
$C00C
$C00F
$C012
$C015
$C018
$C018
$C01E
$C021
$C024
$C027
$C02A
$C02D
$C033
$C04C
$334
$336
$338
$33A
$33C
$33E

CINT
DISPLY
LP2
LOOP5
PRINT
SCRORG
SCNKEY
REPEAT
PLOT
CURSOR
ESCAPE
KEYSET
IRQ
INIT80
SWAPPER
WINDOW
LDTB2
LDTB1
CONTRL
SHIFTD
ESCAPE
KEYVEC
KEYCHK
DECODE

Initialize editor and screen

display .A = char, .X = color
get a key from irq buffer in .A
get a chr from screen line in .A
print character in .A
get size of current window
scan keyboard subroutine
repeat key logic and CKIT2
read or set cursor position
move 8563 cursor subroutine
execute escape function
redefine a programmable key
irq entry
initialize 80-column char set
40/80 mode change
set UL or BR of window
screen lines low byte table
screen lines high byte table
print C T R L indirect
print S H F T indirect
print E S C indirect
keyscan logic indirect
keyscan store indirect
keyboard decode table vectors

Entries 17, 18, and 24 are table pointers, and are not callable routines. Entries 19-23
are considered indirect vectors, not true entry points.
This chapter has presented the Commodore 128 operating system. Chapter 16
provides information on CP/M on the Commodore 128 and Commodore 64 memory
maps.

475

j4
CP/M 3.0
ON THE
COMMODORE 128

477

478

COMMODORE 128

CP/M is a microprocessor operating system produced by Digital Research, Inc. (DRI).

The version of CP/M used on the Commodore 128 is CP/M Plus Version 3.0. In this
chapter, CP/M is generally referred to as CP/M 3.0, or simply CP/M.
This chapter summarizes the non-C128-dependent aspects of CP/M on the Commodore
128. For detailed information on C128-dependent CP/M 3.0, see Appendix K of this
guide. For detailed information on non-C128-dependent CP/M 3.0, see the Commodoreproduced volume that includes DRI's CP/M Plus User's Guide, Programmer's Guide,
and System Guide.

REQUIREMENTS FOR A CP/M 3.0 SYSTEM

The general requirements for CP/M 3.0 are:

A computer containing a Z80 microprocessor.

A console consisting of a keyboard and a display screen.
At least one floppy disk drive.
CP/M system software on disk.

CP/M 3.0 on the Commodore 128 Personal Computer normally consists of the
following elements:

A built-in Z80 microprocessor.

A console consisting of the full Commodore 128 keyboard and an 80-column
monitor.
The Commodore 1571 fast disk drive.
The CP/M system disk, which includes the CP/M 3.0 system, an extensive
HELP utility program and a number of other utility programs.
NOTE: CP/M can also be used with a 40-column monitor. To view all
80 columns of display, you must scroll the screen horizontally by pressing the C O N T R O L key and the appropriate C U R S O R key
(left or right).

CP/M 3.0 can also be used with the 1541 disk drive. In this case, only singlesided GCR disks can be used, and the speed of operation will be approximately
one-tenth the speed achieved using the 1571 disk drive. (See the discussion of disk
formats later in this chapter for more details.)

CP/M 3.0 O N THE COMMODORE 128

COMMODORE ENHANCEMENTS
TO CP/M 3.0
Commodore has added a number of enhancements to CP/M 3.0. These enhancements
tailor the capabilities of the Commodore 128 to those of CP/M 3.0. They include such
things as a selectively displayed disk status line, a virtual disk drive, local/remote
handling of keyboard codes, programmable function keys (strings) and a number of
additional functions/characters that are assigned to various keys. These enhancements
are described at appropriate points in this chapter.

CP/M FILES
There are two types of CP/M files:

PROGRAM or C O M M A N D files, consisting of a series of instructions that

the computer follows to achieve a specified result.
D A T A files, consisting usually of a collection of related information (e.g., a
list ofcustomer names and addresses; inventory records; accounting records; the
text of a document).

FILE SPECIFICATION
A CP/M file is identified by a file specification that can consist of up to four individual
elements, as follows:

Drive Specifier (optional), consisting of a single letter, followed by a colon.

Each disk drive is assigned a letter, in the range A through E. (E denotes a
virtual drive, as explained later in this chapter.)
Filename (mandatory), which can be from one to eight characters long. (Note
that this is the only mandatory element of the file specification.)
Filetype (optional), consisting of one to three characters. It must be separated
from the filename by a period.
Password (optional), which can be from one to eight characters. Must be
separated from the filetype (or filename, if no filetype is included) by a
semicolon.

EXAMPLE:
The following file specification contains all four possible elements, all separated by the
appropriate symbols:
A: DOCUMENT. LAW ;FIREB IRD

479

480

C O M M O D O R E 128

USER NUMBER
CP/M 3.0 further identifies all files by assigning each one a user number, which can
range from 0 to 15. CP/M 3.0 assigns the user number to a file when the file is created.
User numbers allow you to separate your files into sixteen file groups.
Any user number other than 0 must precede the drive specifier. User 0, which is
the default user number, is not displayed in the prompt.
If a file resides in user 0 and is marked with a system file attribute, that file can
be accessed from any user number. Otherwise, a command can access only those files
that have the current user number.

CREATING A FILE
There are several ways to create a CP/M file, including:

Using
Using
Using
which

the CP/M text editor (ED).

the PIP command to copy and rename a file.
a program such as MAC (a CP/M machine language assembler program),
creates output files as it processes input files.

USING WILDCARD CHARACTERS T O

ACCESS MORE T H A N ONE FILE
A wildcard is a character that can be used in a filename or filetype in place of some other
characters. CP/M 3.0 uses the question mark (?) and asterisk (*) as wildcards. A ? stands
for any character that may be encountered in that position. An * tells CP/M to fill the
filename with question mark characters as indicated. A file specification containing a wildcard can refer to more than one file and is therefore called an ambiguous file specification.

RESERVED CHARACTERS
The characters in Table 14-1 are reserved characters in CP/M 3.0. Use only as indicated.
CHARACTER

MEANING

< $ , !I> [ I
|
T A B, S P A C E ,
i File specification delimiters
CARRIAGE RETURN]
Drive delimiter in file specification
Filetype delimiter in file specification
Password delimiter in file specification
Comment delimiter at the beginning of a command line
Wildcard characters in an ambiguous file specification
< > & ! I \ H
Option list delimiters
[1
Option list delimiters for global and local options
()
Delimiters for multiple modifiers inside square
brackets for options that have modifiers
/$
Option delimiters in a command line
Table 14-1. CP/M 3.0 Reserved Characters

C P / M 3.0 O N T H E C O M M O D O R E 128

RESERVED FILETYPES
The filetypes defined in Table 14-2 are reserved for system use.

FILETYPE

MEANING

ASM
BAS
COM
HEX
HLP

Assembler source file

BASIC source program
Z80 or equivalent machine language program
Output file from MAC (used by HEXCOM)
HELP message file
Temporary file
Print file from MAC or RMAC
Output file from RMAC (used by LINK)
List of commands to be executed by SUBMIT
Symbol file from MAC, RMAC or LINK
System file
Resident System Extension (a file automatically loaded by a command
file when needed)

$$$
PRN
REL
SUB
SYM
SYS
RSX

Table 14-2. CP/M 3.0 Reserved Filetypes

CP/M COMMANDS
There are two types of commands in CP/M 3.0:

Built-in commands, which identify programs in memory.

Transient utility commands, which identify prognm files.

CP/M 3.0 has six built-in commands and over twenty transient utility commands.
Utilities can be added by purchasing CP/M 3.0-compatible application programs. In
addition, experienced programmers can write utilities that operate with CP/M 3.0.

BUILT-IN COMMANDS
Built-in commands are entered in the computer's memory when CP/M 3.0 is loaded,
and are always available for use, regardless of which disk is in which drive. Table 143
lists the Commodore 128 CP/M 3.0 built-in commands.
Some built-in commands have options that require support from a related transient
utility. The related transient utility command has the same name as the built-in command and has a filetype of COM.

481

482

COMMODORE 128

COMMAND

FUNCTION

DIR

Displays filenames of all files in the directory except those marked with
the SYS attribute.

DIRSYS

Displays filenames of files marked with the SYS (system) attribute in the
directory.

ERASE

Erases a filename from the disk directory and releases the storage space
occupied by the file.

RENAME Renames a disk file.

TYPE

Displays contents of an ASCII (TEXT) file at your screen.

USER

Changes to a different user number.

Table 14-3. Built-in Commands

TRANSIENT UTILITY COMMANDS

The CP/M 3.0 transient utility commands are listed in Table 14-4. When a command keyword identifying a transient utility is entered, CP/M 3.0 loads the program file from the
disk and passes that file any filenames, data or parameters specified in the command tail.

USING CONTROL CHARACTERS

FOR LINE EDITING
Table 14-5 lists the line-editing control characters for CP/M 3.0 on the Commodore 128.

HOW TO MAKE COPIES OF

CP/M 3.0 DISKS AND FILES
NOTE: The Digital Research Inc. COPYSYS command, used in many
CP/M systems in formatting a disk, is not implemented on the Commodore 128 computer. Instead, the Commodore 128 uses a special FORMAT
command.
To make backups of the CP/M system disks, use the FORMAT and PIP utility
programs. FORMAT formats the disk as either a C128 single-sided or C128 double-sided
diskette.

C P / M 3.0 O N T H E C O M M O D O R E 128

NAME

FUNCTION

DATE

Sets or displays the date and time.

DEVICE

Assigns logical CP/M devices to one or more physical devices, changes

device driver protocol and baud rates, or sets console screen size.

DIR

Displays directory with files and their characteristics.

DUMP

Displays a file in ASCII and hexadecimal format.

ED

Creates and alters ASCII files.

ERASE

Used for wildcard erase.

GENCOM

Creates a special COM file with attached RSX file.

GET

Temporarily gets console input from a disk file rather than the
keyboard.

FORMAT

Initializes disk in GCR format for CP/M use.

HELP

Displays information on how to use CP/M 3.0 commands.

INITDIR

Initializes a disk directory to allow time and date stamping.

KEYFIG

Allows redefinition of keys.

PATCH

Displays or installs patches to CP/M system.

PIP

Copies files and combines files.

PUT

Temporarily directs printer or console output to a disk file.

RENAME

Changes the name of a file, or a group of files, using wildcard characters.

SAVE

Saves a program in memory to disk.

SET

Sets file options including disk labels, file attributes, type of time and
date stamping and password protection.

SETDEF

Sets system options including the drive search chain.

SHOW

Displays disk and drive statistics.

SUBMIT

Automatically executes multiple commands.

TYPE

Displays contents of text file (or group of files, if wildcard characters are
used) on screen (and printer if desired).

Table 14-4. Transient Utility Commands

483

484

C O M M O D O R E 128

CHARACTER

MEANING

CTRL-A or
SHIFT-LEFT CURSOR

Moves the cursor one character to the left.

CTRL-B

Moves the cursor to the beginning of the command line without

having any effect on the contents of the line. If the eursor is
at the beginning, CTRL-B moves it to the end of the line.

CTRL-E

Forces a physical carriage return but does not send the

command line to CP/M 3.0. Moves the cursor to the beginning of the next line without erasing the previous input.

CTRL-F or
RIGHT CURSOR

Moves the cursor one character to the right.

CTRL-G

CTRL-H

CTRL-I

CTRL-J
CTRL-K
CTRL-M

CTRL-R

CTRL-U

Deletes the character at current cursor position. The cursor

does not move. Characters to the right of the cursor shift
left one place.
Deletes the character to the left of the cursor and moves
the cursor left one character position. Characters to the right
of the cursor shift left one place.
Moves the cursor to the next tab stop. Tab stops are automatically set at each eighth column. Has the same effect
as pressing the T A B key.
Sends the command line to CP/M 3.0 and returns the cursor
to the beginning of a new line. Has the same effect as a
R E T U R N or a CTRL-M keystroke.
Deletes to the end of the line from the cursor.
Sends the command line to CP/M 3.0 and returns the cursor
to the beginning of a new line. Has the same effect as a
R E T U R N or a CTRL-J keystroke.
Retypes the command line. Places a # character at the
current cursor location, moves the cursor to the next line,
and retypes any partial command you typed so far.
Discards aII the characters in the command line, places a
# character at the current cursor position, and moves the
cursor to the next line. However, you can use a CTRL-W to
recall any characters that were to the left of the cursor
when you pressed CTRL-U.

CTRL-Wor | C R S R i

Recalls and displays previously entered command line both

at the operating system level and within executing programs,
if the CTRL-W is the first character entered after the
prompt. CTRL-J, CTRL-M, CTRL-U and RETURN define
the command line you can recall. If the command line
contains characters, CTRL-W moves the cursor to the end
of the command line. If you press R E T U R N , CP/M
3.0 executes the recalled command.

CTRL-X

Discards all the characters left of the cursor and moves the
cursor to the beginning of the current line. CTRL-X saves
any characters to the right of the cursor.

Table 14-5. CP/M 3.0 Line-Editing Control Characters

CP/M 3.0 O N THE COMMODORE 128

MAKING COPIES WITH A

SINGLE DISK DRIVE
You can copy the contents of a disk with a single Commodore disk drive (1541 or
1571). For example, use the following sequence of commands to create a bootable
CP/M system disk. First type:
A>FORMAT
and follow the instructions given on the screen. When the copy disk is formatted,
type:
A > P I P E: = A:CPM + .SYS
When the CPM + SYS file is copied, you type:
A > P I P E: = A:CCP.COM
To copy everything on a disk, use the following command sequence:
A>FORMAT
A > P I P E: = A:*.*
The system prompts the user to change disks as required.
Use drive A as the source drive and drive E as the destination drive. Drive E is
referred to as a virtual drive; that is, it does not exist as an actual piece of hardwareit is
strictly a logical drive.

MAKING COPIES WITH TWO DISK DRIVES

You can back up disks in CP/M by using two drives: drive A and drive B. The drives
can be named with other letters from A through D. To make a copy of your CP/M 3.0
system disk, first use the FORMAT utility to copy the operating system loader. Make
sure that the CP/M system disk is in drive A, the default drive, and the blank disk is in
drive B. Then enter the following command at the system prompt:
A > P I P B : A:CPM + .SYS
When you have copied the CPM + .SYS file, use the PIP command to copy the
CCP.COM file. This provides a copy of the operating system only. To copy all of
the files from the system disk, enter the following PIP command:
A > P I P B: = A:*.*
This PIP command copies all the files on the disk in drive A to the disk in drive B. PIP
displays the message COPYING, followed by each filename as the copy operation
proceeds. When PIP finishes copying, the system prompt ( A > ) is displayed.

485

486

COMMODORE 128

GENERAL CP/M 3.0 SYSTEM LAYOUT

The Commodore 128 computer is a two-processor system, with the 8502 as the primary
processor and the Z80 as the secondary processor. The 8502 has the same instruction set
as the 6502. The Z80's primary function is to run CP/M 3.0. This section describes the
general requirements and methods for implementing CP/M 3.0 on the C128.
When CP/M is running, the normal functions of the C128 are not supported
(CP/M and BASIC cannot run at the same time). Also, CP/M does not directly support
all the display modes of the VIC chip. (An application could be written to run under
CP/M that could use additional graphics capabilities, but the application would have to
keep track of all the details, such as memory maps).

CP/M 3.0 OPERATING SYSTEM

COMPONENTS
The CP/M 3.0 operating system consists of the following three modules: the Console
Command Processor (CCP), the BASIC Disk Operating System (BDOS), and the Basic
Input Output System (BIOS).
The CCP is a program that provides the basic user interface to the facilities of the
operating system. The CCP supplies the six built-in commands: DIR, DIRS, ERASE,
RENAME, TYPE, and USER. The CCP executes in the Transient Program Area
(TPA), the region of memory where all application programs execute. The CCP contains
the Program Loader Module, which loads transient (applications) programs from disk
into the TPA for execution. On the Commodore 128, a 58K to 59K TPA area is provided
for CP/M.
The BDOS is the logical nucleus and file system of CP/M 3.0. The BDOS
provides the interface between the application program and the physical input/output
routines of the BIOS.
The BIOS is a hardware-dependent module that interfaces the BDOS to a particular hardware environment. The BIOS performs all physical I/O in the system. The BIOS
consists of a number of routines that are configured to support the specific hardware of
the target computer system (in this case, the Commodore 128).
The BDOS and the BIOS modules cooperate to provide the CCP and other
transient programs with hardware-independent access to CP/M 3.0 facilities. Because
the BIOS can be configured for different hardware environments and the BDOS remains
constant, you can transfer programs that run under CP/M 3.0 to systems with different
hardware configurations.

COMMUNICATION BETWEEN MODULES

The BIOS loads the CCP into the TPA at system cold and warm starts. The CCP moves
the Program Loader Module to the top of the TPA and uses the Program Loader Module
to load transient programs.

CP/M 3.0 O N THE COMMODORE 128

The BDOS contains a set of functions that the CCP and applications programs call
to perform disk and character input and output operations.
The BIOS contains a Jump Table with a set of thirty-three entry points that the
BDOS calls to perform hardware-dependent primitive functions, such as peripheral
device I/O. For example, CONIN is an entry point of the BIOS called by the BDOS to
read the next console input character.
Similarities exist between the BDOS functions and BIOS functions, particularly
for simple device I/O. For example, when a transient program makes a console output
function call to the BDOS, the BDOS makes a console output call to the BIOS. In the
case of disk I/O, however, this relationship is more complex. The BDOS file may make
many BIOS function calls to perform a single BDOS file I/O function. BDOS disk I/O is
in terms of 128-byte logical records. BIOS disk I/O is in terms of physical sectors and
tracks.
The System Control Block (SCB) is a 100-byte (decimal) CP/M 3.0 data structure
that resides in the BDOS system component. The BDOS and the BIOS communicate
through fields in the SCB. The SCB contains BDOS flags and data, CCP flags and data,
and other system information, such as console characteristics and the current date and
time. You can access some of the System Control Block fields from the BIOS.
Note that the SCB contains critical system parameters that reflect the current state
of the operating system. If a program modifies these parameters, the operating system
can crash. See Section 3 of the DRI CP/M Plus System Guide and the description of
BDOS Function 49 in the DRI CP/M Plus Programmer's Guide for more information on
the System Control Block.
Page zero is a region of memory that acts as an interface between transient
programs and the operating system. Page zero contains critical system parameters, including the entry to the BDOS and entry to the BIOS Warm BOOT routine. At system
start-up, the BIOS initializes these two entry points in page zero. All linkage between
transient programs and the BDOS is restricted to the indirect linkage through page zero.

CP/M 3.0 BIOS OVERVIEW

This section describes the organization of the CP/M 3.0 BIOS and the BIOS jump
vector. It provides an overview of the System Control Block, followed by a discussion
of system initialization procedures, character I/O, clock support, disk I/O, and memory
selects and moves.

ORGANIZATION OF THE BIOS

The BIOS is the CP/M 3.0 module that contains all hardware-dependent input and
output routines. To configure CP/M 3.0 for a particular hardware environment, the
sample BIOS supplied with the CP/M Plus System Guide must be adapted to the specific
hardware of the target system (the Commodore 128).
The BIOS essentially is a set of routines that performs system initialization,

487

488

C O M M O D O R E 128

character-oriented I/O to the console and printer devices, and physical sector I/O to disk
devices. The BIOS also contains routines that manage block moves and memory selects
for bank-switched memory. The BIOS supplies tables that define the layout of the disk
devices and allocate buffer space that the BDOS uses to perform record blocking and
deblocking. The BIOS can maintain the system time and date in the System Control Block.
Table 14-6 describes the entry points into the BIOS from the Cold Start Loader
and the BDOS. Entry to the BIOS is through a set of jump vectors. The jump table is
a set of thirty-three jump instructions that pass program control to the individual BIOS
subroutines.

NO.

INSTRUCTION

DESCRIPTION

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP

BOOT
WBOOT
CONST
CONIN
CONOUT
LIST
AUXOUT
AUXIN
HOME
SELDSK
SETTRK
SETSEC
SETDMA
READ
WRITE
LISTST
SECTRN
CONOST
AUXIST
AUXOST
DEVTBL
DEVINI
DRVTBL
MULTIO

24
25
26
27
28
29
30
31
32

JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP

FLUSH
MOVE
TIME
SELMEM
SETBNK
XMOVE
USERF
RESERV1
RESERV2

Perform cold start initialization.

Perform warm start initialization.
Check for console input character ready.
Read console character in.
Write console character out.
Write list character out.
Write auxiliary output character.
Read auxiliary input character.
Move to Track 00 on selected disk.
Select disk drive.
Set track number.
Set sector number.
Set DMA address.
Read specified sector.
Write specified sector.
Return list status.
Translate logical to physical sector.
Return output status of console.
Return input status of aux. port.
Return output status of aux. port.
Return address of char. I/O table.
Initialize char. I/O devices.
Return address of disk drive table.
Set number of logically consecutive sectors to be read or
written.
Force physical buffer flushing for user-supported deblocking.
Memory to memory move.
Time set/get signal.
Select bank of memory.
Specify banks for inter-bank MOVE.
Set banks for an inter-bank MOVE.
Commodore CP/M system functions.
Reserved for future use.
Reserved for future use.

Table 14-6. CP/M 3.0 BIOS Jump Vectors

CP/M 3.0 O N THE COMMODORE 128

All the entry points in the BIOS jump vector are included in the C128 CP/M 3 . 0
BIOS.
Each jump address in Table 14-6 corresponds to a particular subroutine that
performs a specific system operation. Note that two entry points are reserved for future
versions of CP/M, and one entry point is provided for the Commodore system functions.
Table 14-7 shows the five categories of system operations and the function calls
that accomplish these operations.

OPERATION

FUNCTION

System
Initialization

BOOT, WBOOT, DEVTBL, DEVINI, DRVTBL

Character I/O

CONST, CONIN, CONOUT, LIST, AUXOUT, AUXIN, LISTST,

CONOST, AUXIST, AUXOST

Disk I/O

HOME, SELDSK, SETTRK, SETSEC, SETDMA, READ, WRITE,

SECTRN, MULTIO, FLUSH

Memory Selects
and Moves

MOVE, SELMEM, SETBNK, XMOVE

Clock Support

TIME

Table 14-7. CP/M 3 BIOS Functions

Appendix K illustrates how to call a Commodore CP/M system function in Z80
machine language.

SYSTEM MEMORY
ORGANIZATION
Figure 14-1 shows the general memory organization of CP/M 3.0.

489

490

COMMODORE 128

COMMON SYSTEM MEMORY

BANKED SYSTEM

T
P
A

CCP BUFFER
VIC SCREEN
8S02 BIOS
40-COLUMN
LOGICAL SCREEN
KEY TABLES

ROM CODE
Figure 14-1. C P / M 3.0 General Memory Organization

CP/M 3.0 O N THE COMMODORE 128

The memory map is limited to 64K at any one point in time. However, the RAM
bank can be selected and then different ROM areas can overlay the RAM (with
bleed-through on write operations). The actual memory map is controlled by the MMU. The
MMU can be accessed in the I/O area (only when I/O is enabled in Z80 space) or
through the Load Configuration Register located at FF00 through FF04.
If the Load Configuration Registers are read, then the current value is read. A
write to FF00 changes the configuration after completing the current instruction. A
write to FF01 to FF04 updates the current configuration to the value stored in the
Preconfiguration Registers (the data written is not used). The MMU page pointers have
both a low (page) and a high (page) pointer. The high is written first and latched in the
MMU; the high value is updated from the latch when the low byte is written. The MMU
Control Registers are listed in Chapter 13.

DISK ORGANIZATION
CP/M 3.0 supports a number of different disk formats, including three Commodore
formats and a number of MFM formats. (MFM is the industry standard format.) The
first Commodore format is single-sided Commodore GCR, which is compatible with the
CP/M 2.2 that runs on the Commodore 64. With this format, the File Control Block
(FCB) is set up as 32 tracks of 17 sectors each and a track offset of 2. The BIOS routine
adds a 1 to tracks greater than 18 (this is the C64 directory track).
The second format, known as the C128 CP/M Plus disk format, is new and is also
single-sided. This format, which is also a GCR format, takes advantage of the full disk
capacity by setting up the FCB with 638 tracks of 1 sector each and a track offset of 0.
This has the effect of having CP/M set the track to the block number relative to
the beginning of the disk, with the sector always set to 0. The following algorithm is
used to convert the requested TRACK to a real track and sector number.
REQUESTED TRACK

000
355
487
595
680

>
>
>
>
>

=
=
=
=

TRACK
TRACK
TRACK
TRACK
TRACK

ACTUAL TRACK

>
>
>
>
>

355
487
595
680
1360

((TRACK + 2)/21) + 1
((TRACK - 354)/19) + 18
((TRACK - 487)/18) + 25
((TRACK - 595)/17) + 31
SET SIDE 2 TRACK = TRACK - 680

491

492

COMMODORE 128

The effective sector is then translated to provide a skew that speeds up operations.
The skew is used only with the new larger format. A different skew table is used for
each region of the disk.
The third Commodore format is a GCR double-sided format. The disk is treated as
1276 sectors of data with a track offset of 0. Side 1 is used first; then side 2 is used.
NOTE: This is not the usual way to handle a two-sided disk; however,
allocating the disk in this manner, the user with a 1541 may still be able
to read data written at the start of a two-sided disk.

The third Commodore format and all MFM formats require that the user have the
new 1571 disk drive. This disk drive supports both single- and double-sided diskettes
and both the Commodore GCR and industry standard MFM data coding formats.
The following table summarizes 1541/1571 disk drive capabilities with regard to
the various disk formats.

DISK FORMAT

1541 DRIVE

1571 DRIVE

C64 GCR
single-sided

C128 GCR
single-sided

C128 GCR
double-sided

MFM
format

C64 CP/M DISK FORMAT

(SINGLE-SIDED)
This format, shown in Figure 142, is provided to allow the user to read/write files
created using the C64 CP/M 2.2 cartridge. (However, do not use the CP/M 2.2 cartridge
with the C128.) Notice the unused space in this format.

CP/M 3.0 O N THE COMMODORE 128

SECTOR
0 1 2 3 4 5 6 7 8 9
0 B B B B B B B B B B
1 B B B B B B B B B B
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 D D D D D D D D D D
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
.
B
D
x

10
B
B

11
B
B

12
B
B

13
B
B

14
B
B

15
B
B

16
B
B

17
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
D
x
x
x
x
x
x
x
x
x
x
x
x

18
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
D
x
x
x
x
x
x

Used by CP/M.
Boot Sector (System).
Directory Sector (Disk DOS),
Not used by CP/M.

Figure 14-2. C64 C / P M Disk Format

CI28 CP/M DISK FORMATS

(SINGLE- A N D DOUBLE-SIDED)
Figure 1 4 - 3 s h o w s the C 1 2 8 C P / M Plus format for a single-sided disk.

19
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x

20
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x

493

494

COMMODORE 128

SECTOR
0
0 B
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18 D
19
20
.
21
22
23
24
25
26
27
28
29
30
31
32
33
34
B
D
x

1
.

2
.

3
.

4
.

10

11

12

13

14

15

16

17

18

19

20

Used by CP/M, reg. = region (1^4).

Boot Sector (System).
Directory Sector (Disk DOS),
Not used by CP/M.
SKEW TABLE
0

1
2
3
4

00
00
00
00

17 13 09
04 08 12
11 04 15
07 14 04

05
16
08
11

01
01
01
01

10

11

12

13

14

15

16

17

18

19

18 14 10 06 02
05 09 13 17 02
12 05 16 09 02
08 15 05 12 02

19
06
13
09

15
10
06
16

11
14
17
06

07 03
18 03
10 03
13 03

20
07
14
10

16
11
07

12
15

08

Figure 14-3. C I 2 8 C P / M Plus Disk Format

20

CP/M 3.0 O N THE COMMODORE 128

NOTE: This format is duplicated on the second side of a two-sided disk

(with the exception of B, which is unused and therefore becomes X).

MFM DISK FORMATS

A number of MFM disk formats are built into CP/M on the C128. These formats, which
can be selected at the time a program is to be run, include Osborne, Kaypro, Epson and
IBM CP/M-86. The IBM CP/M-86 capability is provided so that data can be transferred
between machines. However CP/M-86 programs cannot be run on the C128, since on
the C128, CP/M Plus runs on a Z80, not an 8088.
When used with the 1571 Disk Drive, the Commodore 128 supports a variety
of double-density MFM disk formats (for reading and/or writing), including:
Epson QX10

(512 byte sectors, double-sided, 10 sectors per track)

IBM-8 SS (CP/M 86)

(512 byte sectors, single-sided, 8 sectors per track)

IBM-8 DS (CP/M 86)

(512 byte sectors, double-sided, 8 sectors per track)

KayPro II

(512 byte sectors, single-sided, 10 sectors per track)

KayPro IV

(512 byte sectors, double-sided, 10 sectors per track)

Osborne DD

(1024 byte sectors, single-sided, 5 sectors per track)

When you insert one of these disks into the disk drive and try to access it, the system
senses the type of disk with respect to the number of bytes per sector and the number of
sectors per track. If the disk format is not unique, a box is displayed near the bottom-left
corner of the screen, showing which disk type you are accessing. The system requires
you to select the specific disk type by scrolling through the choices given in this
window.

NOTE: The choices are given one at a time; scroll through using the
right and left arrow keys. Press R E T U R N when the disk type that
you know is in the disk drive is displayed. Press
C O N T R O L
R E T U R N to lock this disk format so that you will not need to
select the disk type each time you access the disk drive.

495

496

COMMODORE 128

KEYBOARD SCANNING
The keyboard scan routine that is called to get a keyboard character returns the key code
of the pressed key, or a code indicating that no key is currently being pressed. The
keyboard scan code is also responsible for handling programmable keys, programmable
function keys, setting character and background colors, selecting MFM disk formats and
selecting current screen emulation type.
Any key on the keyboard can be defined to generate a code or function except the
following keys:

LEFT SHIFT
RIGHT
SHIFT
SHIFT
LOCK
O

CONTROL
RESTORE (8502 N M I )
40/80 D I S P L A Y
CAPS LOCK KEY
The keyboard recognizes the following special functions:
Cursor left key-Used to define a key
Cursor right key-Used to define a string
(points to function keys)
ALT key-Used as toggle key filter
To indicate these functions, hold down the C O N T R O L
key and the
R I G H T S H I F T key and simultaneously press the desired function key.

DEFINING A KEY
The KEYFIG utility program allows the user to define the code that a key can produce.
Each key has four modes of use for this function:

Normal
Alpha shift
Shift
Control

The alpha shift mode is toggled on/off by pressing the Commodore ( O ) key. When
this mode is turned on, a small white box appears on the bottom of the screen. The first
key that is pressed thereafter is the key to be defined. The current hex value assigned to
this key is displayed, and the user can then type the new hex code for the key, or abort
by typing a non-hex key. The following is a definition of the codes that can be assigned
to a key. See KEYFIG HELP for more information.

CP/M 3.0 O N THE COMMODORE 128

CODE

FUNCTION

00h
01h to 7Fh
80h to 9Fh
A0h to AFh
B0h to BFh
C0h to CFh
D0h to DFh
E0h to EFh
F0h
Flh
F2h
F3h
F4h
F5h to FFh

Null (same as not pressing a key)

Normal ASCII codes
String assigned
80-column character color
80-column background color
40-column character color
40-column background color
40-column border color
Toggle disk status on/off
System Pause
(Undefined)
40-column screen window right
40-column screen window left
(Undefined)

DEFINING A STRING
The DEFINE STRING function allows the user to assign more than one key code to a
single key. Any key that is typed in this mode is placed in the string. The user can see
the results of typing in a long box at the bottom of the screen. Note, however, that some
keys may not display what they are.
To allow the user control of entering data, five special edit functions are provided.
To access any of these functions, you first press the C O N T R O L
and
RIGHT
S H I F T keys. (This allows the user to enter any key into the buffer.)
The functions assigned to the five string edit keys are as follows:

KEY

FUNCTION

RETURN

End string definition.

Insert space in string.

symbol*

symbol*

Delete cursor character.

Right Cursor

Move cursor to right.

Left Cursor

Move cursor to left.

*On main keyboard only.

ALT MODE
This function is a toggle (on/off) and is provided to allow the user to send 8-bit
codes to an application without the keyboard driver "eating" the code from 80h to
FFh.

497

498

COMMODORE 128

UPDATING THE
40/80 COLUMN DISPLAY
As noted elsewhere in this book, there are two different display systems within
the C128. The first, which is controlled by the VIC chip, produces a 25-line by
40-column display, has many graphics modes of operation, and can be used with a
standard color (or black-and-white) television or color monitor. (See Chapters 8 and 9
for details.) The only VIC-controlled display mode used by CP/M is standard character
mode, with each character and screen background having up to sixteen colors.
The second display system available in C128 CP/M is controlled by the 8563
display controller. The display format of this controller is 25 lines by 80 columns, with
character color attributes. The VIC chip is a memory-mapped display, and the 8563 is
I/O-controlled. The two display subsystems are treated as two separate displays. CP/M
3 . 0 can assign one or both to the console output device.
Both displays are controlled by a common terminal emulation package, a Lear
Siegler A D M - 3 1 ( A D M - 3 A is a subset of this) driver. The terminal driver is divided
into two parts: terminal emulation and terminal functions. Terminal emulation is
handled by the Z80 BIOS, and the terminal function is handled primarily in the
Z80 ROM.
The following section shows the various terminal emulation protocols supported
by Commodore 128 CP/M.

TERMINAL EMULATION PROTOCOLS

FUNCTION

CHARACTER SEQUENCE

HEX CHAR CODE

Position Cursor
Cursor Left
Cursor Right
Cursor Down
Cursor Up
Home and Clear Screen
Carriage Return
Escape
Bell

ESC (row# + 32) (col# 4- 32)

Control H
Control L
Control J
Control K
Control Z
Control M
Control [
Control G

l B 3D 20 + 20 +
08
0C
0A
0B
lA
0D
lB
07

NOTE: Display is 24 (1-24) by 80 (1-80); cursor origin is always 1/1.

Figure 14-4. Lear Siegler ADM-3A Protocol

CP/M 3.0 ON THE COMMODORE 128

N O T E : The following have been added to allow the system to emulate

the KayPro II display more closely.

FUNCTION

CHARACTER
SEQUENCE

Home Cursor
CEL (Clear to End of Line)
CES (Clear to End of Screen)

Control T
Control-X
Control-W

CHARACTER SEQUENCE

Clear to end of line

ESC T
ESC t
Clear to end of screen
ESC Y
ESC y
Home cursor and clear screen ESC :
ESC *
Half intensity on
ESC )
Half intensity off
ESC (
Reverse video on
ESC G4
Blinking on
ESC G2
Underline on *
ESC G3
Select alternate character set* ESC G1
Reverse video and blinking off ESC G0
Insert line
ESC E
Insert character
ESC Q
Delete line
ESC R
Delete character
ESC W
Set screen colors*
ESC ESC ESC color
where color # = 20h
30h
40h

*Indicates this is not a normal ADM31 sequence.

HEX CHARACTER CODES

lB
lB
lB
lB
lB
lB
lB
lB
lB
lB
lB
lB
lB
lB
lB
lB
lB

#
to 2Fh :haracter color
to 3Fhibackground color
to 4Fhiborder color (40
columns only)
50h to 50Fh character color
60h to 60Fhibackground color
70h to 70Fhiborder color (40
columns only)

Note: Display is 24 (1-24) by 80 (1-80); cursor origin is always 1/1.

Figure 14-5. Lear Siegler ADM-3I Protocol

54
74
59
79
3A
2A
29
28
47 34
47 32
47 33
47 31
47 30
45
51
52
57

Physical
Colors

Logical
Colors

499

500

COMMODORE 128

SYSTEM OPERATIONS
SETTING SYSTEM TIME
The time of day is set with this function. The time of day is stored in packed BCD
format in the System Control Block (SCB) in three locations (hours, minutes, seconds).
This routine reads the SCB time and writes that time to the time of day clock within the
6526. This time is updated on the chip and is used by CP/M. The Z80 is able to
read/write the 6526 directly.

UPDATING SYSTEM TIME

The SCB time is updated from the time of day clock on the 6526 by doing a system call.

8502 BIOS ORGANIZATION

The 8502 is responsible for most of the low-level I/O functions. The request for these
functions is made through a set of mailboxes. Once the mailboxes are set up, the Z80
shuts down and the 8502 starts up (BIOS85). The 8502 looks at the command in the
mailbox and performs the required task, sets the command status and shuts down. The
Z80 is re-enabled; it then looks at the command status and takes the appropriate actions.
The 8502 BIOS commands are defined in Appendix K.
This concludes the summary explanation of the Commodore 128 CP/M system.
However, the Commodore 128 CP/M System includes many additional Commodore
128-dependent routines and functions that are performed by the Z80 microprocessor.
Since most of these routines, system calls and functions are tabular information, they are
covered in Appendix K. For information on any of the following topics, refer to
Appendix K.
8502 BIOS commands
All Commodore 128 Z80 system-dependent user functions
Calling a CP/M BIOS, 8502 BIOS and CP/M User system functions in Z80 machine
language
More information on MFM disk formats
Commodore 128 CP/M (Z80) Memory Map
For more information on the general (non-Commodore 128-dependent) CP/M 3.0
system, see the offer in section 15 of the C128 System Guide for the Digital Research
CP/M Plus User's Guide, Programmer's Guide and System Guide.

J5
THE
COMMODORE 128
AND
COMMODORE 64
MEMORY MAPS

501

502

COMMODORE 128

This chapter provides the memory maps for both C128 and C64 modes. A memory map
tells you exactly how memory is laid out internally in both R A M and ROM. It tells you
exactly what resides in each memory location. The memory map directs you in finding
address vectors for routines and entry points and provides information about the general
layout of the computer. The memory map is probably the most vital programming tool.
Refer to the memory map whenever you need directions throughout the memory of your
Commodore 128. Addresses listed with more than one address label are used for more
than one purpose. To BASIC, the variable has one purpose; to the Machine Language
Monitor, it may have another.
The conventions used for the memory maps are as follows:
Column 1

Column 2

Column 3

Column 4

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

See Appendix K for the Z80 memory map for CP/M on the Commodore 128.

CI28 MEMORY MAP

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

D6510
R6510
BANK

0000
0001
0002

0
1
2

PC_HI

0003

PC_LO

0004

S_REG
A_REG
X_REG
Y_REG
STKPTR

0005
0006
0007

5
6
7
8
9

0008
0009

DECIMAL
ADDRESS

DESCRIPTION

6510 DATA DIRECTION REGISTER

6510 DATA REGISTER
TOKEN <SEARCH' LOOKS FOR, OR
BANK #
ADDRESS FOR BASIC SYS
COMMAND OR MONITOR AND
LONG CALL/JUMP ROUTINES
ADDRESS, STATUS, A-REG, X-REG,
Y-REG
STATUS REG TEMP
.A REG TEMP
.X REG TEMP
.Y REG TEMP
STACK POINTER TEMP

BASIC ZERO PAGE STORAGE

INTEGR
CHARAC
ENDCHR

0009

000A

10

TRMPOS
VERCK

000B
000C

11
12

SEARCH CHARACTER
FLAG: SCAN FOR QUOTE AT END
OF STRING
SCREEN COLUMN FROM LAST TAB
FLAG: 0 = LOAD, 1 = VERIFY

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

Cl28 Memory Map (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

COUNT
DIMFLG
VALTYP

000D
000E
000F

13
14
15

INTFLG

0010

16

GARBFL

0011

17

DORES
SUBFLG

0012

18

INPFLG

0013

19

DOMASK
TANSGN

0014

20

CHANNL
POKER
LINNUM
TEMPPT
LASTPT
TEMPST
INDEX
INDEX1
INDEX2
RESHO
RESMOH
ADDEND
RESMO
RESLO
TXTTAB
VARTAB

0015
0016

21
22

0018
0019
001B
0024

24
25
27
36

0026
0028
0029
002A

38
40
41
42

002B
002D
002F

43
45
47

ARYTAB
STREND

0031
0033

49
51

FRETOP

0035

53

FRESPC
MAX_MEM_1

0037
0039

55
57

CURLIN
TXTPTR

003B
003D

59
61

FORM
FNDPNT

003F

63

DECIMAL
ADDRESS

DESCRIPTION

INPUT BUF.PTR / # OF SUBSCRIPTS

FLAG: DEFAULT ARRAY DEMENSION
DATA TYPE: $FF = STRING,
$00 = NUMERIC
DATA TYPE: $OO = FLOAT.PT,
$80 = INTEGER
FLAG: DATA SCAN / LIST QUOTE /
GARBAGE COLLECTION
FLAG: SUBSCRIPT REF. / USER
FUNC. CALL
FLAG: $00 = INPUT, $40 = GET,
$98 = READ
FLAG: TAN SIGN / COMPARISON
RESULT

TEMP INTEGER VALUE

POINTER: TEMP STRING STACK
LAST TEMP STRING ADDRESS
STACK FOR TEMP STRINGS
UTILITY POINTER AREA

FLOAT.PT. PRODUCT OF MULTIPLY

POINTER: START OF BASIC TEXT

POINTER: START OF BASIC
VARIABLES
POINTER: START OF BASIC ARRAYS
POINTER: END OF BASIC ARRAYS
+ 1
POINTER: BOTTOM OF STRING
STORAGE
UTILITY STRING POINTER
TOP OF STRING/VARIABLE BANK
(BANK 1)
CURRENT BASIC LINE NUMBER
POINTER TO BASIC TEXT USED BY
CHRGET,ETC.
USED BY PRINT USING
POINTER TO ITEM FOUND BY
SEARCH

503

504

COMMODORE 128

C128 Memory Map (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

BASIC ZERO PAGE STORAGE

DATLIN
DATPTR
INPPTR
VARNAM
FDECPT
VARPNT

0041
0043
0045
0047
0049

LSTPNT
FORPNT

004B

ANDMSK
EORMSK
VARTXT
OPPTR
OPMASK
GRBPNT
TEMPF3
DEFPNT
DSCPNT

65
67
69
71
73

POINTER: CURRENT BASIC

VARIABLE DATA
75
POINTER: INDEX VARIABLE FOR
FOR/NEXT
004C
004D

76
77

004F
0050

79
80

0052
0054
0055
0056
0057
0058
0059

82
84
85
86
87
88
89

005B
005D
0060
0063
0064
005A

91
93
96
99
100
90

005C
005E
005F

92
94
95

TENEXP
T0

0060

96

GRBTOP
DPTFLG
LOWTR
EXPSGN
FAC

0061

HELPER
JMPER
OLDOV
TEMPF1
PTARG1
PTARG2
STR1
STR2
POSITN
MATCH
ARYPNT
HIGHDS
HIGHTR
TEMPF2
DECCNT

CURRENT DATA LINE NUMBER

CURRENT DATA ITEM ADDRESS
VECTOR: INPUT ROUTINE
CURRENT BASIC VARIABLE NAME

FLAGS 'HELP' OR 'LIST'

MULTIPLY DEFINED FOR INSTR

NUMBER OF DIGITS AFTER THE

DECIMAL POINT
ML MONITOR Z.P. STORAGE IN
FAC

97
DECIMAL POINT FLAG

0062
0063

98
99

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

BASIC ZERO PAGE STORAGE

DSCTMP
LEFT__FLAG
FACEXP
T1
RIGHT_FLAG
FACHO
FACMOH
INDICE
FACMO
T2
FACLO
FACSGN
DEGREE
SGNFLG
ARGEXP
ARGHO
ARGMOH
INIT_AS_0
ARGMO
ARGLO
ARGSGN
STRNG1
ARISGN
FACOV
STRNG2
POLYPT
CURTOL
FBUFPT
AUTINC
MVDFLG
Z_P_TEMP_1

0064

100

0065

0066

101
102

0067
0068
0069

103
104
105

006A
006B
006C

106
107
108

006D
006E
006F
0070

109
110
111
112

PAINT-LEFT FLAG
F A C # 1 EXPONENT
MONITOR Z.P. STORAGE IN FAC
PAINT-RIGHT FLAG
FAC#1 MANTISSA

MONITOR Z.P. STORAGE IN FAC

F A C # 1 SIGN
POINTER: SERIES-EVAL. CONSTANT
F A C # 2 EXPONENT
F A C # 2 MANTISSA
JUST A COUNT FOR INIT

0071
0072

113
114

0074
0076
0077

116
118
119

HULP
KEYSIZ
SYNTMP

0078

120

0079

121

DSDESC
TXTPTR
TOS
RUNMOD
PARSTS
POINT

007A

122

007D
007F

125
127
128

0080

F A C # 2 SIGN
SIGN COMPARISON RESULT:
F A C # 1 VS # 2
F A C # 1 LOW-ORDER (ROUNDING)

POINTER: CASSETTE BUFFER

INC. VAL FOR AUTO (O = OFF)
FLAG IF 10K HIRES ALLOCATED
PRINT USING'S LEADING ZERO
COUNTER
MOYSPR & SPRITE TEMPORARY
MID$ TEMPORARY
COUNTER
USED AS TEMP FOR INDIRECT
LOADS
DESCRIPTOR FOR DS$
MONITOR Z.P. STORAGE
TOP OF RUN TIME STACK
FLAGS RUN/DIRECT MODE
DOS PARSER STATUS WORD
USING'S POINTER TO DEC.PT

505

506

COMMODORE 128

C128 Memory Map (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

BASIC ZERO PAGE STORAGE

PARSTX
OLDSTK

0081
0082

129
130

BASIC Z-P STORAGE FOR GRAPHIC COMMANDS

COLSEL
MULTICOLOR_l
MULTICOLOR_2
FOREGROUND
SCALE_X
SCALE_Y
STOPNB

0083
0084
0085
0086
0087
0089
008B

131
132
133
134
135
137
139

GRAPNT
VTEMP1
VTEMP2

008C
008E
008F

140
142
143

CURRENT COLOR SELECTED

SCALE FACTOR IN X
SCALE FACTOR IN Y
STOP PAINT IF NOT BACKGROUND/
NOT SAME COLOR

KERNAL/EDITOR STORAGE
STATUS
STKEY
SVXT
VERCK
C3P0
BSOUR
SYNO
XSAV
LDTND
DFLTN
DFLTO
PRTY
DPSW
MSGFLG
PTR1
T1
PTR2
T2
TIME
R2D2
PCNTR
BSOURl
FIRT
COUNT
CNTDN
BUFPT

0090
0091
0092
0093
0094
0095
0096
0097
0098
0099
009A
009B
009C
009D
009E

144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

009F

159

00A0
00A3

160
163

00A4

164

00A5

165

00A6

166

I/O OPERATION STATUS BYTE

STOP KEY FLAG
TAPE TEMPORARY
LOAD OR VERIFY FLAG
SERIAL BUFFERED CHAR FLAG
CHAR BUFFER FOR SERIAL
CASSETTE SYNC #
TEMP FOR BASIN
INDEX TO LOGICAL FILE
DEFAULT INPUT DEVICE #
DEFAULT OUTPUT DEVICE #
CASSETTE PARITY
CASSETTE DIPOLE SWITCH
OS MESSAGE FLAG
CASSETTE ERROR PASS1
TEMPORARY 1
CASSETTE ERROR PASS2
TEMPORARY 2
24HOURCLOCKEVl/60THSECONDS
SERIAL BUS USAGE
CASSETTE
TEMP USED BY SERIAL ROUTINE
TEMP USED BY SERIAL ROUTINE
CASSETTE SYNC COUNTDOWN
CASSETTE BUFFER POINTER

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

KERNAL/EDITOR STORAGE
INBIT
SHCNL
BITCI
RER
RINONE

00A7

167

00A8

168

00A9

169

00AA

170

RS-232 RCVR INPUT BIT STORAGE

CASSETTE SHORT COUNT
RS-232 RCVR BIT COUNT IN
CASSETTE READ ERROR
RS-232 RCVR FLAG FOR START BIT
CHECK
CASSETTE READING ZEROES
RS-232 RCVR BYTE BUFFER
CASSETTE READ MODE
RS-232 RCVR PARITY STORAGE
CASSETTE SHORT CNT
POINTER: TAPE BUFFER / SCREEN
SCROLLING

REZ
RIDATA
RDFLG
RIPRTY
SHCNH
SAL

00AB

171

00AC

172

SAH
EAL

00AD
00AE

173
174

EAH
CMP0
TEMP
TAPE1
BITTS
SNSW1
NXTBIT
DIFF
RODATA
PRP
FNLEN
LA
SA
FA
FNADR
ROPRTY
OCHAR
FSBLK
DRIVE
MYCH
CAS1

00AF
00B0
00B1
00B2
00B4

175
176
177
178
180

ADDRESS OF TAPE BUFFER

RS-232 TRNS BIT COUNT

00B5

181

RS-232 TRNS NEXT BIT TO BE SENT

00B6

182

RS-232 TRNS BYTE BUFFER

00B7
00B8
00B9
00BA
00BB
00BD

183
184
185
186
187
189

LENGTH CURRENT FILE N STR

CURRENT FILE LOGICAL ADDR
CURRENT FILE 2ND ADDR
CURRENT FILE PRIMARY ADDR
ADDR CURRENT FILE NAME STR
RS-232 TRNS PARITY BUFFER

00BE
00BF

190

CASSETTE READ BLOCK COUNT

TRACK
STAL
SECTOR
STAH
MEMUSS
TMP2
DATA

00C0
00C1
00C2
00C3
00C5

191
192
193
194
195
197

TAPE END ADDRESSES / END OF

PROGRAM
TAPE TIMING CONSTANTS

SERIAL WORD BUFFER

CASSETTE MANUAL/CNTRLED
SWITCH (UPDATED DURING IRQ)
I/O START ADDRESS (LO)
I/O START ADDRESS (HI)
CASSETTE LOAD TEMPS (2 BYTES)
TAPE READ/WRITE DATA

507

508

COMMODORE 128

C128 Memory Map (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

KERNAL/EDITOR STORAGE
BA

00C6

198

FNBANK

00C7

199

RIBUF
ROBUF

00C8
00CA

200
202

BANK FOR CURRENT LOAD/SAVE/

VERIFY OPERATION
BANK WHERE CURRENT FN IS
FOUND (AT <FNADR')
RS-232 INPUT BUFFER POINTER
RS-232 OUTPUT BUFFER POINTER

GLOBAL SCREEN EDITOR VARIABLES

oocc

KEYTAB
IMPARM
NDX
KYNDX
KEYIDX

00CE
00D0
00D1
00D2

204
206
208
209
210

SHFLAG
SFDX
LSTX
CRSW
MODE
GRAPHM
CHAREN

00D3
00D4
00D5
00D6
00D7
00D8
00D9

211
212
213
214
215
216
217

KEYSCAN TABLE POINTER

PRIMM UTILITY STRING POINTER
INDEX TO KEYBOARD QUEUE
PENDING FUNCTION KEY FLAG
INDEX INTO PENDING FUNCTION
KEY STRING
KEYSCAN SHIFT KEY STATUS
KEYSCAN CURRENT KEY INDEX
KEYSCAN LAST KEY INDEX
< C R > INPUT FLAG
40/80 COLUMN MODE FLAG
TEXT/GRAPHIC MODE FLAG
RAM/ROM VIC CHARACTER FETCH
FLAG (BIT-2)

THE FOLLOWING LOCATIONS ARE SHARED BY SEVERAL EDITOR ROUTINES.

SEDSAL
BITMSK

00DA
00DA

218
218

SAVER

00DB

219

SEDEAL
SEDT1
SEDT2
KEYSIZ
KEYLEN
KEYNUM
KEYNXT
KEYBNK
KEYTMP

00DC
00DE
00DF
00DA
00DB
00DC
00DD
00DE
00DF

220
222
223
218
219
220
221
222
223

POINTERS FOR MOVLIN

TEMPORARY FOR TAB & LINE
WRAP ROUTINES
ANOTHER TEMPORARY PLACE TO
SAVE A REG.
SAVPOS
PROGRAMMABLE KEY VARIABLES

LOCAL SCREEN EDITOR VARIABLES.

THESE ARE SWAPPED OUT TO $0A40
WHEN SCREEN (40/80) MODE CHANGES.
PNT
USER

00E0
00E2

224
226

POINTER TO CURRENT LINE (TEXT)

POINTER TO CURRENT LINE
(ATTRIBUTE)

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

LOCAL SCREEN EDITOR VARIABLES.

THESE ARE SWAPPED OUT TO $0A40
WHEN SCREEN (40/80) MODE CHANGES.
SCBOT
SCTOP
SCLF
SCRT
LSXP
LSTP
INDX
TBLX
PNTR
LINES

00E4
00E5
00E6
00E7
00E8
00E9
00EA
00EB
00EC
00ED

230
231
232
233
234
235
236
237

COLUMNS

00EE

238

DATAX
LSTCHR

00EF
00F0

239

COLOR

228
229

240

00F1
241

TCOLOR

00F2
242

RVS
QTSW
INSRT
INSFLG
LOCKS

00F3
00F4
00F5
00F6
00F7

SCROLL

00F8

248

BEEPER
FREKZP

00F9
00FA

249
250

LOFBUF

00FF

255

243
244
245
246
247

WINDOW LOWER LIMIT

WINDOW UPPER LIMIT
WINDOW LEFT MARGIN
WINDOW RIGHT MARGIN
CURRENT INPUT COLUMN START
CURRENT INPUT LINE START
CURRENT INPUT LINE END
CURRENT CURSOR LINE
CURRENT CURSOR COLUMN
MAXIMUM NUMBER OF SCREEN
LINES
MAXIMUM NUMBER OF SCREEN
COLUMNS
CURRENT CHARACTER TO PRINT
PREVIOUS CHAR PRINTED (FOR
< E S C > TEST)
CURR ATTRIBUTE TO PRINT
(DEFAULT FGND COLOR)
SAVED ATTRIB TO PRINT ('INSERT>
& <DELETE')
REVERSE MODE FLAG
QUOTE MODE FLAG
INSERT MODE FLAG
AUTO-INSERT MODE FLAG
DISABLES < S H I F T > < C * > ,
<CTRL>S
DISABLES SCREEN SCROLL, LINE
LINKER
DISABLES < C T R L > G
FREE ZERO PAGE RESERVED FOR
APPLICATIONS SOFTWARE
($FA-$FE)

BASIC/DOS INTERFACE VARS

BAD
FBUFFR

0100

256

XCNT

0110

272

TAPE READ ERRORS

AREA TO BUILD FILENAME IN
(16 BYTES)
DOS LOOP COUNTER

509

510

COMMODORE 128

C128 Memory Map (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

BASIC/DOS INTERFACE VARS

DOSFlL
DOSDSl
DOSF2L
DOSDS2
DOSF2A
DOSOFL
DOSOFH
DOSLA
DOSFA
DOSSA
DOSRCL
DOSBNK
DOSDID
DIDCHK

0111
0112
0113
0114
0115
0117
0119
011B
011C
011D
011E
011F
0120
0122

273
274
275
276
277
279
281
283
284
285
286
287
288
290

BNR
ENR
DOLR
FLAG
SWE
USGN
UEXP
VN

0123
0124
0125
0126
0127
0128
0129
012A

291
292
293
294
295
296
297
298

CHSN
VF

012B
012C

299
300

NF

012D

301

POSP
FESP
ETOF
CFORM
SNO
BLFD
BEGFD
LFOR
ENDFD
SYSTK
BUF

012E
012F
0130
0131
0132
0133
0134
0135
0136
0137
0200

302
303
304
305
306
307
308
309
310
311
512

DOS FILENAME 1 LEN

DOS DISK DRIVE 1
DOS FILENAME 2 LEN
DOS DISK DRIVE 2
DOS FILENAME 2 ADDR
BLOAD/BSAVE STARTING ADDRESS
....AND ENDING ADDRESS
DOS LOGICAL ADDR
DOS PHYS ADDR
DOS SEC. ADDR
DOS RECORD LENGTH
DOS DISK ID
DOS DSK ID FLG
SPACE USED BY PRINT USING
POINTER TO BEGIN. NO.
POINTER TO END NO.
DOLLAR FLAG
COMMA FLAG
COUNTER
SIGN EXPONENT
POINTER TO EXPONENT
# OF DIGITS BEFORE DECIMAL
POINT
JUSTIFY FLAG
# OF POS BEFORE DECIMAL POINT
(FIELD)
# OF POS AFTER DECIMAL POINT
(FIELD)
+ / - F L A G (FIELD)
EXPONENT FLAG (FIELD)
SWITCH
CHAR COUNTER (FIELD)
SIGN NO
BLANK/STAR FLAG
POINTER TO BEGIN OF FIELD
LENGTH OF FORMAT
POINTER TO END OF FIELD
SYSTEM STACK ($0137-$01FF)
INPUT BUFFER: BASIC & MONITOR
($0200-$02Al)

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

BASIC/DOS INTERFACE VARS

FETCH
FETVEC
STASH
STAVEC
CMPARE
CMPVEC
JSRFAR
JMPFAR

02A2
02AA
02AF
02B9
02BE
02C8
02CD
02E3

674
682
687
697
702
712
716
739

LDA(-),Y FROM ANY BANK

STA(-),Y TO ANY BANK
CMP(-),Y TO ANY BANK
JSR XXXX TO ANY BANK & RETURN
JMP XXXX TO ANY BANK

VECTORS
ESC_FN_VEC

02FC

764

BNKVEC

02FE

766

IERROR

0300

768

IMAIN

0302

770

ICRNCH

0304

772

IQPLOP

0306

774

IGONE

0308

776

IEVAL

030A

778

IESCLK

030C

780

IESCPR
IESCEX
IIRQ
CINV
IBRK
CBINV
INMI
IOPEN
ICLOSE
ICHKIN
ICKOUT

030E
0310
0314

782
784
788

VECTOR FOR ADDITIONAL

FUNCTION ROUTINES
VECTOR FOR FUNCTION CART.
USERS
VECTOR FOR PRINT BASIC ERROR
(ERR IN .X)
VECTOR TO MAIN (SYSTEM DHtECT
LOOP)
VECTOR TO CRUNCH
(TOKENIZATION ROUTINE)
VECTOR TO LIST BASIC TEXT
(CHAR LIST)
VECTOR TO GONE (BASIC CHAR
DISPATCH)
VECTOR TO BASIC TOKEN
EVALUATION
VECTOR TO ESCAPE-TOKEN
CRUNCH,
...LIST,
...AND EXECUTE.
IRQ RAM VECTOR

0316

790

BRK INSTR RAM VECTOR

0318
031A
031C
031E
0320

792
794
796
798
800

ICLRCH

0322

802

NMI VECTOR
KERNAL OPEN ROUTINE VECTOR
KERNAL CLOSE ROUTINE VECTOR
KERNAL CHKIN ROUTINE VECTOR
KERNAL CHKOUT ROUTINE
VECTOR
KERNAL CLRCHN ROUTINE
VECTOR

511

512

COMMODORE 128

C128 Memory Map (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

VECTORS
IBASIN
IBSOUT

0324
0326

804
806

ISTOP
IGETIN
ICLALL
EXMON
ILOAD
ISAVE

0328
032A
032C
032E
0330
0332

808
810
812
814
816
818

KERNAL CHRIN ROUTINE VECTOR

KERNAL CHROUT ROUTINE
VECTOR
KERNAL STOP ROUTINE VECTOR
KERNAL GETIN ROUTINE VECTOR
KERNAL CLALL ROUTINE VECTOR
MONITOR COMMAND VECTOR
KERNAL LOAD ROUTINE VECTOR
KERNAL SAVE ROUTINE VECTOR

EDITOR INDIRECT VECTORS

CTLVEC
SHFVEC
ESCVEC
KEYVEC
KEYCHK
DECODE

0334
0336
0338
033A
033C
033E

820
822
824
826
828
830

KEYD

034A

842

TABMAP

0354

852

BITABL

035E

862

LAT
FAT
SAT
CHRGET
CHRGOT
QNUM

0362
036C
0376
0380
0386
0390

866
876
886
896
902
912

EDITOR: PRINT <CONTRL' INDIRECT

EDITOR: PRINT <SHIFTD' INDIRECT
EDITOR: PRINT 'ESCAPE' INDIRECT
EDITOR: KEYSCAN LOGIC flTCHRECT
EDITOR: STORE KEY INDIRECT
VECTORS TO KEYBOARD MATRIX
DECODE TABLES
IRQ KEYBOARD BUFFER (10 BYTES)
BITMAP OF TAB STOPS (10 BYTES,
$0354-D)
BITMAP OF LINE WRAPS
TABMAP AND BITABL GET
SWAPPED TO $0A60 WHEN SCREEN
40/80 MODE IS CHANGED.
LOGICAL FILE NUMBERS
PRIMARY DEVICE NUMBERS
SECONDARY ADDRESSES

INDIRECT LOAD SUBROUTINE AREA

INDSUB_RAM0
INDSUB_RAM1
INDIN1_RAM1
INDIN2
INDTXT

039F
03AB
03B7
03C0
03C9

927
939
950
959
968

SHARED ROM FETCH SUB

SHARED ROM FETCH SUB
INDEX1 INDIRECT FETCH
INDEX2 INDIRECT FETCH
TXTPTR

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

INDIRECT LOAD SUBROUTINE AREA

ZERO
CURRENTBANK
TMPDES
FIN_BANK

03D2
03D5

977
979

03D6
03DA

980
984

SAVSIZ

03DB

985

BITS
SPRTMP_1
SPRTMP_2
FG_BG

03DF
03E0
03E1
03E2

989
990
991
992

FG_MC1

03E3

993

NUMERIC CONSTANT FOR BASIC

CONTEXT FOR SYS,POKE,PEEK
FROM BANK CMMD
TEMP FOR INSTR
BANK POINTER FOR STRING/
NUMBER CONVERT RTN
TEMP WORK LOCATIONS FOR
SSHAPE
F A C # 1 OVERFLOW DIGIT
TEMP FOR SPRSAV
PACKED FOREGROUND/
BACKGROUND COLOR NYBBLES
PACKED FOREGROUND/
MULTICOLOR 1 COLOR NYBBLES

PAGE FOUR & HIGHER DECLARATIONS

VICSCN

0400

1024

0800

2048

(BEGINNING OF BANKABLE RAM)

VIDEO MATRIX #1: VIC 40-COLUMN
TEXT SCREEN
$0400-$07FF
BASIC RUN-TIME STACK (512
BYTES)
$0800-$09FF

ABSOLUTE KERNAL VARIABLES

SYSTEM_VECTOR

0A00

2560

DEJAVU

0A02

2562

PALNTS
INIT_STATUS

0A03
0A04

2563
2564

MEMSTR

0A05

2565

MEMSIZ

0A07

2567

IRQTMP

0A09

2569

CASTON

0A0B

2571

KIKA26
STUPID
TIMOUT
ENABL

0A0C
0A0D
0A0E
0A0F

2572
2573
2574
2575

VECTOR TO RESTART SYSTEM

(BASIC WARM)
KERNAL WARM/COLD INIT'N
STATUS BYTE
PAL/NTSC SYSTEM FLAG
FLAGS RESET VS. NMI STATUS
FOR INIT'N RTNS
PTR TO BOTTOM OF AVAIL.
MEMORY IN SYSTEM BANK
PTR TO TOP OF AVAILABLE
MEMORY IN SYSTEM BANK
TAPE HANDLER PRESERVES IRQ
INDIRECT HERE
TOD SENSE DURING TAPE
OPERATIONS
TAPE READ TEMPORARY
TAPE READ DlIRQ INDICATOR
FAST SERIAL TIMEOUT FLAG
RS-232 ENABLES

513

514

COMMODORE 128

C128 Memory Map (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

ABSOLUTE KERNAL VARIABLES

M51CTR
M51CDR
M51AJB
RSSTAT
BITNUM
BAUDOF

0A10
0A11
0A12
0A14
0A15
0A16

2576
2577
2578
2580
2581
2582

RIDBE

0A18

2584

RIDBS

0A19

2585

RODBS

0A1A

2586

RODBE

0A1B

2587

SERIAL

0A1C

2588

TIMER

0A1D

2589

RS-232 CONTROL REGISTER

RS-232 COMMAND REGISTER
RS-232 USER BAUD RATE
RS-232 STATUS REGISTER
RS-232 NUMBER OF BITS TO SEND
RS-232 BAUD RATE FULL BIT TIME
(CREATED BY OPEN)
RS-232 INPUT BUFFER INDEX TO
END
RS-232 INPUT BUFFER INDEX TO
START
RS-232 OUTPUT BUFFER INDEX TO
START
RS-232 OUTPUT BUFFER INDEX TO
END
FAST SERIAL INTERNAL^XTERNAL
FLAG
DECREMENTING JIFFIE REGISTER

GLOBAL ABSOLUTE SCREEN EDITOR DECLARATIONS

XMAX
PAUSE
RPTFLG
KOUNT
DELAY

0A20
0A21
0A22
0A23
0A24

2592
2593
2594
2595
2596

LSTSHF

0A25

2597

BLNON

0A26

2598

BLNSW
BLNCT
GDBLN

0A27
0A28
0A29

2599
2600
2601

GDCOL
CURMOD

0A2A
0A2B

2602
2603

VM1

0A2C

2604

VM2
VM3
VM4
LINTMP

0A2D
0A2E
0A2F
0A30

2605
2606
2607
2608

KEYBOARD QUEUE MAXIMUM SIZE

<CTRL>S FLAG
ENABLE KEY REPEATS
DELAY BETWEEN KEY REPEATS
DELAY BEFORE A KEY STARTS
REPEATING
DELAY BETWEEN < O > < S H F T >
TOGGLES
VIC CURSOR MODE (BLINKING,
SOLID)
VIC CURSOR DISABLE
VIC CURSOR BLINK COUNTER
VIC CURSOR CHARACTER BEFORE
BLINK
VIC CURSOR COLOR BEFORE BUNK
VDC CURSOR MODE (WHEN
ENABLED)
VIC TEXT SCREEN/CHARACTER
BASE POINTER
VIC BIT-MAP BASE POINTER
VDC TEXT SCREEN BASE
VDC ATTRIBUTE BASE
TEMPORARY POINTER TO LAST
LINE FOR LOOP4

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

GLOBAL ABSOLUTE SCREEN EDITOR DECLARATIONS

SAV80A
SAV80B
CURCOL

0A31
0A32
0A33

2609
2610
2611

SPLIT
FNADRX

0A34
0A35

2612

PALCNT

0A36

SPEED

0A37

SPRITES

0A38

BLANKING

0A39

HOLD_OFF

0A3A

LDTBl_SA

0A3B

CLR_EA_LO
CLR_EA_HI

0A3C
0A3D
0A40

2620
2621
2624

XCNT
HULP
FORMAT
LENGTH
MSAL
SXREG
SYREG
WRAP
XSAVE

0A80
0AA0
OAAA
OAAB
OAAC
OAAF
0AB0
0AB1
0AB2

2688
2720
2730
2731
2732
2735
2736
2737
2738

DIRECTION

0AB3

2739

COUNT
NUMBER
SHIFT
TEMPS

0AB4
0AB5
0AB6
0AB7

2740
2741
2742
2743

2613
2614
2615
2616
2617
2618
2619

TEMPORARY FOR 80-COL ROUTEVJES

TEMPORARY FOR 80-COL ROUTINES
VDC CURSOR COLOR BEFORE
BLINK
VIC SPLIT SCREEN RASTER VALUE
SAVE .X DURING BANK
OPERATIONS
COUNTER FOR PAL SYSTEMS
(JIFFIE ADJUSTMENT)
SAVE SYSTEM SPEED DURING TAPE
AND SERIAL OPS
SAVE SPRITE ENABLES DURING
TAPE AND SERIAL OPS
SAVE BLANKING STATUS DURING
TAPE OPS
FLAG SET BY USER TO RESRV
FULL CNTRL OF VIC
HI BYTE: SA OF VIC SCRN (USE
W/VM1 TO MOVE SCRN)
8563 BLOCK FILL
8563 BLOCK FILL
$0A40-$0A7F RESERVED SWAP
AREA FOR SCREEN VARIABLES
WHEN (40/80) MODE CHANGES
MONITOR'S DOMAIN
COMPARE BUFFER (32 BYTES)

ASM/DIS
FOR ASSEMBLER
1 BYTE TEMP USED ALL OVER
1 BYTE TEMP USED ALL OVER
1 BYTE TEMP FOR ASSEMBLER
SAVE .X HERE DURING INDIRECT
SUBROUTINE CALLS
DIRECTION INDICATOR FOR
'TRANSFER'
PARSE NUMBER CONVERSION
PARSE NUMBER CONVERSION
PARSE NUMBER CONVERSION

FUNCTION KEY ROM CARD TABLES

CURBNK

0AC0

2752

CURRENT FUNCTION KEY ROM

BANK BEING POLLED

515

516

COMMODORE 128

C128 Memory Map (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

FUNCTION KEY ROM CARD TABLES

PAT

0AC1

2753

0AC5

2757

0AC6

2758

0B00

2810

RS232I
RS2320

0C00
0D00
0E00

3072
3328
3584

PKYBUF

1000

4096

PKYDEF

100A

4106

DOSSTR

1100

4352

VWORK
XYPOS
XPOS
YPOS
XDEST
YDEST
XYABS
XABS
YABS
XYSGN
XSGN
YSGN
FCT
ERRVAL
LESSER
GREATR

1131
1131
1131
1133
1135
1137
1139
1139
113B
113D
113D
113F
1141
1145
1147
1148

4401
4401
4401
4403
4405
4407
4409
4409
4411
4413
4413
4415
4417
4421
4423
4424

ANGSGN
SINVAL

1149
114A

4425
4426

DK_FLAG

TBUFFR

PHYSICAL ADDRESS TABLE(IDS OF

LOGGED-IN CARDS)
RESERVED FOR FOREIGN SCREEN
EDITORS
$0AC6-$0AFF RESERVED FOR
SYSTEM
CASSETTE BUFFER (192 BYTES)
$0B00-$0BC0, THIS PAGE ALSO
USED AS A BUFFER FOR THE DISK
AUTO-BOOT
RS-232 INPUT BUFFER
RS-232 OUTPUT BUFFER
SPRITE DEFINITION AREA (MUST
BE BELOW $1000)
$0E00-$0FFF, 512 BYTES
PROGRAMMABLE FUNCTION KEY
LENGTHS TABLE FOR 10 KEYS
(Fl-F8, <SHIFT RUN>, HELP)
PROGRAMMABLE FUNCTION KEY
STRINGS

DOS/VSP AREA
DOS OUTPUT STR. BUF
48 BYTES TO BUILD DOS STRING
GRAPHICS VARS
CURRENT X POSITION
CURRENT Y POSITION
X-COORDINATE DESTINATION
Y-COORDINATE DESTINATION
LINE DRAWING VARIABLES

ANGLE ROUTINE VARIABLES

SIGN OF ANGLE
SINE OF VALUE OF ANGLE

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

DOS/VSP AREA
COSVAL
ANGCNT

114C
114E

4428
4430

COSINE OF VALUE OF ANGLE

TEMPS FOR ANGLE DISTANCE
ROUTINES

BASIC GRAPHIC VARIABLES.

THE FOLLOWING 24 BYTES ARE MULTIPLY DEFINED.
XCIRCL
YCIRCL
XRADUS
YRADUS
ROTANG
ANGBEG
ANGEND
XRCOS
YRSIN
XRSIN
YRCOS

1150
1152
1154
1156
1158
115C
115E
1160
1162
1164
1166

XCENTR
YCENTR
XDIST1
YDIST1
XDIST2
YDIST2
DISEEND
COLCNT
ROWCNT
STRCNT

1150
1152
1154
1156
1158
115A
115C
115E
115F
1160

4432
4434
4436
4438
4440
4442
4444
4446
4447
4448

XCORDl
YCORDl
BOXANG
XCOUNT
YCOUNT
BXLENG
XCORD2
YCORD2

1150
1152
1154
1156
1158
115A
115C
115E

4432
4434
4436
4438
4440
4442
4444
4446

4432
4434
4436
4438
4440
4444
4446
4448
4450
4452
4454

CIRCLE DRAWING VARIABLES

CIRCLE CENTER, X COORDINATE
CIRCLE CENTER, Y COORDINATE
X RADIUS
Y RADIUS
ROTATION ANGLE
ARC ANGLE START
ARC ANGLE END
X RADIUS * COS(ROTATION ANGLE)
Y RADIUS * SIN(ROTATION ANGLE)
X RADIUS * SIN(ROTATION ANGLE)
Y RADIUS * COS(ROTATION ANGLE)

BASIC GENERAL USE PARAMETERS

PLACEHOLDER
CHAR'S COL. COUNTER

BOX-DRAWING VARIABLES
POINT 1 X-COORD.
POINT 1 Y-COORD.
ROTATION ANGLE

LENGTH OF A SIDE

SHAPE AND MOVE-SHAPE VARIABLES

KEYLEN
KEYNXT
STRSZ

1151
1152
1153

4433
4434
4435

STRING LEN

517

518

COMMODORE 128

C128 Memory Map (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

SHAPE AND MOVE-SHAPE VARIABLES

GETTYP
STRPTR
OLDBYT
NEWBYT
XSIZE
YSIZE
XSAVE
STRADR
BITIDX

1154
1155
1156
1157
1158
1159
115B
115D
115F
1161

4436
4437
4438
4439
4440
4441
4443
4445
4447
4449

REPLACE SHAPE MODE

STRING POS'N COUNTER
OLD BIT MAP BYTE
NEW STRING OR BIT MAP BYTE
PLACEHOLDER
SHAPE COLUMN LENGTH
SHAPE ROW LENGTH
TEMP FOR COLUMN LENGTH
SAVE SHAPE STRING DESCRIPTOR
BIT INDEX INTO BYTE

BASIC GRAPHIC VARIABLES

CHRPAG

1168

4456

BITCNT
SCALEM
WIDTH
FILFLG
BITMSK
NUMCNT
TRCFLG
RENUM_TMP_1
RENUM_TMP_2
T3
T4
VTEMP3
VTEMP4
VTEMP5
ADRAYI

1169
116A
116B
116C
116D
116E
116F
1170
1172
1174
1175
1177
1178
1179
117A

4457
4458
4459
4460
4461
4462
4463
4464
4466
4468
4469
4471
4472
4473
4474

ADRAY2

117C

4476

SPRITE_DATA

117E

4478

VIC_SAVE

11D6

4566

UPPER_LOWER

llEB

4587

UPPER_GRAPHIC
DOSSA

llEC
llED

4588
4589

HIGH BYTE: ADDR OF CHARROM

FOR 'CHAR' CMD.
TEMP FOR GSHAPE
SCALE MODE FLAG
DOUBLE WIDTH FLAG
BOX FILL FLAG
TEMP FOR BIT MASK
FLAGS TRACE MODE
A TEMP FOR RENUMBER
A TEMP FOR RENUMBER

GRAPHIC TEMP STORAGE

PTR TO ROUTINE: CONVERT

FLOAT ^ INTEGER
PTR TO ROUTINE: CONVERT
INTEGER ^ FLOAT
SPRITE SPEED/DIRECTION TABLES
($117E-D5)
COPY OF VIC REG'S, USED TO
UPDATE CHIP DURING RETRACE
(21 BYTES, $llD6-EA)
POINTER TO UPPER/LOWER CHAR
SET FOR CHAR
PTR. TO UPPEM,RAPfflC CHAR. SET
TEMP STORAGE FOR FILE SA
DURING RECORD CMD

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

BASIC GENERAL NON-ZP STORAGE

OLDLIN
OLDTXT

1200
1202

4608
4610

PREVIOUS BASIC LINE NUMBER

POINTER: BASIC STATEMENT FOR
CONTINUE

PRINT USING DECLARATIONS

PUCHRS
PUFILL
PUCOMA
PUDOT
PUMONY
ERRNUM

1204
1204
1205
1206
1207
1208

ERRLIN

1209

TRAPNO

120B

TMPTRP
ERRTXT
TEXT_TOP
MAX_MEM_0

120D
120E
1210
1212

4621
4622
4624
4626

TMPTXT

1214

4628

TMPLIN
USRPOK
RNDX
CIRCLE_SEGMENT
DEJAVU

1216
1218
121B
1220
1221

4630
4632
4635
4640
4641

4612
4612
4613
4614
4615
4616
4617
4619

PRINT USING FILL SYMBOL

PRINT USING COMMA SYMBOL
PRINT USING D.P. SYMBOL
PRINT USING MONETARY SYMBOL
USED BY ERROR TRAPPING
ROUTINE-LAST ERR NO
LINE # OF LAST ERROR$FFFF IF
NO ERROR
LINE TO GO TO ON ERROR. $FFXX
IF NONE SET
HOLD TRAP # TEMPOR.
TOP OF TEXT POINTER
HIGHEST ADDRESS AVAILABLE
TO BASIC IN RAM 0
USED BY DO-LOOP. COULD BE
MULT. ASSIGNED

DEGREES PER CIRCLE SEGMENT

'COLD' OR <WARM' RESET STATUS

BASIC STORAGE FOR MUSIC VECTORS

TEMPO_RATE
VOICES
NTIME
OCTAVE
SHARP
PITCH
VOICE
WAVE0
DNOTE
FLTSAV
FLTFLG
NIBBLE
TONNUM

1222
1223
1229
122B
122C
122D
122F
1230
1233
1234
1238
1239
123A

4642
4643
4649
4651
4652
4653
4655
4656
4659
4660
4664
4665
4666

519

520

COMMODORE 128

C128 Memory Map (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

BASIC STORAGE FOR MUSIC VECTORS

TONVAL
PARCNT
ATKTAB
SUSTAB
WAVTAB
PULSLW
PULSHI
FILTERS

123B
123E
123F
1249
1253
125D
1267
1271

INT_TRIPJLAG
INT_ADR_LO
INT_ADR_HI
INTVAL
COLTYP

1276
1279
127C
127F
1280

4667
4668
4669
4681
4691
4701
4711
4721
INTERRUPT VECTORS
4726
4729
4732
4735
4736

BASIC SOUND COMMAND VARS

SOUND_VOICE
SOUND_TIME_LO
SOUND_TIMEJU
SOUND_MAX_LO
SOUNDJMAX_HI
SOUNDJVHN_LO
SOUND_MIN_HI
SOUND_DIRECTION
SOUND_STEP_LO
SOUND_STEPJH
SOUND_FREQ_LO
SOUND__FREQ_HI
TEMP_TIME_LO
TEMP_TIME_HI
TEMP_MAX_LO
TEMP_JVIAX__HI
TEMPJVMN__LO
TEMPJMIN__HI
TEMP_DIRECTION
TEMP_STEP_LO
TEMP_STEP_HI
TEMP__FREQ_LO
TEMP__FREQJflI
TEMP_PULSE_LO
TEMP_PULSE_HI
TEMP_WAVEFORM

1281
1282
1285
1288
128B
128E
1291
1294
1297
129A
129D
12A0
12A3
12A4
12A5
12A6
12A7
12A8
12A9
12AA
12AB
12AC
12AD
12AE
12AF
12B0

4737
4738
4741
4744
4747
4750
4753
4756
4759
4762
4765
4768
4771
4772
4773
4774
4775
4776
4777
4778
4779
4780
4781
4782
4783
4784

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

POT_TEMP_l

12B1

4785

POT_TEMP_2
WINDOW_TEMP
SAVRAM
DEFMOD
LINCNT
SPRITE_NUMBER
IRQ_WRAP_FLAG

12B2
12B3
12B7
12FA
12FB
12FC
12FD

4786
4787
4791
4858
4859
4860
4861

1300

4864

APPLICATION PROGRAM AREA

$1300-$lBFF

1C00

7168

1C00

7168

START OF BASIC TEXT $1C00$EFFF (KERNAL SETS MEMBOT

HERE)
OR
VIDEO MATRIX # 2 (1KB OF
COLORS FOR BITMAP, IF
ALLOCATED) $1C00-$1FFF

2000

8192

DECIMAL
ADDRESS

DESCRIPTION

BASIC SOUND COMMAND VARS

RAMBOT

TEMPORARIES FOR 'POT'

FUNCTION

USED BY
USED BY
USED BY
USED BY
USED BY
ALL BUT

SPRDEF & SAVSPR

SPRDEF & SAVSPR
SPRDEF & SAVSPR
SPRDEF & SAVSPR
BASIC IRQ TO BLOCK
ONE IRQ CALL

VIC BITMAP (8KB, IF ALLOCATED)

$2000-$3FFF

BEGINNING OF ROM OVER RAM

4000

16384

C128 BASIC LO ROM

START OF BASIC TEXT IF BIT MAP
IS ALLOCATED (RAM)
$4000-$EFFF

8000

32768

C128 BASIC HI ROM (OR FUNCTION

ROM) $8000-$BFFF

BASIC JUMP TABLE

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

JMP HARD_RESET
JMP SOFT_RESET
JMP BASIC_IRQ

4000
4003
4006

DECIMAL
ADDRESS

DESCRIPTION

BASIC ENTRY
16384
16387
16390

COLD ENTRY
WARM ENTRY
IRQ ENTRY

FORMAT CONVERSIONS
JMP AYINT
JMP GIVAYF

AF00
AF03

44800
44803

CONVERT F.P. TO INTEGER

CONVERT INTEGER TO F.P.

521

522

COMMODORE 128

Basic Jump Table (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

FORMAT CONVERSIONS
JMP
JMP
JMP
JMP

FOUT
VAL_1
GETADR
FLOATC

AF06
AF09
AFOC
AFOF

JMP FSUB
JMP FSUBT
JMP FADD
JMP FADDT
JMP FMULT
JMP FMULTT
JMP FDIV
JMP FDIVT
JMP LOG
JMP INT
JMP SQR
JMP NEGOP
JMP FPWR
JMP FPWRT
JMP EXP
JMP COS
JMP SIN
JMP TAN
JMP ATN
JMP ROUND
JMP ABS
JMP SIGN
JMP FCOMP
JMP RND 0

AF12
AF15
AF18
AFlB
AFlE
AF21
AF24
AF27
AF2A
AF2D
AF30
AF33
AF36
AF39
AF3C
AF3F
AF42
AF45
AF48
AF4B
AF4E
AF51
AF54
AF57

44806
44809
44812
44815

CONVERT
CONVERT
CONVERT
CONVERT

F.P. TO ASCII STRING

ASCII STRING TO F.P.
F.P. TO AN ADDRESS
ADDRESS TO F.P.

MATH FUNCTIONS
44818
44821
44824
44827
44830
44833
44836
44839
44842
44845
44848
44851
44854
44857
44860
44863
44866
44869
44872
44875
44878
44881
44884
44887

MEM - FACC
ARG - FACC
MEM + FACC
ARG - FACC
MEM * FACC
ARG * FACC
MEM / FACC
ARG / FACC
COMPUTE NATURAL LOG OF FACC
PERFORM BASIC INT ON FACC
COMPUTE SQUARE ROOT OF FACC
NEGATE FACC
RAISE ARG TO THE MEM POWER
RAISE ARG TO THE FACC POWER
COMPUTE EXP OF FACC
COMPUTE COS OF FACC
COMPUTE SIN OF FACC
COMPUTE TAN OF FACC
COMPUTE ATN OF FACC
ROUND FACC
ABSOLUTE VALUE OF FACC
TEST SIGN OF FACC
COMPARE FACC WITH MEM
GENERATE RANDOM F.P. NUMBER

MOVEMENT
JMP
JMP
JMP
JMP
JMP
JMP
JMP

CONUPK
ROMUPK
MOVFRM
MOVFM
MOVMF
MOVFA
MOVAF

AF5A
AF5D
AF60
AF63
AF66
AF69
AF6C

44890
44893
44896
44899
44902
44905
44908

MOVE
MOVE
MOVE
MOVE
MOVE
MOVE
MOVE

RAM MEM TO ARG

ROM MEM TO ARG
RAM MEM TO FACC
ROM MEM TO FACC
FACC TO MEM
ARG TO FACC
FACC TO ARG

OTHER BASIC ROUTINES

JMP OPTAB
JMP DRAWLN

AF6F
AF72

44911
44914

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

OTHER BASIC ROUTINES

JMP GPLOT
JMP CIRSUB
JMP RUN
JMP RUNC
JMP CLEAR
JMP NEW
JMP LNKPRG
JMP CRUNCH
JMP FNDLIN
JMP NEWSTT
JMP EVAL
JMP FRMEVL
JMP R U N _ A _
PROGRAM
JMP SETEXC
JMP LINGET
JMP GARBA2
JMP EXECUTE_A_
LINE

AF75
AF78
AF7B
AF7E
AF81
AF84
AF87
AF8A
AF8D
AF90
AF93
AF96

44917
44920
44923
44926
44929
44932
44935
44938
44941
44944
44947
44950

AF99
AF9C
AF9F
AFA2

44953
44956
44959
44962

AFA5

44965
MONITOR ENTRY

JMP CALL
JMP BREAK
JMP MONCMD

B000
B003
B006

45056
45059
45062

C000

49152

MONITOR CALL ENTRY

MONITOR BREAK ENTRY
MONITOR COMMAND PARSER
ENTRY
KERNAL (OR FUNCTION) ROM
$C000-$FFFF

EDITOR JUMP TABLE

MEMORY
ADDRESS

HEXADECIMAL

DECIMAL

LABEL

ADDRESS

ADDRESS

DESCRIPTION

JMP CINT
JMP DISPLY

C000
C003

49152
49155

JMP LP2

C006

49158

JMP LOOP5

C009

49161

JMP PRINT
JMP SCRORG

C00C
C00F

49164
49167

INITIALIZE EDITOR & SCREEN

DISPLAY CHARAC IN .A, COLOR
IN .X
GET KEY FROM IRQ BUFFER
INTO .A
GET A CHR FROM SCRN LINE
INTO.A
PRINT CHARACTER IN .A
GET # OF SCRN ROWS, COLS
INTO X&Y

523

524

COMMODORE 128

EditorJump Table (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

JMP SCNKEY
JMP REPEAT

C012
C015

49170
49173

JMP PLOT

C018

49176

JMP CURSOR
JMP ESCAPE

C01B
C01E

49179
49182

JMP KEYSET

C021

49185

JMP IRQ
JMP INIT80

C024
C027

49188
49191

JMP SWAPPER

C02A

49194

JMP WINDOW

C02D

49197

D000

53248

DESCRIPTION

SCAN KEYBOARD SUBROUTINE

HANDLE REPEAT KEY&STORE
DECODED KEY
READ OR SET CRSR POSITION IN
.X, .Y
MOVE 8563 CURSOR SUBROUTINE
EXECUTE ESC FUNCTION USING
CHR IN .A
REDEFINE A PROGRAMMABLE
FUNC'N KEY
IRQ ENTRY
INITIALIZE 80-COLUMN
CHARACTER SET
SWAP EDITOR LOCALS (40/80
CHANGE)
SET TOP-LEFT OR BOT-RIGHT OF
WINDOW
VIC CHARACTER ROM
($D000-$DFFF)

VIC CHIP REGISTERS

VICREG0
VICREG1
VICREG2
VICREG3
VICREG4
VICREG5
VICREG6
VICREG7
VICREG8
VICREG9
VICREG10
VICREG11
VICREG12
VICREG13
VICREG14
VICREG15
VICREG16

D000
D001
D002
D003
D004
D005
D006
D007
D008
D009
D00A
D00B
D00C
D00D
D00E
D00F
D010

53248
53249
53250
53251
53252
53253
53254
53255
53256
53257
53258
53259
53260
53261
53262
53263
53264

SPRITE 0, X-LOCATION
SPRITE 0, Y-LOCATION
SPRITE 1, X-LOCATION
SPRITE 1, Y-LOCATION
SPRITE 2, X-LOCATION
SPRITE 2, Y-LOCATION
SPRITE 3, X-LOCATION
SPRITE 3, Y-LOCATION
SPRITE 4, X-LOCATION
SPRITE 4, Y-LOCATION
SPRITE 5, X-LOCATION
SPRITE 5, Y-LOCATION
SPRITE 6, X-LOCATION
SPRITE 6, Y-LOCATION
SPRITE 7, X-LOCATION
SPRITE 7, Y-LOCATION
MSBIT OF X-LOCATION FOR
SPRITES 0-7

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

VIC CHIP REGISTERS

VICREG17

D011

53265

VIC CONTROL REGISTER 1

7
6

VICREG18

D012

53266

VICREG19
VICREG20
VICREG21

D013
D014
D015

53267
53268
53269

VICREG22

D016

53270

RASTER COMPARE BIT

EXTENDED COLOR TEXT
MODE (1 = ON)
BIT MAP MODE (1 = ENABLE)
BLANK SCREEN TO BORDER
CLR (0 = BLANK)
SELECT 24/25 ROW TEXT
DISPLAY (1 = 25)
2^)
SMOOTH SCROLL TO Y
DOT POSITION
READ/WRITE RASTER VALUE FOR
COMPARE IRQ
LIGHT PEN LATCH X-POSITION
LIGHT PEN LATCH Y-POSITION
SPRITES 0-7 DISPLAY ENABLE
(1 = ENABLE)
VIC CONTROL REGISTER 2
BITS
7^6
5
4
3
2^)

VICREG23
VICREG24

D017
D018

53271
53272

UNUSED
RESET
MULTI-COLOR MODE
(1 = ENABLE)
SELECT 38/40 COLUMN
DISPLAY ( 1 - 4 0 COLS)
SMOOTH SCROLL TO
X-POSITION

SPRITES 0-7 Y EXPAND

VIC MEMORY CONTROL REGISTER
BITS ($D018)
7^4
3^)

VIDEO MATRIX BASE

ADDRESS
CHARACTER DOT-DATA
BASE ADDRESS

525

526

COMMODORE 128

C128 Memory Map (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

VIC CHIP REGISTERS

VICREG25

D019

53273

VIC INTERRUPT FLAG REGISTER

(l = IRQ OCCURRED)

&-4
3

2
1
0
VICREG26

D01A

53274

IRQ ENABLE (1 = ENABLED) BITS

1-4
3
2
1
0

VICREG27

D01B

53275

VICREG28

D01C

53276

VICREG29
VICREG30

D01D
D01E

53277
53278

VICREG31

D01F

53279

VICREG32
VICREG33
VICREG34
VICREG35
VICREG36
VICREG37
VICREG38
VICREG39
VICREG40
VICREG41
VICREG42

D020
D021
D022
D023
D024
D025
D026
D027
D028
D029
D02A

53280
53281
53282
53283
53284
53285
53286
53287
53288
53289
53290

SET ON ANY ENABLED VIC

IRQ CONDITION
NOT USED
LIGHT PEN TRIGGERED
IRQ FLAG
SPRITE TO SPRITE
COLLISION IRQ FLAG
SPRITE TO BACKGROUND
COLLISION IRQ FLAG
RASTER COMPARE IRQ
FLAG

NOT USED
LIGHT PEN
SPRITE TO SPRITE
SPRITE TO BACKGROUND
IRQ

SPRITES 0-7 BACKGROUND

PRIORITY (1 = SPRITE)
SPRITES 0-7 MULTI-COLOR MODE
(1 = MULTI-COLOR)
SPRITES 0-7 X EXPAND
SPRITE TO SPRITE COLLISION
LATCH
SPRITE TO BACKGROUND
COLLISION LATCH
BORDER COLOR
BACKGROUND COLOR 0
BACKGROUND COLOR 1
BACKGROUND COLOR 2
BACKGROUND COLOR 3
SPRITE MULTI-COLOR REGISTER 0
SPRITE MULTI-COLOR REGISTER 1
SPRITE 0 COLOR
SPRITE 1 COLOR
SPRITE 2 COLOR
SPRITE 3 COLOR

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

VIC CHIP REGISTERS

VICREG43
VICREG44
VICREG45
VICREG46
VICREG47

D02B
D02C
D02D
D02E
D02F

53291
53292
53293
53294
53295

SPRITE 4 COLOR
SPRITE 5 COLOR
SPRITE 6 COLOR
SPRITE 7 COLOR
KEYBOARD LINES
BITS
7-3
2r4)

VICREG48

D030

53296

NOT USED
K2, K1 AND K0

CLOCK SPEED
BITS
7-2
1
0

NOT USED
TEST
2 MHZ

SID REGISTERS
SIDREG0
SIDREG1
SIDREG2
SIDREG3
SIDREG4

D400
D401
D402
D403
D404

54272
54273
54274
54275
54276

VOICE
VOICE
VOICE
VOICE
VOICE
7
6
5
4
3

SIDREG5

D405

54277

1
1
1
1
1

FREQUENCY LO
FREQUENCY HI
PULSE WIDTH LO
PULSE WIDTH HI (0-15)
CONTROL REGISTER

NOISE
PULSE
SAW
TRI
TEST

(1
(1
(1
(1
(1

= NOISE)
= PULSE)
= SAWTOOTH)
= TRIANGLE)
= DISABLE
OSCILLATOR)
RING (1 = RU^G MODULATE
OSC 1 WITH OSC
3 OUTPUT)
SYNC (1 = SYNCHRONIZE
OSC 1 WITH OSC
3 FREQ)
GATE (1 = START ATTACK/
DECAY/SUSTAIN
0 = START RELEASE)

VOICE 1 ATTACK/DECAY
l^X
3^)

ATTACK (0-15)
DECAY (0-15)

527

528

COMMODORE 128

C128 Memory Map (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

SID REGISTERS
SIDREG6

D406

54278

VOICE 1 SUSTAIN/RELEASE
7-4
3^)

SIDREG7
SIDREG8
SIDREG9
SIDREG10
SIDREG11

D407
D408
D409
D40A
D40B

54279
54280
54281
54282
54283

VOICE
VOICE
VOICE
VOICE
VOICE

SUSTAIN (0-15)
RELEASE (0-15)
2
2
2
2
2

FREQUENCY LO
FREQUENCY HI
PULSE WIDTH LO
PULSE WIDTH HI (0-15)
CONTROL REGISTER

(1 = NOISE)
(1 = PULSE)
(1 = SAWTOOTH)
(1 = TRIANGLE)
(1 = DISABLE
OSCILLATOR)
RING (1 = RING MODULATE
OSC 2 WITH OSC
1 OUTPUT)
SYNC (1 = SYNCHRONIZE
OSC 2 WITH OSC
1 FREQ)
GATE (1 = START ATTACK/
DECAY/SUSTAIN
0: START RELEASE)
NOISE
PULSE
SAW
TRI
TEST

SIDREG12

D40C

54284

VOICE 2 ATTACK/DECAY
7^4
m

SIDREG13

D40D

54285

VOICE 2 SUSTAIN/RELEASE
7^4
3^)

SIDREG14
SIDREG15
SIDREG16
SIDREG17

D40E
D40F
D410
D411

54286
54287
54288
54289

ATTACK (0-15)
DECAY (0-15)

VOICE
VOICE
VOICE
VOICE

SUSTAIN (0-15)
RELEASE (0-15)
3
3
3
3

FREQUENCY LO
FREQUENCY HI
PULSE WIDTH LO
PULSE WIDTH HI (0-15)

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

SID REGISTERS
SIDREG18

D412

54290

VOICE 3 CONTROL REGISTER

NOISE)
PULSE)
SAWTOOTH)
(1 = 1TRIANGLE)
(1 = DISABLE
OSCILLATOR)
RING (1 = RING MODULATE
OSC 3 WITH OSC
2 OUTPUT)
SYNC (1 = SYNCHRONIZE
OSC 3 WITH OSC
2 FREQ)
GATE (1 = START ATTACK/
DECAY/SUSTAIN
0 = START RELEASE)
NOISE
PULSE
SAW
TRI
TEST

SIDREG19

D413

54291

VOICE 3 ATTACK/DECAY
7^4
3^)

SIDREG20

D414

54292

D415
D416
D417

54293
54294
54295

ATTACK (0-15)
DECAY (0-15)

VOICE 3 SUSTAIN/RELEASE
7^4
3^)

SIDREG21
SIDREG22
SIDREG23

(1
(1
(1

SUSTAIN (0-15)
RELEASE (0-15)

FILTER CUTOFF FREQUENCY LO

FILTER CUTOFF FREQUENCY HI
RESONANCE/FILTER
l-A
3
2
1
0

FILTER RESONANCE (0-15)

FILTER EXTERNAL INPUT
(l = YES)
FILTER VOICE 3 OUTPUT
(1 = YES)
FILTER VOICE 2 OUTPUT
(l = YES)
FILTER VOICE 1 OUTPUT
(1 = YES)

529

530

COMMODORE 128

C128 Memory Map (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

SID REGISTERS
SIDREG24

D418

54296

MODE/VOLUME
7
6
5
4
^4)

SIDREG25
SIDREG26
SIDREG27

D419
D41A
D41B

54297
54298
54299

SIDREG28

D41C

54300

CUTOFF VOICE 3 OUTPUT

(1 = OFF)
SELECT HI-PASS FILTER
(l = ON)
SELECT BAND-PASS FILTER
(1 - ON)
SELECT LO-PASS FILTER
(l = ON)
OUTPUT VOLUME (0-15)

POT X, Aft) CONVERTER, PADDLE 1

POT Y, Afl) CONVERTER, PADDLE 2
OSCILLATOR 3, RANDOM NUMBER
GENERATOR
ENVELOPE GENERATOR 3 OUTPUT

C128 MEMORY MANAGEMENT UNIT, PRIMARY REGISTERS

IMPLEMENTS C128, C64, & CP/M 3.0 MODES
MMUCR1
D500
CONFIGURATION REGISTER
54528
PCRA
D501
PRECONFIGURATION REGISTER
54529
PCRB
D502
PRECONFIGURATION REGISTER
54530
PCRC
D503
PRECONFIGURATION REGISTER
54531
PCRD
D504
PRECONFIGURATION REGISTER
54532
BITS ($D500-$D504)
7^6
5^4
3-2
1
0

MMUMCR

D505

54533

A
B
C
D

RAM BANK (0-3)

ROM HI
(SYSTEM, INT,
EXT, RAM)
ROM MID (SYSTEM, INT,
EXT, RAM)
ROM LO
(SYSTEM, RAM)
l/O
(I/O BLOCK,
ELSE ROM-HI)

MODE CONFIGURATION REGISTER

7
6
5
4
3
2-1
0

40/80 KEY SENSE

OS MODE, 0 = C128/1 = C64
/EXROM LINE SENSE
/GAME LINE SENSE
FSDIR
NOT USED
PROCESSOR, 0 = Z80/l - 8 5 0 2

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

C128 MEMORY MANAGEMENT UNIT, PRIMARY REGISTERS

IMPLEMENTS C128, C64, & CP/M 3,O MODES
MMURCR

D506

54534

RAM CONFIGURATION REGISTER

7^>
5^4
3-2
1^)

MMUPOL

D507

54535

MMUPOH

D508

54536

MMUPlL

D509

54537

MMUPlH

D50A

54538

VIC RAM BANK (VA17 &

VA16)
RAM BLOCK (FOR FUTURE
EXPANSION)
RAM SHARE STATUS (NONE,
BOT, TOP, BOTH)
RAM SHARE AMOUNT ( l K ,
4K, 8K, 16K)

PAGE 0
SWAPS PAGE0
POINTER LOW
AND/OR PAGE1
PAGE 0
WITH ANY
POINTER HIGH
OTHER PAGE IN
PAGE 1
THE 256K
POINTER LOW
ADDRESS SPACE
PAGE 1
POINTER HIGH
BITS ($D508 & $D50A)
7^4
3-2
1^)

A19-A18 (USED IN 1MB

SYSTEM)
A17-A16 (256K SYSTEM)

BITS ($D507 & $D509)

7_0
MMUVER

D50B

54539

A15-A8

MMU VERSION NUMBER

7^4
3^)

BANK VERSION
MMU VERSION

C128 8O-COLUMN VIDEO DISPLAY CONTROLLER

VDCADR

D600

54784

8563 ADDRESS REGISTER

531

532

COMMODORE 128

C128 Memory Map (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

ADDRESS AND DATA REGISTER BITS

D600

WRITE
READ

VDCDAT
D601-

STATUS
D601

LP

D7

D6

-DATA

R5
R4
R3 R2 R1 R0
VBLANK

54785
8563 DATA REGISTER
D5

D4

D3

D2

D1 DO

ADDITIONAL 8563 REGISTERS ARE NOT VISIBLE TO THE 8502

D700
D800

VICCOL

55040
55296

RESERVED I/O BLOCK

VIC COLOR MATRIX, 1 KB
($D800-$DBFF)

6526 CIA#1, COMPLEX INTERFACE ADAPTER # 1

KEYBOARD, JOYSTICK, PADDLES, LIGHTPEN, FAST DISK
DlPRA

DC00

56320

PORT A (OUTPUT KEYBOARD

COLUMNS)

BITS ($DC00)
0
1
2
3
4
5
6
7

PRA0 ::
PRA1 ::
PRA2 ::
PRA3 ::
PRA4 ::
PRA5 ::
PRA6 ::
PRA7 ::

DlPRB
BITS ($DC01)
0
1
2
3
4
5
6
7

KEYBD O/P
KEYBD O/P
KEYBD O/P
KEYBD O/P
KEYBD O/P
KEYBD O/P
KEYBD O/P
KEYBD O/P
DC01

PRB0 :: KEYBD
PRB1 :: KEYBD
PRB2 :: KEYBD
PRB3 :: KEYBD
PRB4 :: KEYBD
PRB5 :: KEYBD
PRB6 :: KEYBD
PRB7 :; KEYBD

DlDDRA
DlDDRB
DlTlL

I/P
I/P
I/P
I/P
I/P
I/P
I/P
I/P

DC02
DC03
DC04

CO/JOY
Cl/JOY
C2/JOY
C3/JOY
C4/JOY
C5/
C6/
C7/

#1
#1
#1
#1
#1

DIRECTION
DIRECTION
DIRECTION/PADDLE FIRE BUTTON
DIRECTION/PADDLE FIRE BUTTON
FIRE BUTTON
/SELECT PORT # 1 PADDLES
/SELECT PORT # 2 PADDLES

56321

PORT B (INPUT KEYBOARD ROWS)

TOGGLE /PULSE OUTPUT

56322
56323
56324

DATA DIRECTION PORT A

DATA DIRECTION PORT B
TA LO

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

6526 CIA#1, COMPLEX INTERFACE ADAPTER # 1

KEYBOARD, JOYSTICK, PADDLES, LIGHTPEN, FAST DISK
DlTlH
DlT2L
DlT2H
DlTODl
DlTODS
DlTODM
DlTODH
DlSDR
DlICR
DlCRA
DlCRB

DC05
DC06
DC07
DC08
DC09
DCOA
DCOB
DCOC
DCOD
DCOE
DCOF

56325
56326
56327
56328
56329
56330
56331
56332
56333
56334
56335

TA HI (TIMER A)
TB LO
TB HI (TIMER B)
TOD (TENTHS)
TOD (SECONDS)
TOD (MINUTES)
TOD (HOURS)
SERIAL DATA REGISTER
INTERRUPT CONTROL REGISTER
CONTROL REGISTER A
CONTROL REGISTER B

6526 C I A # 2 COMPLEX INTERFACE ADAPTER # 2

USER PORT,RS-232,SERIAL BUS,VIC MEMORY,NMI
D2PRA

DD00

56576

PORT A, SERIAL BUS, RS-232, VA14

& VA15
BITS
0
1
2
3
4
5
6
7

PRA0 : VA14
PRA1 : VA15
PRA2 : RS232
DATA
OUTPUT
PRA3 : SERIAL ATN
OUTPUT
PRA4 : SERIAL CLK
OUTPUT
PRA5 : SERIAL DATA
OUTPUT
PRA6 : SERIAL CLK INPUT
PRA7 : SERIAL DATA INPUT

533

534

COMMODORE 128

C128 Memory Map (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

D2PRB

DD01

56577

DESCRIPTION

PORT B, USER PORT, RS-232

BITS
PRB0 : USER PORT / RS-232
RECEIVED DATA
PRB1 : USER PORT / RS-232
REQUEST TO SEND
PRB2 : USER PORT / RS-232
DATA TERMINAL READY
PRB3 : USER PORT / RS-232
RING INDICATOR
PRB4 : USER PORT / RS-232
CARRIER DETECT
PRB5 : USER PORT
PRB6 : USER PORT / RS-232
CLEAR TO SEND
PRB7 : USER PORT / RS-232
DATA SET READY

D2DDRA
D2DDRB
D2TlL
D2TlH
D2T2L
D2T2H
D2TODl
D2TODS
D2TODM
D2TODH
D2SDR
D2ICR

DD02
DD03
DD04
DD05
DD06
DD07
DD08
DD09
DD0A
DD0B
DD0C
DD0D

56578
56579
56580
56581
56582
56583
56584
56585
56586
56587
56588
56589

D2CRA
D2CRB

DD0E
DD0F

56590
56591

DATA DIRECTION PORT A

DATA DIRECTION PORT B
TA LO
TA HI (TIMER A)
TB LO
TB HI (TIMER B)
TOD (TENTHS)
TOD (SECONDS)
TOD (MINUTES)
TOD (HOURS)
SERIAL DATA REGISTER
INTERRUPT CONTROL REGISTERS
(NMI'S)
CONTROL REGISTER A
CONTROL REGISTER B

101

DE00

56832

EXPANSION I/O SLOT (RESERVED)

102

DF00

57088

EXPANSION I/O SLOT (RESERVED)

DMA ST

DF00

57088

C128 DMA CONTROLLER FOR

EXPANSION RAM ACCESS
OPTIONAL DEVICE MAPPED INTO
102 BLOCK VIA SYSTEM
EXPANSION PORT (PRELIMINARY)
DMA CONTROLLER STATUS
REGISTER (READ ONLY)

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

INTERRUPT
PENDING (1 = INT.
WAITING TO BE
SERVICED)
END OF BLOCK
(1 = TRANSFER
COMPLETE)
FAULT (1 =BLOCK
VERIFY ERROR)
SIZE (0 = EXP.
MEMORY =
128K)
(l = EXP.
MEMORY =
512K)
VERSION
DMA CMD

DF01

57089

DMA CONTROLLER COMMAND

REGISTER
7
6
5

3
2
1-0

DMA ADL

DF02

57090

DMA ADH

DF03

57091

DMA LO

DF04

57092

DMA HI

DF05

57093

DMA BNK

DF06

57094

EXECUTE
RESERVED
LOAD (1 = ENABLE
AUTO = LOAD)
$FF00 (1 =DISABLE $FF00
DECADES)
RESERVED
RESERVED
MODE (00 = TRANSFER
FROM INTERNAL TO
EXTERNAL,
01 = FROM EXT TO INT,
10 = SWAP, 11 = VERIFY)

LSB OF INTERNAL (C128) ADDRESS

TO ACCESS
MSB OF INTERNAL (C128) ADDRESS
TO ACCESS
LSB OF EXTERNAL EXPANSION
RAM TO ACCESS
MSB OF EXTERNAL EXPANSION
RAM TO ACCESS
64K EXTERNAL RAM BANK
BITS ($DF06)

535

536

COMMODORE 128

C128 Memory Map (continued)

MEMORY
ADDRESS
LABEL

HEXADECIMAL
ADDRESS

DECIMAL
ADDRESS

DESCRIPTION

7-3
2^)
DMA DAL
DMA DAH

DF07
DF08

57095
57096

DMA SUM

DF09

57097

NOT USED
EXPANSION BANK NUMBER

LSB OF BYTE COUNT

MSB OF BYTE COUNT (BLOCK
COUNT)
INTERRUPT MASK REGISTER
INTERRUPT ENABLE
(1 = INTERRUPTS ENABLED)
END OF BLOCK MASK
(1 = INTERRUPT ON END
OF BLOCK)
VERIFY ERROR
(1 = INTERRUPT ON VERIFY
ERROR)

DMA VER

DF0A

57098

E000

57344

ADDRESS CONTROL REGISTER

BITS 7 AND 6
0,0 = INCREMENT BOTH ADDRESS
(DEFAULT)
0,1 = FIX EXPANSION ADDRESS.
1.0 = FIX C128 ADDRESS.
1.1 = FIX BOTH ADDRESSES.
KERNAL ROM (8K OPERATING
SYSTEM, $E000-$FFFF)

MMU SECONDARY REGISTERS

MMUCR

FF00

65280

LCRA

FF01

65281

LCRB

FF02

65282

LCRC

FF03

65283

LCRD

FF04

65284

CONFIGURATION REGISTER
(SECONDARY)
LOAD CONFIGURATION
REGISTER A
LOAD CONFIGURATION
REGISTER B
LOAD CONFIGURATION
REGISTER C
LOAD CONFIGURATION
REGISTER D
BITS ($FF00-$FF04)
1^6
5^4
3-2
1
0

RAM BANK (0-3)

ROM HI
(SYSTEM, INT,
EXT, RAM)
ROM MID (SYSTEM, INT,
EXT, RAM)
(SYSTEM, RAM)
ROM LO
(I/O ELSE ROMI/O
HI)

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

KERNAL JUMP TABLE

NEW ENTRIES FOR CI28
JMP SPIN SPOUT

FF47

65351

JMP CLOSE ALL

FF4A

65354

JMP C64MODE

FF4D

65357

JMP DMA CALL

FF50

65360

JMP BOOT CALL

FF53

65363

JMP PHOENIX

FF56

65366

JMP LKUPLA

FF59

65369

JMP LKUPSA

FF5C

65372

JMP SWAPPER

FF5F

65375

JMP DLCHR

FF62

65378

JMP PFKEY

FF65

65381

JMP SETBNK

FF68

65384

JMP GETCFG

FF6B

65387

JMP JSRFAR

FF6E

65390

JMP JMPFAR
JMP INDFET

FF71
FF74

65393
65396

JMP INDSTA

FF77

65499

JMP INDCMP

FF7A

65402

JMP PRIMM

FF7D

65405

SET UP FAST SERIAL PORT

FOR I/O
CLOSE ALL LOGICAL
FILES FOR A DEVICE
RECONFIGURE SYSTEM
AS A C64 (NO RETURN)
INITIATE DMA REQUEST
TO EXTERNAL RAM
EXPANSION, SEND
COMMAND TO DMA
DEVICE
BOOT LOAD PROGRAM
FROM DISK
CALL ALL FUNCTION
CARDS' COLD START
ROUTINES, INITIALIZE
SEARCH TABLES FOR
GIVEN LA
SEARCH TABLES FOR
GIVEN SA
SWITCH BETWEEN 40 AND
80 COLUMNS (EDITOR)
INIT 8O-COL CHARACTER
RAM (EDITOR)
PROGRAM FUNCTION KEY
(EDITOR)
SET BANK FOR I/O
OPERATIONS
LOOKUP MMU DATA FOR
GIVEN BANK
JSR TO ANY BANK, RTS
TO CALLING BANK
JMP TO ANY BANK
LDA (FETVEC), Y FROM
ANY BANK
STA (STAVEC), Y TO ANY
BANK
CMP (CMPVEC),Y TO ANY
BANK
PREVT IMMEDIATE UTUJTY
(ALWAYS JSR TO THIS
ROUTINE)

STANDARD KERNAL JUMP TABLE

JMP CINT

FF80

65408

FF81

65409

RELEASE NUMBER OF
KERNAL
INIT EDITOR & DISPLAY
CHIPS (EDITOR)

S37

538

COMMODORE 128

C128 Memory Map (continued)

STANDARD KERNAL JUMP TABLE
JMP IOINIT

FF84

65412

JMP RAMTAS

FF87

65415

JMP RESTOR

FF8A

65418

JMP VECTOR

FF8D

65421

JMP
JMP
JMP
JMP

SETMSG
SECND
TKSA
MEMTOP

FF90
FF93
FF96
FF99

65424
65427
65430
65433

JMP MEMBOT

FF9C

65436

JMP KEY

FF9F

65439

JMP SETTMO

FFA2

65442

JMP ACPTR

FFA5

65445

JMP CIOUT

FFA8

65448

JMP UNTLK
JMP UNLSN

FFAB
FFAE

65451
65454

JMP
JMP
JMP
JMP
JMP

LISTN
TALK
READSS
SETLFS
SETNAM

FFB1
FFB4
FFB7
FFBA
FFBD

65457
65460
65463
65460
65469

JMP
JMP
JMP
JMP
JMP

(IOPEN)
(ICLOSE)
(ICHKIN)
(ICKOUT)
(ICLRCH)

FFC0
FFC3
FFC6
FFC9
FFCC

OPEN
CLOSE
CHKIN
CKOUT
CLRCH

65472
65475
65478
65481
65484

JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP

(IBASIN)
(IBSOUT)
LOADSP
SAVESP
SETTIM
RDTIM
(ISTOP)
(IGETIN)
(ICLALL)

FFCF
FFD2
FFD5
FFD8
FFDB
FFDE
FFE1
FFE4
FFE7

BASIN
BSOUT

65487
65490
65493
65496
65599
65502
65505
65508
65511

STOP
GETIN
CLALL

INIT I/O DEVICES (PORTS,

TIMERS, ETC.)
INITIALIZE RAM AND
BUFFERS FOR SYSTEM
RESTORE VECTORS TO
INITIAL SYSTEM
CHANGE VECTORS FOR
USER
CONTROL O.S. MESSAGE
SEND SA AFTER LISTEN
SEND SA AFTER TALK
SET/READ TOP OF SYSTEM
RAM
SET/READ BOTTOM OF
SYSTEM RAM
SCAN KEYBOARD
(EDITOR)
SET TIMEOUT IN IEEE
(RESERVED)
HANDSHAKE SERIAL BYTE
T
M
lIN
HANDSHAKE SERIAL BYTE
OUT
SEND UNTALK OUT SERIAL
SEND UNLISTEN OUT
SERIAL
SEND LISTEN OUT SERIAL
SEND TALK OUT SERIAL
RETURN I/O STATUS BYTE
SET LA, FA, SA
SET LENGTH AND FILE
NAME ADDRESS
OPEN LOGICAL FILE
CLOSE LOGICAL FILE
SET CHANNEL IN
SET CHANNEL OUT
RESTORE DEFAULT I/O
CHANNEL
INPUT FROM CHANNEL
OUTPUT TO CHANNEL
LOAD FROM FILE
SAVE TO FILE
SET INTERNAL CLOCK
READ INTERNAL CLOCK
SCAN STOP KEY
READ BUFFERED DATA
CLOSE ALL FILES AND
CHANNELS

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

STANDARD KERNAL JUMP TABLE

JMP UDTIM

FFEA

JMP SCRORG

FFED

65517

JMP PLOT

FFF0

65520

JMP IOBASE
SYSTEM

FFF3
FFF8

65523
65528

NMI
RESET

FFFA
FFFC

65530
65532

IRQ

FFFE

65534

CLOCK

65514

INCREMENT INTERNAL
CLOCK
RETURN SCREEN WINDOW
SIZE (EDITOR)
READ/SET X,Y CURSOR
COORD (EDITOR)
RETURN I/O BASE
OPERATING SYSTEM
VECTOR (RAMI)
PROCESSOR NMI VECTOR
PROCESSOR RESET
VECTOR
PROCESSOR IRQ/BRK
VECTOR

KERNAL/EDITOR FLAGS AND

SHADOW REGISTERS
The following symbols are used by the C128 Editor. Note that the Editor IRQ VIC
screen handler depends upon them. In most cases the contents of these locations will be
placed directly into the appropriate register and should be used instead of the actual
register. For example, to change the location of the character set used by VIC, use VM1
($0A2C) instead of VIC register 24 ($D018). VM1 will be used by the editor to update
VIC register 24.

ADDRESS/NAME

EXPLANATION

$00D8/GRAPHM
$00D9/CHAREN
$0A2C/VM1

SEE BELOW. IF - $FF THEN EDITOR LEAVES VIC ALONE.

MASK FOR 8502 /CHAREN BIT.
VIC TEXT MODE VIDEO MATRIX & CHARACTER BASE
POINTER.
VIC GRAPHIC MODE VIDEO MATRIX & BIT MAP
POINTER.
8563 TEXT DISPLAY BASE ADDRESS.
8563 ATTRIBUTE BASE ADDRESS.
IN SPLIT SCREEN MODE, CONTAINS VALUE FOR
MIDDLE RASTER IRQ.
8563 CURSOR MODE.
CONTROL S FLAG (IN EFFECT - $13)

$0A2D/VM2
$0A2E/VM3
$0A2F/VM4
$0A34/SPLIT
$OA2B/CURMOD
$0A21/PAUSE

539

540

COMMODORE 128

E X P L A N A T I O N OF VARIOUS KERNAL/EDITOR FLAG BYTES, ETC.

ADDRESS SYMBOL

DESCRIPTION
7

0000
0001
00F7
00F8
00D3
0A22
0A26
00F9
00D8
00D7
0A04

D6510

R6510
LOCKS
CASE
SCROLL
OFF

SHFLAG
RPTFLG
ALL
BLNON
ON
BEEPER
ON
GRAPHM
MCM
MODE
40/80
INIT_
CHRSET
STATUS

(OUT)
(IN)
(OUT)
(OUT) (OUT) (OUT)
(IN)
CAPKEY CASMTR CASSEN CASWRT CHAREN HIRAM LORAM

CTL S
LINKER

ALT
ALPHA
CTRL
SHIFT

NONE

BLNK

SPLIT

BMM

CINT

BASIC

Notes on Kernal Symbols:

lnit_Status. See also above. Lets system know what has been initialized and what
hasn't. Set to $00 by a reset but untouched by NMI.
S y s t e m _ V e c t o r . Where the Kernal goes when it has to go somewhere. It's set to
BASIC cold at reset. BASIC itself sets it to BASIC warm after it has initialized.
The monitor respects it too.
System. Vector in R A M I at $FFF8. Set at power-up to C 1 2 8 M O D E , user may redirect
it to his code. Taken at reset always providing user with control (protection) from
reset.

COMMODORE 64 MEMORY MAP

HEX

DECIMAL

LABEL

ADDRESS

LOCATION

DESCRIPTION

D6510
R6510

0000
0001

0
1

ADRAY1

0002
0003^)004

2
3^1

ADRAY2

0005^)006

5-6

CHARAC
ENDCHR

0007
0008

7
8

6510 On-Chip Data-Direction Register

6510 On-Chip 8-Bit Input/Output
Register
Unused
Jump Vector: Convert Floating
Integer
Jump Vector: Convert Integer
Floating
Search Character
Flag: Scan for Quote at End of String

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

LABEL

HEX
ADDRESS

DECIMAL
LOCATION

TRMPOS
VERCK
COUNT
DIMFLG
VALTYP

0009
000A
000B
000C
000D

9
10
11
12
13

INTFLG

000E

14

GARBFL

000F

15

SUBFLG

0010

16

INPFLG

0011

17

TANSGN
LINNUM
TEMPPT
LASTPT
TEMPST
INDEX
RESHO
TXTTAB
VARTAB
ARYTAB
STREND
FRETOP
FRESPC
MEMSIZ

0012
0013
0014^)015
0016
0017^)018
0019^)021
0022^)025
0026^)02A
002B^)02C
002D^)02E
002F-0030
0031^)032
0033^)034
0035^)036
0037^)038

18
19
20-21
22
23-24
25-33
34-37
38^42
43^44
45^46
47^48
49-50
51-52
53-54
55-56

CURLIN
OLDLIN
OLDTXT
DATLIN
DATPTR
INPPTR
VARNAM
VARPNT

0039^)03A
003B^)03C
003D^)03E
003F^)040
0041^)042
0043^)044
0045^)046
0047^)048

57-58
59^>0
61-62
63^>4
65^6
67^>8
69-70
71-72

FORPNT
FACEXP

0049^)04A
004B^)060
0061

73-74
75-96
97

FACHO
FACSGN

0062^)065
0066

98-101
102

DESCRIPTION

Screen Column From Last TAB

Flag: 0 = Load, 1 = Verify
Input Buffer Pointer/No. of Subscripts
Flag: Default Array DIMension
Data Type: $FF = String, $00 =
Numeric
Data Type: $80 = Integer, $00 =
Floating
Flag: DATA scan/LIST quote/
Garbage Coll
Flag: Subscript Ref / User Function
Call
Flag: $00 = INPUT, $40 = GET,
$98 = READ
Flag: TAN sign / Comparison Result
Flag: INPUT Prompt
Temp: Integer Value
Pointer: Temporary String Stack
Last Temp String Address
Stack for Temporary Strings
Utility Pointer Area
Floating-Point Product of Multiply
Pointer: Start of BASIC Text
Pointer: Start of BASIC Variables
Pointer: Start of BASIC Arrays
Pointer: End of BASIC Arrays ( + 1)
Pointer: Bottom of String Storage
Utility String Pointer
Pointer: Highest Address Used by
BASIC
Current BASIC Line Number
Previous BASIC Line Number
Pointer: BASIC Statement for CONT
Current DATA Line Number
Pointer: Current DATA Item Address
Vector: INPUT Routine
Current BASIC Variable Name
Pointer: Current BASIC Variable
Data
Pointer: Index Variable for FOR/NEXT
Temp Pointer / Data Area
Floating-Point Accumulator # 1 :
Exponent
Floating Accum. # 1 : Mantissa
Floating Accum. # 1 : Sign

541

542

COMMODORE 128

Commodore

64 Memory Map

(continued)

LABEL

HEX
ADDRESS

DECIMAL
LOCATION

SGNFLG
BITS
ARGEXP

0067
0068
0069

103
104
105

ARGHO
ARGSGN
ARISGN

006A^)06D
006E
006F

106-109
110
111

FACOV

0070

112

FBUFPT
CHRGET

0071^)072
0073^)08A

113-114
115-138

CHRGOT

0079

121

TXTPTR
RNDX
STATUS
STKEY
SVXT
VERCK
C3PO

007A^)07B
008B-008F
0090
0091
0092
0093
0094

122-123
139-143
144
145
146
147
148

BSOUR
SYNO
LDTND

0095
0096
0097
0098

149
150
151
152

DFLTN
DFLTO
PRTY
DPSW
MSGFLG

0099
009A
009B
009C
009D

153
154
155
156
157

PTR1
PTR2
TIME

009E
009F
00A0^)0A2

158
159
160-162

CNTDN
BUFPNT
INBIT
BITCI

00A3^)0A4
00A5
00A6
00A7
00A8

163-164
165
166
167
168

RINONE

00A9

169

DESCRIPTION

Pointer: Series Evaluation Constant

Floating Accum. #1: Overflow Digit
Floating-Point Accumulator #2:
Exponent
Floating Accum. #2: Mantissa
Floating Accum. #2: Sign
Sign Comparison Result: Accum. # 1
vs # 2
Floating Accum. #1. Low-Order
(Rounding)
Pointer: Cassette Buffer
Subroutine: Get Next Byte of BASIC
Text
Entry to Get Same Byte of Text
Again
Pointer: Current Byte of BASIC Text
Floating RND Function Seed Value
Kernal I/O Status Word: ST
Flag: STOP key / RVS key
Timing Constant for Tape
Flag: 0 = Load, 1 = Verify
Flag: Serial BusOutput Char.
Buffered
Buffered Character for Serial Bus
Cassette Sync No.
Temp Data Area
No. of Open Files / Index to File
Table
Default Input Device (0)
Default QuipuUCMD) Device (3)
Tape Character Parity
Flag: Tape Byte-Received
Flag: $80 - Direet Mode, $00 =
Program
Tape Pass 1 Error Log
Tape Pass 2 E*ror Log
Real-Time Jiffy Clock (approx) 1/60
Sec
Temp Data Area
Cassette Sync Countdown
Pointer: Tape I/O Buffer
RS-232 Input Bits / Cassette Temp
RS-232 Input Bit Count / Cassette
Temp
RS-232 Flag: Check for Start Bit

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

LABEL

HEX
ADDRESS

DECIMAL
LOCATION

RIDATA

00AA

170

RIPRTY

00AB

171

SAL
EAL
CMPO
TAPE1
BITTS

00AC^)0AD
00AEM)0AF
00B0^)0B1
00B2^)0B3
00B4

172-173
174-175
176-177
178-179
180

NXTBIT

00B5

181

RODATA
FNLEN
LA
SA
FA
FNADR
ROPRTY
FSBLK
MYCH
CAS1
STAL
MEMUSS
LSTX

00B6
00B7
00B8
00B9
00BA
00BB^)0BC
00BD
00BE
00BF
00C0
00C1^)0C2
00C3^)0C4
00C5

182
183
184
185
186
187-188
189
190
191
192
193-194
195-196
197

NDX

00C6

198

RVS

00C7

199

INDX

00C8

200

LXSP
SFDX
BLNSW

00C9^)0CA
00CB
00CC

201-202
203
204

BLNCT
GDBLN
BLNON
CRSW
PNT
PNTR
QTSW

00CD
00CE
00CF
00D0
00D1^)0D2
00D3
00D4

205
206
207
208
209-210
211
212

LNMX

00D5

213

DESCRIPTION

RS-232 Input Byte Buffer/Cassette

Temp
RS-232 Input Parity / Cassette Short
Cnt
Pointer: Tape Buffer/Screen Scrolling
Tape End Addresses / End of Program
Tape Timing Constants
Pointer: Start of Tape Buffer
RS-232 Out Bit Count / Cassette
Temp
RS-232 Next Bit to Send / Tape EOT
Flag
RS-232 Out Byte Buffer
Length of Current File Name
Current Logical File Number
Current Secondary Address
Current Device Number
Pointer: Current File Name
RS-232 Out Parity / Cassette Temp
Cassette Read/Write Block Count
Serial Word Buffer
Tape Motor Interlock
I/O Start Address
Tape Load Temps
Current Key Pressed: CHR$(n) 0 =
No Key
No. of Chars, in Keyboard Buffer
(Queue)
Flag: Print Reverse Chars.1 =
Yes, 0 = Not Used
Pointer: End of Logical Line for
INPUT
Cursor X-Y Pos. at Start of INPUT
Flag: Print Shifted Chars.
Cursor Blink enable: 0 = Flash
Cursor
Timer: Countdown to Toggle Cursor
Character Under Cursor
Flag: Last Cursor Blink On/Off
Flag: INPUT or GET from Keyboard
Pointer: Current Screen Line Address
Cursor Column on Current Line
Flag: Editor in Quote Mode, $00 =
NO
Physical Screen Line Length

543

544

COMMODORE 128

Commodore

64 Memory Map

(continued)

LABEL

HEX
ADDRESS

DECIMAL
LOCATION

TBLX

00D6

214

INSRT
LDTB1

00D7
00D8
00DSMMF2

215
216
217-242

USER

00F3-00F4

243-244

KEYTAB
RIBUF
ROBUF
FREKZP
BASZPT

BAD
BUF
LAT

00F5-00F6
00F7-00F8
00F9-00FA
00FB-00FE
00FF
0100^)1FF
0100^)10A
0100^)13E
0200^)258
0259^)262

245-246
247-248
249-250
251-254
255
256-511
256-266
256-318
512-600
601-610

FAT

0263^)26C

611-620

SAT

026D^)276

621^30

KEYD
MEMSTR
MEMSIZ
TIMOUT

0277^)280
0281^)282
0283^)284
0285

631-640
641-642
643-644
645

COLOR
GDCOL
HIBASE
XMAX
RPTFLG

0286
0287
0288
0289
028A

646
647
648
649
650

KOUNT
DELAY
SHFLAG

028B
028C
028D

651
652
653

LSTSHF
KEYLOG
MODE

028E
028F-0290
0291

654
655-656
657

AUTODN
M51CTR
M51CDR

0292
0293
0294

658
659
660

DESCRIPTION

Current Cursor Physical Line

Number
Temp Data Area
Flag: Insert Mode, > 0 = # INSTs
Screen Line Link Table / Editor
Temps
Pointer: Current Screen Color RAM
loc.
Vector: Keyboard Decode Table
RS-232 Input Buffer Pointer
RS-232 Output Buffer Pointer
Free 0-Page Space for User Programs
BASIC Temp Data Area
Micro-Processor System Stack Area
Floating to String Work Area
Tape Input Error Log
System INPUT Buffer
KERNAL Table: Active Logical File
Mr*'c
I>0 s.
KERNAL Table: Device No. for Each
File
KERNAL Table: Second Address
Each File
Keyboard Buffer Queue (FIFO)
Pointer: Bottom of Memory for O.S.
Pointer: Top of Memory for O.S.
Flag: Kernal Variable for IEEE
Timeout
Current Character Color Code
Background Color Under Cursor
Top of Screen Memory (Page)
Size of Keyboard Buffer
Flag: REPEAT Key Used, $80 =
Repeat
Repeat Speed Counter
Repeat Delay Counter
Flag: Keyb'rd SHIFT Key / CTRL
Key /
Key
Last Keyboard Shift Pattern
Vector: Keyboard Table Setup
Flag: $00 = Disable SHIFT Keys,
$80 = Enable SHIFT Keys
Flag: Auto Scroll Down, 0 = ON
RS-232: 6551 Control Register Image
RS-232: 6551 Command Register
Image

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

LABEL

HEX
ADDRESS

DECIMAL
LOCATION

M51AJB

0295^296

661-662

RSSTAT
BITNUM
BAUDOF
RIDBE
RIDBS
RODBS
RODBE

0297
0298
0299^)29A
029B
029C
029D
029E

663
664
665^66
667
668
669
670

IRQTMP
ENABL

029F-02A0
02A1
02A2
02A3
02A4

671^>72
673
674
675
676

02A5
02A6

677
678

02A7^)2FF
0300^)301
0302^)303
0304^)305
0306^)307
0308^)309
030A^)30B
030C
030D
030E
030F
0310
031Mtfl2
0313
0314^)315
0316^)317
0318^)319
031A^)31B
031C^)31D
031E-031F
0320^)321
0322^)323
0324^)325
0326^)327
0328^)329
032A-4)32B
032C^)32D
032E-032F

697-767
768-769
770-771
772-773
774-775
776-777
778-779
780
781
782
783
784
785-786
787
788-789
790-791
792-793
794-795
796-797
798-799
800-801
802-803
804-805
806-807
808-809
810-811
812-813
814-815

IERROR
IMAIN
ICRNCH
IQPLOP
IGONE
IEVAL
SAREG
SXREG
SYREG
SPREG
USRPOK
USRADD
CINV
CBINV
NMINV
IOPEN
ICLOSE
ICHKIN
ICKOUT
ICLRCH
IBASIN
IBSOUT
ISTOP
IGETIN
ICLALL
USRCMD

DESCRIPTION

RS-232 Non-Standard BPS

(Time/2-100) USA
RS-232: 6551 Status Register Image
RS-232 Number of Bits Left to Send
RS-232 Baud Rate: FuII Bit Time (^s)
RS-232 Index to End of Input Buffer
RS-232 Start of Input Buffer (Page)
RS-232 Start of Output Buffer (Page)
RS-232 Index to End of Output
Buffer
Holds IRQ Vector During Tape I/O
RS-232 Enables
TOD Sense During Cassette I/O
Temp Storage For Cassette Read
Temp DlIRQ Indicator For Cassette
Read
Temp for Line Index
PAL/NTSC Flag, 0 - NTSC, 1 =
PAL
Unused
Vector: Print BASIC Error Message
Vector: BASIC Warm Start
Vector: Tokenize BASIC Text
Vector: BASIC Text LIST
Vector: BASIC Char. Dispatch
Vector: BASIC Token Evaluation
Storage for 6502 .A Register
Storage for 6502 .X Register
Storage for 6502 .Y Register
Storage for 6502 .SP Register
USR Function Jump Instr (4C)
USR Address Low Byte / High Byte
Unused
Vector: Hardware IRQ Interrupt
Vector: BRK Instr. Interrupt
Vector: Non-Maskable Interrupt
KERNAL OPEN Routine Vector
KERNAL CLOSE Routine Vector
KERNAL CHKIN Routine Vector
KERNAL CHKOUT Routine Vector
KERNAL CLRCHN Routine Vector
KERNAL CHRIN Routine Vector
KERNAL CHROUT Routine Vector
KERNAL STOP Routine Vector
KERNAL GETIN Routine Vector
KERNAL CLALL Routine Vector
User-Defined Vector

545

546

COMMODORE 128

Commodore

64 Memory Map

LABEL

HEX
ADDRESS

DECIMAL
LOCATION

0330^)331
0332^333
0334^)33B
033003FB
03FC^)3FF
0400^)7FF
0400^)7E7

816^17
818-819
820-827
828-1019
1020-1023
1024-2047
1024-2023

07F8^)7FF
0800-9FFF
8000-9FFF
A000-BFFF

2040-2047
2048^40959
32768^40959
40960^49151

C000-CFFF
D000-DFFF

49152-53247
53248-57343

E000-FFFF

57344^5535

ILOAD
ISAVE
TBUFFR
VICSCN

(continued)
DESCRIPTION

KERNAL LOAD Routine Vector

KERNAL SAVE Routine Vector
Unused
Tape I/O Buffer
Unused
1024 Byte Screen Memory Area
Video Matrix: 25 Lines x 40
Columns
Sprite Data Pointers
Normal BASIC Program Space
VSP Cartridge ROM8192 Bytes
BASIC ROM8192 Bytes (or 8K
RAM)
RAM4096 Bytes
Input/Output Devices and Color
RAM
or Character Generator ROM
or RAM^4096 Bytes
KERNAL ROM8192 Bytes (or 8K
RAM)

COMMODORE 64 INPUT/OUTPUT ASSIGNMENTS

HEX

DECIMAL

BITS

DESCRIPTION

0000

7^)

0001

MOS 6510 Data Direction Register

(xxl01111)
Bit = l: Output, Bit = 0:
Input, x = Either
MOS 6510 Micro-Processor On-Chip
I/O Port
/LORAM Signal (0 = Switch BASIC
ROM Out)
/HIRAM Signal (0 = Switch Kernal
ROM Out)
/CHAREN Signal (0 = Switch Char.
ROM In)
Cassette Data Output Line
Cassette Switch Sense
1 - Switch Closed
Cassette Motor Control
0 = ON, 1 = OFF
Undefined

0
1
2
3
4
5
6-7

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

HEX

DECIMAL

D000-D02E

53248-54271

D000
D001
D002
D003
D004
D005
D006
D007
D008
D009
D00A
D00B
D00C
D00D
D00E
D00F
DOlO
D011

53248
53249
53250
53251
53252
53253
53254
53255
53256
53257
53258
53259
53260
53261
53262
53263
53264
53265

BITS

7
6
5
4
3
2-0
D012

53266

D013
D014
D015
D016

53267
53268
53269
53270
7^
5
4
3
2^)

D017
D018

53271
53272
l^X

DESCRIPTION

MOS 6566 VIDEO INTERFACE

CONTROLLER (VIC)
Sprite 0 X Pos
Sprite 0 Y Pos
Sprite 1 X Pos
Sprite 1 Y Pos
Sprite 2 X Pos
Sprite 2 Y Pos
Sprite 3 X Pos
Sprite 3 Y Pos
Sprite 4 X Pos
Sprite 4 Y Pos
Sprite 5 X Pos
Sprite 5 Y Pos
Sprite 6 X Pos
Sprite 6 Y Pos
Sprite 7 X Pos
Sprite 7 Y Pos
Sprites 0 - 7 X Pos (msb of X coord.)
VIC Control Register
Raster Compare: (Bit 8) See 53266
Extended Color Text Mode: 1 =
Enable
Bit-Map Mode: 1 = Enable
Blank Screen to Border Color: 0 =
Blank
Select 24/25 Row Text Display: 1 =
25 Rows
Smooth Scroll to Y Dot-Position (0-7)
Read Raster / Write Raster Value for
Compare IRQ
Light-Pen Latch X Pos
Light-Pen Latch Y Pos
Sprite Display Enable: 1 = Enable
VIC Control Register
Unused
ALWAYS SET THIS BIT TO 0
Multi-Color Mode: 1 = Enable (Text
or Bit-Map)
Select 38/40 Column Text Display: 1
= 40 Cols
Smooth Scroll to X Pos
Sprites 0 - 7 Expand 2 x Vertical (Y)
VIC Memory Control Register
Video Matrix Base Address (inside
VIC)

547

548

COMMODORE 128

Commodore
HEX

D019

64 Input/Output
DECIMAL

Assignments
BITS

DESCRIPTION

3-1

Character Dot-Data Base Address

(inside VIC)
VIC Interrupt Flag Register (Bit =
1: IRQ Occurred)
Set on Any Enabled VIC IRQ
Condition
Light-Pen Triggered IRQ Flag
Sprite to Sprite Collision IRQ Flag
Sprite to Background Collision IRQ
Flag
Raster Compare IRQ Flag
IRQ Mask Register: 1 = Interrupt
Enabled
Sprite to Background
Display Priority: 1 = Sprite
Sprites 0-7 Multi-Color Mode Select:
1 = M.C.M.
Sprites 0-7 Expand 2 x Horizontal
(X)
Sprite to Sprite Collision Detect
Sprite to Background Collision
Detect
Border Color
Background Color 0
Background Color 1
Background Color 2
Background Color 3
Sprite Multi-Color Register 0
Sprite Multi-Color Register 1
Sprite 0 Color
Sprite 1 Color
Sprite 2 Color
Sprite 3 Color
Sprite 4 Color
Sprite 5 Color
Sprite 6 Color
Sprite 7 Color
MOS 6581 SOUND INTERFACE
DEVICE (SID)
Voice 1: Frequency ControlLow-Byte
Voice 1: Frequency ControlHighByte
Voice 1: Pulse Waveform Width
Low-Byte

53273
7
3
2
1
0

D01A

53274

D01B

53275

D01C

53276

D01D

53277

D01E
D01F

53278
53279

D020
D021
D022
D023
D024
D025
D026
D027
D028
D029
D02A
D02B
D02C
D02D
D02E
D400-D7FF

53280
53281
53282
53283
53284
53285
53286
53287
53288
53289
53290
53291
53292
53293
53294
54272-55295

D400
D401

54272
54273

D402

54274

(continued)

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

HEX

DECIMAL

BITS

DESCRIPTION

D403

54275

7^4
3^)

D404

54276

Unused
Voice 1: Pulse Waveform Width
High-Nybble
Voice 1: Control Register
Select Random Noise Waveform, 1 =
On
Select Pulse Waveform, 1 = On
Select Sawtooth Waveform, 1 = On
Select Triangle Waveform, 1 = On
Test Bit: 1 = Disable Oscillator 1
Ring Modulate Osc. 1 with Osc. 3
Output, 1 = On
Synchronize Osc. 1 with Osc. 3
Frequency, 1 = On
Gate Bit: 1 - Start Att/Dec/Sus, 0 =
Start Release
Envelope Generator 1: Attack / Decay
Cycle Control
Select Attack Cycle Duration: 0-15
Select Decay Cycle Duration: 0-15
Envelope Generator 1: Sustain /
Release Cycle Control
Select Sustain Cycle Duration: 0-15
Select Release Cycle Duration: 0-15
Voice 2: Frequency ControlLow-Byte
Voice 2: Frequency Control
High-Byte
Voice 2: Pulse Waveform Width
Low-Byte
Unused
Voice 2: Pulse Waveform Width
High-Nybble
Voice 2: Control Register
Select Random Noise Waveform, 1 =
On
Select Pulse Waveform, 1 = On
Select Sawtooth Waveform, 1 = On
Select Triangle Waveform, 1 = On
Test Bit: 1 = Disable Oscillator 2
Ring Modulate Osc. 2 with Osc. 1
Output, 1 = On
Synchronize Osc. 2 with Osc. 1
Frequency, 1 = On
Gate Bit: 1 = Start Att/Dec/Sus, 0
= Start Release
Envelope Generator 2: Attack / Decay
Cycle Control
Select Attack Cycle Duration: 0-15

7
6
5
4
3
2
1
0
D405

54277
7^4
3-0

D406

54278
7^4
3^)

D407
D40B

54279
54280

D409

54281

D40A

54282

D40B

54283

7^4
3-0

7
6
5
4
3
2
1
0
D40C

54284
7^

549

550

COMMODORE 128

Commodore

64 Input/Output

HEX

DECIMAL

D40D

54285

Assignments
BITS

DESCRIPTION

3-0

Select Decay Cycle Duration: 0-15

Envelope Generator 2: Sustain /
Release Cycle Control
Select Sustain Cycle Duration: 0-15
Select Release Cycle Duration: 0-15
Voice 3: Frequency ControlLow-Byte
Voice 3: Frequency Control
High-Byte
Voice 3: Pulse Waveform Width
Low-Byte
Unused
Voice 3: Pulse Waveform Width
High-Nybble
Voice 3: Control Register
Select Random Noise Waveform, 1 =
On
Select Pulse Waveform, 1 = On
Select Sawtooth Waveform, 1 = On
Select Triangle Waveform, 1 = On
Test Bit: 1 = Disable Oscillator 3
Ring Modulate Osc. 3 with Osc. 2
Output, 1 = On
Synchronize Osc. 3 with Osc. 2
Frequency, 1 = On
Gate Bit: 1 = Start Att/Dec/Sus, 0 =
Start Release
Envelope Generator 3: Attack / Decay
Cycle Control
Select Attack Cycle Duration: 0-15
Select Decay Cycle Duration: 0-15
Envelope Generator 3: Sustain /
Release Cycle Control
Select Sustain Cycle Duration: 0-15
Select Release Cycle Duration: 0-15
Filter Cutoff Frequency: Low-Nybble
(Bits 2r4)
Filter Cutoff Frequency: High-Byte
Filter Resonance Control / Voice
Input Control
Select Filter Resonance: 0-15
Filter External Input: 1 = Yes, 0 =
No
Filter Voice 3 Output: 1 - Yes, 0 =
No
Filter Voice 2 Output: 1 = Yes, 0 =
No

7^4
3^)
D40E
D40F

54286
54287

D410

54288

D411

54289

D412

54290

7^4
3^0

1
6
5
4
3
2
1
0
D413

54291
7^4
3^)

D414

54292
7^4
3-0

D415

54293

D416
D417

54294
54295

(continued)

7^4
3
2
1

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

HEX

D418

DECIMAL

BITS

DESCRIPTION

Filter Voice 1 Output: 1 = Yes, 0 =

No
Select Filter Mode and Volume
Cut-Off Voice 3 Output: 1 - Off, 0
= On
Select Filter High-Pass Mode: 1 =
On
Select Filter Band-Pass Mode: 1 =
On
Select Filter Low-Pass Mode: 1 = On
Select Output Volume: 0-15
Analog/Digital Converter: Game
Paddle 1 (0-255)
Analog/Digital Converter: Game
Paddle 2 (0-255)
Oscillator 3 Random Number
Generator
Envelope Generator 3 Output
SID IMAGES
Color RAM (Nybbles)
MOS 6526 Complex Interface
Adapter (CIA) # 1
Data Port A (Keyboard, Joystick,
Paddles, Light-Pen)
Write Keyboard Column Values for
Keyboard Scan
Read Paddles on Port A / B (01 =
Port A, 10 = Port B)
Joystick A Fire Button: 1 = Fire
Paddle Fire Buttons
Joystick A Direction (0-15)
Data Port B (Keyboard, Joystick,
Paddles): Game Port 1
Read Keyboard Row Values for
Keyboard Scan
Timer B: Toggle/Pulse Output
Timer A: Toggle/Pulse Output
Joystick 1 Fire Button: 1 = Fire
Paddle Fire Buttons
Joystick 1 Direction
Data Direction RegisterPort A
(56320)
Data Direction RegisterPort B
(56321)
Timer A: Low-Byte
Timer A: High-Byte
Timer B: Low-Byte

54296
7
6
5
4
3^)

D419

54297

D41A

54298

D41B

54299

D41C
D500-D7FF
D800-DBFF
DC00-DCFF

54300
54528-55295
55296-56319
56320-56575

DC00

56320
7-0
7^
4
3-2
3^)

DC01

56321
7-0
7
6
4
3-2
3^)

DC02

56322

DC03

56323

DC04
DC05
DC06

56324
56325
56326

551

554

COMMODORE 128

Commodore

64 Input!OutputAssignments

HEX

DECIMAL

DC07
DC08
DC09
DCOA
DCOB

56327
56328
56329
56330
56331

DCOC
DCOD

56332
56333

BITS

7
4
3
2
1
0
DCOE

56334
7
6
5
4
3
2
1
0

DCOF

56335
7
6-5

4-0

(continued)
DESCRIPTION

Timer B: High-Byte
Time-of-Day Clock: 1/10 Seconds
Time-of-Day Clock: Seconds
Time-of-Day Clock: Minutes
Time-of-Day Clock: Hours +
AM/PM Flag (Bit 7)
Synchronous Serial I/O Data Buffer
CIA Interrupt Control Register (Read
IRQVWrite Mask)
IRQ Flag (1 - IRQ Occurred) /
Set-Clear Flag
FLAG1 IRQ (Cassette Read / Serial
Bus SRQ Input)
Serial Port Interrupt
Time-of-Day Clock Alarm Interrupt
Timer B Interrupt
Timer A Interrupt
CIA Control Register A
Time-of-Day Clock Frequency: 1 =
50 Hz, 0*= 60 Hz
Serial Port I/O Mode: 1 = Output, 0
= Input
Timer A Counts: 1 = CNT Signals, 0
= System 02 Clock
Force Load Timer A: 1 = Yes
Timer A Run Mode: 1 = One-Shot,
0 = Continuous
Timer A Output Mode to PB6: 1 =
Toggle, 0 = PuIse
Timer A Output on PB6: 1 = Yes, 0
- No
Start/Stop Timer A: 1 = Start, 0 =
Stop
CIA Control Register B
Set Alarm/TOD-Clock: 1 = Alarm, 0
= Clock
Timer B Mode Select:
00 = Count System 02 Clock Pulses
01 - Count Positive CNT
Transitions
10 = Count Timer A Underflow
Pulses
11 = Count Timer A Underflows
While CNT Positive
Same as CIA Control Reg. Afor
Timer B

THE COMMODORE 128 AND COMMODORE 64 MEMORY MAPS

HEX

DECIMAL

DD00-DDFF

56576-56831

DD00

56576

BITS

7
6
5
4
3
2
1^)
DD01

56577
7
6
5
4
3
2
1
0

DD02
DD03
DD04
DD05
DD06
DD07
DD08
DD09
DDOA
DDOB

56578
56579
56580
56581
56582
56583
56584
56585
56586
56587

DDOC
DDOD

56588
56589
7
4
3
1
0

DDOE

56590
7
6

DESCRIPTION

MOS 6526 Complex Interface

Adapter (CIA) # 2
Data Port A (Serial Bus, RS-232,
VIC Memory Control)
Serial Bus Data Input
Serial Bus Clock Pulse Input
Serial Bus Data Ouput
Serial Bus Clock Pulse Output
Serial Bus ATN Signal Output
RS-232 Data Output (User Port)
VIC Chip System Memory Bank
Seleet (Default = 11)
Data Port B (User Port, RS-232)
User / RS-232 Data Set Ready
User / RS-232 Clear to Send
User
User / RS-232 Carrier Detect
User / RS-232 Ring Indicator
User / RS-232 Data Terminal Ready
User / RS-232 Request to Send
User / RS-232 Received Data
Data Direction RegisterPort A
Data Direction RegisterPort B
Timer A: Low-Byte
Timer A: High-Byte
Timer B: Low-Byte
Timer B: High-Byte
Time-of-Day Clock: 1/10 Seconds
Time-of-Day Clock: Seconds
Time-of-Day Clock: Minutes
Time-of-Day Clock: Hours +
AM/PM Flag (Bit 7)
Synchronous Serial I/O Data Buffer
CIA Interrupt Control Register (Read
NMPs/Write Mask)
NMI Flag (1 = NMI Occurred) /
Set-Clear Flag
FLAG1 NMI (User/RS-232 Received
Data Input)
Serial Port Interrupt
Timer B Interrupt
Timer A Interrupt
CIA Control Register A
Time-of-Day Clock Frequency: 1 =
50 Hz, 0 = 60 Hz
Serial Port I/O Mode: 1 = Output, 0
= Input

553

554

COMMODORE 128

Commodore

64 Input/Output

HEX

DECIMAL

Assignments
BITS

DESCRIPTION

Timer A Counts: 1 = CNT Signals, 0

= System 02 Clock
Force Load Timer A: 1 = Yes
Timer A Run Mode: 1 = One-Shot,
0 = Continuous
Timer A Output Mode to PB6: 1 =
Toggle, 0 = Pulse
Timer A Output on PB6: 1 = Yes, 0
= No
Start/Stop Timer A: 1 = Start, 0 =
Stop
CIA Control Register B
Set Alarm/TOD-Clock: 1 = Alarm, 0
- Clock
Timer B Mode Select:
00 = Count System 02 Clock
Pulses
01 = Count Positive CNT
Transitions
10 = Count Timer A Underflow
Pulses
11 = Count Timer A Underflows
While CNT Positive
Same as CIA Control Reg. Afor
Timer B
Reserved for Future I/O Expansion
Reserved for Future I/O Expansion

4
3
2
1
0
DDOF

56591
7
6-5

4^)
DEOO-DEFF
DF00-DFFF

56832-57087
57088-57343

(continued)

J6
C128 HARDWARE
SPECIFICATIONS

555

554

COMMODORE 128

This chapter describes the Commodore C128 hardware, VLSI integrated circuit requirements, and the relationship between the hardware configuration and the operating
system.
The C128 personal computer is compatible with C64 software and peripherals. In
addition to C64 compatibility, a C128 mode exists in which 128K of RAM is available
for system/user use. BASIC version 7.0 is the default language. The Commodore Kernal
is supported in a compatible fashion.
The C128 also has a Z80 coprocessor that can make full use of system RAM and
Kernal utilities, intended for use with such powerful operating systems as CP/M version
3.0. The Banking ROM scheme allows function key software to be installed internal to
the system or added externally as an expansion cartridge.
Another major feature is the 8563 80-column display capability, available in C128
mode as an addition to the 40-column mode.
Peripheral support includes the Commodore mouse, joystick, paddle, light pen
interface (both 40- and 80-column light pens); the Commodore Datassette; the User Port,
which supports RS232; modems; the Expansion Bus, which supports external memory
expansion; and the Commodore standard Serial Bus, which supports all existing Serial
Bus components. There are also several features intended to reduce software overhead,
such as relocatable zero page and system stack.
In C64 mode, the standard sixty-six keys are available. In C128 mode, twentysix extra keys are available, including separate cursor keys, a HELP key, additional function keys, and a true CAPS LOCK key. The additional keys,
grouped into the alternate keypad, are user-definable, increasing the flexibility and user
friendliness of the system.
The following is a summary of C128 features:

C64 compatibility
80-column display capability
Z80 coprocessor (CP/M version 3.0 (2 MHz))
2 MHz 8502 operation in 80-column mode
128K standard system RAM
48K standard system ROM
32K internal function ROM (optional)
32K external cartridge ROM
Fast serial disk drive interface
Full keyboard, ninety-two keys with CAPS
and separate cursor-control keys.

LOCK

key,

HELP

key

C128 HARDWARE SPECIFICATIONS

SYSTEM ARCHITECTURE
The C128 computer utilizes a shared bus structure similar to that of the C64. The shared
bus emulates dual-port RAM and ROM, which allows the character R O M , color RAM
and system RAM to be shared by both the microprocessor and the 8564 VIC video
controller, with no interference to each other. This requires that the RAM be fast enough
to supply valid data in half the time of a normal microprocessor machine cycle. Normal
sharing is controlled by a coprocessor that will enable or disable the processor during
alternate halves of the machine cycle.
The C128 system splits the address bus into shared and nonshared sections. All
normal 8502 I/O parts are on the nonshared address bus; the VIC chip and its associated
support chips are located on the shared bus. The VIC chip will gate processor addresses
onto the shared bus based upon its AEC control line. The data bus is common to both
sides of the address bus.
The processor interfaces with most of the system chips like a standard 6502 bus
cycle, where a machine cycle is equal to a clock cycle. This allows the use of 1 MHz
parts for a 1 MHz clock and eliminates the need to create valid address and data strobes,
as this information is now supplied by the edges of the master clock, 4>0. Chip selects
for the I/O and system ROM are generated by the PLA that tracks the microprocessor
addresses during <51.
For system RAM access, the row address is the address from the microprocessor, and the column address is the MMU output address (called the Translated Address).
The Translated Address outputs are calculated by considering the contents of the
M M U ' s Configuration Register and RAM Configuration Register. From these values,
the M M U generates either normal or translated addresses, a CAS selection. The
CAS-gating circuitry in the MMU enables either one of the two banks of 64K RAM in a
128K system. For VIC cycle access of RAM, the RAM bank is set independently of the
processor's bank. A write to ROM will result in the write "bleeding through" to RAM
underneath, while a read from ROM will always disable CAS in both banks. The M M U
allows custom arrangements of RAM for both banks 0 and 1.
Banking ROM is effected through the setting of bits in the Configuration Register
contained in the M M U and communicated to the PLA decoder. This allows Banking
Function ROM and any attached C128 cartridge to be included in the basic system
configuration.
The PLA generates chip selects for the color RAM, VIC control registers and
character ROM, which are used during processor and VIC cycles, as well as all chip
selects needed for the processor-only ROM and peripherals. To avoid bus contention,
the PLA must also generate CAS disable for any accesses to ROM or I/O devices.
The VIC chip generates the signals used to control Dynamic Memory and provides
macro-control functions such as RAM refresh. The VIC's primary purpose is to fetch
screen data from memory, using either cycle sharing or DMA, and create an NTSC- or
PAL-compatible video output that is applied to a monitor or modulated and applied to a
TV set. The C128 provides outputs for Composite, Chroma/Luminance and RF video

557

554

COMMODORE 128

outputs from the VIC chip, as well as an edge-triggered light pen input latch going to
the VIC chip.
The output from the SID chip sound generator is buffered and applied directly to
an external amplifier, like that found in an external monitor, or modulated and reproduced in the user's television set. The SID chip also has an external input for mixing
another sound source.
The 8563 video control chip fetches screen data from a dedicated section of RAM
referred to as the display RAM and creates an RGBI (Red-Green-Blue-Intensity) output
for use with an external 80-column monitor. The 8563 also creates all needed signals for
dynamic refresh of its dedicated display RAM. The C128 provides RGBI and composite
monochrome outputs from the 8563 chip.
The cassette port is implemented using the zero page ports available on the 8502
and software control of hardware handshaking. The Commodore serial bus port is implemented in a similar manner using a 6526 CIA for I/O. The serial bus works with
Commodore serial components, and in C64 mode is actually driven by the software
routines contained in the C64. The User Port is a multipurpose port comprising several
parallel port lines that support peripherals such as slow RS232, modem, etc. The
joystick ports are identical to those on the C64 and are implemented using a 6526 CIA
to read/write the port.
The video connector has composite video as well as separate chroma and luminance outputs for use with monitors. The 1701 and 1702 Commodore monitors interface
directly to this connector. The RF output jack supplies an RF signal compatible with the
regulations for TV interface devices and is switch selectable between channels 3 and 4.
Both NTSC and PAL television standards are supported. The RGBI connector and
signal are similar to the ones used by IBM, and are compatible with most monitors
supporting Type I RGBI. Additionally, a composite monochrome signal is available on
the RGBI connector and is generally compatible with NTSC (or PAL) composite. Audio
is available only from the 40-column video/audio connector.

SYSTEM SPECIFICATION
This section
descriptions
loading and
Figure

discusses various features and constraints of the C128 system. Included are
of the system and its configurations and limiting factors such as power,
environment.
16-1 shows the C128 system.

Figure 16I. The CI28 System

554

COMMODORE 128

SYSTEM BUS ARCHITECTURE

The buses described include:

Processor bus
Translated address bus
Multiplexed address bus

Shared address bus

Color data bus
Display bus

THE PROCESSOR BUS

The Processor Bus includes the data and address buses that are connected directly to the
8502 processor. These buses are designated D 0 -D 7 for the 8-bit data bus and A 0 -A 1 5 for the
16-bit address bus. These buses tie the processor to most of the system ROM and I/O
devices, including at least part of all system ROM, all built-in function ROM, the
MMU, the PLA, the 8563 video processor, the SID and both CIA chips.
The processor bus is in communication with the Z80 coprocessor as well. All
address lines are shared directly by both processors. In order to allow the Z80 to operate
on a 6502 family bus, it is necessary to latch data going into the Z80 and gate the data
leaving the Z80. Thus, the Z80 has a small local data bus, designated ZD 0 -ZD 7 . During
a write cycle, when AEC is high, Z80 data is gated to the processor bus. During a read
cycle, processor bus data is gated to the Z80 data bus. This read data is transparently
latched by the 1 MHz system clock.
NOTE: Read and write cycles referred to in this document, unless
otherwise specified, are 8502-type bus cycles. The Z80 Read Enable and
Write Enable outputs are conditioned using logic to interface with an
8502 bus cycle, so no distinction is made as to the differences between
cycles of the different processors. For more information on this logic,
consult the section on the Z80 processor and the C128 Schematic,
Commodore Part No. 310378.
As mentioned above, the Z80 is not in direct communication with the processor
data bus, because of the need to adapt the Z80 to 8502 bus protocol. Note, however,
that every other device and every other bus (except two that will be explained later)
shares the processor data bus as a common data bus.

THE TRANSLATED ADDRESS BUS

Another C128 system bus is the Translated Address Bus produced by the MMU during
AEC high. This bus consists only of high-order addressing lines, designated TA 8 -TA 1 5 .
These lines reflect the action of the MMU on the normal high-order address lines, which
may or may not include some sort of translation. The MMU can translate the address of
page zero or page one in normal operation, and it translates the Z80 address from $0000
through $0FFF in order to direct it to read the Z80 BIOS. A more complete description
of MMU translations can be found in the MMU section of this document.
Normally, the translated address bus indirectly drives the system RAM and the VIC

C128 HARDWARE SPECIFICATIONS

chip by driving the multiplexed address buses. It directly drives system ROM 4 address
line 12 to allow the Z80 ROM relocation. Finally, this bus becomes address lines 8
through 15 of the C64 compatible expansion port.
During a VIC cycle or a DMA, the MMU pulls TA 1 2 -TA 1 5 high, while T A 8 - T A n
are tri-stated. This allows the VIC chip to drive T A 8 - T A n as VIC addresses V A 8 - V A n .
During an external DMA cycle, the TA lines of the MMU are tri-stated, and the TA
bus, presumably driven by the DMA source, in turn drives the processor address bus
from A 8 to A , 5 . Thus allows the DMA source to access any peripheral chip except the
M M U . The action of the VIC during a VIC cycle is described below.

THE MULTIPLEXED ADDRESS BUS

This section describes two related address buses, the Multiplexed Address Bus and the
VIC Multiplexed Address Bus, known respectively as M A 0 - M A 7 and V M A 0 - V M A 7 .
The VIC multiplexed address bus is created during AEC high by multiplexing the
high-order translated address bus (TA 8 -TA 1 5 ) with the low-order processor address bus
(A 0 -A 7 ), controlled via the MUX signal. This bus, driven by a hardware multiplexer
through series resistors, is called the Multiplexed Address Bus. The VIC multiplexed
address bus is used for processor access of the VIC chip registers. It is also used for VIC
access of system RAM.
During a VIC cycle (AEC low), the VIC chip address lines will be asserted. There
is no completely separate address bus for the VIC addresses, so it shares the V M A 0 - V M A 7
and address lines that are tri-stated during AEC high. Most of the VIC addresses come
out of the VIC chip already multiplexed, but two of them, VA 6 and VA 7 , do not supply
column information, as the VIC chip supplies only 14 bits of addressing. The higherorder address bits V A ] 4 and VA, 5 come from CIA-2, as in the C64. This means the VIC
supplies complete V M A 0 - V M A 7 for a VIC DRAM access or DRAM refresh. The
T A 8 - T A n supplied by VIC are used in conjunction with another addressing bus for
nonmultiplexed VIC cycle addresses, such as character ROM and color RAM accesses.

THE SHARED ADDRESS BUS

The Shared Address Bus is a nonmultiplexed address bus used by both the processor
and the VIC chip to communicate with common resources, namely the character R O M
and color RAM (and the 8563 system RAM indirectly). During AEC high, the shared
address bus, designated S a 0 - S A 7 , is driven by A 0 - A 7 , the lower-order processor
address bits. The higher-order bits needed are supplied by the translated address bus,
which is also a shared address bus. Thus, the processor is able to access both shared
items.
During AEC low, the VIC addresses V A 0 - V A 7 ( V M A 0 - V M A 7 ) must come onto
the shared address bus. Since V A 0 - V A 8 are actually multiplexed, the row address only
must be sent to the shared address bus. Thus, the multiplexed VIC addresses are
transparently gated when either /RAS or MUX are high, but latched and held afterward
so that when combined with the column address, the full address is presented. The highorder address bits here are supplied by the shared translated address bus. Note that the
shared address bus provides the lower 8 bits of the expansion port address, allowing VIC
access to cartridges and some additional drive capability by way of the TTL chips used to

561

554

COMMODORE 128

drive the shared address bus. During DMA, the SA lines, like the TA, are driven
backward to drive the processor bus. As noted above, this allows peripheral chips, ROM
and RAM to be accessed by a DMA source, like the RAM expansion module. Only the
MMU and the 8563 video controller cannot be accessed during DMA. See the auto-start
ROM section in Chapter 13 for more details on initializing both external and internal
expansion ROMS.

THE COLOR DATA BUS

The color RAM is written to or read from a nybble data bus called the Color Data Bus.
During AEC high, the color data bus is connected to the lower half of the processor data
bus via an analog switch, allowing the processor full access to the color RAM. During
AEC low, that switch is opened, effectively isolating the color data bus from the
processor data bus. In this state, it is driven by the VIC extended data bus D 8 - D n .
Since the color RAM is banked, only one-half appears here at a time.

THE DISPLAY BUS

The Display Bus is a bus local to the 8563 video controller, consisting of the Display
Address (DA 0 -DA 7 ) and the Display Data Bus (DD 0 -DD 7 ). This local bus supports
the 8563 display RAM, which is completely isolated from the rest of the C128 system.
The display address bus is a multiplexed address bus providing addressing to the display
DRAM. The display data bus provides communication between this DRAM and the
8563. The 8563 also provides row and column strobes and dynamic refresh to this
DRAM.

SYSTEM MEMORY
ORGANIZATION
This section describes the C128 memory system. Figure 16-2 is a detailed diagram of
the C128 Memory Map.

LU
CJ
^* cr
3=0_
CO
K\

LU

LU
U
^ cr
s:Q_
cn

3^ a.
=
01

=^fe

c
o
CD
CC
DC

c
o
CD
CE
DC

M
Ic
3
i
I

I
^J
I
c
i
ii
ii
3_

ffil

1C,

C
4 0C|C'
C
O o'
1

>

5c|

~U- ~X

L,

CD
CD
CD
OO
V*

Figure 16-2. CI28 Memory Map (C64 Mode)

CD

CD
L0
4A

CD
CD
CD
r?
<A

CD
CD
CD
OJ
4A

CD
CD
CD
^H
4A

CD
CD
=r
CD
4ft

ou
CD
CD
O
*ft

CD
CD
CD
CD
*

554

COMMODORE 128

CI28 ROM MEMORY ORGANIZATION

C128 mode is achieved at system reset and is controlled by a bit in the MMU
Configuration Register. In C128 mode, the MMU asserts itself in the C128 memory
map at $FF00 and in the I/O space, starting at $D500. Use of MMU registers located at
$FF00 allows memory management without actually having the I/O block banked in at
the time and with a minimum loss of contiguous RAM. The MMU is completely
removed from the memory map in C64 mode. It is, however, still used by the hardware
to manage memory.
Figure 16-2 presents the standard map forthe C64 mode. Some of the alternate modes
are shown in Figure 16-3. All C64 modes are compatible with the C64 computer, as the
C128 basically becomes a C64 when in C64 mode. The details of MMU register
location/operation are discussed in Chapter 13.
The ROMs in C64 mode look like Commodore 64 ROMs. The internal BASIC
and Kernal provide the C64 mode with the normal Commodore 64 operating system in
ROM. This ROM actually duplicates some of the ROM used in C128 mode, but it is
necessary, as it is not accessible from C128 mode. In C128 mode, up to 48K of the
operating system is present, with the exact amount being set by software control. This
allows quicker access to underlying RAM by turning off unneeded sections of the
operating system.
The external ROMs represented on the memory map are those used in C64 mode.
They obey the Commodore 64 rules for mapping; i.e., cartridges assert themselves in
hardware via the /EXROM and /GAME lines. External ROMs in C128 mode (i.e., C128
cartridges) are mapped as banked ROMs; when the system is initialized, all ROM slots
are polled for the existence of a ROM, and the ROM's priority, if one exists. This
allows much more flexibility than the hard-wired ROM substitution method, since the
Kernal and BASIC ROMs can be swapped for an application program, or for external
program control, or can be turned off altogether. This banking manipulation is accomplished by writing to the Configuration Register at location $D500 or $FF00 in the
MMU.
The hardware also features the ability to store preset values for the configuration
and force a load of the Configuration Register by writing to one of the LCRs (Load
Configuration Registers). This allows the programmer to imply that ROM does not
appear in the bank (by default) any time an access occurs to a bank where data is stored.

0 c3r
u_x:
T30oC 0)L
I II II II
r r
a:
cr
cc Lu
o
0C CC X cc
o cr x
_IXULU

ii ii ii ii
cc rcn uJ ro
cc cc x : oc
o_ J^X OcrU Jx

C3 0C
a*:
o=j3C CD

CO ^H

11 II
sz
s: r
cccrujo
cc
cc x:xcc
D^cr
_ixauj

\T

5 5

d d J

2:0x 0^

CD CC C

\, \

d J

T
J CJ)
C
W 0

a~o
0 c

x: 0

5: r 5:
aiccujQ
ccccs:oc
aH
H a: x
_iXL3LU
X, \ .

a:rcc ujr 0

CCQCXOC

oax
_l X CO UJ

d J J

Figure 16-3. C64 Alternate Memory Configurations

554

COMMODORE 128

CI28 RAM MEMORY ORGANIZATION

A s shown in Figure 1 6 - 2 , the R A M present in the system is actually composed of two
banks of 64K by 8 bytes of DRAM. The RAM is accessed by selecting one of the two 64K
banks, the maximum address range of the 8502 and Z80, according to the R A M banking
rules set in the R A M configuration register of the M M U . This area shown as R A M
represents what the processor would see if all ROM were disabled. Bank switching can
be accomplished in one of two ways.
The bank in use is a function of the value stored in the configuration register. A
store to this register will always take effect immediately. An indirect store to this
register, using programmed bank configuration values, can be accomplished by writing
to one of the indirect load registers known as LCRs, located in the $FF00 region of
memory. By writing to an LCR, the contents of its corresponding PCR (PreConfiguration
Register) will be latched into the configuration register. This allows the programmer to
set up four different preprogrammed configurations that allow each bank to be personalized ahead of time; e . g . , bank 1 as a data bank might be strictly a R A M bank with no
ROM or I/O enabled, while bank 0 as the system bank can have the system ROM and
I/O enabled by default. Additionally, reading any LCR will return the value of its
corresponding PCR.
When dealing with 64K banks of memory at once, it may be desirable to bank in
bank 1 but still retain the system R A M (stack, zero page, screen, etc.). The M M U has
provisions for what is referred to as c o m m o n RAM. This RAM does not bank and is
programmable in size and position (top, bottom, or both) in the memory map. The size
is set by bits 0 and 1 in the RAM Configuration Register (RCR). If the value of the
bits is 0, l K will be common. Values of 1, 2 and 3 produce common areas of 4K, 8K
and 16K respectively. If bit 2 of the RCR is set, bottom memory is held common; if bit
3 is set, then top memory is common. In all cases, common R A M is physically located
in bank 0.
Zero page and page one can be located (or relocated) independently of the
RCR. When the processor accesses an address that falls within zero page or page
one, the M M U adds to the high-order processor address the contents of the P0
register pair or the P1 register pair, respectively, and puts this new address on the
bus, including the extended addressing bit A16. R A M banking will occur as appropriate
to access the new address. Writes to the P0 and P1 registers will be stored in prelatch until a write to the respective low byte page pointer occurs. This prevents a P x H
high byte page pointer from affecting the translated address until both high and low
bytes have been written. Common memory overrides the page pointers.
At the same time, the contents of the P0 and P1 registers are applied to a digital
comparator, and a reverse substitution occurs if the address from the 8502 falls within
the page pointed to by the register. This results in a swapping of the zero page or page
one with the memory that it replaced. Swapping occurs only if the swapped area is
defined as RAM; i . e . , system or function ROM must always be at its assigned addresses
and thus should not be back-substituted but of course will not cause contention of any
kind. Note that upon system reset, the pointers are set to true zero page and true page
one.

C128 HARDWARE SPECIFICATIONS

NOTE: There are actually several memory modes that override parts of
the bank as selected here. These modes are mentioned below, and are
covered in detail in a later section.

For VIC-chip access, one bit in the MMU status register substitutes for extended
address line A ! 6 , selecting the proper CAS enable to make it possible to steer the VIC
to anywhere in the 128K range. Note that AEC is the mechanism the M M U uses to steer
a VIC space address; i.e., when AEC is low, a VIC access is assumed. This results in
the VIC bank being selected as well for an outside DMA, since this, too, will pull the
AEC line to the MMU low.

PERFORMANCE SPECIFICATIONS
POWER CONSUMPTION
Table 16-1 contains values for C128 power consumption, including various add-on
options.

I Typ I Max I Typ I Max I Typ I Max

(5v)
(9v)
(12v)
SUBTOTAL

61

2.63

3.83

0.03

0.05

1
1
1
1

0.24
0.07
0
0

0.35
0.10
0
0

0
0
0.07
0.28

0
0
0.10
0.40

0
0
0
0

0
0
0
0

A
A
A
A

0.31

0.45

0.35

0.50

2.94

4.28

0.38

0.55

PERIPHERALS

Magic Desk
RS-232
Auto Modem
Cassette
PERIPHERAL TOTAL
C128 AND PERIPHERALS

TOTAL POWER, WORST CASE (WATTS)

Voltage

Power

5V

12V

5.25

9.45

12.60

TOTAL

22.47

5.20

0.00

27.67

Table 1^-1. CI28 Power Consumption

BUS LOADING
Table 16-2 details AC and DC device loading for the C128 system. All capacitances
are in picofarads and currents are in microampheres.

567

554

COMMODORE 128

Dev:
Signal

DRAM ROM VIC 8563 4016 2332

LS MMU PLA 8502 Z80 4066 SID TOTAL

CIA LOADS
TTL

TA 8 -TA 15

1
1
10 2.5
8
8

#
I
C

1
10
4

2
1
10 800
8 30

...

...

...

...

...

...

...

...

...

...

1
10
4

1
1
10 400
8 15

...

...

...

...

...

...

...

...

...

...

...

...

420
27

...

...

...

...

...

1
400
15

1
2.5
8

1
3
0.1 7.5
8 24

488
129

2
800
30

1
1
2.5 2.5
8
8

1
2.5
8

1
2.5
8

1
1
2.5 2.5
8
8

833
58

SA0-SA7

#
I
C

---

---

D 0 -D 7

#
I
c

2
20

5
50
40

1
1
2.5 2.5
8
8

1
2.5
8

...
...

R/W

#
I
c

1
1
2.5 2.5
8
8

...

...

...

...

...

...

...

...

...

...

...

...

3
7.5
24

820
94

3
7.5
24

18
56

3
7.5
24

2008
99

RES

#
I
c

...

...

...

1
2.5
8

...

...

---

...

...

---

...

...

...

...

...

---

...

lMHz

#
I
c

5
2000
75

...

...

...

...

...

...

...

...

Table 16-2. Bus Loading Power Requirements (Capacitances and Currents)

ENVIRONMENTAL SPECIFICATIONS
The C128 is rated to operate at from 10 to 40 degrees Celsius (50 to 104 degrees
Fahrenheit) and at a noncondensing relative humidity of 5 to 95 percent.

C128 HARDWARE SPECIFICATIONS

THE 8502
MICROPROCESSOR
GENERAL DESCRIPTION
The 8502 is an HMOSII Technology microprocessor, similar to the 6510/6502. It is the
normal operating processor used in C64 and C128 modes. Software-compatible with
the 6510, hence the 6502, the 8502 also features a zero page port used in memory
management and cassette implementation.
The 8502 is also specified for operation at 2 MHz. The 2 MHz operation is made
possible by removing the VIC from the system as a display chip. (The VIC chip is never
completely removed from the C128 system, as it continues to function as clock
generator and refresh controller.) What this refers to is that the VIC is removed as a display
chip and co-processor; thus the full clock cycle can be devoted to processor functioning
instead of sharing the cycle with the VIC.
The task of the video display processor is taken over by the 8563, which can
function without the need for bus sharing. Since the I/O devices, SID, etc., are rated at
1 MHz only, stretching of the 2 MHz clock is used to allow these parts to be accessed
directly by the 2 MHz processor and still keep throughput to a maximum.
The I/O devices are not affected by the 2 MHz operation, as they are still driven
by a 1 MHz source (as such, all timer operations remain unchanged), and clock
stretching is used only to synchronize the 2 MHz machine cycle to the 1 MHz 4>0 high
time. The clock sources and clock-stretching capabilities are generated by the VIC chip.

ELECTRICAL SPECIFICATION
This section describes some of the electrical constraints and specifications of the system.

MAXIMUM RATINGS
Table 16-3 gives the absolute maximum ratings of the 8502 microprocessor.

RATING

SYMBOL

VALUE

Supply Voltage
Input Voltage
Storage Temperature
Operating Temperature

VV cc

^).5
^).5
-55
0

Vin
T s tg

T
*a

to
to
to
to

UNIT

+7.0
+7.0
+150
+70

Vdc
Vdc
C
C

Table 16-3. 8502 Absolute Maximum Ratings

ELECTRICAL CHARACTERISTICS
Table 16^4 gives the 8502's basic electrical specifications for minimum, typical and
worst-case operation, valid over the range of operation T.

569

554

COMMODORE 128

CHARACTERISTIC

SYMBOL

Input High Voltage

4>o (in)
/RES, P0-P7,/IRQ, Data

ViH

Input Low Voltage

$0 (in)
/RES, P0-P7,/IRQ, Data

VIL

Input Leakage Current

(Vin = 0 to 5.25V, Vee = 5.25V)
Logic
<fo> (in)

IlN

3-State (Off) Inp. Cur.

(Vin = 0.4 to 2.4V, VCC = 5.25V)
Data Lines

lTSI

Output High Voltage

(IoH = -100^Adc, VCC = 4.75V)
Data, Ao-A15, R/W, P 0 -P 7

VoH

MIN

Vss + 2.4
Vss + 2.2

TYP

MAX

UNIT

Vec

Vdc
Vdc

V ss + 0.5
Vss 4- 0.8

Vdc
Vdc

2.5
10.0

fxA
fjiA

10.0

pA

V ss ^).3

Vss + 2.4

Vdc

Output Low Voltage

(IoL = 1.6mAdc, Vcc = 4.75V)
Data, Ag-Ajs, R/W, P 0 -P 7
Power Supply Current
Capacitance
(Vin = 0, Ta = 25 C, f = l M H z )
Logic, Po-P7
Data
A0-A7
<ta

Vss
Icc

+ 0.4

Vdc

125

mA

30

10
15
12
50

pF
pF
pF
pF

c
r.
*^in
r^out
Cout

C^O

Table 16-4. 8502 Basic Electrical Specifications

SIGNAL DESCRIPTION
Below is a description of all the 8502 signals from a functional and electrical point of
view:
C L O C K (<&o)This is the dual speed system clock. Note that the input level required is
above worst-case TTL; thus, extra precautions must be taken when attempting to
drive this input from a standard TTL level input.
A D D R E S S BUS ( A 0 - A , 5 > - T T L output. Capable of driving 2 TTL loads at
130 pF.
D A T A BUS (Dcr-Dy)Bidirectional bus for transferring data to and from the device
and the peripherals. The outputs are tri-state buffers capable of driving 2 standard
TTL loads at 130 pF.

C128 HARDWARE SPECIFICATIONS

RESETThis input is used to reset or start the processor from a power down
condition. During the time that this line is held low, writing to or from the
processor is inhibited. When a positive edge is detected on the input, the
processor will immediately begin the reset sequence. After a system initialization
time of 6 cycles, the mask interrupt flag will be set and the processor will load the
program counter from the contents of memory locations $FFFC and $FFFD. This is
the start location for program control. After Vcc reaches 4.75 volts in a power up
routine, reset must be held low for at least 2 cycles. At this time the RAV line will
become valid.
I N T E R R U P T R E Q U E S T (IRQ)TTL input; requests that the processor initiate an
interrupt sequence. The processor will complete execution of the current instruction before recognizing the request. At that time, the interrupt mask in the Status
Code Register will be examined. If the interrupt mask is not set, the processor will
begin an interrupt sequence. The Program Counter and the Processor Status
Register will be stored on the stack and the interrupt disable flag is set so that no
other interrupts can occur. The processor will then load the program counter from
the memory locations $FFFE and $FFFF.
N O N - M A S K A B L E I N T E R R U P T R E Q U E S T ( N M I ) T T L input, negative edge
sensitive request that the processor initiate an interrupt sequence. The processor
will complete execution of the current instruction before recognizing the request.
The Program Counter and the Processor Status Register will be stored on the
stack. The processor will then load the program counter from the memory
locations $FFFA and $FFFB. Since NMI is non-maskable, care must be taken to
insure that the NMI request will not result in system fatality.
A D D R E S S E N A B L E C O N T R O L (AEC)The Address Bus is only valid when the
AEC line is high. When low, the address bus is in a high impedance state. This
allows DMA's for dual processor systems.
I / O P O R T (P<H*6)Bidirectional port used for transferring data to and from the
processor directly. The Data Register is located at location $0001 and the Data
Direction Register is located at location $0000.
R/WTTL level output from processor to control the direction of data transfer between
the processor and memory, peripherals, etc. This line is high for reading memory
and low for writing.
RDYReady. TTL level
normally while RDY
processor will finish
is a write cycle. On
making it possible to

input, used to DMA the 8502. The processor operates

is high. When RDY makes a transition to the low state, the
the operation it is on, and any subsequent operation if it
the next occurrence of read cycle the processor will halt,
gain complete access to the system bus.

PROCESSOR TIMING
This section explores the timing considerations of the 8502 processor unit. Table 16-5 is
a processor timing chart. Figure 16^4 presents timing diagrams that show both general
timing and the particular method of clock stretching used in 2 MHz mode.

571

554

COMMODORE 128

Electrical Characteristics Vcc = 5v 5%, Vss = Ov, T s = 0 C to 70 C

CHARACTERISTIC

AEC setup time

Up data setup from ^>o
Up write data hold
Data bus to tri-state from AEC
Read data stable
Read data hold
Address setup from ^o
Address hold
Address setup from AEC
Address tri-state from AEC
Port input setup
Port input half
Port output data valid
Cycle time
c^o (in) pulse width @1.5v (crystal clock)
cf>o (in) rise time
4>o (in) fall time
RDY setup time

SYMBOL
TAEC

MIN

MAX

UNITS

25

60
100

ns
ns
ns
ns
ns
ns
ns
ns
ns
ns
ns
ns
ns
ns
ns
ns
ns
ns

TMDS
Tnw

40
120

TAEDT
TDSU
THR
TADS
THA

40
40
40
40

60
120

TAADS
TAEAT
TpDSU
TpDH

105
65
195

TpDW
TcYC

P WH ^0
TR4>o
TF4>o
TRDY

75

489
235

80

265
10
10

Table \b-S. Processor Timing Chart

CLOCK STRETCHING
When running in 2 MHz mode, the processor clock sometimes must be stretched. This
is handled by the VIC chip, the processor and the PLA working together. When an I/O
operation is decoded during a 2 MHz cycle, the phase relationship between the 2 MHz
and 1 MHz clocks must be considered. If the 2 MHz access occurs during l M H z O l , the
access to a clocked I/O chip would be out of synchronization with the 1 MHz clock that
drives all I/O chips. Thus, during this phase relationship, /IOACC from the PLA signals
the VIC chip to extend the 2 MHz clock. Should the 2 MHz cycles take place during the
1 MHz 3>2 cycle, no special attention is necessary.

C128 HARDWARE SPECIFICATIONS

1 MHz
Clock

_^
^

2 MHz
Clock

I/O

flcc

Proc
C 1 ock

I/O

_T

~L

Hcc

Pr oc
C 1 ock

~L

573

PHI
I/O
Rc c e s

PHI 2
I/O
fl c c e s s

Figure 16-4. Clock Stretching in 2 MHz Mode

Note the speed implications of this. In 2 MHz mode, half the I/O access given will
occur at an effective speed of lMHz.
Figure 16-5 is a diagram of the 8502 microprocessor pin configuration.

554

COMMODORE 128

Figure 16-5. The 8502 Microprocessor Pin Configuration

For information on programming 8502 Machine Language, see Chapter 5, Machine
Language on the C128.

Z80 MICROPROCESSOR
HARDWARE SPECIFICATION
The Z80 microprocessor is used as a secondary processor in the C128 to run CP/M
based programs. Covered in this section is not only the operation of the Z80 as part of

C128 HARDWARE SPECIFICATIONS

the C128 system, but some important electrical and timing specifications of the Z80. For
more information on Z80 bus interfacing, consult the Zilog Z80 Data Book.

SYSTEM DESCRIPTION
The Z 8 0 A , a 4MHz version of Zilog's standard Z80 processor, is included as an
alternate processor in the C128 system. This allows the C128 to run the CPM 3 . 0
operating system at an effective speed of 2 MHz. The Z80 is interfaced to the 8502 bus
interface and can access all the devices that the Z80 can access. The bus interface for the
Z80 (the most complex part of the Z80 implementation) is described in this section,
along with Z80's operation as a coprocessor in the C128 system.
N O T E : See the Signal Description section later in this chapter for
definitions of the signals mentioned in the following paragraphs.

BUS INTERFACE
Because a Z80 bus cycle is much different than a 65xx family bus cycle, a certain
amount of interfacing is required for a Z80 to control a 65xx-type bus. Since the Z80
has built-in bus arbitration control lines, it is possible to isolate the Z80 by tri-stating its
address lines. Thus, both the Z80 and the 8502 share common address lines.
The interfacing of the data lines is more complex. Because of the shared nature of
the bus during Z80 mode, the Z80 must be isolated from the bus during A E C low. Thus,
a tri-statable buffer must drive the processor bus during Z80 data writes. The reverse
situation occurs during a Z80 readthe Z80 must not read things that are going on
during AEC low; it must latch the data that was present during AEC high. Thus, a
transparent latch drives the data input to the Z80. It is gated by the Z80 read-enable
output, and latched when the 1 MHz clock is low. It will be seen that the Z80 actually
runs during AEC low, but that the data bus interfaces with it only during A E C high.

CONTROL INTERFACE
The Z80 control read-enable interfacing must provide useful clock pulses to the Z80,
and must tailor the Z80 and write-enable signals for the 8502-type bus protocol. The
Z80 clock is provided by the VIC chip, and is basically a 4MHz clock that occurs only
during AEC low, as seen in Figure 16-6. This ensures that the Z80 is clocked only when
it is actively on the bus. One additional consideration in clocking the Z80 is that while
all of the 8502 levels and most of the Z80 levels are TTL-compatible, the Z80 clock
input expects levels very close to 5 volts. For that reason, the output from the VIC chip
is processed by the 9-volt supply; thus, the 9-volt circuit must be operational for the
Z80, and the system, to function. The most common power-up failure for the C128 is a
blown 9-volt fuse.

575

554

COMMODORE 128

S u s t e n

C iock
Z-8G
C 1 ock
Z

8 Li

flcl

d r

- m

<

/LiLi

: : > # < :

Z - 8 Q
D a 1. a

M S v )

" ' "

: ^ m m m < ^

Re a o
Da t e
L o t c h
Da

t a

4$fy>y*f> * '''Vj w^

Vn i i d

Figure 16-6. Z80 Bus Timing

PROCESSOR SWITCHING
It is important in normal operation for the Z80 and the 8502 to operate as coprocessors,
communicating with each other. Since only one processor may have the bus at any one
time, this is only serial coprocessing, not parallel coprocessing or multiprocessing. This
is important in several ways:
First, the C128 system must power-up with the Z80 as master processor. This is to
prevent the Z80 from accidentally accessing the bus when powering up. Thus, the Z80
is made master on power-up and can do anything it likes to the bus. Also, because the
Z80 can start-up certain C64 applications that would cause the 8502 to crash, the Z80 is
the logical choice as start-up processor. After some initializations, the Z80 starts-up the
8502 in either C128 or C64 mode, depending upon whether a cartridge is present, and
upon the type of cartridge, if one is present. The operating system also allows C64 mode
to be forced on power-up.
Second, processor switching allows the Z80 to access 8502 Kernal routines. For
standardized programs or for any I/O operation not supported in the Z80 BIOS, the Z80
can pass on the task of I/O to the 8502. Since the Z80 sees BIOS ROM where the 8502
sees its pages 0 through F, the Z80 can operate without fear of disrupting any 8502
pointers or the stack in RAM Bank 0. The Z80 ROM BIOS physically overlays that
critical section of RAM Bank 1.
The Z80 can receive a bus grant request from the MMU via /Z80EN, or from the
VIC chip via BA. Since the VIC control line is used for DMAs, the latter request is not
of immediate concern. The /Z80EN action, however, is important, since it is the
mechanism by which the two processors exchange control.

C128 HARDWARE SPECIFICATIONS

When the /Z80EN line goes high, it triggers a Z80 / B U S R Q . The Z80 then relinquishes the bus by pulling / B U S A C K low. This action drives the 8502 AEC high and
(providing VIC does not request a D M A ) also drives the 8502 R D Y line high, enabling
the 8502. To switch back, a low on the Z80 /BUSRQ will result in Z80 / B U S A C K
going high, tri-stating and halting the 8502.
See Appendix K on CP/M for interchip communication details.

SIGNAL DESCRIPTION
The list below defines each Z80 signal. The Z80 pin configuration is shown in Figure 16-7.
Address Bus ( A ^ A I 5 ) : 16-bit tri-stating address bus. Used for 16-bit I/O cycles. This
allows up to 256 input or 256 output ports. During refresh time, the lower 7 bits
contain a valid refresh address. (This signal is not used in the C128 system.)
D a t a Bus ( D o - D 7 ) : Input/output bus capable of tri-stating; used for 8-bit exchanges
with memory and I/O devices.
Machine Cycle O n e ( / M | ) : Output, active low. This signal indicates that the current
machine cycle is the operation code fetch of an instruction execution. During
execution of a two-byte opcode, /Mj is generated, as each byte is fetched. /MY also
occurs with an input/output request (/IORQ) to indicate an interrupt acknowledge
cycle. The Mi line is used to disable the I/O decoder during an interrupt acknowledge cycle (See Input/Output Request).
M e m o r y Request ( / M R E Q ) : Active low, tri-state output that indicates that the address
bus holds a valid address for a memory read or write operation.
I n p u t / O u t p u t Request ( / I N R Q ) : Active low, tri-state output. The /INRQ signal
indicates that the lower half of the address bus holds a valid address for an I/O
read or write operation. An /INRQ signal is also generated with a /Mi signal when
an interrupt is being acknowledged to indicate that an interrupt response vector
can be placed on the data bus. An interrupt can acknowledge during /Mj; I/O
operations never occur during /Mj.
M e m o r y Read (/RD): Active low, tri-state output. /RD indicates that the CPU wants
to read data from memory or from an I/O device. This signal is generally used to
gate-read data onto the data bus.
M e m o r y W r i t e (AYR): Active low tri-state output. /WR indicates that the data bus
holds valid data to be processed by memory or by an I/O device.
Refresh (/RFSH): Active low output used to indicate that the address bus holds a
refresh address in its lower 7 bits. Thus, the current /MREQ signal should be used
to do a refresh read to all dynamic memories not refreshed from an alternate source.
A7 is set to 0 and the upper 8 bits contain the I register at this time.
H a l t S t a t e ( / H A L T ) : Active low output, indicating that the Z80 has executed a halt
instruction and is awaiting some kind of interrupt before execution can continue.
While in the halt state, the Z80 continuously executes NOPs to continue refresh
activity.
W a i t ( / W A I T ) : Active low input, used to drive the Z80 into wait states. As long as this
signal is low, the Z80 executes wait states; thus, this signal can be used to access
slow memory and I/O devices.

577

554

COMMODORE 128

NOTE: While the Z80 is in either a wait state or a bus acknowledge

(/BUSAK) state, a dynamic memory refresh cannot be performed. See Bus
Acknowledge.
Interrupt Request (/INT): Active low input, driven by external devices. If the
interrupt flag IFF is enabled and the bus request (/BUSRQ) line is not active, the
processor honors the request interrupt at the end of the current instruction. When
the Z80 acknowledges an interrupt, it generates an interrupt acknowledge signal
(/INRQ during / M 0 at the beginning of the next instruction cyele. There are three
different modes of response to a given interrupt. See Bus Request.
Non-Maskable Interrupt (/NMI): Active low input. This interrupt is edge-triggered
and cannot be masked against. It is always recognized at the end of the current
instruction, forcing the Z80 to restart at location $0066. The program counter is
automatically saved in the stack to allow a return from the interrupt program. Note
that continuous cycles can delay an /NMI by preventing the end of the current
cycle, and that /BUSRQ will override /NMI.
Reset (/RESET): Active low input that forces the program counter to zero and
initializes the Z80, which will set interrupt mode 0, disable interrupts, and set
register I and R to 0. During /RESET, the address and data buses go tri-state and
all other signals go inactive.
Bus Request (/BUSRQ): Active low input that requests the CPU address, data and
tri-statable output control signals to go tri-state for sharing and DMA's. The lines
go tri-state upon termination of the current machine cycle.
Bus Acknowledge (/BUSAK): Active low output, used to indicate to any device
taking over the bus that the Z80 has gone into tri-state and the bus has been
granted.
Clock (^): Single phase system clock.

C128 HARDWARE SPECIFICATIONS

21

>

;/Ml

7
z_

O
n
u u

flQ

3Q |

pi

31 |

19

VMEMREQ

fi2

20

V I

fl 3

NRQ

'/RD
22

/ WR

;/RFSH

;/HflLT

33 |

fl4

_34^

n5

35 |

flS

36(

n7

37 <

R8

38

n9

39 (

R 1 0
;/NflI T

32 |

<

40

fl 1 1
fll2.

16

1 7

/ I N T

n i 3 .

;/NMI

R 14.
R 15.

:/RESET
|

25

/BUSRQ

DG.

14

23

/BUSflK

D1.

15

D2.

12

PHI

D3.

+ 5 V

D4.

GND

D 5.
D 6.

1G

D7.

13

Figure 16-7. Z80 Microprocessor Pin Configuration

ELECTRICAL SPECIFICATIONS
ABSOLUTE MAXIMUM RATINGS
Table 16-6 gives the absolute maximum temperature, voltage and power dissipation
ratings for the Z80. Permanent damage is likely to occur if these ratings are exceeded.

579

554

COMMODORE 128

PARAMETER

SYMBOL

RANGE

Operating Temperature
Storage Temperature
Input Voltage
Power Dissipation

Ta

c
0 tO +70
^ 5 to +150 c
Vdc
0.3 to 7.0
W
1.5

Tst
Vin
1p cc

UNITS

Table 16-6. Z80 Absolute Maximum Ratings

DC OPERATING CHARACTERISTICS
Table 16-7 shows the maximum DC operating ratings for the Z80. Except as noted,
these ratings apply over the full rated temperature and voltage ranges.

UNITS

PARAMETER

SYMBOL

RANGE

Power Supply Variance

Clock Input Low Voltage
Clock Input High Voltage
Input Low Voltage
Input High Voltage
Output Low Voltage
0oL = l-8mA)
Output High Voltage
(IoH = -250^A)
Power Supply Current
Input Leakage Current
=
(Vin 0 to V c c )
Tri-State Leakage Current

V
Y CC

VoL

Vdc
5 5%
Vdc
^).3 to 0.8
V cc ^).6 to Vcc + 0.3 Vdc
Vdc
^).3 to 0.8
Vdc
2.0 to Vcc
Vdc
Vss to 0.4

VoH

2.4 to Vcc

Vdc

ICC

mA

lLI

200
10

lLO

+10, -10

piA

lLD

10

fxA

V,LC
VlHC
VlL

V,H

^jiA

( V o U T VoH> V 0 U T V o L )

Data Bus Input Leakage Current

(VSS v i n Vcc)

Table 16-7. Z80 DC Operating Characteristics

CAPACITANCE
The line capacitance values for the Z80 are given in Table 16-8. All measurements are
at T - 25 degrees, F = 1 MHz.

PARAMETER

SYMBOL

MAXIMUM

UNIT

Clock Capacitance
Input Capacitance
Output Capacitance

C<fr
c^ m

35
5
10

pF
pF
pF

p
^out

Table l 6 ^ . Z80 Capacitance Values

C128 HARDWARE SPECIFICATIONS

THE PROGRAMMED
LOGIC ARRAY (PLA)
The 8721 C128 PLA is a programmed version of the Commodore 48 Pin Programmable
Logic Array (Commodore Part # 3 1 5 0 1 1 ) . It provides all the chip selects and other
decoded signals that are necessary for the C64, along with a number of such signals
new in the C128 system. Figure 16-8 shows the PLA chip.
The PLA does a number of things vital to the operation of the C128, including:

All ROM selects (Kernal, BASIC, function, external) in all operating modes.
VIC chip select.
Color R A M chip select.
Character RAM chip select.
Write enable to color RAM.
Latched write enable to DRAMs.
Z80 select decoding.
Z80 I/O decoding, for Z80 I/O cycle and Z80 memory mapping.
Data bus direction signal.
I/O group chip select (includes I / O - l , 1/0-2, CIA-1, CIA-2, SID, 8563).
I/O access signal indicating an I/O operation is occurring.
CAS ENaBle for D R A M enable.

CHIP SELECT GENERATION

This PLA device is responsible for defining the banking rules for ROM and R A M that
the system will follow. This chip generates chip selects for all ROM and the VIC chip.
It generates an enable for any other I/O device in the map, and can enable or disable
CAS based upon what else is enabled. In C128 mode, decisions are made using the
processor addresses and the four mode status lines: R O M B A N K L O , R O M B A N K H I ,
I/O SELECT, and C128/64. The C128 mode banking scheme is quite straightforward
and simple. In Z80 mode, the selection mechanism becomes even simpler, thanks to the
I/O cycle of the Z80 processor.
C64 chip selects account for the bulk of the PLA font. The C64 selects I/O, R A M
and ROM based upon internal control lines: B A , HIRAM, LORAM, and C H A R E N .
The status of these lines, and decoded addresses, determine for any given time which (if
any) chip is selected. When a cartridge is inserted, two additional control lines come
into play: /EXROM and /GAME. Various combinations of these lines cause different
memory maps to be asserted, all based upon the PLA font.

OTHER FUNCTIONS
The PLA performs a variety of functions other than chip selects. It creates the write
enable strobes for both D R A M and Color RAM. In C128 mode, the C64 control lines
(HIRAM, LORAM and CHAREN) are not needed, since the M M U controls the more
sophisticated C128 method of banking. Thus, these lines are used to extend the
functionality of the C128 at little or no additional cost in hardware. The C H A R E N line is

581

554

COMMODORE 128

used in C128 mode to turn the Character ROM on and off in the VIC bank selected; in
C128 mode the ROM can appear or disappear in any VIC bank.
The second of the new functions uses LORAM and HIRAM to select one of two
Color RAM banks. The level of LORAM selects the bank that will be seen during
processor time; the level of HIRAM selects the bank that will be seen during VIC time.
Thus, a program can swap between two full-color pictures very cleanly, or the processor
can modify one full-color picture while displaying another.

VCC
/R0M4
/R0M3
/R0M2
/R0M1

fll5
R14
R13
R12
Rl 1
R10
BR
CLK

P^
3^
C^
c^

^v33
/FROM L
o

PLfl

R/W
MR4
MR5
/VR14
REC

/ R O M H py>
/ROML 0 ^

/CHRROM r ^
/COLRRM

R0MBRNKL0

/V

ROMBRNKHI

:c o >

/IORCC

/IOSE

b^

bs

/IOCS c^

C 1 28/64

/SDEN
p^
D I R 39

H/GRME
^j/EXROM

/'DNE p ^
/GWE

128/256

&*

LORRM
/CR5ENB

HIRRM
CHRREN
/DMRRCK

CLRBNK

/Z80_EN
/Z8Q_I0
GND

"55]

Figure l 6 ^ . The CI28 PLA Chip

C128 HARDWARE SPECIFICATIONS

THE MEMORY
MANAGEMENT UNIT (MMU)
The M M U is d e s i g n e d t o allow complex control of the C128 system memory resources.
Because of the way it handles all the standard C64 modes of operation, it is completely
compatible with the C64. Additionally, it controls the management of particular C128
modes including the Z80 mode. The M M U ' s features include:

Generation
Generation
Generation
Generation

of
of
of
of

translated address bus ( T A 8 - T A 1 5 ) .

control signals for different processor modes (C128, C64, Z80).
CAS selects lines for R A M banking.
R O M B A N K lines for ROM banking.

Programming the M M U is described in detail in Chapter 13.

PHYSICAL DESCRIPTION
Many of the M M U input and output signals have been discussed informally so far.
This section contains descriptions of the M M U as a physial 48-pin device, including a description of all pin requirements, input and output signals, and electrical
requirements.

PIN REQUIREMENTS
Table 1 6 - 9 lists the required M M U pins, indicating the number in each signal category
and the total number.

583

554

COMMODORE 128

SIGNAL NAMES
A 0 - A 3 ,
A4/5,

A * r A

1 5

A5y'7

D 0 -D 7
T A 8 - T A

1 5

V cc

GND
P H I o

RESET
R/W
/ C A S o - / C A S j

AEC
/Z80EN
/GAME
/EXROM
M S o - M S j

I/O (MS2)
C128/64 (MS3)
40/80
/FSDIR
MUX

DESCRIPTION

NUMBER OF PINS

Address Lines In
Combined Address Lines In
Data Lines In/Out
Translated Addr. Lines Out
+ 5V
Ground
2 MHz 4>0 Clock In
System Reset In
Read/Write Line In
DRAM CAS, 64K Bank Out
Address Enable Control In
Z80 Enable Out
Game ROM Enable In, Control Out
External ROM Enable In, Control Out
Memory Status Out
I/O Select Out
C128 or C64 Mode Out
40/80 Status In
Fast Serial Direction Out
Memory Multiplex In

12
2
8
8
1
1
1
1
1

TOTAL

48

1
1
1
1
1
1
1
1
1

Table 16-9. MMU Pln Requirements

PIN DESCRIPTION
The following comprises a signal-by-signal description of the MMU input and output
signals. Figure 169 shows the MMU pin configuration. Included here are any available
bond options.
The MMU input signals are:

A 0 - A 3 , A 8 -A 1 5 : Addresses from the microprocessor. Used to derive chip

selects as well as multiplexed address lines. A 0 - A 3 are found at pins 18-21 on
the MMU, while A 8 - A 1 5 are located at pins 24-31.
A 4 / 5 , A 6/7 : Combined addresses from the microprocessors. Used along with
simple addresses, combined in this fashion to lower the pin count of the
MMU. Located at pins 22 and 23 respectively.
PHI0: Presystem clock. Used for early transition of gated signals on write
operations. Processor address is valid on the rising edge, and data is valid on
the falling edge. This is found at pin 33.
R/W: System Read/Write control line. This input is high for a processor read,
low for a processor write. This signal is located at pin 32 on the MMU chip.
RESET: System Reset. This input initializes internal registers on a power-up
or hardware reset. It can be found at pin 2.
AEC: Address Enable Control. Indicates whether the 8502 processor or the
VIC has access to the shared bus. When low, VIC or an external DMA has the

C128 HARDWARE SPECIFICATIONS

bus and V A 1 6 have the processor bus, and no pointer or BIOS translation takes
place. This signal occupies pin 16.
M U X : The memory multiplex signal, used to clock various sections of the
M M U . It is located at pin 17.
V d d : System + 5 Vdc supply, connected at pin 1.
V s s : System Ground, connected at pin 34.

The following represents the M M U bidirectional lines. Some of the port bits
detailed here are left for future expansion in a one-directional sense.

D 0 ~ D 7 : Data inputs from microprocessor. Used for writing to internal registers. Located at pins 35 to 42.
/EXROM: This signal is used to sense the /EXROM line on the expansion
connector in C64 mode and as an expansion control line in C128 mode.
Located at pin 46. This line will drive one TTL load on output, and has a
passive depletion mode pull-up on input. This signal can be pulled down, but
not up, by an external driver.
/GAME: This signal is used to sense the / G A M E line on the expansion
connector in C64 mode and as the color R A M bank control line in C128 mode.
Located at pin 45. This line will drive one TTL load on output, and has a
passive depletion mode pull-up on input. External hardware can pull this line
down, but not up.
40/80: This port in input mode senses the 40/80 column switch. It detects
whether or not this switch is closed. Its output function is open for expansion.
Located at pin 48. This line will drive one TTL load on output, and has a
passive depletion mode pull-up on input. External hardware can pull this line
down, but not up.
FSDIR: This port in output mode is used to control the data direction of the fast
serial disk interface. It is a general-purpose port signal, and is connected at pin
44. This line will drive one TTL load on output, and has a passive depletion
mode pull-up on input. External hardware can pull this line down, but not up.

The following list represents the M M U output signals, their physical locations on
the M M U and their logical levels if applicable.

T A 8 - T A 1 5 : Translated address outputs. Tri-stated for VIC cycles during AEC,

they provide translated physical addresses for use on the Multiplexed Address
Bus and the Shared Static Bus. T A 1 2 to T A 1 5 are each defined to have an
internal, depletion mode pull-up with an equivalent resistance of 3 . 3 K O . T A 8
to T A n each go tri-state during VIC time (AEC low). These are located on the
M M U at pins 10 to 3.
M S o - M S j : Also called ROMBANKO and R O M B A N K l , these outputs control
ROM banking for all ROM slots. They are located on pins 15 and 14. These
lines are used to decode ROM bank selection for any ROM access in C128
mode. If they are both low, a system ROM has been selected. If M S ] alone is

585

554

COMMODORE 128

high, then a built-in function ROM has been selected. If MS 0 alone is high,
then an external function ROM has been selected. Finally, ifboth are high, the
RAM that occupies the particular slot has been selected. In C64 mode, the
PLA completely ignores these lines.
I/O: This output is used to select memory mapped I/O in C128 mode. It is on
pin 13, and is also known as MS 2 . In C128 mode, this line always reflects the
polarity of the I/O bit. It is ignored by the PLA in C64 mode, and remains
high throughout C64 mode.
C128: This output directs the system to act in either C128 or C64 mode. It is
located on pin 47, and is also known at MS3. It goes low to indicate C64
mode, high for C128 mode.
/Z80EN: This output is used to enable the Z80 processor and disable the
normal operation of the 8502 processor. It can be found at pin 43. It goes low
to indicate Z80 mode, high for all other modes.
/CASo-CASj: CAS enables to control RAM banking. CAS 0 enables the first
bank of 64K; CASi enables the second bank of 64K. These are pins 12 and
11, respectively.

ABSOLUTE MAXIMUM RATINGS

ITEM

SYMBOL

RANGE

UNITS

Irtput Voltage
Supply Voltage
Operating Temperature
Storage Temperature

Vin
vT cc

-2.0 tO +7.0
-2.0 to +7.0
0 to 70
-55 to 150

Vdc
Vdc
C
C

Ta
Tst

Table 16-10. Absolute Maximum Ratings for the MMU

MAXIMUM OPERATING CONDITIONS

ITEM

SYMBOL

V' cc
Voltage Variance
Input Leakage Current
Ii
Input High Voltage
V,H
Input Low Voltage
V,L
Output High Voltage
VoH
(Ion = -200^A. Vcc = 5V 5%)
Output Low Voltage
VoL
(IoL = -3.2mA, Vcc = 5V S%)
Maximum Input Current
Icc

RANGE

UNITS

5.0 5%
-1.0
Vss + 2.4 to V cc + 1.0
V ss -2.0 to Vss + 0.8
Vss + 2.4

Vdc
fxA
Vdc
Vdc
Vdc

Vss + 0.4

Vdc

250

mA

Table 16-11. Maximum Operating Conditions for the MMU

C128 HARDWARE SPECIFICATIONS

VDD
31 fll5
30 R 1 4
29

fll3

28

R 12

27

Rl 1

26

fllG

MUX
R/N
REC

/Z80EN

43

25 R 9

^24 R 8

TR15
TR 1 4

23

fl6/7

TR13

22

fl4/5

TR12

21

R3

20

R2

TR9

19

R1

TR8

TR 1 1
TR10

1 8R G

42 D 7
41

D6

40

D5

39

D4

I/O

38

D3

ROMBRNKHI
ROMBRNKLO

37

D2

36

D1

35

DG

C 1 28

/CRSG
/CRS1

33

PHI__0

46

/EXROM

45

/GRME

RESET

i 48
4Q/8G

ESDIRfe
V5S
34]

Figure 16-9. The Memory Management Unit Pin Configuration

587

554

COMMODORE 128

THE 8564
VIDEO INTERFACE CHIP
The 8564 VIC chip used in the C128 is an updated version of the VIC chip used in
current C64 systems. It contains all the video capabilities of the earlier 6567 VIC chip,
including high-resolution bit-mapped graphics and movable image blocks. It also supports new features used by the C128 system, including extended keyboard scanning. Its
register map is upwardly compatible with the old VIC, allowing compatibility in C64
mode. It is powered by a single, 5V DC source instead of the two sources required by
the old VIC chip. The 8564 pin configuration is shown in Figure 16-10.

GENERAL DESCRIPTION
The 8564 VIC chip is similar to the 6567 VIC chip, yet it supports many new
features unique to the C128 system requirements. It will run on a single 5V DC supply,
and is packaged in a 48-pin dual-in-line package.

8564 VIC OPERATIONS

The 8564 VIC supports all the operations of the previous VIC chip. These functions,
quickly summarized, are:

Standard color character display mode.

Multicolor character display mode.
Extended color character display mode.
Standard bit map mode.
Multicolor bit map mode.
Movable image blocks.
Movable image block magnification.
Movable image block priority
Movable image block collision detection
Screen blanking
Row/column display select
Smooth scrolling
Light pen
Raster compare interrupt

As these functions exist in the previous VIC, their description is purposely kept to
a minimum here, while the VIC programming information is contained in Chapter 8. The
new functions, however, are described in detail below.

EXTENDED KEYBOARD SCANNING

The 8564 contains a register called the Keyboard Control Register. This register
allows scanning of three additional keyboard control lines on the C128 keyboard. Thus,
the C128 keyboard can have advanced additional keys in C128 mode while still

C128 HARDWARE SPECIFICATIONS

retaining C64 keyboard compatibility in C64 mode. In this register (register 53295
($D02F)), bits 0-2 are directly reflected in output lines K 0 to K 2 , while bits 3 - 7 are
unused, returning high when read.

2 MHz OPERATION
The VIC chip contains a register that allows the C128 system to operate at 2 MHz
instead of the standard 1 MHz speed of the C64. This operating speed, however,
disallows the use of the VIC chip as a display processor. This is bit 0 in 53296 ($D030),
and setting this bit enables 2 MHz mode. During 2 MHz operations, the VIC is disabled
as a video processor. The processor spends the full time cycle on the bus, while VIC is
responsible only for dynamic R A M refresh. Clearing this bit will bring back 1 MHz
operation and allow the use of the VIC as a video display chip. During refresh and I/O
access, the system clock is forced to 1 MHz regardless of the setting of this bit.
The 2MHz speed is available in C64 mode by setting bit 0 of location 5 3 2 9 6
($D030). Prior to this, blank the screen by clearing bit 4 of location 53265 ($D011).
You can then process at 2MHz (to perform number crunching, for example); however,
you will have no visible VIC screen. To return, set bit 4 of 53265 ($D011) and clear bit
0 of 5 3 2 9 6 ($D030).
Bit 1 of this register contains a chip-testing facility. For normal operation, this bit
must be clear. None of the other bits in this register is connected.

SYSTEM CLOCK CONTROL

The new VIC chip generates several clocks used by the C128 system. The main clock is
the 1 MHz clock, which operates at approximately 1 MHz at all times. Most bus
operations and all I/O operations take place in reference to this clock. The next clock to
consider is the 2 MHz clock. This clock clocks selected system components, such as the
processor, at 2 MHz when in 2 MHz mode. The VIC chip monitors the /IOACC input,
which indicates the access of an I/O chip, and when asserted, will stretch the 2 MHz
clock to synchronize all 2 MHz parts with the 1 MHz I/O parts. Finally, the last clock is
the Z80 clock, which is a 4 MHz clock that takes place only during the low half of the 1
MHz clock. Since all timed I/O parts look only at the 1 MHz clock, all I/O timings
remain the same no matter what the 2 MHz clock is doing.

SIGNAL DESCRIPTION
The VIC chip is mounted in a 48-pin dual-in-line package. The following lists describe
the electrical signals that it generates.
The signals used in the system interface are:

D 0 - D 7 : These are the bidirectional data bus signals. They are for communication between the VIC and the processor, and can be accessed only during A E C
high. They occupy pins 7 through 1 and 47, respectively.
D g - D i i : These are the extended data bus signals. They are used for VIC
communication with the color R A M . They occupy pins 47 to 43 in order.
/CS: Chip select, used by the processor to select the VIC chip. Found at pin 13.
R/W: Standard 8502 bus read/write for interface between the processor and
the various VIC registers. Pin 14.

589

554

COMMODORE 128

A 0 - A 6 : Multiplexed address lines, pins 32 through 38. During row address

time, A 0 - A 8 are driven on A 0 - A 5 . During column address time, A 8 - A 1 3 are
driven on A 0 - A 5 and A 6 is held at 1. During a processor read or write, A 0 - A 5
serve as address inputs that latch on the low edge or /RAS.
A - A 1 0 : Static address lines, pins 39 through 42. These address lines are used
for non-multiplexed VIC memory accesses, such as to character ROM and
color RAM.
lMHz: The 1 MHz system clock, pin 18. All system bus activity is referenced
to this clock.
2MHz: This is the changing system clock, which will be either 1 MHz or 2
MHz. If the 2 MHz bit is clear, no VIC or external DMA is taking place, and
no I/O operation is occurring, the clock will be 2 MHz; otherwise it will be 1
MHz. Found at pin 23.
Z80 Phi: The special 4 MHz Z80 clock, pin 25.
/IOACC: From PLA, indicating an I/O chip access for clock stretching. Pin 22
of the VIC.
/RAS: Row address strobe for DRAMs, pin 19.
/CAS: Column address strobe for DRAMs, pin 20.
MUX: Address multiplexing control for DRAMs, pin 21.
/IRQ: Interrupt output, used to signal one of the various internal interrupt
sources has taken place. Requires a pull-up, found at pin 8 on the chip.
AEC: Address Enable Control, high for processor enable on the shared bus,
low for VIC cycle and VIC or external DMA. Found at pin 12 of the VIC.
BA: Bus Available signal, used to DMA processor. Pin 10.
K 0 - K 2 : Extended keyboard strobe bits, pins 26 to 28.
LP: Edge triggered latch for light pen input. Pin 9 of the VIC chip.

The signals comprised in the video interface, i.e., all the signals required to create
a color video image, are:

PH IN: The fundamental shift rate clock, also called the dot clock. Used as the
reference for all system clocks. Located at pin 30.
PH CL: The color clock, used to derive the chroma signal. Pin 29.
SYNC: Output containing composite sync information, video data and luminance information. Requires a pull-up, pin 17.
COLOR: Output containing all color-based video information. Open source
output, should be tied through a resistor to ground. Found at pin 16.

ELECTRICAL SPECIFICATION
Tables 16-12 and 16-13 specify the electrical operation of the VIC chip in its new form.
These specs include absolute maximum ratings and maximum operating conditions.

C128 HARDWARE SPECIFICATIONS

ITEM

SYMBOL

RANGE

UNIT

Input Voltage
Supply Voltage
Operating Temperature
Storage Temperature

Vin
Vcc
Ta

^).5 t0 +7.0
^).5 to +7.0
0 to 75
^65 to 150

Vdc
Vdc
C
C

Tst

Table 16-12. Absolute Maximum Ratings for VIC Chip

Below is a list of the maximum operating specifications for the new VIC chip:

ITEM

SYMBOL

RANGE

UNIT

Power Supply Variance

Input Leakage Current
Input High Voltage
Input Low Voltage
Output High Voltage
(IoH = -200fxA, Vcc = 5.0 5% Vdc)
Output Low Voltage
(IoL = -3.2mA, Vcc = 5.0 5% Vdc)
Max Power Supply Current

vT cc
ii
V,H
V,L
VoH

5.0 5%
-1.0
Vss + 2.0 to Vcc
V ss ^).5 to Vss + 0.8
Vss + 2.4

Vdc
pA
Vdc
Vdc
Vdc

VoL

Vss + 0.4

Vdc

Icc

200

mA

Table 16-13. Maximum Operating Specifications for VIC Chip

RASTER REGISTER
The Raster Register is a dual function register. A read of the raster register 53266 ($D012)
returns the lower 8 bits of the current raster position [the MSB-RC8 is located in register
53265 ($D011)]. A write to the raster bits (including RC8) is latched for use in an internal
raster compare. When the current raster matches the written value, the raster interrupt
latch is set. The raster register should be interrogated to prevent display flicker by
delaying display changes to occur outside the visible area. The visible area of the
display is from raster 51 to raster 251 ($033-$0FB).

INTERRUPT REGISTER
The Interrupt Register indicates the status of the four sources of interrupts. An interrupt
latch in register 53273 ($D019) is set to 1 when an interrupt source has generated an
interrupt request.

591

554

COMMODORE 128

LATCH
BIT

ENABLE
BIT

IRST
IMDC
IMMC
ILP
IRQ

ERST
EMDC
EMMC
ELP

WHEN SET

Actual raster count = stored raster count (bit 0)

MOB-DATA collision (first bit only) (bit 1)
MOB-MOB collision (first bit only) (bit 2)
First negative transition of LP per frame (bit 3)
When IRQ/ output low (bit 7)

Table 16-14. Interrupt Register Definitions

To enable an interrupt request to set the IRQ/ output to 0, the corresponding interrupt
enable bit in register 53274 ($D01A) must be set to "1". Once an interrupt latch has
been set, the latch may be cleared only by writing a " 1 " to the associated bit in the
interrupt register. This feature allows selective handling of video interrupts without
software storing the active interrupts.

SCREEN BLANKING
The display screen can be blanked by clearing the BLNK bit (bit 4) in register 53265
($D011) to zero (0). When the screen is blanked, the entire screen displays the exterior
color specified by register 53280 ($D020). When blanking is enabled, only transparent
(phase 1) memory accesses are required, permitting full processor utilization of the
system bus. However, sprite data will be accessed if the sprites are not also disabled.

DISPLAY ROW/COLUMN SELECT

The normal display screen consists of 25 rows of 40 character regions per row. For
special display purposes, the display window is reduced to 24 rows of 38 characters.
There is no change in the format of the display information, except that characters (bits)
adjacent to the exterior border area are covered by the border.

C128 HARDWARE SPECIFICATIONS

RSEL

NUMBER OF ROWS

CSEL

NUMBER OF COLUMNS

0
1

24 rows
25 rows

0
1

38 columns
40 columns

The R S E L bit (bit 3) is in register 53265 ($D011), and the C S E L bit (bit 3) is in
register 5 3 2 7 0 ($D016). For standard display, the larger display window is normally
used, while the smaller display window is normally used in conjunction with scrolling.

SCROLLING
The display data may be scrolled up to one character in both the horizontal and vertical
directions. When used in conjunction with the smaller display window (above), scrolling
can be used to create a smooth panning motion of display data while updating the
system memory only when a new character row (or column) is required. Scrolling is
also used for centering a display within the border. An example of horizontal smooth
scrolling is found in Chapter 8.

BITS

REGISTER

FUNCTION

0-2
0-2

53270 ($D016)
53265 ($D011)

Horizontal Position
Vertical Position

LIGHT PEN
The light pen input latches the current screen position into a pair of registers (LPX,
LPY) on a low-going edge. Since the X position is defined by a 9-bit counter (53267
($D013)), resolution to 2 horizontal dots is provided. Similarly, the Y position is latched
in register 53268 ($D014) with 8 bits providing unique raster resolution within the
visible display. The light pen latch may be triggered only once per frame, and subsequent triggers within the same frame will have no effect.
For more information on programming the VIC (8564) chip, see Chapter 8, The
Power Behind Commodore 128 Graphics.

593

554

COMMODORE 128

48

TUU
7

6
5

P H _ I N 30.
PH__CL 29>

D0
D1
D2

4
o
D3

K0 2 6 ,
K1 2 7 o

3 D4

^2 D5

K2 2 8

1 D6
^47 D7

LP

^46 D8

25
Z80_PH
o
18
1 MHZ e>

D9
44
o DIG
43

D11
1

^3H
0 32

Rll

^ ^

R0

L O

033

fll
0 34
fl2
5
o3
fl3

^
U^J

r y

2MHZ ^ o
/ I O f l C C 2_2^
19
/RflS
o
/ C R S
20 o

MUX 21
R / N U^

o 3 6 RL[

/ C S 13

J37 R5

/IRQ

<3_QAS
^39 R7

BR i ^ o
REC L2^

0 R8
^ 1 R9
J 2 R10

U^
15

^_6
,17

COLOR
STNC
VSS
24
4>

Figure 16-10. The 8564 V I C Chip

C128 HARDWARE SPECIFICATIONS

THE 8563
VIDEO CONTROLLER
The 8563 is a HMOSII technology custom 80-column, color video display controller.
The 8563 supplies all necessary signals to interface directly to 16K of DRAM, including
refresh, and generated RGBI for use with an external RGBI monitor. For more information on the 8563 video controller, see Chapter 10, Programming the 80-Column (8563) Chip.

GENERAL DESCRIPTION
The 8563 is a text display chip designed to implement an 80-column display system with
a minimum of parts and cost. The chip contains the high-speed pixel frequency logic
necessary for 80-column RGBI video. It can drive loads directly, though some buffering
is desirable in most real-world applications. The chip can address up to 64K of DRAM
for character font, character pointer, and attribute information. The chip provides RAS,
CAS, write enable, address, data and refresh for its subordinate DRAMs. A programmable bit selects either two 4416 DRAMs (16K total) or eight 4164 DRAMs (64K total)
for the display RAM. The C128 system uses the 4416 DRAMs.

EXTERNAL REGISTERS
The 8563, which sits at $D600 in the C128, appears to the user as a device consisting of
only two registers. These two registers are indirect registers that must be programmed to
access the internal set of thirty-seven programming registers. The first register, located
at $D600, is called the Address Register. Bit 7 of $D600 is the Update Ready Status Bit.
When written to, the five least significant bits convey the address of an internal register
to access in some way. On a read of this register, a status byte is returned. Bit 7 of this
register is low while display memory is being updated, and goes high when ready for the
next operation. The sixth bit will return low for an invalid light pen register condition and
high for a valid light pen address. The final register indicates with a low that the scan is
not in vertical blanking, and with a high that it is in vertical blanking.
The other register is the Data Register. It can be read from and written to. Its
purpose is to write data to the internal register selected by the address register. All
internal registers can be read from and written to through this register, though not all of
them are a full 8 bits wide.

INTERNAL REGISTERS
There are thirty-seven internal registers in the 8563, used for a variety of operations.
They fall into two basic groups: setup registers and display registers. Setup registers are
used to define internal counts for proper video display. By varying these registers, the
user can configure the 8563 for NTSC, PAL or other video standards.
The display registers are used to define and manipulate characters on the screen.
Once a character set has been downloaded to this chip, it is possible to display
80-column text in 4-bit digital color. There are also block movement commands that
remove the time overhead needed to load large amounts of data to the chip through the
two levels of indirection. Figure 16-11 is a display of the 8563 internal register map.

595

554

COMMODORE 128

Bit 6
BTt 5 V B i t~ 4 7 BTT"3 r B i t 2 r B1 t 1 ~ 1 B i t Q ~
Bit 7
RQQ
Hop i zon ta I To ta 1
HopizontoI Displayed
RQt
Horizontal
Sync Position
RQ2
Horizontal Sync Hid th
_RQ3_
Ve r t i c a 1 S ync W i d t h
Vep t i ca 1 To ta 1
_RJW
,
,
v\n\^\^v;v\\'iviviviviv\v\vm\'\\'\v\viv\\'\mmv\\
\\'\v\v\vi\
\nYn'
r
Vertical Total Rdjust
RQ5 l.llJUUl.lLlLllJlJJJJ.tj\jJJJJJiJtJlJlJiJLILUJUlJIJlJLIlJLll.UJtJUUl.
Vep t1ca 1 Disp1ayed
_R06_
11 , ca 1 5ync
Ver
_R07_
, , Pos
, 1 11, on T , 1 , r
\,'\.'\A
\V\/y>.V//.\^//.\V
\V
V/\y-\n
U
\ \V\)\TO|
TTTTrTaTp
Modeu "
^wwwwwmvmvmr^V
RQ8 v\v\v\v\\'\viv\v\v\vw\viv\vivivi\'\v\vu'\v\\'i\'ir
/y.V//.^i/ryw
. /^
y.\'\'//.
/y\V
. \/V
y./U
y.k
/\V/y\V
./y.\v/yn./\A
.T
//.//.OV
TT^TTg
/.A
/V
^
AV
/iW
/^/A
/,/A
/!/^/AA/Af^/A/A/i/A/A/!/^/./!'UUUUUUUUUidUL
v/y.fyiy./y./y./y./y././y./y.f/./.(A//.l
V
\
\
V
\
\
W
V
\
M
\
m
i
w
i
W
Character
Total Vertical
RQ9 V
lJlJJJJJJJUUUJJJJJJJJJJJJJJJJJJUUJJJJUJJl
lJUlJUUUUUUUUl,
V\Y\Y\Y\Y\Y\Y\Y\Y\Y\Y\Yr
Mndp'
Cursor S t arT Scan TT7Te
lir9nr
R 1 uiMUuuuLiuum
0
T^TT..9T......?.."..
W\WVl\W^
^ ^
E nd 3 c an "TTne"
Rll W
i.ii./i.ii.ii.ii.ii.ii.ii.iJ.iJJj.tJ.iJ,ii.iJ.iiJj.iiJi.u.ii.uM.n.ii.ii.iiJi.ii.n.n.iJ.iJ.iJ.ii,
D i s p1 euJ 5 t Qrt R d d res s ( n i g h )
R1 2
DTspTay TTarT Rddress (L o w)
R1 3
Cu r s o r P o s 1 t i o n ( H i g h)
nm
CTr s or Pos i t i o n ( L o w)
R15
CTgTiT^Fen^ V e r tTTaT
R15
CTgKT P
R17
^__^__^_
^ _e^n^ F
_To
_ rTTon
^ _ ^tal

R18
CTpTaTe To c a t i o n TCTwl
R 1 ~9
H 11r i buTe^rrTrTTTcTdp^ess rFTTgTl
_R20_
FTTTT1 bu te S tar t Rddress CCowJ
R2_L_
D^"rac te"r TTTa 1-Ho r iz oTaT"
n
|
C haTaTTer D i sp 1 ayTTcPTToTT z orTta 1
R22
Y
l
m
V
W
W
W
'
t
W
'
t
W
W
W
|
v
w
w
w
x
v
w
w
m
v
m
r
ivmmwpww
~"
C h a r a c t e r D i s p'l a y e d - V e r t i c a 1
R23 tMLUJUUi.IUUl.IJ.il,
UUUUUUUULIUI.il,
lUUUUUUUUUUUl,
VerTTTaT SnToTh Scro 1 1
e n Rate
_R24_ Copy /F i11 R e <j 5 c r eBlink
Se nigr a p h PTx TOT [
HTTTTo7TTal 5TToTh 5TToTI
ex t
R25 G r a p h / T"TTrT"Fnb
F^TTgrTund Co 1 o r
|
Back ground Co 1 or
R26
Rddress increnent per Row
R2 7
Ti
T
Ri
L
/
L
i
ii
1
R
mvmv\
n
v\
n
vmv\
v
\v\nnv\
Cnaracter , Set Hadress
R28
././A/\yv.\/A
y,rY\
/./,/Y
.^\v^Jy.
/A/n
y.nnv^
/vy./y./l/./././y./y./y,/A^//,/.fy.f/.ry,^f/,/y.fy,/y,rA/j^y,/y,/yjy^
^v^^^^A^^vv\v\v\v\wv\vvv\^vv\^^^
\^v^^^
\T
\' ^
\'^,vK^AVv\v\^v^vv\v\v\^r^vv\ 4 i D 4 / 4 4 i D ^,/y,/,/y./y^y./y.^Under
1 ine Scan L ine
R29 vl.ll.lUl.lUl.lLll.llJJ.IlJlJJJJ,UJJJlJl,ILll.UJlJl.iniJLIUUUUUUlJUUl.
TToTa CTunT( c o u rTTT1
R30
^
C"FTTTTe a d / W r i t eTTaTa
R31
Block Copy Source Hddress (Hlgh)
_R32_
BTocT'TTTpy 5ource FTTTTeTs TToTT
_R33_
D i s p1 ay Enable Begin
_R34_
DTspToy Enab 1 e End
R35
v
v
r
W
Y
T
C
V
W
W
W
W
w
r
m
v
w
m
Y
W
^
^
TTRTTM RTTTTT^ TTr TrTn PThT UMnM nerresn pei oca
R36 LIUUULIUUUULUJlklUULIl.ll,llM.ILII.IIJl.\LILIlJUUUUUl.ll^
Figure I 6 - I L 8563 Register Map

SIGNAL DESCRIPTION
There are many different signals involved with the 8563 chip, but they can be divided
into three general categories. The CPU interface signals serve as an interface to the 8502
bus. The local bus management signals serve to maintain the local memory bus. Finally,
the video interface signals are the signals that are necessary to provide an RGBI image
on an RGBI monitor. The 8563 pin configuration is shown in Figure 16-12.

THE CPU INTERFACE

The 8563 chip interfaces to the 8502 bus using a minimum of signals. This is due
mainly to the local memory used by the 8563. The CPU interface signals are as follows:

D 0 - D 7 : Bidirectional data bus allowing data to be passed between the 8563

and 8502. Found on pins 18 to 13, 11 and 10.
CS: Chip select input. This input must be high for selection and proper
operation of the chip. Located at pin 4.
/CS: Chip select input. This input must be low for selection and proper
operation of the chip. Located at pin 7.

C128 HARDWARE SPECIFICATIONS

/RS: Register Select input. A high allows reads and writes to the selected data
register. A low allows reads of the status register and writes to the address
register, ln the system, this line is tied to AO. It is located at pin 8.
R/W: This line controls the data direction for the data bus. This is a typical
8502 control signal. Found at pin 9.
INIT: Active low input for clearing internal control latches, allowing the chip
to begin operation following initial power-on. Connect to /RES in the C128,
at pin 23.
DISPEN: Display Enable output signal, unused in the C128. Found at pin 19.
RES: This input initializes all internal scan counters, but not control registers.
It is not actively used in the C128 circuit, and is not found at pin 22.
TST: Pin used for testing only, tied to ground in the C128. Located at pin 24
of the chip.

THE LOCAL BUS MANAGEMENT INTERFACE

The local bus management interface is a group of signals generated by the 8563 for the
management of local video DRAM. This local DRAM both simplifies the addition of an
80-column video display to a system and enables a computer system with a limited
address space to support an 80-column display without taxing its limited memory
resources.

DD 0 ~DD 7 : Bidirectional local display DRAM data bus, comprising pins 35-36
and 3 8 ^ 2 .
DA 0 -DA 7 : Local display DRAM multiplexed address bus. Takes up pins
26-33.
DR/W: Local display DRAM Read/Write, pin 21.
/RAS: Row Address Strobe for local DRAM, pin 47.
/CAS: Column Address Strobe for local DRAM, pin 48.

THE VIDEO INTERFACE

The final set of 8563 signals are the video interface signals. These signals are directly
related to the display video image.

DCLK: Video Dot Clock, determines the pixel width and is used internally as
the timing basis for all synchronized signals, such as character clock and
DRAM timing. Found at pin 2.
CCLK: The character clock output, unused in the C128 system, and found at pin 1.
LP2: Input for light pen; a positive going transition on this input latches the
vertical and horizontal position of the character being displayed at that time.
Found at pin 25.
HSYNC: The horizontal sync signal, fully programmable via internal 8563
registers, and found at pin 20.
R , G , B J - The pixel data outputs. They form a 4-bit code associated with each
pixel, containing color/intensity information, allowing a total of sixteen colors
or gray shades to be displayed. Located at pins 46, 45, 44, 43, respectively.

597

554

COMMODORE 128

37

^2 D D 7
^il D D 6

VDD

CS

__,
Dfl7

33

Dfl6

32

4Q

DD5

Dfl5

31

39

DD4

DR4

30

>

38

DD3

DR3

29

>

^ 36

DD2

Dfl2

^ 35

DDI

Dfll

27

Dfl0

26

/cns

48

.34

DDQ

D7

k1

>

D6

( Q

D5
D4
0 3

D2

n n
^ ^

28

/Rns

47

DR/W

21

46
R

45

D1

44

D0

43

/RS
>

/CS

VSTN

20

R/W

HSTN

,23 / R E S
CCLK

DISPEN

19

TST

24

INIT

22

.25 / L P 2
/DCLK

vss

Figure 16-12. The 8563 Chip Pin Configuration

C128 HARDWARE SPECIFICATIONS

6581 SOUND INTERFACE DEVICE (SID)

CHIP SPECIFICATIONS
CONCEPT
The 6581 Sound Interface Device (SID) is a single-chip, three-voice electronic music
synthesizer/sound effects generator compatible with the 8502 and similar microprocessor
families. SID provides wide-range, high-resolution control of pitch (frequency), tone
color (harmonic content), and dynamics (volume). Specialized control circuitry minimizes software overhead, facilitating use in arcade/home video games and low-cost
musical instruments.

FEATURES

3 T O N E OSCILLATORS
Range: 0 ^ kHz
4 W A V E F O R M S PER OSCILLATOR
Triangle, Sawtooth,
Variable Pulse, Noise
3 AMPLITUDE M O D U L A T O R S
Range: 48 dB
3 ENVELOPE GENERATORS
Exponential response
Attack Rate: 2 m s - 8 s
Decay Rate: 6 m s - 2 4 s
Sustain Level: 0-peak volume
Release Rate: 6 m s - 2 4 s
OSCILLATOR SYNCHRONIZATION
RING M O D U L A T I O N
P R O G R A M M A B L E FILTER
Cutoff range: 30 H z - 1 2 kHz
12 dB/octave Rolloff
Low pass, Bandpass,
High pass, Notch outputs
Variable Resonance
MASTER V O L U M E CONTROL
2 A / D POT INTERFACES
R A N D O M N U M B E R / M O D U L A T I O N GENERATOR
E X T E R N A L A U D I O INPUT

599

554

COMMODORE 128

O
1

28

VDD

CAP 1B

27

AUDIO OUT

CAP 2A

26

EXT IN

CAP 2B

25

Vcc
POTX
POTY

22

D?

RES

LJ

CAP 1A

24

02

23

R/W

CS

21

D6

A0

20

D5

Ai

10

19

D4

A2

11

18

D3

A3

12

17

D2

A4

13

16

Di

GND

14

15

D0

6581
SID

Figure 16-13. 6581 SID Pin Configuration

C128 HARDWARE SPECIFICATIONS

r n o o i

JL
lttf1ttt TTTTTTT7

CHIP ACCESS CONTROL

15 |Sj <

<

<T <

DATA BUFFERS

<

Figure 16-14. 6581 Block Diagram

601

554

COMMODORE 128

DESCRIPTION
The 6581 consists of three synthesizer " v o i c e s " which can be used independently or in
conjunction with each other (or external audio sources) to create complex sounds. Each
voice consists of a Tone Oscillator/Waveform Generator, an Envelope Generator and an
Amplitude Modulator. The Tone Oscillator controls the pitch of the voice over a wide
range. The Oscillator produces four waveforms at the selected frequency, with the
unique harmonic content of each waveform providing simple control of tone color. The
volume dynamics of the oscillator are controlled by the Amplitude Modulator under the
direction of the Envelope Generator. When triggered, the Envelope Generator creates an
amplitude envelope with programmable rates of increasing and decreasing volume. In
addition to the three voices, a programmable Filter is provided for generating complex,
dynamic tone colors via subtractive synthesis.
SID allows the microprocessor to read the changing output of the third Oscillator
and third Envelope Generator. These outputs can be used as a source of modulation
information for creating vibrato, frequency/filter sweeps and similar effects. The third
oscillator can also act as a random number generator for games. T w o A / D converters are
provided for interfacing SID with potentiometers. These can be used for "paddles" in a
game environment or as front panel controls in a music synthesizer. SID can process
external audio signals, allowing multiple SID chips to be daisy-chained or mixed in
complex polyphonic systems. For full register descriptions, see Chapter 11, Sound and
Music on the Commodore 128.

SID PIN DESCRIPTION

CAPIA, CAPIB, (PINS l,2)/ CAP2A,CAP2B (PINS 3,4)
These pins are used to connect the two integrating capacitors required by the programmable filter. C1 connects between pins 1 and 2, C2 between pins 3 and 4. Both
capacitors should be the same value. Normal operation of the filter over the audio range
(approximately 30 H z - 1 2 kHz) is accomplished with a value of 2200 pF for C1 and C2.
Polystyrene capacitors are preferred and in complex polyphonic systems, where many
SID chips must track each other, matched capacitors are recommended.
The frequency range of the filter can be tailored to specific applications by the
choice of capacitor values. For example, a low-cost game may not require full highfrequency response. In this case, large values for C1 and C2 could be chosen to provide
more control over the bass frequencies of the filter. The maximum cutoff frequency of
the filter is given by:
FC m a x =

2.6E-5/C

where C is the capacitor value. The range of the filter extends nine octaves below the
maximum cutoff frequency.

RES (PIN 5)
This TTL-level input is the reset control for SID. When brought low for at least ten 4>2
cycles, all internal registers are reset to 0 and the audio output is silenced. This pin is
normally connected to the reset line of the microprocessor or a power-on-clear circuit.

C128 HARDWARE SPECIFICATIONS

<^2 (PIN 6)
This TTL-level input is the master clock for SID. All oscillator frequencies and
envelope rates are referenced to this clock. 2 also controls data transfers between SID
and the microprocessor. Data can only be transferred when 2 is high. Essentially, ^>2 acts
as a high-active chip select as far as data transfers are concerned. This pin is normally
connected to the system clock, with a nominal operating frequency of 1.0 MHz.

R/W (PIN 7)
This TTL-level input controls the direction of data transfers between SID and the
microprocessor. If the chip select conditions have been met, a high on this line allows
the microprocessor to Read data from the selected SID register and a low allows the
microprocessor to Write data into the selected SID register. This pin is normally
connected to the system Read/Write line.

CS (PIN 8)
This TTL-level input is a low active chip select which controls data transfers between
SID and the microprocessor. CS must be low for any transfer. A Read from the selected
SID register can only occur if CS is low, $ 2 is high and R/W is high. A Write to the
selected SID register can only occur if CS is low, $ 2 is high and R/W is low. This pin is
normally connected to address decoding circuitry, allowing SID to reside in the memory
map of a system.

A0-A4 (PINS 9-13)

These TTL-level inputs are used to select one of the 29 SID registers. Although enough
addresses are provided to select one of thirty-two registers, the remaining three register
locations are not used. A Write to any of these three locations is ignored and a Read
returns invalid data. These pins are normally connected to the corresponding address
lines of the microprocessor so that SID may be addressed in the same manner as
memory.

GND (PIN 14)

For best results, the ground line between SID and the power supply should be separate
from ground lines to other digital circuitry. This will minimize digital noise at the audio
output.

D0-D7 (PINS 15-22)

These bidirectional lines are used to transfer data between SID and the microprocessor.
They are TTL compatible in the input mode and capable of driving two TTL loads in the
output mode. The data buffers are usually in the high-impedance off state. During a
Write operation, the data buffers remain in the off (input) state and the microprocessor
supplies data to SID over these lines. During a Read operation, the data buffers turn on
and SID supplies data to the microprocessor over these lines. The pins are normally
connected to the corresponding data lines of the microprocessor.

603

554 COMMODORE 128

POTX,POTY (PINS 24,23)

These pins are inputs to the A / D converters used to digitize the position of potentiometers. The conversion process is based on the time constant of a capacitor tied from the
POT pin to ground, charged by a potentiometer tied from the POT pin to + 5 volts. The
component values are determined by:
RC -

4.7E^t

Where R is the maximum resistance of the pot and C is the capacitor.

The larger the capacitor, the smaller the POT value jitter. The recommended
values of R and C are 4 7 0 k f l and 1000 pF. Note that a separate pot and cap are required
for each POT pin.

Vcc (PIN 25)

As with the G N D line, a separate + 5 V D C line should be run between SID V c c and the
power supply in order to minimize noise. A bypass capacitor should be located close to
the pin.

EXT IN (PIN 26)

This analog input allows external audio signals to be mixed with the audio output of SID
or processed through the Filter. Typical sources include voice, guitar, and organ. The
input impedance of this pin is on the order of 100 k f l . Any signal applied directly to the
pin should ride at a D C level of 6 volts and should not exceed 3 volts p - p . In order to
prevent any interference caused by D C level differences, external signals should be
AC-coupled to EXT IN by an electrolytic capacitor in the 1 - 1 0 p f range. As the direct
audio path (FILTEX = 0) has unity gain, EXT IN can be used to mix outputs of many
SID chips by daisy-chaining. The number of chips that can be chained in this manner is
determined by the amount of noise and distortion allowable at the final output. Note that
the output volume control will affect not only the three SID voices, but also any external
inputs.

A U D I O O U T (PIN 27)
This open-source buffer is the final audio output of SID, comprised of the three
SID voices, the filter and any external input. The output level is set by the output
volume control and reaches a maximum of 2 volts p-p at a D C level of 6 volts. A
source resistor from Audio Out to ground is required for proper operation. The recommended resistance is 1 k f l for a standard output impedance.
As the output of SID rides at a 6-volt D C level, it should be AC-coupled to any
audio amplifier with an electrolytic capacitor in the 1 - 1 0 p f range.

V D D (PIN 28)
As with V c c , a separate 4-12 V D C line should be run to SID V D D and a bypass capacitor
should be used.

C128 HARDWARE SPECIFICATIONS

6581 SID CHARACTERISTICS

ABSOLUTE MAXIMUM RATINGS
RATING

SYMBOL

VALUE

Supply Voltage
Supply Voltage
Input Voltage (analog)
Input Voltage (digital)
Operating Temperature
Storage Temperature

VoD
Vv cc

^).3 to
^).3 to
^).3 to
^).3 to
0 to
- 5 5 to

VT ma

vind
TA
TsTG

UNITS

VDC
VDC
VDC
VDC
C
4-150 C
+17
+7
+17
+7
+70

ELECTRICAL CHARACTERISTICS
( V D D = 12 V D C 5 % , V c c = 5 V D C 5 % , T A = 0 to 70 C)

CHARACTERISTIC

SYMBOL

MIN

TYP

MAX

UNITS

V cc
0.8

VDC
VDC

2.5

^A

10

fxA

Input High Voltage

Input Low Voltage

(RES, 4>2, R/W, CS

A0-A4, D0-D7)

Vffl
V IL

2
^).3

Input Leakage Current

Iin

~~~

Three-State (Off)

(RES, 4>2, R/W, CS,

A0-A4; V in = 0 - 5 VDC)
(D0-D7; V cc = max)

Input Leakage Current

Vin = 0.4-2.4 VDC

Output High Voltage

(D0-D7; V cc = min,
1 load = 200 pA)

VoH

2.4

V c c ^).7

VDC

Output Low Voltage

(D0-D7; V cc = max,
1 load = 3.2 mA)

VoL

GND

0.4

VDC

Output High Current

(D0-D7; Sourcing,
VoH = 2.4 VDC)

IoH

200

fxA

Output Low Current

(D0-D7; Sinking
VoL = 0.4 VDC)

Io

3.2

mA

Input Capacitance

(RES, 4>2, R/W, CS,

A0-A4, D0-D7)

C in

10

pF

Pot Trigger Voltage

(POTX, POTY)

Vpo,

Vee/2

VDC

Pot Sink Current

(POTX, POTY)

Ipot

500

^A

lTSI

605

554

COMMODORE 128

CHARACTERISTIC

SYMBOL

MIN

TYP

MAX

UNITS

100

150

kn

5.7

6
0.5

6.3
3

VDC
VAC

Vout

5.7
0.4
1.0

6
0.5
1.5

6.3
0.6
2.0

VDC
VAC
VAC

Input Impedance

(EXT IN)

Rn

Audio Input Voltage

(EXT IN)

Vin

Audio Output Voltage

(AUDIO OUT; 1 kH
load, volume = max)
One Voice on:
All Voices on:

Power Supply Current

(VDO)

^DD

20

25

mA

Power Supply Current

(Vcc)

lcc

70

100

mA

Power Dissipation

(Total)

PD

600

1000

mW

6581 SID TIMING

T

j-

cvc

~~\

TR ^ |-

~A

_
f

i Tr

4
rlRS

t ;
m

TC
T

RHT^

: ~ JA _

j' ACC.

j~ , ' AHI

:
:
v ~
TCH ^" "

W ^ \

--J-

I DH^"

w
*TACC

IS

NAME

Tcvc
Tc
TR,TF
TRs
TRH

Clock Cycle Time

1
Clock High Pulse Width 450

Clock Rise/Fall Time

Read Set-Up Time
0
Read Hold time
0

Access Time
Address Hold Time
10
Chip Select Hold Time
0
Data Hold Time
20

T AH
TcH
TDH

^ -

m e a s u r e d f r o m t h e l a t e s t o c c u r r i n g of o 2 . CS. A 0 - A 4 .

SYMBOL

TAcc

Figure 16-15. Read Cycle

MIN

TYP

500

MAX

UNITS

20
10,000
25

300

fXS

ns
ns
ns
ns
ns
ns
ns
ns

C128 HARDWARE SPECIFICATIONS

T X XTX X X ^
AWS 4*~~|

!h-

3C

s x s t :
T W A

DC

* T W is m e a s u r e d f r o m t h e l a t e s t o c c u r r i n g of o 2 > C S , R / W

SYMBOL

NAME

MIN

Tw

Write Pulse Width

Write Hold Time
Address Set-up Time
Address Hold Time
Chip Select Hold Time
Valid Data
Data Hold Time

300
0
0
10
0
80
10

T\VH
TAWS
TAH
TcH
TvD
TDH

TYP

MAX

UNITS

ns
ns
ns
ns
ns
ns
ns

Figure 16-16. Write Cycle

EQUAL-TEMPERED
MUSICAL SCALE VALUES
The table in Chapter 11 lists the numerical values which must be stored in the SID
Oscillator frequency control registers to produce the notes of the equal-tempered musical
scale. The equal-tempered scale consists of an octave containing twelve semitones
(notes): C , D , E , F , G , A , B and C # , D # , F # , G # , A # . The frequency o f e a c h semitone is
exactly the 12th root of 2 (V~2~) times the frequency of the previous semitone. The table
is based on a c^2 clock of 1.02 MHz. Refer to the equation given in the Register
Description in Chapter 11 for use of other master clock frequencies. The scale selected
is concert pitch, in which A^4- = 4 4 0 Hz. Transpositions of this scale and scales other
than the equal-tempered scale are also possible.
Although the table in Chapter 11 provides a simple and quick method for generating the equal-tempered scale, it is very memory inefficient as it requires 192 bytes for
the table alone. Memory efficiency can be improved by determining the note value
algorithmically. Using the fact that each note in an octave is exactly half the
frequency of that note in the next octave, the note look-up table can be reduced from
ninety-six entries to twelve entries, as there are twelve notes per octave. If the twelve

607

554

COMMODORE 128

entries (24 bytes) consist of the 16-bit values for the eighth octave (C-7 through B-7),
then notes in lower octaves can be derived by choosing the appropriate note in the eighth
octave and dividing the 16-bit value by two for each octave of difference. As division by
two is nothing more than a right-shift of the value, the calculation can easily be
accomplished by a simple software routine. Although note B-7 is beyond the range of
the oscillators, this value should still be included in the table for calculation purposes
(the MSB of B-7 would require a special software case, such as generating this bit in the
CARRY before shifting). Each note must be specified in a form which indicates which
of the twelve semitones is desired, and which of the eight octaves the semitone is in.
Since 4 bits are necessary to select one of twelve semitones and 3 bits are necessary to
select one of eight octaves, the information can fit in one byte, with the lower nybble
selecting the semitone (by addressing the look-up table) and the upper nybble being used
by the division routine to determine how many times the table value must be right-shifted.

SID ENVELOPE GENERATORS

The four-part ADSR (ATTACK, DECAY, SUSTAIN, RELEASE) envelope generator
has been proven in electronic music to provide the optimum trade-off between flexibility
and ease of amplitude control. Appropriate selection of envelope parameters allows the
simulation of a wide range of percussion and sustained instruments. The violin is a good
example of a sustained instrument. The violinist controls the volume by bowing the
instrument. Typically, the volume builds slowly, reaches a peak, then drops to an
intermediate level. The violinist can maintain this level for as long as desired,
then the volume is allowed to slowly die away. A *'snapshot" of this envelope is
shown below:

S
PEAK AMPLITUDE

SUSTAIN
PERIOD

ZERO AMPLITUDE

Figure 16-17. ADSR Envelope

This volume envelope can be easily reproduced by the ADSR as shown below,
with typical envelope rates:

C128 HARDWARE SPECIFICATIONS

ATTACK:
DECAY:
SUSTAIN:
RELEASE:

10 ($A)
8
10 ($A)
9

500 ms
300 ms
750 ms
GATE^|

Note that the tone can be held at the intermediate S U S T A I N level for as long as
desired. The tone will not begin to die away until GATE is cleared. With minor
alterations, this basic envelope can be used for brass and woodwinds as well as strings.
An entirely different form of envelope is produced by percussion instruments such
as drums, cymbals and gongs, as well as certain keyboards such as pianos and
harpsichords. The percussion envelope is characterized by a nearly instantaneous attack,
immediately followed by a decay to zero volume. Percussion instruments cannot be
sustained at a constant amplitude. For example, the instant a drum is struck, the sound
reaches full volume and decays rapidly regardless of how it was struck. A typical
cymbal envelope is shown below:

ATTACK
DECAY
SUSTAIN
RELEASE

2 ms
750 ms
750 ms

Note that the tone immediately begins to decay to zero amplitude after the peak is
reached, regardless of when GATE is cleared. The amplitude envelope of pianos and
harpsichords is somewhat more complicated, but can be generated quite easily with the
A D S R . These instruments reach full volume when a key is first struck. The amplitude
immediately begins to die away slowly as long as the key remains depressed. If the key
is released before the sound has fully died away, the amplitude will immediately drop to
zero. This envelope is shown below:

ATTACK
DECAY
SUSTAIN
RELEASE

2 ms
750 ms
6 ms

Note that the tone decays slowly until GATE is cleared, at which point the
amplitude drops rapidly to zero.
The most simple envelope is that of the organ, When a key is pressed, the tone
immediately reaches full volume and remains there. When the key is released, the tone
drops immediately to zero volume. This envelope is shown below:

609

554

COMMODORE 128

ATTACK
DECAY
SUSTAIN
RELEASE

0
2ms
0
6 ms
15($F)
0
6 ms

The real power of SID lies in the ability to create original sounds rather than
simulations of acoustic instruments. The ADSR is capable of creating envelopes which
do not correspond to any "real" instruments. A good example would be the "backwards" envelope. This envelope is characterized by a slow attack and rapid decay
which sounds very much like an instrument that has been recorded on tape then played
backwards. This envelope is shown below:
ATTACK
DECAY
SUSTAIN
RELEASE

10 ($A)
0
15 ($F)
3

500 ms
6 ms
72 ms

Many unique sounds can be created by applying the amplitude envelope of one
instrument to the harmonic structure of another. This produces sounds similar to familiar
acoustic instruments, yet notably different. In general, sound is quite subjective and
experimentation with various envelope rates and harmonic contents will be necessary in
order to achieve the desired sound.

Figure 16-18. Typical 658I/SID Application

C128 HARDWARE SPECIFICATIONS

6526 COMPLEX INTERFACE ADAPTER

(CIA) CHIP SPECIFICATIONS
DESCRIPTION
The 6526 Complex Interface Adapter (CIA) is an 8502 bus compatible peripheral
interface device with extremely flexible timing and I/O capabilities. Figure 1 6 - 1 9 shows
the 6526 pin configuration. Figure 1 6 - 2 0 shows the 6526 block diagram.

FEATURES

16 Individually programmable I/O lines

8 or 16-bit handshaking on read or write
2 independent, linkable 16-bit interval timers
24-hour (AM/PM) time of day clock with programmable alarm
8-bit shift register for serial I/O
2TTL load capability
CMOS compatible I/O lines
1 or 2 MHz operation available

ORDERING INFORMATION
MXS 6526
FREQUENCY RANGE
NO SUFFIX = lMHz
A = 2MHz
PACKAGE DESIGNATOR
C = CERAMIC
P = PLASTIC

611

554

COMMODORE 128

Vss

PA0

E
E

^7
40 CNT

PA!

3 s p
js] RS0

PA2

TT| RS!

PA3

PA4

3RS2
35 RS3

PA5

34 RES

PA6

33 DB0

PA7

32 DB1

PBo 10

6526

31 DB2

PBi 11

30 DB3

PB2 12

29 DB4

PB3 13

28 DB5

PB4 14

j7| DB6

PB5 15

^2ej DB7

PB6 Qe
PB7 7

3 | *2
24 FLAG

PC 18

23 CS

TOD 19

22 R/W

Vcc

20

| fRQ

Figure 16-19. 6526 CIA Pin Configuration

C128 HARDWARE SPECIFICATIONS

D0-D7

CHIP ACCESS CONTROL

fVW

02

CS

RS3 RS2

RS1 RSO

RES

Figure l6-20. 6526 Block Diagram

ABSOLUTE MAXIMUM RATINGS

Supply Voltage, V cc
Input/Output Voltage, V IN
Operating Temperature, T 0 p
Storage Temperature, T s r G

- 0 . 3 V to + 7 . 0 V
^ ) . 3 V to + 7 . 0 V
0 C to 70 C
-55 C to 150 C

613

554

COMMODORE 128

All inputs contain protection circuitry to prevent damage due to high static
discharges. Care should be exercised to prevent unnecessary application of voltages in
excess of the allowable limits.

COMMENT
Stresses above those listed under ''Absolute Maximum Ratings" may cause permanent
damage to the device. These are stress ratings only. Functional operation of this device
at these or any other conditions above those indicated in the operational sections of this
specification is not implied and exposure to absolute maximum rating conditions for
extended periods may affect device reliability.

ELECTRICAL CHARACTERISTICS
(Vcc 5%, Vss = 0 V, T A = 0-70C)
TYP.

MAX.

UNIT

+ 2.4

Vcc

^).3

1.0

2.5

^A

5.0

Ka

CHARACTERISTIC

SYMBOL MIN.

Input High Voltage

ViH

Input Low Voltage

ViL

Input Leakage Current;

VIN = VSS + 5V
(TOD, R/W, FLAG,4>2,
RES, RS0-RS3, CS)

IlN

Port Input Pull-up Resistance

Rpi

Output Leakage Current for

High Impedance State (Three
State); VIN = 4V to 2.4V;

lTSI

3.1

1.0

10.0

pA

Vcc

+ 0.40

(DB0-DB7, SP, CNT, IRQ)

Output High Voltage

Vcc = MIN, ILOAD < _

VoH

+ 2.4

VoL

-200pA (PA0-PA7, PC
PB0-PB7, DB0-DB7)

Output Low Voltage

Vcc = MIN, lLOAD<3.2 mA

Output High Current (Sourcing);

VoH > 2.4V (PA0-PA7,
PB0-PB7, PC, DB0-DB7

IOH

Output Low Current (Sinking);

VoL < .4V (PA0-PA7, PC,
PB0-PB7, DB0-DB7)

IOL

Input Capacitance

ClN

10

pf

Output Capacitance

CoUT

10

pf

Power Supply Current

Icc

70

100

mA

-200

-1000

pA
~

3.2

mA

C128 HARDWARE SPECIFICATIONS

TCYC '
T

CHW -

- T CLW

02 INPUT
'

PD "

PERIPHERAL
DATA OUT
T WCS

^.
T

_fflMMMT

ADS

ADH "

z > :
X

.r

DATA IN
DB7-DB0

-^DH

Figure 16-21. 6526 Write Timing Diagram

J"
TPS

02 INPUT

J ~

PORT IN

CS

y,

RS3-RS0

"TADS

J
ADH -

3c
^

RAV
T

CO-

RWH "

RWS-

DATA OUT
DB7-DB0

^ W L
T

" ACC "

DR~

Figure 16-22. 6526 Read Timing Diagram

6526 INTERFACE SIGNALS

4>2CLOCK INPUT
The 4>2 clock is a TTL-compatible input used for internal device operation and as a timing
reference for communicating with the system data bus.

C S ^ C H I P SELECT INPUT

The CS input controls the activity of the 6526. A low level on CS while ^ 2 is high causes
the device to respond to signals on the R/W and address (RS) lines. A high on CS
prevents these lines from controlling the 6526. The CS line is normally activated (low)
at 4>2 by the appropriate address combination.

615

616

COMMODORE 128

R/WREAD/WRITE INPUT
The R/W signal is normally supplied by the microprocessor and controls the direction of
data transfers of the 6526. A high on R/W indicates a read (data transfer out of the
6526), while a low indicates a write (data transfer into the 6526).

RS3-RS0ADDRESS INPUTS
The address inputs select the internal registers as described by the Register Map.

DB7-DB0DATA BUS INPUTS/OUTPUTS

The eight data bus pins transfer information between the 6526 and the system data bus.
These pins are high impedance inputs unless CS is low and R/W and $ 2 are high to read
the device. During this read, the data bus output buffers are enabled, driving the data
from the selected register onto the system data bus.

lRQINTERRUPT REQUEST OUTPUT

IRQ is an open drain output normally connected to the processor interrupt input. An
external pullup resistor holds the signal high, allowing multiple IRQ outputs to be
connected together. The IRQ output is normally off (high impedance) and is activated
low as indicated in the functional description.

RESRESET INPUT
A low on the RES pin resets all internal registers. The port pins are set as inputs and
port registers to zero (although a read of the ports will return all highs because of
passive pullups). The timer control registers are set to 0 and the timer latches to all ones.
All other registers are reset to 0.

6526 TIMING CHARACTERISTICS

1 MHz
SYMBOL

TcYC

TR, TF
TcHW
TcLW

Tpo
Twcs
TADS
TADH
TRws
TRWH

TDS
TDH

CHARACTERISTIC
<4>2 Clock
Cycle Time
Rise and Fall Time
Clock Pulse Width (High)
Clock Pulse Width (Low)

Write Cycle
Output Delay From ^2
CS low while 4>2 high
Address Setup Time
Address Hold Time
R/W Setup Time
R/W Hold Time
Data Bus Setup Time
Data Bus Hold Time

2MHz

MIN

MAX

1000

20,000 500
25
10,000 200
10,000 200

420
420

420
0
10
0
0
150
0

1000

MIN

MAX

UNIT

20,000
25
10,000
10,000

ns
ns
ns
ns

500

ns
ns
ns
ns
ns
ns
ns
ns

200
0
5
0
0
75
0

C128 HARDWARE SPECIFICATIONS

6526 TIMING CHARACTERISTICS (continued)

2MHz

1 MHz
SYMBOL

Tps

Twcs(2)
TADS
TAOH
TRws
TRWH
TACC

Ico(3)
TDR

CHARACTERISTIC

MIN

Read Cycle
Port Setup Time
CS low while ^2 high
Address Setup Time
Address Hold Time
R/W Setup Time
R/W Hold Time
Data Access from RS3-RS0
Data Access from CS
Data Release Time

300
420
0
10
0
0

MAX

550
320

50

MIN

150
20
0
5
0
0

MAX

275
150

25

UNIT

ns
ns
ns
ns
ns
ns
ns
ns
ns

1.

All timings are referenced from V I L max and V I H min on inputs and V 0 L max and
V D H min on outputs.

2.

T w c s is measured from the later of 4>2 high or CS low. CS must be low at least
until the end of 4>2 high.
T c o is measured from the later of ^>2 high or CS low. Valid data is available only
after the later of T A C C or T c o .

3.

REGISTER MAP
RS3

RS2

RS1

RS0

REG

0
0
0
0
0
0
0
0

0
0
0
0
1
1
1
1
0
0
0
0
1
1
1
1

0
0
1
1
0
0
1
1
0
0
1
1
0
0
1
1

0
1
0
1
0
1
0
1
0
1
0
1
0
1
0
1

0
1
2
3
4
5
6
7
8
9
A
B
C
D
E
F

NAME

DESCRIPTION

PRA
PRB
DDRA
DDRB
TA LO
TA HI
TB LO
TB HI
TOD lOTHS
TOD SEC
TOD MIN
TOD HR
SDR
ICR
CRA
CRB

PERIPHERAL DATA REG A

PERIPHERAL DATA REG B
DATA DIRECTION REG A
DATA DIRECTION REG B
TIMER A LOW REGISTER
TIMER A HIGH REGISTER
TIMER B LOW REGISTER
TIMER B HIGH REGISTER
lOTHS OF SECONDS REGISTER
SECONDS REGISTER
MINUTES REGISTER
HOURSAM/PM REGISTER
SERIAL DATA REGISTER
INTERRUPT CONTROL REGISTER
CONTROL REG A
CONTROL REG B

617

618

COMMODORE 128

6526 FUNCTIONAL DESCRIPTION

I/O PARTS (PRA, PRB, DDRA, DDRB).
Parts A and B each consist of an 8-bit Peripheral Data Register (PR) and an 8-bit Data
Direction Register (DDR). If a bit in the DDR is set to one, the corresponding bit in the PR
is an output, if a DDR bit is set to a 0, the corresponding PR bit is defined as an input.
On a READ, the PR reflects the information present on the actual port pins (PA0-PA7,
PB0-PB7) for both input and output bits. Port A and Port B have passive pull-up
devices as well as active pull-ups, providing both CMOS and TTL compatibility. Both
parts have two TTL load drive capability. In addition to normal I/O operation, PB6 and
PB7 also provide timer output functions.

HANDSHAKING

Handshaking on data transfers can be accomplished using the PC output pin and the
FLAG input pin. PC will go low for one cycle following a read or write of PORT B.
This signal can be used to indicate "data ready" at PORT B or "data accepted" from
PORT B. Handshaking on 16-bit data transfers (using both PORT A and PORT B) is
possible by always reading or writing PORT A first. FLAG is a negative edge sensitive
input which can be used for receiving the PC output from another 6526, or as a general
purpose interrupt input. Any negative transition of FLAG will set the FLAG interrupt
bit.

REG NAME

D7

0
1
2
3

PA7
PA6
PA5
PB7
PB6
PB5
DPA7 DPA6 DPA5
DPB7 DPB6 DPB5

PRA
PRB
DDRA
DDRB

D6

D5

D4

Di

PA2
PB2
DPA2
DPB2

PA!
PAo
PBi
PBo
DPAi DPAo
DPBi DPBo

D3

PA4
PA3
PB4
P3
DPA4 DPA3
DPB4 DPB3

Do

INTERVAL TIMERS (TIMER A, TIMER B)

Each interval timer consists of a 16-bit read-only Timer Counter and a 16-bit writeonly Timer Latch. Data written to the timer are latched in the Timer Latch, while
data read from the timer are the present contents of the Time Counter. The timers
can be used independently or linked for extended operations. The various timer modes
allow generation of long time delays, variable width pulses, pulse trains and variable
frequency waveforms. Utilizing the CNT input, the timers can count external pulses
or measure frequency, pulse width and delay times of external signals. Each timer
has an associated control register, providing independent control of the following
functions:

START/STOP
A control bit allows the timer to be started or stopped by the microprocessor at any
time.

C128 HARDWARE SPECIFICATIONS

PB ON/OFF
A control bit allows the timer output to appear on a PORT B output line (PB6 for
TIMER A and PB7 for TIMER B). This function overrides the DDRB control bit and
forces the appropriate PB line to an output.

TOGGLE/PULSE
A control bit selects the output applied to PORT B. On every timer underflow the output
can either toggle or generate a single positive pulse of one cycle duration. The toggle
output is set high whenever the timer is started and is set low by RES.

ONE-SHOT/CONTINUOUS
A control bit selects either timer mode. In one-shot mode, the timer will count down
from the latched value to 0, generate an interrupt, reload the latched value, then stop. In
continuous mode, the timer will count from the latched value to 0, generate an interrupt,
reload the latched value and repeat the procedure continuously.

FORCE LOAD
A strobe bit allows the timer latch to be loaded into the timer counter at any time,
whether the timer is running or not.

INPUT MODE
Control bits allow selection of the clock used to decrement the timer. TIMER A can
count ^>2 clock pulses or external pulses applied to the CNT pin. TIMER B can count 4>2
pulses, external CNT pulses, TIMER A underflow pulses or TIMER A underflow pulses
while the CNT pin is held high.
The timer latch is loaded into the timer on any timer underflow, on a force load or
following a write to the high byte of the prescaler while the timer is stopped. If the timer
is running, a write to the high byte will load the timer latch, but not reload the counter.

READ (TIMER)
REG

NAME

4
5
6
7

TA
TA
TB
TB

LO
HI
LO
HI

TAL7
TAH7
TBL7
TBH7

TAL6
TAH6
TBL6
TBH6

TAL5
TAHS
TBL5
TBH5

TAL4
TAH4
TBL4
TBH4

TAL3
TAH3
TBL3
TBH3

TAL2
TAH2
TBL2
TBH2

TALt
TAHj
TBLi
TBHi

TAL<,
TAH0
TBL0
TBH0

PAL7 PAL6 PAL5 PAL4 PAL3 PAL2 PAL!

PAH7 PAH6 PAHS PAH4 PAH3 PAH2 PAHi
PBL7 PBL6 PBL5 PBL4 PBL3 PBL2 PBLi
PBH7 PBH6 PBH5 PBH4 PBH3 PBH2 PBHj

PAL0
PAH0
PBL0
PBH0

WRITE (PRESCALER)
REG

NAME

4
5
6
7

TA LO
TA HI
TB LO
TBHI

619

620

COMMODORE 128

TIME OF DAY CLOCK (TOD)

The TOD clock is a special purpose timer for real-time applications. TOD consists of a
24-hour (AM/PM) clock with l/10th second resolution. It is organized into four registers: 10ths of seconds, Seconds, Minutes and Hours. The AM/PM flag is in the MSB of
the Hours register for easy bit testing. Each register reads in BCD format to simplify
conversion for driving displays, etc. The clock requires an external 60 Hz or 50 Hz
(programmable) TTL level input on the TOD pin for accurate time keeping. In addition
to timekeeping, a programmable ALARM is provided for generating an interrupt at a
desired time. The ALARM registers are located at the same addresses as the corresponding TOD registers. Access to the ALARM is governed by a Control Register bit. The
ALARM is write-only; any read of a TOD address will read time regardless of the state
of the ALARM access bit.
A specific sequence of events must be followed for proper setting and reading of
TOD. TOD is automatically stopped whenever a write to the Hours register occurs. The
clock will not start again until after a write to the 10ths of seconds register. This assures
TOD will always start at the desired time. Since a carry from one stage to the next can
occur at any time with respect to a read operation, a latching function is included to
keep all Time Of Day information constant during a read sequence. All four TOD
registers latch on a read of Hours and remain latched until after a read of 10ths of
seconds. The TOD clock continues to count when the output registers are latched. If
only one register is to be read, there is no carry problem and the register can be read
" o n the f l y , " provided that any read of Hours is followed by a read of 10ths of seconds
to disable the latching.

READ
REG

NAME

8
9
A
B

TOD
TOD
TOD
TOD

10THS
SEC
MIN
HR

0
0
0
PM

0
SH4
MH4
0

0
SH2
MH2
0

0
SH!
MHi
HH

T8
SL8
ML8
HL8

T4
SL4
ML4
HL4

T2
SL2
ML2
HL2

Ti
SLi
ML!
HLi

WRITE
CRBy = 0 TOD
CRB7 = 1 ALARM
(SAME FORMAT AS READ)

SERIAL PORT (SDR)

The serial port is a buffered, 8-bit synchronous shift register system. A control bit
selects input or output mode. In input mode, data on the SP pin is shifted into the shift
register on the rising edge of the signal applied to the CNT pin. After eight CNT pulses,
the data in the shift register is dumped into the Serial Data Register and an interrupt is
generated. In the output mode, TIMER A is used for the baud rate generator. Data is

C128 HARDWARE SPECIFICATIONS

shifted out on the SP pin at one half the underflow rate of TIMER A. The maximum
baud rate possible is ^>2 divided by 4, but the maximum useable baud rate will be
determined by line loading and the speed at which the receiver responds to input data.
Transmission will start following a write to the Serial Data Register (provided TIMER A
is running and in continuous mode). The clock signal derived from TIMER A appears as
an output on the CNT pin. The data in the Serial Data Register will be loaded into the
shift register then shift out to the SP pin when a CNT pulse occurs. Data shifted out
becomes valid on the falling edge of CNT and remains valid until the next falling edge.
After eight CNT pulses, an interrupt is generated to indicate more data can be sent. If
the Serial Data Register was loaded with new information prior to this interrupt, the new
data will automatically be loaded into the shift register and transmission will continue. If
the microprocessor stays one byte ahead of the shift register, transmission will be
continuous. If no further data is to be transmitted, after the 8th CNT pulse, CNT will
return high and SP will remain at the level of the last data bit transmitted. SDR data is
shifted out MSB first and serial input data should also appear in this format.
The bidirectional capability of the Serial Port and CNT clock allows many 6526
devices to be connected to a common serial communication bus on which one 6526 acts
as a master, sourcing data and shift clock, while all other 6526 chips act as slaves. Both
CNT and SP outputs are open drain to allow such a common bus. Protocol for
master/slave selection can be transmitted over the serial bus, or via dedicated handshaking
lines.

REG

NAME

SDR

S7 S5 S5 S4 S3 S2 Sj S(

INTERRUPT CONTROL (ICR)

There are five sources of interrupts on the 6526: underflow from TIMER A, underflow
from TIMER B, TOD ALARM, Serial Port full/empty and FLAG. A single register
provides masking and interrupt information. The interrupt Control Register consists of a
write-only MASK register and a read-only DATA register. Any interrupt will set the
corresponding bit in the DATA register. Any interrupt which is enabled by the MASK
register will set the IR bit (MSB) of the DATA register and bring the IRQ pin low. In a
multi-chip system, the IR bit can be polled to detect which chip has generated an
interrupt request. The interrupt DATA register is cleared and the IRQ line returns high
following a read of the DATA register. Since each interrupt sets an interrupt bit
regardless of the MASK, and each interrupt bit can be selectively masked to prevent the
generation of a processor interrupt, it is possible to intermix polled interrupts with true
interrupts. However, polling the IR bit will cause the DATA register to clear, therefore,
it is up to the user to preserve the information contained in the DATA register if any
polled interrupts were present.
The MASK register provides convenient control of individual mask bits. When
writing to the MASK register, if bit 7 (SET/CLEAR) of the data written is a ZERO, any

621

622

COMMODORE 128

mask bit written with a one will be cleared, while those mask bits written with a 0
will be unaffected. If bit 7 of the data written is a ONE, any mask bit written with a one
will be set, while those mask bits written with a 0 will be unaffected. In order for an
interrupt flag to set IR and generate an Interrupt Request, the corresponding MASK bit
must be set.

READ (INT DATA)

REG

NAME

ICR

IR

FLG

SP

ALRM

TB

TA

FLG

SP

ALRM

TB TA

WRITE (INT MASK)

REG

NAME

ICR

S/C

CONTROL REGISTERS
There are two control registers in the 6526, CRA and CRB. CRA is associated
with TIMER A and CRB is associated with TIMER B. The register format is as
follows:

CRA:

BIT

NAME

FUNCTION

START

1
2
3
4

PBON
OUTMODE
RUNMODE
LOAD

INMODE

SPMODE

TODIN

1 = START TIMER A, O = STOP TIMER A, This bit is automatically reset when underflow occurs during one-shot mode.
l = TIMER A output appears on PB6, 0 = PB6 normal operation.
1 = TOGGLE, 0 = PULSE
1 = ONE-SHOT, 0 = CONTINUOUS
1 = FORCE LOAD (this is a STROBE input, there is no data
storage, bit 4 will always read back a 0 and writing a 0 has no
effect).
1 = TIMER A counts positive CNT transitions, 0 = TIMER A counts
4>2 pulses.
1 = SERIAL PORT output (CNT sources shift clock), 0 = SERIAL
PORT input (external shift clock required).
1 = 50 Hz clock required on TOD pin for accurate time, 0 = 60 Hz
clock required on TOD pin for accurate time.

C128 HARDWARE SPECIFICATIONS

CRB:

BIT

NAME

FUNCTION

5,6

INMODE

ALARM

(Bits CRB0-CRB4 are identical to CRA0-CRA4 for TIMER B

with the exception that bit 1 controls the output of TIMER B on
PB7).
Bits CRB5 and CRB6 select one of four input modes for TIMER
B as:
CRB6 CRB5
0
0
TIMER B counts 4>2 pulses.
0
1
TIMER B counts positive CNT transitions.
1
0
TIMER B counts TIMER A underflow pulses.
1
1
TIMER B counts TIMER A underflow pulses
while CNT is high.
l = writing to TOD registers sets ALARM, 0 = writing to TOD
registers sets TOD clock.

us

NAME

TOD
ttl

SP

REG

MODE

MODE

LOAD

CRA

0 = 60Hz

0 = INPUT

0 = 4>2

l = 50Hz

1 = OUTPUT

l = CNT

1 = FORCE
LOAD
(STROBE)

RUN
MODE

OUT
MODE

PS ON

START

O=CONT

0 = PULSE

0 = PB$OFF

0 = STOP

1 = 0.5

1=TOGGLE

l = PB 6 ON

1=START

REG

NAME

ALARM

IN

MODE

LOAD

RUN
MODE

OUT
MODE

PS ON

START

CRS

O = TOD

0
1
1
1

0 = $2
l = CNT
0 = TA
1 = CNT TA

1 = FORCE
LOAD

O = CONT.

0 = PULSE

O = PS7OFF

0 = STOP

(STROBE)

l = O.S.

1 = TOGGLE

l = PS7ON

1=START

1=
ALARM

All unused register bits are unaffected by a write and are forced to zero on a
read.

623

624

COMMODORE 128

DYNAMIC RANDOM ACCESS

MEMORY
This section discusses the characteristics of the C128 dynamic RAMs, which are
currently the 4164 64K-bit RAM. This RAM device is in the 64K by 1-bit configuration. This section also contains information on the 4416 dynamic RAMs used by
the 8563 video controller. This type of RAM is a 64K RAM in the 16K by 4 bit
configuration.

SYSTEM RAM DESCRIPTION

The C128 system contains 128K of processor-addressable DRAM in the 64K by 1
configuration, organized into two individual 64K banks. Additionally, the system
contains 16K of video display DRAM local to the 8563 video controller, not directly
accessable by the processor.
RAM banking, described in detail in the MMU section in Chapter 13, is controlled
by several MMU registers: the Configuration Register, the RAM Configuration Register, and the Zero Page and Page One Pointers. Simply put, the Configuration Register
controls which 64K bank of RAM is selected; the RAM Configuration Register controls
if and how much RAM is kept in common between banks, and the Pointer Registers
redirect the zero and one pages to any page in memory, overriding the effect of the two
Configuration Registers. In the system, RAM bank select is achieved via gated CAS
control.

PHYSICAL CHARACTERISTICS
This section covers some of the characteristics of the 64K by 1-bit RAM and 16K by
4-bit RAM that are used in the C128 system. A pinout table and a figure are given for
both the 4164 and the 4416 packages (See Tables 16-15 and 16-16 and Figures 16-23 and
16-24).

C128 HARDWARE SPECIFICATIONS

PIN

NAME

DESCRIPTION

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

NC
Din
/WE
/RAS
Ao
A2
A,
Vcc
A7
As
A4
A3
A6
Dout
/CAS
VT
ss

No Connection
Data In
Write Enable (Active Low)
Row Address Strobe (Active Low)
Address Bit 0
Address Bit 2
Address Bit 1
Power Supply + 5 Vdc
Address Bit 7
Address Bit 5
Address Bit 4
Address Bit 3
Address Bit 6
Data Out
Column Address Strobe (Active Low)
Power Supply Ground

Table 16-15. 4164 Pinout

Figure 16-23. The 4164 Chip

625

626

COMMODORE 128

PIN

NAME

DESCRIPTION

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

/OE
D!
D2
/WE
/RAS
A6
A5
A4
Vdd
A7
A3
A2
Ai
Ao
D3
/CAS
D4
Vss

Output Enable (Active Low)

Data Bit 1
Data Bit 2
Write Enable (Active Low)
Row Address Strobe (Active Low)
Address Bit 6
Address Bit 5
Address Bit 4
Power Supply + 5 Vdc
Address Bit 7
Address Bit 3
Address Bit 2
Address Bit 1
Address Bit 0
Data Bit 3
Column Address Strobe (Aetive Low)
Data Bit 4
Power Supply Ground

Table 16-16. 4416 Pinout

/ 0 E

VSS

<^-

D 1

D4

0-

D2

CflS

^>
^>

D3

^>

/RR

flQ

^>

o-

n6

R1

^>

o-

n5

fl2

o-

n^

n3

<s^-

DD

Figure 16-24. The 4464 Chip

^>
^>

^>

C128 HARDWARE SPECIFICATIONS

READ ONLY MEMORY (ROM)

This section describes the C128 system ROM, both from a logical and a hardware point
of view. It mentions aspects of the ROM banking structure, the management of Kernal
and BASIC, and explains the physical specifications of the ROM devices themselves.

SYSTEM ROM DESCRIPTION

In C64 mode, the operating system resides in 16K of ROM, which includes approximately 8K for Kernal and 8K for BASIC. In C128 mode, the operating system resides in
48K of ROM and includes advanced Kernal and BASIC features. The Kernal, by
definition, is the general operating system of the computer, with fixed entry points into
usable subroutines to facilitate ROM update transparent use by higher-level programs.
There is also a character ROM that resides on the Shared Bus, shared by the VIC chip
and the processor. This ROM is a 4016 8K by 8, NMOS ROM. The C64 OS ROM is
wired so as to appear as two chunks of noncontiguous ROM, copying the actual C64
ROM memory map. Provision is included to handle system ROM as either four 16K X
8 ROMs or as two 32K x 8 ROMs. All internal C128 function ROMs will be the 32K
x 8 variety.

ROM BANKING
Refer back to the MMU register map, Figure 13^- in Chapter 13. Note that the
Configuration Register (CR) controls the type of ROM or RAM seen in a given address
location. Dependent on the contents of the CR, ROM may be enabled and disabled to
attain the most useful configuration for the application at hand. ROM is enabled in three
memory areas in C128 mode, each consisting of 16K of address space. The lower ROM
may be defined as RAM or System ROM, the upper two ROMs may be System ROM,
Function ROM ; Cartridge ROM or RAM. In C64 mode, the C64 memory mapping rules
apply, which are primitive compared to those used in C128 mode. C64 ROM is banked
as two 8K sections, BASIC and Kernal, according to the page zero port and the
cartridge in place at the time. No free banking can occur when a cartridge is in
place.
In the C128, if an address falls into the range of an enabled ROM, the MMU will
communicate the status of ROM to the PLA decoder via the memory status lines.
Essentially, the MMU looks up in the Configuration Register which ROM or RAM is
set. See Chapter 13. The way the banking scheme is implemented, it allows up to 32K
of internal, bankable ROM for use in such programs as Function Key Applications,
and will support 32K of internal bankable ROM. Various combinations of ROM are
possible, and can be noted by studying the configurations for the Configuration
Register. Type 23128 (16K by 8) and 23256 (32K by 8) ROMs are used by the
system.

627

628

COMMODORE 128

TIMING SPECIFICATION
INTERNAL ROMs
This section specifies timing parameters for both the 23128 and the 27256 Read Only
Memories. This timing spec applies to internal ROMs and for external ROMs run at 1
MHz. For external ROMs run at 2 MHz, see Table 16-18.

PARAMETER

SYMBOL

MIN

MAX

UNIT

Address Valid to Output Delay

Chip Enable to Output Delay
Output Enable to Output Delay

T A cc
TCE
T OE

300
300
120

ns
ns
ns

Table 16-17. Internal ROM Timing

flDDRE55CHIP
ENRBLE
OUTPUT
ENflBLE
DRTfl

Figure 16-25. ROM Timing Diagram

EXTERNAL ROMS
All C64 mode external ROMs and many C128 mode external ROMs can be of the type
mentioned above. Any external ROM that is to run at 2 MHz must be faster, as
specified in Table 16-18.

PARAMETER

SYMBOL

MIN

Address Valid to Output Delay

Chip Enable to Output Delay
Output Enable to Output Delay

TACC
TcE
ToE

250
200
100

Table 16-18. External 2MHz ROM Timing

MAX

UNIT

ns
ns
ns

C128 HARDWARE SPECIFICATIONS

THE 23128 ROM

PIN

NAME

DESCRIPTION

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

Vv

Programming Voltage
Address Bit 12 (A13 on the C64 OS ROM)
Address Bit 7
Address Bit 6
Address Bit 5
Address Bit 4
Address Bit 3
Address Bit 2
Address Bit 1
Address Bit 0
Data Bit 0
Data Bit 1
Data Bit 2
Power Supply Ground
Data Bit 3
Data Bit 4
Data Bit 5
Data Bit 6
Data Bit 7
Chip Enable (Active Low)
Address Bit 10
Output Enable (Active Low)
Address Bit 11
Address Bit 9
Address Bit 8
Address Bit 13
Program Enable (Active Low)
Power Supply + 5 Vdc

pp

Ai2
A7
A6
A5
A4
A3
A2
Ai
Ao
Do
D,
D2
GND
D3
D4
D5
D6
D7
/CE
Aio
/OE
An

A9
A8
Au
/PGM
V
* cc

Table 16-19. 23128 ROM Pinout

629

630

COMMODORE 128

VPP

n 1 2

fl7

R6

0 fl 5

^ -^

VCC
/PGM

2 3 1. 2

O
o

fl 1 3

fl 8

fi9

0
0

fl 4

fl 1 1

fl3

/ 0 E

fl 2

fllC

fl 1

/ C E

fl 0

D 7

D0

DC

D 1

D 5

D2

D 4

GND

D 3

CH>
o
O

Figure 16-26. The 23128 ROM Chip (BASIC, Kernal, Editor and External Function
ROMs)

C128 HARDWARE SPECIFICATIONS

THE 23256 ROM

PIN

NAME

DESCRIPTION

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

v p p

Programming Voltage
Address Bit 12
Address Bit 7
Address Bit 6
Address Bit 5
Address Bit 4
Address Bit 3
Address Bit 2
Address Bit 1
Address Bit 0
Data Bit 0
Data Bit 1
Data Bit 2
Power Supply Ground
Data Bit 3
Data Bit 4
Data Bit 5
Data Bit 6
Data Bit 7
Chip Enable-Program Enable (Active Low)
Address Bit 10
Output Enable (Active Low)
Address Bit 11
Address Bit 9
Address Bit 8
Address Bit 13
Address Bit 14
Power Supply + 5 Vdc

Aw
A7
A6
A5
A4
A3
A2
A,
Ao
Do
D,
D2
GND
D3
D4
D5
D6
D7
/CE-/PGM
Aio
/OE
An

A9
A8
A, 3
A14
v
V
cc

Table 16-20. 23256 ROM Pinout (Internal or External Function ROMs)

631

632

COMMODORE 128

jVPP

VCC

. fl l 2

n i L[
Rl

,fl7

fl 1 3

fl8

o .fl6
o i

f l 5

fl 9
o 1 1
M

,fl4

fl 3

/ 0 E

fl 2

fllG

p 11i

/PGM

flG

D 7

0 0

DC

01

D 5

0 2

D4

GND

D 3

<H-

Figure \6-27. The 23256 ROM Chip

-^>

C128 HARDWARE SPECIFICATIONS

THE SERIAL BUS

The C128 Serial Bus is an improved version of the C64 serial bus. This bus uses
IEEE-488-type addressing, thus maintaining software compatibility between the consumer market serial devices and the CBM IEEE-488 parallel devices. The C128
improves this bus by allowing communication at much greater speeds with specially
designed peripherals, the most important being the disk drive, while still maintaining
compatibility with older, slower peripherals used by the C64. This section describes the
hardware and some of the software aspects of both the old and the new serial transmission scheme.

BUS OPERATIONS
There are three basic bus operations that take place on the serial bus, in both fast and
slow modes. The first of these is called Control. The C128 is the controller in most
circumstances. The controller of the bus is always the device that initiates protocol on
the bus, requesting peripheral devices to do one of the two other serial operations, either
Talk or Listen.
All serial bus devices can listen. A listening device is a device that has been
ordered by the controller to receive data. Some devices, such as disk drives, can talk. A
talking device is sending data to the controller. Both hardware and software drive this
bus protocol.

BUS SIGNALS
The Commodore serial bus is composed of the following signals:

SRQ (pin 1): This signal is called Service Request. The slow serial bus does
not use this line, the fast bidirectional clock line. (Not used in C64 Mode.)
GND (pin 2): Chassis ground.
ATN (pin 3): This signal is called Attention. It is used to address a device on
the bus. When requesting a device to talk to or listen, the controller brings this
signal low, creating some sort of interrupt on all serial bus devices. It then
sends out an address that will select one device on the bus. It is the controller's
responsibility to time out if a device on the bus does not respond within a
reasonable amount of time.
CLK (pin 4): This is the slow serial clock. It is used by slow serial devices,
which are software-clocked, to clock data transmitted on the serial bus.
DATA (pin 5): This is the serial data line. It is used by both slow and fast
serial devices to transmit data in sync with clock signal.
RESET (pin 6): This is the reset line, used to reset all peripherals when the
host resets.

633

634

COMMODORE 128

FAST SERIAL BUS

FAST PROTOCOL
To function as a fast talker, the system must be addressing a fast device, such as the
1571 disk drive. When addressing any device, the C128 sends a fast byte, toggling the
SQR line eight times, with the ATN line low. If the device is a fast device, it will record
the fact that a fast controller accessed it and respond with a fast acknowledge. If the
device is a slow device, no response is delivered and the C128 then assumes it is talking
with a slow device. The status of drive speed is retained until the device is requested to
untalk or unlisten, if an error occurs, or if a system reset occurs.

FAST HARDWARE
The fast serial bus, in order to achieve its speed increase, uses different hardware from
that of the slow serial bus. The slow serial bus uses several 6526 port lines to drive
ATN, CLK and DATA. Thus, clocking of the data transfers must be software-driven.
The fast serial method is to use the serial port line of a 6526 (CIA-1) to actually transfer
the serial data. This increases the transfer rate dramatically, to the point where the
transfer becomes limited more by software overhead than anything else. The actual
speed of transfer is set by the 6526 timer. Current 6526's have a minimum serial timer
value of 4, though in actual use this value is closer to 6, owing to loading. Any
advances in the 6526 would make a faster data transfer possible.
This scheme could interfere with slow serial transmissions, since the DATA line is
shared by both schemes. Thus, circuitry exists that will isolate the fast serial drivers
from the slow serial bus. Setting FSDIR to input mode is sufficient to remove any
possible fast serial interactions with the slow serial bus, other than the additional device
loading, which is not a problem at slow serial bus speeds.
In order to ensure compatibility with the C64, however, the slow serial bus cannot
interfere with the fast drivers, since these drivers are shared with the User Port and a
user port device could presumably make use of them. Once C64 mode is set, the input
direction of the interface circuitry is disabled. Thus, in C64 mode, the FSDIR bit must
be set to input to remove fast to slow interference, but slow to fast interference is
automatically removed by invoking C64 mode. There is no way to disable slow to fast
interference in C128 mode (at least not simultaneously with the elimination of fast to
slow interference).

C128 HARDWARE SPECIFICATIONS

THE EXPANSION BUS

The C128 Expansion Bus is compatible with the C64 Expansion Bus, while at the same
time allowing extended capabilities in C128 mode.

CARTRIDGE ADDITION
The C128 can use larger and more sophisticated cartridges than the C64. One of the
main reasons for this is the new banking scheme used in the C128 for external
cartridges. The C64 uses two hardware control lines, /EXROM and /GAME, to control
banking out of internal facilities and banking in of cartridge facilities. The C128 uses a
software polling method, where upon power-up it polls the cartridge, according to a
defined protocol, to determine if such a cartridge exists, and if so, what its software
priority is. Since the C128 is always free to bank between cartridges and built-in ROM,
an external application can take advantage of internal routines and naturally become an
extended part of the C128, as opposed to becoming a replacement application. See
Chapter 13 for information on the Auto Start Cartridge ROM sequence.
The elimination of /EXROM and /GAME as hardware control lines for cartridge
identification (in C128 mode) has freed up both of these lines for extended functioning.
Both of the lines appear as bits in the MMU Mode Configuration Register, and are both
input and output ports. Neither has a dedicated function other than general cartridge
function expansion, and lend themselves to act as latched banking lines or input sense
lines. Of course, neither can be asserted on C128 power-up or C64 mode will automatically be set.

DMA CAPABILITY
The C128 expansion bus supports DMAs in a fashion similar to that of the C64. A C64
DMA is achieved by pulling the /DMA pin on the expansion bus low. Immediately after
this happens, the RDY and AEC lines of the processor are brought low. This can neatly
shut down the processor, but it can also cause problems, depending on what the
processor is doing at the time. The RDY input of an 8502 series processor, when brought
low, will halt the processor of the next $ 1 cycle, leaving the processor's address lines
reflecting the current address being fetched. However, if the processor is in a write cycle
when RDY is brought low, it will ignore RDY until the next read cycle. Thus, in the
C64, a /DMA input occurring during a write cycle will tri-state the processor's address
and data bus, but not stop it until up to three cycles later when the next read cycle
occurs. The write cycles following the /DMA input do not actually write, causing
memory corruption and often processor fatality when the /DMA line is released. Any
/DMA input during <52 is a potentially fatal DMA.
If a proper /DMA is asserted, the C64 tri-states and shuts down, allowing the
DMA source complete access to the processor bus. Such a DMA source must monitor
the <t>2 and BA outputs, as it must tri-state when the VIC is on the bus, and it must
completely DMA when a VIC DMA is called for. The VIC chip always has the highest

635

636

COMMODORE 128

DMA priority. When on the bus, the DMA source has access to RAM, ROM and I/O
in the C64 scheme. A proper DMA shutdown is usually achieved via some C64 software
handshaking with the DMA source.
The C128 system uses a similar DMA scheme. When the /DMA input goes low,
the RDY input to the 8502, the AEC input to the 8502, and the /BUSRQST input to the
Z80 immediately go low. Additionally, the gated AEC signal, GAEC, goes low,
causing the MMU to go immediately to its VIC CYCLE MODE, and the Z80 Data Out
buffer to tri-state. The DMA causes the Address to the Shared Address buffer to reverse
direction, and the Translated Address to the Address buffer to be enabled, giving the
external DMA source complete access to the processor address bus. The PLA is still
looking at ungated AEC and as such will allow access to I/O devices, RAM and ROM.
There can be no access to the MMU; thus for C128 memory mapping the memory map
must be set up before being DMA'ed. For C64 mode, memory mapping is done by the
8502 processor port lines and by the external /EXROM and /GAME. Since the 8502
ports will be inaccessible by a DMA source, only the C64 map changes based upon
/EXROM and /GAME can be made during a DMA. This is the same as in a C64 unit.
All DMA sources, as with the C64, must yield to the VIC during $ 0 or BA low. The
C128 can perform a destructive DMA as easily as the C64. In order to use DMA's, the DMA
source will most likely have to cooperate with a C128 mode program, allowing it to
handshake with a DMA source to effect DMA's nondestructively.

C128 HARDWARE SPECIFICATIONS

EXPANSION BUS PINOUT

PIN

NAME

DESCRIPTION

1
2
3
4
5
6
7
8
9
10
11

GND
+ 5V
+ 5V
/IRQ
R/W
DCLOCK
I/Oj
/GAME
/EXROM
I/0 2
/ROML

12
13

BA
/DMA

14
15
16
17
18
19
20
21
22
A
B

D7
D6
D5
D4
D3
D2
Di
Do
GND
GND
/ROMH

C
D
E
F
H
J
K
L
M
N
P
R
S
T
U
V

/RESET
/NMI
lMHz
TA15
TAj4
TA13
TA12
TA
TAio
TA9
TA8
SA7
SA6
SAs
SA4
SA3
SA2
SA!
SAo
GND

System Ground
System Vcc
System Vcc
Interrupt Request
System Read Write Signal
8.18 MHz Video Dot Clock
I/O Chip Select: $DE00-$DEFF, Active Low
Sensed for Memory Map Configuration
Sensed for Memory Map Configuration
I/O Chip Select: $DFOO-$DFFF, Active Low.
External ROM Chip Select, $8000-$BFFF in C128 Mode
($8000-$9FFF in C64 mode)
Bus Available Output
Direct Memory Access Input (see caution on DMA capability
on p. 636)
Data Bit 7
Data Bit 6
Data Bit 5
Data Bit 4
Data Bit 3
Data Bit 2
Data Bit 1
Data Bit 0
System Ground
System Ground
External ROM Chip Select, $C000-$FFFF in C128 Mode
($C000-$FFFF in C64 mode)
System Reset Signal
Non-Maskable Interrupt Request
System lMHz 4>0 Clock
Translated Address Bit 15
Translated Address Bit 14
Translated Address Bit 13
Translated Address Bit 12
Translated Address Bit 11
Translated Address Bit 10
Translated Address Bit 9
Translated Address Bit 8
Shared Address Bit 7
Shared Address Bit 6
Shared Address Bit 5
Shared Address Bit 4
Shared Address Bit 3
Shared Address Bit 2
Shared Address Bit 1
Shared Address Bit 0
System Ground

w
X
Y
Z

Table 16-21. Expansion Bus Pinout

637

638

COMMODORE 128

THE VIDEO INTERFACE

The C128 VIC video interface hardware allows the connection of a standard NTSC or
PAL commercial television and/or a color monitor. The monitor can accept either a
composite video signal or separate chroma and luminance/sync signals in addition to an
audio signal. This output is very similar to the output in later revision C64 units.
The C128 also provides 80-column video interfacing. The available 80-column
display is RGBI and monochrome, able to interface to most NTSC- or PAL-compatible
RGBI TYPE I monitors and most 80-column-compatible NTSC or PAL monochrome
monitors.

THE VIC VIDEO INTERFACE

The following items specify the VIC video interface for 40-column display in sixteen
colors. The VIC signal is available at analog levels at the video connector and at RF
levels at the RF output.

MODULATOR SPECIFICATION
The modulator provides a broadcast-type RF signal carrying the VIC composite video
and audio signals. The NTSC modulator is switchable between channels 3 and 4 to help
minimize local broadcast interference. The signal generated by the RF modulator
complies with the FCC ruling concerning FCC Class B, TV interface devices. The RF
output is accessible via a standard RCA-type phono/video jack.

MONITOR OUTPUT
The VIC video output provides the signals shown in Table 16-22.

SIGNAL

LEVEL

IMPEDENCE

DC OFFSET

Luminance/Syne
Chroma
Composite
Audio

lVp-p
lVp-p
lVp-p
1 V p-p

75 a

0.5 V
0.5 V
0.5 V

75 ft
75 n
l K ft

Table 16-22. VIC Video Output Signals

VIDEO CONNECTOR PINOUT

The VIC video connector exists physically as an eight-pin DIN connector. It provides
the signals shown in Table 16-23.

C128 HARDWARE SPECIFICATIONS

PIN

SIGNAL

1
2
3
4
5
6
7
8

Luminance/Sync
Ground
Audio Out
Composite
Audio In
Chroma
N.C.
N.C.

Table 16-23. Video Connector Signals

THE 8563 VIDEO INTERFACE

The following items specify the 8563 video interface for 80-column display in sixteen
colors. The 8563 signal is available at digital levels for RGBI and at a three-level
derived analog for black and white composite video.

MONITOR OUTPUT
Table 16-24 shows the signals provided by the 8563 output.

SIGNAL

LEVEL

IMPEDENCE

Red
Green
Blue
Intensity
HSync
VSync
Composite
Full Intensity
Half Intensity
Sync

TTL
TTL
TTL
TTL
TTL
TTL

TTL
TTL
TTL
TTL
TTL
TTL
75 n

2.0 V
1.5 V
0.5 V

Table 16-24. 8563 Output Signals

VIDEO CONNECTOR PINOUT

The 8563 video connector is an IBM-style D9 connector, providing the signals shown in
Table 16-25.

639

640

COMMODORE 128

PIN

SIGNAL

1
2
3
4
5
6
7
8
9

Ground
Ground
Red
Green
Blue
Intensity
Monochrome (non-standard)
Horizontal Sync
Vertical Sync

Table 16-25. 8563 Video Connector Pinout

THE KEYBOARD
The C128 Keyboard is an advance over the standard C64 keyboard, while still maintaining full compatibility. It has several extra keys that are used in C128 mode, but not in
C64 mode. It features a numeric keypad, a H E L P key, extended function keys, a
true C A P S L O C K key, and a 4 0 / 8 0 column switch key, all of which are
strobed by the VIC chip or tied to dedicated 8502 or MMU I/O lines.

CONNECTOR PINOUT
The C128 keyboard is designed to be connected by one 12- and one 13-pin internal
single-in-line connector for the unit with a built-in keyboard. Table 16-26 illustrates
both connections.

C128 HARDWARE SPECIFICATIONS

D-TYPE

SIGNAL

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

Ground
Key
Restore
+ 5V
Row 3
Row 6
Row 5
Row 4
Row 7
Row 2
Row 1
Row 0
Column 0
Column 6
Column 5
Column 4
Column 3
Column 2
Column 1
Column 7
Ko
Ki
K2
40/80
Alpha Lock

Table 16-26. The Keyboard Connector Pinout

641

642

COMMODORE 128

THE CI28 KEYBOARD TABLE

C0
PIN13

C1

C2

C3

C4

C5

PIN19 PIN18 PIN17 PIN16 PIN15

C6

C7

K0

K1

K2

GND

PIN14

PIN20

PIN21

PIN22

PIN23

PIN-1

HELP

ESC

ALT

< -

CTRL

)
9

lb

R0
PIN12

INS
DEL

#
3

%
5

Rl
PIN11

RET

R2
PIN10

t
I

R3
PIN5

F8
F7

$
4

&
6

(
8

R4
PIN8

F2
Fl

R5
PIN7

F4
F3

R6
PIN6

F6
F5

7T

LEFT

<

R7
PIN9

< -

SHIFT

(LOCKING)

(LOCKING)

(LOCKING)

>

CLR
HOM

TAB
2

RIGHT SPACE
SHIFT BAR

LINE
FEED
ENTER

i
4

RUN

STOP

NO
SCRL

NMI
PIN3

40/80
PIN24

40/80
pDSPLY

P6510
PIN25

CAPS
LOCK

NOTE: Pins R0 through R7 pertain to the keyboard row values for the keyboard SCAN.
These pins correspond to bits 0 through 7 of location 56321 ($DC01).
Pins C0 through C7 are the keyboard's column values, which correspond to bits 0
through 7 of location 56320 ($DC00).
Pins K0 through K2 pertain to the C128 keyboard control register bit, 0 through 2 of
location 53295 ($D02F).

APPENDIXES
Appendix A - BASIC Language Error Messages

644

Appendix B - DOS Error Messages

648

Appendix C - Connectors/Ports for Peripheral

Equipment

652

Appendix D - Screen Display Codes

658

Appendix E - ASCII and CHR$ Codes

660

Appendix F - Screen and Color Memory Maps

663

Appendix G - Derived Trigonometric Functions

665

Appendix H - Control and Escape Codes

666

Appendix I - BASIC 7.0 Abbreviations

670

Appendix J - Disk Command Summary

674

Appendix K

Part l-Commodore 128 CP/M

676

Part ll-Calling CP/M BIOS, 8502 BIOS, and CP/M

User Functions in Z80 Machine Language

702

Part lll-The CP/M System Memory Map

709

Appendix L - Commodore 128 System Schematics

721

643

644

COMMODORE 128

APPENDIX A

BASIC LANGUAGE
ERROR MESSAGES
The following error messages are displayed by BASIC. Error messages can also be
displayed with the use of the ERR$() function. The error numbers below refer only to
the number assigned to the error for use with the ERR$() function.
ERROR NAME

DESCRIPTION

TOO MANY FILES

There is a limit of ten files OPEN at one

time.

FILE OPEN

An attempt was made to open a file using

the number of an already open file.

FILE NOT OPEN

The file number specified in an I/O statement must be opened before use.

FILE NOT FOUND

Either no file with that name exists (disk)

or an end-of-tape marker was read (tape).

DEVICE NOT PRESENT

NOT INPUT FILE

An attempt was made to GET or INPUT

data from a file that was specified as output
only.

NOT OUTPUT FILE

An attempt was made to send data to a file

that was specified as input only.

MISSING FILE NAME

File name missing in command.

ILLEGAL DEVICE NUMBER

An attempt was made to use a device improperly (SAVE to the screen, etc.).

10

NEXT WITHOUT FOR

Either loops are nested incorrectly, or there

is a variable name in a NEXT statement
that doesn't correspond with one in FOR.

11

SYNTAX

A statement not recognized by BASIC. This

could be because of a missing or extra
parenthesis, a misspelled key word, etc.

ERROR #

The required I/O device is not available or

buffers deallocated (cassette). Check to make
sure the device is connected and turned
on.

APPENDIXES

ERROR N A M E

DESCRIPTION

12

RETURN WITHOUT GOSUB

A RETURN statement was encountered

when no GOSUB statement was active.

13

OUT OF DATA

A READ statement is encountered without

any data left to READ.

14

ILLEGAL QUANTITY

15

OVERFLOW

The result of a computation is larger than

the largest number allowed (1.701411834E
+ 38).

16

OUT OF MEMORY

Either there is no more room for program

code and/or program variables, or there are
too many nested DO, FOR or GOSUB statements in effect.

17

UNDEF'D STATEMENT

A referenced line number doesn't exist in

the program.

18

BAD SUBSCRIPT

The program tried to reference an element

of an array out of the range specified by
the DIM statement.

19

REDIM'D ARRAY

An array can only be DIMensioned once.

20

DIVISION BY ZERO

Division by zero is not allowed.

21

ILLEGAL DIRECT

INPUT, GET, INPUT#, G E T # and GETKEY statements are allowed only within a
program.

22

TYPE MISMATCH

This error occurs when a numeric value is

assigned to a string variable or vice versa.

23

STRING TOO LONG

A string can contain up to 255 characters.

24

FILE DATA

Bad data read from a tape or disk file.

25

FORMULA TOO COMPLEX

The computer was unable to evaluate this

expression. Simplify the expression (break
into two parts or use fewer parentheses).

26

CAN'T CONTINUE

The CONT command does not work if the

program was not RUN, if there was an
error, or if a line has been edited.

27

UNDEF'D FUNCTION

A user-defined function that was never defined was referenced.

ERROR #

A number used as the argument of a function or statement is outside the allowable

range.

645

646

COMMODORE 128

ERROR NAME

DESCRIPTION

28

VERIFY

The program on tape or disk does not match

the program in memory.

29

LOAD

There was a problem loading. Try again.

30

BREAK

The STOP command was issued in a program or the STOP key was pressed
to halt program execution.

31

CAN'T RESUME

A RESUME statement was encountered

without a TRAP statement in effect.

32

LOOP NOT FOUND

The program has encountered a DO statement and cannot find the corresponding
LOOP.

33

LOOP WITHOUT DO

LOOP was encountered without a DO statement active.

34

DIRECT MODE ONLY

This command is allowed only in direct

mode, not from a program.

35

NO GRAPHICS AREA

A command (DRAW, BOX, etc.) to create

graphics was encountered before the
GRAPHIC command was executed.

36

BAD DISK

37

BEND NOT FOUND

38

LINE NUMBER TOO LARGE

39

UNRESOLVED REFERENCE

An error has occurred in renumbering a

BASIC program. A line number referred to
be a command (e.g., GOTO 999) does not
exist. Therefore, the renumbering was not
performed.

40

UNIMPLEMENTED
COMMAND

A command not supported by BASIC 7.0

was encountered.

ERROR #

An attempt failed to HEADER a diskette,

because the quick header method (no ID)
was attempted on an unformatted diskette
or the diskette is bad.
The program encountered an " I F . . . THEN
BEGIN" or 'TF . . . THEN . . . ELSE
BEGIN" construct, and could not find a
BEND keyword to match the BEGIN.
An error has occurred in renumbering a
BASIC program. The given parameters result in a line number greater than 63999
being generated; therefore, the renumbering
was not performed.

APPENDIXES

ERROR #

ERROR NAME

DESCRIPTION

41

FILE READ

An error condition was encountered while

loading or reading a program or file from
the disk drive (e.g., opening the disk drive
door while a program was loading).

647

648

COMMODORE 128

APPENDIX B

DOS ERROR MESSAGES

The following DOS error messages are returned through the DS and DS$ variables. The
DS variable contains just the error number, and the DS$ variable contains the error
number, the error message, and any corresponding track and sector number. NOTE:
Error message numbers less than 20 should be ignored with the exception of 01, which
gives information about the number of files scratched with the SCRATCH command.
ERROR
NUMBER

ERROR M E S S A G E AND DESCRIPTION

20

READ ERROR (block header not found)

The disk controller is unable to locate the header of the requested data
block. Causes: an illegal sector number, or the header has been destroyed.

21

READ ERROR (no sync character)

The disk controller is unable to detect a sync mark on the desired track.
Causes: misalignment of the read/write head, no diskette, or an unformatted or improperly seated diskette. Can also indicate a hardware failure.

22

READ ERROR (data block not present)

The disk controller has been requested to read or verify a data block that
was not properly written. This error occurs in conjunction with the BLOCK
commands and can indicate an illegal track and/or sector request.

23

READ ERROR (checksum error in data block)

This error message indicates there is an error in one or more of the data
bytes. The data has been read into the DOS memory, but the checksum
over the data is in error. This message may also indicate hardware grounding problems.

24

READ ERROR (byte decoding error)

The data or header has been read into the DOS memory but a hardware
error has been created owing to an invalid bit pattern in the data byte. This
message may also indicate hardware grounding problems.

25

WRITE ERROR (write-verify error)

This message is generated if the controller detects a mismatch between the
written data and the data in the DOS memory.

26

WRITE PROTECT ON
This message is generated when the controller has been requested to write
a data block while the write protect switch is depressed. This is caused by
using a diskette with a write protect tab over the notch or a notchless diskette.

APPENDIXES

ERROR
NUMBER

ERROR MESSAGE AND DESCRIPTION

27

READ ERROR
This message is generated when a checksum error has been detected in the
header of the requested data block. The block has not been read into DOS
memory.

28

WRITE ERROR
This error message is generated when a data block is too long and
overwrites the sync mark of the next header.

29

DISK ID MISMATCH
This message is generated when the controller has been requested to access
a diskette that has not been initialized or improperly formatted. The
message can also occur if a diskette has a bad header.

30

SYNTAX ERROR (general syntax)

The DOS cannot interpret the command sent to the command channel.
Typically, this is caused by an illegal number of file names, or patterns
that are illegally used. For example, two file names appear on the left side
of the COPY command.

31

SYNTAX ERROR (invalid command)

The DOS does not recognize the command. The command must start in the
first position.

32

SYNTAX ERROR (invalid command)

The command sent is longer than 58 characters. Use abbreviated disk
commands.

33

SYNTAX ERROR (invalid file name)

Pattern matching is invalidly used in the OPEN or SAVE command. Spell
out the file name.

34

SYNTAX ERROR (no file given)

The file name was left out of the command or the DOS does not recognize
it as such. Typically, a colon(:) has been left out of the command.

39

SYNTAX ERROR (invalid command)

This error may result if the command sent to the command channel
(secondary address 15) is unrecognized by the DOS.

50

RECORD NOT PRESENT

Result of disk reading past the last record through INPUT# or G E T #
commands. This message will also appear after positioning to a record
beyond end-of-file in a relative file. If the intent is to expand the file by
adding the new record (with a PRINT# command), the error message may
be ignored. INPUT# and G E T # should not be attempted after this error is
detected without first repositioning.

649

650

COMMODORE 128

ERROR
NUMBER

ERROR MESSAGE AND DESCRIPTION

51

OVERFLOW IN RECORD
PRINT# statement exceeds record boundary. Information is truncated.
Since the carriage return that is sent as a record terminator is counted in the
record size, this message will occur if the total characters in the record
(including the final carriage return) exceed the defined size of the record.

52

FILE TOO LARGE

The record position within a relative file indicates that disk overflow will
result.

60

WRITE FILE OPEN

This message is generated when a write file that has not been closed is
being opened for reading.

61

FILE NOT OPEN

A file that has not been opened in the DOS is being accessed. Sometimes
in this situation, a message is not generated; the request is simply ignored.

62

FILE NOT FOUND

The requested file does not exist on the indicated drive.

63

FILE EXISTS
The file name of the file being created already exists on the diskette.

64

FILE TYPE MISMATCH

The requested file access is not possible using files of the type named.
Reread the chapter covering that file type.

65

NO BLOCK
Occurs in conjunction with block allocation. The sector you tried to allocate
is already allocated. The track and sector numbers returned are the next
higher track and sector available. If the track number returned is 0, all
remaining higher sectors are full. If the diskette is not full yet, try a
lower track and sector.

66

ILLEGAL TRACK AND SECTOR

The DOS has attempted to access a track or a block that does not exist in
the format being used. This may indicate a problem reading the pointer to
the next block.

67

ILLEGAL SYSTEM T OR S
This special error message indicates an illegal system track or sector.

70

NO CHANNEL (available)
The requested channel is not available, or all channels are in use. A
maximum of five buffers are available for use. A sequential file requires
two buffers; a relative file requires three buffers; and the error/command
channel requires one buffer. You may use any combination of those as
long as the combination does not exceed five buffers.

APPENDIXES

ERROR
NUMBER

ERROR MESSAGE AND DESCRIPTION

71

DIRECTORY ERROR
The BAM (Block Availability Map) on the diskette does not match the
copy on disk memory. To correct this, initialize the disk drive.

72

DISK FULL
Either the blocks on the diskette are used, or the directory is at its entry
limit. DISK FULL is sent when two blocks are still available on the
diskette, in order to allow the current file to be closed.

73

DOS VERSION NUMBER (73, CBM DOS V30 1571, 00, 00)
DOS 1 and 2 are read compatible but not write compatible. Disks may be
interchangeably read with either DOS, but a disk formatted on one version
cannot be written upon with the other version because the format is
different. This error is displayed whenever an attempt is made to write
upon a disk that has been formatted in a noncompatible format. This
message will also appear after power-up or reset and is not an error in this
case.

74

DRIVE NOT READY

An attempt has been made to access the disk drive without a diskette
inserted; or the drive lever or door is open.

651

652

COMMODORE 128

APPENDIX C

CONNECTORS/PORTS FOR
PERIPHERAL EQUIPMENT
1.
2.
3.
4.
5.
6.

Power Socket
Power Switch
Reset Button
Controller Ports
Expansion Port
Cassette Port

7.
8.
9.
10.
11.
12.

Serial Port
Composite Video Connector
Channel Selector
RF Connector
RGBI Connector
User Port

10

11

12

APPENDIXES

SIDE PANEL CONNECTIONS

1.
2.
3.
4.

Power SocketThe free end of the cable from the power supply is attached here.
Power SwitchTurns on power from the transformer.
Reset ButtonResets computer (warm start).
Controller PortsThere are two Controller ports, numbered 1 and 2. Each Controller port can accept a joystick mouse or a game controller paddle. A light pen
can be plugged only into port 1, the port closest to the front of the computer. Use
the ports as instructed with the software.

CONTROLLER PORT 1
PIN

TYPE

1
2
3
4
5
6
7
8
9

JOYAO
JOYAl
JOYA2
JOYA3
POT AY
BUTTON A/LP
+ 5V
GND
POT AX

NOTE

MAX. 50mA

CONTROLLER PORT 2
PIN

TYPE

1
2
3
4
5
6
7
8
9

JOYBO
JOYBl
JOYB2
JOYB3
POT BY
BUTTON B
+ 5V
GND
POT BX

NOTE

MAX. 50mA

REAR CONNECTIONS
5.

Expansion PortThis rectangular slot is a parallel port that accepts program or

game cartridges as well as special interfaces.

653

654

COMMODORE 128

CARTRIDGE
EXPANSION PORT
PIN

TYPE

PIN

TYPE

12
13
14
15
16
17
18
19
20
21
22

BA
DMA
D7
D6
D5
D4
D3
D2
D1
D0
GND

1
2
3
4
5
6
7
8
9
10
11

GND
+ 5V
+ 5V
IRQ.
R/W
Dot Clock
I/O 1
GAME
EXROM
I/O 2
ROML

PIN

TYPE

PIN

TYPE

N
P
R
S
T
U
V
W
X
Y
Z

A9
A8
A7
A6
A5
A4
A3
A2
A1
A0
GND

A
B
C
D
E
F
H
J
K
L
M

GND
ROMH
RESET
NMI
S 02
A15
A14
A13
A12
All
A10

22 21 20 19 16 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3


'

Z v

X W V U

R P N M L

K J

E D C

B A

(view of port from the back of the C128)

6.

Cassette PortA 1530 Datassette recorder can be attached here to store programs
and information.
CASSETTE PORT
PIN

TYPE

A-1
B-2
C-3
D-4
E-5
F-6

GND
+5V
CASSETTE
CASSETTE
CASSETTE
CASSETTE

M
MOTOR
READ
WRITE
SENSE

B C

APPENDIXES

7.

Serial PortA Commodore serial printer or disk drive can be attached directly to
the Commodore 128 through this port.

SERIAL I/O PORT

PIN

1
2
3
4
5
6

8.

TYPE

SERIAL
GND
SERIAL
SERIAL
SERIAL
RESET

SRQIN
ATN IN/OUT
CLK IN/OUT
DATA IN/OUT

Composite Video ConnectorThis DIN connector supplies direct audio and composite video signals. These can be connected to the Commodore monitor or used
with separate components. This is the 40-column output connector.

(view of port while facing the rear of the C128)

COMPOSITE VIDEO CONNECTOR

PIN

1
2
3
4
5
6
7
8

TYPE

NOTE

LUM/SYNC
GND
AUDIO OUT
VIDEO OUT
AUDIO IN
COLOR OUT
NC
NC

Luminance/SYNC output

Composite signal output

Chroma signal output
No eonneetion
No connection

655

656

COMMODORE 128

9.

10.
11.

Channel SelectorUse this switch to select which TV channel (L = channel 3, H

= channel 4) the computer's picture will be displayed on when using a television
instead of a monitor.
RF ConnectorThis connector supplies both picture and sound to your television
set. (A television can display only a 40-column picture.)
RGBI ConnectorThis 9-pin connector supplies direct audio and an RGBI (Red/
Green/ Blue/Intensity) signal. This is the 80-column output.

RGBI CONNECTOR
PIN

1
2
3
4
5
6
7
8
9

12.

SIGNAL

Ground
Ground
Red
Green
Blue
Intensity
Monochrome
Horizontal Sync
Vertical Sync

User PortVarious interface devices can be attached here, including a Commodore modem.

APPENDIXES

USER I/O PORT

PIN

1
2
3
4
5
6
7
8
9
10
11
12

TYPE

NOTE

GND
+ 5V
RESET
CNT1
SP1
CNT2
SP2
PC2
SER. ATN IN
9 VAC
9 VAC
GND

PIN

TYPE

A
B
C
D
E
F
H
J
K
L
M
N

GND
FLAG2
PB0
PB1
PB2
PB3
PB4
PB5
PB6
PB7
PA2
GND
1 2

MAX. 100mA

MAX. 100mA
MAX. 100mA

NOTE

4 5 6

7 8

10 11 12

A B C

L M N

657

658

COMMODORE 128

APPENDIX D

SCREEN DISPLAY CODES

SCREEN DISPLAY CODES
40 COLUMNS
The chart below lists all the characters built into the Commodore screen character sets.
It shows which numbers should be POKEd into the VIC chip (40-column) screen
memory (location 1024 to 2023) to get a desired character on the 40-column screen.
(Remember, to set color memory, use locations 55296 to 56295.) Also shown is which
character corresponds to a number PEEKed from the screen.
Two character sets are available. Both are available simultaneously in 80-column
mode, but only one is available at a time in 40-column mode. The sets are switched by
holding down the S H I F T
and C (Commodore) keys simultaneously. The entire
screen of characters changes to the selected character set.
From BASIC, PRINT CHR$(142) will switch to upper case/graphics mode and
PRINT CHR$(14) will switch to upper/lower case mode.
Any number on the chart may also be displayed in reverse. The reverse character
code can be obtained by adding 128 to the values shown.
SET 1

POKE I

SET 1

SET 2

POKE

POKE

SET 1

SET 2

14

28

15

16

]
T

29

30

17

31

18

SET 2

19

SPACE |
!

32
33

"

34

20

21

35

22

36

23

37

10

24

&

38

11

25

'

39

12

26

13

(
)

40

27

41

APPENDIXES

SET 1

SET 2

POKE | SET 1

42

43

44
45

SET 2

46

47

48

49

50

51

52

53

54

55

56

57

POKE | SET 1

72

73

74

75

76

77

78

ffl

107

79

108

80

109

81

82

110

83

84

85

114

86

a:

115

87

88

89

90

59

<

60

61

ffl

>

62

ffl

91

63

92

64

93

65

66

67

68

69

70

SPACE

E
H
n

H
&

100

71

58

POKE

R
o

SET 2

94

H
B

101
102
103
104
^

106

111
112
113

116
117
118

n
H
B

105

119
120
121
I0 |

122
123

95

96

125

97

126

98

124

127

99

Codes from 128-255 are reversed images of codes 0-127.

659

660

COMMODORE 128

APPENDIX E
ASCII A N D CHR$ CODES
This appendix shows you what characters will appear if you PRINT CHR$(X), for all
possible values of X. It also shows the values obtained by typing PRINT ASC ( " x " ) ,
where x is any character that can be displayed. This is useful in evaluating the character
received in a GET statement, converting upper to lower case and printing characterbased commands (such as switch to upper/lower case) that could not be enclosed in
quotes.

PRINTS

CHR$

CASE

m22Mk
CLR
I HOME
ffBl
Q

^ ^ |
^ ^ ^ M

69

47

70

25

48

71

26

49

72

27

50

73

jJJ^

28

51

74

gg

29

52

75

^jj^

30

53

76

^jjj^
I

SPACE

31

54

77

32

55

78

33

56

79

11

'

34

57

80

12

35

58

81

13

36

59

82

14

37

<1

60

83

15

&

38

61

84

39

62

85

40

63

86

64

87
88

17

S
w i

46

24

16

fi^

CHR$

10

lOWtH

PRINTS

CHR$

23

ENABLESQQIQ9

swnoM^H

PRINTS

DlSABlESQQQ8

; R E T U R N ^ ^ H

CHR$

PRINTS

(
)

41

19

42

65

20

43

66

89

44

67

90

45

68

91

18

21
22

APPENDIXES

PRINTS

CHR*

92

93

94

95

B
a
m
B
B

B
D

PRINTS
"

Q
B

96

97

ffl

98
99
100

D
m

101
102

CMR$

PRINTS

115

f4

138

116

f6

139

117

f8

140

CHR$

PRINTS

nr
n

J22JJ522EJJl41

118

SWITCH TO wwcrn
119 IIupp[R CAseHkfil
143

120
121

Qk

144

122

i l

145

123

^%j

146

124

J ^ J

^47

125

103

126

Wf
Brown

104

127

Lt. R e d

161

162

164
165

166

167

163

168
169

170

148

ffl

171

149

172

150

173

Dk. G r a y 151

174

Gray

152

175

176

105

128

106

O r a n g e 129

107

130

Lt. G r e e n i 5 3

108

131

Lt. B l u e

154

109

132

Lt. G r a y

155

CHR$

B
B

177
178

110

f1

133

JQ^

156

111

f3

134

J ^

157

112

f5

135

113

f7

136

114

f2

137

g g g

CHRS

PRINTS

186

188

190

187

189

191

PRINTS

CHR>

184

185

CODES
CODES
CODE

PRINTS

192-223
224-254
255

fi

BBk

SAME AS
SAME AS
SAME AS

ffl

158

159

160

CMR$

179
180
181
182

183

PRINTS

CHR$

96-127
160-190
126

661

672

COMMODORE 128

NOTE: The 80-column (RGBI) output has three colors that are different
from the 40-column (composite video) color output. This means that the
character string codes that represent color codes for these three colors are
used differently depending on which video output is used. The following
character string codes represent these colors in each video output.

CHR$

40-COLUMN (VIC COMPOSITE)

8O-COLUMN (8563 RGBI)

129
149
151

Orange
Brown
Dark Gray

Dark Purple
Dark Yellow
Dark Cyan

APPENDIXES

APPENDIX F

SCREEN A N D COLOR MEMORY MAPS

CI28 MODE, 40-COLUMN
A N D C64 MODE
The maps below display the memory locations used in 40-column mode (C128 and C64)
for identifying the characters on the screen as well as their color. Each map is separately
controlled and consists of 1000 positions.
The character displayed on the maps can be controlled directly with the POKE
command.

V I C CHIP (40-COLUMN) SCREEN MEMORY MAP

COLUMN
20

55335

r~
:..j:

:B

r f W

__^_l^ U

J i: ii i lt- J^^

"1
_i
. .-. j-. - . . - _ ^ ,
i
.
j
T
T
!
.1 .
~j~H
n
ri__4 1 M
' ! ^
|
it
l
.
_
L
.
.| r
\
TI , T
^.. 1
.
L
:
<~
I ~~ ";
h"
h
I
j

i
j_i
|--v-^
+
^
w
H
i
~^"' i
i
r
*

r
^
"
i
- 41
ir i-T-- -i - + + - t _L4_
r^
. , , . i
L_L
^~T
^_, 4- t f t
, T ^
H
i
i ,
'
*r~ ^~r
T
TT
^
T ^ ~1
f^i
i ~r^
~T~M
i
r
~*H
, ii
^
i
i

^ -

t
56295

The Screen Map is POKEd with a Screen Display Code value (see Appendix D).
For example:
POKE 1024, 13 (from BANK 0 or 15)
will display the letter M in the upper-left corner of the screen.

663

670

COMMODORE 128

V I C C H I P (40-COLUMN) COLOR MEMORY MAP

COLUMN
20
1063

I
10241064
1104
1144
1184
1224
1264
1304
1344
1384
1424
1464
1504
1544
1584
1624
1664
1704
1744
1784
1824
1864
1904
1944
1984

2023

If the color map is POKEd with a color value, this changes the character color. For
example:
POKE 55296,1 (from BANK 15)
will change the letter M inserted above from light green to white.

COLOR CODES40 COLUMNS

0
1
2
3
4
5
6
7

Black
White
Red
Cyan
Purple
Green
Blue
Yellow

8
9
10
11
12
13
14
15

Orange
Brown
Light Red
Dark Gray
Medium Gray
Light Green
Light Blue
Light Gray

Border Control Memory 53280

Background Control Memory 53281

APPENDIXES

APPENDIX G

DERIVED TRIGONOMETRIC
FUNCTIONS
FUNCTION

BASIC EQUIVALENT

SECANT
COSECANT
COTANGENT
INVERSE SINE
INVERSE COSINE

SEC(X) = l/COS(X)
CSC(X) = l/SIN(X)
COT(X) = l/TAN(X)
ARCSIN(X) = ATN(X/SQR(-X*X + 1))
ARCCOS(X) = -ATN(X/SQR
( - X * X + 1)) +77/2

INVERSE SECANT
INVERSE COSECANT
INVERSE COTANGENT
HYPERBOLIC SINE
HYPERBOLIC COSINE
HYPERBOLIC TANGENT
HYPERBOLIC SECANT
HYPERBOLIC COSECANT
HYPERBOLIC COTANGENT
INVERSE
INVERSE
INVERSE
INVERSE

HYPERBOLIC
HYPERBOLIC
HYPERBOLIC
HYPERBOLIC

SINE
COSINE
TANGENT
SECANT

INVERSE HYPERBOLIC COSECANT

INVERSE HYPERBOLIC COTANGENT

ARCSEC(X) - ATN(X/SQR(X*X-1))
ARCCSC(X) = ATN(X/SQR(X*X-1))
+ (SGN(X)-l)*Tr/2
ARCCOT(X) = -ATN(X) + 77/2
SINH(X) = (EXP(X)-EXP(-X))/2
COSH(X) = (EXP(X) + EXP(-X))/2
TANH(X) = -EXP(-X)/(EXP(X) + EXP
(-X))*2 + 1
SECH(X) = 2/(EXP(X) + EXP(-X))
CSCH(X) - 2/(EXP(X)-EXP(-X))
COTH(X) = EXP(-X)/(EXP(X)
-EXP(-X))*2 + 1
ARCSINH(X) - LOG(X + SQR(X*X + 1))
ARCCOSH(X) = LOG(X + SQR(X*X-1))
ARCTANH(X) = LOG(l 4- X)/(l-X))/2
ARCSECH(X) = LOG(SQR
(-X*X 4-1) + l/X)
ARCCSCH(X) = LOG(SGN(X)*SQR
(X*X + l)/X)
ARCCOTH(X) - LOG((X + l)/(x-l))/2

665

666

COMMODORE 128

APPENDIX H

CONTROL AND ESCAPE CODES

CONTROL CODES
The table below lists the control codes used by the Commodore 128. The print codes
in the first column are used in PRINT statements. The key codes in the second
column are the sequence of keys pressed to perform specific controls. Hold down
the C O N T R O L key (or the key specified on the left in the key code column)
and strike the key specified to the right in the key code column.

PRINT
CODES

KEY CODES
EFFECTIVE
IN MODE:

(CHR$)

KEY SEQUENCE

FUNCTION

CHR$(2)
CHR$(5)
CHR$(7)
CHR$(8)
CHR$(9)

CTRL
CTRL
CTRL
CTRL
CTRL

B
2 or CTRL E
G
H
I

CHR$(10)
CHR$(11)
CHR$(12)
CHR$(13)

CTRL
CTRL
CTRL
CTRL

J
K
L
M

CHR$(14)

CTRL N

CHR$(15)
CHR$(17)
CHR$(18)

CTRL 0
CRSR DOWN/CTRL
Q
CTRL 9 or CTRL R

CHR$(19)

HOME

Underline (80)
Set character color to white
Produce bell tone
Disable character set change
Enable character set change
Move cursor to next set tab
position
Line feed
Enable character set change
Disable character mode change
Send a carriage return and line
feed to the computer and enter a
line of BASIC
Set character set to upper/lower
case
Turn flash on (80)
Move the cursor down one
row
Cause characters to be printed in
reverse field
Move the cursor to the home position (top left) of the display (the
current window)

NOTE: (40) - 40-column screen only.

(80) = 80-column screen only.

C64

C128

y
/

/
j

/
/
/
j

/
/

APPENDIXES

PRINT
CODES

KEY CODES
EFFECTIVE
IN MODE:

(CHR$)

KEY SEQUENCE

FUNCTION

CHR$(20)

DEL or CTRL T

Delete last character typed and

move all characters to the right
of the deleted character one space
to the left

CHR$(24)
CHR$(27)
CHR$(28)

CTRL X, CTRL TAB

or O TAB
ESC or CTRL[
CTRL 3 or CTRL

CHR$(29)

CRSR or CTRL]

CHR$(30)

CTRL 6 or CTRL

CHR$(31)

CTRL 7 or CTRL =

CHR$(34)
CHR$(129)

Ol

CHR$(130)
CHR$(131)

CHR$(133)
CHR$(134)
CHR$(135)
CHR$(136)
CHR$(137)
CHR$(138)
CHR$(139)
CHR$(140)
CHR$(141)

CHR$(142)
CHR$(143)

F1
F3
F5
F7
F2
F4
F6
F8
SHIFT RETURN,
CTRL ENTER,
O ENTER or
& RETURN

Tab set/clear
Send an ESC character
Set character color to red (40)
and (80)
Move cursor one column to the
right
Set character color to green (40)
and (80)
Set character color to blue (40)
and (80)
Print a double quote on screen
and place editor in quote mode
Set character color to orange (40);
dark purple (80)
Underline off (80)
Run a program. This CHR$ code
does not work in PRINT CHR$
(131), but works from keyboard
buffer
Reserved CHR$ code for F1 key
Reserved CHR$ code for F3 key
Reserved CHR$ code for F5 key
Reserved CHR$ code for F7 key
Reserved CHR$ code for F2 key
Reserved CHR$ code for F4 key
Reserved CHR$ code for F6 key
Reserved CHR$ code for F8 key
Send a carriage return and line
feed without entering a BASIC
line
Set the character set to upper
case/graphic
Turn flash off (80)

N O T E : (40) = 40-column screen only.

(80) = 80-column screen only.

C64

C12

y
y

j
j
v/
v/

v/
v/

y
y

y
y

v/
j

v/

v/

j
j

667

668

COMMODORE 128

PRINT
CODES

KEY CODES
EFFECTIVE
IN MODE:

(CHR$)

KEY SEQUENCE

FUNCTION

CHR$(144)

CTRL 1

CHR$(145)

CRSR UP

CHR$(146)
CHR$(147)

CTRL 0
CLEAR HOME

CHR$(148)

INST

CHR$(149)

CHR$(150)

Set character color to black (40)

and (80)
Move cursor or printing position
up one row
Terminate reverse field display
Clear the window screen and
move the cursor to the top-left
position
Move character from cursor
position end of line right one
column
Set character color to brown (40);
dark yellow (80)
Set character color to light red
(40) and (80)
Set character color to dark gray
(40); dark cyan (80)
Set character color to medium
gray (40) and (80)
Set character color to light green
(40) and (80)
Set character color to light blue
(40) and (80)
Set character color to light gray
(40) and (80)
Set character color to purple (40)
and (80)
Move cursor left by one column
Set character color to yellow (40)
and (80)
Set character color to cyan (40);
light cyan (80)

CHR$(151)

CHR$(152)

CHR$(153)

CHR$(154)

CHR$(155)

CHR$(156)

CTRL 5

CHR$(157)
CHR$(158)

CRSR LEFT
CTRL 8

CHR$(159)

or CTRL 4

NOTE: (40) = 40-column screen only.

(80) = 80-column screen only.

C64

C128

y
j

j
j

J
J

v/

J
/

v/
/

v/

J
v/

/y

APPENDIXES

ESCAPE CODES
This table lists the key sequences for the ESCape functions available on the Commodore
128. ESCape sequences are entered by pressing and releasing the E S C key, followed by pressing the key listed in the right column.

ESCAPE FUNCTION

SEQUENCE KEY

Cancel quote, reverse, flash

ESC O

Erase to end of current line

Erase to start of current line
Clear to end of screen

ESCQ
ESC P
ESC @

Move to start of current line

Move to end of current line

ESC J
ESC K

Enable auto-insert mode

Disable auto-insert mode

ESC A
ESC C

Delete current line

Insert line

ESC D
ESC I

Set default tab stop (8 spaces)

Clear all tab stops

ESC Y
ESC Z

Enable scrolling
Disable scrolling

ESC L
ESC M

Scroll up
Scroll down

ESC V
ESC W

Enable bell (by control-G)

Disable bell

ESC G
ESC H

Set cursor to nonflashing mode

Set cursor to flashing mode

ESC E
ESC F

Set bottom right corner of screen window at cursor position

Set top left corner of screen window at cursor position

ESC B
ESC T

Swap 40/80 column display output device

ESC X

The following ESCape sequences have an effect on an 80-column screen only.

ESCAPE FUNCTION

SEQUENCE KEY

Change to underlined cursor (80)

Change to block cursor (80)

ESC U
ESC S

Set screen to reverse video (80)

Return screen to normal (non reverse video) state (80)

ESC R
ESC N

669

670

COMMODORE 128

APPENDIX I
BASIC 7.0 ABBREVIATIONS
NOTE: The abbreviations below operate in upper case/graphics mode. Press the letter
key(s) indicated, then hold down the S H I F T
key and press the letter key following the word SHIFT.

KEYWORD

ABS
APPEND
ASC
ATN
AUTO
BACKUP
BANK
BEGIN
BEND
BLOAD
BOOT
BOX
BSAVE
BUMP
CATALOG
CHAR
CHR$
CIRCLE
CLOSE
CLR
CMD
COLLECT
COLLISION
COLOR
CONCAT
CONT
COPY
COS
DATA
DEC
DCLEAR
DCLOSE
DEF FN
DELETE
DIM

ABBREVIATION

A SHIFT B
A SHIFT P
A SHIFT S
A SHIFT T
A SHIFT U
BA SHIFT C
B SHIFT A
B SHIFT E
BE SHIFT N
B SHIFT L
B SHIFT O
none
B SHIFT S
B SHIFT U
C SHIFT A
CH SHIFT A
C SHIFT H
C SHIFT I
CL SHIFT O
C SHIFT L
C SHIFT M
COLL SHIFT E
COL SHIFT L
COL SHIFT O
C SHIFT 0
none
CO SHIFT P
none
D SHIFT A
none
DCL SHIFT E
D SHIFT C
none
DE SHIFT L
D SHIFT I

APPENDIXES

KEYWORD

DIRECTORY
DLOAD
DO
DOPEN
DRAW
DS
DS$
DSAVE
DVERIFY
EL
END
ENVELOPE
ER
ERR$
EXIT
EXP
FAST
FETCH
FILTER
FOR
FRE
FNXX
GET
GETKEY
GET#
GOSUB
G064
GOTO
GRAPHIC
GSHAPE
HEADER
HELP
HEX$
IF . . . GOTO
IF . . . THEN . . . ELSE
INPUT
INPUT#
INSTR
INT
JOY
KEY
LEFT$
LEN
LET
LIST
LOAD
LOCATE
LOG

ABBREVIATION

DISHIFT R
D SHIFT L
none
D SHIFT 0
D SHIFT R
none
none
D SHIFT S
D SHIFT V
none
none
E SHIFT N
none
E SHIFT R
EX SHIFT I
E SHIFT X
none
F SHIFT E
F SHIFT I
F SHIFT 0
F SHIFT R
none
G SHIFT E
GETK SHIFT E
none
GO SHIFT S
none
G SHIFT O
G SHIFT R
G SHIFT S
HE SHIFT A
X SHIFT X
H SHIFT E
none
none
none
I SHIFT N
IN SHIFT S
none
J SHIFT O
K SHIFT E
LE SHIFT F
none
L SHIFT E
L SHIFT I
L SHIFT O
LO SHIFT C
none

671

672

COMMODORE 128

KEYWORD

LOOP
MID$
MONITOR
MOVSPR
NEW
NEXT
ON GOSUB
ON GOTO
OPEN
PAINT
PEEK
PEN
PI
PLAY
POINTER
POKE
POS
POT
PRINT
PRINT#
PRINT USING
PUDEF
RCLR
RDOT
READ
RECORD
REM
RENAME
RENUMBER
RESTORE
RESUME
RETURN
RGR
RIGHT$
RND
RREG
RSPCOLOR
RSPPOS
RSPR
RSPRITE
RUN
RWINDOW
SAVE
SCALE
SCNCLR
SCRATCH
SGN

ABBREVIATION

LO
M
MO
M

SHIFT O
SHIFT I
SHIFT N
SHIFT O
none
N SHIFT E
ON GO SHIFT S
ON G SHIFT 0
0 SHIFT P
P SHIFT A
PE SHIFT E
P SHIFT E
none
P SHIFT L
PO SHIFT I
PO SHIFT K
none
P SHIFT O
none
P SHIFT R
US SHIFT I
P SHIFT U
R SHIFT C
R SHIFT D
RE SHIFT A
R SHIFT E
none
RE SHIFT N
REN SHIFT U
RE SHIFT S
RES SHIFT U
RE SHIFT T
R SHIFT G
R SHIFT I
R SHIFT N
R SHIFT R
RSP SHIFT C
R SHIFT S
none
RSP SHIFT R
R SHIFT U
R SHIFT W
S SHIFT A
SC SHIFT A
S SHIFT C
SC SHIFT R
S SHIFT G

KEYWORD

SIN
SLEEP
SLOW
SOUND
SPC
SPRCOLOR
SPRDEF
SPRITE
SPRSAV
SQR
SSHAPE
STASH
ST
STEP
STOP
STR$
SWAP
SYS
TAB(
TAN
TEMPO
TI
TI$
TO
TRAP
TROFF
TRON
UNTIL
USR
VAL
VERIFY
VOL
WAIT
WHILE
WIDTH
WINDOW
XOR

ABBREVIATION

S SHIFT I
S SHIFT L
none
S SHIFT 0
none
SPR SHIFT C
SPR SHIFT D
S SHIFT P
SPR SHIFT S
S SHIFT Q
S SHIFT S
S SHIFT T
none
ST SHIFT E
ST SHIFT O
ST SHIFT R
S SHIFT W
none
T SHIFT A
none
T SHIFT E
none
none
none
T SHIFT R
TRO SHIFT F
TR SHIFT O
U SHIFT N
U SHIFT S
none
V SHIFT E
V SHIFT O
W SHIFT A
W SHIFT H
WI SHIFT D
W SHIFT I
X SHIFT O

674

COMMODORE 128

APPENDIX j

DISK COMMAND SUMMARY

This appendix lists the commands used for disk operation in C128 and C64 modes
on the Commodore 128. For detailed information on any of these commands, see
Chapter 2. Your disk drive manual also has information on disk commands.
The new BASIC 7.0 commands can be used only in C128 mode. All BASIC 2.0
commands can be used in both C128 and C64 modes.

COMMAND

USE

APPEND
BLOAD

Append data to file

Load a binary file starting at the specified
memory location
Load and execute a bootable program
Save a binary file from the specified memory location
Display directory contents of disk on screen*
Close logical disk file
Redirect screen output to a peripheral
device
Free inaccessible disk space*
Concatenate two data files*
Copy files between devices*
Clear all open channels on disk drives
Close logical disk file
Display directory of contents of disk on
screen*
Load a BASIC program from disk
Open a disk file for a read and/or write
operation
Save a BASIC program to disk
Verify program in memory against program on disk
Receive input from open disk file
Format a disk*
Load a file from disk
Open a file for input or output
Output a data to file
Position relative file pointers*
Change name of a file on disk*

BOOT
BSAVE
CATALOG
CLOSE
CMD
COLLECT
CONCAT
COPY
DCLEAR
DCLOSE
DIRECTORY
DLOAD
DOPEN
DSAVE
DVERIFY
GET#
HEADER
LOAD
OPEN
PRINT#
RECORD
RENAME

BASIC 2.0

BASIC 7.0

/
/
J

/
/

/
J
J

/
J

y
y
j

/
/
/
j

/
v/

/
J
J

y
j

APPENDIXES

COMMAND

USE

RUN filename
SAVE
VERIFY

Execute BASIC program from disk

Store program in memory to disk
Verify program in memory against program on disk

BASIC2.0

BASIC7.0
J

/
/

*Although there is no single equivalent command in BASIC 2.0, there is an equivalent multi-command
instruction. See your disk drive manual for these BASIC 2.0 conventions.

675

676

COMMODORE 128

APPENDIX K

PART ICOMMODORE 128 CP/M

This appendix explains each CP/M BIOS, 8502 BIOS and User Function routine and
how to call each in Z80 assembly language. This section assumes you already have
some knowledge about Z80 machine language and the basic operations of the CP/M
system. If you need more information about Z80 or CP/M, your local bookstore
probably has several good reference books about these widely covered subjects. To fully
cover these topics is beyond the scope of this reference guide. See "Suggestions for
Reading" at the end of this guide.
Part I of this appendix first lists each CP/M BIOS, 8502 BIOS and User Function
routine by number. Part II explains how and provides examples to call these routines.
Part III lists the Z80 memory map.
The format used to describe these routines are as follows:
a)
b)
c)
d)
e)

Function Name
Input Parameters
Output Parameters
Brief Description
Other required preparatory/post routines (or additional information)

The 8502 BIOS and User Function routines require certain values to be placed into
the Z80 microprocessor registers. In Chapter 5 you learned about the 8502 microprocessor registers: A, X, Y, Status (PSW), Stack Pointer (S) and Program Counter (PC). The
Z80 also has applicable registers. The Z80 registers are named as follows:
A
BC
DE
HL
PSW
IX
IY
PC
SP

(Accumulator)

(Status Word)
(X register)
(Y index register)
(program counter)'
(stack pointer)

Certain registers can be used as a register pair, to represent a 16 bit address, or as

single 8-bit register. The Z80 has a duplicate set of registers for interrupt processing.
For more detailed information on the Z80 microprocessor consult the "Suggestions for Further Reading." For more detailed information on the CP/M system, refer to
the Commodore 128 System Guide to receive the full set of CP/M Plus documentation,
written by Digital Research Inc., through Commodore.

APPENDIXES

COMMODORE 128 CP/M BIOS ROUTINES

The Commodore 128 CP/M system has a set of routines called the CP/M BIOS, which
handle the low level input/output operations of the system. Each of these routines can
be accessed via the CP/M BIOS jump table below. The jump vector numbers 0 through
29 are the CP/M BIOS jump vectors. The 30th jump vector is for system dependent
User Functions. These are discussed following the CP/M BIOS routines.
The 8502 BIOS routines are a subset of the system dependent User Functions
(specifically, User Function 4) contained in the Commodore 128 CP/M system. Many of
the User Functions have subfunctions which require certain parameters to be passed
through the Z80 registers. This is discussed in detail in the User Function section in this
appendix. Examples of calling the CP/M BIOS and User Function routines are provided
in Part II of this appendix.
NO.

INSTRUCTION

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP
JMP

BOOT
WBOOT
CONST
CONIN
CONOUT
LIST
AUXOUT
AUXIN
HOME
SELDSK
SETTRK
SETSEC
SETDMA
READ
WRITE
LISTST
SECTRN
CONOST
AUXIST
AUXOST
DEVTBL
DEVINI
DRVTBL
MULTIO
FLUSH
MOVE
TIME
SELMEN
SETBNK
XMOVE
USERF
RESERV1
RESERV2

DESCRIPTION

Perform cold start initialization

Perform warm start initialization
Check for console input character ready
Read Console Character in
Write Console Character out
Write List Character out
Write Auxiliary Output Character
Read Auxiliary Input Character
Move to Track 00 on Selected Disk
Select Disk Drive
Set Track Number
Set Sector Number
Set DMA Address
Read Specified Sector
Write Specified Sector
Return List Status
Translate Logical to Physical Sector
Return Output Status of Console
Return Input Status of Aux. Port
Return Output Status of Aux. Port
Return Address of Char. I/O Table
Initialize Char. I/O Devices
Return Address of Disk Drive Table
Set Number of LogicaUy Consecutive sectors to be read or written
Force Physical Buffer Flushing for user-supported deblocking
Memory to Memory Move
Time Set/Get signal
Select Bank of Memory
Specify Bank for DMA Operation
Set Bank When a Buffer is in a Bank other than 0 or 1
Reserved for System Implementor
Reserved for Future Use
Reserved for Future Use

CP/M 3 BIOS Jump Vector Table

677

678

COMMODORE 128

BOOT
Bank:
Input:
Output:
Function:

WBOOT
Bank:
Input:
Output:
Function:
CONST
Bank:
Input:
Output:
Function:

CONIN
Bank:
Input:
Output:
Function:

CONOUT
Bank:
Input:
Output:
Function:

LIST
Bank:
Input:
Output:
Function:

None
None
This code does all of the hardware initialization, sets up zero
page, prints any sign-on message and loads the CCP and then
transfers control to the CCP.
0 or 1
None
None
This code sets up page zero, reloads the CCP and then executes the CCP.
0 or 1
None
A = OFFH if console character
A = 00H if no console character
Checks the console input status of the current console devices.
If any of the devices have a character available, FFH is
returned, otherwise 00H is returned.
0 or 1
None
A = ASCII console character
Reads a character from any ONE of the assigned console input
devices. A scan of each assigned device is done until an
input character is found. The character is returned in the A
register.
0 or 1
C = ASCII character to display
None
Sends the character in C to ALL devices that are currently
assigned to the console. It waits for all assigned devices to
accept a character before exiting.
0 or 1
C = ASCII character to print
None
Sends the character in C to ALL devices that are currently
assigned to the LIST device. It waits for all assigned devices
to accept a character before exiting.

APPENDIXES

AUXOUT
Bank:
Input:
Output:
Function:

AUXIN
Bank:
Input:
Output:
Function:

HOME
Bank:
Input:
Output:
Function:

SELDSK
Bank:
Input:
Output:
Function:

10 SETTRK
Bank:
Input:
Output:
Function:
11 SETSEC
Bank:
Input:
Output:
Function:

0 or 1
C = ASCII Character to send to AUX device
None
Sends the character in C to ALL devices that are currently
assigned to the AUXOUT device. It waits for all assigned devices
to accept a character before exiting.
0 or 1
None
A = ASCII character from AUX device
Reads a character from any ONE of the assigned AUXCsf devices.
A scan of each assigned device is done until an input character
is found. The character is returned in the A register.
0

None
None
Homes the head on the currently selected disk drive. This
function sets the current track to 0 and does not move the head
of the disk.
0
C = Disk Drive (0-15) (A = 0)
E = Initial Select Flag (LSB)
HL = Address of Disk Parameter Header (DPH) if drive exists.
HL = 000H if drive does not exist.
Selects the disk drive whose address is in C as the current drive
for all further disk operations. If the LSB of the E register is a
zero, then this is the first logging of this disk. The disk type
(C64 CP/M, MFM or C128 CP/M) is checked and the DPB
parameters adjusted for the diskette currently in the drive.
0
BC = Track number
None
Register pair BC contains the track number to be used in the
subsequent disk access. This value is saved.
0
BC = Sector number
None
Register pair BC contains the sector number to be used in the
subsequent disk access. This value is saved. The value in BC
is the value returned by the sector translation routine (in HL).

679

680

COMMODORE 128

12

SETDMA
Bank:
Input:
Output:
Function:

13 READ
Bank:
Input:
Output:

Function:

14 WRITE
Bank:
Input:
Output:

Function:

15 LISTST
Bank:
Input:
Output:
Function:

0
BC = Direct memory access address
None
The value in BC is saved as the current DMA address. This is
the address where ALL disk reads or writes occur. The DMA
address that is set is used until it is changed by a future call to
this routine to change it.
0
None
A = 000H if no errors
A = 001H if nonrecoverable error
A = 0FFH if media has changed
Reads the sector addressed by the current disk, track and
sector to the current DMA address. If the data is read with no
errors then A = 0 on return. If an error occurs, the operation is
tried several more times, and if a successful read does not
occur then A is set to 001H. A test for media change is
performed each time this routine is called and A is set to - 1 if
the media has been changed.
0

C = Deblocking code (not used)

A = 000H if no errors
A = 001H if nonrecoverable error
A = 002H if disk is read only
A = OFFH if media has changed
Writes the sector addressed by the current disk track and
sector from the current DMA address. If the data is written with
no errors, then A is set to 0 on return. If an error occurs, the
operation is tried several more times, and if a successful write
does not occur, then A is set to 001H. A test for media change
is performed each time this routine is called and A is set to
- 1 if the media has been changed. Also, if an attempt is made
to write to a read-only disk, then the A register is set to 002H.
0 or 1
None
A = 00H if list device is not ready to accept a character.
A = OFFH if list device is ready to accept a character.
This routine scans the currently assigned list devices and returns
with A set to OFFH if ALL assigned devices are ready to accept a
character. If any assigned device is not ready then A is set
to 00H.

APPENDIXES

16 SECTRN
Bank:
Input:
Output:
Function:

17 CONOST
Bank:
Input:
Output:
Function:

18 AUXIST
Bank:
Input:
Output:
Function:

19 AUXOST
Bank:
Input:
Output:
Function:

20

DEVTBL
Bank:
Input:
Output:
Function:

BC = Logical sector number (0-n)

DE = Translation table address (from DPB)
HL = Physical sector number
This routine converts the physical sector number to a logical
sector number. If no translation is needed then it moves the
BC register to HL and returns.
0 or 1
None
A = 0FFH if Ready
A = 000H if not Ready
This routine scans the currently assigned console devices and
returns with A set to 0FFH if ALL assigned devices are ready
to accept a character. If any assigned device is not ready then
A is set to 000H.
0 or 1
None
A = 0FFH if console character present
A = 000H if no console character
Checks the status of the current AUXIN device. If any of the
devices have a character available, 0FFH is returned, otherwise
000H is returned.
0 or 1
None
A = 0FFH if ready
A = 000H if not ready
This routine scans the currently assigned AUXOUT devices and
returns with A set to 0FFH if ALL devices are ready to accept a
character. If any assigned device is not ready then A is set
to 00H.
0 or 1
None
HL = address of character I/O table
This routine returns the address of the Character I/O table.
This table is used to name each of the driver modules and
set/control the baud rate and XON/XOFF logic for each driver.
Note: the device drive mechanism is used to replace the IOBYTE
used with CP/M 2.2.

681

682

COMMODORE 128

21

22

23

24

DEVINI
Bank:
Input:
Output:
Function:
DRVTBL
Bank:
Input:
Output:
Function:

MULTIO
Bank:
Input:
Output:
Function:

FLUSH
Bank:
Input:
Output:

Function:
25

MOVE
Bank:
Input:

Output:
Function:

26

TIME
Bank:
Input:
Output:

0 or 1
C = device number
None
Initializes the physical character device specified in the C
register to the BAUD rate in the DEVTBL.
0

None
HL = address of the drive table
Returns the address of the drive table in HL (NOTE: first
instruction MUST be LXI H, DRVTBL). The drive table is a
list of 16 word pointers that point to the DPH for that drive. If
a drive is not present in the system, then the pointer for that
drive is set to zero.
0

C = multisector count
None
The multisector count is set before the track, sector, and DMA
address and the read/write of the sectors occur. A maximum
of 16K can be transferred by each multisector count.
0

None
A = 000H if no errors
A = 001H if nonrecoverable error
A = 002H if disk is read-only
A = OFFH if media has changed
This routine is used only if blocking/deblocking is done in the
BIOS. This code ALWAYS returns with A =000H.
0 or 1
HL = destination address
DE = source address
BC = count
HL = HL(in) 4- BC(in)
DE = DE(in) + BC(in)
Moves a block of data. Data to be moved is to/from the current
memory bank (or common) unless the XMOVE routine is
called first, then the move is an interbank data movement.
0 or 1
C = 000H (Time Get) / OFFH (Set Time)
None

APPENDIXES

Function:

27

SELMEM
Bank:
Input:
Output:
Function:

This function is called with C = 000H if the system time in the

SCB needs to be updated by the clock. I f C = OFFH, then the
time in the SCB has just been updated and the clock is
set to the SCB time. NOTE: HL and DE MUST be preserved.
0 or 1
A = memory bank
None
Changes the current memory bank. This code MUST be in
common memory.

NOTE: ONLY A can be changed.

28

29

SETBNK
Bank:
Input:
Output:
Function:
XMOVE
Bank:
Input:
Output:
Function:

30

USERF
Banks
Input:
Output:
Function:

31

RESERV1
Bank:
Input:
Output:
Function:
RESERV2
Bank:
Input:
Output:
Function:

32

A = DMA memory bank

None
Sets the DMA bank for the next READ/WRITE operation.
0

B = destination bank
C = source bank
None
Provides the system with the ability to perform memory-tomemory DMA through the entire system space.
0 or 1
A = function number, L = subfunction number
Outputs depend on the called function or subfunction.
This calls the user functions and 8502 BIOS routines, which
are defined in the Commodore 128 System Dependent User
Function section.
N/A
N/A
N/A
Not available to the user.
N/A
N/A
N/A
Not available to the user.

683

684

COMMODORE 128

DATA STRUCTURES
SYSTEM CONTROL BLOCK^SCB)
The System Control Block is a 100-byte data structure. The data structure is
used as the basic communication between the various modules that make up the
CP/M Plus system. The contents of the data structure are system parameters and
variables.

DRIVE TABLE (DRVTBL)

PH0 through DPHI5
A list of 16 word pointers (reverse-byte format). The first pointer (DPH0) is
drive A and the last pointer (DPH15) is drive P. The pointers point to the XDPH
for that disk drive. Any drive that is not in the system has its pointers set to
zero.

EXTENDED DISK PARAMETER HEADER (XDPH)

(NORMAL DPH WITH A HEADER)
WRT READ LOGIN INIT TYPE UNIT XLT

16b 16b 16b

-10 ^
^6

WRT
READ
LOGIN
INIT
TYPE
UNIT
XLT
-0MF

16b 8b
-A -2

8b
-1

-0- MF DPB CSV ALV DIRBCB DTABCB HASH HBANK

16b 72b 8b 16b 16b 16b

0 2 11
12 14 16

16b
18

16b 16b
20 22

8b
24

Contains the address of the sector write routine for this drive.
Contains the address of the sector read routine for this drive.
Contains the address of the login routine for this drive.
Contains the address of the first time initialization routine for this drive.
This byte is used by the BIOS to keep track of density and media type.
Contains the drive number relative to the disk controller.
Contains the address of the sector translation table or zero if none.
BDOS scratch area (9 bytes).
Media flag cleared to zero if disk logged in. BIOS sets to OFFH if media
has changed.
DPB
Contains a pointer to the current DPB that describes the current media type.
CSV
Contains a pointer to directory checksum area (one per disk drive).
ALV
Contains a pointer to allocation vector area (one per disk drive).
DIRBCB Contains a pointer to a single directory Buffer Control Block (BCB).
DTSBCB Contains a pointer to a single data Buffer Control Block (BCB).
HASH
Contains a pointer to an optional directory hashing table (FFFFH is
not used).
HBANK Contains a bank number of the directory hashing table.

APPENDIXES

685

DISK PARAMETER BLOCKDPB

SPT

BSH

BLM

EXM

DSM

DRM

AL0

AL1

CKS

OFF

PSH

PHM

16b

8b

8b

8b

16b

16b

8b

8b

16b

16b

8b

8b

SPT
BSH
BLM
EXM
DSM
DRM
AL0
AL1
CKS
OFF
PSH
PHM

Number of 128 records per track

Data allocation block shift factor
Block mask
Extent mask
Number of allocation block on disk minus one
Number of directory entries minus one
First byte: directory block allocation vector. Filled from MSB to LSB
Second byte: (Up to 16 allocation blocks can be used for the directory)
Size of the directory check vector, (DRM+ l)/4
Number of reserved tracks at the beginning of the disk
Physical record shift factor
Physical record mask

BUFFER CONTROL BLOCK (LRU CONTROL BLOCKBCB)

DRV

REC#

WFLG

00

TRACK

SECTOR

BUFFAD

BANK

LINK

8b

24b

8b

8b

16b

16b

16b

8b

16b

DRV
REC#
WFLG
00
TRACK
SECTOR
BUFFAD
BANK
LINK

Drive associated with this record. Set to OFFH when not used.
Contains the absolute sector number of the buffer.
Set to OFFH when buffer contains data that must be written to disk.
Scratch byte used by BDOS
Physical track address of buffer.
Physical sector address of buffer.
Address of the buffer associated with this BCB.
Bank number of buffer associated with this BCB.
Contains the address of the next BCB in this linked list. Set to zero if last.

COMMODORE 128 SYSTEM DEPENDENT

USER FUNCTIONS
The Z80 machine language routines discussed in this section pertain explicitly to the
Commodore 128 Personal Computer. These routines are not part of the standard CP/M
system that is transportable from one manufacturer's computer to another. They are
written to run only on the Commodore 128.
Most of these customized C128 Z80 routines require certain parameters to be
passed from the user into the appropriate Z80 registers. All these routines, listed by

686

COMMODORE 128

function number, require that the function number be placed in the Z80 A register
(accumulator). Many of these routines have subfunctions which require the user to place
a value in the eight bit L register, which is used to call the appropriate subfunction. All
other additional required parameters are noted if they are necessary. This section follows
the same format as the preceding CP/M BIOS section:
a)
b)
c)
d)
e)

Function Name
Input Parameters
Output Parameters
Brief Description
Additional Information

a) User Function 0: Read any Byte in RAM Bank 00

b) A = 0 (function number)
DE = 16 bit address to be read
c) C = Value read from address in RAM Bank 0
A = 0 on RETurn from routine
d) This reads a value from RAM BANK 0 ($0-$0FFF, $1000-$FFFF RAM)
and places it in register C.

I.

a) User Function 1: Write Function in RAM Bank 0

b) A = 1 (function number)
DE = 16-bit address where write operation occurs
C = Value to be written to the address in Bank 0
c) A = 0 on RETurn from routine if write is successful
A = - 1 ($FF) on RETurn from routine if write is unsuccessful
d) This function writes the value in register C to RAM in bank 0 specified
by the address in register pair DE. An error is flagged if a write to ROM
($0-$DFFFH) or the top page of memory ($FF00-$FFFF) is attempted.

II.

a) User Function 2: Keyscan Function

b) A = 2 (function number)
c) B = - 1 ($FF) if no key is pressed
B = Matrix position in the keyboard matrix table (if pressed)
A = Contents (character value) of matrix position whether A is lower- or
uppercase or containing the C O N T R O L key.
HL = Address (pointer) where A (contents of matrix position) is found
in memory
Address = Tablestart + (4 * B) + C (bits 1 and 0)
C = Returns control code information, where each bit has a specific
meaning as follows:
Bits 1 & 0
0
0
1
1

0 = lower case
1 = upper case
0 = shifted
1 = control key

APPENDIXES

C =

Bit
Bit
Bit
Bit
Bit
Bit

2 1 = control key down, 0 = up

3 Not implemented
4 1 = Right shift key down, 0 = up
5 1 = O key is active (not necessarily down)
6 Not implemented
7 1 = left shift key down, 0 = up

d) The keyscan function allows the user to bypass the normal I/O BIOS
keyboard processing and check for a particular key or key sequence
being pressed.
e) Additional InformationImportant Addresses:
$FD09 = Pointer to Tablestart (low byte first)
Each ASCII character has four coded definitions. Each key has a defined code for
the following:
a)
b)
c)
d)

lower case
upper case
shifted key and character
control key and character

These four definitions are labeled in columns in the ASCII table.

ASCII$TBL:

1292
1296
129A
129E
12A2
12A6
12AA
12AE

7F7F7F16
0D0D0D0D
06060101
86868787
80808181
82828383
84848585
1717171A

DB
DB
DB
DB
DB
DB
DB
DB

7FH,7FH,7FH,16H
0DH,0DH,0DH,0DH
06H,06H,01H,01H
86H,86H,87H,87H
80H,80H,81H,81H
82H,82H,83H,83H
84H,84H,85H,85H
17H,17H,17H,lAH

INS DEL matrix 0 position

RETURN
LF RT
F7 F8
Fl F2
F3 F4
F5 F6
UP DOWN

12B2
12B6
12BA
12BE
12C2
12C6
12CA
12CE

333323A2
77575717
61414101
343424A3
7A5A5AlA
73535313
65454505
00000000

DB
DB
DB
DB
DB
DB
DB
DB

33H ,33H, 23H,0A2H

77H,57H,57H,17H
61H,41H,41H,01H
34H,34H,24H,0A3H
7AH,5AH,5AH,lAH
73H,53H,53H,13H
65H,45H,45H,05H
00H,00H,00H,00H

3 #
W
A
4$
Z

12D2
12D6
12DA
12DE
12E2
12E6

353525A4
72525212
64444404
363626A5
63434303
66464606

DB
DB
DB
DB
DB
DB

35H, 35H, 25H, 0A4H

72H,52H,52H,12H
64H,44H,44H,04H
36H,36H,26H,0A5H
63H,43H,43H,03H
66H,46H,46H,06H

5%
R
D
6&
C
F

s
E
(LF SHIFT)

687

688

COMMODORE 128

ASCII$TBL:

12EA 74545414
12EE 78585818

DB
DB

74H,54H,54H,14H
78H,58H,58H,18H

;T
; x

12F2
12F6
12FA
12FE
1302
1306
130A
130E

373727A6
79595919
67474707
383828A7
62424202
68484808
75555515
76565616

DB
DB
DB
DB
DB
DB
DB
DB

37H,37H,27H,0A6H
79H,59H,59H,19H
67H,47H,47H,07H
38H,38H,28H,0A7H
62H,42H,42H,02H
68H, 48H, 48H, 08H
75H,55H,55H,15H
76H,56H,56H,16H

; 7'
;Y
;G
;8(
;B
;H
; u
; v

1312
1316
131A
131E

39392900
69494909
6A4A4A0A
30303000

DB
DB
DB
DB

39H,39H, 29H, 00H

69H,49H,49H,09H
6AH,4AH,4AH,0AH
30H,30H, 30H, 00H

;9)
;I
;J
;o

1322
1326
132A
132E

6D4D4D0D
6B4B4B0B
6F4F4F0F
6E4E4E0E

DB
DB
DB
DB

6DH,4DH,4DH,0DH
6BH,4BH,4BH,0BH
6FH,4FH,4FH,0FH
6EH,4EH,4EH,0EH

;M
;K

1332
1336
133A
133E
1342
1346
134A
134E

2B2B2B00
70505010
6C4C4C0C
2D2D2D00
2E2E3E00
3A3A5B7B
40404000
2C2C3C00

DB
DB
DB
DB
DB
DB
DB
DB

2BH,2BH,2BH,00H
70H,50H,50H,10H
6CH,4CH,4CH,0CH
2DH,2DH,2DH,00H
2EH,2EH,3EH,00H
3AH,3AH,5BH,7BH
40H,40H,40H,00H
2CH,2CH,3CH,00H

;+

1352
1356
135A
135E
1362
1366
136A
136E

23232360
2A2A2A00
3B3B5070
000000F5
00000000
3D3D3D7E
5E5E7C7C
2F2F3F5C

DB
DB
DB
DB
DB
DB
DB
DB

23H,23H,23H,60H
2AH,2AH,2AH,00H
3BH,3BH,5DH,7DH
00H,00H,00H,0F5H
00H,00H,00H,00H
3DH,3DH,3DH,7EH
5EH,5EH,7CH,7CH
2FH,2FH,3FH,5CH

;POUND
.*

1372 313121A0
1376 5F5F5F7F
137A 09153000

DB
DB
DB

31H,31H,21H,0A0H
5FH,5FH,5FH,7FH
09H,15H,30H,00H

137E
1382
1386
138A
138E

DB
DB
DB
DB
DB

32H ,32H,22H,0AlH
20H,20H,20H,00H
21H,20H,00H,00H
71H,51H,51H,11H
00H, 00H, 00H, 0F0H

323222A1
20202000
21200000
71515111
000000F0

;o
;N
;P
;L

;, <
;; :@
[{

;,<
;;]}
; CLEAR/HOME
; (RT SHIFT)

; PI

;/?\

;1

; <; (CONTROL) SOUNDl

SOUND2
; 2"
;SPACE
; (COMMODORE) SOUND3
;Q
; RUN STOP

APPENDIXES

ASCII$TBL:

1392
1396
139A
139E
13A2
13A6
13AA
13AE

9F9F9F9F
383838B7
353535B4
09090900
323232B1
343434B3
373737B6
313131B0

DB
DB
DB
DB
DB
DB
DB
DB

9FH, 9FH, 9FH, 9FH

38H,38H,38H,0B7H
35H,35H,35H,0B4H
09H, 09H, 09H, 00H
32H ,32H,32H ,0B1H
34H,34H,34H,0B3H
37H,37H,37H,0B6H
31H,31H,31H,0B0H

/HELP/
/8/
/5/
/TAB/
111
/4/
111
11/

13B2
13B6
13BA
13BE
13C2
13C6
13CA
13CE
13D2
13D6
13DA
13DE
13E2
13E6
13EA
13EE

1B1B1B00
2B2B2B00
2D2D2D00
0A0A0A0A
0D0D0DFF
363636B5
39393900
333333B2
00000000
30303000
2E2E2E00
05050512
18181803
1313138D
0404048E
FlFlFlF2

DB
DB
DB
DB
DB
DB
DB
DB
DB
DB
DB
DB
DB
DB
DB
DB

1BH,1BH,1BH,00H
2BH,2BH,2BH,00H
2DH,2DH,2DH,00H
0AH,0AH,0AH,0AH
ODH, ODH, ODH, OFFH
36H,36H,36H,0B5H
39H,39H,39H,00H
33H,33H,33H,0B2H
00H,00H,00H,00H
30H,30H,30H,00H
2EH,2EH,2EH,00H
05H,05H,05H,12H
18H,18H,18H,03H
13H,13H,13H,08DH
04H, 04H, 04H, 08EH
0FlH,0FlH,0FlH,0F2H

/ESC/
/+/
/-/

/LINE FEED/
/ENTR/
/6/
/9/
/3/
/ALT/
/0/

/./
/UP/
/DN/
/LF/
/RT/
/NO SCROLL/

LOGICAL COLOR TABLE (USED WITH ESC ESC ESC CHAR)

(WHERE CHAR IS 50H TO 7FH)
13F2
13F6
13FA
13FE

00112233
44556677
8899AABB
CCDDEEFF

DB
DB
DB
DB

III.

a) User Function 3: Execute a Z80 ROM function

b) A - 3
L = subfunction number
Additional input parameters may be necessary
c) Most of the ROM functions do not output values; they instead perform
an action, which in this user function is assumed to be the output.
d) This function executes a Z80 ROM function. These ROM routines
primarily perform screen manipulation routines.
All subfunction numbers are even numbers. The first 80 subfunctions are
screen manipulating routines for the 40- and 80-column display. Only the
80-column subfunction is listed here. Add 2 to the 80-column subfunction
number to get the corresponding 40-column subfunction number.

000H,011H,022H,033H
044H,055H,066H,077H
088H,099H,0AAH,0BBH
0C C H, ODDH, OEEH, OFFH

689

690

COMMODORE 128

III.

0a) Subfunction 0: Write Character

b) wr$char
c) Register D = character to write auto advance cursor to next position
d)

III.

4a) Subfunction 4: Cursor Position

b) cursor$pos
c) Register D = row value
Register E = column value
d) This subfunction sets the current position of the cursor on the 80-column
screen.

III.

8a)
b)
c)
d)

Subfunction 8: Cursor Up one position

cursor$up
no values returned
This subfunction moves the cursor up one row on the current screen (40
or 80), but not past the top of the screen.

III.

12a)
b)
c)
d)

Subfunction 12: Cursor down one row

cursor$down
no values returned
This subfunction moves the cursor down one row on the current screen
(40 or 80). The screen scrolls down if on bottom line.

III.

14a) Subfunction 14: Not Implemented

b)
c)

III.

16a)
b)
c)
d)

Subfunction 16: Cursor left one column

cursor$left
no values returned
This subfunction moves the cursor left one column, but not past the
left margin.

III.

20a)
b)
c)
d)

Subfunction 20: Cursor right one column

cursor$rt
no values returned.
This subfunction moves the cursor right one column, but not past the
right edge of the screen.

III.

24a)
b)
c)
d)

Subfunction 24: Execute a carriage return

do$cr
No values returned.
This subfunction executes a carriage return and places the cursor at the
left margin.

III.

28a)
b)
c)
d)

Subfunction 28: Clear to end of line

CEL
No values returned.
This subfunction clears the cursor row starting where the cursor is
currently located and ending at the end of the line.

APPENDIXES

III.

32a)
b)
c)
d)

Subfunction 32: Clear to end of screen

CES
No values returned.
This subfunction clears the screen starting where the cursor is currently
located through the end of screen.
Subfunction 36: Character insert
char$ins
No values returned.
This subfunction inserts a character at the current cursor position, the
last character on the line is lost.
Subfunction 40: character delete
char$del
No values returned.
This subfunction deletes a character at the current cursor position, and
places a space in the last position in the line.
Subfunction 44: Line insert
line$ins
No values returned.
This subfunction inserts a line of spaces on the current cursor row, the
current cursor row is moved down one and the last line (24) is lost.
Subfunction 48: Line delete
line$del
No values returned.
This subfunction deletes a line at the character row marked by the
current cursor position. The bottom line (24) is filled with spaces.
Subfunction 50: Not Implemented

Subfunction 52: Set Cursor Color

color
B register returns color code value
No values returned.
This function sets the current cursor color code with the value in color.
Subfunction 56: Set 80-column Attributes
attr
B = bit to set/clear
C = bit value
No values returned.
This function enables/disables the 8563 attributes for the 80-column screen.
Attributes are extra screen features such as foreground R,G,B and I,
character blinking, underlining, reverse video and the alternate character
set. The 40-column function (subfunction 58) controls only reverse video.

691

692

COMMODORE 128

III. 60a) Subfunction 60: Read Character Attribute (80)

b) rd$chr$atr
D = 8563 character row
E = 8563 character column
c) D = 8563 character row
L = 8563 character column
B = character value
C = attribute bit pattern of selected character location
d) This function reads the attribute byte of the selected character row and
column on the 8563 screen, and returns the true RGBI color. The
corresponding 40-column subfunction (62) controls only reverse video.
III. 64a) Subfunction 64: Write Character Attribute (80)
b) wr$chr$atr
B = character value
C = attribute
c) No values returned
d) This function writes an attribute byte of the selected character value
on the 8563 screen.
III. 68a) Subfunction 68: Read Color
b) rd$color
c) A = character color
B = background color
C = border color (40-column only)
D = 8563 attribute
d) This function reads the current color of the 8563 color sources. Subfunction
70 returns the VIC color sources.
III. 80a)
b)
c)
d)

Subfunction 80: Convert record (GCR only)

@trk
VIC$trk, VIC$SEC
This function returns the physical track and sector from the disk drive,
including skew, given the logical track.

III. 82a) Subfunction 82: Check CBM code from disk (GCR only)
b) check$CBM
c) zero flag = 1 if CBM (C128 mode disk) is present in drive
zero flag = 0 if CP/M 2.2 (C64 CP/M disk) is present in drive
A = 0 if single sided
A = $FF if double sided
d) This function detects which type of GCR disk is in the drive. Reads
data from t - 1, s = 0 into buffer at $FE00.
III. 84a)
b)
c)
d)

Subfunction 84: Bell Function

Sound 1, Sound 2, Sound 3 ($FD10, $FD12, $FD14, respectively)
Outputs a bell sound
This function outputs a bell sound from the SID chip.
Subfunctions 86-95 are not defined

APPENDIXES

III. 96a)
b)
c)
d)

Subfunction 96: Track 40

trk$40
@ off 40
This function computes the logical (offset) position of the cursor on the
physical 80-column screen. The variable @ off40 is computed on
8-character boundaries, and is used in the next subfunction.

III. 98a)
b)
c)
d)

Subfunction 98: Set cursor position

set$cur$40
No value returned.
This function calls Track 40 to check the offset between the logical
(window) and physical (40-column) screen. It keeps the cursor within
the 40-column logical window on the scrolled 80-column virtual screen
for VIC screen output.

III. 100a)
b)
c)
d)

Subfunction 100: Line Paint

line$paint
No value returned.
This function updates the current character line only if @ off 40 and
old $offset are the same. If old $offset = - l , TRACK 40 is called.
If @off40 and old $offset are not equal, Screen Paint is called to
scroll the 40-column logical screen (window) over the virtual 80column screen.

III. 102a)
b)
c)
d)

Subfunction 102: Screen paint

screen$paint
No value returned.
This function updates (scrolls) the 40-column logical (window) screen
across the VIC 80-column virtual screen based on the value of @off40.
This and the three previous subfunctions (96, 98, 100) are intertwined
to make the scrolled 40-column logical screen display as fast as
possible. Normally you would only call Set Cursor Position or Line
Paint, since they call the other related routines, if necessary. See file
CXROM.ASM listing on the DRI disks that come with the documentation for the source listings.

III. 104a)
b)
c)
d)

Subfunction 104: Print Message (BOTH)

prt$msg$both
No value returned.
This function prints simultaneous output to both screens, displaying
the string pointed to by the top value on the stack. Place the address of
the string on the stack, and terminate the string with a zero. Execution
resumes with the byte following the zero terminator. This works like
an "in-line Print"

III. 106a) Subfunction 106: (Print Message (BOTH)

b) prt$de$both
c) No value returned.

693

694

COMMODORE 128

d) This function works like the previous one, except the start address of
the string is taken from DE, and execution resumes with the return
address from the stack.
III. 108a)
b)
c)
d)

Subfunction 108: Incripted Messages

update$it
No value returned
This function displays incripted messages.
Subfunction 110 is not implemented.

III. 112a)
b)
c)
d)

Subfunction 112: ASCII to PET ASCII Conversion

ASCII$pet, B register = ASCII character ($20-$7F)
A register = converted PET ASCII character.
This function performs a standard ASCII to Pet ASCII conversion on
the characters printed to the screen (from any input device)
Control codes are not translated.

III. 114a) Subfunction 114: Place 40-column cursor at specified address

b) cur$adr$40
c) HL = address of cursor on screen
DE = cursor line (row) start address
BC = # of characters to end of line (<80, not counting cursor)
d) This function places the cursor at the address specified in HL (in RAM
bank 0). This address is of the logical screen, not the virtual one.
III. 116a) Subfunction 116: Place 80-column cursor at specified address
b) cur$adr$80
c) HL = address of cursor on screen
DE = cursor line (row) start address
BC = # of characters to end of line (<80, not counting cursor)
d) This function places the cursor at the address specified in HL (in
8563 RAM).
III. 118a) Subfunction 118: Look up color
b) look$color, B = color code ($30-$3F), C = max. Value of color code.
c) HL = pointer to logical color table (lower nybble = 80, high nybble = 40B = $0 (Character color)
$10 (Background color)
$20 (Border color)
d) This function sets the 8563 screen colors to the VIC screen colors.
Subfunction 120 is not defined.
III. 122a) Subfunction 122: Block Fill
b) blk$fill, put start address on stack (8563)
BC - # of bytes to fill
D = fill character
E = attribute
c) No value returned.
d) This function fills a 256-byte block with data specified in the D register.

APPENDIXES

III. 124a) Subfunction 124: Block move

b) blk$move, place source address (in 8563 RAM) on the stack
DE = destination address (in 8563 RAM)
BC = count
c) No value returned.
d) This function moves 256-byte blocks from one memory block to another
in 8563 RAM.
NOTE: Subfunctions 122 and 124 and 126 must be direct Z80 calls. The
example routines provided in this section for subfunctions 122, 124 and 126
will not work. They are usually not user-accessible, and must run in BANK 0.
III. 126a) Subfunction 126: Character Install
b) chr$inst, stack = 8563 RAM address to install character definition
DE = address of system memory (C128 RAM) bank 0) of new
character definition (8 bytes per character).
B = number of consecutive characters
c) No value
d) This function installs a user-defined character in 8563 RAM.
IV.

a) User Function 4: 8502 BIOS Functions

b) A = 4 (function number)
L = Subfunction number (-1 through 11)
Additional input parameters may be required
c) Outputs depend on each subfunction
d) User function 4 allows you to call 8502 input/output functions that are
performed by the 8502 processor. These functions are not part of the
standard CP/M system and are completely hardware-dependent. This
function enables you to go back and forth between the Z80 and 8502
processors.
e) Each subfunction is discussed in detail using the defined conventions.

IV. -l.a) Subfunction -1: Reboot C128 hardware

b) A - 4
L = -1
c) none
d) This subfunction reboots the Commodore 128 hardware when the value
in the L register is equal to -1 ($FF). This subfunction is not normally
used. It performs the same actions as pressing reset.
IV. 0.a) Subfunction 0: Initialize 8502 BIOS
b) A - 4
L = 0
cl) Sets up interrupt vector $0314-$0319 to vector to the 8502 interrupt
handler
c2) Copies ROM interrupt vector to RAM

695

696

COMMODORE 128

c3) Sets up PAL and NTSC variables (SYSFREQ)

c4) Closes all open channels
d) This subfunction intializes 8502 system variables, interrupt processing
and system frequencies so that the Z80 and 8502 may communicate
back and forth. Processor control is given to either the Z80 or the 8502
at one particular time. The processors cannot run simultaneously.
IV. l.a) Subfunction 1: 1541 Read (GCR format only)
b) A - 4
L = 1
VICTRACK = (1-35)Variable for track number on disk
VICSECTOR - (0-21)Variable for sector number on disk
VICDRV = Variable for disk drive device number where:
EQUIVALENT OPEN

LOWER NYBBLE
OF VICTORY
BIT VALUE

0001
0010
0100
1000

DEVICE NUMBER

DRIVE

8
9
10
11

0
0
0
0

STATEMENT IN BASIC

OPEN
OPEN
OPEN
OPEN

8,11,15
9,12,16
10,13,17
11,14,18

Values of the Lower Nybble of VICDRV

c) VICDATA = 11 ($0B) if disk in drive has been changed

VICDATA = 13 ($0D) if read/write or channel error occurs
VICDATA = 0 if read is successful
VICDATA = 15 ($0F) if device is not present
d) This function reads a particular track and sector on the disk in the drive
as specified by VICTRACK and VICSECTOR and VICDRV respectively. Data is read into the buffer at $FE00H. The value returned in the
variable VICDATA depends on the conditions described in c.
e) Additional Information: This subfunction assumes that both the data and
command channels have been opened previously. An error will occur if
this routine is called to read from a 1571.
IV. 2.a) Subfunction 2: 1541 Write (GCR format only)
b) A - 4
L - 2
VICTRACK - Same as for 1541 Read
VICSECTOR = Same as 1541 Read
VICDRV - Same as 1541 Read
c) VICDATA - Same as 1541 Read
d) This subfunction writes data to the specified track and sector on the disk
in the drive as specified by VICTRACK, VICSECTOR and VICDRV
respectively. The value returned in VICDATA depends on the conditions described for the outputs in c. See subfunction 1 for details.

APPENDIXES

e) Additional Information: This subfunction assumes that both the data and
command channels have been opened previously. Data is written from
the buffer at $FE00H.
IV. 3.a) Subfunction 3: 1571 Read Set Up (MFM or GCR formats)
b) A - 4
L = 3
* VICTRACK = (1-35)Variable for track number on disk
* VICSECTOR = (0-21)Variable for sector number on disk
* VICDRV = Variable for disk drive device number (See VICDRV
table above.)
* = Ranges apply to GCR format only. The ranges are different for
MFM disks depending on the manufacturer.
VIC$COUNT = Number of sectors to read (on the track)
c) VICDATA = 11 ($0B) if disk in drive has been changed
VICDATA = 12 ($0C) if drive is not a fast (1571) disk drive
VICDATA = 13 ($0D) if channel error occurs
VICDATA = 15 ($0F) if device is not present
If FAST ANDed with VICDRV = 0 meaning drive is a 1541
If FAST ANDed with VICDRV = 1 meaning drive is a 1571
d) This subfunction sets up the 1571 disk drive for a read operation.
However, the data transfer is not performed by the 8502 BIOS. The
data is transferred by the Z80.
e) Additional Information: To access the back side of an MFM disk set bit
7 ($80) of VICSECTOR. For MFM formats, a dash between the track and
sector on the display window means that the drive accesses the back
side of the disk. This is usually performed by the BIOS.
IV. 4.a) Subfunction 4: 1571 Write Set Up (MFM or GCR formats)
b) A - 4
L = 4
* VICTRACK = (1-35)Variable for track number on disk
* VICSECTOR = (0-21)Variable for sector number on disk
VICDRV - Variable for disk drive device number. See VICDRV
table on previous page.
VIC$COUNT = Number of sectors to read
* = Ranges apply to GCR format only. The ranges are different for
MFM disks depending on the manufacturer.
c) VICDATA = 11 ($0B) if disk in drive has been changed
VICDATA = 12 ($0C) if drive is not a fast (1571) disk drive
VICDATA = 13 ($0D) if channel error occurs
VICDATA = 15 ($0F) if device is not present
If FAST ANDed with VICDRV - 0 meaning drive is a 1541
If FAST ANDed with VICDRV = 1 meaning drive is a 1571
d) This subfunction sets up the 1571 disk drive for a write operation.
However, the data is not performed by the 8502 BIOS. The data is
transferred by the Z80.

697

698

COMMODORE 128

e) Additional Information. This is how the user should select between a

1541 and 1571 Drive. To access the back side of an MFM disk set bit 7
of VICSECTOR. To perform a write operation, the user will have to do
so in their application.
IV. 5.a) Subfunction 5: Interrogate 1541 or 1571 Disk Drive
b) A - 4
L = 5
VICDRV = (8-11)Diskdrivedevice numbervariable
c) VICDATA = lower four bits returns status for FAST read/write
(same as previous VICDATA Disk error codes, which
are listed in the Disk Error Status table on the next page).
= upper four bits return sector size for MFM disks
d) This subfunction interrogates the disk drive for the disk sector size
(MFM or GCR) and the drive status. In addition, this subfunction
initializes the FAST variable, closes and reopens the channel for the
corresponding drive, and clears the drive status.
IV. 6.a) Subfunction 6: Query to Disk
b) A - 4
L = 6
VICTRACK = (1-35)Variable for track number on disk
VICSECTOR = (0-21)Variable for sector number on disk
VICDRV = Variable for disk drive device number
c) If error-free
VICDATA = lower four bits returns status for FAST read/write
= upper four bits return sector size for MFM disks and the
subfunction inputs 6 bytes into a memory buffer starting at
location $FE00 (and ending at $FEFF). These 6 bytes are
defined as :
1)
2)
3)
4)
5)
6)

$FE00-TRACK STATUS (on track below)

$FE01-Number of Sectors
$FE02-Logical Track
$FE03-Minimum Sector Number (on this track)
$FE04-Maximum Sector Number (on this track)
$FE05-Physical Interleave

If an error occurs:
VICDATA - 11 ($0B) if disk in drive has been changed
VICDATA - 12 ($0C) if drive is not a fast (1571) disk drive
VICDATA - 13 ($0D) ifchannel error occurs
VICDATA = 15 ($0F) if device is not present
d) This subfunction queries the disk, and returns the disk status and sector
size (if MFM format). In addition, the buffer located between $FE00
and $FEFF receives 6 data items as described above.

APPENDIXES

Disk Error Status Table

MD

DN

II

12

D1

MD
DN
II, 12
a)
b)
c)
d)
Dl-D4

00
01
10
11

=
=
=
=

D2

D3

D4

Mode: 1 = MFM, 0 = GCR.

Drive Number.
Sector Size.
128 bytes
256 bytes
512 bytes
1024 bytes
Controller Status

GCR

000x
0010
0011
0100
0101
0110
0111
1000
1001
1010
1011
1100
1101
1110
1111

=
=
=
=
=
=
=
=
=
=
=
=
=
=
=

Ok.
Sector not found.
No Sync.
Data block not found.
Data block checksum.
Format error.
Verify error.
Write protect error.
Header block checksum.
Data extends into next block.
Disk ID mismatch^)isk change.
Drive is not fast (1571).
Channel Error.
Syntax.
No Drive present.

000x
0010
0011
0100
0101
0110
0111
1000
1001
1010
1011
1100
1101
1110
1111

=
=
=
=
=
=
=
=
=
=
=
=
=
=
=

Ok.
Sector not found.
No address mark.
Unused.
Data CRC error.
Format error.
Verify error.
Write protect error.
Header CRC error.
Unused.
Disk change.
Drive is not fast (1571).
Channel Error.
Syntax.
No Drive present.

MFM

Disk Error Status Table

699

708 COMMODORE 128

IV. 7.a) Subfunction 7: Print characters to a serial bus printer

b) A = 4
L = 7
VICDRV - Printer number (either 4 or 5)
VICTRACK = Secondary address in which device is opened as
VICDATA = Character to be printed to the serial bus printer (if
VICCOUNT = 0)
c) VICDATA = - 1 ($FF) if device is not present
d) This subfunction outputs characters to the previously opened serial bus
printer.
e) Additional Information: If the secondary address (which is normally 7)
is changed, the device is closed and reopened with the new secondary
address. If a serial bus error besides device not present occurs, the
channel is closed, reopened and the original operation is executed
again.
If VICCOUNT is not equal to zero, the data is printed from the buffer
pointed to by $FE00. The number of bytes printed is supplied in VICCOUNT.
IV. 8.a) Subfunction 8: Format a 1541 or 1571 Diskette
b) A - 4
L - 8
DRIVE#
FAST
c) VICDATA
d) This subfunction formats a 1541 or 1571 diskette in the appropriate
drive. If FAST is enabled, (FAST ANDed with DRIVE# (not equal to
0)), the length of a disk command is fetched from memory buffer
location $FE00. The command starting at location $FE01 and ending at
the location specified by the length of the command in $FE00 is sent to
the drive. For example, if $FE00 = $06, the command in the memory
buffer between $FE01 and $FE06 is sent to the drive. All commands
have a "U0" preceding them, so only the command from the memory
buffer must be supplied.
IV. 9.a) Subfunction 9: User Call to 8502 Code Routine
b) A = 4
L = 9
VICOUNT - ($FD05) low byte address of 8502 routine (pointer to the
start of execution of the user routine)
VICDATA = ($FD06) high-byte address of 8502 routine
c) User defined outputs only
d) This is the routine that allows you to call an 8502 machine language
subroutine from Z80 mode. The 8502 coded routine is usually user
defined. It must execute in RAM bank 0 with the input/output registers
enabled. The MMU value = $3E. Control is transferred to the 8502
processor with the KERNAL disabled. If you want to call a C128

APPENDIXES

KERNAL routine, you must enable the KERNAL after you have transferred control to the 8502. Before you return to the Z80, you must
disable the KERNAL again.
When control passes from the Z80 to the 8502 processor, the Z80
is idle. To return control to the Z80 processor, place the customary
8502 RTS instruction at the end of your 8502 coded routine and control
is passed back to the Z80.
e) Additional Information: Once control is passed from the Z80 to the
8502, the 8502 is running at the speed of 1 Mhz. You can increase the
speed to 2 Mhz to speed up processing on the 8502 side of the
computer. However, YOU MUST RETURN TO 1 Mhz SPEED BEFORE
RETURNING TO THE Z80 OR A SYSTEM CRASH WILL OCCUR.
The nature of the timing of the two processors dictates this. If you
don't return to 1 Mhz, the clock cycle timing is thrown off and the
system crashes.
IV. 10.a) Subfunction 10: RAM Disk Read
b) A = 4
L = 10
c) Data is transferred to expansion RAM from RAM (BANK 0)
d) All expansion RAM registers must be set up prior to calling this routine.
IV. ll.a) Subfunction 11: RAM Disk Write
b) A = 4
L = 11
c) Data is transferred to expansion RAM from RAM (BANK 0)
d) All expansion RAM registers must be set up prior to calling this routine.
V.

a) User Function 5: Read 40/80 Column Key

b) A = 5 (function number)
c) A = Value stored in $D505 (C128 Mode Configuration register)
If bit 7 is high (1), 40/80 key is up, otherwise 40/80 is down.
d) This function returns the value of location $D505, the mode configuration register. Only bit 7 is significant as noted above. The 40/80 key is
not in the keyboard matrix table, so this function is dedicated to reading
its position.

VI.

a) Functions 6 through 254 are not implemented.

b) none
c) HL = number of days (in binary) since 1/1/78

VII.

a)
b)
c)
d)

User Function 255: System Date

A = - 1 ($FF)
HL = number of days (in binary) since 1/1/78
By specifying A = -1, the system date is returned.

701

702

COMMODORE 128

APPENDIX K

PART II

CALLING CP/M BIOS, 8502 BIOS AND

CP/M USER FUNCTIONS IN
Z80 MACHINE LANGUAGE
The Commodore 128 CP/M system allows you to call the CP/M BIOS, 8502 BIOS and
CP/M user functions in your own Z80 assembly language programs. However, in order
to program in Z80 assembly language, you need either an assembler or machine
language monitor. Many Z80 assemblers and monitors are available on the market;
however, the full featured Digital Research CP/M Plus (3.0) system now available on
the Commodore 128 comes with two Z80 assemblers, MAC and RMAC and CP/M plus
documentation. These programs or documentation are not included in the Commodore
128 Personal Computer package; refer to the Commodore 128 System Guide for information on obtaining them.
Assuming you have the MAC and RMAC assemblers, you can now enter and
assemble Z80 assembly language programs. At this point, this reference guide must
make a substantially large assumption about its readers and their knowledge of Z80
assembly language programming. As you probably agree, this reference guide could not
possibly introduce Z80 machine language and thoroughly cover it. That is simply
beyond the scope of this book, considering how voluminous it is already. Your trusty
local bookstore undoubtedly offers several excellent books on Z80 programming. See
"Suggestions for Further Reading" for a few Z80 book titles.
Now that all the assumptions are out of the way, here's how to call a Z80 user or
BIOS function. First, the user function call.

CALLING A CP/M SYSTEM USER FUNCTION

As you saw in Part I of this appendix, certain user functions had subfunctions, others
did not. User function 4 is the 8502 BIOS call function. The 8502 BIOS functions have
13 (-1-11) subfunctions which perform the machine level 8502 input and output
routines. Do not confuse the 8502 BIOS with the CP/M BIOS. The CP/M BIOS comes
standard with every CP/M Plus system regardless of the hardware running it. Remember
that CP/M was designed to be transportable from one microcomputer to another. Each
different microcomputer has its own machine level input and output which it must
perform. The 8502 BIOS is completely hardware-dependent and will only run on the
Commodore 128's 8502 microprocessor.
Another way of understanding the difference between the two BIOS types is

APPENDIXES

recalling the CP/M jump vector on page 677 of Appendix K. The first 30 jumps (0-29)
are direct calls to CP/M BIOS routines. Jump number 30 is the call to the user functions, of
which user function 4 is the 8502 BIOS. The 8502 BIOS is a subset of the CP/M user
functions. The user function call is 1 of 31 system routine calls within the CP/M BIOS
jump table.
The following example calls user function 2 the keyscan function. The calling
routine starts at "waitkey" and the subroutine starts at "user$fun".
MVI useroffset,30
waitkey:
MVI A,2
CALL user$fun
INR B
JZ waitkey
DCR B

; load A reg. with function no. 2

;calls subroutine user$fun
;increment Btest for - 1 if no key is pressed
;jump to wait key if none
;decrement B if B not equal to 0
;this restores original matrix value

Rest of Program

user$fun
PUSH H
LHLD 1
MVI L, useroffset * 3
XTHL
RET

;place HL reg. pair on stack

;load address ofjump vector 1 (WBOOT) into HL
;get offset of 90 (30*3) to L
;exchange HL with top of stack
;jump to new HL pointer location of routine

First, the main program loads the user function number (2) into the A register. To
call a user function, place the required input parameter, the user function number, in the
A register. If a subfunction is going to be called, like in user function 4 (8502 BIOS), the
input parameter for the subfunction number must be placed in L.
The second instruction in the main routine is a CALL to the subroutine user$fun.
However, in this example of the keyscan user function, the returned value B is - 1 if
no key is pressed. If this is the case, B is incremented to zero and the main program
jumps to waitkey and scans the keyboard again. Otherwise, the rest of the program
continues processing.
When the subroutine is called, the first instruction saves the HL register pair, the
address pointer, on top of the stack. The next instruction loads memory location 1 (low)
and 2 (high) into register pair HL. The high byte points to the page number that the
jump vectors are on and the low byte is always 3 (Jump #1 the warm boot vector). Next
the jump number times 3 is loaded into the low byte (L) of register pair HL. This adds the
offset of 90 memory locations to base address of the CP/M BIOS jump table, which now
points to jump number 30, USERF.

703

704

COMMODORE 128

The XTHL instruction exchanges the HL register pair with the top of the stack.
This places the computed address on the top of the stack and the entry values of HL
back in HL. When the RETurn instruction is reached by the Z80, program control is
therefore passed to the USERF vector, entry 30 in the CP/M BIOS jump table. When
the function has completed, control returns to the instruction immediately following the
CALL User$Fun instruction (INR B).
In order for the routines to be called successfully, the proper required input
parameters must be placed in the appropriate registers. The user function number must
be placed in the A register, the subfunction number is placed in L, if any. Additional
inputs must be placed in the correct register or variable prior to calling the user function.
The above example calls user function 2, the keyscan function. To call any other
user function, load the subfunction number into the A register. To call a subfunction,
load the L register with a subfunction number on the beginning of the main (calling)
program as follows:
MVI L, subfun
The way this program is written, the value in L, which you will load at the beginning
of the program with the above instruction, is placed back in L from the stack when the
XTHL is reached at the end of the subroutine. Use this example as a template when
calling other subfunctions. Make sure the proper inputs are present in the correct
locations prior to calling the user function.

CALLING A CP/M BIOS ROUTINE

Making a direct BIOS call is different from calling a user function. User function calls
always enterjump number 30 in the CP/M BIOS jump table. A direct BIOS call enters
any of the first 30 (0-29) jump vectors. These are the input and output routines that are
a part of any CP/M system on any microcomputer. The standard method of calling a
CP/M BIOS routine is via BIOS function 50. This function handles the banking of the
two 64K RAM banks in the C128.
You could call a CP/M BIOS routine similar to the first example, but there is a
limitation. With the user function call method, you are only able to call BIOS routines
that reside in RAM bank 1. The TPA resides in bank 1, while the Z80 function code is
stored in RAM bank 0. If you try to call a direct BIOS routine in bank 0, the system will
crash because bank 1 is in context. This is why it is important to make direct
CP/M BIOS calls through user function 50. Refer to the Digital Research CP/M Plus
documentation for more details on user function 50.
Here's a program example that illustrates how to call a CP/M BIOS function.
main
MVI C,50
LXI D,bios$pb
CALL 5

;store function no. 50 in reg. C

;load immediate a 16 bit pointer in DE
;standard BIOS call

APPENDIXES

Rest of Program

RET
bios$pb:
db FUNNUM
db AREG
dw BCREG
dw DEREG
dw HLREG

;BIOS variable table

;BIOS function no. variable
;temporary A reg. storage
;temp BC reg. pair storage
;ternp DE reg. pair storage
;temp HL reg. pair storage

The first instruction in the main routine stores the function number 50 in the C
register. The system expects the input parameter C to be the BIOS function number. The
next instruction loads the address of the BIOS variable table bios$pb into register pair
DE. The third instruction calls BDOS function 50 through the call BDOS vector, the
standard BIOS vector through which all direct BIOS functions are called. BDOS
function 50 manipulates the banking in and out of RAM banks 0 and 1. This is the
recommended way of directly calling a CP/M BIOS function over that of the first
example which is designed primarily for calling user functions.
The variable table "bios$pb" contains the necessary input parameters required for
BDOS function 50. The "db" 's stand for a byte of storage (like .byte in 8502) while the
"dw" 's stand for a 16 bit word (like .word in 8502).
This appendix is the only section of the book that crosses the Z80 programming
barrier. It at least points you in the right direction and gives you the "hooks" into the
machine level routines of the CP/M system. For more detailed Z80 programming
information see the "Suggestions for Further Reading" at the back of the book. For
more detailed CP/M information, refer to the Digital Research CP/M Plus documentation.

MFM DISK FORMATS

The abbreviation MFM stands for Modified Frequency Modulation. This type of disk
format is variable and programmable according to the specifications of the particular
computer manufacturer.
The Commodore 128 CP/M system supports four standard MFM disk formats. These
four formats constitute the majority of CP/M software formats available on the market.
This does not mean that the Commodore 128 CP/M system can read every single CP/M
disk format in the universe; however, the majority of available CP/M software can run
on the Commodore 128, if the particular application is not hardware dependant.
The four major formats that are supported are as follows:
a)
al)
b)
bl)
c)
d)
e)

Epson QX10 (double sided)

Epson QX10 (double sided)
IBM-8 (single sided)
IBM-8 (double sided)
KayPro IV (double sided)
KayPro II (single sided)
Osborne (single sided)

705

706

COMMODORE 128

Each of these formats is compatible with the Commodore 128 CP/M system. At
the present time, the system cannot format these disk types and successfully use them on
the host system, but they can be used on the C128 system. This portion of the system
is still in development.
The following table lists the parameters that these disk formats are looking for
when reading third party CP/M software.

Manufacturers
a

al

bl

Disk Type

DSDD

SSDD

DSDD

SSDD

SSDD

DSDD

DSDD

Starting pos. (t/s)

2/1

1/1

0/10

1/0

3/1

2/1

1/1

Sector size (bytes)

256

512

512

512

1024

512

512

Number of sec/trk

32

10

10

20

Number of tracks

40

40

80

40

40

40

80

Block alloc size

2048

1024

2048

1024

1024

2048

2048

# of dir entries

128

64

128

64

64

128

64

# of resvd tracks

SS = single sided
DS = double sided
DD = double density
MFM Disk Format Table

NOTE: Epson (a) labels sector numbers 1 through 16. The other Epson
QX10 format (al) labels sectors from 1 to 10. Both the top and bottom of
the disk are labeled the same way.
IBM (b) labels sector numbers 1 through 8. Both the top and
bottom of the disk are labeled the same way.
KayPro IV and KayPro II (c and d) label sector numbers 0 through
9 on top and 10 through 19 on the bottom.
These values are taken from the MFM table. The vector at $FD46 holds the
pointer to the start of the table labeled MFM$table. In the current system, these are the
formats that are read and write compatible on the Commodore 128 CP/M Plus system.
The following is a listing of the MFM format table:

APPENDIXES

db
db
dw
dpb

S256*2 + (16*2-8) +1
MFM + S256 + TypeO + CO + S1
0
256,32,40,2048,128,2

; 256 byte sect, 16 sect/trk

; DSDD
;start on track 2 sect 1 (2 alc)
; sect# 1 to 16

db
db

16
<Epson QX10'

; (top and bottom numbered the same)

;1 Epson QX10

db
db
db
dw
dpb

80h + S512*2 + (10*2-8) + 1

S256*2
MFM + S512 + TypeO + CO + S1
0
512,20,40,2048,128,2

;512 byte sect, 10 sect/trk

;track 0 is 256 bytes/sector
; DSDD
;start on track 2 sect 1 (2 aic)
;sect# 1 to 10

db
db

10
<Epson QX10'

;(top and bottom numbered the same)

;2

db
db
dw
dpb

S512*2 + (8*2^) + l
MFM + S512 + Type2 + CO + S1
0
512,8,40,1024,64,1

;512 byte sect 8 sect/trk

; SSDD
;start on track 1 sector 1 (2 alc)
;sect# 1 to 8

db
db

8
' IBM-8 SS'

;3

db
db
dw
dpb

S512*2 + (8*2-8) + 1
MFM + S512 + Type2 + CO + S1
0
512,8,80,2048,64,1

512 byte sect 8 sect/trk

DSDD
start on track 1 sector 1 (1 alc)
sect# 1 to 8

db
db

8
' IBM-8 DS'

; (top and bottom numbered the same)

;4

db
db
dw
dpb

S512*2 4- (10*2-8) + 0
MFM + S512 + Typel + C1 + SO
0
512,10,80,2048,128,1

db
db

10
'KayPro IV'

db
db
dw
dpb

S512*2 + (10*2-8) + 0
MFM + S512 + TypeO + C1 + SO
0
512,10,40,1024,64,1

db
db

10
<KayPro IP

MFM Format Table

512 byte sector, 10 sect/trk

DSDD
start on track 0 sector 10 (2 alc)
sect# 0 to 9 on top (even tracks)
; sect# 10 to 19 on bottom (odd traeks)
;;5
512 byte sect, 10 sect/trk
SSDD
start on track I sector 0 (4 alc)
sect# 0 to 9
;
;6

707

708

COMMODORE 128

db
db
dw

S1024*2 + (5*2-8) + 1
MFM + S1024 + Type0 +
0

dpb

1024,5,40,1024,64,3

db
db

5
'Osborne DD'

MFM Format Table (continued)

; 1024 byte sect, 5 sect/trk

; SSDD
; start on track 3 sector 1 (2 alc)
; sect# 1 to 5
9
;7

APPENDIXES

APPENDIX K

PART III

THE CP/M SYSTEM MEMORY MAP

The following pages contain the Z80 CP/M memory map for the Commodore 128.
The memory map includes all the key CP/M locations, vectors and variable tables.
Use it as a guide through the Z80 CP/M system within the Commodore 128.
The CP/M memory map is available as a disk file "CXEQU.LIB" on the disk
that comes with the computer.

709

710

COMMODORE 128

$*MACRO
false
true
banked
EXTSYS
pre$release

equ
equ
equ
equ
equ

; start at Jan 1,1978

dt$hx$yr
equ
1985
date$hex
equ
date

macro
db
endm

not false
true
false
; use external system as disk and char I/O
false
78 79 80 81 82 83 84
365+365+366+365+365+365+366
1 2 3 4 5 6 7 8 9 10 11 12
dt$hx$yr+31+28+31+30+31+30+31+31+30+31+30+6

'6 Dec 85'

; boot memory map (bank 0 only)

bios02
block$buffer
boot$parm

equ
equ
equ

3000h
3400h
3C00h

uses 2K
uses about 256 bytes

0000h
1000h
1000h
1400h
2400h
2600h
2C00h
3000h
4000h

I/O page only (I0$0 selected)

3 256 byte blocks (allow 4)
2 X 80 X 25 = 4000
allow 0.5K of parameters
1.5K
lK
0c80h (allow 4K)
start of free area in bank 0

; bank 0 low memory map

ROM
VIC$color
SYS$key$area
screen$40
B&NK$parm$blk
BIOS8502
VIC$screen
ccp$buffer
bank0$free

equ
equ
equ
equ
equ
equ
equ
equ
equ

mapped I/O locations

VIC
SID
MMU
DS8563
VIC$C$H
VIC$C$L
CTAl
CIA2
USART
RAM$dsk$base

equ
equ
equ
equ
equ
equ
equ
equ
equ
equ

0D000h
0D400h
0D500h
0D600h
0D800h
01000h
0DC00h
0DD00h
0DE00h
0DF00h

8563
(memory mapped only in I0$0)
{memory and i/o mapped in I0$0)
6526
6526
6551 (extrn card)
8726

Common memory allocation

int$block
parm$block
@buffer

equ
equ
equ

0PC00h
0FD00h
0FE00h
0FF00h

;
;
;
;

mode 2 interrupt pointers (to FDFDh)

system parameters
disk buffer (256 bytes)
to 0FFFFh used by 8502

the following are Cl28 system equates

enable$z80
return$z80
enable$6502
return$6502

equ
equ
equ
equ

0FFD0h
0FFDCh
0FFE0h
0FFEEh

vic$cmd
vic$drv
vic$trk

equ
equ
equ

parm$block+l
vic$cmd+l
vic$drv+l

8502 code
Z80 code
1st byte used as Intterrupt pointer
; bios8502 ccmmand byte
bios8502 drive (bit 0 set, drv 0)
; bios8'502 track #

APPENDIXES

vic$sect
vic$count
vic$data
cur$drv
fast

equ
equ
equ
equ
equ

vic$trk+l
vic$sect+l
vic$count+l
vic$data+l
cur$drv+l

; bios8502 sector #
b.ios8502 sector count
; bios8502 data byte to/from
current disk installed to Vir. drive
bit 0 set, drv 0 is fast. ect.

key$tbl
fun$tbl
color$tbl$ptr
fun$offset
sound$l
sound$2
sound$3

equ
equ
equ
equ
equ
equ
equ

fast+1
key$tbl+2
fun$tbl+2
color$tbl$ptr+2
fun$offset+l
sound$l+2
sound$2+2

; pointer to
; pointer to
; pointer to
; function #
; unused

equ
equ

sound$3+2
@trk+2

@trk
@dma

keyboard table
function table
logical color table
to be prepormed

;; current track number

j; current DMA address

; below here not used by ROM

@sect
@cnt
@ cbnk
@dbnk
@adrv
@rdrv
ccp$count
stat$enable

equ
equ
equ
equ
equ
equ
equ
equ

emulation$adr equ
usart$adr
equ
; CXIO equates
int$hl
equ
int$stack
equ
user$hl$temp
equ
hl$temp
equ
de$temp
equ
a$temp
equ
source$bnk
equ
dest$bnk
equ
MFM$tbl$ptr
equ
; 1st release end
prt$conv$l
equ
prt$conv$2
equ
key$FX$function equ
XxD$config
equ

@dma+2
@sect+2
@cnt+1
@ cbnk+1
@dbnk+l
@adrv+l
@rdrv+l
ccp$count+l

stat$enable+l
emulation$adr+2

current sector number

record count for multisector transfer
bank for processor operations
bank for CMA operations
currently selected disk drive
controller relative disk drive
number of records in the CCP
status line enable
7 kybrd, key codes(1), functions(0)
6 40 column tracking on(0), off(l)
0 disk stat, enable(l), disable(0)
address of current emulation
pointer to USART (6551) register

usart$adr+2
int$hl+2+20
int$stack
user$hl$temp+2
hl$temp+2
de$temp+2
a$temp+l
source$bnk+l
dest$bnk+l

interrupt HL hold location

currently only 5*2 used
user function HL hold location
misc temp storage (used by VECTOR)
misc temp storage (used by VECTOR)
misc temp storage (used by VECTOR)
inter bank move source bank #
inter bank move dest bank #
pointer to MFM table

MFM$tbl$ptr^2
prt$conv$l+2
prt$conv$2+2
key$FX$function+2
bit 7 0 = no parity
1 = parity
bit 6 0 = mark/space 1 = odd/even
bit 5 0 = space/even 1 = mark/odd
; bit 1 0 = 1 stop bit 1 = 2 stop bits
bit 0 0 = 7 data bits 1 = 8 data bits

RS232$status

equ

XxD$config+l

xmit$data
recv$data

equ
equ

RS232$status+l ; data byte to send

xmit$data+l
; received data byte

bit
bit
bit
bit
bit
bit
bit
bit

1,
6,
5,
4,
3,
2,
1,
0,

l=send data, 0=no data

l=sending data
l=recv que active
l=parity error
l=framing error
l=recv over run (no used)
l=receiving data
l=Data byte ready

The following equates are used by the interrupt driven keyboard handler

711

712

COMMODORE 128

int$rate

equ

recv$data+l

1st byt.e is a pointer into table, 2nd to 12th byte represent

the keyboards current state (active low), NOTE: only
current if key$buffer is not full
key$scan$tbl

equ

int$rate+l

keyboard roll over buffer

key$buf$size
key$get$ptr
key$put$ptr
key$buffer

equ
equ
equ
equ

8*2
; must be an even number of bytes
key$scan$tbl+12
key$get$ptr+2
key$put$ptr+2

software UART recv buffer

RxD$buf$size
RxD$buf$count
RxD$buf$put
RxD$buf$get
RxD$buffer
tick$vol
'

INT$vector
;==> 40 column
temp$l
@off40
cur$offset
old$offset
prt$flg
flash$pos
;==> 40 column
paint$size
char$adr$40
char$col$40
char$row$40
attr$40
bg$color$40
bd$color$40
rev$40

equ
equ
equ
equ
equ
equ
equ

64
key$buffer+key$buf$size
RxD$buf$count+l
RxD$buf$put+l
RxD$buf$get+l
RxD$buffer+RxD$buf$size
tick$vol+l

equ

0FDFDh

;;; contains
; (in common

misc parm
BANK$parrn$blk
equ
equ
temp$l+2
equ
@off40
equ
@off40+2
equ
old$offset+l
equ
prt$flg+l
position and color storage
equ
flash$pos+2
equ
paint$size+l
equ
char$adr$ 4 0+ 2
char$col$40+l
equ
equ
char$row$40+l
equ
attr$40+l
equ
bg$color$40+l
equ
bd$color$40+l

;==> 80 column position and color storage

char$adr
equ
rev$40+l
char$col
equ
char$adr+2
char$row
equ
char$col+l
current$atr
equ
char$row+l
equ
current$atr+l
bg$color$80
equ
bg$color$80+l
char$color$80
ROM uses localtions above this point
==> Bnulation parameters
equ
parm$base
char$color$80+l
equ
parm$base+2
parm$area$80
ds
2
ds
1
parm$area$80+3
parm$area$40
equ
2
ds
1
ds
buffer$80$col equ
parm$area$40+3

80 column exec$adr
80 column row #
40 column exec$adr
40 column row #

;==> CXIO parameters

;
int$count not used by releases past 10 Oct 85
int$count
qu
buffer$80$col+40*2
; one added every l/60th sec
key$buf
ev i
int$count+l

APPENDIXES

;=> CXKEYS parameters

key$down$tbl
equ
key$buf+l
; not used any more (int code)
;;;;; free space above, new interrupt driven code does not require this space
; control$keys equ
key$down$tbl+ll*2 ; byte, not used any more (irit code)
commodore$mode equ
key$down$tbl+ll*2
msgptr
equ
commodore$mode+l
of fset
equ
msgptr+2
cur$pos
equ
offset+1
string$index
equ
cur$pos+l
; 1st release end (3 June 85)
sys$freq
equ
string$index+l
; 2nd release end (1 Aug 85)
;
equ
sys$freq+l
;=> temp ROM
blk$ptr$cnt
load$count
ld$blk$ptr
blk$unld$ptr
block$size
block$end
block$ptrs
info$buffer
ext$num
retry
boot$stack
;

boot data storage

32
equ
equ
; number of 128 byte blocks to load
boot$parm
equ
; current sector dma pointer
load$count+2
equ
; read memory block (lk,2K) pointer
ld$blk$ptr+2
equ
blk$unld$ptr+2 ; block size (1K=32 or 2K=64)
equ
; allow 48K cpm.sys to load
block$size+l
equ
; end of block load buffer (+lK or +2K
block$end+2
equ
block$ptrs+blk$ptr$cnt
; CPM3.sys load aar's and counts
equ
info$buffer+12 ; CPM3.SYS current ext #
equ
ext$num+l
equ
retry+l+64
; allow 64 bytes of stack
equ
boot$stack

;=> special equates used by CXKI

special
equ
00010111b
SF$exit
equ
001h
SF$insert
equ
028h
SF$delete
equ
02Bh
alpha$toggle
equ
03Dh
alt$key
equ
050h
SF$left
equ
055h
lf$arrow
equ
055h
SF$right
equ
056h
rt$arrow
equ
056h
buff$large
buff$small
buff$pos

; -l=50Hz, 0=60Hz

equ
equ
equ

RETURN KEY
PLUS KEY
MINUS KEY

cctTTOodore key

alterant key
left arrow key
left arrow key
right arrow key
right arrow key

25
7
7

;==> External RS232 interface controls

rxd$6551
equ
USART+0
; read
txd$6551
equ
USART+0
; write
status$6551
equ
USART+1
; read
reset$6551
equ
USART+1
; write
command$6551
equ
USART+2
; read/write
control$6551
equ
USART+3
; read/write
txrdy
equ
10h
rxrdy
equ
08h
cmd$init
equ
0bh
no parity, enable txd + rxd, interrupts
cntr$init$19200 equ
lFh
1 stop, 8 bits, 19200 baud
cntr$init$9600 equ
lEh
1 stop, 8 bits, 9600 baud (internal)
cntr$init$600 equ
017h
600 baud
;-=> memory management loactions
rrmu$start
equ
MMU
equ
conf$reg
MMU
equ
conf$reg$l
MMU+1
conf$reg$2
equ
MMU+2
conf$reg$3
equ
MMU+3
conf$reg$4
equ
MMU+4
mode$reg
equ
MMU+5

;
;
;
;
;
;

3eh
3fh
7fh
3eh
7eh
blh

713

714

COMMODORE 128

ram$reg
page$0$l
page$0$h
page$l$l
page$l$h
mmu$version

equ
equ
equ
equ
equ
equ

MU+6
MMU+7
MMU+8
MMU+9
MMU+10
MMU+11

;
;
;
;
;
;

enable$C64
z80$off
z80$on
fast$rd$en
fast$wr$en
common$4K
common$8K
comnnon$16K

equ
equ
equ
equ
equ
equ
equ
equ

11110001b
10110001b
10110000b
Z80$on+0
Z80$on+8
09h
0ah
0bh

; FS=0

;==> preconfiguration
force$map
equ
equ
bank$0
bank$l
equ
io
equ
io$0
equ
io$l
equ

maps
0ff00h
0ff01h
0ff02h
0ff03h
0ff03h
0ff04h

Obh 16K top Ccnmon

00h
01h
01h
01h
??h

; value to be write to enable 8502

;
;
;
;
;

fast serial read

fast serial write
top 4K ccmmon
top 8K ccmmon
top 16K ccmmon

;
;
;
;
;

3fh
7fh
3eh
3eh
7eh

; = > 80 column display equates

DS$index$reg
equ
DS8563
DS$status$reg equ
DS8563
DS$data$reg
equ
DS8563+1
; = > register pointers
DS$cursor$high equ
14
DS$cursor$low equ
15
DS$rw$ptr$high equ
18
DS$rw$ptr$low equ
19
DS$rw$data
equ
31
DS$color
equ
26
; = > status bits
DS$ready
equ
80h
DS$lt$pen
equ
40h
;==> display memory layout (16K) 0-3fffh
DS$screen
equ
0000h
DS$attribute
equ
0800h
DS$char$def
equ
2000h
= > VIC equates
vic colors
black
equ
equ
white
red
equ
cyan
equ
purple
equ
green
equ
blue
equ
yellow
equ
equ
orange
brown
equ
lt$red
equ
equ
dark$grey
med$gray
equ
lt$green
equ
equ
lt$blue
equ
lt$grey
RM$status
bit 7
6
5
note: bits
4
3-0

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

equ
RAM$dsk$base
;read only register
Interrupt pending if 1
Transfer complete if 1
Block verify error if 1
5-7 are cleared when read
128K if 0, 512K if 1
Version #

APPENDIXES

RM$ccmrrand
bit 7
6
5
4
3,2
1,0

equ
RAM$dsk$base+l ;r/w
execute per current config. if set
reserved
enable auto reload if set (restores all register to
value before command was done, else point to
next byte to read/write.)
disable FF00 decode if set (do operation after command writen)
reserved
00 = transfer Cl28 > Ram Disk
01 = Transfer C128 < Ram Disk
10 = swap
Cl28 <-> Ram Disk
11 = Verify Cl28 = Ram Disk

RM$128$low
equ
RAM$dsk$base+2 ;r/w
bits 0 to 7 of C128 address
RM$128$mid
equ
RAM$dsk$base+3 ;r/w
;
bits 8 to 15 of the Cl28 address
RM$ext$low
equ
RAM$dsk$base+4 ;r/w
;
bits 0 to 7 of Ram Disk address
RM$ext$mid
equ
RAM$dsk$base+5 ;r/w
bits 8 to 15 of Ram Disk address
RM$ext$hi
equ
RAM$dsk$base+6 ;r/w
bit 16
of Ram Disk address if 128K version
;
bits 16 to 18 of Ram Disk address if 512K version
RM$count$low
equ
RAM$dsk$base+7 ;r/w
;
low byte transfer count (bits 0-7)
RM$count$hi
equ
RAM$dsk$base+8 ;r/w
;
hi byte transfer count (bits 8-15)
RM$intr$mask
bit 7

equ
RAM$dsk$base+9 ;r/w
l=enable chip interrupts
l=enable end of block interrupts
l=enable verify error interrupts

RM$control
bit 7,6

equ
00
01
10
11

RAM$dsk$base+10 ;r/w
Increment both addresses
Fix expansion address
Fix Cl28 address
Fix both addresses

;==> CIA equates

Data$a
Data$b
Data$dir$a
Data$dir$b
timer$a$low
timer$a$high
timer$b$low
timer$b$high
tod$sec$60
tod$sec
tod$min
tod$hrs
sync$data
int$ctrl
cia$ctrl$a
cia$ctrl$b
CIA$hours

equ
equ
equ
equ
equ
equ
equ
equ
equ
equ
equ
equ
equ
equ
equ
equ
equ

00h
01h
02h
03h
04h
05h
06h
07h
08h
09h
0ah
0bh
0ch
0dh
0eh
0fh
CIAl+tod$hrs

key$row

equ

Cml+Data$a

(default)

715

716

COMMODORE 128

key$col
VTC$key$row

equ
equ

CIAl+Data$b
0d02fh

input
output

data$hi
data$low

equ
equ

RS232 data line HI

RS232 data line LCM

lf$shift$key
rt$shift$key
commodore$key
control$key

equ
equ
equ
equ

80h
10h
20h
04h

type$lower
type$upper
type$shift
type$cntrl
type$field

equ
equ
equ
equ
equ

0
1

bnkl
pageO
pagel

1
0
1

equ
equ
equ

MMU$tbl$M
db
db
db
endm

3
00000011b

macro
3fh,3fh,7fh,3eh,7eh
z 8 0 $on,common$ 8K
pageO,bnkl,pagel,bnkl

; config reg's
; mode & mem
; page reg's

ROM functions
TJMP

macro x
rst 2 ! db x
endm

TCALL

macro x
mvi l,x ! rst 4
endm
macro x
rst 3 ! db x
endm
macro x
mvi l,x ! rst 5
endm

FR$40

equ

offset to 40 column RQM functions

FR$wr$char
FR$cursor$pos
FR$cursor$up
FR$cursor$dcwn
FR$cursor$left
FR$cursor$rt
FR$do$cr
FR$CEL
FR$CES
FR$char$ins
FR$char$del
FR$line$ins
FR$line$del
FR$color
FR$attr
FR$rd$chr$atr

equ
equ
equ
equ
equ
equ
equ
equ
equ
equ
equ
equ
equ
equ
equ
equ

00h
04h
08h
0Ch
10h
14h
18h
lCh
20h
24h
28h
2Ch
30h
34h
38h
3Ch

D=char auto advance

B=row, C=column

FR$wr$chr$atr

equ

40h

FR$rd$color
;FR$wr$color
;

equ
equ
equ

44h
48h
4Ch

B=color
B=bit to set/clear, C=bit value
in D=row, E=col
out H=row, L=col, B=char, C=attr(real)
in D=row, E=col, B=char, C=attr(real)
out H=row, L=col

APPENDIXES

FR$trk$sect
FR$check$CBM
FR$bell

equ
equ
equ
equ
equ
equ
equ
equ

50h
52h
54h
56h
58h
5Ah
5Ch
5Eh

FR$trk$40
FR$set$cur$40
FR$line$paint
FR$screen$paint
FR$prt$msg$both
FR$prt$de$bot.h
FR$update$it

equ
equ
equ
equ
equ
equ
equ
equ

60h
62h
64h
66h
68h
6Ah
6Ch
6Eh

equ
equ
equ
equ
equ
equ
equ
equ

70h
72h
74h
76h
78h
7Ah
7Ch
7Eh

'

FR$ASCII$to$pet
FR$cur$adr$40
FR$cur$adr$80
FR$look$color
;
FR$blk$fil1
FR$blk$move
FR$char$inst

HL passed on the stack

fixed RQM locations

R$cmp$hl$de
R$write$memory
R$read$memory
R$set$update$adr
R$wait

equ
equ
equ
equ
equ

100h-6
180h+0
180h+3
180h+6
180h+9

R$status$color$tbl
R$color$convert$tbl

equ
equ

1000h-246-16
1000h-230-16

Disk type byte definition

bit

0=GCR,

l=MFM

if bit 7 is
6
5,4
3,2,1
0

1 (MFM)
C0=0,
C1=1
(side 2 #, 0 to (n/2)-l or n/2 to n-1)
00=128, 01=256, 10=512, 11=1024 byte/sector
disk type (MFM)
starting sector # ( 0 or 1)

if bit 7 is
6
5,4
3,2,1

0 (GCR)
unused (set to 0)
always 01 (256 byte sectors)
disk type (GCR)
TypeO = none, set track and sector as passed
Typel = C64 type disk
Type2 = C128 type disk
unused (set to 0)

0
MFM
C0
C1
Cl$bit
TypeO

equ
equ
equ
equ
equ

1*128
0*64
1*64
6
0*2

Typel

equ

1*2

Type2

equ

2*2

2nd side start at begining

2nd side continues from first
(MFM) top, bottom then next track
(TRK# 0 to (34 or 39))
(MFM) top (trk 0 even), bottom (trk 1 odd)
(TRK# 0 to (69 or 79))
(MFM) top TRK# 0 to 39, bottom TRK# 40 to 79
(TRK# on back start at 39 and go to 0)

717

718

COMMODORE 128

Type7

equ

7*2

TypeX

equ

7*2

S0
S1

equ
equ

0*1
1*1

S128
S256
S512
Sl024

equ
equ
equ
equ

0*16
1*16
2*16
3*16

; (MFM) pass the byte values supplied in ^trk

;
and vsect

; start at sector 0
; start at sector 1

dsk$none
dsk$c64
dsk$cl28

equ
equ
equ

TypeO+S256
Typel+S256
Type2+S256

dir$track

equ

18

access to any sector on the disk

; C64 disk dir track

6510 commands
vic$reset
vic$init
vic$rd
vic$wr
vic$rdF
vic$wrF
vic$test
vic$query
vic$prt
vic$frmt
vic$user$fun
vic$RM$rd
vic$RM$wr

equ
equ
equ
equ
equ
equ
equ
equ
equ
equ
equ
equ
equ

-1
0
1
2
3
4
5
6
7
8
9
10
11

control charactors
eom
bell
bs
lf
cr
xon
xoff
esc

equ
equ
equ
equ
equ
equ
equ
equ

00h
07h
08h
0ah
0dh
llh
13h
lbh

reboot C128
initilize the bios8502
read one sector of data (256 bytes)
write one sector of data
set-up for fast read (many sectors)
set-up for fast write
test current disk in drive
get start sectors and #sector/trk
print data character
format a disk (1541)
;: RAM disk read
;: RAM disk write

APPENDIXES

H t4 fa s
3 Z rt U o
.
23 Oo
X
^fa ^ 2 uX
X 0
H ^ oS Ou fHe ^g 5^ ^
H O J J O p 3 ffi
<
CQ CQ CQ uV u V
o w g p: ov ^ p^ y

NUR U
h^O^On
rr fN
rrO
rq
<*> r^5^t n^tnxQ

ft
Z 5
ft
W^
<*
g<w a ^ a <
l^juyH
p*rth x
w z j < o o ~ <<%H
x x S z
H
<
w
fa
fa
o
< CQ CQ CQ CQ C
uQu u u u
fe ^g ^,
r-
^^ fc

ft
feU* u Urr> r^i
U*

||sg

J ?
tt
^
O O a2? S
s
go S
g r t g ^ S
fa ss J <2 rt
u
ig fa
i iQi tt9^ Sg sO3^ iHl ^ cj Q
w w 3 ^
gywK^ o
ft
fa X CQ U U X
5^?5^SuQjS <
Zcn< O rt rt rt fa
O O U> << < X c^ c^ cU
J
fa
fa
fa
fa
fa
u U U ft ft ft ft ft ft ft
rt oo n oo
<2^ ^^ S2 ^ Q
r
fa
P >
^ nr- ^H
ft
| ftfaSS
1 ft
2
S fa

fa
fa

U^^ f^
CQ M ti
zq
x
S 3 9rt z
cw
S Cti 5 ^ftgs K< O
z^
S
.. z.. < H H U c^
O
u uOvrt u>^ft<ftWft c^ ft

UJ
w
rt
C
2
^
z<
CQ

^-

rt
00
u,
j
^
J H O Sa
u.
p
^
5o

CQ
^oB
s
n ^
n ^ i ^ - s
oy R^R S S ^ g
03 CQ CQ CQ CQ U U U U

rt
1
s
o?Sg
%%%i
X
HZH
X
u. Xu.Pu.>:s
(fe

ft p so QO ^t 00

U U
^tmfM r^
^H
Os
-

fS

so
00
r- rSo r-f^Qfav+

^t
p Tt 5
f ^ PO fa <N ft

H
U H
w J zp
c
CQ 5
H
HZH
rt P Z
fafa
a
05
o
8fa
| Sn

rt
so c^
^ i;
ry^ O
S5^
rt a c^ S rt O C
C
>< JcQ>^KMS H
HG
w 0J ;
ffi < H < ^ U U 5
H
j rtu.rtLi.rt L
{u :
ft uz ax u*

>H
u
^ X
rt
^
HW^
0 0
hW
^r ^H
MN
t
^ sS
"

0a
^t
s
rt <J gJ fOt -Z <Os^ ^H^^ ^ rt
rt

ft
O <N
H
0
0
W
O
Z
S
g
>
<
rt
55
^r
fa
^ fa tn
rt 5 5 p< w 0 a
00
X VH O g ta H rt ^ H rt so g;
^ X O xn
j
S
S
z
z
rt
H
S
3
<
<
U
H Z u Q u:
O O O O O 5 < Wu ^4 rt
fa < 0
z
U U U U U Uftft c^ cn ^fi
< CQCQS CQ
ft ft ft
fe ^n fN

2>^ fe
O ^O<N^ y^ W g CQ <N rt vi n ^
^
^
i

U
^

SO
~
0
-> C
u-x "nTt'<s
^t
fMrrN ftS8^8^rSg
Un rq fe

0
u:
rt
a
z
0
V

fS _
s , s
s i |
3S^
< H c^
ZX<
UJ a U.
R ^rTi0CgQ
H
fe
U^j
U. r

S
CQ
U
^
u
J
UJSK
u u
rt rt
b u.

H H H rt rt

S 5 S ^ 5^ H
S5 hfe
rt 5 cQ 15 c*53
sOS^ w
sHgSS^" urtgP
^5
^u j^Zrt
ft^ H
uK^^t O
Lb
purt
Q< Q^ 0^|tfX
u. u- a U- u,

U <N Tt
^H ^^ v<o U
f^ fN
^0
3

^ 3
^
O
&
WH2
w
fe>^8
^ rt
Z pHg2z g O c^
H t
Z
W
Q a ^ 5 ^
^s <
Q S^
s
Suus<rt g
C J PC D
^USrt
H C^ u H
< CQ U U 3
^ft ft
C*)ftc n S
< X X X X trt
uj u< u* u.fcfa M
0 0r~ut^far- V U
U *H 2
rrfa C
f^Q C
00
PQ000 T
^^ S
Q
<N
T

nf
ftX

u
H
P
x
c WS5
OC0ffiH
^ ^ WH
rt H H 5
^ < < ^n
V ft ft ft

719

<

<

rt
<
a a.
^rt ^a
^ d
fa
x
S ta^
Pfa

fa
a
0
H
x
fa JUi
c^ sg * ^Z
<s
J
O
2
fa
rt

fa CDU NN
O
rt iTi H
EC fa
SO iriW
D
rt
fa^ 00 & , O o C
O i s w
O ^fa ^ Srt
Z
w
fa
g
*
H
3
^3
S
w H
O
ftH c^ fa0
>w <
. e s ftO^S
fart 9 a u^ Ss fa
^ ^
H
_ x ft^ fa# H
OfaO fa O 0^fa
^ 0a. fe
<
us
^
< 3 JZ c^
z
rt rt fa < fa f^irtr 3fa u
^ ^grt Spftw
H
3ffl p ^ i S
^ J P V^ S> fa ^CQ2 5;; p 5g fa
H O< < ^> 5 rt S ux 5!VI
g

rt
S ^ tfO
TtCiQ
( Uu u fa O
u" 3 p l
^ 0 0 fa C
S
z
z
rt
h
h
$
u
5
z
u
fa
0_ j l l
Pu Z< 0 ^ ^ rt ^ U. ffi^:
. , 0_
rt
_ fa
rt
t fa
rt fa
rt rt
< c^ &n cCzZ}5 ^2S
fa
fa<.fa
rtfartfartfart rt rt
J C n cQ CQ CQ CQ ;Uu u u u u 0u u0 u0 u^ <Jj
ft ft ft ft ft ft ft
fa fafafaO
< CQ
< rr ^ TT r^
r-
Q S g o g S g fa 00

CQ Cw
^so
rsi r- r<5so c00so
so U
SO w)

u urT)
r
1 fa far^t r<i
i |fa n*t <s
*>1 ^ 1 S w
0
Q g<Ngftwft?cq8 8 10 8 ft

720

aa
2
u
03

COMMODORE 128

Z
>>%2
ta
c
^
Jg^ugs^u

^
z
so

a ^ ^s
taO X
a Hu w
C w>
S o W f i * < * 5 W
?
s * L4 - S ^. O 0.ta& a a
a
W<
g o {j a 5
__,tata
O
ta O
ta ota Str)g| gwgo5wSn o ta Q
Z <3 Hi *** < i O^a
>

H
*
O
- ptaa
2
ta
-Q
^ ta
S
nS
J
aSfe5<*
o - E h ^ 5 S c j ta ^g^P^^tao
I l
S <ptaEH^^g|gOta2
3
S

H x x S tagSQ ^S |a go ^ >* ^M8s 2s ga 3a sa lx l g

tf tf tf tt ffi C^ CZ) c H H H H > > > > > > X ^ ^-

SO ^r m
fiQ r-^Urr^
r^ g so g 5 ^
ir^
taQ <^2i
S2HHr4X ^
0
0 0 o
Q ta 0 0 Q
Q ^ ta tatac^

H
H

z
ta
O
>
ta J ^
Z
^
U a >? H H
O
g I
0
4
^
^ zh S
u Q~
*^ S
H
H
ta
*
<Hta9ata52 >

ta
ta
ta
<
H
^i
a
zMtaW <^Uj. ^,
2j A ta c p ta P
< ^5 O te ^
^nS^S>
< ta x u fc Q 5 fe ^ 3 2 9 ^ 5
31gg353giggii
H PQfeM w s w S E 3 8 ^ a s i ^
>< >- ><fta ^ o o as H o H s K g - S g
: ^Ha>>>a>a >s X
| | ^' ^
fc w wta H g J < < a u w S S o 05 S M S ft SH8HgHg H
2 a g * ta j S o 2 S a a a a a
o ta 00
*r> < f^taj>> SO^ ^<t?2rT)
r ^ i i s s i s ^ 2 S

22 G *^
Q ^Q ^
p $ p p g 5 Utata
Q ta tatatata
ta r* ta ta O Q c* n c^ o r*^ Qta
ta
a
H i*

w OO
X
5
o
ta
^ta
^

3
a ^tar^ta
ooaf^5t
Q
ta2oE^HgHugw
ta H O H
r^
^ Z 04 rjj c^
S ^ rj ]C4 rj z H < t ^ ta H X Z,
Vm
J,
<*^
ta >N ft 55
^
tata5 Z d ^ S B ^ H Dtata
-y O
,_
ta r^i
^J_T^P
a ^>>iTi
T)^ta
r^R^ta
ao<Ojn^<ShH5
wwwSz^
ta
z 5aj &
s ta
ta o
UUitflH&OttS
5
2S
9Q
tata
g
g 53
g iH8 HS H
& Hf cH a>a>a>a>a>| ^i lNi ^vSft ft

^
ta
0
5
2
^H ^ta >^
H
H
^
^t aO Hw04
fc
S^ ^>,
^
&
O
ta
r
^K-2^o
S|
0
4
rj
WdtaHtaMfc,
^
^
taSng^gta
>
<
ta
o
L
J
taflQ
05
ta
ta O
Q
U ta s y s s g s i
"8*
X
^ se 5^ &; ^7taa r^ J^ y^ WtataLT> ^ ^ ro
<
>< >
Pfe
ga
H 2ta
E
tataH
gP
<S
< xH <staQta>, ^ & 0^4 ! g g y y y y 2 g ^
5 2 * tadtataS S S o4 & !o5P4( 04 04
1
t^ (T) r? ^ 4^f( ^ ^ A. O
O n#s 00 SO ^> A 00 ^04 55ftftCfl K H H H Hta> > > > > N ^ ^
<s so ^ta*r ov g o rt 5 ^
ataUQgQ3gQ3tata
00
S00g g o
^ &
<^S
gS2l gg^ E ii ^
g S
i
S^g
taw S^ feta
taS*H
ta tata
tataQta ta<-i ^ ta O ^ O Q

gsg

a
>
a^Q
H
ta o ta< >N 1 N
^K>U1
ata
ta05
rfta ffi
^w o
N H tf
V
<
S
|
a
S
|
a H
Q^
O

B
a

^
N

V
ft
<
X
^o
O
a
2^j ftS &^
ta ta HQ Z 0taa u o
Htata ta
,ta^ o l | | a ta
05,
*H ta H i i a g ^ o ^
S tata
H SX s J s ^ g S >^S^
^ a ata
w^Q
a >< ta
ta5 u ^ ^ ^ S o
HtaW^?
s J535
H
ffi
Q
Q
o
o
a
t
;
e
|
S
2
S
ta
cfl
^
&

g
Q
H
y 5 hH 29 i | ^ 5 S | wtaS S a c HX X ^ ta g H >^ S O>< a^ ^ y y y y ^ w ^ ^ : ;
a a a a ^ ta
S 2 S ^tata
c^ O
c^<fi & H HH Hta > > > > > > ^ S
g ^, a.tataaa a a a a
00 ^ n
I U ^ 2^5^taoo^
9 2 fegw ^ y < ^ _
^ S s p:* " 5
SQ
ta Tf
r> Q !
>dp
ptau r^
:taotaur^ r <
ta r*
; ta

Q
^QO
ta&
Q
Qtatata22

tatatau
W

APPENDIXES

721

APPENDIX L

COMMODORE 128 SYSTEM SCHEMATICS

The following eight pages contain the full system schematics for the Commodore 128.
Each two-page spread represents one full-size engineering schematic sheet. For easier
readability, the right edge of the left-hand page and the left edge of the right-hand page
have portions of the schematic that are duplicated. This overlap is provided so you can
read the circuit diagram from either half of the two-page spread, then move to the
adjacent page and pick up where you left off from the point where the opposite page
ends. The arrow at the top of each page provides a frame of reference to mark the
portion of the diagram that is overlapped.

722

COMMODORE 128

APPENDIXES

723

724

COMMODORE 128

APPENDIXES

725

726

COMMODORE 128

APPENDIXES

J_

1/0 CONKfECTOR

MQTEi:

^ \

LOW

JEND

ONJLV

fa

H I G H EKJO

ONLV

I/O Control Ports, Keyboard,

User Port, Serial Port, Cassette Port
SC SCHEMATIC 310378
1

727

728

COMMODORE 128

APPENDIXES

C/?S .0/pf

, j r ^ ,

RAM, ROM
SCHEMATIC 310378

729

GLOSSARY

This glossary provides brief definitions of frequently used computing terms.

Acoustic Coupler or Acoustic Modem: A device that converts digital signals to
audible tones for transmission over telephone lines. Speed is limited to about 1200
baud, or bits per second (bps). Compare Direct Connect Modem.
Address: The label or number identifying the register or memory location where a unit
of information is stored.
Alphanumeric: Letters, numbers and special symbols found on the keyboard, excluding graphic characters.
ALU: Arithmetic Logic Unit. The part of a Central Processing Unit (CPU) where
mathematical operations are performed.
Animation: The use of computer instructions to simulate motion of an object on the
screen through gradual, progressive movements.
Array: A data storage structure in which a series of related constants or variables is stored
in consecutive memory locations. Each constant or variable contained in an array
is referred to as an element. An element is accessed using a subscript. See
Subscript.
ASCII: Acronym for American Standard Code for Information Interchange, which is a
seven-bit code used to represent alphanumeric characters. It is a useful communication code for such things as sending information from a keyboard to the
computer, and from one computer to another. See Character String Code.
Assembler: A program that translates assembly language instructions into machine
language instructions.
Assembly Language: A machine-oriented language in which mnemonics are used to
represent each machine language instruction. Each CPU has its own specific
assembly language. See CPU and Machine Language.
Assignment Statement: A BASIC statement that sets a variable, constant or array
element to a specific numeric or string value.
Asynchronous Transmission: A communication scheme in which data characters are
sent at time intervals, independent of the system clock. Limits phone line transmission to about 2400 baud (bps). See Synchronous Transmission.
Attack: The rate at which the volume of a musical note rises from zero to peak volume.
Background Color: The color of the portion of the screen that the characters are
placed upon.
731

732

COMMODORE 128

BASIC: Acronym for Beginner's All-purpose Symbolic Instruction Code.

Baud: A unit of serial-data transmission speed. The term was originally used for
measuring telegraph transmission speed. Three hundred baud is approximately
equal to a transmission speed of 30 bytes, or characters, per second.
Binary: A base-2 number system. All numbers are represented as a sequence of 0s and
ls.
Bit: The abbreviation for Binary digIT. A bit is the smallest unit in a computer's
memory. Each binary digit can have one of two values, 0 or 1. A bit is referred to
as set or " o n " if it equals 1. A bit is clear or " o f f " if it equals 0.
Bit Control: A means of transmitting serial data in which each bit has a significant
meaning and a single character is surrounded with start and stop bits.
Bit Map Mode: An advanced graphic mode in the Commodore 128 in which you can
control every pixel on the screen.
Border Color: The color of the edges around the screen.
Branch: To jump to a section of a program and execute it. GOTO and GOSUB are
examples of BASIC branch instructions.
Bubble Memory: A relatively new type of computer memory, it uses tiny magnetic
"pockets" or "bubbles" to store data.
Burst Mode: A special high-speed mode of communication between a 1571 disk drive
and a C128 computer, in which information is transmitted at many times the speed
of the 1541 Disk Drive.
Bus: Parallel or serial lines used to transfer signals between devices. Computers are
often described by their bus structure (i.e., S-100-bus computers, etc.).
Bus Network: A system in which all stations or computer devices communicate by
using a common distribution channel or bus.
Byte: A group of 8 bits that make up the smallest unit of addressable storage in a
computer. Each memory location in the Commodore 128 contains 1 byte of
information. One byte is the unit of storage needed to represent one character in
memory. See Bit.
Carrier Frequency: A constant signal transmitted between communicating devices
that is modulated to encode binary information.
Character: Any symbol on the computer keyboard that is printed on the screen.
Characters include numbers, letters, punctuation and graphic symbols.
Character Memory: The area in Commodore 128's memory that stores the encoded
character patterns that are displayed on the screen.
Character Set: A group of related characters. The Commodore 128 character sets
consist of upper case letters, lower case letters and graphic characters.
Character String Code: The numeric value assigned to represent a Commodore 128
character in the computer's memory.
Chip: A miniature electronic circuit that performs a computer operation such as
graphics, sound and input/output.
Clock: The timing circuit for a microprocessor.
Clocking: A technique used to synchronize the sending and receiving of data that is
modulated to encode binary information.
Coaxial Cable: A transmission medium, usually employed in local networks.

GLOSSARY

Collision Detection: Determination of collision between two or more sprites or

between sprites and data.
Color Memory: The area in the Commodore 128's memory that controls the color of
each location in screen memory.
Command: A BASIC instruction used in direct mode to perform an action. See Direct
Mode.

Compiler: A program that translates a high-level language, such as BASIC, into

machine language.
Composite Monitor: A device used to provide the C128 40-column video display.
Computer: An electronic, digital device that inputs, processes, and outputs information.
Condition: Expression(s) between the words IF and THEN, in an IF . . . THEN
statement, evaluated as either true or false. The conditional IF . . . THEN
statement gives the computer the ability to make decisions.
Coordinate: A single point on a grid having vertical (Y) and horizontal (X) values.
Counter: A variable used to keep track of the number of times an event has occurred in
a program.
CPU: Acronym for Central Processing Unit, the part of the computer containing the
circuits that control and perform the execution of computer instructions.
Crunch: To minimize the amount of computer memory used to store a program.
Cursor: The flashing square that marks the current location on the screen.
Data: Numbers, letters or symbols that are input into the computer and are to be
processed.
Database: A large amount of related data stored in a well-organized manner. A
database management system is a program that allows access to the information.
Data Link Layer: A logical portion of data communications control that mainly
ensures that communication between adjacent devices is error-free.
Data Packet: A means of transmitting serial data in an efficient package that includes
an error-checking sequence.
Data Rate or Data Transfer Rate: The speed at which data is sent to a receiving
computergiven in baud, or bits per second (bps).
Datassette: A device used to store programs and data files sequentially on tape.
Debug: To correct errors in a program.
Decay: The rate at which the volume of a musical note decreases from its peak value to
a midrange volume called the sustain level. See Sustain.
Decrement: To decrease an index variable or counter by a specific value.
Dedicated Line or Leased Line: A special telephone line arrangement supplied by
the telephone company, and required by certain computers or terminals, whereby
the connection is always established.
Delay Loop: An empty FOR . . . NEXT loop that slows the execution of a
program.
Dial-Up Line: The normal switched telephone line that can be used as a transmission
medium for data communications.
Digital: Of or relating to the technology of computers and data communications
where all information is encoded as bits of ls or 0s that represent on or off
states.

733

734

COMMODORE 128

Dimension: The property of an array that specifies the size and direction along an axis
in which the array elements are stored. For example, a two-dimensional array has
an X-axis for rows and a Y-axis for columns. See Array.
Direct Connect Modem: A device that converts digital signals from a computer into
electronic impulses for transmission over telephone lines. Contrast with Acoustic
Coupler.
Direct Mode: The mode of operation that executes BASIC commands immediately after
the R E T U R N key is pressed. Also called Immediate Mode. See Command.
Disable: To turn off a bit, byte or specific operation of the computer.
Disk Drive: A random access, mass-storage device that saves and loads files to and
from a floppy diskette.
Disk Operating System: A program used to transfer information to and from a disk.
Often referred to as a DOS.
Duration: The length of time a musical note is played.
Electronic Mail, or E-Mail: A communications service for computer users in which
textual messages are sent to a central computer, or electronic "mailbox," and
later retrieved by the addressee.
Enable: To turn on a bit, byte or specific operation of the computer.
Envelope Generator: Portion of the Commodore 128 that produces specific waveforms (sawtooth, triangle, pulse width and noise) for musical notes. See Waveform.
EPROM: A PROM that can be erased by the user, usually by exposing it to ultraviolet
light. Abbreviation for Erasable Programmable Read Only Memory. See PROM.
Error Checking or Error Detection: Software routines that identify, and often
correct, erroneous data.
Execute: To perform the specified instructions in a command or program statement.
Expression: A combination of constants, variables or array elements acted upon by
logical, mathematical or relational operators that return a numeric value.
File: A program or collection of data treated as a unit and stored on disk or
tape.
Firmware: Computer instructions stored in ROM, as in a game cartridge.
Frequency: The number of sound waves per second of a tone. The frequency corresponds to the pitch of the audible tone.
Full-Duplex Mode: In this mode, two computers can transmit and receive data at the
same time.
Function: A predefined operation that returns a single value.
Function Keys: The four keys on the far right of the Commodore 128 keyboard. Each
key can be programmed to execute a series of instructions. Since the keys can be
SHIFTed, you can create eight different sets of instructions.
GCR: The abbreviation for Group Code Recording, a method of storing information on
a disk. The 1541 and 1571 disk drives can read, write and format GCR disks.
Graphic Characters: Nonalphanumeric characters on the computer's keyboard.
Graphics: Visual screen images representing computer data in memory (i.e., characters, symbols and pictures).
Grid: A two-dimensional matrix divided into rows and columns. Grids are used to
design sprites and programmable characters.

GLOSSARY

Half-Duplex Mode: In this mode, data can be transmitted in only one direction at a
time; if one device is sending, the other must simply receive data until it's time for
it to transmit.
Hardware: Physical components in a computer system, such as the keyboard, disk
drives and printer.
Hexadecimal: Refers to the base-16 number system. Machine language programs are
often written in hexadecimal notation.
Home: The upper-left corner of the screen.
IC: The abbreviation for Integrated Circuit. A silicon chip containing an electrical
circuit made up of components such as transistors, diodes, resistors and capacitors. Integrated circuits are smaller, faster and more efficient than the individual
circuits used in older computers.
Increment: To increase an index variable or counter with a specified value.
Index: The variable counter within a programming loop.
Input: Data fed into the computer to be processed. Input sources include the keyboard,
disk drive, Datassette or modem.
Integer: A whole number (i.e., a number containing no fractional part), such as 0, 1,
2, etc.
Interface: The point of meeting between a computer and an external entity, whether an
operator, a peripheral device or a communications medium. An interface may be
physical, involving a connector, or logical, involving software.
I/O: The abbreviation for Input/Output. Refers to the process of entering data into the
computer, or transferring data from the computer to a disk drive, printer or storage
medium.
Keyboard: Input component of a computer system.
Kilobyte (K): 1024 bytes.
Local Network: One of several short-distance data communications schemes typified
by common use of a transmission medium by many devices at high-data speeds.
Also called a Local Area Network, or LAN.
Loop: A program segment executed repetitively a specified number of times.
Machine Language: The lowest-level language the computer understands. The computer converts all high-level languages, such as BASIC, into machine language
before executing any statements. Machine language is written in binary form, which
a computer can execute directly. Also called machine code or object code.
Matrix: A two-dimensional rectangle with row and column values.
Memory: Storage locations inside the computer. ROM and RAM are two different
types of memory.
Memory Location: A specific storage address in the computer. There are 131,072
memory locations (0-131,071) in the Commodore 128.
MFM: The abbreviation for Modified Frequency Modulation, a method of storing
information on disks. The 1571 disk drives can read and write to MFM disks.
Microprocessor: A CPU that is contained on a single integrated circuit (IC). Microprocessors used in Commodore personal computers include the 6510, the 8502 and
the Z80.
Mode: A state of operation.

735

736

COMMODORE 128

Modem: The acronym for MOdulator/DEModulator. A device that transforms digital

signals from the computer into analog electrical impulses for transmission over
telephone lines, and does the reverse for reception.
Monitor: A display device resembling a television set but with a higher-resolution
(sharper) image on the video screen.
Motherboard: In a bus-oriented system, the board that contains the bus lines and edge
connectors to accommodate the other boards in the system.
Multi-Color Bit Map Mode: A graphic mode that allows you to display one of four
colors for each pixel within an 8 by 8 character grid. See Pixel.
Multi-Color Character Mode: A graphic mode that allows you to display four
different colors within an 8 by 8 character grid.
Multiple-Access Network: A flexible system by which every station can have access
to the network at all times; provisions are made for times when two computers
decide to transmit at the same time.
Null String: An empty character (""). A character that is not yet assigned a character
string code. Produces an illegal quantity error if used in a GET statement.
Octave: One full series of eight notes on the musical scale.
Operating System: A built-in program that controls everything a computer does.
Operator: A symbol that tells the computer to perform a mathematical, logical or
relational operation on the specified variables, constants or array elements in the
expression. The mathematical operators are + , - , *, / and f . The relational
operators are < , = , > , < = , > = and < > . The logical operators are AND,
OR NOT and XOR.
Order of Operations: Sequence in which computations are performed in a mathematical expression. Also called Hierarchy of Operations.
Parallel Port: A port used for transmission of data 1 byte at a time using 8 data lines,
one for each bit.
Parity Bit: A 1 or 0 added to a group of bits that identifies the sum of the bits as odd or
even, for error checking purposes.
Peripheral: Any accessory device attached to the computer such as a disk drive, printer,
modem orjoystick.
Pitch: The highness or lowness of a tone that is determined by the frequency of the
sound wave. See Frequency.
Pixel: Computer term for picture element. Each dot that makes up an image on
the screen is called a pixel. Each character on the screen is displaced within
an 8 by 8 grid of pixels. The entire screen is composed of a 320 by 200 pixel
grid. In bit-map mode, each pixel corresponds to a bit in the computer's
memory.
Pointer: A register used to indicate the address of a location in memory.
Polling: A communications control method used by some computer/terminal systems
whereby a "master" station asks many devices attached to a common transmission rnedium, in turn, whether they have information to send.
Port: A channel through which data is transferred to and from the CPU.
Printer: Peripheral device that outputs the contents of the computer's memory onto a
sheet of paper. This paper is referred to as a hard copy.

GLOSSARY

Program: A series of instructions that direct the computer to perform a specific task.
Programs can be stored on diskette or cassette, reside in the computer's memory,
or be listed on a printer.
Program Line: A statement or series of statements preceded by a line number in a
program. The maximum iength of a program line on the Commodore 128 is 160
characters.
Programmable: Capable of being processed with computer instructions.
PROM: The acronym for Programmable Read Only Memory. A semiconductor memory
chip whose contents can be changed.
Protocol: The rules under which computers exchange information, including the
organization of the units of data to be transferred.
Random Access Memory (RAM): The programmable area of the computer's memory
that can be read from and written to (changed). All RAM locations are equally
accessible at any time in any order. The contents of RAM are erased when the
computer is turned off.
Random Number: A nine-digit decimal number from 0.000000001 to 0.999999999
generated by the RaNDom (RND) function.
Read Only Memory (ROM): The permanent portion of the computer's memory. The
contents of ROM locations can be read, but not changed. The ROM in the
Commodore 128 contains the BASIC language interpreter, character-image patterns and the operating system.
Register: Internal storage compartments with the microprocessor that communicate
between system ROM, RAM, and themselves.
Release: The rate at which the volume of a musical note decreases from the sustain
level to 0.
Remark: Comments used to document a program. Remarks are not executed by the
computer, but are displayed in the program listing.
Resolution: The fineness of detail of a displayed image, determined by the density of
pixels on the screen.
RGBI Monitor: A high-resolution display device necessary to produce the C128 80column screen format. RGBI stands for Red/Green/Blue/Intensity.
Ribbon Cable: A group of attached parallel wires, usually made up of 25 lines for
RS-232 communication.
Ring Network: A system in which all stations are linked to form a continuous loop or
circle.
RS-232: A recommended standard for electronic and electromechanical specifications for
serial communication. The Commodore 128 parallel user port can be treated as a
serial port if accessed through software, sometimes with the addition of an
interface device.
Screen: A video display unit, which can be either a television or a video monitor.
Screen Code: The number assigned to represent a character in screen memory. When
you type a key on the keyboard, the screen code for that character is entered into
screen memory automatically. You can also display a character by storing its
screen code directly into screen memory with the POKE command.
Screen Memory: The area of the Commodore 128's memory that contains the information displayed on the video screen.

737

738

COMMODORE 128

Serial Port: A port used for serial transmission of data; bits are transmitted one bit
after the other over a single wire.
Serial Transmission: The sending of sequentially ordered data bits.
Software: Computer programs (set of instructions) stored on disk, tape or cartridge that
can be loaded into random access memory. Software, in essence, tells the computer what to do.
Sound Interface Device (SID): The MOS 6581 sound synthesizer chip responsible
for all the audio features of the Commodore 128.
Source Code: A nonexecutable program written in a higher-level language than
machine code. A compiler or an assembler must translate the source code into an
object code (machine language) that the computer can understand.
Sprite: A programmable, movable, high-resolution graphic image. Also called a Movable Object Block (MOB).
Standard Character Mode: The mode the Commodore 128 operates in when you
turn it on and when you write programs.
Start Bit: A bit or group of bits that identifies the beginning of a data word.
Statement: A BASIC instruction contained in a program line.
Stop Bit: A bit or group of bits that identifies the end of a data word and defines the
space between data words.
String: An alphanumeric character or series of characters surrounded by quotation
marks.
Subroutine: An independent program segment separate from the main program that
performs a specific task. Subroutines are called from the main program with the
GOSUB statement and must end with a RETURN statement.
Subscript: A variable or constant that refers to a specific element in an array by its
position within the array.
Sustain: The midranged volume of a musical note.
Synchronous Transmission: Data communications using a synchronizing, or clocking, signal between sending and receiving devices.
Syntax: The grammatical rules of a programming language.
Tone: An audible sound of specific pitch and waveform.
Transparent: Describes a computer operation that does not require user intervention.
Variable: A unit of storage representing a changing string or numeric value. Variable
names can be any length, but only the first two characters are stored by the
Commodore 128. The first character must be a letter.
Video Interface Controller (VIC): The MOS chip (8564) responsible for the 40-column
graphics features of the Commodore 128.
Voice: A sound-producing component inside the SID chip. There are three voices
within the SID chip so the Commodore 128 can produce three different sounds
simultaneously. Each voice consists of a tone oscillator/waveform generator, an
envelope generator and an amplitude modulator.
Waveform: A graphic representation of the shape of a sound wave. The waveform
determines some of the physical characteristics of the sound.
Word: Number of bits treated as a single unit by the CPU. In an 8-bit machine, the
word length is 8 bits; in a 16-bit machine, the word length is 16 bits.

INDEX
A
Abbreviations, 670-673
ABS, 73
Accumulator, 127-129
addressing, 138
loading, 147-148
ACPTR, 4 2 2 - 4 2 3
A D C , 162
Addition, 19
Addressing
absolute, 138-139, 143
accumulator, 138
immediate, 138
implied, 139
indexed, 141-143, 144-145
indirect, 143-145
modes, 137, 141-142
relative, 140-141
16-bit, 133-135
table, 161-179
zero-age, 139, 142
ALT Mode, 497
A N D , 152, 162
A P P E N D , 27
Arithmetic
instructions, 151-152
operations, 18-20
Arrays, 13, 16-18
ASC, 73, 660-662
ASL, 163
Assembler, 126-127
A T N , 73
AUTO, 27

B
BACKUP 27-28
B A N K , 28
BASIC
advanced programming techniques,
103-107
color RAM in C128, 218
color RAM in C64, 218-219
C128 bit map mode, 221
crunching of programs, 95
C64 bit map mode, 222
C64 character modes, 222
entering machine language subroutines through, 198-202
error messages, 644-647
intelligent use of, 97
mixed with machine language,
198-205
placement of machine language
routines with, 203-205
relocating, 106
screen memory in C128, 215-217
screen memory in C64, 217

BASIN, 423-433
BCC, 163
BCS, 163
BEGIN/BEND, 2 8 - 2 9
BEQ, 164
BIOS (Basic Input Output System),
486-489, 500, 677-683, 7 0 4 705
BIT, 153-154, 164
Bit map mode 112, 221, 222
data, 241-243
80-column (8563) chip, 314-320
multi-color, 243-245
standard, 239-243
standard sprites, 283-284
video matrix, 240-241, 244
Bits
masking, 97-98
16-bit addressing, 133-135
values in a byte, 9 8 - 9 9
BLOAD, 29
BMI, 164
BNE, 164
BOOT, 29-30, 446-447
BOX, 30, 113-114
BPL, 165
BRK, 165
BSAVE, 31
BSOUT, 433
Buffer
control block, 685
routine, 93
BUMP, 73-74
Bus
architecture, 560-562
color data, 562
display, 562
expansion, 635-637
loading, 567-568
multiplexed address, 561
processor, 560
serial, 633-634
shared address, 561-562
translated address, 560-561
BVC, 165
BVS, 165

C
Cassette connector, 398
C A T A L O G , 31
C H A R , 31-32, 115
Character mode
accessing character R O M , 229
character memory, 226-229,
234-235
color data, 225-226, 235-237
color memory, 226

C128 BASIC, 2 1 9 - 2 2 0
C64 BASIC, 222
multi-color, 2 3 3 - 2 3 7
programmable characters, 230-233
screen location, 224, 234
screen memory data, 224-225
standard, 2 2 3 - 2 3 3
CHKIN, 4 2 9 - 4 3 0
CHR$, 74, 660-662
CIA (6526) chip, 6 1 1 - 6 2 3
control registers 6 2 2 - 6 2 3
description, 611, 6 1 8 - 6 2 2
electrical characteristics, 613-615
interface signals, 6 1 5 - 6 1 6
interrupt control, 6 2 1 - 6 2 2
serial port, 620-621
timing, 616-617, 6 1 8 - 6 2 0
CINT, 410, 414
CIOUT, 423
CIRCLE, 32-33, 115-116
C K O U T 430-431
CLALL, 439
CLC, 166
CLD, 166
CLI, 166
CLOSE, 33, 4 2 8 - 4 2 9
CLOSE ALL, 443
CLR, 33
CLRCH, 4 3 1 - 4 3 2
CLV, 166
C M D , 33
CMP, 167
CMPSTA, 456
COLLECT, 34
COLLISION, 34, 267
C O L O R , 34-35, 116-117
Color mode
extended background, 237-239
memory map, 664
sprites, 283-285
See also Memory, color RAM
Commands, 12
basic, 27-72
CP/M, 481-482, 483
format, 2 5 - 2 7
graphics, 113-122
machine language monitor, 186-194
sprites, 267-270
summary, 674675
See also specific commands
Commodore 128. See C128 Mode
Commodore 64. See C64 Mode
Complex Interface Adapter. See CIA
(6526) chip
CONCAT, 3 5 - 3 6
C128 Mode, 2 - 3 , 5
BASIC bit map mode, 221

739

740

INDEX

C128 Mode (continued)

character memory, 219-220
character set availability, 222
color RAM in BASIC, 218
CP/M disk format, 493-494
memory map, 502-540
ROM cartridge, 4 7 1 - 4 7 2
screen memory in BASIC, 215-217
switching from mode to mode, 6
using C64 function key values, 95
Configuration Register. See Memory
Connectors, 652-657
Constants, 12-15
floating-point, 13
integer, 13
string, 14-15
C O N T , 36
Control codes, 666-668
C O P Y , 36
COS, 74
CP/M, 676
BIOS routines, 677-683, 704-705
calling user function, 702-704
commands, 481-482, 483
control characters for line editing,
482, 484
copies of disks and files, 482, 485
disk organization, 491-495
enhancements, 479
files, 479-481, 482, 485
keyboard scanning, 496-497
memory map, 709 -720
mode, 4
requirements for system, 478
switching from mode to mode, 7
system layout, 486-487
system memory organization,
489-491
system operations, 500
system release, 8
CPX, 167
CPY, 167
C64 Mode, 3, 5, 444
BASIC bit map mode, 222
BASIC character modes, 222
color RAM in BASIC, 218-219
CP/M disk format, 4 9 2 - 4 9 3
input/output assignments, 546-554
memory map, 540-554
ROM cartridge, 472
screen memory in BASIC, 217
switching from mode to mode, 7
using function key values, 95
Cursor, 313-314, 326

D
Daisy wheel printer, 378
DATA, 36
Datassette, 389-390
Data structures, 684-685
DCLEAR, 37
DCLOSE, 37
Debugging. See Programming
DEC, 168
D E F FN, 37
DELETE, 38
Device numbers, 457
DEX, 168

DEY, 168
DIM, 38
DIRECTORY, 3 8 - 3 9
Directory, 375
Disk drive
copies, 482, 485
device number, 378
directory, 375
formatting, 372-373
replacing files or programs, 374
retrieving files or programs, 375-376
saving programs, 373-374
verifying files or programs,
374-375
Disk Parameter Block, 685
Division, 19-20
DLCHR, 450
DLOAD, 39
DMA CALL, 444-445
DO/LOOP/WHILE/UNTIL/EXIT, 39^40
DOPEN, 40
DOS errors, 101, 648-651
Dot matrix printer, 378-379
D R A W , 41, 117-118
Drive Table, 684-685
DSAVE, 41
DVERIFY, 42

E
Editor. See Screen editor
80-column (8563) chip, 292-334
bit map mode, 314-320
Block Write and Block Copy,
312-313, 333
characters, 296-297, 301-304, 325,
328, 333
cursor, 313-314, 326
display, 299-301, 326, 327-334
frames, 297-299
RAM, 304-305, 309-313, 327-334
registers, 304-309, 324-334
scrolling of screen, 320-323,
328-331
8502 microprocessor, 569-574
description, 569
electrical specification, 569-571
processor timing, 571-574
END, 42
ENVELOPE, 42, 336-337, 347-348
Environmental specifications, 568
EOR, 152, 168
Errors
BASIC messages, 644-647
DOS, 101. 648-651
functions, 101
logic, 99
syntax, 99
tracing of, 101
trapping of, 100
See also Programming, debugging
Escape codes, 669
Exponentiation, 20
Expressions, 18
arithmetic, 18
string, 24

F
FAST, 43

FETCH, 43
Files
CP/M, 479-481
creating and storing, 376-378
disk drive, 374-376
merging, 106-107
FILTER, 43, 337-338, 348-351
FNxx, 74
FOR/TO/STEP/NEXT, 44
FRE, 75
Function keys
changing, 95
programming, 94
using C64 values, 95
Functions, 7 2 - 8 6
errors, 101
user, 685-704
See also specific functions

G
GET, 4 4 - 4 5
G E T # , 45
GETCFG, 452
GETIN, 4 3 8 - 4 3 9
G E T K E Y , 45
G 0 6 4 , 45
GOSUB, 45-46
GOTO/GO TO, 46
GRAPHIC, 46, 119
Graphics
commands, 113-122
power behind, 208-263
programming, 110-122
system, 215-223
GSHAPE, 46, 119-120

H
Hardware
components, 4 - 5
specifications, 556-641
system architecture, 557-558
See also specific components
HEADER, 47
HELP, 47
HEX$, 75
Hexadecimal notation, 136-137

I
IF/THEN/ELSE, 4 7 - 4 8
INC, 169
INDFET, 4 5 4 - 4 5 5
INDSTA, 455
INPUT. 48
I N P U T # , 49
Input/output, 5, 372-400, 727
BIOS (Basic Input Output System),
486-489, 500, 667-683, 7 0 4 705
controller ports input, 390-393
C64 assignments, 546-554
Datassette output, 389-390
disk drive, 372-376
files, 376-378
modem output, 381
output control, 393-394
pinouts, 394-400
printer output, 378-381
RS-232 channel, 382-388

INDEX

Input/output (continued)
screen outpuut, 388-389
INSTR, 75
Instructions
arithmetic, 151-152
branching, 154-156
compare, 150-151
counter, 148-149
entering machine language in
monitor, 183-184
j u m p , 159-160
logical, 151, 152-153
machine language, 145-179,
183-184
multiple, 96
register to memory, 147-148
registertransfer, 156
return, 160
rotate, 156, 157
set and clear, 158-159
shift, 156-157
stack, 160
table, 161-179
See also specific instructions
INT, 7 5 - 7 6
Interrupt service routine, 2 5 8 - 2 6 3
INX, 169
INY, 169
IOBASE, 442
IOINIT, 4 0 9 - 4 1 0 , 4 1 5 - 4 1 6
IRQ pin, 411-414

J
JMP, 169
JMPFAR, 453-454
JOY, 76
Joysticks, 390-392
JSR, 170
JSRFAR, 4 5 3 - 4 5 4

K
Kernal calls, 414-457
Kernal/Editor flags, 539-540
Kernal j u m p table, 537-539
Kernal routines, 4 0 3 - 4 0 6
K E Y , 49, 4 2 1 - 4 2 2
Keyboard, 640-642, 727
connector pinout, 640-641
scanning, 496-497, 588-589
Keywords. See Reserved system
words

L
L D A , 147-148, 170
L D X , 170
LDY, 171
LEFT$, 76
LEN, 77
LET, 4 9 - 5 0
Light pen, 393, 593
LIST, 50
LISTN, 425
LKULPA, 448-449
LKUPSA, 448-449
L O A D , 50, 434-435
Loading
accumulator, 147-148
bus, 567-568

routine, 9 3 - 9 4
LOCATE, 51, 120
LOG, 77
Logic
errors, 99
instructions, 151, 152-153
Logical operators, 21-22
LSR,171

M
Machine language, 124-179
character memory, 223
color RAM, 219
definition, 124
enteringprograms, 182-195
entering subroutines through
BASIC, 198-202
executing programs, 184-186
instructions, 145-179, 183-184
mixed with BASIC, 198-205
monitor, 127
monitorcommands, 186-194
operand field, 126
operation code field, 125
placement of programs in memory,
202-203
placement of routines with BASIC,
203-205
programming of SID chip, 352-358
screen memory, 217-218
Z80, 702-708
M E M B O T , 420-421
Memory, 4
banked, 208-213, 218, 490
character (ROM), 219-222, 226-229
color RAM, 218-219, 225-226,
236, 238, 243, 245
Configuration Register, 460-463
CP/M system memory organization,
489-491
crunching, 95
dynamic RAM, 624-626
80-column (8563) chip, 299-301,
304-305, 309-313, 327-334
management, 5, 458-471, 583-587
maps, 502-554, 663-664, 709-720
Mode Configuration Register,
465-466
placement of machine language
programs, 202-203
preconfiguration, 462-465
RAM Configuration Register,
467-469
R A M and 80-column (8563) chip,
304-305, 309-313 327-334
RAM organization, 566-567
RAM and system architecture,
557-558, 729
ROM, 627-632
ROM banking, 627
R O M cartridge startup, 471-472
ROM chip, 630, 632
ROM organization, 564
ROM pinout, 629, 631
ROM and system architecture,
557-558, 729
ROM timing, 628
RS-232 channel, 387-388

screen (RAM), 215-218

16K video banks, 210-212
64K RAM banks, 208-210
split-screen mode, 246-247
storage, 12-13, 148
switching banks, 4 5 9 - 4 6 0
system organization, 562-567
See also Character mode
Memory Management Unit (MMU).
See Memory, management
MEMTOP, 419-420
Menu, 92
MFM. See Modified Frequency
Modulation
MID$, 77
Modem, 381
Modified Frequency Modulation
(MFM), 705-708
Module communication, 486-487
MONITOR, 51
Monitor, 388-389
entering machine language programs in, 183-184
field descriptors, 187-188
machine language commands,
186-194
manipulating text within, 194-195
Mouse, 392
Movable object blocks. See Sprites
MOVSPR, 5 1 - 5 2 , 267-268
Multiplication, 19
Music, 336-369
coding a song from sheet music,
341-344
equal-tempered scale values, 366,
607-608
instruments, 336-337
notes, 338-340, 341-343, 366-369
statements, 336-341

N
NEW, 52
Non-Maskable Interrupt (NMI) vector,
407-408
NOP, 160, 171

O
ON, 53
OPEN, 5 3 - 5 4 , 427-428
Operating system, 4 0 2 - 4 7 5
CP/M components, 486
Kernal calls, 4 1 4 - 4 5 7
Kernal routines for programs,
403-406
vectors, 4 0 7 - 4 1 4
Operations
arithmetic, 18-20
hierarchy of, 2 2 - 2 3
string, 24
O R A , 152, 172
Output. See Input/output

P
Paddles, 392
Page pointers, 4 7 0 - 4 7 1
PAINT, 5 4 - 5 5 , 120-121
PEEK,77
PEN,78

741

742

INDEX

Performance specifications, 567-568

PFKEY, 450-451
PHA, 172
PHOENIX, 448
PHP, 172
Pinouts, 394-400
PLA, 172
See also Programmed Logic Array
PLAY, 55-56, 338-339
PLOT, 441
PLP, 173
POINTER, 78
POKE, 56
Ports, 372, 727
controller, 390-393, 398-399
expansion, 399-400
for peripheral equipment, 652-657
serial, 394
user (RS-232 channel), 394-396
See also specific controller devices
POS, 79
POT. 79
PRIMM, 456-457
PRINT, 56, 100
P R I N T # , 57, 380
Printer, 378-380
control, 380-381
daisy wheel, 378
dot matrix, 378-379
PRINT USING, 5 7 - 5 8
Processors, 4, 560
Program counter, 132
Programmed Logic Array, 581-582,
723
Programming
advanced BASIC techniques,
103-107
debugging, 99-101
of 80-column (8563) chip, 292-334
escape, 106
of function keys, 94
graphics, 110-122
of SID chip in machine language,
352-358
Programs
definition, 376
Kernal routines, 4 0 3 - 4 0 6
printing program listing, 379
printing through a program, 380
replacing, 374
retrieving from disks, 375-376
saving, 373-374
verifying, 374-375
PUDEF, 5 8 - 5 9

R
RAM. See Memory
R A M T A S , 416
Raster interrupt split screen program,
248-258
RCLR, 7 9 - 8 0
RDOT, 80
RDTIM, 437
READ, 59
READSS, 426
RECORD, 59-60
Registers, 126
CIA (6526) chip, 622-623

80-column (8563) chip, 304-309,

324-334
8502 microprocessor, 127
8563 video controller, 595
interrupt, 591-592
raster, 591
shadow, 213-214, 539-540
SID chip, 359-365, 528-530
status, 130-132
System Version, 471
VIC chip, 524-527, 591-592
X and Y index, 129-130, 141-143
Relational operators, 20-21
REM, 60, 96
R E N A M E , 60
R E N U M B E R , 60-61
Reserved system symbols, 8 8 - 8 9
Reserved system words, 86-88
RESET, 408
RESTOR, 416-417
RESTORE, 61, 407-408
RESUME, 6 1 - 6 2
RETURN, 62
RGBI video connector, 397-398
RGR, 80-81
RIGHT$, 81
RND, 81
ROL, 173
ROM. See Memory
ROR, 173
RSPCOLOR, 82
RSPPOS, 82
RSPRITE, 83
RS-232 channel, 382-388, 394-396
closing, 385-387
data, 385
memory locations, 387-388
opening, 382-385
sample program, 387
RTI, 174
RTS, 174
RUN, 62
R W I N D O W , 83

S
SAVE, 63, 435-436
SBC, 174
SCALE, 63, 121-122
Schematics, 721-729
SCNCLR, 64
SCRATCH, 64
Screen editor
control codes, 474
escape codes, 473
intermediate storage, 213-214
interrupt-driven, 214-215, 247-248
j u m p table, 474-475
Screen output, 388-389
See also Graphics; Video
Scrolling
of 8563 screen, 320-323, 328-331
of 8564 VIC chip, 593
SCRORG, 440
SEC,175
SECND, 4 1 8 - 4 1 9
SED, 175
SEI, 175
SETBNK, 451

SETLFS, 4 2 6 - 4 2 7
SETMSG, 418
SETNAM, 427
SETTIM, 436-437
SETTMO, 422
SGN, 84
SID (Sound Interface Device) chip,
336, 723
audio input, 351-352
electrical characteristics, 6 0 5 - 6 0 6
envelope generators, 6 0 8 - 6 1 0
filter, 337-338, 348-351, 363
pins, 600, 602-604
programming in machine language,
352-358
registers, 359-365, 528-530
specifications, 599-604
synchronization and ring modulation, 3 5 8 - 3 5 9
and system architecture, 558
timing, 6 0 6 - 6 0 7
SIN, 84
SLEEP, 64, 99
SLOW, 64
SOUND, 65, 339-340
Sound, 5, 336-369
characteristics, 345-348
statements, 336-341
volume, 347
Sound Interface Device. See SID chip
Space elimination, 95
SPC, 84
SPINP, 4 4 2 - 4 4 3
Split-screen mode, 245-248
organization in memory, 246-247
raster interrupt program, 248-258
SPOUT, 4 4 2 - 4 4 3
SPRCOLOR, 6 5 - 6 6 , 2 6 8 - 2 6 9
SPRDEF, 66, 269-270, 276, 279
SPRITE, 6 6 - 6 7 , 272-273
Sprites, 2 6 6 - 2 9 0
adjoining, 274276
collision priorities, 289-290
color, 283-285
commands, 267-270
creation of image, 279-281
creation procedure in definition
mode, 270-274
display priorities, 288-289
enablement, 282
expansion of size, 287-288
inner workings, 279-290
pointers, 281-282
positioning on screen, 2 8 5 - 2 8 7
program examples, 276-278
SPRSAV, 67, 273
SQR, 84
SSHAPE/GSHAPE, 6 8 - 6 9 , 122,
273-274
STA, 175
Stack pointer, 132-133
STASH, 69
Statements, 12
basic, 2 7 - 7 2
format, 2 5 - 2 7
See also specific statements
STOP, 69, 100, 437-438
Storage. See Files; Memory, storage

INDEX

STORE, 148
STR$,84-85
String, 497
STX, 176
STY, 176
Subtraction, 19
SWAP, 69
SWAPPER, 449
Symbols. See Reserved system
symbols
Syntax, 96, 99
Synthesizers, 336
SYS, 69-70
System Control Block, 684
System schematics, 721-729
System Version Register, 471

T
TAB, 85
TALK, 425
TAN, 85
TAX, 176
TAY, 176
Telephones
detecting carrier, 105
programming to be on or off hook,
104-105
ringing, 104
rotary (pulse) dialing, 105-106
TouchTone frequencies, 103-104
TEMPO, 70, 340-341

Text
display, 111-112
manipulation within machine
monitor, 194-195
TKSA, 419
TouchTone frequencies, 103-104
TRAP, 70
Trigonometric functions, 665
TROFF, 70
TRON, 71
TSX, 177
TXA, 177
TXS, 177
TYA, 177

U
UDTIM, 439-440
UNLSN, 424
UNTLK, 424
User functions, 685-704
User number, 480
USR, 85-86

V
VAL, 86
Variables, 12-13, 15-16, 96
VECTOR, 417
VERIFY, 71
VIC chip. See Video, interface
chip
Video, 4, 725

composite connector, 396-397

display codes, 658-659
8563 controller, 595-598
features, 110-112
40/80 column display, 498-499
interface chip, 524-527, 557-558,
588-594, 638-639
RGBI connector, 397-398
16K banks, 210-212
types of screen display, 111-112
VOL, 71, 341

W
WAIT, 71-72
WIDTH, 72, 122
Wildcard characters, 480
WINDOW, 72, 102
Windowing, 102

X
XOR, 86

Z80 microprocessor, 574-580, 685

bus interface, 575
control interface, 575
electrical specifications, 579-580
machine language, 702-708
processor switching, 576-577
signal description, 577-578
system description, 575-577

743

SUGGESTIONS FOR FURTHER READING

Advanced Machine Language on the C64

by Lothar Englisch (Abacus)

The Anatomy of the Commodore 64

by Michael Angerhausen, Dr. Achim Becker, Lothar Englisch, and Klaus Gerits
(Abacus)
Artificial IntelligenceHow

Computers

Think

by F. David Peat (Simon and Schuster)

Basic 64 BASIC

by James Coan (Hayden Publications)

C64 Assembly Language Arcade Game

Programming

by Steve Bress (TAB)

C64 Graphics and Sound

Programming

by Stan Krute (TAB)

The Commodore 64 Programmers

Reference

Guide

by Commodore Business Machines (Howard W. Sams)

The Complete Commodore Inner Space

Anthology

by Karl J.H. Hildon (Transactor Publishing)

Computer

Primer

by Ann Cavanaugh (Trillium Press)

CP/M Bible

by Mitchell Waite and John Angermeyer (Howard W. Sams)

The Digital Research CP/M Plus Programmers

by Digital Research
The Digital Research CP/M Plus System Guide

by Digital Research
The Digital Research CP/M Plus User's Guide

by Digital Research
Inside Commodore

DOS

by Richard Emmers (Reston Publishing)

Introducing 64 Machine

Code

by lan Sinclair (Prentice Hall)

Microcomputer

Graphics

by Roy E. Meyers (Addison-Wesley)

Programming

the 6502

by Rodney Zaks (Sybex)

Z80 and 8080 Assembly Language

by Kathe Spracklen (Hayden)

Programming

Guide