Commodore 128 Programmer's Reference Manual

Commodore 128 is a versatile, multimode computer offering 128K of RAM, expandable to 256K or 640K. It features a powerful 80-column display, compatibility with Commodore 64 software, and CP/M 3.0 operation. This allows you to run a wide range of programs, including word processors, spreadsheets, and databases. The 128 offers enhanced BASIC with over 140 commands and functions, providing improved graphics, animation, sound, and music capabilities. You can even switch between C128, C64, and CP/M modes to access the specific features of each.

PDF

Document

COMMODORE

cfl

Programmer’s

Reference Guide

COMMODORE

BUSINESS MACHINES, INC.

T .M .

B A N T A M

C O M P U T E R

B O O K S

A Bantam Computer Book

COMMODORE 128

PROGRAMMER’S

REFERENCE GUIDE

Bantam Computer Books

Ask your bookseller for the books you have missed

THE AMIGADOS MANUAL by Comm odore-A miga, Inc.

THE MACINTOSH by Bill O ’Brien

TH E APPLE //c BOOK by Bill O ’Brien

TH E COM M ODORE 64 SURVIVAL

M ANUAL by W inn L. Rosch

THE NEW jr.

A GUIDE TO IB M ’S PCjr by Winn L. Rosch

ORCHESTRATING SYMPHONY by The Waite Group/Dan Shafer

COM M ODORE 128 PROG RAM M ER’S

REFERENCE GUIDE by Comm odore Business Machines, Inc.

EXPLORING ARTIFICIAL INTELLIGENCE

ON YOUR APPLE II by Tim Hartnell

EXPLORING ARTIFICIAL INTELLIGENCE

ON YOUR COM M ODORE 64 by Tim Hartnell

EXPLORING THE UNIX ENVIRONMENT by The Waite Group/Irene Pasternack

FRAM EW ORK FROM THE GROUND UP by The Waite G roup/Cynthia Spoor and

Robert Warren

HOW TO GET THE MOST OUT OF

COM PUSERVE, 2d ed. by Charles Bowen and David Peyton

HOW TO GET TH E MOST OUT OF THE

SOURCE by Charles Bowen and David Peyton

PC-DOS/MS-DOS

User’s Guide to the M ost Popular Operating

System fo r Personal Computers by Alan M. Boyd

POWER PAINTING: COMPUTER GRAPHICS

ON THE MACINTOSH by Verne Bauman and Ronald Kidd/ illustrated by Gasper Vaccaro

SMARTER TELECOM M UNICATIONS

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./Michael McCarty

U SER’S GUIDE TO THE AT&T PC 6300

PERSONAL COM PUTER by David B. Peatroy, Ricardo A. Anzaldua,

H. A. W ohlwend, and Datatech Publications

Corp.

C O M M O D O R E 128

PROGRAMMER’S

REFERENCE GUIDE

COM M ODORE BUSINESS MACHINES, INC.

BANTAM BOOKS

TORONTO • NEW YORK • LONDON • SYDNEY • AUCKLAND

CO M M O D O RE 128 PROGRA M M ER S REFERENCE GUIDE

A Bantam Book / February 1986

Commodore 64 and Commodore 128 are registered trademarks o f Commodore

Electronics. Ltd.

CPIM and CPIM Plus Version 3 .0 are registered trademarks o f Digital Research

Inc.

Perfect is a registered trademark o f Perfect Software.

TouchTone is a registered trademark o f AT&T.

WordStar is a registered trademark o f MicroPro International Corporation.

Grateful acknowledgment is made fo r permission to reprint two bars o f Invention

Corp., N ew York.

Book design by Ann Gold.

Cover design by Jo Ellen Temple.

This book may not be reproduced in whole or in part, by mimeograph or any other means, without permission.

For information address: Bantam 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 o f the words “Bantam Books" and the portrayal o f a rooster, is Registered in U.S.

Patent and Trademark Office and in other countries. M arca Registrada. Bantam

Books, In c., 666 Fifth Avenue, New York, New York 10103.

P R IN T E D IN T H E U N IT E D S T A T E S O F A M E R IC A

HL 0 9 8 7 6 5 4 3 2 1

C hapter 1

Introduction

C hapter 2

B A SIC Building Blocks and BASIC 7 .0 Encyclopedia

C hapter 3

O ne Step Beyond Sim ple BASIC

C hapter 4

C om m odore 128 G raphics Program m ing

C hapter 5

M achine Language

C hapter 6

H ow to Enter M achine Language Program s Into the

C om m odore 128

C hapter 7

M ixing M achine Language and BASIC

C hapter 8

The P ow er B ehind C om m odore 128 G raphics

C hapter 9

Sprites

C hapter 10

Program m ing the 80-Colum n (8563) Chip

C hapter 11

S ound and M usic on the C om m odore 128

C hapter 12

Input/O utput G uide

109

123

181

197

207

265

291

335

371

C hapter 13

The C om m odore 128 O perating System

C hapter 14

CP/M 3.0 on the Commodore 128

C hapter 15

The C om m odore 128 and Com m odore 64 M em ory M aps

C hapter 16

C l 28 H ardw are Specifications

A ppendixes

G lossary

Index

401

A l l

501

555

643

731

739

ACKNOW LEDGMENTS

W ritten 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 o f 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 o f Commodore Hardware

Design, who provided expertise in the operation of the Z80 hardware, and of Dave

DiOrio o f Commodore Integrated Circuit Design, who provided insight into the design of the Memory M anagement Unit and the C l 28 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 Techni cal Support for providing an always available source of technical assistance. In addition, we want to acknowledge the valuable contributions of members of Commodore Soft ware 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

2 COMMODORE 128

■i

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

Commodore 128 is the successor to the commercially successful Commodore 64 com puter. 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:

■ C l 28 Mode

■ C64 Mode a CP/M Mode

Two of these primary modes (C l28 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.

C l 28 MODE

In C128 M ode, the Commodore 128 Personal Computer provides the capabilities and memory needed to run sophisticated applications, such as word processing, spreadsheets, and database programs.

C l 28 Mode features include:

■ 8502 processor running at 1.02 or 2.04 MHz

■ New, enhanced C l 28 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

IN T R O D U C TIO N 3

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, Datasette™ , joysticks, com posite video m onitors, 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 impossi ble for the 1571 to operate in C64 Mode at fast speed.

4 COMMODORE 128

CP/M MODE

In CP/M M ode, 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 iclude:

■ 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 VIC 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 o f 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 software- compatible; runs at 1.02 or 2.04 MHz

Z80: CP/M Mode only; runs at 2.04 MHz

MEMORY

R O M : 64K standard (C64 Kernal plus BASIC; C l 28 Kernal plus BASIC, character

ROMs and CP/M BIOS); one 32K slot available for software

RAM: 128K 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

IN T R O D U C T IO N 5

SO UN D

6 5 8 1: SID Chip

IN P U T /O U T P U T

6526: Joystick ports/keyboard scan/cassette

6526: User and serial ports

MEMORY M ANAGEM ENT

8921: PLA (C64 plus C l 28 mapping modes)

8922: MMU (Custom gate array)

For details on these and other hardware components see Chapter 16, Commodore

128 Hardware Specifications.

CO M PA TIB ILITY W ITH

COMMODORE 64

The Commodore 128 system is designed as an upgrade to the Commodore 64. Accord ingly, 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 C l 28 Kernal.

These functions are also provided at the same locations in the jum p table of the C l 28

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 simpli fies interfacing for many programs.

Providing Commodore 64 compatibility means that the new features of the Com modore 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.

6 COMMODORE 128

SW ITC HING FROM MODE T O 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:

■ C l 28 Mode with 80-column display

■ C l 28 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.

FR O M

T O

O FF C128

40 CO L

C128

80 COL

C64 CP/M

40 COL

CP/M

80 CO L

C l 28

40 COL

C l 28

80 COL

Check that

40/80 key is UP.

M ake sure that: a)No CP/M system disk is in drive b)N o C64 cartridge is in ex pansion port

Turn com puter ON.

1. Press

40/80 key

DOW N.

1. Press

ESC key; release.

2. Turn com 2. Press X puter ON.

key.

1. Press

40/80 key

DOW N.

2. Press

RESET button.

1. Press ESC I . Check that 1. Check that key; 40/80 key 40/80 key release.

2. P ress X is UP.

2. Turn com is UP.

2. Turn com puter OFF, then ON.

key.

OR is UP.

2. Press puter OFF, then ON.

1. Check that 3. Remove

40/80 key cartridge if present

RESET button.

40/80 key is UP.

2. Turn com puter OFF, then ON.

1. Press

40/80 key

D O W N.

1. Press

40/80 key

DOW N.

1. Check that

40/80 key is DOW N.

2. Remove 2. Turn com 2. Remove puter OFF, CP/M sys then ON.

3. Remove cartridge if present.

tem disk from drive, if

CP/M sys tem disk from drive, if necessary.

necessary.

3. T urn com 3. Turn com puter OFF, puter OFF, then ON.

then ON.

Figure I —I . C o m m o d o re 128 M ode Sw itching C h a rt

IN T R O D U C T IO N 7

FR O M

T O

C64

CP/M

40 COL

CP/M

80 COL

OFF C128

40 COL

C128

80 COL

C64 CP/M

40 COL

CP/M

80 CO L

1. Hold

“ C1 ’’ key

DOW N.

SURE?

Type Y;

1. Type GO

64; press

RETURN.

2. Turn com 2. The com 2. The com puter ON.

puter re puter re

1. Insert C64 cartridge.

2. Turn com

1. Type GO

64; press

RETURN.

sponds:

ARE YOU sponds:

ARE YOU

SURE?

Type Y; puter ON.

press

RETU RN.

press

RETURN.

1. Turn disk drive ON.

2. Insert

CP/M sys tem disk in drive.

is UP.

4. Turn com puter ON.

1. Turn disk drive ON.

2. Insert

CP/M sys tem disk in drive.

is UP.

4. Type:

BOOT

5. Press

RETURN.

1. Turn disk drive ON.

1. Check that

40/80 key

2. Insert is UP.

CP/M sys 2. Turn disk tem disk in drive.

3. Check that 3. Check that 3. Check that

40/80 key 40/80 key 40/80 key is UP.

4. Type:

BOOT

5. Press

RETU RN.

drive ON.

3. Insert

CP/M sys tem disk in drive.

4. Turn com puter OFF.

1 .

Turn disk drive ON.

2. Insert

CP/M sys tem disk in drive.

3. Press

40/80 key

DOW N.

1. Turn disk drive ON.

2. Insert

CP/M sys tem disk in drive.

3. Press

40/80 key

DOW N.

4. Turn com 4. Type: puter ON.

BOOT

5. Press

RETU RN.

1. Turn disk drive ON.

2. Insert is DOW N.

4. Type:

BOOT.

5. Press

RETU RN.

1 .

Press

40/80 key

DOW N.

1. Insert

CP/M util ities disk

CP/M sys 2. Turn disk tem disk in drive.

drive ON.

2. At screen in drive.

3. Check that

40/80 key

3. Insert

CP/M sys tem disk prom pt,

A > type:

DEVICE in drive.

4. Turn com

CONOUT =

80 COL puter OFF.

3. Press

RETU RN.

1. Turn com 1. Turn com puter OFF.

puter OFF.

2. Check that 2. Check that

40/80 key 40/80 key is UP.

is UP.

3. Hold

DOW N

3. Hold

DOW N

C‘ key while turning com puter

C1 key while turn

ON.

1. Turn com puter OFF.

2. Insert C64 cartridge.

3. Turn power ON.

ing com puter ON.

1. Turn com puter OFF.

2. Insert C64 cartridge.

3. Turn pow er

ON.

1. Insert

CP/M util ities disk in drive.

2. At screen prom pt,

A > type:

DEVICE

CONOUT: =

40 COL

3. Press

R ETU RN .

Figure I —I . C o m m o d o re 128 M ode Sw itching C h a rt (continued)

8 COMMODORE 128

NOTE: If you are using a Commodore 1902 dual monitor, remember to move the video switch on the monitor from COMPOSITE or SEPA

RATED 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 C l 28 warranty card, your name will be added to a list which makes you eligible for CP/M system release dates.

H O W T O 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 ex pressions and operations.

C H A P T E R 3. ONE STEP BEYOND SIMPLE BASIC— Provides routines (menu, keyboard buffer, loading, programming function keys) and techniques ( “ crunch ing” or saving memory; debugging and merging programs; relocating BASIC) that can be incorporated in your own programs. Provides modem-related informa tion (how to generate TouchTone® frequencies, how to detect telephone ringing, etc.) plus technical specifications for Commodore Modem/1200 and Modem/300.

C H A P T E R 4. COMMODORE 128 GRAPHICS PROGRAMMING— Describes the general BASIC 7.0 graphics commands (COLOR, GRAPHIC, DRAW , LO

CATE, 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.

IN T R O D U C T IO N 9

C H A P T E R 5. MACHINE LANGUAGE ON THE COMMODORE 128— Defines, 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

COMMODORE 128— Describes, with examples, how to enter M L 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 BASIC— Describes, 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

ML programs in memory.

C H A P T E R 8. THE POWER BEHIND COMMODORE 128 GRAPHICS— Describes the C l 28 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. SPRITES— Describes 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 anno tated examples o f use, including programs.

C H A P T E R 10. PROGRAMMING THE 8O-COLUMN (8563) CHIP— Defines 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 128— Defines the

BASIC 7.0 sound and music commands (SOUND, ENVELOPE, VOL, TEM PO,

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 GUIDE— Describes 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 SYSTEM— Describes, 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 128— Summarizes the Commo dore version of CP/M 3.0. Defines the general system layout and the operating system components (CCP, BIOS and BDOS). Describes the Commodore enhance ments 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 MEMORY MAPS—

Provides detailed memory maps for C l 28 and C64 modes. (The Z80 memory map is shown in Appendix K.)

C H A P T E R 16. HARDWARE SPECIFICATIONS— Includes technical specifications for

Commodore 128 hardware components (8563, 8564, etc.).

A P P E N D IX E S A through L— Provide additional technical information and/or a more convenient grouping of information supplied elsewhere in the Guide (e.g ., pinout diagrams).

G L O S S A R Y — Provides standard definitions of technical terms.

B A S I C

BUILDING

BLOCKS AND

BASIC 7.0

ENCYCLOPEDIA

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 o f the elements of the BASIC language.

COM M ANDS A N D 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.

M ost 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 “ The Commodore 128” R E T 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” R E T U R N

RUN R E T U R N

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

NUMERIC MEMORY STORAGE:

CONSTANTS, VARIABLES A N D 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 o f 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 13 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 data— that 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.

C O N S TAN TS: INTEGER,

F LO A T IN G -P O IN T A N D STRING

INTEGER C O N S TA N TS

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:

1000

-3 2

-32767

F L O A T IN G -P O IN T C O N S TA N TS

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. Simple Number Notation

2. 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

14 COMMODORE 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 of 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. The mantissa is the leftmost number separated by a decimal point.

2. The letter E indicates that the number is displayed in exponential (scientific) notation.

3. 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:

SIM PLE NUMBER

9.99

.0234

+ 10.01

-9 0 .2 3

SCIEN TIFIC

22.33E + 20

99999.234E -23

^ t 5 .8 9 E - ll

- 3 .1 4 E + 17

NOTE: The values in either column are not equivalent.

STRING C O N S TA N TS

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 15 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 o f 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”

“ q w e rl2 3 4 !# $ % ()* .:,”

“ ” (null string)

“ John and Joan”

VARIABLES: INTEGER,

F L O A TIN G -P O IN T A N D 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 o f a mathematical calculation.

Variables are assigned values using an equals sign. The variable name appears to the left o f 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 C l 28 will interpret them as the same variable name.

The first character o f a variable name m ust be a letter. The rest o f the variable name can be any letter or number from zero to nine. A variable name m ust not contain any BASIC keyw ord. If you include a BASIC keyw ord in a variable nam e, a SYNTAX ERRO R occurs. BASIC keyw ords 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 C l 28 assumes that the variable value is a floating-point number. Here are some examples of variables and how they are assigned:

16 COMMODORE 128

A = 3.679 (floating-point)

Z% = 714 (integer)

F$ = “ CELEBRATE THE COMMODORE 128” (string)

T = A + Z% (floating-point)

Count % = Count % + 1 (integer)

G$ = “ SEEK A HIGHER LEVEL OF CONSCIOUSNESS” (string)

H$ = F$ + G$ (string)

ARRAYS: INTEGER,

F L O A TIN G -P O IN T A N D 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 “ ALPHA” is constructed and includes all the letters o f 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) A

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

ALPHA$( 1) B

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)

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 multi dimensional. 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 17

10 DIM A(99) dimensions a one-dimensional floating-point array with 100 elements. The following are examples o f two-, three- and four-dimensional integer arrays:

20 DIM B(9, 9) (100 elements)

30 DIM C(20,20,20) (9261 elements)

40 DIM D( 10,15,15,10) (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 C l28 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 o f 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. H ere’s how much memory each type of array requires:

5 bytes for the array name

+ 2 bytes for each dimension

+ 2 bytes for each integer array element

OR + 5 bytes for each floating-point element

OR + 3 bytes for each string element

AND + 1 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%) = “ JA N ”

G2%(X) = 5

CNT%(G2%(X)) = CNT%( 1 )- 2

FP(12*K%) = 24.8

(string array)

(integer array)

(floating-point array)

18 COMMODORE 128

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

A(5) = 0

B(5,6) = 26

C ( l,2 ,3 )= 1 0 0

(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 dimen sional array called “ C ” equal to 100

EXPRESSIONS A N D 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. Expres sions can be separated into two classes:

1. ARITHMETIC

2. 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.

A R ITH M ETIC EXPRESSIONS

Arithmetic expressions yield an integer or floating-point value. The arithmetic operators

( + ,- ,* ,/, t ) are used to perform addition, subtraction, multiplication, division and exponentiation operations, respectively.

A R ITH M ETIC 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 19

A D D IT IO N ( + )

The plus sign ( + ) specifies that the operand on the right is added to the operand on the left.

EX A M P LE S:

A + B + C

X % + 1

BR + 10E-2

SU B TR A C TIO N (- )

The minus sign (-) specifies that the operand on the right is subtracted from the operand on the left.

EX A M P LE S :

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).

E X A M P LE S:

-5

-9 E 4

-B

4 - ( - 2 ) (same as 4 + 2)

M U L T IP L IC A T IO N (*)

An asterisk (*) specifies that the operand on the left is multiplied by the operand on the right.

EX A M P LE S:

100*2

50*0

A*X1

R%* 14

D IV IS IO N (/)

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

20 COMMODORE 128

EX A M P LE S :

10/2

6400/4

A/B

4E2/XR

E X P O N E N T IA T IO N ( | )

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.

EX A M P LE S:

2 | 2 Equivalent to 2*2

3 | 3 Equivalent to 3*3*3

4 | 4 Equivalent to 4*4*4*4

AB f CD

3 | - 2 Equivalent to V3*lA

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 o f - 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

EX A M P LE S :

5 - 4 = 1 result true (-1)

14> 66 result false (0)

15 > = 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 21 evaluating the relationship between corresponding characters from left to right (see string operations).

EX A M P LE S:

“ A ” < “ B ” result true (-1)

“ X ” = “ Y Y ” result false (0)

BB$ < > CC$ 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

M ISMATCH 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 o f 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 + 32767)

(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 o f 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 to gether, constitute a Boolean “ truth table” as shown in Table 2-1.

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 X O R 1 = 0

1 XOR 0 = 1

0 XOR 1 = 1

0 XOR 0 = 0

T a b le 2-1 Boolean T ru th T a b le

The logical operators AND, OR and NOT specify a Boolean arithmetic operation to be performed on the two operand expressions on either side o f 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.

E X A M P LE S :

IF A = 100 AND B = 100 THEN 10 (if both A and B have a value o f 100 then the result is true)

A = 96 AND 32: PRINT A (A = 32)

IF A = 100 OR B = 100 THEN 20 (if A or B is 100 then the result is true)

A = 64 OR 32: PRINT A (A = 96)

X = NOT 96 (result is -9 7 (tw o’s complement))

HIERARCHY OF OPERATIONS

All expressions perform the different types o f 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 23 parentheses ( ), creating a “ subexpression.” The parts of an expression enclosed in pa rentheses 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 levels— ten matching sets of parentheses. The innermost expression has its operations performed first. Some examples o f expressions are:

A + B

C f (D + E)/2

( ( X - C t (D + E)/2)*10) + 1

G G $>H H $

JJ$ + “ M O RE”

K % = 1 AND M O X

K% = 2 OR (A = B AND M < X )

NOT (D = E)

The BASIC Interpreter performs operations on expressions by performing arithme tic operations first, then relational operations, and logical operations last. Both arithme tic 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.

OPERA TOR

> = <

NOT

AND

DESCRIPTIO N

Exponentiation

Negation (Unary Minus)

M ultiplication

Division

Addition

Subtraction

Relational Operations

Logical NOT

(Integer T w o’s Complement)

Logical AND

Logical OR

EXAMPLE

BASE t EXP

-A

AB * CD

E F / GH

CNT + 2

J K - P Q

A < = B

NOT K%

JK AND 128

PQ OR 15

T a b le 2 -2 H ie ra rc h y o f O peratio ns P erfo rm e d on Expressions

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 char acters 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 o f 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 ?T Y PE M ISM A T C H occurs. Some examples of string expres sions and concatenation are:

10 A$ = “ FILE” : B $ = “ NAM E”

20 NAM$ = A$ + B$ (yields the string “ FILENAM E” )

30 RES$ = “ N EW ” + A$ + B$ (yields the string “ NEW FILENAM E” )

O R G A N IZA TIO N 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) o f Commodore 128

BASIC 7.0, along with a concise description o f 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 2S 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:

C om m ands and Statem ents: the commands used to edit, store and erase programs, and the BASIC program statements used in the numbered lines o f a program.

2. Functions: the string, numeric and print functions.

3. Reserved W ords 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 follow ing format:

Command name—

Brief definition—

Command format—

Discussion of format and use—

A U T O

Enable/disable automatic line numbering

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 o f the line number. The line number argument refers to the desired incre ment 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).

E X A M P LE S:

Example(s)—

AUTO 10 Automatically numbers program lines in incre ments of 10.

AUTO 50 Automatically numbers lines in increments of 50.

AUTO Turns off automatic line numbering.

26 COMMODORE 128

The boldface line that defines the format consists of the following elements:

DLO AD “ program nam e” [,D 0,U 8] t keyword t argum ent additional arguments

(possibly optional)

The parts of the command or statement that must be typed exactly as shown are in capital letters. Words the user supplies, such as the name of a program, are not capitalized.

When quote marks ( “ ” ) appear (usually around a program name or filename), the user should include them in 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. Key words 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.

A rgum ents, also called parameters, appear in lower-case letters. Arguments comple ment 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 nam e” 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.

A ngle Brackets < > indicate the user MUST choose one of the arguments listed.

A V e rtica l B ar | separates items in a list o f 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 o f the listed arguments.

Ellipsis . . . (a sequence of three dots) means an option or argument can be repeated more than once.

Q u o tatio n M arks “ ” 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 o f 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 27

V a ria b le 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 COM M ANDS A N D

STATEMENTS

APPEND

Append data to the end of a sequential file

APPEND #logical file num ber,“ filenam e” [,Ddrive n u m ber][< O N |,> U device]

E X A M P LE S:

Append # 8, “ M YFILE” OPEN logical file 8 called “ M YFILE” , and prepare to append with subsequent PRINT # statements.

Append # 7,(A $),D 0,U 9 OPEN logical file named by the variable in A$ on drive 0, device number 9, and prepare to APPEND.

A U T O

Enable/disable automatic line numbering

AUTO [line#]

EX A M P LE S :

AUTO 10 Automatically numbers program lines in increments of 10.

AUTO 50 Automatically numbers lines in increments of 50.

AUTO 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.

28 COMMODORE 128

EX A M P LE S :

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

CONFIGURATION

RAM(O) only

R A M (l) only

RAM(2) only (same as 0)

RAM(3) only (same as 1)

Internal ROM , RAM(O), I/O

Internal ROM , R A M (l), I/O

Internal ROM , RAM (2), I/O (same as 4)

Internal ROM , RAM (3), I/O (same as 5)

External ROM , RAM(O), I/O

External ROM , R A M (l), 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(O), I/O

Kernal and External ROM (LOW ), RAM(O), I/O

Kernal and BASIC ROM, RAM(O), Character ROM

Kernal and BASIC ROM , RAM(O), 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.

H ere’s the format:

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA 29

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 “ So this part of the statement is perform ed”

30 PRINT “ When X equals 1”

40 BEND: PRINT “ End of BEGIN/BEND structure” :GO to 60

50 PRINT “ X does not equal 1” :PRINT “ The statements between BEGIN/

BEND are skipped”

60 PRINT “ Rest of Program ”

BLOAD

Load a binary file starting at the specified memory location where:

BLOAD “ filenam e” !,D drive n u m b er][< O N I,U > d evice num ber] [,Bbank number] [,Pstart address]

■ filename is the name of your file a bank number selects one of the 16 BASIC banks (default memory con figurations)

■ start address is the memory location where loading begins

EX A M P LE S:

BLOAD “ SPRITES” , B0, P3584 LOADS the binary file "S P R IT E S ” starting in location 3584 (in BANK 0).

BLOAD “ DATA1” , DO, U8, B l, P4096 LOADS the binary file “ DATA 1” into location 4096 (BANK 1) from

Drive 0, unit 8.

B O O T

Load and execute a program which was saved as a binary file

BOOT “ filenam e” [,Ddrive num ber][< O N |,> U device][,P alt LOAD ADD]

E X A M P LE :

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

30 COMMODORE 128

BOOT “ GRAPHICS 1” , DO, U9 LOADS the binary program “ GRAPHICS 1” from unit 9, drive 0, and executes it.

BO X

Draw box at specified position on screen

BOX [color source], X I, Y l[,X 2,Y 2][,angle][,paint] where: color source 0 = Background color

1 = Foreground color (DEFAULT)

2 = Multi-color 1

3 = Multi-color 2

X I,Y 1 Corner coordinate (scaled)

X2,Y 2 Corner diagonally opposite X I, Y l, (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)

EX A M P LE S :

BOX 1, -I- 10, -I- 10 Draw a box 10 pixels to the right and 10 down from the current pixel cursor location.

BOX 1, 10, 10, 60, 60 Draws the outline of a rectangle.

BOX , 10, 10, 60, 60, 45, 1 Draws a painted, rotated box (a diamond).

BOX , 30, 90, , 45, 1 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 31

BSAVE

Save a binary file from the specified memory locations where:

BSAVE “ filenam e” [,D drive n u m b er][< O N I,U > d evice num ber] [,Bbank num ber],Pstart address TO Pend address

■ start address is the starting address where the program is SAVEd from a end address is the last address + 1 in memory which is SAVEd

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

EX A M P LE S :

BSAVE “ SPRITE D A TA ” ,BO, Saves the binary file named “ SPRITE DATA” ,

P3584 TO P4096 starting at location 3584 through 4095 (BANK

0 ).

BSAVE “ PROG RA M .SCR” ,DO, Saves the binary file named “ PROGRAM.

U9,B0,P3182 TO P7999 SC R ” in the memory address range 3182 through 7999 (BANK 0) on drive 0, unit 9.

CATALOG

Display the disk directory

CATALOG [Ddrive num ber][< O N |,> U device num ber][,wildcard string]

E X A M P LE :

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. H ere’s what the parameters mean: color source

0 = Background

1 = Foreground

Character column (0-39) (VIC screen)

(0-79) (8563) screen

32 COMMODORE 128

Y Character row (0-24) string String to print reverse Reverse field flag (0 = off, 1 = on)

E X A M P LE :

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

20 COLOR 3,7: REM MULTI-COLOR 2 = BLUE

30 GRAPHIC 3,1

30 CHAR 0,10,10, “ TEX T” ,0

CIRCLE

Draw circles, ellipses, arcs, etc., at specified positions on the screen where:

CIRCLE [color source],X ,Y [,X r][,Y r] [,sa][,ea][,angle][,inc] color source

X,Y

Yr sa ea angle inc

0 = background color

1 = foreground color

2 = multi-color I

3 = multi-color 2

Center coordinate of the CIRCLE

X radius (scaled); (default = 0)

Y radius (sealed default is Xr)

Starting arc angle (default 0 degrees)

Ending arc angle (default 360 degrees)

Rotation is clockwise degrees (default is 0 degrees)

Degrees between segments (default is 2 degrees)

EX A M P LE S :

CIRCLE1, 160,100,65,10 Draws an ellipse.

CIRCLE1, 160,100,65,50 Draws a circle.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA 33

CIRCLE1, 60,40,20,18,,,,45 Draws an octagon.

CIRCLE 1, 2 6 0 ,4 0 ,2 0 ,,,,.9 0 Draws a diamond.

CIRCLE 1, 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.

CIRCLE 1, 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

E X A M P LE :

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]

E X A M P LE :

OPEN 1,4 Opens device 4 (printer).

CMD 1 All normal output now goes to the printer.

LIST The LISTing goes to the printer, not the screen— even the word

READY.

P R IN T # 1 Sends output back to the screen.

CLOSE 1 Closes the file.

34 COMMODORE 128

COLLECT

Free inaccessible disk space

COLLECT [Ddrive num ber][< O N |,> U device]

E X A M P LE :

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.

C O LLIS IO N

Define handling for sprite collision interrupt

COLLISION type [,statement] type Type of interrupt, as follows:

1 = Sprite-to-sprite collision statement

2 = Sprite-to-display data collision

3 = Light pen (VIC screen only)

BASIC line number of a subroutine

E X A M P LE :

Collision 1, 5000 Enables 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 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

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 A N D BASIC 7.0 ENCYCLOPEDIA 35

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

CO LO R CODE COLO R C O LO R CODE CO LOR

Black

White

Red

Cyan

Purple

Green

Blue

Yellow

Orange

Brown

Light Red

Dark Gray

Medium Gray

Light Green

Light Blue

Light Gray

C o lo r N u m b ers in 40-C o lu m n O u tp u t

Black

White

Dark Red

Light Cyan

Light Purple

Dark Green

Dark Blue

Light Yellow

C o lo r N u m b ers in 80-C olum n O u tp u t

Dark Purple

Dark Yellow

Light Red

Dark Cyan

Medium Gray

Light Green

Light Blue

Light Gray

E X A M P LE S:

COLOR 0, 1: Changes background color of 40-column screen to black.

COLOR 5 ,8 : Changes character color to yellow.

C O N C A T

Concatenate two data files

CONCAT “ file 2” [,Ddrive number] TO “ file 1”

[,Ddrive num ber][<O N |,>U device]

E X A M P LE :

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$), D l, U9 The file named by B$ becomes a new file with the same name with the file named by A$ at tached to the end of B$. This is performed on

Unit 9, drive 1 (a dual disk drive).

36 COMMODORE 128

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

C O N T

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 num ber,]“ source fiIename” TO[Ddrive num ber,]“ destination filenam e” [< O N |,> U d evice]

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

E X A M P LE S :

COPY DO, “ TEST” TO D1, “ TEST PROG” Copies “ test” from drive 0 to drive

1, renaming it “ test prog” on drive 1.

COPY DO. “ STUFF” TO D l, “ STUFF” Copies “ STUFF” from drive 0 to drive 1.

COPY DO TO Dl Copies all files from drive 0 to drive

COPY “ W ORK.PROG” TO “ BACKUP” Copies “ W O RK .PRO G ” as a file called “ BACKUP” on the same disk

(drive 0).

D A TA

Define data to be used by a program

DATA list of constants

E X A M P LE :

DATA 100, 200, FRED, “ HELLO, M OM ” ,, 3, 14, ABC123

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA 37

DCLEAR

Clear all open channels on disk drive

DCLEAR [Ddrive num ber][< O N |,> U device]

EX A M P LE S :

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

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

DCLOSE

Close disk file

DCLOSE [#logical file num ber][<O N |,>U device]

E X A M P LE S:

DCLOSE Closes all channels currently open on unit 8.

DCLOSE # 2 Closes the channel associated with the logical file number 2 on unit 8.

DCLOSE ON U9 Closes all channels currently open on unit 9.

DEF FN

Define a user function

DEF FN name (variable) = expression

E X A M P LE :

10 DEF FNA(X) = 12*(34.75-X/.3) + X

20 PRINT FNA(7)

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.

38 COMMODORE 128

DELETE

Delete lines of a BASIC program in the specified range

DELETE [first line] [-last line]

EX A M P LE S:

DELETE 75 Deletes line 75.

DELETE 10-50 Deletes lines 10 through 50, inclusive.

DELETE-50 Deletes all lines from the beginning o f the program up to and including line 50.

DELETE 75- 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)] . . .

E X A M P LE :

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.

D LO A D

Load a BASIC program from the disk drive, device 8.

DLOAD “ filenam e” [,Ddrive num ber][< O N |,> U device number]

E X A M P LE S:

DLOAD “ BANKRECS” Searches the disk for the program “ BANKRECS” and LOADS it.

DLOAD (A$) 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.

D O / LOOP / W HILE / U N T IL / EX IT

Define and control a program loop

DO [UNTIL 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 > 65.

40 COMMODORE 128

E X A M P LE S :

10 X = 25

20 DO UNTIL X = 0

30 X = X - l

40 PRINT “ X = ” ;X

50 LOOP

60 PRINT “ End of Loop”

This example performs the statements X = X -l and PRINT “ X = ” ;X until X = 0 . When X = Othe program resumes with the PRINT “ End o f Loop” statement immediately following LOOP.

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

20 PRINT “ THE 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 o f the loop and line 20 is executed.

10 DOPEN # 8 , “ SEQFILE”

20 DO

30 GET # 8 ,A $

40 PRINT AS;

50 LOOP UNTIL ST

60 DCLOSE # 8

This program opens file “ SEQFILE” 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 file num ber,“ filen a m e[,< ty p e> ]” [,Lrecord length] t,Ddrive num ber][< O N |,> U device number][,W ] where type is:

S = Sequential File Type

P = Program File Type

U = User File Type

R = Relative File Type

L = Record Length = the length of records in a relative file only

W = Write Operation (if not specified a read operation occurs)

EX A M P LE S :

D O PE N # 1, “ ADDRESS” ,W Create the sequential file number 1 (ADDRESS) for a write operation

D O PE N #2 “ RECIPES” ,D1,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 41

DRAW

Draw dots, lines and shapes at specified positions on the screen

DRAW [color source] [,X 1, Y l][T O X2, Y2] . . .

where:

Color source 0 = Bit map background

1 = Bit map foreground

2 = Multi-color 1

3 = Multi-color 2

X I,Y 1 Starting coordinate (0,0 through 319,199)

X2,Y 2 Ending coordinate (0,0 through 319,199)

E X A M P LE S :

DRAW 1 ,1 0 0 , 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 “ filenam e” [,Ddrive num ber][< O N |,> U device number]

EX A M P LE S :

DSAVE "B A N K R E C S” Saves the program “ BANKRECS” to disk.

DSAVE (A$) Saves the disk program named in the variable A$.

DSAVE “ PROG 3” ,D1,U9 Saves ber 9, drive 1.

the program “ PROG3” to disk on unit num

42 COMMODORE 128

□VERIFY

Verify the program in memory against the one on disk

DVERIFY “ filenam e” [,Ddrive num ber][< O N |,> U device number]

To verify Binary data, see VERIFY “ filenam e” ,8,1 format, under VERIFY command description.

E X A M P LE S :

DVERIFY “ C128” Verifies program “ C128” on drive 0, unit 8.

DVERIFY “ SPRITES” ,DO,U9 Verifies program “ SPRITES” on drive 0, de vice 9.

END

Define the end o f program execution

END

ENVELOPE

Define a musical instrument envelope

ENVELOPE n[,atk] [,dec] [,sus] [ ,r e l][,w f] [,pw] where: n Envelope number (0-9) a tk Attack rate (0-15) dec Decay rate (0-15) sus Sustain (0-15) rel Release rate (0-15) w f Waveform: 0 = triangle

1 = sawtooth

2 = variable pulse (square)

3 = noise

4 = ring modulation pw Pulse width (0-4095)

See the “ T ” option in the PLAY command to select an envelope in a PLAY string.

E X A M P L E :

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 43

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 1MHz mode. The

DMA operations (FETCH, SWAP, STASH) must be performed at 1MHz (slow) speed.

FETCH

Get data from expansion (RAM module) memory

FETCH # b y tes, intsa, expsa, expb where bytes = Number o f 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 Filter cut-off frequency (0-2047) lp Low-pass filter on (1), off (0) bp hp

Band-pass filter on (1), off (0)

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

Unspecified parameters result in no change to the current value.

EX A M P LE S:

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.

44 COMMODORE 128

FOR / T O / STEP / N E X T

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 o f 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.

E X A M P LE :

10 FOR L = 1 TO 10

20 PRINT L

30 NEXT L

40 PRINT “ I ’M DONE! L = ” L

This program prints the numbers from one to 10 followed by the message I ’M DONE!

L = 11.

E X A M P LE :

10 FOR L = 1 TO 100

20 FOR A = 5 TO 11 STEP .5

30 NEXT A

40 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

E X A M P LE :

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 45

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

E X A M P LE :

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.

G E T#

Receive input data from a tape, disk or RS232

G E T # logical file number, variable list

E X A M P LE :

10 G E T #1,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.

G 064

Switch to C64 mode

G 0 6 4

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

E X A M P LE :

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

46 COMMODORE 128

800 PRINT “ THE C l 28 WAS WORTH THE W AIT!” : RETURN

G O TO / GO TO

Transfer program execution to the specified line number

GOTO line number

E X A M P LE S:

10 PRIN T“ COM M ODORE” The GOTO in line 20 makes line 10 repeat continu-

20 GOTO 10 ously 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:

M ODE

D ESCRIPTIO N

40-column 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

E X A M P LE S:

GRAPHIC 1,1 Select standard bit map mode and clear the bit map.

GRAPHIC 4,0,10 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 Clear and deallocate the bit map screen.

GSHAPE

See SSHAPE.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA 47

HEADER

Format a diskette

HEADER “ diskname” [,1 i.d.] [,Ddrive number]

[< O N |,> U d ev ice 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 ,1 5 ,“ N 0:disknam e,i.d.”

EX A M P LE S :

HEADER “ M YDISK” ,I23, DO This headers “ M YDISK” using i.d. 23 on drive 0, (default) device number 8.

HEADER “ RECS” , 145, D1 ON U9 This headers “ RECS” using i.d. 45, on drive 1, device number 9.

HEADER “ C l 28 PROGRAM S” , DO 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.

HEADER (A$),I76,D0,U9 This example headers the diskette with the name specified by the variable A$, and the i.d. 76 on drive 0, device num ber 9.

HELP

Highlight the line where the error occurred

HELP

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

IF / T H E N / ELSE

Evaluate a conditional expression and execute portions o f a program depending on the outcome o f the expression

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 o f 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. W hen 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 ( = , < , > , < = , > = , < > ) .

E X A M P LE :

50 IF X > 0 THEN PRINT “ O K ” : ELSE END

This line checks the value of X. If 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

99 STOP

100 PRINT “ X EQUALS 10” transferred to line 100 and the message

“ X EQUALS 10” is printed. IF X does not equal 10, the program resu mes with line 20, the C l 28 prints the prompt “ X DOES NOT EQUAL 10” and the program stops.

IN P U T

Receive a data string or a number from the keyboard and wait for the user to press

RETURN

INPUT [“ prompt string” ;] variable list

E X A M P LE :

10 INPUT “ PLEASE TYPE A NUM BER” ;A

20 INPUT “ AND YOUR NAM E” ;A$

30 PRINT A$ “ YOU TYPED THE NUM BER” ;A

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA 49

IN P U T #

Input data from an I/O channel into a string or numeric variable

IN P U T # file number, variable list

E X A M P L E :

10 OPEN 2,8,2

20 IN P U T #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)

E X A M P LE :

KEY 7, “ GRAPHICO” + CHR$(13) + “ LIST” + 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 DS$” + 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 FOR 1= 1 to 7 STEP 2

20 KEY I, CHR$(I + 132):NEXT

30 FOR I = 2 to 8 STEP 2

40 KEY 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

E X A M P LE :

10 LET A = 5 Assign the value 5 to numeric variable A.

50 COMMODORE 128

20 B = 6 Assign the value 6 to numeric variable B.

3 0 C = A * B + 3 Assign the numeric variable C, the value resulting from 5 times 6 plus 3.

40 D$ = “ HELLO” Assign the string “ H ELLO” 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.

EX A M P LE S :

LIST Shows entire program.

LIST 1 0 0 - Shows from line 100 until the end of the program.

LIST 10 Shows only line 10.

LIST - 1 0 0 Shows all lines from the beginning through line 100.

LIST 10-200 Shows lines from 10 to 200, inclusive.

LOAD

Load a program from a peripheral device such as the disk drive or Datassette

LOAD “ filenam e” [,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).

E X A M P LE S:

LOAD Reads in the next program from tape.

LOAD “ H ELLO” 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” ).

LO A D “ M ACHLANG” ,8 ,l LOADs the m achine language program called

“ M ACHLANG” into the location from which it was SAVEd.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA 51

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.

E X A M P LE :

LOCATE 160,100 Positions the PC in the center of the bit map screen. Noth ing will be seen until something is drawn.

LOCATE + 2 0 ,1 0 0 Move the pixel cursor 20 pixels to the right of the last PC position and place it at Y coordinate 100.

L O C A T E - 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

R D O T(l) to get the Y-coordinate. The color source of the pixel at the PC can be found by PRINTing RDOT(2).

M O N IT O R

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 num ber,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.

52 COMMODORE 128

4) MOVSPR number, angle # speed Move sprite at an angle relative to its current coordinate, in the clock wise 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 statem ent 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.

EX A M P LE S:

MOVSPR 1,150,150 Position sprite 1 near the center o f the screen, x,y coordinate 150,150.

MOVSPR l, + 2 0 ,-3 0 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 53

O N

Conditionally branch to a specified program line number according to the results of the specified expression

ON expression <G O T O /G O SU B > line # 1 [, line # 2 , . . .]

E X A M P LE :

10 INPUT X:IF X < 0 THEN 10

20 ON X GOTO 30, 40, 50, 60 When X = 1, ON sends control to the first line

25 STOP number in the list (30). When X = 2, ON sends

30 PRINT “ X = 1”

40 PRINT “ X = 2 ” control to the second line (40), etc.

50 PRINT “ X = 3 ”

60 PRINT “ X = 4 ”

OPEN

Open files for input or output

OPEN logical file number, device number [,secondary address] [ < , “ filename

[,filetype[, [m ode” ]]|< ,cm d string>]

EX A M P LE S :

10 OPEN 3,3

20 OPEN 1,0

30 OPEN 1 ,1 ,0 ,“ DOT”

OPEN 4,4

OPEN 15,8,15

5 OPEN 8 ,8 ,1 2 ,“ TESTFILE,S,W ”

OPEN the screen as file number

OPEN the keyboard as file num ber 1.

OPEN the cassette for reading, as file number 1, using “ D O T” as the filename.

OPEN the printer as file number 4.

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.

OPEN a sequential disk file for writing called TESTFILE as file number 8, with secondary address

54 COMMODORE 128

See also: CLOSE, CMD, G E T # , IN P U T # , and P R IN T # statements and system variables ST, DS, and DS$.

PA IN T

Fill area with color

PAINT [color source],X,Y[,m ode] where: color source 0 = bit map foreground

1 = bit map background (default)

2 = multi-color 1

3 = 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.

E X A M P LE :

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).

Draws an outline o f a box.

10 BOX 1, 10, 10, 20, 20

20 PAINT 1, 15, 15

30 PAINT 1, + 10, + 10

Fills the box with color from source 1, assuming point 15,15 is colored in the background source

(

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 55

100 PAINT 1, 100;90 Paint the screen area 90° relative to and 100 pixels away from the current pixel cursor co ordinate.

PLAY

Defines and plays musical notes and elements within a string or string variable.

PLAY “ V n,O n,T n,U n,X n,elem ents, 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.

56 COMMODORE 128

EX A M P LE S :

PLAY “ VIO4T0U5X0CDEFGAB ’ 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 305T6U 7X 1#B $A W .C H D Q EIF 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 305T6U 3A BCD E” : PLAY A$ PLAY the notes and elements within

A$.

PLAY “ V1CV2EV3G” Plays a chord in the default setting.

POKE

Change the contents of a RAM memory location

POKE address, value

E X A M P L E :

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)

(;,)

E X A M P LE S :

10 PRINT “ HELLO”

20 A$ = “ THERE” :PRINT “ HELLO” ;A$

30 A = 4:B = 2:?A + B

40 J = 4LPR IN T J;:PRINT J - 1

50 PRINT A;B;:D = A + B:PRINTD;A-B

RESULTS

HELLO

HELLO THERE

41 40

4 2 6 2

See also POS, SPC, TAB and CHAR functions.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA 57

PR IN T#

Output data to files

P R IN T # file number[, print list]

P R IN T # is followed by a number which refers to the data file previously OPENed.

E X A M P LE :

10 OPEN 4,4 Outputs the data “ HELLO TH ERE”

20 P R IN T # 4 ,“ HELLO THERE!” ,A$,B$ and the variables A$ and B$ to the printer.

10 OPEN 2,8,2

20 P R IN 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 IN T # command is used by itself to close the channel to the printer before closing the file, as follows:

10 OPEN 4,4

30 P R IN T #4, “ PRINT W ORDS”

40 PR IN T #4

50 CLOSE 4

PRINT USING

Output using format

PRINT [# file number,] USING“ format list” ; print list

This statement defines the format o f string and numeric items for printing to the text screen, printer or other device.

E X A M P LE :

5 X = 32: Y = 100.23: A$ = “ CA T”

10 PRINT USING “ $ # # . # # # ” ;13.25,X ,Y

20 PRINT USING “ # # # > # ” ;“ C B M ” ,A$

When this is RUN, line 10 prints:

$13.25 $32.00 $***** p jve 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 de fined in format list.

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.

E X A M P LE :

10 PRINT USING “ # # # # ” ;X

For these values of X, this format displays:

A = 12.34

A = 567.89

A = 123456

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.

EX A M P LE S:

FIELD

# # . #

# # # #

EXPRESSION

- .1

-1 0 0 .5

- 1 0 0 0

RESULT

- 0 . 1

1 .0

- 1 0 1

# # # .

# $ # #

1 0 .

COMM ENT

Leading zero added.

Trailing zero added.

Rounded to no decimal places.

Overflow because four digits and a minus sign cannot fit in field.

Decimal point added.

Floating dollar sign.

PUDEF

Redefine symbols in PRINT USING statement

PUDEF “ nnnn”

Where “ nnnn” 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 char acter 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 59

E X A M P LE S:

10 PUD EF“ *”

20 PUDEF“ < ”

PRINT * in the place o f blanks.

PRINT < in the place o f 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.

E X A M P LE S :

10 READ A, B, C

20 DATA 3, 4, 5

10 READ A$, B$, C$

20 DATA JOHN, PAUL, GEORGE

10 READ A, B$, C

20 DATA 1200, NANCY, 345

READ the first three numeric variables from the closest data statement.

READ the first three string variables from the nearest data statement.

READ (and input into the C l 28 memory) a numeric variable, a string variable and an other 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) o f 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 (PR IN T #) operation, additional records are created to expand the file to the desired record number.

For a read (IN PU T#) operation, a null record is returned and a “ RECORD NOT

PRESENT ERROR occurs” . See your disk drive manual for details about relative files.

EX A M P LE S :

10 DOPEN# 2 , “ FILE ’ ’

20 R E C O R D # 2 ,10,1

30 PR IN T #2,A $

40 D C LO SE#2

60 COMMODORE 128

This example opens an existing relative file called “ FILE” 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

E X A M P LE :

10 NEXT X:REM THIS LINE INCREMENTS X.

RENAME

Change the name of a file on disk

RENAME “ old filenam e” TO “ new filename” [,Ddrive n um ber][< O N I,>

Udevice number]

E X A M P LE S:

RENAME “ TEST” TO “ FINALTEST” ,D0 Change the name o f the file

“ TEST” to “ FINAL TEST” .

RENAME (A$) TO (B$),D0,U9 Change the filename specified in

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

RENUMBER

Renumber lines of a BASIC program

R ENUM BER [new starting line n u m b er][,in crem en ts,o ld starting line number]

E X A M P LE S:

RENUMBER Renumbers the program starting at 10, and increments each additional line by 10.

RENUMBER 20, 20, 1 Starting at line 1, renumbers the program. Line 1 be comes line 20, and other lines are numbered in incre ments of 20.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA 61

RENUM BER,, 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.

E X A M P LE S :

10 FOR I = 1 TO 3

20 READ X

30 ALL = X + ALL

40 NEXT

50 RESTORE

60 GOTO 10

70 DATA 10,20,30

10 READ A ,B ,C

20 DATA 100,500,750

30 READ X ,Y ,Z

40 DATA 36,24,38

50 RESTORE 40

60 READ S,P,Q

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 RE-

STOREd to the beginning of the program and it returns to line 10 and performs repetitively.

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 indi cating 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.

E X A M P LE :

10 TRAP 100

15 INPUT “ ENTER A NUM BER’';A

20 B = 100/A

40 PRINT“ THE RESULT = ” ;B

62 COMMODORE 128

50 INPUT “ DO YOU WANT TO RUN IT AGAIN (Y /N )” ;Z$:IF Z$ = “ Y ”

THEN 10

60 STOP

100 IN PU T“ ENTER ANOTHER NUMBER (NOT ZERO)” ;A

110 RESUME 20

This example traps a “ DIVISION BY ZERO ERROR” 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

E X A M P LE :

10 PRINT “ ENTER MAIN PROGRAM ”

20 GOSUB 100

30 PRINT “ END OF PROGRAM ”

90 STOP

100 PRINT “ SUBROUTINE 1”

110 RETURN

This example calls the subroutine at line 100 which prints the message “ SUBROU

TINE 1” and RETURNS to line 30, the rest of the program.

RUN

Execute BASIC program

1) RUN [line number]

2) RUN “ filenam e” [,Ddrive num ber][< O N |,> U device number]

EX A M P LE S:

RUN Starts execution from the beginning of the program.

RUN 100 Starts program execution at line 100.

RUN“ PRG 1” DLOADs “ PRG1” from disk drive 8, and runs it from the starting line number.

RUN(A$) DLOADs the program named in the variable A$.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA 63

SAVE

Store the program in memory to disk or tape

SAVE [“ filenam e” ][,device number][,EOT flag]

E X A M P LE S:

SAVE Stores program on tape, without a name.

SAVE “ HELLO” Stores a program on tape, under the name HELLO.

SAVE A$,8 Stores on disk, with the name stored in variable A$.

SAVE “ HELLO” ,£ Stores on disk, with name HELLO (equivalent to

DSAVE “ HELLO” ).

SAVE “ H ELLO ” , 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 Y = 0 to 199

X = 0 to 319 Y = 0 to 199

EX A M P LE S :

10 GRAPHIC 1,1 Enter standard bit map, turn scaling

20 SCALE LCIRCLE 1,180,100,100,100 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.

64 COMMODORE 128

SCNCLR

Clear screen

SCNCLR mode number

The modes are as follows:

MODE NUMBER

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.

EX A M P LE S:

SCNCLR 5 Clears 80 column text screen.

SCNCLR I Clears the (VIC) bit map screen.

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

SCRATCH

Delete file from the disk directory

SCRATCH “ filenam e” [,Ddrive num ber][< O N |,> U device number]

E X A M P LE :

SCRATCH “ MY BACK” , DO

This erases the file MY BACK from the disk in drive 0.

SLEEP

Delay program for a specific period o f time

SLEEP N where N is seconds 0 < N < = 65535.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA 65

SLOW

Return the Commodore 128 to 1MHz operation

SLOW

SO UN D

Output sound effects and musical notes

SOUND v,f,d[,dir][,m ][,s][,w ][,p] where: v = voice (1..3) f = frequency value (0..65535) d = duration (0..32767) dir = step direction (0(up), l(down) or 2(oscillate)) default = 0 m = minimum frequency (if sweep is used) (0..65535) default = s = step value for sweep (0..32767) default = 0 w = waveform (0 = triangle, 1 = sawtooth, 2 = variable, 3 = noise) default = 2 p = pulse width (0..4095) default = 2048

E X A M P LE S:

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 frequen cies starting at 2000 and incrementing upward in units of 100 up to 20,000. Each frequency is played for 50 jiffies.

SO U N D 3,5000,90,2,3000,500,1 This example outputs a range of sounds start ing 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 [sm cr-l][,sm cr-2] where: smcr-1 Sets multi-color 1 for all sprites.

smcr-2 Sets multi-color 2 for all sprites.

66 COMMODORE 128

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

E X A M P LE S:

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 corre sponds 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

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

Turns on and off automatic cursor movem ent.

CRSR keys

RETURN KEY

RETURN key

Moves cursor in work/area.

M oves cursor to start o f next line.

Exits sprite designer mode at the SPRITE NUM BER? prompt

HOME key

CLR key only.

Moves cursor to top left corner of sprite work area.

Erases entire grid.

1-4

CTRL key, 1-8

Selects color source (enables/disables pixels).

Selects sprite foreground color (1-8).

Comm odore key, 1-8 Selects sprite foreground color (9-16).

STOP key

SHIFT RETURN

Cancels changes and returns to prompt.

Saves sprite and returns to SPRITE NUM BER? prompt.

Expands sprite in X (horizontal) direction.

Expands sprite in Y (vertical) direction.

M ulti-color sprite mode.

C Copies sprite data from one sprite to another.

SPRITE

Turn on and off, color, expand and set screen priorities for a sprite

SPRITE < n u m b er> [,on/off][,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 67

PARAM ETER D ESCRIPTIO N number on/off

Sprite number (1-8)

Turn sprite on (1) or o ff (0) foreground Sprite foreground color (1-16) (default = sprite number) priority Priority is 0 if sprites appear in front o f objects on the screen. Priority x-exp y-exp mode is 1 if sprites appear in back o f 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)

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.

E X A M P LE S:

SPRITE 1,1,3 Turn on sprite number 1 and color it red.

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

SPRITE 6,1,1,0,0,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.

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

C l 28 to expand the sprite vertically only. The last 1 specifies multi-color mode. Use the SPRCOLOR com mand 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 from one sprite to another.

SPRSAV < o rig in > ,< d e stin a tio 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 o f data are used. The rest are ignored since a sprite can only hold 63 data bytes.

EX A M P LE S :

SPRSAV 1,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.

68 COMMODORE 128

S S H A P E / 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: where:

SSHAPE string variable, X I, Y1 [,X2,Y2] string variable String name to save data in

X I,Y 1 Corner coordinate (0,0 through 319,199) (scaled)

X2,Y2 Corner coordinate opposite (X I,Y l) (default is the PC)

The command to retrieve (load) the data from a string variable and display it on specified screen coordinates is: where:

GSHAPE string variable [X,Y][,mode] string Contains shape to be drawn

X ,Y Top left coordinate (0,0 through 319,199) telling where to draw the shape

(scaled— the default is the pixel cursor) mode 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

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.

EX A M P LE S:

SSHAPE A $,10,10 Saves a rectangular area from the coordinates 10,10 to the location of the pixel cursor, into string vari able 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$, + 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 69

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, + 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 # b y tes, 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 # b y tes, 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.

70 COMMODORE 128

E X A M P LE S:

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.

E X A M P LE S:

TEMPO 16 Defines the Tempo at 16.

TEMPO 1 Defines the TEMPO at the slowest speed.

TEMPO 250 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$.

EX A M P LE S :

.100 TRAP 1000 If an error occurs, GOTO line 1000.

. 1000?ERR$(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 71

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 “ filenam e” f,device number][,relocate flag]

Issue the VERIFY command immediately after you SAVE a program.

EX A M P LE S :

VERIFY Checks the next program on the tape.

VERIFY “ H ELLO " Searches for HELLO on tape, checks it against memory.

VERIFY “ H ELLO” ,8,1 Searches for HELLO on disk, then checks it against memory.

VOL

Define output level of sound for SOUND and PLAY statements

VOL volume level

E X A M P LE S :

VOL 0 Sets volume to its lowest level.

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

WAST

Pause program execution until a data condition is satisfied

W AIT < lo ca tio n > , < m a s k - l> [,m ask-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.

72 COMMODORE 128

EX A M P LE S:

WAIT 1, 32, 32

WAIT 53273, 2

W AIT 36868, 144, 16

W ID T H

Set the width of drawn lines

WIDTH n

EX A M P LE S:

WIDTH 1 Set single width for graphic commands

WIDTH 2 Set double width for drawn lines

W IN D O W

Define a screen window

W INDOW 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 o f the newly described window).

EX A M P LE S :

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 FU N C TIO N S

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 “ EXAM PLE” is the function you type. The second line without bold is the com puter’s response.

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA 73

ABS

Return absolute value of argument X

A B S (X )

E X A M P LE :

PRINT ABS (7*(-5))

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$.

E X A M P LE :

X$ = “ C128” :PRINT ASC (X$)

A T N

Return the arctangent of X in radians

ATN (X)

The value returned is in the range - tt /2 through tt /2.

E X A M P LE :

PRINT ATN (3)

1.24904577

BUMP

Return sprite collision information

BU M P (N)

To determine which sprites have collided since the last check, use the BUMP function.

BU M P(l) 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.

74 COMMODORE 128

H ere’s how the sprite numbers and BUMP values that are returned correspond:

BUMP Value: 128 64 32 16 8 4 2 1

Sprite Number: 8 7 6 5 4 3 2 1

EX A M P LE S :

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 ASCII code is X. Refer to Appendix E for a table of CHR$ codes.

EX A M P LE S :

PRINT CHR$ (65) Prints the A character.

PRINT CHR$ (147) Clears the text screen.

COS

Return cosine for angle o f X in radians

COS(X)

E X A M P LE :

PRINT COS (tt /3)

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

E X A M P LE :

10 DEF FNAA(X) = (X-32)*5/9

20 INPUT X

30 PRINT FNAA(X)

RUN

?40 (? is input prompt)

4.44444445

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA 75

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.

EX A M P LE S :

PRINT FRE (0) Returns the number of free bytes for BASIC programs.

58109

PRINT FRE (1) Returns the number of free bytes for BASIC variable storage.

64256

HEX$

Return hexadecimal string equivalent to decimal number X

HEX$(X)

E X A M P LE :

PRINT HEX$(53280)

D020

INSTR

Return starting position of string 2 within string 1

INSTR (string 1, string 2 [,starting position])

E X A M P LE :

PRINT INSTR ( “ COMMODORE 128” , “ 128” )

IN T

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.

76 COMMODORE 128

EX A M P LE S :

PRINT IN T (3.14)

PRINT IN T (-3 .14)

- 4

JOY

Return position of joystick and the status of the fire button

JOY(N) when N equals:

1 JOY returns position of joystick 1.

2 JOY returns postion of joystick 2.

Any value o f 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.

EX A M P LE S :

PRINT JOY (2)

135

Joystick 2 fires to the left.

IF (JOY (1) > 127) THEN PRINT “ FIR E” Determines whether the fire button is pressed.

DIR = JO Y (l) AND 15 Returns direction (only) of joystick 1.

LEFT$

Return the leftmost characters of string

LEFT$ (string,integer)

E X A M P LE :

PRINT LEFT$(“ COM M ODORE” ,5)

COMMO

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA 77

LEN

Return the length of a string

LEN (string)

The returned integer value is in the range 0-255.

EXAMPLE:

PRINT LEN (“ COMMODORE 128” )

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

MID$ (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 ID $(“ COMMODORE 128” ,3,5)

MMODO

PEEK

Return contents o f 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 BANK 15:VIC = D EC(“ D 000” )

20 FOR I = 1 TO 47

30 PRINT PEEK(VIC + I)

40 NEXT

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

78 COMMODORE 128

PEN

Return X and Y coordinates of the light pen

PEN(n) where n = 0 PEN returns the X coordinate of light pen position on any VIC screen, n = 1 PEN returns the Y coordinate of light pen position on any VIC screen, n = 2 PEN returns the character column position o f the 80 column display, n = 3 PEN returns the character row position of the 80 column display, n = 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.

EX A M P LE S :

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)

E X A M P LE :

PRINT it 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.

E X A M P LE :

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 79

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 : ?SPC(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, POT returns the position of paddle # 1 (control port 1)

= 2, POT returns the position of paddle # 2 (control port 1)

= 3, POT returns the position of paddle # 3 (control port 2)

= 4, POT returns the position o f paddle # 4 (control port 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 PO T(l)

20 IF P O T (l) > 256 THEN PRINT “ FIR 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:

80 COMMODORE 128

SO U R CE DESCRIPTIO N

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.

E X A M P LE :

10 FOR I = 0 TO 6

20 PRINT “ SOURCE” ;I;“ IS 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.

E X A M P LE S:

PRINT RDOT(O) Returns X position of pixel cursor

PRINT RD O T(l) Returns Y position of pixel cursor

PRINT RDOT(2) 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 81

VALUE

G RAPH IC M ODE

40 column (VIC) text

Standard bit map

Split screen bit map

M ulti-color bit map

Split screen M ulti-color bit map

80 column (8563) text

E X A M P LE :

PRINT RGR(O) Displays the current graphic mode; in this case, standard bit

1 map mode.

PRINT RGR(O) Both multi-color bit map and 80-column text modes are enabled.

RIGHT$

Return sub-string from rightmost end of string

RIGHT$(string, numeric)

E X A M P L E :

PRINT RIGHT$(‘'BASEBALL” ,5)

EBALL

RND

Return a random number

RND (X)

If X = 0 RND returns a random number based on the hardware clock.

If X > 0 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.

EX A M P LE S:

PRINT RND(O)

.507824123

Displays a random number between 0 and 1.

PRINT INT(RND(1)*100 + 1) Displays a random number between 1 and 100.

82 COMMODORE 128

RSPCOLOR

Return sprite multicolor values

RSPCOLOR (X)

When:

X = 1 RSPCOLOR returns the sprite multi-color 1.

X = 2 RSPCOLOR returns the sprite multi-color 2.

The returned color value is a value between 1 and 16. The counterpart of the RSPCOLOR function is the SPRCOLOR statement. Also see the SPRCOLOR statement.

E X A M P LE :

10 SPRITE 1,1,2,0,1,1,1

20 SPRCOLOR 5,7

30 PRINT “ SPRITE MULTI-COLOR 1 1S” ;R SPC 0L 0R (1)

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.

E X A M P LE :

10 SPRITE 1,1,2

20 MOVSPR 1,45# 13

30 PRINT RSPPOS (1,0);RSPPOS (l,l);R S P P O S (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 83

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:

C H A R A C TERISTIC

RSPR ITE RETURNS

TH ESE VALUES:

E nabled(l) / disabled(O)

Sprite color (1-16)

Sprites are displayed in front of (0) or behind

(1) objects on the screen

Expand in

M ulti-color

X direction

Y direction yes = 1, no = 0 yes = 1, no = 0 yes = 1, no = 0

E X A M P LE :

10 FOR 1 = 0 TO 5

20 PRINT RSPRITE (1,1)

30 NEXT

This example prints all 6 characteristics of sprite 1.

R W IN D O W

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.

E X A M P LE :

10 WINDOW 1,1,10,10

20 PRINT RW INDOW(0);RWINDOW( 1 );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.

84 COMMODORE 128

SGN

Return sign of argument X

SGN(X)

E X A M P LE :

PRINT SGN(4.5);SGN(0);SGN(-2.3)

1 0 - 1

SIN

Return sine of argument

SIN(X)

E X A M P LE :

PRINT SIN ( it / 3 )

.866025404

SPC

Skip spaces on printed output

SPC (X)

E X A M P LE :

PRINT “ COM M ODORE” ;SPC(3);“ 128”

COMMODORE 128

SQR

Return square root of argument

SQR (X)

E X A M P LE :

PRINT SQR(25)

STR$

Return string representation of number

S T R $ (X )

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA 85

E X A M P LE :

PRINT STR$(123.45)

123.45

PRINT STR$(-89.03)

-89.03

PRINT STR$(1E20)

IE + 20

TAB

Moves cursor to tab position in present statement

TAB (X)

E X A M P LE :

10 PRIN T“ COM M ODORE” TAB(25)“ 128”

COMMODORE 128

T A N

Return tangent of argument in radians

TAN(X)

This function returns the tangent of X, where X is an angle in radians

E X A M P LE :

PRINT T A N (.785398163)

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 machine- language program in the floating-point accumulator ($63-$68 in C l 28 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.

86 COMMODORE 128

E X A M P LE :

10 POKE 4633,0

20 POKE 4634,48

30 A = USR(X)

40 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 floating point accumulator. The USER vector is assumed to be in BANK 15. Your machine language routine M U ST be in RAM bank 0 below address $4000.

VAL

Return the numeric value of a number string

VAL(X$)

E X A M P LE :

10 A$ = “ 120”

20 B$ = “ 365”

30 PRINT VAL (A$ + B$)

RUN

485

X O R

Return exclusive OR value

XOR (n l,n 2)

This function returns the exclusive OR o f the numeric argument values n l and n2.

X = XOR (n l,n 2) where n l, n2, are 2 unsigned values (0-65535)

E X A M P LE :

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 87

ABS

AND

DELETE

DIM

HELP

HEX$

APPEND DIRECTORY IF

POT

PRINT#

ASC

ATN

DLOAD

INPUT

INPUT#

PUDEF

(QUIT)

AUTO

BEND

BLOAD

BOOT

BOX

BSAVE

CHR$

CIRCLE

CLR

CMD

DOPEN

BACKUP DRAW

BANK DS

BEGIN DS$

DSAVE

BUMP

CATALOG ER

CHAR ERR$

INSTR

INT

JOY

KEY

LEFTS

RCLR

RDOT

READ

RECORD

REM

DVERIFY

ELSE

END

LEN

LET

LIST

LOAD

RENAME

RENUMBER

RESTORE

RESUME

ENVELOPE LOCATE RETURN

EXIT

EXP

FAST

FETCH

FILTER

COLLECT FN

COLLISION FOR

LOG

LOOP

MID$

MONITOR

RGR

RIGHTS

RND

RREG

MOVSPR RSPCOLOR

NEW

NOT

(OFF)

RSPPOS

RSPRITE

RUN

RWINDOW

COLOR

CONCAT

CONT

COPY

FRE

GET

G ET#

G064

OPEN

PAINT

PEEK

SAVE

SCALE

SCNCLR

SCRATCH

SGN COS GOSUB

DATA GOTO

DCLEAR GO TO

DCLOSE GRAPHIC

DEC

DEF FN

GSHAPE

HEADER

PEN

PLAY

POINTER SLOW

POKE

POS

SIN

SLEEP

SOUND

SPC

TAN

TEMPO

THEN

TI$

TRAP

TROFF

TRON

UNTIL

USING

USR

VAL

VERIFY

VOL

WAIT

WHILE

WIDTH

WINDOW

XOR

SPRCOLOR

SPRDEF

SPRITE

SPRSAV

SQR

SSHAPE

STASH

STEP

STOP

STR$

SWAP

SYS

TAB

N O T E : 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 o f 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.

88 COMMODORE 128

TI and TI$ are variables that relate to the real time clock built into the Commodore

128. The system clock is updated every 1 /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.

E X A M P LE :

TI$ = “ 101530” Sets the clock to 10:15 and 30 seconds (AM).

The value o f 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 o f 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 o f 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.

RESERVED SYSTEM SYMBOLS

The following characters are reserved system symbols.

SYMBOL

Plus sign

—

* t

)

M inus sign

Asterisk

Slash

Up arrow

Blank space

Equal sign

Less than

Greater than

Comma

USE(S)

Arithmetic addition; string concatenation; relative pixel cursor/sprite movement; declare decim al num ber in ma chine 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

Format output in variable lists; com m and/statem ent func tion parameters

BASIC BUILDING BLOCKS A N D BASIC 7.0 ENCYCLOPEDIA 89

6 6 91

(

)

S Y M B O L

Period

Semicolon

Colon

Quotation mark

Question mark

Left parenthesis

Right parenthesis

Percent

Number

Dollar sign

And sign

USE(S)

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

Declare a variable name as integer; declare binary num ber in machine language monitor

Precede the logical fde number in input/output statements

Declare a variable name as a string and declare hexadeci mal number in machine language monitor

Declare octal number in machine language monitor

Declare the numeric constant 3.141592654

ONE STEP

BEYOND

SIMPLE B A S I C

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 o f a program.

Here is a general example of a menu program:

5 R E M ME N U S K E L E T O N

1 0 S C N C L R 0

2 0 P R I N T " 1 . F I R S T I T E M "

3 0 P R I N T " 2 . S E C O N D I T E M "

4 0 P R I N T " 3 . T H I R D I T E M "

5 0 P R I N T " 4 . F O U R T H I T E M "

1 0 0 P R I N T : P R I N T " S E L E C T AN I T E M F R O M A B O V E "

1 1 0 G E T K E Y A 5

1 2 0 A = V A L ( A S ) : I F A > 4 T H E N 1 0

1 3 0 ON A G O S U B 1 0 0 0 , 2 0 0 0 , 3 0 0 0 , 4 0 0 0

1 4 0 G O T O 1 0 : RE M R E T U R N T O MENU

9 9 9 S T O P

1 0 0 0 R E M S T A R T F I R S T R O U T I N E F O R I T E M O N E H E R E

1 9 9 9 R E T U R N

2 0 0 0 R E M S T A R T S E C O N D R O U T I N E H E R E

2 9 9 9 R E T U R N

3 0 0 0 R E M S T A R T T H I R D R O U T I N E H E R E

3 9 9 9 R E T U R N

4 0 0 0 R E M S T A R T F O U R T H R O U T I N E H E R E

4 9 9 9 R E T U R N

P ro g ram 3—1. M enu 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 BEYO ND SIMPLE BASIC 93

BUFFER ROUTINE

The C l 28 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 10— the 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 “ ?CHR$(156)” on the screen, but does not execute the instruction. Line 50 displays the word “ LIST” 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.

1 0 P O K E 2 0 8 , 7 : R E M S P E C I F Y # O F C H A R S I N B U F F E R

2 0 F O R 1 = 8 4 2 T O 8 4 9 : P O K E 1 , 1 3 : N E X T : R E M P L A C E C H A R S I N B U F F E R

3 0 S L E E P 2 : R E M D E L A Y

4 0 S C N C L R : 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 : P R I N T " ? C H R $ ( 1 5 6 ) ' '

5 0 P R I N T : P R I N T : P R I N T : P R I N T " L I S T " : R E M P L A C E L I S T ON S C R E E N

6 0 P R I N T C H R $ ( 1 9 ) : P R I N T : P R I N T : R E M GO HOME A N D C U R S O R DOWN T W I C E

7 0 R E M WHE N P R O G R A M E N D S , B U F F E R E M P T I E S A N D E X E C U T E S 7 R E T U R N S .

8 0 R E M T H I S C H A N G E S C H A R C O L O R T O P U R P L E A N D L I S T S T H E P R O G R A M

9 0 R E M A S I F Y O U P R E S S E D T H E R E T U R N K E Y MA N U A L L Y

A U T O M A T I C A L L Y

P ro g ram 3 -2 . B u ffer 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.

94 COMMODORE 128

2 C O L O R 4 , 1 : C O L O R 0 , 1 : C O L O R 5 , 1

5 A $ = " P I C T U R E "

1 0 S C N C L R : P R I N T : P R I N T : P R I N T : P R I N T " L O A D " C H R $ ( 3 4 ) A $ C H R $ ( 3 4 ) " , 8 , 1 "

1 5 P R I N T : P R I N T : P R I N T " N E W "

2 5 B $ = " F I L E 3 . B I N "

3 0 P R I N T : P R I N T : P R I N T " L O A D " C H R $ ( 3 4 ) B $ C H R $ ( 3 4 ) " , 8 , 1 "

4 5 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 " S Y S 1 2 * 2 5 6 "

9 0 P R I N T C H R $ ( 5 ) : P R I N T " G R E E T I N G S F R O M C O M M O D O R E "

1 0 0 P R I N T " P L E A S E S T A N D B Y - L O A D I N G " : P R I N T C H R $ ( 1 4 4 )

2 0 0 P R I N T C H R $ ( 1 9 )

3 0 0 P O K E 2 0 8 , 7 : F O R I = 8 4 2 T 0 8 5 1 : P O K E I , 1 3 : N E X T

P ro g ra m 3 -3 . Loading Routine

Line 2 colors the border, screen and characters black. Line 5 assigns A$ the filename “ PICTURE” , 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 EW ” 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 instruc tion for the machine language program “ FIL E 3.B IN ” . 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 ($OCOO) once the keyboard buffer empties. This is only a template sample for you to follow.

“ PICTURE” 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

“ PICTURE” and “ F1LE3.BIN” . Line 300 is the buffer routine.

If you were to do each step manually it would require seven “ RETURNS” . 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

C l 28 F U N C T IO N KEYS

As each of the function keys (FI 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 95

C H A N G IN G F U N C T IO N 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, “ DLO A D ” + C H R $(34)+ “ PROGRAM NAM E”

+ CHR$(34) + CHR$( 13) + “ LIST” + CHR$( 13)

This tells the computer to automatically load the BASIC program called “ program nam e” and list it immediately (whenever FI 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 F U N C T IO N KEY VALUES

IN C l 28 MODE

Programs previously written for the C64 which incorporate the function keys may still be used in C l 28 mode by first assigning the C64 ASCII values to them with this instruction:

10J = 132:FORA = 1T 02:F0R K = AT08STEP2:J = J + 1 :KEYK,CHR$(J):NEXT:

H O W T O CRUNCH B A S I C PROGRAMS

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

E L IM IN A T IN G 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 NAM E” ;N$:FOR T = A TO M:PR1NT “ O K ” :

10INPUT1 ‘FIRST NAM E’’;N$:FORT = ATOM :PRINT‘‘O K ” :

96 COMMODORE 128

USING MULTIPLE IN STR U C TIO N S

Colons allow you to place several instructions within a single program line. Each program line consumes additional memory. Be careful, however, crunching IF state ments. 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

(B)

10 PRINTX

20 INPUTY

30 PRINTY

40 SCNCLRO

50 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.

S Y N T A X 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 vari ables. DIMension all arrays (subscripted variables) to have twelve or more elements. The

C l 28 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 PRIN T” A ” ;Z$;“ W ORD” ;CHR$(65);“ NOW $ ”

20 P R IN T '‘A ” Z $‘‘W ORD” CHR$(65)“ NOW $ ”

REM OVING R EM 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. O f 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 BEYO ND SIMPLE BASIC 97

USING B A S I C INTELLIG ENTLY

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 Y

0 0

0 1

1 0

I 1

X AND Y

X OR Y

T a b le 3 -1 . A N D and O R T ru th T ab le

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:

5 = 0000 0101

0000 0110

ANDed 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 “ 0100” 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:

98 COMMODORE 128

5 = 0000 0101

0000 0110

ORing 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 com puter’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 M O D IFY

T H E BIT VALUES IN A BYTE

A byte is a group o f 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 6 5 4 3 2 1 0 and the corresponding values in decimal are:

128 64 32 16 8 4 2 1

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 (1 2 8 + 1 6 ), these two bits are turned on. To turn bits on, store

(POKE) a new value to that byte— a value equal to the sum of all the decimal equivalents o f all the bits that are enabled (on). O f 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 o f 0. Had it already been

“ o n ,” it would have no effect. To prevent such confusion, the C l 28 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 off—with a slight difference.

AND results in a “ 1” only if both bits compared are “ 1.” The trick is to compare the

ONE STEP BEYO ND SIMPLE BASIC 99 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

EX A M P LE S:

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 = 126)

POKEC,PEEK(C)AND254 Turns OFF bit 0

POKEC,PEEK( V)OR63 Turns ON all bits except 6 and 7

DEBUGGING PROGRAMS

No program when first written is free of “ bugs” or errors. The process o f finding errors and removing them, debugging, combines editing with problem solving.

S Y N T A X ERRORS

Syntax errors result from misspelling or misusing the guidelines and formats o f 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 o f line numbers that do not exist, etc.

LO GIC 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.

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 o f 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 o f the program.

5 TRAP 50

10 INPUT A,B

20 PRINT A/B

30 GOTO 10

50 PRIN T“ DIVISION BY ZERO IS NOT POSSIBLE”

60 PR1NT“ ENTER ANOTHER NUMBER FOR B BESIDES ZERO ’

70 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 error— line 20— and 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 BEYO ND SIMPLE BASIC 101

ERROR F U N C TIO N S

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 ZERO ” and ERR$(EL) returns “ BREAK” . Add this to the program in the previous section. See Appendix A for a complete listing of errors.

D O S 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)

TR A C IN G 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 ( O ) key down.)

Try it with this double loop:

10 FOR A = 1T05

20 FOR B = 2T06

30 C = B* A:K = K + C:PRINTK

40 NEXTB:NEXTA

50 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.

102 COMMODORE 128

W IN D O W IN G

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 “ w indow ing.”

D EFIN IN G A W IN D O W

There are two ways to create a window— either 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. Move the cursor to the upper-left com er position of the proposed window.

Press the (ESC) escape key, then press the letter T key.

2. 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 bottom- right 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.

ONE STEP BEYOND SIMPLE BASIC 103

AD VA N C ED B A S I C

PROGRAMMING TECHNIQUES

FOR COMMODORE MODEMS

The following information tells you how to:

1. Generate Touch Tone™ frequencies

2. Detect telephone ringing

3. Program the telephone to be on or off the hook

4. Detect carrier

The programming procedures operate in C128 or C64 modes with the Modem/300.

In C128 mode, select a bank configuration which contains BASIC, I/O, and the Kernal.

GENERATING T O U C H TO N E

(DTM F) 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:

Row 1 (697 Hz)

Row 2 (770 Hz)

Row 3 (852 Hz)

Row 4 (941 Hz)

T O U C H T O N E F R E Q U E N C Y T A B L E

COLUM N 1 (1029 HZ)

COLUMN 2 (1336 HZ)

COLUM N 3 (1477 HZ)

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 = 54272

POKE SID + 2 4 .15:POKE SID +

POKE SID + 1 1 ,16:POKE SID +

POKE SID + 6,15* 16:POKE SID

4,16

5,0:POKE SID + 12,0

+ 13,15*16:POKE SID + 23,0

2. 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:

104 COMMODORE 128

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

Column 2: POKE SID,152:POKE SID + 1,85

Column 3: POKE SID, 161, POKE SID + 1,94

Row 1: POKE SID + 7,168:POKE SID + 8,44

Row 2: POKE SID + 7,85,:PO K E 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 SID + 7 , 168:POKE SID + 8,44:REM ROW 1

POKE SID, 117:POKE SID + 1,77:REM COLUMN 1

3. Turn on the tones and add a time delay with these statements:

POKE SID + 4,17:POKE SID + 11,17:REM ENABLE TONES

FOR 1= 1 TO 50:NEXT:REM TIME DELAY

4. Turn off the tones and add a time delay with the following statements:

POKE SID + 4,16:POKE SID + 11,16:REM DISABLE TONES

FOR 1= 1 TO 50:NEXT:REM TIME DELAY

5. Now repeat steps 2 through 4 for each digit in the telephone number you are dialing.

6. 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 “ RINGING”

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 H O O K

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 + 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 BEYO ND SIMPLE BASIC 105

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

1. Set the modem ’s answer/originate switch to the “ O ” for originate.

2. Program the telephone to be OFF the hook.

3. Wait 2 seconds (FOR I = 1 to 500:NEXT:REM 2-SECOND DELAY)

4. Dial each digit and follow it with a delay (FOR I = 1 TO 50:NEXT)

5. When a carrier (high pitched tone) is detected, the Modem/300 automatically goes on-line with the computer you are connecting with.

6. Program the phone to hang up when you are finished.

Here is the procedure to answer a call:

1. Set the modem ’s answer/originate switch to “ A ” for answer.

2. To manually answer, program the telephone to be OFF the hook.

3. To automatically answer, detect if the phone is ringing then program the phone to be OFF the hook.

4. The Modem/300 automatically answers the call.

5. Program the phone to hang up when you are finished.

DETEC TIN G CARRIER

Your Commodore M odem /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 o f 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 “ off-hook” (the equivalent of you picking up the receiver). Then to dial the first digit, a 3 for instance,

106 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.

U SING 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 o f Chapter 13 for all the escape and control codes available on the Commodore 128.)

RELO CATING 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 instruc tion 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 0 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 IK, from 7168 to 8192, use this command line:

POKE 46,32: POKE45,1: NEW

This is the case only when a bit-mapped graphics screen is not allocated. Remem ber, 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 BEYO ND SIMPLE BASIC 107

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. C l 28 BASIC has included the APPEND command to accomplish this:

A PPE N D #5, “ FILE N A M E” opens channel 5 to a previously stored file named “ FILE N A M E .” Subsequent write

(PR IN T #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) o f two files or programs while maintaining the name of the first.

CONCAT“ PART2B” TO “ PART2” 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 o f 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.

COMMODORE

128

GRAPHICS

PROGRAMMING

HOW TO USE

T H E

GRAPHICS SYSTEM

NO COMMODORE 128

COMMODORE 128 VIDEO FEATURES

In C128 M ode, 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 displays— the 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 C l 28 video hardware features offer high price/performance value for any microcomputer application.

The C l 28 graphics features include:

■ Specialized graphics and sprite commands

■ 16 colors

■ 6 display modes, including:

Standard character mode

M ulti-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 anima tion possible

■ Custom programmable characters

■ Vertical and horizontal scrolling

The Commodore 128 is capable of producing two types of video signals: 40- column 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 64— mixes 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 80- column chip, primarily designed for business applications, also supports sixteen colors

(a few o f 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 111

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 o f sprites, their storage and addressing requirements, color assignments, and describes how to control sprites through machine language.

TYPES OF SCREEN DISPLAY

Your C l 28 displays information several different ways on the screen; the parameter

“ source” in the command pertains to three different modes of screen display.

T E X T DISPLAY

Text display shows only text or characters, such as letters, numbers, special symbols and the graphics characters on the front faces of most C l 28 keys. The C l 28 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. W hen 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 o f sixteen colors on a background of one of sixteen colors.

M ulti-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.

M ulti-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) o f 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

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 o f 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 of two 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 o f 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 o f 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 C l 28 is capable of this since it depends on two parts o f its memory to store the two screens: one part for text, and the other for graphics.

COMMODORE 128 GRAPHICS PROGRAMMING 113

C O M M AN D SUMMARY

Following is abrief explanation of each graphics command available in BASIC 7.0:

B O X : Draws rectangles on the bit-map screen

C H A R : Displays characters on the bit-map screen

C IR C LE : Draws circles, ellipses and other geometric shapes

C O L O R : Selects colors for screen border, foreground, background and characters

D R A W : Displays lines and points on the bit-map screen

G R A P H IC : Selects a screen display (text, bit map or split-screen bit map)

G S H A P E : Gets data from a string variable and places it at a specified position on the bit-map screen

L O C A T E : Positions the bit-map pixel cursor on the screen

P A IN T : Fills area on the bit-map screen with color

SCALE: Sets the relative size of the images on the bit-map screen

SSH APE: Stores the image of a portion o f the bit-map screen into a text-string variable

W ID 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 o f these commands, see the BASIC 7.0 Encyclopedia in Chapter 2.

B O X

Draw a box at a specified position on the screen.

where:

BOX [color source], X I, Y l[,X 2,Y 2][,angle][,paint] color source

X I, Y l

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, Y l, is the pixel cursor location (scaled)

Rotation in clockwise degrees; default is 0 degrees

Paint shape with color

0 = Do not paint

1 = Paint

114 COMMODORE 128

E X A M P LE S :

1 0 C O L O R 0 , 1 : C O L O R 1 , 6 : C O L O R 4 , 1

2 0 G R A P H I C 1 , 1 : R E M S E L E C T BMM

3 0 B O X 1 , 1 0 , 1 0 , 7 0 , 7 0 , 9 0 , 1 : R E M DRAW F I L L E D G R E E N B O X

4 0 F O R 1 = 2 0 T O 1 4 0 S T E P 3

5 0 B O X 1 , 1 , 1 , 1 + 6 0 , 1 + 6 0 , 1 + 8 0 : R E M DRAW A N D R O T A T E B O X E S

6 0 N E X T

7 0 B O X 1 , 1 4 0 , 1 4 0 , 2 0 0 , 2 0 0 , 2 2 0 , 1 : R E M DRAW 2 N D F I L L E D G R E E N B O X

8 0 C O L O R 1 , 3 : R E M S W I T C H T O R E D

9 0 B O X 1 , 1 5 0 , 2 0 , 2 1 0 , 8 0 , 9 0 , 1 : R E M DRAW F I L L E D R E D B O X

1 0 0 F O R 1 = 2 0 T O 1 4 0 S T E P 3

1 1 0 B O X 1 , 1 + 1 3 0 , I , 1 + 1 9 0 , 1 + 6 0 , I + 7 0 : R E M DRAW AN D R O T A T E R E D B O X E S

1 2 0 N E X T

1 3 0 B O X 1 , 2 7 0 , 1 4 0 , 3 3 0 , 2 0 0 , 2 1 0 , 1 : RE M DRAW 2 N D F I L L E D R E D B O X

1 4 0 S L E E P 5 : R E M D E L A Y

1 5 0 G R A P H I C 0 , 1 : R E M S W I T C H T O T E X T MODE

1 0 C O L O R 0 , 1 : C O L O R 4 , 1 : C O L O R 1 , 6

2 0 G R A P H I C 1 , 1

3 0 B O X 1 , 0 , 0 , 3 1 9 , 1 9 9

4 0 F O R X = 1 0 T O 1 6 0 S T E P 1 0

5 0 C = X / 1 0

6 0 C O L O R 1 , C

7 0 B O X 1 , X , X , 3 2 0 - X , 3 2 0 - X

8 0 N E X T

9 0 S L E E P 5

1 0 0 G R A P H I C 0 , 1

1 0 C O L O R 0 , 1 : C O L O R 4 , 1 : C O L O R 1 , 6

2 0 G R A P H I C 1 , 1

3 0 B O X 1 , 5 0 , 5 0 , 1 5 0 , 1 2 0

4 0 B O X 1 , 7 0 , 7 0 , 1 7 0 , 1 4 0

5 0 DRAW 1 , 5 0 , 5 0 T O 7 0 , 7 0

6 0 DRAW 1 , 1 5 0 , 1 2 0 T O 1 7 0 , 1 4 0

7 0 DRAW 1 , 5 0 , 1 2 0 T O 7 0 , 1 4 0

8 0 DRAW 1 , 1 5 0 , 5 0 T O 1 7 0 , 7 0

9 0 C H A R 1 , 2 0 , 2 0 , " C U B E E X A M P L E "

1 0 0 S L E E P 5

1 1 0 G R A P H I C 0 , 1

1 0 C O L O R 1 , 6 : C O L O R 4 , l : C O L O R 0 , 1

2 0 G R A P H I C 1 , 1 : R E M S E L E C T B I T MAP MOD E

3 0 DO : R E M C A L C U L A T E RA N D O M P O I N T S

4 0 X 1 = 1 N T ( R N D ( 1 ) * 3 1 9 + 1 )

5 0 X 2 = I N T ( R N D ( 1 ) * 3 1 9 + 1 )

6 0 X 3 = I N T ( R N D ( 1 ) * 3 1 9 + 1 }

7 0 X 4 = I N T ( R N D ( 1 ) * 3 1 9 + 1 )

8 0 Y 1 = I N T ( R N D ( 1 ) * 1 9 9 + 1 )

9 0 Y 2 = I N T ( R N D ( 1 ) * 1 9 9 + 1 )

1 0 0 Y 3 = 1 N T ( R N D ( 1 ) * 1 9 9 + 1 )

1 1 0 Y 4 = I N T ( R N D ( 1 ) * 1 9 9 + 1 )

1 2 0 B O X 1 , X 1 , Y 1 , X 2 , Y 2 : R E M DRAW T H E RA N D O M B O X E S

1 3 0 B O X 1 , X 3 , Y 3 , X 4 , Y 4

1 4 0 DRAW 1 , X I , Y 1 T O X 3 , Y 3 : R E M C O N N E C T T H E P O I N T S

1 5 0 DRAW 1 , X 2 , Y 2 T O X 4 , Y 4

1 6 0 DRAW 1 , X 1 , Y 2 T O X 3 , Y 4

1 7 0 DRAW 1 , X 2 , Y 1 T O X 4 , Y 3

1 8 0 S L E E P 2 : R E M D E L A Y

1 9 0 S C N C L R

2 0 0 L O O P : R E M L O O P C O N T I N U O U S L Y

COMMODORE 128 GRAPHICS PROGRAMMING 115

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

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 = o n )

E X A M P LE :

10 COLOR 2,3: REM multi-color 1 = R ed

20 COLOR 3,7: REM multi-color 2 = Blue

30 GRAPHIC 3,1

40 CHAR 0,10,10, “ TEX 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

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)

EX A M P LE S :

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.

116 COMMODORE 128

CIRCLE1, 2 6 0 ,4 0 ,2 0 ,,,,,9 0 Draws a diamond.

CIRCLE 1, 6 0 ,1 40,20,18,,,, 120 Draws a triangle.

C IR C L E 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.

SA M PLE PRO G RAM S:

1 0 R E M S U B M A R I N E T R A C K I N G S Y S T E M

2 0 C O L O R 0 , 1 : C O L O R 4 , 1 : C O L O R 1 , 2 : R E M S E L E C T B K G R N D , B R D R , S C R E E N C O L O R S

3 0 G R A P H I C 1 , 1 : R E M E N T E R B I T MAP MOD E

4 0 B O X 1 , 0 , 0 , 3 1 9 , 1 9 9

5 0 C H A R 1 , 7 , 2 4 , " S U B M A R I N E T R A C K I N G S Y S T E M " : R E M D I S P L A Y C H A R S O N B I T MAP

6 0 C O L O R 1 , 3 : R E M S E L E C T R E D

7 0 X R = 0 : Y R = 0 : R E M I N I T X A N D Y R A D I U S

8 0 DO

9 0 C I R C L E 1 , 1 6 0 , 1 0 0 , X R , Y R , 0 , 3 6 0 , 0 , 2 : R E M DRAW C I R C L E S

1 0 0 X R = X R + 1 0 : Y R = Y R + 1 0 : R E M U P D A T E R A D I U S

1 1 0 L O O P U N T I L X R = 9 0

1 2 0 DO

1 3 0 X R = 0 : Y R = 0

1 4 0 DO

1 5 0 C I R C L E 0 , 1 6 0 , 1 0 0 , X R , Y R , 0 , 3 6 0 , 0 , 2 : R E M E R A S E C I R C L E

1 6 0 C O L O R 1 , 2 : R E M S W I T C H T O W H I T E

1 7 0 DRAW 1 , 1 6 0 , 1 0 0 + X R : D R A W 0 , 1 6 0 , 1 0 0 + X R : RE M DRAW S U B M A R I N E B L I P

1 8 0 C O L O R 1 , 3 : R E M S W I T C H B A C K T O R E D

1 9 0 S O U N D 1 , 1 6 0 0 0 , 1 5 : R E M B E E P

2 0 0 C I R C L E 1 , 1 6 0 , 1 0 0 , X R , Y R , 0 , 3 6 0 , 0 , 2 : R E M DRAW C I R C L E

2 1 0 X R = X R + 1 0 : Y R = Y R + 1 0 : R E M U P D A T E R A D I U S

2 2 0 L O O P U N T I L X R = 9 0 : R E M L O O P

2 3 0 L O O P

1 0 C O L O R 0 , 1 : C O L O R 4 , 1 : C O L O R 1 , 7

2 0 G R A P H I C 1 , 1 : R E M S E L E C T BMM

3 0 X = 1 5 0 : Y = 1 5 0 : X R = 1 5 0 : Y R = 1 5 0

4 0 DO

5 0 C I R C L E 1 , X , Y , X R , YR

6 0 X = X + 7 : Y = Y - 5 : RE M I N C R E M E N T X AN D Y C O O R D I N A T E S

7 0 X R = X R - 5 : Y R = Y R - 5 : R E M D E C R E M E N T X A N D Y R A D I I

8 0 L O O P U N T I L X R = 0

9 0 G R A P H I C 0 , 1 : R E M S E L E C T T E X T 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

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-column background color

Colors codes are in th e range 1-16.

COMMODORE 128 GRAPHICS PROGRAMMING 117

C O LO R CODE

COLOR

Black

White

Red

Cyan

Purple

Green

Blue

Yellow

CO LOR CODE

C o lo r Codes in 40-C olum n (V IC ) O u tp u t

COLO R

Orange

Brown

Light Red

Dark Gray

Medium Gray

Light Green

Light Blue

Light Gray

E X A M P LE :

COLOR 0, 1: Changes background color of 40-column screen to black.

COLOR 5, 8: Changes character color to yellow.

SA M PLE PR O G R A M :

1 0 R E M C H A N G E F O R E G R O U N D B I T MAP C O L O R

2 0 G R A P H I C 1 , 1

3 0 1 = 1

4 0 DO

5 0 C O L O R 1 , 1

6 0 B O X 1 , 1 0 0 , 1 0 0 , 2 1 9 , 1 5 9

7 0 1 = 1 + 1 : S L E E P 1

8 0 L O O P U N T I L 1 = 1 7

9 0 G R A P H I C 0 , 1

1 0 0 R E M C H A N G E B O R D E R C O L O R

110 1=1

1 2 0 DO

1 3 0 C O L O R 4 , 1

1 4 0 1 = 1 + 1 : S L E E P 1

1 5 0 L O O P U N T I L 1 = 1 7

1 6 0 R E M C H A N G E C H A R A C T E R C O L O R

1 7 0 1 = 1

1 8 0 DO

1 9 0 C O L O R 5 , 1

2 0 0 P R I N T " C O L O R C O D E " ; I

2 1 0 1 = 1 + 1 : S L E E P 1

2 2 0 L O O P U N T I L 1 = 1 7

2 3 0 R E M C H A N G E B A C K G R O U N D C O L O R

2 4 0 1 = 1

2 5 0 DO

2 6 0 C O L O R 0 , 1

2 7 0 1 = 1 + 1 : S L E E P 1

2 8 0 L O O P U N T I L 1 = 1 7

2 9 0 C O L O R 0 , 1 : C O L O R 4 , l : C O L O R 5 , 2

DRAW

Draw dots, lines and shapes at specified positions on screen.

DRAW [color source], [X I, Y l][T O X2, Y2] . . .

Here are the parameter values:

118 COMMODORE 128 where: color source 0 Bit map background

1 Bit map foreground

X I ,Y l

X2,Y2

2 Multi-color 1

3 Multi-color 2

Starting coordinate (0,0 through 319,199) (scaled)

Ending coordinate (0,0 through 319,199) (scaled)

EX A M P LE S :

DRAW 1, 100, 50

DRAW , 10, 10 TO 100,60

Draw a dot.

Draw a line.

DRAW , 10, 10 TO 10,60 TO 100,60 TO 10,10 Draw a triangle.

SAM PLE PRO G RAM S:

1 0 R E M DRAW E X A M P L E S

2 0 C O L O R 0 , 1 : C O L O R 4 , 1 : C O L O R 1 , 6

3 0 G R A P H I C 1 , 1

4 0 C H A R 1 , 1 0 , 1 , " T H E DRAW C OMMAND"

5 0 X = 1 0

6 0 DO

7 0 DRAW 1 , X , 5 0 : R E M DRAW P O I N T S

8 0 X = X + 1 0

9 0 L O O P U N T I L X = 3 2 0

1 0 0 C H A R 1 , 1 2 , 7 / ' D R A W S P O I N T S "

1 1 0 Y = 7 0

1 2 0 DO

1 3 0 Y = Y + 5

1 4 0 DRAW 1 , 1 , Y T O Y , Y : R E M DRAW L I N E S

1 5 0 L O O P U N T I L Y = 1 3 0

1 6 0 C H A R 1 , 1 8 , 1 1 , " L I N E S "

1 7 0 DRAW 1 , 1 0 , 1 4 0 T O 1 0 , 1 9 9 T O 9 0 , 1 6 5 T O 4 0 , 1 6 0 T O 1 0 , 1 4 0 : R E M DRAW S H A P E 1

1 8 0 DRAW 1 , 1 2 0 , 1 4 5 T O 1 4 0 , 1 9 5 T O 1 9 5 , 1 9 5 T O 2 2 5 , 1 4 5 T O 1 2 0 , 1 4 5 : R E M DRAW S H A P E

1 9 0 DRAW 1 , 2 5 0 , 1 9 9 T O 3 1 9 , 1 9 9 T O 3 1 9 , 6 0 T O 2 5 0 , 1 9 9 : R E M DRAW S H A P E 3

2 0 0 C H A R 1 , 2 2 , 1 5 , " A N D S H A P E S "

2 1 0 S L E E P 5 : G R A P H I C 0 , 1

1 0 C O L O R 0 , 1 : C O L O R 4 , 1 : C O L O R 1 , 7

2 0 G R A P H I C 1 , 1 : R E M S E L E C T BMM

3 0 Y = 1

4 0 DO

5 0 DR AW 1 , 1 , Y T O 3 2 0 , Y : R E M DRAW H O R I Z O N T A L L I N E S

6 0 Y = Y + 1 0

7 0 L O O P W H I L E Y < 2 0 0

7 5 X = 1

8 0 DO

9 0 DRAW 1 , X , 1 T O X , 2 0 0 : R E M DRAW V E R T I C A L L I N E S

9 5 X = X + 1 0

9 7 L O O P W H I L E X < 3 2 0

1 0 0 C O L O R 1 , 3 : R E M S W I T C H T O R E D

1 1 0 DRAW 1 , 1 6 0 , 0 T O 1 6 0 , 2 0 0 : R E M DRAW X A X I S I N R E D

1 2 0 DRAW 1 , 0 , 1 0 0 T O 3 2 0 , 1 0 0 : R E M DRAW Y A X I S I N R E D

1 3 0 C O L O R 1 , 6 : RE M S W I T C H T O G R E E N

1 4 0 DRAW 1 , 0 , 1 9 9 T O 5 0 , 1 0 0 T O 9 0 , 5 0 T O 1 1 0 , 3 0 T O 1 5 0 , 2 0 T O 1 8 0 , 3 0

1 5 0 DRAW 1 , 1 8 0 , 3 0 T O 2 2 0 , 1 0 T O 2 6 0 , 8 0 T O 3 2 0 , 0 : R E M DRAW G R OWT H C U R V E

1 6 0 C H A R 1 , 7 , 2 3 , " P R O J E C T E D S A L E S T H R O U G H 1 9 9 0 "

1 7 0 C H A R 1 , 1 , 2 1 , " 1 9 7 0 1 9 7 5 1 9 8 0 1 9 8 5 1 9 9 0 "

1 8 0 S L E E P 1 0 : G R A P H I C 0 , 1 : R E M D E L A Y A N D S W I T C H T O T E X T MODE

COMMODORE 128 GRAPHICS PROGRAMMING 119

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:

M ODE

DESCRIPTIO N

40-coluinn text 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 Select standard bit map mode and clear the bit map.

GRAPHIC 4,0,10 Select split screen multi-color bit map mode, do not clear

GRAPHIC 0 the bit map and start the split screen at line 10.

Select 40-column text.

GRAPHIC 5

GRAPHIC CLR

Select 80-column text.

Clear and deallocate the bit map screen.

SAMPLE PROGRAM:

1 0 R E M G R A P H I C M O D E S E X A M P L E

2 0 C O L O R 0 , 1 : C O L O R 4 , 1 : C O L O R 1 , 7

3 0 G R A P H I C 1 , 1 : R E M E N T E R S T N D B I T MAP

4 0 C I R C L E 1 , 1 6 0 , 1 0 0 , 6 0 , 6 0

5 0 C I R C L E 1 , 1 6 0 , 1 0 0 , 3 0 , 3 0

6 0 C H A R 1 , 9 , 2 4 , " S T A N D A R D B I T M A P M O D E "

7 0 S L E E P 4

8 0 G R A P H I C 0 , 1 : R E M E N T E R S T N D C H A R MODE

9 0 C O L O R 1 , 6 : R E M S W I T C H T O G R E E N

1 0 0 F O R 1 = 1 T O 2 5

1 1 0 P R I N T " S T A N D A R D C H A R A C T E R M O D E "

1 2 0 N E X T

1 3 0 S L E E P 4

1 4 0 G R A P H I C 2 , 1 : RE M S E L E C T S P L I T S C R E E N

1 5 0 C I R C L E 1 , 1 6 0 , 7 0 , 5 0 , 5 0

1 6 0 C H A R 1 , 1 4 , 1 , " S P L I T S C R E E N "

1 7 0 C H A R 1 , 8 , 1 6 , " S T A N D A R D B I T MAP MODE ON T O P "

1 8 0 F O R 1 = 1 T O 2 5

1 9 0 P R I N T " S T A N D A R D C H A R A C T E R MOD E ON T H E B O T T O M "

2 0 0 N E X T

2 1 0 S L E E P 3 : RE M D E L A Y

2 2 0 S C N C L R : R E M C L E A R S C R E E N

2 3 0 G R A P H I C C L R : R E M D E - A L L O C A T E B I T MAP

GSHAPE

Retrieve (load) the data from a string variable and display it on a specified coordinate.

GSHAPE string variable [X,Y][,mode]

120 COMMODORE 128 where: string

X,Y mode

Contains shape to be drawn

Top left coordinate (0,0 through 319,199) telling where to draw the shape (scaled— the 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

SA M PLE PR O G RA M :

1 0 R E M D R A W , S A V E A N D G E T T H E CO MMO D O R E S Y M B O L

2 0 C O L O R 0 , 1 : C O L O R 4 , 1 : C O L O R 1 , 7

3 0 G R A P H I C 1 , 1 : R E M S E L E C T BMM

4 0 C I R C L E 1 , 1 6 0 , 1 0 0 , 2 0 , 1 5 : R E M O U T E R C I R C L E

5 0 C I R C L E 1 , 1 6 0 , 1 0 0 , 1 0 , 9 : R E M I N N E R C I R C L E

6 0 B O X 1 , 1 6 5 , 8 5 , 1 8 5 , 1 1 5 : R E M I S O L A T E A R E A T O B E E R A S E D

7 0 S S H A P E A 5 , 1 6 6 , 8 5 , 1 8 5 , 1 1 5 : RE M S A V E T H E A R E A I N T O A $

8 0 G S H A P E A $ , 1 6 6 , 8 5 , 4 : R E M E X C L U S I V E O R T H E A R E A - T H I S ( E R A S E S ) T U R N S O F F P I X E L S

9 0 DRAW 0 , 1 6 5 , 9 4 T O 1 6 5 , 1 0 6 : R E M T U R N O F F ( D R A W I N B K G R N D C O L O R ) P I X E L S I N " C = "

1 0 0 DRAW 1 , 1 6 6 , 9 4 T O 1 6 6 , 9 9 T O 1 8 0 , 9 9 T O 1 8 5 , 9 4 T O 1 6 6 , 9 4 : R E M U P P E R F L A G

1 1 0 DRAW 1 , 1 6 6 , 1 0 6 T O 1 6 6 , 1 0 1 T O 1 8 0 , 1 0 1 T O 1 8 5 , 1 0 6 T O 1 6 6 , 1 0 6 : R E M L O WE R F L A G

1 2 0 P A I N T 1 , 1 6 0 , 1 1 0 : R E M P A I N T " C "

1 3 0 P A I N T 1 , 1 6 8 , 9 8 : RE M U P P E R F L A G

1 4 0 S L E E P 5 : R E M D E L A Y

1 5 0 S S H A P E B $ , 1 3 7 , 8 4 , 1 8 7 , 1 1 6 : R E M S A V E S H A P E I N T O B $

1 6 0 DO

1 7 0 S C N C L R

1 8 0 Y = 1 0

1 9 0 DO

2 0 0 X = 1 0

2 1 0 DO

2 2 0 G S H A P E B $ , X , Y : RE M G E T A N D D I S P L A Y S H A P E

2 3 0 X = X + 5 0 : R E M U P D A T E X

2 4 0 L O O P W H I L E X < 2 8 0

2 5 0 Y = Y + 4 0 : R E M U P D A T E Y

2 6 0 L O O P W H I L E Y < 1 6 0

2 7 0 S L E E P 3

2 8 0 L O O P

LOCATE

Position the bit map pixel cursor (PC) on the screen.

LOCATE X, Y

E X A M P LE :

LOCATE 160,100 Position the PC in the center o f the bit map screen.

Nothing will be seen until something is drawn.

LOCATE + 2 0 ,1 0 0 Move the PC 20 pixels to the right of the last PC position and place it at Y coordinate 100.

LOCATE + 30, + 20 Move the PC 30 pixels to the right and 20 down from the previous PC position.

P A IN T

Fill area with color.

PAINT [color source],X ,Y[,m ode]

COMMODORE 128 GRAPHICS PROGRAMMING 121 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

E X A M P LE :

10 CIRCLE 1, 160,100,65,50

20 PAINT 1, 160,100

10 BOX 1, 10, 10, 20, 20

20 PAINT 1, 15, 15

30 PAINT 1, + 1 0 , + 1 0

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 ).

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

EX A M P LE S :

10 GRAPHIC 1,1 Enter standard bit map, turn scaling

20 SCALE 1:CIRCLE 1,180,100,100,100 on to default size (1023, 1023) and draw a circle.

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 o f the screen into a string variable is: where:

SSHAPE string variable, X I, Y l [,X2,Y2] string variable

X I ,Y l

X2,Y 2

String name to save data in

Corner coordinate (0,0 through 319,199) (scaled)

Corner coordinate opposite (X1,Y1) (default is the PC)

EX A M P LE S:

SSHAPE A$,10,10

SSHAPE B$, 20,30,47,51

SSHAPE D$, + 10, + 10

Saves a rectangular area from the coordinate 10,10 to the location of the pixel cursor, into string vari able 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.

W ID T H

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 o f 2 defines a double width line.

E X A M P LE S:

WIDTH 1 Set Single width for graphic commands

WIDTH 2 Set double width for drawn lines

______

MACHINE

LANGUAGE

ON 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 program mer, skip this section and continue to the 8502 Instruction and Addressing Table at the end o f 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 M ACHINE 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 opera tions. 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 o f 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 C l28 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.

W H Y USE M ACHINE LANGUAGE?

If machine language is more intricate and complicated than BASIC, why use it? Certain applications, such as graphics and telecommunications, require machine language be cause 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 125

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 o f 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 HAT 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 + 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

O PER ATIO N CODE (OP-CODE) FIELD

The first part o f 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.

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 OPER

AND. 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 o f 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 o f 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

M ACHINE-LANG UAG E INSTRUCTIO NS

LDA $100 ; Absolute addressing

LDA $10 ; Zero page absolute addressing

LDA ($FA),Y ; Indirect indexed addressing

LDA $2000,X ; Indexed addressing (absolute)

LDA # $ 1 0 ; Immediate addressing (constants)

M AC HINE LANGUAGE ON TH E COMMODORE 128 127

TH E SIMILARITIES A N D DIFFERENCES BETWEEN A N

ASSEMBLER A N D A M A C H IN E LANGUAGE M O N IT O R

An assembler and machine-language monitor both provide for symbolic op-codes.

Assemblers typically allow symbolic operands as well, whereas the C l 28 machine- language monitor refers to addresses and operands literally ( absolutely ).

An assembler typically has two forms o f 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 o f 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 com put e r’s memory (RAM and ROM) accomplishes all the functions of machine language and your com puter’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 o f these registers.

TH E A C C U M U LA TO R

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).

128 COMMODORE 128

For example, if you want to store a value within one of the RAM locations, you must first load 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.)

A,o

A„

A,3

A,.

A,s

Figure S - l . 8502 Block D iag ram

M AC HINE LANGUAGE ON THE COMMODORE 128 129

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.

T H E X A N D Y IN D E X 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 address— i.e ., the location where a data value is stored or retrieved. The effective address is acted upon by machine-language instruc tions. 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 Load the Accumulator with 0

TAX Transfer the contents of Accumulator (0) to X

START STA $0400,X Store contents of Accumulator in address $0400 + X

INX Increment the X register

CPX #$0B Compare the X register with $0B (11 decimal)

BNE START If X register does not equal 11 branch to START.

BRK Stop

* = In the machine-language monitor the symbolic label START is not allowed, so it would appear as an absolute address reference (eg; $183B).

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 BA

SIC 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 #$0B

B N E ST A R T

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 # $0B 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 machine- language instruction.

T H E STATUS REGISTER

The m icroprocessor’s status register indicates the status of certain conditions within the

8502. The status register is controlled by seven programming states of the microproces sor, 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.

M ACHINE LANGUAGE ON THE COMMODORE 128 131

7 0

[ N 1 V j 1 B j D 1 I | Z~|C] PROCESSOR STATUS REG "P"

(-► CARRY

----- ZERO

1 = TRUE

1 = RESULT ZERO

-----------► IR Q DISABLE 1 = DISABLE

--------------- ► DECIMAL MODE 1 = TRUE

..................— ► BRK COMMAND

-----------------------------► OVERFLOW

--------------------------------* - NEGATIVE

Figure 5 -2 , 8502 Status Register

1 = TRUE

1 = NEG

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 dis abled 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 microproces sor 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

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) o f 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.

TH E PROGRAM C O U N TER

So far all o f 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 o f 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.

TH E 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 $1FF). 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. W hen 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). W hen a value is pulled from the stack, the stack pointer then indicates the new address of the next item on the stack. W hen a subroutine is called or an interrupt occurs, the

M AC HINE LANGUAGE ON THE COMMODORE 128 133 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.

16-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 micropro cessor, 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.

H ere’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

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

HEXADECIMAL

$FF

Figure 5 -3 . Com parison o f N u m b e r Systems

DECIMAL

255

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 23 22 2 1 2

One binary byte = 1 1 1 1 1 1 1 1

The byte in decimal = 128 + 64 + 32 + 16 + 8 + 4 + 2 + 1 = 255

Figure 5 -4 . B in ary /D ec im al Conversion

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 2s 24 23 22 21 2°

One binary byte = 1 1 0 0 1 0 1 0

The byte in decim al = 128 + 64 + 0 + 0 + 8 + 0 + 2 + 0 = 202

Figure 5 -5 . B in ary/D ecim al 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 counter— the register responsible for storing the address of the next instruction to be executed— is 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 o f 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 o f a 16-bit address in decimal:

High Byte 2 15

One binary byte = 1

The byte in decimal

2 14

2 13

2 12

2 11

2 10

= 3 2 7 6 8 + 1 6 3 8 4 + 8192 + 4096 + 2048 + 1024 + 512 + 256 = 65280

Low Byte 27

One binary byte = 1

The byte in decim al

= 128 + 64 + 32 +

16 +

+ 4

+ 2

2°

+ 1

Figure 5 -6 . E xam p le o f 16-Bit Address in D ecim al

M ACHINE LANGUAGE ON TH E COMMODORE 128 135

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? T hat’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 pro grams, you will usually reference memory in hexadecimal notation, explained in the next section.

136 COMMODORE 128

HEXADECIM AL N O T A T IO N

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 C l 28 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 o f 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 instruc tions you give to your computer. The hardware and software merge here, at machine level.

U N DERSTAN D IN G HEXADECIM AL

(H E X ) N O T A T IO 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:

M ACHINE LANGUAGE O N THE COMMODORE 128 137

HEXADECIMAL

DECIMAL

BINARY

0111

1000

1001

1010

1011

1100

1101

1110

1111

0000

0001

0010

0011

0100

0101

0110

Figure 5 -7 . H e x a d e cim a l/D e cim a l/B in ary 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.

138 COMMODORE 128

A C C U M U LA TO R 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 o f stor age. Here are some examples of accumulator addressing instructions:

INSTRUCTION

ASL

LSR

ROR

HEX OPCODE

$0A

$4A

$6A

MEANING

Shift one bit left

Shift one bit right

Rotate one bit right

IM MEDIATE 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 m achine level, the m icroprocessor 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 immedi ate addressing instruction examples:

INSTRUCTION

LDA # $ 0 F

CMP # $ F F

SBC # $ E 0

HEX OPCODE

$A9

$C9

$E9

MEANING

Load the accumulator with 15 ($0F)

Compare the accumulator with 255 ($FF)

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 ACHINE LANGUAGE ON THE COMMODORE 128 139

INSTRUCTION

INC $4FFC

LDX $200C

JSR SFFC3

HEX OPCODE

$EE

$AE

$20

MEANING

Increm ent the contents of address $4FFC by 1

Load the X register with the contents o f address

$200C

Jump to location $FFC3 and save the return address

ZERO-PAGE ADDRESSING

Zero-page addressing requires two bytes o f 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

LDA $FF

ORA $E4

ROR $0F

HEX OPCODE

$A5

$05

$66

MEANING

Load the accumulator with the contents o f zero-page location $FF (255)

OR the accumulator with the contents o f location

$E4

Rotate the contents o f 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

DEX

INY

RTS

HEX OPCODE

$CA

$C8

$60

MEANING

Decrement the contents of the X register

Increm ent the contents o f the Y register

Return from Subroutine

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 TEM P

BEQ START

LDX #$01

STA COUNT

(A)

.01800 A9 01 LDA # $ 0 1

.01802 85 FA STA $FA

.01804 C6 FA DEC $FA

.01806 F0 FC

.01808 A2 01

(B)

.0180A 85 FB

BEQ $1804

LDX # $ 0 1

STA $FB

(C)

*NOTE: The machine language m onitor does not provide for symbolic addresses and labels like TEM P and START.

Figure 5 -8 . R elative 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 Accum ulator in the variable

TEMP. The third instruction, DEC, decrements the contents o f 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).

M ACHINE LANGUAGE ON THE COMMODORE 128 141

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 machine- language 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

BEQ

BNE

BCC

HEX OP-CODE

$F0

$D0

$90

MEANING

Branch on result Equal to 0

Branch on result Not Equal to 0

Branch on Carry Clear

IN D EX ED 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:

142 COMMODORE 128

LDA # $ 0 F

LDX # $ 0 0

LOOP STA $2000,X

INX

BNE 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 + 0 =

$2000). The next instruction (INX) 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 of the 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 address ing (illustrated in the example just shown), (2) indexed zero-page addressing, (3) indexed indirect addressing, and (4) indirect indexed addressing.

IN D E X E D 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) o f 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 calcu lated by adding the contents o f the index register to the low byte o f 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 o f indexed zero-page addressing instructions:

INSTRUCTION

INC operand, X

CM P operand,X

HEX OP CODE

$F6

MEANING

Increm ent the contents o f memory by 1.

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

$D5 Compare the contents o f the accum ulator with m em ory. The memory base address (the oper and) is added to the contents o f the index register

(X)).

M ACHINE LANGUAGE ON TH E COMMODORE 128 143

IN D E X E D ABSOLUTE ADDRESSING

Indexed absolute addressing allows you to access and modify any o f the memory locations in each of the two 64K banks. The effective address is calculated by adding the contents o f 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. There fore, this type of addressing requires three bytes.

Here are some examples of indexed absolute addressing instructions:

INSTRUCTION

AND operand,Y

ASL operand,X

HEX OP CODE

$39

$1E

MEANING

Perform the logical AND operation on the accumulator and the contents o f memory base address plus the contents o f the register (Y).

Shift the contents o f the memory (the memory is the base address (the operand) added to the contents o f the index register (X)) one bit to the left.

TH E 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 o f an address. H ere’s an illustration using absolute indirect addressing:

JMP ($0326)

The above JuM P 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

144 COMMODORE 128 the program counter as the address $F265, the actual address of the next instruction the computer executes then is $F265.

If the parentheses were not present, the assembler interprets the instruction as an absolute addressing instruction. The com puter 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 o f each.

IN D E X E D IN D IR ECT 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.

H ere’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.

IN D IR E C T IN D E X E D ADDRESSING

This mode, also called indirect Y addressing, is post-indexed, which means the adding o f 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 MS zero-page memory address. The contents o f the pointer and the contents o f the Y register are added to arrive at the low byte o f 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 o f data. In order to access different table values, just change the contents of the Y register since the base address is already established. H ere’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 (displace ment). 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 o f the effective address. Indirect indexed is post-indexed with the Y register.

You have just covered all the addressing modes in the Commodore 128. Each calls for different circumstances and you should use the correct mode whenever circum stances dictate it to obtain optimal performance from the microprocessor. For example, use indexed zero-page addressing when you are manipulating zero-page locations in stead 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).

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 M ICR O PR O C ESSO R INSTRUCTION S E T -

ALPH ABETIC SEQUENCE

ADC

AND

ASL

Add Memory to Accumulator with Carry

“ A N D ” M emory with Accumulator

Shift Left One Bit (Memory or Accumulator)

BCC

BCS

BEQ

BIT

BMI

BNE

BPL

BRK

BVC

BVS

Branch

Test Bits in Memory with Accumulator

Branch

Branch on Result not Zero

Branch

Force Break on Carry Clear on Carry Set on Result Zero on Result Minus on Result Plus

Branch on Overflow Clear

Branch on Overflow Set

CLC

CLD

Clear Carry Flag

Clear Decimal Mode

CLI Clear Interrupt Disable Bit

CLV Clear Overflow Flag

CM P Compare M emory and Accumulator

CPX

CPY

Compare M emory and Index X

Compare Memory and Index Y

DEC

DEX

DEY

EOR

INC

INX

INY

Decrement Memory by One

Decrement Index X by One

Decrement Index Y by One

“ Exclusive-O r” M emory with Accumulator

Increm ent Memory by One

Increment Index X by One

Increment Index Y by One

JM P

JSR

LDA

LDX

LDY

LSR

Jump to New Location

Jump to New Location Saving Return Address

Load Accumulator with Memory

Load Index X with Memory

Load Index Y with Memory

Shift Right One Bit (Memory or Accumulator)

NOP No Operation

M ACHINE LANGUAGE ON THE COMMODORE 128 147

TAX

TAY

TSX

TXA

TXS

TYA

SBC

SEC

SED

SEI

STA

STX

STY

8502 M ICRO PR O C ESSO R INSTRUCTION S E T -

A LPH ABETIC SEQUENCE (cont’d)

ORA “ O R ” 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

Subtract M em ory 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

Transfer Accumulator to Index X

Transfer Accumulator to Index Y

Transfer Stack Pointer to Index X

Transfer Index X to Accumulator

Transfer Index X to Stack Pointer

Transfer Index Y to Accumulator

Figure 5 -9 . 8502 O p -C o d e Mnemonics

REGISTER T O MEMORY

INSTR U C TIO N S

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.

LO A D IN G TH E A C C U M U LA TO R

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:

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 accumu lator. 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: TH E 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 o f 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 o f 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.

C O U N TER INSTRUCTIO NS

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 ON THE COMMODORE 128 149 series o f addresses. The counter instruction, INC, increments the contents of a memory address by a value o f 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 o f 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 o f 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. W hen this occurs, increment the high-byte counter. To count up to 260 (decimal), the high- byte value equals 1 and the low byte equals 4. H ere’s an equation to illustrate the point:

(1 * 256) + 4 = 260

H ere’s the machine-language code that does this:

LOOP

LDA #$ 0 0

STA HIGH

STA LOW

INC LOW

BNE LOOP

INC HIGH

LOOP 2 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.

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 neither— they just set status flags. CPX compares the contents o f 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 of a zero-page location, any other address above zero page, or against a constant. H ere’s an example:

ONE

LDX # $ 0 0

LDA # $ 0 0

STA $DF,X

INX

CPX #$0A

BNE 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. H ere’s the same example as above using the contents of a memory address instead of a constant:

LDA #$0A

STA $FB

LDX # $ 0 0

LDA # $ 0 0

STA $DF,X

INX

CPX $FB

BNE ONE

M ACHINE LANGUAGE ON THE COMMODORE 128 151

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.

A R ITH M ETIC 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 EOR

AND ORA

BIT SBC

Here’s what each instruction means:

A D C — Add the contents o f the specified memory address to the contents o f 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.

A N D — Perform the logical AND operation with the contents of the accumulator and the contents o f the specified memory address.

BIT— Compare the bits in the specified memory address with those in the accu mulator. Bits 6 and 7 are transferred to the status register flags. Bit 7 is trans ferred to the negative status flag bit and bit 6 is sent to the overflow status flag bit.

EO R — Perform the exclusive OR operation with the contents of the specified memory address and the contents of the accumulator.

O R A — Perform the logical OR operation with the contents of the specified memory address and the contents o f the accumulator.

SB C — Subtract 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.)

A R ITH M E T IC IN STR U C TIO N S

(A D C , SBC)

The addition and subtraction instructions are easy to understand. Here’s an example:

CLC

LDA #$0A

STA $FB

ADC #$ 0 4

SEC

SBC # $ 0 6

ADC $FB

STA $FD

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 accumu lator 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 o f 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.

LO G ICAL IN STR U C TIO N S

(A N D , 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. H ere’s an illustration of this concept:

M emory address = 10001010

Accumulator = 11110010

Result o f 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. H ere’s an illustration.

Contents o f 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:

M AC HINE LANGUAGE O N THE COMMODORE 128 153

If either o f the operands equals 1, the resulting Boolean value is 1, except if both operands are 1, then the result equals 0.

H ere’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 o f the flag. For example, the BIT instruction performs the following:

7 0

________

Contents of Memory Address = 10101001

Contents o f Accumulator

N V

= 11001101 h

> 1 0

B D I Z C

_______________

Result of BIT instruction

(Not stored in accumulator)

= 10001001 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 o f 2-bit pattern operands that result in 0 when

ANDed:

154 COMMODORE 128

7 0

________

Contents of Memory Address = 01111010

Contents of Accumulator

N V

= 10000100 —> 0 1

B D I Z C

_______________

Result of BIT instruction = 00001000 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 instruc tions 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 particu lar 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 o f 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

H ere’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.

M ACHINE LANGUAGE ON THE COMMODORE 128 155

B C C — (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.

B EQ — (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.

BN E— (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.

BV C— (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 o f a flag in the status register.

Here are some branching examples.

R E A D Y .

M O N I T O R

P C S R A C X R Y R S P

; F B O O O 0 0 0 0 0 0 0 0 F 8

0 1 8 2 8

0 1 8 2 A

0 1 8 2 C

0 1 8 2 E

0 1 8 3 0

E 6 F A

A 5 F A

DO 0 2

E 6 F B

C 8

I N C $ F A

L D A $ F A

B N E $ 1 8 3 0

I N C $ F B

I N Y

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 o f 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.

R E A D Y .

M O N I T O R

;

P C S R A C X R Y R S P

F B O O O 0 0 0 0 0 0 0 0 F 8

0 1 8 5 8 8 E 0 0 D 6

0 1 8 5 B 2 C 0 0 D 6

0 1 8 5 E 1 0 F B

0 1 8 6 0 8 D 0 1 D 6

S T X $ D 6 0 0

B I T $ D 6 0 0

B P L $ 1 8 5 B

S T A $ D 6 0 1

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

156 COMMODORE 128 with an 8563 register number, into the 8563 address register. The BIT instruction places bit 7 o f 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 TRANSFER INSTRUCTIONS

This instruction is useful since it only requires one byte o f 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:

T A X — Transfer contents of accumulator to X index register

T A Y — Transfer contents of accumulator to Y index register

T S X — Transfer the contents of the stack pointer to X index register

T X A — Transfer the contents of X index register to the accumulator

T Y A — Transfer the contents of the Y index register to the accumulator

T X S — Transfer 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:

A SL— Shift the whole byte one bit to the left

LSR— Shift the whole byte one bit to the right

RO L— Rotate the whole byte one bit to the left

R O R — Rotate the whole byte one bit to the right

SH IFT IN S TR U C TIO N S

The shift instructions are useful when evaluating the value of a single bit at a time in a series o f 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

M ACHINE LANGUAGE ON THE COMMODORE 128 157 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:

R E A D Y .

M O N I T O R

P C S R A C X R Y R S P

; F B 0 0 0 0 0 0 0 0 0 0 0 F 8

0 1 8 0 0

0 1 8 0 3

0 1 8 0 5

0 1 8 0 7

0 1 8 0 8

0 1 8 0 A

0 1 8 0 B

0 1 8 0 C

0 1 8 0 E

0 1 8 0 F

0 1 8 1 0

0 1 8 1 2

0 1 8 1 3

0 1 8 1 4

0 1 8 1 6

0 1 8 1 7

0 1 8 1 8

0 1 8 1 A

0 1 8 1 C

AD 0 0 DC L D A $ D C 0 0

A 0 0 0 L D Y # $ 0 0

A 2 0 0 LD X # $ 0 0

4 A

B 0 0 1

L S R

B C S $ 1 8 0 B

8 8 D E Y

4 A

B 0 0 1

L S R

B C S $ 1 8 0 F

C 8 I N Y

4 A L S R

B 0 0 1 B C S $ 1 8 1 3

C A D E X

4 A

B 0 0 1

L S R

B C S $ 1 8 1 7

E 8 I N X

4 A

8 6

8 4

F A

F B

L S R

S T X $ F A

S T Y $ F B

6 0 R T S

ROTATE IN S TR U C TIO N S

The rotate instructions operate a little differently. Instead o f 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 -1 0 . C oncept o f R O R (R o tate Right) Instruction

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

C L C

C L D

C LI

C L V

Set the Carry Flag

Set Decimal Mode

Set the Interrupt Disable Bit

Clear the Carry Flag

Clear Decimal Mode

Clear the Interrupt Disable Bit

Clear the Overflow Flag

Each o f 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 o f a signed mathematical operation overflowing into the sign bit.

Figure 5-11 shows the 8502 status register:

7 o

| N 1 V 1 j B | D 1 I 1 2 | C] PROCESSOR STATUS REG "P"

L».CAR flY 1 x TRUE

------ ►ZERO 1 = RESULT ZERO

----------► IRQ DISABLE 1 * DISABLE

-------------- ► DECIMAL MODE 1 = TRUE

------------------ ► BRK COMMAND

--------------------------- ►OVERFLOW

-------------------------------► NEGATIVE

1 * TRUE

1 * NEG

Figure 5 -1 1 . 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 subtrac tion. 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

M AC HINE LANGUAGE O N THE COMMODORE 128 159 adding two numbers in the accumulator. To perform mathematical operations in hexa decimal or binary numbers, clear the decimal mode flag so that your calculations are not mistakenly performed in binary coded decimal. W henever the result of a signed mathe matical 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 o f the interrupt initialization routine, issue the CLI (Clear Interrupt Disable bit) instruction to enable (allow) interrupts to occur.

JUMP A N D RETURN INSTRUCTIO NS

JUMP IN STR U C TIO N S

The 8502 processor makes use of two jum p instructions:

JMP — Jump to new location

JSR — Jump 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 jum ps 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) jum ps 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 jum p 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:

. 0 1 8 0 4

. 0 1 8 0 7

2 0 5 8 1 8 J S R S 1 8 5 8

A 2 0 C L D X # $ 0 C 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:

160 COMMODORE 128

0 1 8 5 8

0 1 8 5 B

0 1 8 5 E

0 1 8 6 0

0 1 8 6 3

8 E 0 0 D 6 S T X $ D 6 0 0

2 C 0 0 D 6 B I T $ D 6 0 0

1 0 F B B P L $ 1 8 5 B

8 D 0 1 D 6 S T A $ D 6 0 1

6 0 R T S the processor resumes with the main program instruction (LDX #$0C ) in location $1807.

RETURN IN STR U C TIO N S

The 8502 instruction set has two return instructions:

RTI— Return from Interrupt

RTS— Return from Subroutine

The first instruction returns from your interrupt service routine after the interrupt disable bit is cleared (CLI) and the interrupt occurs. The RTI is the last instruction in the interrupt service routine. The interrupt service routine is the series o f 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 INSTRUCTIO NS

Four stack instructions are included in the 8502 instruction set to manipulate the values on the stack. These instructions are as follows:

P H A — Push accumulator on the stack

P H P — Push processor status on the stack

PLA — Pull accumulator from the stack

PL P— Pull 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 manipula tion of the stack values prior to returning from the interrupt.

TH E NOP IN STR U C TIO N

The NOP instruction stands for no operation. It is often used to add space between program segments for readability. This instruction is not executable.

M ACHINE LANGUAGE ON THE COMMODORE 128 161

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. OP-CODE

2. Brief definition

3. Operation notation

4. Status flags

5. Flags affected

6. Addressing Modes

7. Assembly language form

8. OP-CODE (in hex)

9. Number of bytes

10. Number of instruction cycles

X,Y

-V-

—

< -

PCH

PCL

OPER

The following notation applies to this summary:

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

162 COMMODORE 128

A D C Add memory to accumulator w ith carry

Operation: A + M + C - ^ A , C N E C I E y y y - -

V y

A D C

ADDRESSING

MODE

Immediate

Zero Page

Zero Page, X

Absolute

Absolute, X

Absolute, Y

(Indirect, X)

(Indirect), Y

ASSEMBLY

LANGUAGE FORM

ADC # Oper

ADC Oper

ADC

Oper, X

Oper

Oper, X

Oper, Y

(Oper, X)

(Oper), Y

* Add 1 if page boundary is crossed.

OP NO.

NO.

CODE BYTES CYCLES

A N D “ A N D ” m e m o ry w ith a c c u m u la to r

Logical AND to the accumulator

Operation: A A M —> A N E C y y -

ADDRESSING

MODE

Im mediate

Zero Page

Zero Page, X

Absolute

Absolute, X

Absolute, Y

(Indirect, X)

(Indirect), Y

ASSEMBLY

LANGUAGE FORM

AND # Oper

AND Oper

AND

Oper, X

Oper

Oper, X

Oper, Y

AND

(Oper, X)

(Oper), Y

* Add 1 if page boundary is crossed.

OP NO.

NO.

CODE BYTES CYCLES

A N D

MACHINE LANGUAGE ON THE COMMODORE 128 163

A S L ASL S h ift L e ft O n e B it (M e m o r y o r A c c u m u la to r)

Operation: C [7 |6 |5 |4 |3 |2 lH o 1 < - 0 N Z C I

/ / / - -

D V

ADDRESSING

MODE

A ccumulator

Zero Page

Zero Page, X

Absolute

Absolute, X

ASSEMBLY

LANGUAGE FORM

ASL A

ASL Oper

ASL Oper, X

ASL Oper

ASL Oper, X

CODE

NO.

BYTES

NO.

CYCLES

A S L

B C C

Operation: Branch on C = 0

BCC B ran ch on C a rry C le a r

N Z C

ADDRESSING

MODE

ASSEMBLY

LANGUAGE FORM

Relative BCC Oper

* Add 1 if branch occurs to same page.

* A dd 2 if branch occurs to different page.

CODE

NO.

BYTES

NO.

CYCLES

90 2 2*

B C C

BCS

Operation: Branch on C = 1

BCS B ranch on c a rry set

N Z C

ADDRESSING

MODE

ASSEMBLY

LANGUAGE FORM

Relative BCS Oper

* Add 1 if branch occurs to same page.

* A dd 2 if branch occurs to next page.

CODE

NO.

BYTES

NO.

CYCLES

BO 2 2 *

BCS

164 COMMODORE 128

B E Q

Operation: Branch on Z = 1

BEQ B ranch on result z e ro

N Z C I D V

B E Q

ADDRESSING

MODE

Relative

ASSEMBLY

LANGUAGE FORM

BEQ Oper

* Add 1 if branch occurs to same page.

* Add 2 if branch occurs to next page.

CODE

NO.

BYTES

NO.

CYCLES

2 2*

B IT B IT Test bits in m e m o ry w ith a c c u m u la to r

Operation: A A M , M 7 —> N , M6 —» V

Bit 6 and 7 are transferred to the status register.

If the result o f AAM is zero then Z = 1, otherwise

Z = 0

7 / -

C I D V

- M, 6

B IT

ADDRESSING

MODE

Zero Page

Absolute

ASSEMBLY

LANGUAGE FORM

BIT Oper

CODE

NO.

BYTES

NO.

CYCLES

B M I

Operation: Branch on N = 1

B M I B ran ch on result minus

N z c

I D V

BM I

ADDRESSING

MODE

Relative

ASSEMBLY

LANGUAGE FORM

BMI Oper

* Add 1 if branch occurs to same page.

* Add 2 if branch occurs to different page.

OP NO.

NO.

CODE BYTES CYCLES

30 2 2*

B N E

Operation: Branch on Z = 0

BNE B ranch on result n o t z e ro

N Z C I D V

BN E

ADDRESSING

MODE

Relative

ASSEMBLY

LANGUAGE FORM

BNE Oper

* Add 1 if branch occurs to same page.

* Add 2 if branch occurs to different page.

CODE

NO.

BYTES

NO.

CYCLES

DO 2 2*

M ACHINE LANGUAGE ON THE COMMODORE 128 165

B PL

Operation: Branch on N = 0

BPL B ranch on result plus

N Z C I D V

BPL

ADDRESSING

MODE

Relative

ASSEMBLY

LANGUAGE FORM

BPL Oper

* Add 1 if branch occurs to same page.

* Add 2 if branch occurs to different page.

OP NO.

NO.

CODE BYTES CYCLES

10 2 2*

BRK BRK F orce B re a k

Operation: Forced Interrupt PC + 2 J, P | N Z C I D V

BRK

ADDRESSING

MODE

Implied

ASSEMBLY

LANGUAGE FORM

BRK

OP NO.

NO.

CODE BYTES CYCLES

00 1 7

1. A BRK com m and cannot be masked by setting I.

B V C

Operation: Branch on V = 0

B VC B ranch on o v e rflo w c le a r

N Z C I D V

B V C

ADDRESSING

MODE

Relative

ASSEMBLY

LANGUAGE FORM

BVC Oper

* Add 1 if branch occurs to same page.

* Add 2 if branch occurs to different page.

OP NO.

NO.

CODE BYTES CYCLES

50 2 2*

B V S

Operation: Branch on V = 1

BVS B ranch on o v e rflo w set

N Z C I D V

BVS

ADDRESSING

MODE

Relative

ASSEMBLY

LANGUAGE FORM

BVS Oper

* Add 1 if branch occurs to same page.

* Add 2 if branch occurs to different page.

OP NO.

NO.

CODE BYTES CYCLES

70 2 2*

166 COMMODORE 128

C L C

Operation: O ^ C

ADDRESSING

MODE

Implied

CLC C le a r c a rry fla g

ASSEMBLY

LANGUAGE FORM

CLC

N Z C I D V

OP NO.

NO.

CODE BYTES CYCLES

18 1 2

C L C

C L D

Operation: 0 D

ADDRESSING

MODE

Implied

CLD C le a r d e c im a l m ode

ASSEMBLY

LANGUAGE FORM

CLD

N Z C I D V

- -

OP NO.

NO.

CODE BYTES CYCLES

D8 1 2

C L D

C L I

Operation: 0 - » I

ADDRESSING

MODE

Implied

ASSEMBLY

LANGUAGE FORM

CLI

C L I C le a r in te rr u p t disable b it

N Z C I D V

OP NO.

NO.

CODE BYTES CYCLES

58 1 2

CLI

C L V

Operation: 0 -> V

ADDRESSING

MODE

Implied

CLV C le a r o v e rflo w fla g

ASSEMBLY

LANGUAGE FORM

CLV

N Z C I D V

OP NO.

NO.

CODE BYTES CYCLES

B8 1 2

C L V

MACHINE LANGUAGE ON THE COMMODORE 128 167

C M P

Operation: A - M

C M P C o m p a re m e m o ry and a c c u m u la to r

N Z C I E V

C M P

ADDRESSING

MODE

Immediate

Zero Page

Zero Page, X

Absolute

Absolute, X

Absolute, Y

(Indirect, X)

(Indirect), Y

ASSEMBLY

LANGUAGE FORM

CMP # O p er

CMP Oper

CMP Oper, X

CMP

Oper

Oper, X

CMP

Oper, Y

(Oper, X)

(Oper), Y

Add 1 if page boundary is crossed.

CODE

NO.

BYTES

NO.

CYCLES

C l

C P X

Operation: X - M

ADDRESSING

MODE

Immediate

Zero Page

Absolute

C P X C o m p a re M e m o r y a nd In d e x X

N Z C

I E V

C P X

ASSEMBLY

LANGUAGE FORM

CPX # O p er

CPX

Oper

CODE

NO.

BYTES

NO.

CYCLES

C P Y

Operation: Y - M

ADDRESSING

MODE

Immediate

Zero Page

Absolute

C PY C o m p a re m e m o ry a nd ind ex Y

N Z

J J

C I E V

ASSEMBLY

LANGUAGE FORM

CPY # O p er

CPY

Oper

OP NO.

NO.

CODE BYTES CYCLES

C P Y

168 COMMODORE 128

D E C

Operation: M - 1 —> M

D E C D e c re m e n t m e m o ry by one

N Z C I

ADDRESSING

MODE

Zero Page

Zero Page, X

Absolute

Absolute, X

ASSEMBLY

LANGUAGE FORM

DEC Oper

DEC Oper, X

DEC Oper

DEC O per, X

OP NO. NO.

CODE; BYTES CYCLES

D E X

Operation: X - 1 —» X

ADDRESSING

MODE

Implied

ASSEMBLY

LANGUAGE FORM

DEX

D E X D e c re m e n t ind ex X by one

N Z C

/ / -

OP NO. NO.

CODE BYTES CYCLES

1 2

D E Y

Operation: Y - 1 —» Y

ADDRESSING

MODE

Implied

D E Y D e c re m e n t ind ex Y by one

N Z C y y -

ASSEMBLY

LANGUAGE FORM

DEY

OP NO. NO.

CODE BYTES CYCLES

8 8 1 2

E O R E O R “ Exclusive — O r ” m e m o ry w ith a c c u m u la to r

Operation : A - * M -V" A N Z C y y -

ADDRESSING

MODE

Immediate

Zero Page

Zero Page, X

Absolute

Absolute, X

Absolute, Y

(Indirect, X)

(Indirect), Y

ASSEMBLY

LANGUAGE FORM

EOR #O p er

EOR Oper

EOR Oper, X

EOR

Oper

Oper, X

Oper, Y

(Oper, X)

(O per), Y

* A d d 1 i f p ag e b o u n d ary is c ro ssed .

OP NO. NO.

CODE BYTES CYCLES

D E C

D E X

D E Y

EO R

IN C

Operation: M + 1 —> M

ADDRESSING

MODE

Zero Page

Zero Page, X

Absolute

Absolute, X

M ACHINE LANGUAGE ON THE COMMODORE 128 169

IN C In c re m e n t m e m o ry by one

ASSEMBLY

LANGUAGE FORM

INC Oper

INC O per, X

INC Oper

INC Oper, X

Z y -

OP NO.

NO.

CODE BYTES CYCLES

IN C

I N X

Operation: X + 1 —> X

ADDRESSING

MODE

Implied

I N X In c re m e n t In d e x X by one

N y

Z C y -

ASSEMBLY

LANGUAGE FORM

INX

OP NO.

NO.

CODE BYTES CYCLES

8 1 2

I N X

IN Y

Operation: Y + 1 —» Y

ADDRESSING

MODE

Implied

IN Y In c re m e n t In d e x Y by one

N Z C y y -

ASSEMBLY

LANGUAGE FORM

INY

OP NO.

NO.

CODE BYTES CYCLES

8 1 2

IN Y

JMP JMP

Operation: (PC + 1) —» PCL

(PC + 2) PCH

J M P Jum p to n ew lo c a tio n

N Z C

ADDRESSING

MODE

Absolute

Indirect

ASSEMBLY

LANGUAGE FORM

JM P Oper

JM P (Oper)

OP NO.

NO.

CODE BYTES CYCLES

C 3

170 COMMODORE 128

JSR JSR Jump to new location saving return address

Operation: PC + 2 j , (PC + 1) -> PCL

(PC + 2) -> PCH

_ _

ADDRESSING

MODE

Absolute

ASSEMBLY

LANGUAGE FORM

JSR Oper

OP NO.

NO.

CODE BYTES CYCLES

2 0

JSR

L D A

Operation: M ^ A

LDA Load accum ulator w ith memory

N Z C I D V

L D A

ADDRESSING

MODE

Immediate

Zero Page

Zero Page, X

Absolute

A bsolute, X

Absolute, Y

(Indirect, X)

(Indirect), Y

ASSEMBLY

LANGUAGE FORM

LDA #O p er

LDA Oper

LDA

Oper, X

Oper

Oper, X

LDA

Oper, Y

(Oper, X)

(Oper), Y

* Add 1 if page boundary is crossed.

CODE

NO.

BYTES

NO.

CYCLES

L D X

Operation: M - ^ X

L D X Load index X with memory

ADDRESSING

MODE

Immediate

Zero Page

Zero Page, Y

Absolute

Absolute, Y

ASSEMBLY

LANGUAGE FORM

LDX #O p er

LDX Oper

LDX

Oper, Y

Oper

LDX Oper, Y

* A d d 1 w h en p ag e b o u n d ary is cro ssed .

N Z C I D V

CODE

NO.

BYTES

NO.

CYCLES

L D X

MACHINE LANGUAGE O N THE COMMODORE 128 171

L D Y

Operation: M —> Y

L D Y L oad in d e x Y w ith m e m o ry

N Z C I

J J ~ ~ ~

ADDRESSING

MODE

Immediate

Zero Page

Zero Page, X

Absolute

Absolute, X

ASSEMBLY

LANGUAGE FORM

LDY # O p er

LDY Oper

LDY

O per, X

Oper

O per, X

* Add 1 when page boundary is crossed.

CODE

NO.

BYTES

NO.

CYCLES

L D Y

LSR LSR S h ift rig h t one b it (m e m o ry o r a c c u m u la to r)

Operation: 0 -> |716]5[4 13121 llo l - * C N Z C I D o y y - -

ADDRESSING

MODE

Accumulator

Zero Page

Zero Page, X

Absolute

Absolute, X

ASSEMBLY

LANGUAGE FORM

LSR A

LSR Oper

LSR Oper, X

LSR Oper

LSR O per, X

CODE

NO.

BYTES

NO.

CYCLES

LSR

N O P

Operation: No Operation (2 cycles)

N O P N o o p e ra tio n

N Z C

ADDRESSING

MODE

Implied

ASSEMBLY

LANGUAGE FORM

NOP

OP NO. NO.

CODE BYTES CYCLES

EA 1 2

N O P

172 COMMODORE 128

O R A

Operation: A V M - » A

O RA " O R ” m e m o ry w ith a c c u m u la to r

N Z C y -

ADDRESSING

MODE

Immediate

Zero Page

Zero Page, X

Absolute

Absolute, X

Absolute, Y

(Indirect, X)

(Indirect), Y

* Add 1 on page crossing

ASSEMBLY

LANGUAGE FORM

ORA #O p er

ORA Oper

ORA

Oper, X

Oper

Oper, X

ORA

Oper, Y

(Oper, X)

(Oper), Y

OP NO.

NO.

CODE: BYTES CYCLES

0 1

1 1

P H A

Operation : A |

P H A Push a c c u m u la to r on stack

N Z C

ADDRESSING

MODE

Implied

ASSEMBLY

LANGUAGE FORM

PHA

OP NO. NO.

CODE BYTES CYCLES

48 1 3

P H P

Operation: P J,

ADDRESSING

MODE

Implied

ASSEMBLY

LANGUAGE FORM

PHP

P H P Push processor status on stack

N Z C

CODE

NO. NO.

BYTES CYCLES

08 1 3

P L A

Operation: A f

ADDRESSING

MODE

Implied

PLA P u ll a c c u m u la to r fro m stack

N Z C y y -

ASSEMBLY

LANGUAGE FORM

PLA

CODE

NO. NO.

BYTES CYCLES

68 1 4

O R A

P H A

P H P

P LA

M ACHINE LANGUAGE ON TH E COMMODORE 128 173

PLP PLP

Operation: P f

ADDRESSING

MODE

Implied

PLP P u ll processor status fro m stack

N Z C I D

From Stack

ASSEMBLY

LANGUAGE FORM

PLP

OP NO. NO.

CODE BYTES CYCLES

28 1 4

R O L ROL R o ta te one b it le ft (m e m o ry o r a c c u m u la to r)

M or A

Operation: ----- | 7 |6 | 5 |4 |3 |2 | l |0 |

<-|c h

— N Z C I D y y y - -

ADDRESSING

MODE

ASSEMBLY

LANGUAGE FORM

Accum ulator ROL A

Zero Page ROL Oper

Zero Page, X ROL Oper, X

Absolute

Absolute, X

ROL Oper

ROL Oper, X

OP NO. NO.

CODE BYTES CYCLES

R O L

R O R

Operation: |C k |71

15 14131211 |o| 0

R O R R o ta te one b it rig h t (m e m o ry o r a c c u m u la to r)

N Z C I D y y y - -

ADDRESSING

MODE

ASSEMBLY

LANGUAGE FORM

OP NO. NO.

CODE BYTES CYCLES

Accumulator

Zero Page

Zero Page, X

Absolute

Absolute, X

ROR A

ROR Oper

ROR O per, X

ROR Oper

ROR O per,X

6 6

RO R

174 COMMODORE 128

R T I

Operation: P f P C f

ADDRESSING

MODE

Implied

ASSEMBLY

LANGUAGE FORM

RTI

R T I R e tu rn fro m in te rr u p t

N Z C I D V

From Stack

OP NO.

NO.

CODE BYTES CYCLES

1 6

RTI

RTS RTS R e tu rn fro m s u b ro utine

Operation: PC f , PC + 1 —» PC N Z C I D V

RTS

ADDRESSING

MODE

Implied

ASSEMBLY

LANGUAGE FORM

RTS

OP NO.

NO.

CODE BYTES CYCLES

1 6

SBC SBC S u b tra c t m e m o ry fro m a c c u m u la to r w ith b o rro w

Operation: A - M - C —> A

Note: C = Borrow

ADDRESSING

MODE

Immediate

Zero Page

Zero Page, X

Absolute

Absolute, X

Absolute, Y

(Indirect, X)

(Indirect), Y

ASSEMBLY

LANGUAGE FORM

SBC #O p er

SBC Oper

SBC Oper, X

SBC

Oper

SBC

Oper, X

Oper, Y

(Oper, X)

SBC (Oper), Y

* A d d 1 w h en p ag e b o u n d ary is c ro ssed .

CODE

NO.

BYTES

NO.

CYCLES

E l

SBC

M AC HINE LANGUAGE O N TH E COMMODORE 128 175

SEC

Operation: 1 —» C

ADDRESSING

MODE

Implied

SEC S e t c a rry fla g

ASSEMBLY

LANGUAGE FORM

SEC

N Z C I E

_ 1 _

OP NO.

NO.

CODE BYTES CYCLES

1 2

SEC

SED

Operation: 1 —* D

SED S et d e c im a l m ode

N X C

ADDRESSING

MODE

Implied

ASSEMBLY

LANGUAGE FORM

SED

OP NO.

NO.

CODE BYTES CYCLES

8 1 2

SED

SEI

Operation: 1 —» I

ADDRESSING

MODE

Implied

ASSEMBLY

LANGUAGE FORM

SEI

SEI S e t in te rr u p t disable status

N Z C

OP NO.

NO.

CODE BYTES CYCLES

1 2

S T A

Operation: A —» M

ADDRESSING

MODE

Zero Page

Zero Page, X

Absolute

Absolute, X

Absolute, Y

(Indirect, X)

(Indirect), Y

STA S to re a c c u m u la to r in m e m o ry

N Z C

ASSEMBLY

LANGUAGE FORM

STA Oper

STA Oper, X

STA Oper

STA Oper, X

STA Oper, Y

STA (Oper, X)

STA (Oper), Y

OP NO.

NO.

CODE BYTES CYCLES

SEI

S T A

176 COMMODORE 128

S T X

Operation: X —> M

ADDRESSING

MODE

Zero Page

Zero Page, Y

Absolute

S TX Store in d e x X in m e m o ry

N Z C I

ASSEMBLY

LANGUAGE FORM

STX Oper

STX Oper, Y

STX Oper

CODE

NO.

BYTES

NO.

CYCLES

8 6

S T X

S T Y

Operation: Y —> M

ADDRESSING

MODE

Zero Page

Zero Page, X

Absolute

STY Store in d e x Y in m e m o ry

N Z C

ASSEMBLY

LANGUAGE FORM

STY Oper

STY Oper, X

STY Oper

OP NO.

NO.

CODE BYTES CYCLES

S T Y

T A X

Operation: A -> X

T A X T ra n s fe r a c c u m u la to r to in d e x X

N Z C I

ADDRESSING

MODE

Implied

ASSEMBLY

LANGUAGE FORM

TAX

OP NO.

NO.

CODE BYTES CYCLES

1 2

T A X

T A Y

Operation: A

ADDRESSING

MODE

Implied

TAY T ra n s fe r a c c u m u la to r to in d e x Y

ASSEMBLY

LANGUAGE FORM

TAY

OP NO.

NO.

CODE BYTES CYCLES

8 1 2

E V

T A Y

M AC HINE LANGUAGE O N THE COMMODORE 128 177

T S X

Operation: S X

TSX Transfer stack p ointer to index X

ADDRESSING

MODE

Implied

ASSEMBLY

LANGUAGE FORM

TSX

OP NO.

NO.

CODE BYTES CYCLES

1 2 r V

T S X

T X A

Operation: X

ADDRESSING

MODE

Implied

TXA Transfer index X to accum ulator

N y

Z C I E V

T X A

ASSEMBLY

LANGUAGE FORM

TXA

OP NO.

NO.

CODE BYTES CYCLES

1 2

T X S

Operation: X —» S

ADDRESSING

MODE

Implied

TXS Transfer index X to stack pointer

N Z C I

ASSEMBLY

LANGUAGE FORM

TXS

OP NO.

NO.

CODE BYTES CYCLES

1 2

T X S

T Y A

Operation: Y

ADDRESSING

MODE

Implied

TYA Transfer index Y to accumulator

N Z C I

J J - -

D V

T Y A

ASSEMBLY

LANGUAGE FORM

TYA

OP NO.

NO.

CODE BYTES CYCLES

1 2

178 COMMODORE 128

INSTRUCTION ADDRESSING MODES AND

RELATED EXECUTION TIMES (in clock cycles)

INY

JMP

JSR

LDA

LDX

LDY

LSR

NOP

ORA

PHA

PHP

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 os

3 4

2 3 4

3 4

, x >*

< a * Cn

O O os c* w w

N N

4* 4*

3 .

4* 4*

, .

4* 4*

* 4*

< w

Q > a h

0, -

5 W a os

H H

U U

W a

2 ss g z w '—-

3 z

W o

Efl ea

j u

5* .

M AC HINE LANGUAGE ON THE COMMODORE 128 179

SEI

STA

STX

STY

TAX

TAY

TSX

TXA

TXS

TYA

PLA

PLP

ROL

ROR

RTI

RTS

SBC

SEC

SED s

U u

& o

< w

Q w

X > w w" W o

< e>

< a

< a .

CL.

a .

CS2 o c* OS w w

N N

O w

S I

X >w

H w

W w

H o

O o

J <

C/5 ca

< c/3

SQ c w

C/3

C a .

-J

4 .

. 5

7 .

. 5

. .

2 3 4 .

4* 4*

. .

. 3 4 .

4 5

. 3 . 4 4

. 3 4 .

. ,

, ,

. .

, #

Z w

U w fie;

> z p w u w

S3 os -J o o C/j z CO

5* .

6 6

* A dd 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 o f 1 MHz, which is equivalent to 1,000,000 cycles per second.

________

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 C l 28 offers three methods of inputting instructions so that they may be operated on by the microprocessor. You can enter machine language instructions by:

1. Using the built-in machine language monitor (available in C l 28 mode only).

2. P O K E ing the translated decimal opcode values into memory with a BASIC program (C l28 and C64 modes).

3. 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 o f 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.

H O W T O ENTER M ACHINE LANGUAGE PROGRAMS IN T O THE COMMODORE 128 183

ENTERING M ACHINE LANGUAGE

INSTRUCTIONS IN THE M O N ITO R

Begin entering machine language instructions by entering the monitor from BASIC with the following command:

MONITOR R E T U R N

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 o f the register names are as follows:

PC— Program Counter

SR— Status Register

AC— Accumulator

XR— X Index Register

YR— Y Index Register

SP— Stack Pointer

Marks the address of the current machine language instruction

Flags that alert the microprocessor of certain conditions

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

M ake sure to leave at least one space between each of the fields. H ere’s what each part of the instruction means:

< A ssem ble> <A ddress in memory where opcode is stored> < O p co d e> < O p eran d >

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) speci fies the configuration o f 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

184 COMMODORE 128 appears in the first instruction you entered. You must have an RTS instruction at the end o f 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 DISASSEM

BLE command as follows:

D 04000 04010 R E T 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 exist ing opcode and operand on the screen, erase any unwanted characters and press

R E T U R N . 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 machine- language routines, rather than typing the ASSEMBLE command and the address each time you enter an instruction.

EXECUTING (R UN N IN G )

YO U R 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 com mand as follows:

G FI 800

J F I 800

(JMP)

(JSR)

The G stands for G O , 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 Subrou tine, 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 M ACHINE LANGUAGE PROGRAMS IN T O THE COMMODORE 128 185 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 F I 800) example above.

The BANK 15 command and the leading F in the 5-digit hexadecimal number F I 800 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 o f 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. H ere’s the main BASIC program and the machine language screen-clear subroutine as it appears in the machine language monitor.

1 0 F O R 1 = 1 T O 2 5

2 0 P R I N T " F I L L T H E S C R E E N W I T H C H A R A C T E R S "

3 0 N E X T

4 0 P R I N T : P R I N T

5 0 P R I N T " N O W C A L L T H E M A C H I N E L A N G U A G E "

6 0 P R I N T " R O U T I N E T O C L E A R T H E S C R E E N "

7 0 S L E E P 5

8 0 S Y S D E C ( " 1 8 0 0 " )

9 0 P R I N T " T H E S C R E E N I S NOW C L E A R E D "

R E A D Y .

M O N I T O R

P C S R A C X R Y R S P

; F B O O O 0 0 0 0 0 0 0 0 F 8

0 1 8 0 0

0 1 8 0 2

0 1 8 0 4

0 1 8 0 7

0 1 8 0 A

0 1 8 0 D

0 1 8 1 0

0 1 8 1 1

0 1 8 1 3

A 2 0 0

A 9 2 0

L D X # $ 0 0

L D A # $ 2 0

9 D 0 0 0 4 S T A $ 0 4 0 0 , X

9 D 0 0 0 5 S T A $ 0 5 0 0 , X

9 D 0 0 0 6 S T A $ 0 6 0 0 , X

9 D E 7 0 6 S T A $ 0 6 E 7 , X

E 8 I N X

DO F I

6 0

B N E

R T S

$ 1 8 0 4

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.

186 COMMODORE 128

M ACHINE LANGUAGE

M O N ITO R 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.

KEYW ORD FUNCTION FORM AT

ASSEM BLE Assembles a line of 8502 code

COM PARE

Compares two sections o f mem ory and reports differences

DISASSEM BLE Disassembles a line or lines of 8502

FILL code

Fills a range of memory with spec ified byte

Starts execution at the specified

HUNT address

Hunts through memory within a specified range for all occurrences of a set o f bytes

GOSUB

LOAD

M EM ORY

REGISTERS

SAVE

TRANSFER

VERIFY

EXIT

(period)

(greater than)

(semicolon)

A < sta rt ad d ress> < o p c o d e >

[operand]

<start address> < en d address>

< n ew start address>

D [<start address> < en d address> ]

<start address> < en d address>

[address]

Jumps to the subroutine

Loads a file from tape or disk

Displays the hexadecimal values of memory locations

Displays the 8502 registers

Saves to tape or disk

H <start address> < en d address>

 [ . . .]

H <start address> < en d address>

< a scii strin g>

J [address]

L “ < file n a m e > ” [,< d ev ice # >

[,< lo a d address>]]

M [< start address>

[< en d address>]]

S “ < file n a in e > ” ,< d e v ic e # > ,

< sta rt ad d ress> c la s t address

Transfers code from one section of memory to another

T <start address> < en d address>

< n ew start address>

Compares memory with tape or disk

V “ < file n a n ie > ” [,< d ev ice # > [ , c lo a d address>]]

Exits Commodore 128 MONITOR X

Assembles a line of 8502 code

Modifies memory

Modifies 8502 register displays

> [address]

H O W T O ENTER M ACHINE LANGUAGE PROGRAMS IN T O THE COMMODORE 128 187

KEYW ORD

(at sign)

FUNCTION

Displays disk status, sends disk @ com m and, displays directory disk status disk command disk catalog

FORM AT

© [d evice # ]

© [d evice # ],< c o m m a n d strin g> ]

@ [device # ],$ [ [< d r iv e > :< file sp ec> ]]

NOTES < > enclose required parameters

[] enclose optional parameters

Figure 6 -1 . S u m m a ry o f C o m m o d o re 128 M o n ito r Com m ands

N O TE: 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:

0— RAM 0 only

1— RAM 1 only

2— RAM 2 only

3— RAM 3 only

4— INT R O M , RAM 0, I/O

5— INT R O M , RAM 1, I/O

— INT ROM , RAM 2, I/O

7— INT RO M , RAM 3, I/O

— EXT ROM , RAM 0, I/O

9— EXT ROM , RAM 1, I/O

A— EXT ROM , RAM 2, I/O

B— EXT ROM , RAM 3, I/O

C— KERNAL + INT (lo). RAM 0, I/O

D— KERNAL + EXT (lo), RAM 1, I/O

E— KERNAL + BASIC, RAM 0, CHARROM

F— KERNAL + BASIC, RAM 0, I/O

SUMMARY OF M O N ITO R

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.

precedes lines of disassembled code.

> < rig h t angle> precedes lines of a memory dump.

; < sem ico lo n > precedes line of a register dump.

The following designators precede number fields (e.g ., address) and specify the radix

(number base) o f the value. Entered as commands, these designators instruct the monitor simply to display the given value in each of the four radices.

188 COMMODORE 128

< n u ll> (default) precedes hexadecimal values.

$ < d o lla r> precedes hexadecimal (base-16) values.

+ precedes decimal (base-10) values.

& < am persand> precedes octal (base-8) values.

% 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).

< sp a c e > delimiter— separates two fields.

< co m m a > delimiter— separates two fields.

: < c o lo n > terminator— logical end of line.

? < q u estio n > terminator— logical end of line.

M O N ITO R C O M M A N D DESCRIPTIONS

The following are descriptions of each of the C l28 Machine Language Monitor commands.

COMMAND:

PURPOSE:

SYNTAX:

Enter a line of assembly code.

A < ad d ress> <opcode m nem onic> < o p eran d >

< ad d re ss> A number indicating the location in memory to place the opcode. (See 5-digit address note on

< o p co d e >

< o p eran d > previous page.)

A standard MOS technology assembly language mnemonic, e.g ., LDA, STX, ROR.

The operand, when required, can be any o f the legal addresses or constants.

A R E T U R N is used to indicate the end o f 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.

E X A M P LE :

.A 01200 LDX #$ 0 0

.A 01202

N O T E : A period (.) is equal to the ASSEMBLE command.

E X A M P LE :

.02000 LDA #$23

H O W T O ENTER M ACHINE LANGUAGE PROGRAMS IN T O THE COMMODORE 128 189

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 o f the area o f 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.

COMMAND: D

PURPOSE: Disassemble machine code into assembly language mnemonics and

SYNTAX: operands.

D [< ad d ress> ] |< ad d ress 2 > ]

< ad d re ss> A number setting the address to start the dis assembly.

< address 2 > An optional ending address o f code to be dis assembled.

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 o f disassembly to be displayed.

E X A M P LE :

D3000 3003

.03000 A9 00 LDA # $ 0 0

.03002 FF ???

.03003 DO 2B BNE $3030

COMMAND:

PURPOSE:

SYNTAX:

Fill a range of locations with a specified byte.

F <address 1> <address 2 >

<address 1> The first location to fill with the .

< address 2 > The last location to fill with the .

< byte value> A 1- or 2-digit hexadecimal number to be written.

This command is useful for initializing data structures or any other RAM area.

190 COMMODORE 128

E X A M P LE :

F0400 0518 EA

Fill memory locations from $0400 to $0518 with $EA (a NOP instruction).

COMMAND: G

PURPOSE: Begin execution of a program at a specified address.

SYNTAX: G [< ad d ress> ]

< ad d re ss> 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 o f the program.

E X A M P LE :

G 140C

Execution begins at location $140C in configuration (BANK)0. Certain applica tions 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: H

PURPOSE: Hunt through memory within a specified range for all occurrences o f a

SYNTAX: set of bytes.

H <address 1> <address 2 > < d a ta >

< address 1> Beginning address o f hunt procedure.

<address 2 > Ending address of hunt procedure.

< d a ta > Data set to search for data may be hexadecimal for an ASCII string.

E X A M P LE :

H A000 A101 A9

Search for data $A9 from A000 to A 101.

H2000 9800 ‘CA SH ’

Search for the alpha string “ CASH” .

COMMAND: J

PURPOSE: Jump to a machine language subroutine.

SYNTAX: J < ad d ress>

The JUMP to SUBROUTINE command directs program control to the machine language

H O W T O ENTER M ACHINE LANGUAGE PROGRAMS IN T O TH E COMMODORE 128 191 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.

E X A M P LE :

J 2000

Jump to the subroutine starting at $2000 in configuration 0.

COMMAND: L

PURPOSE: Load a file from cassette or disk.

SYNTAX: L < “ file nam e” > [,< d e v ic e > [,a lt load address]]

< “ file nam e” > Any legal Commodore 128 file name.

< d e v ic e > 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 (EO F) is found.

E X A M P LE :

L “ PROGRAM ” ,8 Loads the file name PROGRAM from the disk.

COMMAND: M

PURPOSE: To display memory as a hexadecimal and ASCII dump within the specified address range.

SYNTAX: M [<address 1>] [<address 2 > ]

<address 1> First address of memory dump. Optional. If omit ted, one page is displayed. The first digit is the

<address 2 > bank number to be displayed, the next four digits are the first address to be displayed.

Last address of memory dump. Optional. If om it ted, 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:

>1A 048 41 42 43 44 45 46 47 48:ABCDEFGH

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 accom plished by typing M and R E T U R N

E X A M P LE :

M 21 COO

>21 COO 41 4A 4B 4C 4D 4E 4F 50 :AJKLMNOP

N O T E : The above display is produced by the 40-column editor.

COMMAND: R

PURPOSE: Show important 8502 registers. The status register, the program counter,

SYNTAX: 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.

E X A M P LE :

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 < “ filenam e” > ,< d e v ic e > ,< a d d re s s 1 > , < address 2 >

< “ filename ” > Any legal Commodore 128 filename. To save the data, the file name must be enclosed in dou

< d e v ic e >

<address 2 > ble quotes. Single quotes cannot be used.

A number indicating on which device the file is to be placed. Cassette is 01; disk is 08, 09, etc.

Starting address of memory to be saved.

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 M ACHINE LANGUAGE PROGRAMS IN T O TH E COMMODORE 128 193

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.

E X A M P LE :

S “ G A M E” ,8,0400,0C00

Saves memory from $0400 to $0BFF onto disk.

COMMAND: T

PURPOSE: Transfer segments of memory from one memory area to another.

SYNTAX: T <address 1> <address 2 > <address 3 >

< address 2 >

Starting address of data to be moved.

Ending address of data to be moved.

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

“ com pare” is performed as each byte is transferred, and any differences are listed by address.

E X A M P LE :

T1400 1600 1401

Shifts data from $1400 up to and including $1600 one byte higher in memory.

COMMAND: V

PURPOSE: Verify a file on cassette or disk with the memory contents.

SYNTAX: V < “ filenam e” > [,< d e v ic e > ][,a lt start address]

< “ filenam e” > Any legal Commodore 128 file name.

< d ev ic e > 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.

E X A M P LE :

V “ W ORKLOAD” ,08

194 COMMODORE 128

COMMAND: X

PURPOSE:

SYNTAX: X

Exit to BASIC.

COMMAND: > (greater than)

PURPOSE: Can be used to assign values for one to eight memory locations at a time

SYNTAX:

(in 40-column mode; up to 16 in 80-column mode).

> < ad d re ss> < d ata byte 1> < d ata byte 2 . .

< ad d ress>

< d ata byte 1>

First memory address

Data to be put at address.

. 8 > to set.

< d ata byte 2 . . . 8 > D ata to be placed in the successive memory locations following the first address (optional) with a space preceding each data byte.

COMMAND: @ (at sign)

PURPOSE: Can be used to send commands to the disk drive.

SYNTAX: @ [<device num ber> ], < d isk cmd string>

<device num ber> Device unit number (optional).

< diskcm d string>String command to disk.

N O T E : @ alone gives the status of the disk drive.

E X A M P L E S :

@ checks disk status

00, OK, 00, 00 initializes drive 8 @ ,I

@ ,$ displays disk directory on unit 8.

@ ,$0:F* 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 automati cally enabled, while in the Monitor. This means the Kernal will display ‘I/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.

M A NIPULATING T E X T W IT H IN

THE M ACHINE LANGUAGE M O N ITO R

Certain machine language application programs require the manipulation o f strings of characters. If you are using an assembler package, it contains provisions for handling strings o f 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 IN T O THE COMMODORE 128 195 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 com mand with the address range in which you want to place the character string informa tion. For example, suppose you want to place the word “ TEXT” in memory starting at location $2000. First, enter the machine language monitor with the MONITOR com mand. 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: iT.TT.Tr.Tr.

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 “ TEX 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

R E T U R N . 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 “ TEX 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 t t

. t t

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 EX 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 o f machine language. For additional information on machine language topics, see Chapter 5, 7, 8, 9, 10, 11, and 13.

MIXING

MACHINE

LANGUAGE

AND B A S I C

198 COMMODORE 128

W H Y M IX B A S I C A N D

M ACHINE 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 M ACHINE LANGUAGE

SUBROUTINES TH R O UG H 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. W rite your machine language program on a piece of paper.

2. 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.

3. 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:

M IX IN G M ACHINE LANGUAGE A N D BASIC 199

1000 DATA 162,0: REM = LDX # $ 0 0 = $A2, $00

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.

4. 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 ALPHA = 8192

20 I = 0

30 DO

40 READ A

45 IF A = -9 9 9 THEN EXIT

50 POKE ALPHA + 1,A

60 I = 1 + 1

70 LOOP

80 PRINT “ ALL DATA IS NOW IN M EM ORY”

1000 DATA 162,0,-999

For C64 mode use this routine:

10 ALPHA = 8192

20 FOR 1 = 0 TO 1

40 READ A

50 POKE ALPHA + I,A

60 NEXT

80 PRINT “ ALL DATA IS NOW IN M EM ORY”

1000 DATA 162,0

The first example, in C l 28 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 -9 9 9 , EXIT the loop and print a message saying all the data is read into memory at the specified locations. This DO . . .

L O O P 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 -9 9 9 . 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).

200 COMMODORE 128

The second example, in C64 mode, uses a F O R . . . N EX T loop to enter the data. This requires you to know how many data items are in the data list. You can add an IF . . . T H E N 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.

5. 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 -999 will be your last decimal data item.

Figure 7-1 shows a step-by-step translation from the machine language screen- clear 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.

M IX IN G M ACHINE LANGUAGE A N D BASIC 201

A ddress Hex O pcode

Sym bolic

Instruction

0 2 0 0 0

0 2 0 0 2

0 2 0 0 4

0 2 0 0 7

0 2 0 0 A

0 2 0 0 D

0 2 0 1 0

0 2 0 1 1

0 2 0 1 3

A 2 0 0

A 9 2 0

L D X

L D A

# $ 0 0

# $ 2 0

9 D 0 0 0 4 S T A $ 0 4 0 0 , X

9 D 0 0 0 5 S T A $ 0 5 0 0 , X

9 D 0 0 0 6 S T A $ 0 6 0 0 , X

9 D E 7 0 6 S T A $ 0 6 E 7 , X

E 8 I N X

DO F I

6 0

B N E

R T S

$ 2 0 0 4

Figure 7 -1 . Step-by-step Tran slatio n i

1st Byte

(O pcode)

162

169

157

2 3 2

2 0 8

Decimal Equivalent

2nd B yte

(O perand)

3rd Byte

231

241

Decim al

To find the hexadecimal opcodes, refer to the 8502 Instruction and Address ing 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. In 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.

Y ou’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. Translate the value into binary:

2. Subtract 1:

3. Convert each bit to its complement; in other words, change each bit to the opposite value:

241 = 1111 0001

= 1111 0000 = 240

= 0000 1111 = 15

To find the tw o’s complement of a number, perform steps 1 and 3 above; then add 1 to the value instead o f subtracting.

H ere’s the complete C128 mode program, including all the decimal DATA equivalents of the instructions in the machine language, clear-screen subroutine above:

1 0 A L P H A = 8 1 9 2

2 0 1 = 0

3 0 D O

4 0 :

4 5

R E A D A

I F A = - 9 9 9 T H E N E X I T

5 0

6 0

P O K E A L P H A + I , A

1 = 1 + 1

7 0 L O O P

8 0 P R I N T " A L L D A T A I S N O W I N M E M O R Y "

8 5 S L E E P 1

9 0 S Y S 8 1 9 2

1 0 0 0 D A T A 1 6 2 , 0 , 1 6 9 , 3 2 , 1 5 7 , 0 , 4 , 1 5 7 , 0 , 5 , 1 5 7 , 0 , 6 , 1 5 7 , 2 3 1 , 6

2 0 0 0 D A T A 2 3 2 , 2 0 8 , 2 4 1 , 9 6 , - 9 9 9

202 COMMODORE 128

Here is the corresponding program in C64:

1 0 A L P H A = 8 1 9 2

2 0 F O R 1 = 0 T O 1 9

4 0 : R E A D A

5 0 :

6 0 N E X T

P O K E A L P H A + I , A

8 0 P R I N T " A L L D A T A I S NOW I N M E M O R Y "

8 5 F O R 1 = 1 T O 2 5 0 0 : N E X T

9 0 S Y S 8 1 9 2

1 0 0 0 D A T A 1 6 2 , 0 , 1 6 9 , 3 2 , 1 5 7 , 0 , 4 , 1 5 7 , 0 , 5 , 1 5 7 , 0 , 6 , 1 5 7 , 2 3 1 , 6

2 0 0 0 D A T A 2 3 2 , 2 0 8 , 2 4 1 , 9 6

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 C l 28 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 goal— programming in 8502 machine language.

WHERE TO PLACE M ACHINE

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 C l 28 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-

M IX IN G M ACHINE LANGUAGE A N D BASIC 203

Management Unit (MMU). For detailed information, refer to the sections on the

Registers of the Memory Management Unit (specifically, the discussion o f the Configu ration Register) in Chapter 13.

WHERE TO PLACE MACHINE LANGUAGE ROUTINES

IN C O N JU N C TIO N W IT H B A S I C

Within BASIC, the operating system takes care of the mapping in and out o f 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

1 0

1 1

1 2

CONFIGURATION

RAM(O) only

R A M (l) only

RAM (2) only

RAM (3) only

Internal ROM , RAM(O), I/O

Internal ROM , R A M (l), I/O

Internal ROM , RAM (2), I/O

Internal ROM , RAM (3), I/O

External ROM , RAM(O), I/O

External R O M , R A M (l), I/O

External ROM , R A M (2), I/O

External ROM , RAM (3), I/O

Kernal and Internal ROM (LOW ), RAM(O), I/O

Kernal and External ROM (LOW ), RAM(O), I/O

Kernal and BASIC ROM , RAM(O), Character ROM

Kernal and BASIC ROM , RAM(O), I/O

Figure 7 -2 . Bank C o n figuration T a b le

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 o f the RAM is available for pro grams, 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:

204 COMMODORE 128

1. Place the subroutine, preferably in bank 0, either through the monitor or by

POKEing in the code through BASIC. If 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 instruc tions are stored. If you are POKEing the codes in through BASIC (not the preferred method), issue the BANK 0 command within your program, assum ing 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

$1BFF. The upper part of BASIC text is also available, provided your BASIC program is small and does not overwrite your routine.

2. 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 configura tions (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 T O PLACE M ACHINE LANGUAGE

ROUTINES W HEN 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 # $ O E ;Set up the Configuration Register value

STA $D501 ;Write to Preconfiguration Register A

STA $FF01 ;Write to LCR A to change value of CR

You can use this sequence:

LDA # $ O E

STA $FF00

When you switch out BASIC, the sixteen default configurations no longer exist

M IX IN G M ACHINE LANGUAGE A N D BASIC 205 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 C l 28 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 C l 28, 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 o f 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.

•»

•*

«■

8 THE POWER

BEHIND

COMMODORE

GRAPHICS

208 COMMODORE 128

THE RELATIONSHIP BETWEEN

VID EO BANKS, RAM BANKS

A N D MEMORY CONFIG URATIO NS

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.

M A N A G IN G 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 puiposes 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 C l 28 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 C l 28 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.

TH E 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 209

1 0

1 1

1 2

BANK CONFIG U RATIO N

RAM(O) only

R A M (l) only

RAM (2) only (same as 0)

RAM (3) only (same as 1)

Internal ROM , RAM(O), I/O

Internal ROM , R A M (l), I/O

Internal ROM , RAM (2), I/O (same as 4)

Internal ROM , RAM (3), I/O (same as 5)

External ROM , RAM(O), I/O

External ROM , R A M (l), I/O

External ROM , RAM (2), I/O (same as

)

External ROM , RAM (3), I/O (same as 9)

Kernal and Internal ROM (LOW ), RAM(O), I/O

Kernal and External ROM (LOW ), RAM(O), I/O

Kernal and BASIC ROM , RAM(O), Character ROM

Kernal and BASIC ROM , RAM(O), I/O

Figure 8 - i . C l 28 D e fa u lt M e m o ry C onfigurations

-64K

■N

-64K

>

Figure 8 -2 . C l 28 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.

210 COMMODORE 128

Write

Operation

(POKE, STA $ ------ ) READ Operation (PEEK, LDA $ - - - - )

ROM

RAM memory

ROM

6 5 5 3 5

Figure 8 -3 . R O M O v e rla y

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 VID EO BANKS

In C l 28 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 o f 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-4.)

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 o f 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.

Y ou’ll understand this after reading the next few pages.

THE POWER BEHIND COMMODORE 128 GRAPHICS 211

3 video bank 3

2 video bank 2

1 video bank 1

0 video bank 0

3 video bank 3

2 video bank 2

1 video bank 1

0 video bank 0

;

Figure 8 -4 . V id e o Banks w ith in RA 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-$3FFF

$4000-$7FFF

$8000-$B FFF

$C 000-$FFFF

VALUE OF BITS 1 & 0 IN $DD00

BINARY DECIM A L

11 = 3 (DEFAULT)

10 = 2

01 = 1

0 0 = 0

Figure 8 -5 . V id e o Banks M e m o ry Ranges

Each RAM bank (0 and 1) has this memory layout.

Bits 0 and 1 o f location $DD00 select the video bank. To select a video bank in

BASIC, type this command:

P O K E 5 6 5 7 6 , (P E E K (5 6 5 7 6 ) A N D 2 5 2 ) O R 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:

L D A $ D D 0 0 ; load the accumulator with contents o f $DD00

A N D # $ F C ; preserve the upper 6 bits of $DD00

O RA # $ X ; where X is the hex value of bits 1 and 0 from Figure 8-5 above

STA $ D D 0 0 ; Place the value in $DD00

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 o f 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 o f the banking concept can be summarized as follows:

1. BASIC and the Machine Language Monitor have sixteen 64K memory con figurations that give you sixteen different combinations of memory layouts.

The MMU chip, particularly the value in the configuration register, controls most o f 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 con trolled by the MMU configuration register (bits 6 and 7), which is part o f the

C l 28 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 indepen dent 64K RAM banks.

3. 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.

H ere’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 M onitor, 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 M onitor with an additional hexadec imal 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 IK o f screen memory, and either 4K of character ROM or an 8K block o f memory for the bit map data. All these components must be present in order for graphics to operate.

THE POWER BEHIND COMMODORE 128 GRAPHICS 213

In essence, the bank concept can be thought of in this way: The C l 28 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 program ming summary.

SH A D O W REGISTERS: INTERMEDIATE STORAGE

LO C A TIO N S USED BY THE C l28 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.

C l 28 mode provides two types of split-screen displays:

1. Standard character mode and bit map mode

2. 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.

NAM E

G RAPHM

VM1*

VM1

VM2**

VM2

IN D IR E C T L O C A T IO N

BIT 7 - 216 ($00D8)

Bit 6 - 216 ($00D8)

BIT 5 - 216 ($00D8)

BITS 7-4 - 2604 <$0A2C)

BITS 3-0 - 2604 ($0A2C)

BITS 7-4 - 2605 ($0A2D)

BITS 3-0 - 2605 ($0A2D)

ACTU A L LO C A TIO N

BIT 4 - 53270 ($D016)

BIT 5 - 53265 ($D011)

BITS 7-4 - 53272 ($D018)

BITS 3-0 - 53272 ($D018)

BITS 7-4 - 53272 ($D018)

BITS 3-0 - 53272 (SD018)

* VM1 appl i es onl y t o s t andar d a n d mul t i - col or char act er (text) modes.

* * V M2 appl i es o nl y t o st anda r d and mul t i - col or bit m a p modes .

D ESC R IPTIO N

M ulticolor Mode Bit

Split Screen Bit

Bit M ap M ode Bit

Video M atrix (screen m em ory) Pointer

C h aracter Base Pointer

Video M atrix (screen memory) Pointer

Bit M ap Pointer

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 C l 28 mode is as follows:

10 POKE 2605,120

20 POKE 216,PEEK(216) OR 32

In C128 machine language, use these instructions:

LDA # $ 7 8 ; set bit map @ $2000

STA $0A2D; set video matrix @ 7 1 6 8

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 o f how to perform these programming steps.

As you can see, C l 28 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 C l 28 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 m a c h in e la n g u a g e , y o u enter:

THE POWER BEHIND COMMODORE 128 GRAPHICS 215

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 com ponents 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 C l 28 can operate in either BASIC or machine language in both C l 28 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 C l 28.

C l 28 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 addresses use indirect memory locations to change the value o f 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:

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 o f each graphic mode, as well as program examples.

L O C A T I O N *

1 1 2

128

144

160

176

192

208

224

240

BITS

OOOOXXXX

0001XXXX

0010XXXX

0011XXXX

0100XXXX

0101XXXX

0110XXXX

0111XXXX

1000XXXX

1001XXXX

1010XXXX

1011XXXX

1100XXXX

1101XXXX

1110XXXX

1111XXXX

DECIM AL

1024

2048

3072

4096

5120

6144

7168

8192

9216

10240

11264

12288

13312

14336

15360

HEX

$ 0 0 0 0

$0400 (DEFAULT)

$0800

$0C00

$ 1 0 0 0

$1400

$1800

$1C00

$ 2 0 0 0

$2400

$2800

$2C00

$3000

$3400

$3800

$3C00

*Remember that the BAN K ADDRESS offset o f $4000 per video bank m ust be added if changing to a higher video bank above 0.

Figure ft-6. Screen M e m o ry 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 “ AND

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 ($1FFF).

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

THE POWER BEHIND COMMODORE 128 GRAPHICS 217 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 C l 28 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.

M A C H IN E LANGUAGE

In machine language, use the commands listed under A in Figure 8-7 to move the C128

(VIC) text screen. Use the commands under B 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)

M OVE C l 28

TEX T SCREEN

LDA $0A2C

AND # $ 0 F

O R A #$X

STA $0A2C

(B)

M OVE C128

BIT M AP SCREEN

LDA $0A2D

AND # $ 0 F

ORA # $ X

STA $0A2D

(C)

M OVE C64

TEX T OR BJT MAP

SCREEN MEM ORY

LDA $D018

AND # $ 0 F

ORA # $ X

STA $D018

Figure 8—7. M oving Screen M e m o ry in M achine Language

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

C l 28 BASIC

Color RAM within the Commodore 128 is always stationary in memory. It occupies the address range 55296 ($D800) through 56295 (SDBE7). 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 explana tions and examples are provided in the Standard Character Mode section of this chapter.

COLOR RAM BANKING

In C l 28 mode, the LORAM and HIRAM signal lines allow the graphics system to make use o f an additional Color RAM bank, which is not available in C64 mode. This allows fast and clean switching o f 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 C l 28 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 $1FFF), 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 219 video matrix) as does C l 28 mode, though the default location for screen memory is

1024 ($0400) through 2023 ($07E7).

M A C H IN E LANGUAGE

In machine language or in BASIC, standard character mode color data always comes from the same place. Color RAM is used for m ulti-color character mode. In standard bit map mode, however, color data originates from screen memory, so wher ever 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)

C l 28 BASIC-CHARACTER MODES

In standard character mode, character information is stored in the character ROM in the memory range 53248 (SD000) through 57343 ($DFFF). In location 1 of the Com modore 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 o f bit 2 in location 1 is low, equal to zero, then the C l 28 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

M ONITOR, 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:

A D D R E S S

BLO CK D ECIM AL HEX

53248

53760

54272

54784

55296

55808

56320

56832

VIC*

IM AGE CONTENTS

DOOO-DIFF 10 0 0 -1 IFF Upper case characters

D 200-D 3FF 1200-13FF Graphics characters

D 400-D 5FF 1400-15FF Reversed upper case characters

D 600-D 7FF 1600-17FF Reversed graphics characters

D 800-D9FF 1800-19FF Lower case characters

D A00-D BFF 1A00-1BFF Upper case & graphics characters

D C00-D DFF 1C 00-1DFF Reversed lower case characters

D E00-D FFF 1E00-1FFF Reversed upper case & graphics characters

* = in C 6 4 m o d e on ly

Figure 8 -8 . B reakdow n o f C h a ra c te r Set S torage in C h a ra c te r R O M

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.

L O C A T I O N O F C H A R A C T E R M E M O R Y

VALUE

O F Z

1 0

1 2

BITS

XXXX000X

XXXX001X

XXXX010X

XXXX011X

XXXX100X

XXXX101X

XXXX110X

XXXX111X

DECIM AL HEX

2048

4096

6144

8192

14336

$0000-$07FF

$0800-$0FFF

$1000-$17FF ROM IM AGE in BANK 0 & 2

(default)*

$1800-$1FF

$2000-$27FF

10240 $2800-$2FFF

12288 $3000-$37FF

$3800-$3FFF

= in C64 mode only.

Figure 8 -9 . C h a ra c te r M e m o ry Locations

ROM IM AGE in BANK 0 & 2*

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 C l 28 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 m em ory, for each bank above 0; i.e ., for bank 3 add

3*$4000 = $C000

THE POWER BEHIND COMMODORE 128 GRAPHICS 221

C l 28 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 o f these 8000 bytes tell the computer which pixels to turn on. This block of memory “ maps out” 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 PH IC 1 command, bit 3 in 2605 is set. This specifies the bit map (data) to start at location 8192 ($2000). W henever 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 C l 28 is running under the control of C l 28 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 o f $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 language— two for each o f the four video banks. In

C l 28 BASIC, the bit map can only start at one of the four locations.

D on’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-10.

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 banks— each with four video banks per

RAM bank— you 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 IK 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 VALUE O F BIT 3 =

0 1

$0000 $2000

$4000

$8000

$C000

$6000

$AOOO

$E000

Figure 8-10. S tartin g Locations fo r B it M ap in M achine Language

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 36864-40959 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 C l 28 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

C l 28 Bit Map Mode in the last section for more detail on the arrangement of bit maps in memory.

THE POWER BEHIND COMMODORE 128 GRAPHICS 223

M A C H IN E 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 # $ F 0

ORA # $ Z

STA $02AC

LDA $02AD

AND # $ F 0

ORA # $ 0 8

STA $02AD

LDA $D018

AND # $ F 0

ORA # $ Z

STA $D018

Figure 8 -1 1 . Selected C h a ra c te r M e m o ry Location

In Figure 8-11, Z is a value in the table in Figure 8-9.

STANDARD CHARACTER MODE

H O W T O ENTER STAN D AR D

CHARACTER MODE

The C l 28 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 C l 28 defaults to the text screen.

Location 53265 (and its shadow register $00D8) determine whether the C l 28 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.

224 COMMODORE 128

SCREEN L O C A T IO N

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.

0 10

SCR EEN M E M O R Y M A P

COLUMN

20 30

1063

1744

1784

1824

1864

1904

1944

1984

1304

1344

1384

1424

1464

1504

1544

1584

1624

1664

1704

1024 ------- -

1064

1104

1144

1184

1224

1264 t

2023

Figure 8 -1 2 . Screen M e m o ry Map

H O W TH E SCREEN MEMORY D A T A

IS INTERPRETED

This screen memory range stores whole characters only. The characters are not repre sented as ASCII character string codes (CH R$). 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 225 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.

If 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 D A TA

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-13 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

COLUMN

55335

55736

55776

55816

55856

55896

55936

55976

56016

56056

56096

56136

56176

56216

56256

5 5 2 9 6 — -

55336

55376

55416

55456

55496

55536

55576

55616

55656

55696

Figure 8 13. C o lo r M e m o ry Map t

56295

10 o

226 COMMODORE 128

H O W 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

Blue

7 Yellow

Orange

9 Brown

10 Light Red

11 Dark Gray

12 M edium Gray

13 Light Green

14 Light Blue

15 Light Gray

Figure 8 -1 4 . C o lo r Codes— 40 Colum ns

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:

P O K E 5 5 2 9 6 ,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 o f 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 C l 28 receives character data from the CHARACTER

ROM. The character ROM is stored in the range 53248 (SD000) 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

THE POWER BEHIND COMMODORE 128 GRAPHICS 227

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 o f RAM, in the range 4096-8191 ($1000-$1FFF) in video BANK

0, and 36864-40959 ($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 loca tions 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.

H O W T O INTERPRET CHARACTER MEMORY

IN STANDARD CHARACTER MODE

Typically, a complete character set contains 256 characters. The C l 28 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 ( O ) 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 C l 28 has a total of 4K of character ROM. Figure 8-15 shows where each character set is stored in the character ROM.

A D D R E S S

BLOCK DECIM AL HEX

53248

53760

54272

54784

55296

55808

56320

56832

VIC-II

IM AGE CONTENTS

D 000-D 1FF 1000-1IFF Upper case characters

D 200-D 3FF 1200-13FF Graphics characters

D 400-D 5FF 1400-15FF Reversed upper case characters

D 600-D 7FF 1600-17FF Reversed graphics characters

D 800-D 9FF 1800-19FF Lower case characters

D A 00-D BFF 1A 00-1BFF Upper case & graphics characters

D C 00-D D FF 1C 00-1DFF Reversed lower case characters

D E00-D FFF 1E00-1FFF Reversed upper case & graphics characters

Figure 8 -1 5 . Location o f C h a ra c te r Sets in C h a ra c te r R O M

228 COMMODORE 128

Note that there is really 8K of character ROM— 4K for C64 mode and 4K for

C l 28 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 o f 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-16 demonstrates the correspondence between a character on the screen and the way it is represented in the character ROM.

Character on the Screen

102

110

Byte 1 ->

Byte 2 ->

Byte 3 -»

Byte 4 ->

Byte 5 -»

Byte 6 ->

Byte 7 -

Byte 8 -*

0 0 1 1 1 1 0 0 = $D000

0 1 1 0 0 1 1 0 = $D001

0 1 1 0 1 1 1 0 = $D002

0 1 1 0 1 1 1 0 = $D003

0 1 1 0 0 0 0 0 = $D004

0 1 1 0 0 0 1 0 = $D005

0 0 1 1 1 1 0 0 = $D006

0 0 0 0 0 0 0 0 = $D007

Character as

Represented in Character ROM

Figure 8 -1 6 . Relationship o f Screen C h a ra c te r to C h a ra c te r R O M .

In Figure 8-16, 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 o f the eight bytes that pertain to each row o f 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 o f character ROM ($D000) is equal to 60, which is calculated by raising two to the following bit positions:

22 + 23 + 24 + 2s = 4 + 8 + 1 6 + 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 o f pixels) o f the at-sign (@ ) character is equal to 102

(decimal) and is obtained by the following:

THE POWER BEHIND COMMODORE 128 GRAPHICS 229

2 ' + 22 + 25 + 26 = 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

C l 28 BASIC

To access character ROM in C l 28 BASIC, type and run the following program:

1 0 B A N K 1 4

2 0 F O R 1 = 5 3 2 4 8

3 0 B A N K 1 5

T O 5 3 2 4 8 + 7 : P R I N T P E E K ( I ) ; : N E X T

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.

M A C H IN E LANGUAGE

To access character ROM in C l 28 Machine Language, type and run the following program:

M O N I T O R

P C S R A C X R Y R S P

;

F B 0 0 0 0 0 1DO 0 0 0 0 F 6

. 0 1 8 0 0

. 0 1 8 0 2

. 0 1 8 0 5

. 0 1 8 0 7

. 0 1 8 0 A

. 0 1 8 0 D

. 0 1 8 0 E

. 0 1 8 1 0

. 0 1 8 1 2

. 0 1 8 1 4

. 0 1 8 1 7

A9 0 1 L D A # $ 0 1

8 D 0 0 F F S T A $ F F 0 0

A 2 0 0 L D X # $ 0 0

BD 0 0 DO L D A $ D 0 0 0 , X

9 D 4 0 1 8 S T A $ 1 8 4 0 , X

E 8

E 0 0 7

DO F 5

I N X

C P X # $ 0 7

A 9 0 0

B N E $ 1 8 0 7

L D A # $ 0 0

8 D 0 0 F F S T A $ F F 0 0

6 0 R T S

1 0 S Y S 6 1 4 4

2 0 F O R 1 = 6 2 0 8 T O 6 2 0 8 + 7 : P R I N T P E E K ( I ) ; : N E X T

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

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 C l 28.

C64 BASIC

To access character ROM in C64 BASIC, enter and run the following program:

4 0

5 0

P O K E 5 6 3 3 4 , P E E K ( 5 6 3 3 4 ) A N D 2 5 4

P O K E 1 , P E E K ( 1 ) AND 2 5 1

8 0 F O R 1 = 0 T O 7 : P O K E 6 1 4 4 + 1 , P E E K ( 5 3 2 4 8 + 1 ) : N E X T

9 0 P O K E 1 , P E E K { 1 ) OR 4

1 0 5 P O K E 5 6 3 3 4 , P E E K ( 5 6 3 3 4 ) OR 1

1 3 0 F O R 1 = 6 1 4 4 T O 6 1 4 4 + 7 : P R I N T P E E K ( I ) ; : N E X T

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 C l 28 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.

mode.

The next section explains how to program your own custom characters in C l 28

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 C l 28 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 231

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 o f 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-17 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.

4 »

5 e

6 •

7 6 5 4 3 2 1 0

• • •

1 • •

•

* « •

•

= 0 0 0 0 1 1 1 0 = 14

= 0 0 010001

0 0 1 0 0 0 0 0

0 1 0 0 0 0 1 0

1 0 0 0 0 0 1 0

130

1 0 0 0 0 1 0 0

132

1 0 0 0 1 0 1 0

138

= 01110001 = 1 2 3

Figure 8 -1 7 . Design fo r Cursive le tte r “ 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 o f 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.

232 COMMODORE 128

1 0 P R I N T C H R $ ( 1 4 2 ) : R E M S E L E C T U P P E R C A S E

2 0 P 0 K E 5 4 , 4 8 : P O K E 5 8 , 4 8 : C L R : R E M P R O T E C T C H A R S E T

3 0 B A N K 1 4 : R E M S W I T C H T O B A N K 1 4 F O R C H A R A C T E R ROM

4 0 F O R I = l T O 5 1 1 : P O K E I + 1 2 2 8 8 , P E E K ( 1 + 5 3 2 4 8 ) : N E X T : R E M ROM T O RAM T R A N S F E R

5 0 B A N K 1 5 : R E M S W I T C H T O D E F A U L T B A N K

6 0 P O K E 2 6 0 4 , ( P E E K ( 2 6 0 4 ) A N D 2 4 0 ) + 1 2 : R E M S T A R T C H A R B A S E A T 1 2 2 8 8

7 0 F 0 R J = 1 2 2 8 8 T O 1 2 2 8 8 + 7 1 : R E M P L A C E C H A R A C T E R D A T A I N RAM

8 0 R E A D A

9 0 P O K E J , A

1 0 0 N E X T J

1 1 0 S C N C L R

1 2 0 D A T A 0 , 0 , 0 , 0 , 0 , 0 , 0 , 0 : R E M @

1 3 0 D A T A 1 4 , 1 7 , 3 2 , 6 6 , 1 3 0 , 1 3 2 , 1 3 8 , 1 2 3 : R E M A

1 4 0 D A T A 1 2 4 , 6 6 , 6 6 , 1 2 4 , 6 6 , 8 1 , 2 2 5 , 1 2 6 : R E M B

1 5 0 D A T A 6 2 , 6 7 , 1 3 0 , 1 2 8 , 1 2 8 , 1 2 8 , 1 3 1 , 1 2 6 : R E M C

1 6 0 D A T A 1 2 5 , 9 8 , 1 2 5 , 6 5 , 6 5 , 1 9 3 , 1 6 1 , 2 5 4 : R E M D

1 7 0 D A T A 2 2 5 , 6 6 , 6 4 , 5 6 , 1 2 0 , 6 5 , 6 6 , 1 2 4 : R E M E

1 8 0 D A T A 1 2 7 , 1 2 9 , 2 , 4 , 1 4 , 2 2 8 , 6 8 , 5 6 : RE M F

1 9 0 D A T A 1 9 3 , 1 6 3 , 2 5 3 , 3 3 , 2 4 9 , 6 5 , 9 9 , 1 9 0 : R E M G

2 0 0 D A T A 2 2 7 , 1 6 5 , 3 6 , 3 6 , 1 2 6 , 3 6 , 3 7 , 2 3 1 : R E M 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 o f 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 C 128 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 o f 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 C l 28 screen editor uses to point to screen and character memory in character mode. You must use this indirect location to change the value o f 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 233 change the value back to the original one within a sixtieth of a second. (You can, how ever, 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 C l 28 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 F O R J = 12288 T O 12288 + (160-1)

M ULTI-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 (SD021).

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.

H O W T O ENTER M ULTI-COLOR MODE

Location 53270 and its shadow register ($00D8) determine whether the C l28 is output ting 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 o f 53270

(and bit 7 of 216) is equal to 1, multi-color mode is enabled. Otherwise, standard mode is enabled. M ost of the new 7.0 BASIC graphics commands have provisions for multi color mode. However, if you want to enter multi-color mode with a POKE command, type:

10 P O K E 216,255: REM Disable IRQ Editor

20 P O K E 53270, P E E K (53270) o r 16: REM Select MCM

This enters multi-color mode, either for character mode or bit map mode.

234 COMMODORE 128

SCREEN LO C A TIO N

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.

H O W SCREEN D A TA 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 LO C A TIO N

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.

H O W CHARACTER MEMORY IS INTERPRETED

IN M ULTI-COLOR CHARACTER MODE

Character memory is interpreted virtually the same way in m ulti-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 (loca tion 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 -1 8 . “ A t ” Sign (@ ) C h a ra c te r as It A ppears on th e Screen

THE POWER BEHIND COMMODORE 128 GRAPHICS 235

0 0 1 1 1 1 0 0

0 1 1 0 0 1 1 0

0 1 1 0 1 1 1 0

0 1 1 0 0 0 0 0

0 1 1 0 0 0 1 0

0 0 1 1 1 1 0 0

0 0 0 0 0 0 0 0

Figure 8 -1 9 . B it P attern s o f th e “ A t ” Sign (@ ) C h a ra c te r as T h e y A p p e a r in

C h a ra c te r R O M

10 11

10 00 00

00 00 00 00

Figure 8 -2 0 . B it P attern s o f the “ A t ” Sign (@ ) C h a ra c te r as T h e y A re G rouped in Pairs in M u lti-C o lo r C h a ra c te r M ode

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

0 0

0 1

1 0

1 1

COLOR REGISTER

Background # 0 color (screen color)

Background # 1 color

Background # 2 color

Color specified b y the lower 3 bits in color memory

Figure 8 -2 1 . T ru th T a b le fo r C o lo r D a ta

LOCATION

53281 ($D021)

53282 ($D022)

53283 ($D023) color RAM

236 COMMODORE 128

If the bit pair equals 00 (binary), the color of those 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) o f 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. If bit 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

1 1

1 2

1 0

COLOR

Orange

Brown

Light Red

Dark Gray

Medium Gray

Light Green

Light Blue

Light Gray

Figure 8 -2 2 . C o lo r Codes

Remember, the multi-color bit (bit 3) must be set to display multi-color characters.

The following program illustrates multi-color character mode.

1 0 C O L O R 0 , 1

2 0 C O L O R 2 , 1

3 0 C O L O R 3 , 2

3 1 F O R I = 1 T 0 2 5

: R E M

: RE M

B K G N D = B L A C K

M U L T C L R 1 =

M U L T C L R 2 =

W H I T E

R E D

3 2 P R I N T " A B C D E F G H I J K L M N O P Q R S T U V W X Y Z "

3 3 N E X T

3 5 F O R 1 = 5 5 2 9 6 + 5 1 2 T O 5 5 2 9 6 + 1 0 2 3 : P O K E I , 7 : N E X T : R E M P L A C E Y E L L O W I N C O L O R RAM

3 7 P O K E 2 1 6 , 2 5 5 : RE M D I S A B L E S C R E E N E D I T O R

4 0 P O K E 5 3 2 7 0 , P E E K ( 5 3 2 7 0 ) O R 1 6 : R E M S E T M U L T I C O L O R B I T

5 0 F O R I = 1 T 0 2 5

6 0 P R I N T " A B C D E F G H I J K L M N O P Q R S T U V W X Y Z "

7 0 N E X T

8 5 F O R 1 = 5 5 2 9 6 T O 5 5 2 9 6 + 1 0 2 3 : P O K E I , 1 4 : N E X T : R E M F I L L C O L O R RAM W I T H B L U E

9 0 G R A P H I C 0 : R E M R E T U R N T O S T A N D A R D C O L O R

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 237 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 C l 28 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 o f 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 TO 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.

238 COMMODORE 128

H O W T O INTERPRET SCREEN D A TA

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 (@); therefore the first screen code, 0, is the code for the at sign.

Remember, since extended background color mode only uses five bits to deter mine the screen code value, only the first 64 screen code characters (0-63) are available.

COLOR D A TA

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 o f 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.

C H A R A C T E R C O D E

BIT 7 BIT 6 RANGE

0-63

64-127

128-191

192-255

B A C K G R O U N D C O L O R

R E G I S T E R

NUMBER

ADDRESS

53281 ($D021)

53282 ($D022)

53283 ($D023)

53284 ($D024)

Figure 8 -2 3 . Extended Background C o lo r 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 239

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.

H ere’s a program that illustrates how extended background color mode operates:

5 S C N C L R

1 0 C O L O R 0 , 1 : RE M B K G R D = B L A C K

2 0 C O L O R 2 , 1 : R E M M U L T I C O L O R 1

3 0 C O L O R 3 , 2 : RE M M U L T I C O L O R 2

4 0 P O K E 5 3 2 8 4 , 3 : R E M B A C K G R D C O L O R 3

4 5 P O K E 5 3 2 6 5 , P E E K ( 5 3 2 6 5 ) O R 6 4 : R E M S E T E X T E N D E D B K G R N D B I T

5 0 F O R 1 = 1 0 2 4 T O 1 2 5 6 : P O K E I , 1 - 1 0 2 3 : N E X T

6 0 P R I N T : P R I N T : P R I N T : P R I N T

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 D A TA

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.

240 COMMODORE 128

0,0

X Coordinate

319,0

Y Coordinate

0,199

Figure 8 -2 4 . B it M ap Screen C oordinates

319,199

H O W T O ENTER STANDARD BIT MAP MODE

To enter standard bit map mode, set bit 5 o f location 216 ($00D8) (the shadow register of location 53265 ($D011)). When you issue the GRAPHIC 1,1 command in C128 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 highest- level 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 C l 28 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

TH E V ID E O M ATRIX

(SCREEN MEMORY) LO C A TIO N

The default location of the C128 video matrix (i.e., the bit map screen memory) is 7168

($1C00) through 8167 ($1FE7).

The default location of the C64 video matrix is 1024 ($0400) through 2023

THE POWER BEHIND COMMODORE 128 GRAPHICS 241

($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

In 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 o f 320 pixels, so that the entire screen is composed o f 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 o f 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 or just under 8K of memory. The spare bytes are used for other purposes. Location 53272 determines the location o f 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.

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 C l 28 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 C oordinate

Figure 8 -2 5 . Relationship o f B it M ap D a ta to Screen Pixels

Now you know how bit map mode operates internally within your C l 28. 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 high- resolution 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 243

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 RAH

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

M ulti-color bit map mode is a combination o f 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 TO 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 C l 28 interrupt driven screen editor. This indirectly turns on, respectively, bit 4 (multi-color mode) of location 53270 ($D 016). and bit 5 (bit map mode) o f location 53265 ($D 011).

Bit 5 o f 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 C l 28 is in standard or multi-color mode. If bit 4 is set, the

C l 28 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 C l 28 screen editor is interrupt driven, enabling the split screen 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

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 C l 28 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 # $ 1 0 ; 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 ($1FE7) 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.

H O W TO 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 colors— background 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 245

BITS

0 0

0 1

1 0

1 1

COLOR INFORMATION COMES FROM

Background color # 0 (screen color)

Upper four bits o f video matrix

Lower four bits o f video matrix

Color RAM

F igure 8 -2 6 . M u lti-C o lo r B it M ap Pixel C o lo r Assignments

TH E 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 applica tions 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 C l 28.

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

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 pro gram 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 C l 28 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 C l 28 defaults the start to line 19.

H O W SPLIT-SCREEN MODES ARE

O RG ANIZED IN MEMORY

SCREEN LO C A TIO N S

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 ($1FFF), 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 247

INTERPRETING SCREEN D A TA

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 LO C A TIO N S

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 o f 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, stan dard bit map and multi-color bit map modes, see the sections describing these modes.

COLOR D A TA

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.

M A C H IN E 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

TH E 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.

248 COMMODORE 128

Unlike the Commodore 64, the C l 28 handles interrupts exclusively according to the raster beam. This has made it necessary to merge the C l 28 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 inter rupts 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 o f the raster beam the intermediate memory locations refresh the actual VIC chip and 8563 chip registers.

RASTER INTERRUPT

SPLIT SCREEN PROGRAM

W ITH H O R IZO N TA L 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 C l 28 Mode. A few differ ences 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 C l 28 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 o f 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 multi color 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 249

1. First start in C128 m ode, and enter split screen (m ulti-color) bit map mode through BASIC with this command:

GRAPHIC 4,1

2. Now draw on the screen with the BOX, CIRCLE, DRAW and PAINT commands either in a program or in direct mode.

3. When you are finished drawing, enter the machine language monitor either by pressing the F 8 function key or by typing the MONITOR command.

4. Now transfer the video matrix and bit map from the C l 28 default locations of

$1C00 through $1FFF 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 “ filenam e” , 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. D on’t worry, your program will still be in memory, but this time it’s in C l 28 memory. Next enter the Machine Language Monitor and use the Monitor Save (S) command to make a binary file as described above.

250 COMMODORE 128

Now you are ready to enter C64 mode and run the program with the following command:

GO 64

Reply to the question “ ARE 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 C l 28 and C64 modes:

$0C00 - $0DFF

$1300 - $1BFF

$ 1 C 0 0 - $1FFF

$2000 - $3FFF

$4000 - $FF00

C128 M EM ORY LAYOUT

RS232 Input and Output Buffers

Available Memory for Machine Language application programs

Bit Map Video Matrix

Bit Map Data

BASIC Text Area

Figure 8 -2 7 . Preserved RAM B etw een C l 28 and C 64 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 C l 28 mode to C64 mode with the GO 64 command, or you switch from C64 to C l 28 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.

1 0 0 0 ; R A S T E R I N T E R R U P T S P L I T S C R I

1 0 1 0 I V E C = $ 0 3 1 4

1 0 2 0 T E M P = $ 1 8 0 6

1 0 3 0 R A S T R O = $ D O 1 2

1 0 4 0 B A C O L = $ D 0 2 1

1 0 5 0 P O I N T = $ 1 8 0 2

1 0 6 0 F L A G = $ F C

1 0 7 0 F L A G 2 = $ F D

1 0 8 0 S C R O L L = $ F E

1 0 9 0 S R E G = $ D 0 1 6

1 1 0 0 T X T P T R = $ F A

1 1 1 0

1 1 2 0

1 1 3 0 ;

* = $ 0 C 0 0

; P O I N T E R I N T O

1 1 4 0

1 1 5 0

L D A # < F R A N K ; P O I N T T O T E X T

S T A T X T P T R

L D A # > F R A N K 1 1 6 0

1 1 7 0

1 1 8 0 ;

S T A T X T P T R + 1

1 1 9 0 L D A # $ 0 7 ; S E T H I V A L S R E G

1 2 0 0

1 2 1 0

S T A S C R O L L

S T A F L A G 2

1 2 2 0 ;

1 2 3 0 L D A $ D D 0 2 ; S E T T O O U T P U T

1 2 4 0

1 2 5 0

1 2 6 0 j

1 2 7 0

O R A # $ 0 3

S T A $ D D 0 2

1 2 8 0

1 2 9 0

L D A $ D 0 1 6 ; S E T 3 8 C O L .

A N D # $ F 7

1 3 0 0

1 3 1 0 ;

1 3 2 0 •

S T A $ D 0 1 6

1 3 3 0

1 3 4 0

1 3 5 0

L D A # $ 0 1 ; C L E A R CR AM

L D X # $ 0 0

B O N K S T A $ D B 2 0 , X

1 3 6 0

1 3 7 0

I N X

C P X # 2 0 0

B N E BONK 1 3 8 0

1 3 9 0

1 4 0 0

1 4 1 0 I N I T I A L I Z E I N T E R R U P T

1 4 2 0

1 4 3 0 L O O P l S E I

1 4 4 0

1 4 5 0

1 4 6 0

1 4 7 0

L D A I V E C

S T A T E M P

L D A I V E C + 1

S T A T E M P + 1

1 4 8 0

1 4 9 0

1 5 0 0

1 5 1 0

L D A # < M I N E

S T A I V E C

L D A # > M I N E

S T A I V E C + 1

1 5 2 0

1 5 3 0

1 5 4 0

1 5 5 0

1 5 6 0 ;

1 5 7 0

L D A # $ 0 0 ; D I S A B L E T I M E R I R Q

S T A $ D C 0 E

S T A F L A G

1 5 8 0

1 5 9 0

L D A # 4 9

S T A P O I N T

S T A R A S T R O

1 6 0 0

1 6 1 0

1 6 2 0

;

L D A # 2 0 1

S T A P O I N T + 1

1 6 3 0

1 6 4 0 ;

1 6 5 0

1 6 6 0

1 6 7 0

1 6 8 0

L D A # 1

S T A $ D 0 1 A ; E N A B L E I N T E R R U P T

S T A $ D 0 1 9 ; R A S T E R C O M P A R E

L D A $ D 0 1 1 ; C L E A R H I B I T

THE POWER BEHIND COMMODORE 128 GRAPHICS 251

H O R I Z O N T A L S C R O L L I N G

252 COMMODORE 128

1 6 9 0

1 7 0 0

1 7 1 0

1 7 2 0

1 7 3 0

1 7 4 0

A N D # $ 7 F

S T A $ D 0 1 1

C L I

; D I S A B L E I N T R P T D I S B I T

1 7 5 0

1 7 6 0

1 7 7 0 C H E C K L D A F L A G 2

1 7 8 0

1 7 9 0

1 8 0 0

1 8 1 0

B P L C H E C K

L D A # $ 0 0

S T A F L A G 2

1 8 2 0

1 8 3 0

L D X # 3 9

L D Y # 3 9

1 8 4 0 S H I F T L D A ( T X T P T R ) , Y

1 8 5 0 S T A $ 0 7 7 0 , X

1 8 6 0

1 8 7 0

1 8 8 0

1 8 9 0

1 9 0 0

1 9 1 0

DE X

DE Y

B P L S H I F T

I N C T X T P T R

B N E M V T I M E

I N C T X T P T R + 1

; T I M E T O R E S E T P O I N T E R

1 9 2 0 M V T I M E L D A T X T P T R ; A R E WE A T T H E E N D O F T H E T E X T

1 9 3 0

1 9 4 0

C MP # < E N D T X T

B N E C H E C K

L D A T X T P T R + 1 1 9 5 0

1 9 6 0

1 9 7 0

1 9 8 0

1 9 9 0

2 0 0 0

2 0 1 0

2 0 2 0

CMP # > E N D T X T

B N E C H E C K

L D A # < F R A N K ; S E T P O I N T E R B A C K T O T H E B E G I N N I N G

S T A T X T P T R

L D A # > F R A N K

S T A T X T P T R + 1

J M P C H E C K

2 0 3 0

2 0 4 0 F R A N K . B Y T

2 1 8 0

2 1 9 0

2 2 0 0

2 2 1 0

2 2 2 0

2 2 3 0

2 2 4 0

2 2 5 0

2 2 6 0

2 2 7 0

2 2 8 0

2 2 9 0

2 3 0 0

2 3 1 0

2 3 2 0

2 3 3 0

2 3 4 0

2 3 5 0

2 3 6 0

2 3 7 0

2 0 5 0

2 0 6 0

2 0 7 0

2 0 8 0

■ B Y T

■ B YT

■ B Y T

' T H I S I S A N E X A M P L E O F S C R O L L I N G

' I N T H E H O R I Z O N T A L ( X ) D I R E C T I O N .

2 0 9 0

2 1 0 0

■ B Y T ' O N C E T H E D A T A H A S B E E N D I S P L A Y E D ,

■ B Y T ' S C R O L L I N G S T A R T S A G A I N F R O M T H E

• B Y T ' B E G I N N I N G . '

2 1 1 0

2 1 2 0 E N D T X T . B Y T

2 1 3 0

2 1 4 0

• B Y T

2 1 5 0 I N T E R R U P T

2 1 6 0

2 1 7 0 M I N E L D A $ D 0 1 9

S E R V I C E R O U T I N E

S T A $ D 0 1 9

L D A F L A G ; F L A G = 0

E O R # 1 ; F L A G = 0

S T A F L A G ; F L A G = 1

T A X ; . X = 1

L D A P O I N T , X ; . X = 1

. A = 0

S T A R A S T R O ; . X = 1 R A S T R O = 2 0 0

C P X # 1

B N E B O T T O M

L D A $ D 0 1 1

O R A # $ 2 0

S T A $ D 0 1 1

L D A $ D 0 1 8

O R A # $ 7 8

S T A $ D 0 1 8

L D A $ D 0 1 6

OR A # $ 1 0

. A = 1

. A = l

, A = 2 0 0

; B I T MAP MODE

; BMM

; C H A R = $ 2 0 0 0 + $ 4 0 0 0

; S C R = $ 1 C O O + $ 4 0 0 0

S T A $ D 0 1 6 ; S E T M U L T I C O L O R

2380 ;

2390 LDA $DD00 ;SELECT BANK 1

2400 AND # $FE

2410 STA SDD00

2420

2430 LDA SREG ;SET SCRRREG

2440 AND #$F8

2450 ORA #$03

2460 STA SREG

2470 ;

2480 LDA #14

2490 STA $D021

2500 ;

2510 PLA

2520 TAY

2530 PLA

2540 TAX

2550 PLA

2560 RTI

2570

2580 ;

2590 BOTTOM LDA $D011 ; SET TEXT

2600 AND # $FF-$ 2

2610 STA $D011

2620

2630 LDA $DD0 0 ;CHANGE TOBANK 0

2640 ORA #$01

2650 STA $DD00

2660

•

2670 LDA $D016 ; DISABLE MULTI

2680 AND #$FF-$10

2690 STA $D016

2700

2710 LDA #23 ; MEMORY

2720 STA $D018

2730 ■

2740 LDA #$00

2750 STA $D021

2760 LDA SCROLL

2770 j

2780

2790 DEC SCROLL

2800 LDA SCROLL

2810 STA FLAG

2820 CMP #$FF

2830 BNE SLURP

2840 LDA #$07

2850 SLURP STA SCROLL

2860 LDA SREG

2870 AND #

2880 ORA SCROLL

2890 STA SREG

2900 BASIRQ JMP (TEMP)

2910 j

2920 • END

THE ROWER BEHIND COMMODORE 128 GRAPHICS 253

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 ad dresses. Most o f the actual addresses are listed in the beginning o f the program (lines

1010 through 1100). Keep in mind that these are only line numbers for an assembler

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 o f 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 o f 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 255 will SYS to this address to start the program in BASIC, or GO to this address from the

Machine Language Monitor.

The first sequence o f program instructions starting at line 1140 places the contents of the address (named FRANK) of the beginning o f the scrolling text into the memory locations ($FA and $FB) called TXTPTR and TXTPTR + 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

‘THIS 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 o f 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 fore ground. The low er 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 LOOP1, sets the interrupt disable bit in the status register. W hen this bit is set, interrupts are disabled and none can occur. Only when the interrupt disable bit is cleared

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 TEMP + 1 (high byte $1807). This is necessary in order to store the original contents o f the IRQ vector so you can jum p 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 M onitor, 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 C l 28 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 POINT + 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 257

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 initializa tion 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.

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 “ THIS IS AN EXAM

PLE . . . ” 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 “ T ” in “ TH IS” one character position across the screen. The next 39 cycles, 37 spaces and the letters “ T H ” in “ TH IS” 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 M onitor 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.

TH E 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 o f the label M INE, 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

($0D 71).

THE POWER BEHIND COMMODORE 128 GRAPHICS 259

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 X O R’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 o f 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

+ 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 jum ps 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.

260 COMMODORE 128

C l 2 8

BASIC

C H A N G IN G VIDEO BANKS

POKE 56576, (PEEK (56576)

AND 252) OR X

W HERE X IS THE DECIMAL

VALUE OF BITS 0 AND 1 IN

TABLE 8-30 ON PAGE 262

C l 28

M AC HINE

LANGUAGE

LDA $DD00

AND #$ F C

ORA # $ X

STA $DD00

W HERE 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

W HERE X IS THE DECIMAL

VALUE OF BITS 0 and 1 IN

TABLE 8-30 on P. 262

M O VIN G SCREEN RAM

TEXT

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

W HERE X IS A VALUE IN

TABLE 8-29 ON P. 262

TEXT BIT MAP

LDA $0A2C LDA $0A2D

AND # $ 0 F AND # $ 0 F

ORA # $ X ORA # $ X

STA $0A2C STA $0A2D

W HERE X IS A HEX EQU IV A

LENT OF THE DECIM AL

VALUE IN FIGURE 8-29 ON P.

262

TEX T OR BIT MAP

POKE 53272, (PEEK(53272)

AND 15) OR X

W HERE X IS A DECIM AL

VALUE IN FIGURE 8-29 ON P.

262

C64

M AC HINE

LANGUAGE

LDA $DD00

A ND #$F C

ORA # $ X

STA $DD00

W HERE X IS THE HEX VALUE

OF BITS 0 AND 1 IN

TABLE 8-30 ON P. 262

TEX T OR BIT M AP

LDA $D018

AND # $ 0 F

ORA # $ X

STA $D018

W HERE X IS A HEX

EQUIVALENT OF THE DECIM AL

VALUE IN FIGURE 8-29 ON P.

262

IN C64 M ODE, YOU CAN SET

UP TWO DIFFERENT SCREENS,

ONE FOR TEXT AND THE

O THER FOR BIT MAP, AS THE

C l 28 KERNAL DOES.

Figure 8-28. Graphics P ro g ram m in g S u m m a ry— P A R T I

THE POWER BEHIND COMMODORE 128 GRAPHICS 261

M O V IN G CHARACTER MEMORY

TEXT

POKE 2604, (PEEK(2604)AND 240) OR Z

BIT MAP*

POKE 2605, (PEEK (2605)AND 240) OR Z

W HERE Z IS A DECIM AL VALUE

IN FIGURE 8-31 ON P. 262

* = ONLY BIT 3 IS SIGNIFICANT

IN BIT MAP MODE

ACCESSING CHARACTER ROM

10 BANK 14: REM SW AP IN CHAR ROM

20 FOR 1 = 0 TO 7

30 ? PEEK (I)

40 NEXT

50 BANK 15

TEXT BIT MAP*

LDA $0A2C LDA $0A2D

AND # $ F 0 AND # $ F 0

ORA # $ Z ORA # $ Z

STA $0A2C STA $0A2D

W HERE Z IS THE HEX EQUIVALENT OF

A DECIM AL VALUE IN FIGURE 8-31 ON

P. 262

* = ONLY BIT 3 IS SIGNIFICANT IN BMM

LDA #$01

INX

CPX # $ 0 7

LDA # $ 0 0

STA $FF00

LDX # $ 0 0

STA $FF00

BNE LOOP

LDA # $D 000,X

LOOP STA $TEM P,X

TEXT OR BIT MAP*

POKE 53272, (PEEK(53272)AND240) OR Z

W HERE Z IS A DECIM AL VALUE IN

FIGURE 8-31 ON P. 262

* = ONLY BIT 3 IS SIGNIFICANT

IN BIT MAP MODE

5 TEM P = 6144

10 POKE 56334,PEEK (56334) AND 254

20 POKE 1, PEEK (1) AND 251

30 FOR 1 = 0 TO 7

40 POKE (TEM P + I, PEEK (53248 + I)

50 NEXT

60 POKE 1, PEEK (1) OR 4

70 POKE 56334, PEEK (56334) OR 1

80 FOR I = TEM P TO TEM P + 7

90 ? PEEK (I);

100 NEXT

TEXT OR BIT MAP*

LDA $D018

AND # $ F 0

ORA # $ Z

STA $D018

W HERE Z IS THE HEX EQUIVALENT

O F A DECIM AL VALUE IN FIGURE

8-31 ON P. 262

* = ONLY BIT 3 IS SIGNIFICANT

IN BIT MAP MODE

LDA $DC0E

AND # $ F E

STA $DC0E

LDA $01

AND #$ F B

STA $01

LDX # $ 0 0

LOOP LDA $D000,X

STA $TEM P,X

INX

CPX # $ 0 7

BNE LOOP

LDA $01

ORA #$01

STA $01

LDA $DC0E

ORA #$01

STA $DC0E

Figure 8-28. Graphics P ro g ram m in g S u m m a ry — P A R T 2

262 COMMODORE 128

L O C A T I O N *

1 1 2

128

144

160

176

192

208

224

240

BITS

OOOOXXXX

0001XXXX

0010XXXX

0011XXXX

0100XXXX

0101XXXX

0110XXXX

0111XXXX

1000XXXX

1001XXXX

1010XXXX

1011XXXX

1100XXXX

1101XXXX

1110XXXX

1111XXXX

DECIMAL

9216

10240

11264

12288

13312

14336

15360

1024

2048

3072

4096

5120

6144

7168

8192

HEX

$ 0 0 0 0

$0400 (DEFAULT)

$0800

$0C00

$ 1 0 0 0

$1400

$1800

$1C00

$ 2 0 0 0

$2400

$2800

$2C00

$3000

$3400

$3800

$3C00

*Remember that the BANK ADDRESS offset o f $4000 for each video bank above zero must be added to the screen memory address.

Figure 8-29. Screen M e m o ry Locations

BANK ADDRESS RANGE VALUE OF BITS 1 & 0 IN $DD00

$0-$3FFF

$4000-$7FFF

$8000-$B FFF

$C 000-$FFFF

BINARY DECIM A L

1 1 = 3 (DEFAULT)

1 0

0 1

Figure 8 -3 0 . V ideo Bank M e m o ry Ranges

L O C A T I O N O F C H A R A C T E R M E M O R Y *

VALUE

OF Z BITS DECIMAL HEX

1 0

1 2

XXXXOOOX

XXXX001X

XXXX010X

XXXX011X

XXXX100X

XXXX101X

XXXX110X

XXXX111X

2048

4096

6144

8192

10240

12288

14336

$0000-$07FF

$0800-$0FFF

$1000-$17FF ROM IM AGE in BANK 0 & 2

(default)*

$1800-$1FFF ROM IM AGE in BANK 0 & 2*

$2000-$27FF

$2800-$2FFF

$3000-$37FF

$3800-$3FFF

Rem em ber to add an offset o f $4000 to the start address o f character m em ory for each bank above 0; for bank 3 add 3*$4000 = $C000

* = in C64 mode only.

Figure 8 - 3 1. C h a ra c te r M e m o ry Locations

THE POWER BEHIND COMMODORE 128 GRAPHICS 263

C128 BASIC

(DEFAULTS)

C l 28

M A CHINE

LANGUAGE

C64 BASIC

(DEFAULTS)

C64

M A CHINE

LANGUAGE

T E X T

SCREEN DATA

B IT M A P

1024-2023 7168-8167

($0400-$07E 7) ($1 C 0 0 -

S1FE7)

1024-2023 7168-8167

($0400-$07E 7) ($1C00-$1FE7)

THIS IS

ALSO PRO

GRAMMABLE

THIS IS

ALSO PR O

GRAMMABLE

SEE

GRA PH ICS

SUM M ARY

1024-2023 1024-2023

($0400-$07E 7) ($0400-$07E7)

THIS IS

ALSO PRO

GRAMMABLE

1024-2023

($0400-$07E7) ($0400-$07E7)

THIS IS ALSO PROGRAM-

MA BLE

1024-2023

T E X T

COLOR DATA

B IT M A P

55296-56295

(SD 800-

SDBE7)

T A K E N

FROM BIT

M AP VIDEO

M ATRIX

55296-56295

(SD 800-

SDBE7)

55296-56295

(SD 800-

SDBE7)

55296-56295

($D 800-

$DBE7)

*TAKEN

FROM BIT

M A P VIDEO

MA TRIX

*TAKEN

FROM BIT

MAP VIDEO

MA TRIX

CHARACTER DATA

T E X T

53248-57343

($D 000-

SDFFF)

B IT M A P

8192-16383

($2000-$3FFF)

T E X T

53248-57343

(SD 000-

SDFFF)

8192-16383

($2000-$3FFF)

THIS IS

ALSO PR O

GRAMMABLE

SEE

GRA PH ICS

SUM M ARY

ROM IM AGE NO DEFAULT

IS AT MUST

4096-8191*

($1000-

BE PRO

G RA M M ED

1 $FFF) SEE

GRAPHICS

SU M M ARY

*TAKEN

FROM BIT

M A P VIDEO

M A TRIX

UPPER

N Y B B L E =

FOREGROU ND

LOW ER

N Y B B L E =

BAC KGROUND

ROM IMAGE NO DEFAULT

IS AT

4096-8191*

($1000-$1FFF)

M UST BE

PRO

GRA M M ED

SEE

GRAPHICS

SU M M ARY

* = actual ch aracter

R O M location =

53 2 4 8 -5 7 3 4 3

(SDOOO-DFFF)

Figure 8 -3 2 . D e fa u lt Graphics M e m o ry Locations

N O T E : These locations pertain to video bank zero (0) only.

■

0 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 C l28 has predefined storage locations for sprite data in the range 3584 ($OEOO) through 4095 ($0FFF).

The C l 28 graphics system has 8 sprites. Each sprite moves on its own indepen dent plane. A sprite may move in front o f or behind objects or other sprites on the screen, depending on the specified priority. Standard bit-mapped sprites may be any one o f 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 Commo dore 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 assign ments, sprite expansion and addressing the sprite registers in machine language.

SPRITES 267

BASIC 7.0

SPRITE CO M M AN D SUMMARY

H ere’s a brief description of each BASIC 7.0 sprite command:

C O L L IS IO N : Defines the type of sprite collision on the screen, either sprite to sprite or sprite to data collision

M O VS PR : Positions or moves sprites from one screen location to another

SP R C O LO R : 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

SSH APE: Stores the image of a portion of the bit-map screen into a text-string variable

BASIC 7.0

SPRITE C O M M AN D 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

E X A M P LE :

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.

268 COMMODORE 128

2. M OVSPR number, + X, + Y Move sprite relative to its current position.

3. M OVSPR number, X;Y Move sprite distance x at angle y relative to its current position.

4. MOVSPR number, angle # speed 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.

A N G LE 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.

EX A M P LE S :

MOVSPR 1, 150, 150

MOVSPR 1, + 2 0 , + 3 0

MOVSPR 4, 50; 100

MOVSPR 5, 45 # 1 5

Position sprite 1 at coordinate 150,150.

Move sprite 1 to the right 20 (X) coordinates and down

30 (Y) coordinates.

Move sprite 4 by 50 coordinates at a 100 degree angle.

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 [sm cr-1] [,sm cr-2] where:

SPRITES 269 sm cr-1 sm cr-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.

E X A M P LE S:

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.

SPR D EF

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 DESCRIPTIO N

1 - 8

keys

CRSR keys

RETURN key

HOM E key

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

Turns on and off automatic cursor movem ent.

Moves cursor.

M oves cursor to start of next line.

Exits sprite designer mode at the SPRITE

NUMBER? prompt only.

M oves cursor to top left

CLR key

1-4 keys

CTRL key, 1-8 corner o f sprite work area.

Erases entire grid.

Selects color source and enables sprite pixels.

Selects sprite foreground color (1-8).

Comm odore key, 1-8 Selects sprite foreground color (9-16).

STOP key

SHIFT RETURN

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.

M ulti-color sprite.

Copies sprite data from one sprite to another.

This SPRite DEFinition area is shown in Figure 9-1.

270 COMMODORE 128

Figure 9 -1 . SPRite D E F inition A re a

SPRITE CREATION PROCEDURE IN

SPRITE D E F IN IT IO N MODE

H ere’s the general procedure to create a sprite in SPRite DEFinition mode:

1. Clear the work area by pressing the shift and CLR/HOME keys at the same time.

2. 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.

3. 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 .

4. 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 271 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.

5. 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.

6 . 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.

7. 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 appropri ate sprite storage area. The displayed sprite in the upper right corner o f 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

8 . 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.

9. If you do not want to SAVE your sprite, press the STOP key. The Commo dore 128 turns off the displayed sprite and any changes you made are cancelled. You are returned to the SPRITE NUMBER prompt.

10. 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

272 COMMODORE 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 “ filenam e” , BO, P3584 TO P4096 (This saves all 8 sprites.)

SPRITE

Turn on and off, color, expand and set screen priorities for a sprite

SPRITE num ber> [,on/off][,fngd][,priority] [,x-exp] [,y-exp] [,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.

PARAM ETER number on/off foreground priority x-exp y-exp mode

D ESCRIPTION

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

if sprites appear in back o f 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 (

)

Unspecified parameters in subsequent sprite statements take on the characteristics o f the previous SPRITE statement. You may check the characteristics of a SPRITE with the

RSPRITE function.

EX A M P LE S:

SPRITE 1,1,3 Turn on sprite number 1 and color it red.

SPRITES 273

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

C l 28 to expand the sprite vertically only. The last 1 specifies multi-color mode. Use the SPRCOLOR com mand 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 o rig in > , 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 1,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: where:

SSHAPE string variable, X I, Y l [,X2,Y2] string variable

X I ,Y l

X2,Y 2

String name to save data in

Corner coordinate (0,0 through 319,199) (scaled)

Corner coordinate opposite (X I,Y l) (default is the PC)

Also see the LOCATE command described in Chapter 3 for information on the pixel cursor.

274 COMMODORE 128

EX A M P LE S :

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,47,51 Saves a rectangular area from top left coordinate

(20,30) through bottom right coordinate (47,51) into string variable B$.

SSHAPE D$, + 10, + 10 Saves a rectangular area 10 pixels to the right and 10 pixels down from the current position of the pixel cursor.

A D JO IN IN G 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 cap sule, 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 C O L O R 4 , 1 : C O L O R 0 , 1 : C O L O R 1 , 2 : R E M S E L E C T B L A C K B O R D E R & B K G R N D , W H I T E F R G R D

1 0 G R A P H I C 1 , 1 : R E M S E T H I R E S MODE

1 7 F O R I = 1 T 0 4 0

1 8 X = I N T ( R N D ( 1 ) * 3 2 0 ) + 1 : R E M DRAW S T A R S

1 9 Y = I N T ( R N D ( 1 ) * 2 0 0 ) + 1 : R E M DRAW S T A R S

2 1 DRAW 1 , X , Y : N E X T : R E M DRAW S T A R S

2 2 B O X 0 , 0 , 5 , 7 0 , 4 0 , , 1 : R E M C L E A R B O X

2 3 B O X 1 , 1 , 5 , 7 0 , 4 0 : R E M B O X - I N S P A C E S H I P

24 COLOR 1 , 8 :CIRCLE 1,190,90,35,25:PAINT 1,190,95:REM DRAW & PAINT PLANET

2 5 C I R C L E 1 , 1 9 0 , 9 0 , 6 5 , 1 0 : C I R C L E 1 , 1 9 0 , 9 3 , 6 5 , 1 0 : C I R C L E 1 , 1 9 0 , 9 5 , 6 5 , 1 0 : C O L O R 0 , 1

2 6 DRAW 1 , 1 0 , 1 7 T O 1 6 , 1 7 T O 3 2 , 1 0 T O 3 3 , 2 0 T O 3 2 , 3 0 T O 1 6 , 2 3 T O 1 0 , 2 3 T O 1 0 , 1 7

2 8 DRAW 1 , 1 9 , 2 4 T O 2 0 , 2 1 T O 2 7 , 2 5 T O 2 6 , 2 8 : R E M B O T T O M WI N D O W

3 5 DRAW 1 , 2 0 , 1 9 T O 2 0 , 1 7 T O 2 9 , 1 3 T O 3 0 , 1 8 T O 2 8 , 2 3 T O 2 0 , 1 9 : R E M T O P WI N D O W

3 8 P A I N T 1 , 1 3 , 2 0 : R E M P A I N T S P A C E S H I P

4 0 DRAW 1 , 3 4 , 1 0 T O 3 6 , 2 0 T O 3 4 , 3 0 T O 4 5 , 3 0 T O 4 6 , 2 0 T O 4 5 , 1 0 T O 3 4 , 1 0 : R E M S P 1

4 2 DRAW 1 , 4 5 , 1 0 T O 5 1 , 1 2 T O 5 7 , 1 0 T O 5 7 , 1 7 T O 5 1 , 1 5 T O

4 3 DRAW 1 , 4 6 , 2 2 T O 5 1 , 2 4 T O 5 7 , 2 2 T O 5 7 , 2 9 T O 5 1 , 2 7 T O

4 6 , 1 7 : R E M E N G 1

4 5 , 2 9 : R E M E N G 2

4 4 P A I N T 1 , 4 0 , 1 5 : P A I N T 1 , 4 7 , 1 2 : P A I N T 1 , 4 7 , 2 6 : DRAW 0 , 4 5 , 3 0 T O 4 6 , 2 0 T O 4 5 , 1 0

4 5 DRAW 0 , 3 4 , 1 4 T O 4 4 , 1 4 : DRAW 0 , 3 4 , 2 1 T O 4 4 , 2 1 : D R A W 0 , 3 4 , 2 8 T O 4 4 , 2 8

4 7 S S H A P E A $ , 1 0 , 1 0 , 3 3 , 3 2 : R E M S A V E S P R I T E I N A $

4 8 S S H A P E B $ , 3 4 , 1 0 , 5 7 , 3 2 : R E M S A V E S P R I T E I N B $

5 0 S P R S A V A $ , 1 : R E M S P R 1 D A T A

5 5 S P R S A V B $ , 2 : R E M S P R 2 D A T A

6 0 S P R I T E 1 , 1 , 3 , 0 , 0 , 0 , 0 : R E M S E T S P R 1 A T T R I B U T E S

6 5 S P R I T E 2 , 1 , 7 , 0 , 0 , 0 , 0 : R E M S E T S P R 2 A T T R I B U T E S

8 2 M O V S P R 1 , 1 5 0 , 1 5 0 : R E M O R I G I N A L P O S I T I O N O F S P R 1

8 3 M O V S P R 2 , 1 7 2 , 1 5 0 : R E M O R I G I N A L P O S I T I O N O F S P R 2

8 5 M O V S P R 1 , 2 7 0 # 5 : R E M MOV E S P R 1 A C R O S S S C R E E N

8 7 M O V S P R 2 , 2 7 0 # 5 : R E M MOV E S P R 2 A C R O S S S C R E E N

9 0 F O R 1 = 1 T O 5 9 5 0 : N E X T : R E M D E L A Y

9 2 M O V S P R 1 , 1 5 0 , 1 5 0 : R E M P O S I T I O N S P R 1 F O R R E T R O R O C K E T L A U N C H

9 3 M O V S P R 2 , 1 7 4 , 1 5 0 : R E M P O S I T I O N S P R 2 F O R R E T R O R O C K E T L A U N C H

9 5 M O V S P R 1 , 2 7 0 # 1 0 : R E M S P L I T R O C K E T

9 6 M O V S P R 2 , 9 0 # 5 : R E M S P L I T R O C K E T

9 7 F O R I = l T O 1 2 0 0 : N E X T : R E M D E L A Y

9 8 S P R I T E 2 , 0 : R E M T U R N O F F R E T R O R O C K E T ( S P R 2 )

9 9 F O R I = l T O 2 0 5 0 0 : N E X T : R E M D E L A Y

1 0 0 G R A P H I C 0 , 1 : RE M R E T U R N T O T E X T MOD E

SPRITES 275

H ere’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 corner o f the screen.

Line 24 DRAWs and PAINTs the planet.

Line 25 DRAWs the CIRCLES around the planet.

the spacecraft in the top-left

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

Line 38 PAINTs the

Line 40 DRAWs the top window of the space capsule.

space capsule white.

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 o f the retro rocket in the background color.

Line 45 DRAWs lines on the retro rocket portion o f 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) o f 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.

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:

1 0 R E M MOV E S P R I T E E X A M P L E

2 0 F O R 1 = 1 T O 8

3 0 M O V S P R 1 , 1 0 0 , 1 0 0

4 0 N E X T

5 0 F O R 1 = 1 T O 8

6 0 S P R I T E I , 1 , 1 , 1 , 1 , 1 , 0

7 0 M O V S P R 1 , 1 * 3 0 # I

8 0 N E X T

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 o f 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 “ I” 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 o f 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 o f the loop.

SPRITES 277

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 algo rithm. 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 OFFF 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.

H ere’s the listing:

10 REM ADJOINING SPRITE ALGORITHM

20 REM THIS PROGRAM ASSUMES YOUR SPRITES ALREADY EXIST IN STORAGE

30 1=1 :REM INITIALIZE DISTANCE I

35 SCNCLR

50 MOVSPR TO ADJOIN SPR 8

60 DO

SPR 8

SPR 7

100 MOVSPR 7,1 ;90 :REM MOVE SPR 8 I UNITS AT A 90 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 o f 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.

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

35 SCNCLR

40 MOVSPR 8,50,100:REM SET ORIG POSITION OF SPRITE 8

50 MOVSPR 7,5 0 ,1 00 :REM SET ORIG POSITION OF SPRITE 7 TO OVERLAY SPR 8

60 DO

70 SPRITE 8,1,3 :REM ENABLE SPR 8

80 MOVSPR 8,I,-45 :REM MOVE SPR 8 I UNITS AT A 45 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 45 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 o f one coordinate according to the current value o f 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 279

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 o f sprites. The enabling o f 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.

SP R IT E PRO G RA M M IN G SEQUENCE

1. Create the sprite image

Point to the sprite data

Enable (turn on) the sprite

Color the sprite

5. Position the sprite

. Expand the sprite

7. Define sprite display priorities

. Define sprite collision priorities

R EG ISTERS INVOLVED

Sprite Data Storage: 3584-4095 ($0E 00-$0FFF)

This is also programm able. You must change the sprite pointer values.

Sprite Data Pointers: 2040-2047 ($07F8-$07FF), or

8184-8191 ($1FF8-$1FFF) when the bit map screen has been cleared with GRAPHIC 1,1

53269 ($D015) (bits 7 -0 , depending on sprite number)

Standard 53287-53294 ($D 027-$D 02E)

Multi-color 53276 ($D01C), 53285 ($D025), 53286 ($D026)

53248-53264 ($D 000-$D 010)

53271 ($D017) (Y direction), 53277 ($D01D) (X direction)

53275 ($D01B)

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 C l 28 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

280 COMMODORE 128 memory takes up 512 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 o f 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

3 .........................................................

4 .........................................................

5 .........................................................

6 .........................................................

7 .........................................................

8 .........................................................

9 .........................................................

10 .........................................................

13 .........................................................

14 .........................................................

15 .........................................................

16 .........................................................

17 .........................................................

18 .........................................................

19 .........................................................

20 ...................................................

Each Row = 24 bits = 3 bytes

Figure 9-2. Sprite D ata Requirem ents

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 281

$0FFF (4095 Decimal)

]— Sprite

]— Sprite 7

$0F80

]— Sprite

$0F40

]— Sprite 5

$0F00

]— Sprite 4

$0EC0

]— Sprite 3

$0E80

]— Sprite

$0E40

]— Sprite

$0E00 (3584 Decimal)

Figure 9 -3 . M e m o ry Address Ranges fo r S p rite 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 ($1FF8) through 8191 ($1FFF), once the bit map screen is cleared with the GRAPHIC 1,1 command. The default contents of these locations are:

Hexadecimal 38 39 3A 3B 3C 3D 3E 3F

Decimal 56 57 58 59 60 61 62 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 -4 for an illustration.

The way the Commodore 128 automatically points to the correct sprite data is conven ient 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

282 COMMODORE 128

DATA PO IN TER

CONTENTS**

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

Data Pointer = 62

Sprite 7 Data Pointer = 63

** = This applies to video bank 0 only.

START OF

SPRITE DATA

64 = 3584 ($0E00)

64 = 3648 ($0E40)

64 = 3712 ($0E80)

64 = 3776 ($0EC0)

64 = 3840 ($0F00)

64 = 3904 ($0F40)

64 = 3968 ($0F80)

64 = 4032 ($0FC0)

Figure 9-4. S p rite D a ta 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 M onitor as follows:

LDA # % 10100000

STA $D015

To disable the sprite display, clear the bits in the sprite enable register.

SPRITES 283

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.

STA N D A R D 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 C l 28 color codes. Figure 9-5 shows the standard bit-map sprite color registers.

ADDRESS

53287 ($D027)

53288 ($D028)

53289 ($D029)

53290 ($D02A)

53291 ($D02B)

53292 ($D02C)

53293 ($D02D)

53294 ($D02E)

DESCRIPTIO N

SPRITE 0 COLOR REGISTER

SPRITE 1 COLOR REGISTER

SPRITE 2 COLOR REGISTER

SPRITE 3 COLOR REGISTER

SPRITE 4 COLOR REGISTER

SPRITE 5 COLOR REGISTER

SPRITE 6 COLOR REGISTER

SPRITE 7 COLOR 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:

Black

White

Red

3 Cyan

4 Purple

5 Green

Blue

7 Yellow

Orange

9 Brown

1 0

Light Red

1 1

1 2

Dark Gray

Medium Gray

13 Light Green

14 Light Blue

15 Light Gray

Figure 9 -6 . S p rite C o lo r 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

284 COMMODORE 128 is equal to zero, those pixels on the sprite are transparent and the background data from the screen passes through the sprite.

M U LTI-C O LO R SPRITES

Multi-color sprites offer a degree o f freedom in the use of color, but you trade the higher resolution o f 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 # $ 1 0

STA $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:

A D D R E S S

Sprite M ulti-Color Register 0 53285 ($D025)

Sprite M ulti-Color Register 1 53286 ($D026)

T h e color codes are those listed in Figure 9 -6 .

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:

B IT P A IR

0 0

0 1

1 0

1 1

D E S C R IP T IO N

TRANSPARENT (SCREEN COLOR)

SPRITE M ULTI-COLOR REGISTER # 0 (53285) ($D025)

SPRITE COLOR REGISTER

SPRITE M ULTI-COLOR REGISTER # 1 (53286) ($D026)

SPRITES 285

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.

PO S ITIO N IN G 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 o f the sprite position registers as they appear in the C l 28 memory.

L O C A T I O N

D E C IM A L H E X

53256

53257

53258

53259

53260

53261

53262

53263

53264

53248

53249

53250

53251

53252

53253

53254

53255

($D000)

($D001)

($D002)

($D003)

($D004)

($D005)

($D006)

($D007)

($D008)

($D009)

($D00A)

($D00B)

($D00C)

($D00D)

($D00E)

($D00F)

($D010)

D E S C R IP T IO N

SPRITE

X POSITION REGISTER

SPRITE

Y POSITION REGISTER

SPRITE

X POSITION REGISTER

SPRITE 1 Y POSITION REGISTER

SPRITE

X POSITION REGISTER

SPRITE

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

X POSITION REGISTER

SPRITE

Y POSITION REGISTER

SPRITE 7 X POSITION REGISTER

SPRITE 7 Y POSITION REGISTER

SPRITE X MSB REGISTER

Figure 9 -7 . M e m o ry Location o f S p rite 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 coordi nate is taken from the upper-left corner pixel within the sprite. W henever 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 com er of the screen is 343,249. Figure 9-8 shows how the sprite coordinate plane relates to the visible screen.

286 COMMODORE 128

0 ($00) 2 4 ($18)

29 (S10)-------

50 (132)-------

VISIBLE V IE W IN G AREA

296 ($128)

344 ($158)

8 ($08)

- - 50 ($32)

NTSC*

40 COLUM NS

25 ROWS

208

($D 0)-

250

($FA ) — r

I I

320 ($140) 344 ($158)

229

($E5)

250 ($FA)

488 ($1E8) 24 ($18)

‘ N o rth A m e ric a n te le v is io n tra n s m is s io n s ta n d a rd s fo r y o u r h o m e TV.

Figure 9-8. Visible S p rite 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 C l 28 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 o f 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 287

LDA $D010

ORA # $ 8 0

STA $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 $D010

AND # $ 7 F

STA $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.

EX P A N D IN G 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:

Vertical (Y) Sprite Expansion Register

Horizontal (X) Sprite Expansion Register

ADDRESS

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 exam ple, to expand sprite 7 in both directions, perform these m achine language instructions:

LDA # $ 8 0 (% 10000000 = binary notation in the Monitor)

STA $D017

STA $D01D

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 o f 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. Sprite-to-sprite

2. 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 o f S p rite 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 289 feature is preset by the C l 28 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 I 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 “ win dow ” effect. The same window effect occurs when a higher priority sprite with “ holes” passes in front of a lower priority sprite. Even though one sprite has a higher priority, if portions o f that higher priority sprite are transparent, the lower priority sprite or the background display data is allowed to pass through the higher priority sprite.

SPR ITE-TO -D ATA 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. If a bit in this register is set, the sprite passes behind the objects on the screen background. The bit number corre spondence 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 # $ 4 0 (%01000000 = binary rotation in the Monitor)

STA $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.

290 COMMODORE 128

SPRITE-TO-SPRITE COLLISIONS

A sprite-to-sprite collision occurs when an enabled pixel in the foreground o f 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 (IRQ) 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.

PROGRAMMING

THE

O-COLUMN

(8563) CHIP

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 o f home and business computers: The C128 can be regarded as a business machine. The 8563 chip enables the

C l 28 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 o f 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 C l 28 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 o f RAM of its own that

PROGRAMMING THE 80-CQLUMN (8563) CHIP 293 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 inter rupts, 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

TH E

O-COLUMN CHIP

So far, you have learned that the 8563 chip has:

1. Thirty-seven internal registers.

2. 16K of independent RAM (that is not addressable in the C l 28 memory map).

3. An address register ($D600 and a data register $D601) in C l 28 I/O memory.

Figure 10-1 is a summary of the 8563 registers, in the form of a register map:

294 COMMODORE 128

REG

7 6 5 4

BITS

3 2 l 0

HT7

HD7

HT6

HD6

HP7 HP6

VW 3 VW 2

VT7 VT6

—

VD7

VP7

—

VD6

VP6

—

C M l

—

DS15 DS14

DS7 DS6

CP15 CP14

CP7 CP6

LPV7 LPV6

LPH7 LPH6

HT5

HD5

HP5

VW1

VT5

—

HT4

HD4

HT3

HD3

HT2

HD2

HT1 HTO

HD1 HDO

HP4

VD4

VP4

HP3 HP2

VD2

VP2

HP1 HPO

VWO HW3 HW2 HW1 HWO

VT4 VT3 VT2 VT1 VTO

VA4 VA3 VA2 VA1 VAO

VD3

VP3

VD1 VDO

VP1 VPO

VD5

VP5

—

CMO

—

— — — IM1 IMO

CTV4 CTV3 CTV2 CTV1 CTVO

CS4

CE4

CS3

CE3

CS2

CE2

CS1

CE1

CSO

CEO

DS13 DS12 DS11 DS10 DS9 DS8

DS5 DS4 DS3 DS2

CP13 CP12 C P U CP10

DS1 DSO

CP9 CP8

CP5 CP4 CP3 CP2 C PI CPO

LPV5 LPV4 LPV3 LPV2 LPV1 LPVO

LPH5 LPH4 LPH3 LPH2 LPH1 LPHO

H orizontal Total

H orizontal D isplayed

Horizontal Sync Position

Vert/H oriz Sync W idth

Vertical Total

Vertical Total Adjust

Vertical D isplayed

Vertical Sync Position

Interlace M ode

Character Total Vertical

Cursor M ode, Start Scan

Cursor End Scan Line

Display Start Address hi

Display Start Address lo

Cursor Position hi

Cursor Position lo

Light Pen Vertical

Light Pen H orizontal

UA15

UA7

AA15

AA7

COPY

TEXT

UA14

UA6

AA14

AA6

CTH3 CTH2

—

FG3

UA13 UA12 UA11 UA10

UA5

AA13

UA4

AA12

UA3

AA11

UA2

AA10

UA9 UA8

UA1 UAO

AA9 AA8

AA5 AA4 AA3 AA2 AA1 AAO

CTH1 CTHO CDH3 CDH2 CDH1CDHO

— — CDV4 CDV3 CDV2 CDV1CDVO

RVS CBRATE VSS4 VSS3 VSS2 VSS1 VSSO

ATR

FG2

SEM I

FG1

DBL

FGO

HSS3

BG3

HSS2

BG2

HSS1 HSSO

BG1 BGO

A17 AI6

CB15 C B M

AI5

CB13

AI4

RAM

AI3

—

AI2

—

A ll

—

AIO

—

— —

WC7 W C6

DA7 DA6

BA15 BA14

Update Address hi

Update A ddress lo

A ttribute Start Adr hi

A ttribute Start Adr lo

Character Tot(h), Dsp(V)

Character Dsp(v)

Vertical sm ooth scroll

Horizontal sm ooth scroll

Foregnd/Bgnd Color

Address Increment / Row

BA13 BA12 BA11 BA10 BA9 BA8

C haracter Base A ddress

— UL4 UL3 UL2 UL1 ULO

W C5 WC4 W C3 WC2 WC1

Underline scan line wco

W ord Count

DA5 DA4 DA3 DA2 DA I DAO Data

Block Start Address hi

BA7

DEB7

DEE7

—

BA6

DEB6

DEE6

—

BA5 BA4 BA3 BA2 BA1 BAO

DEB5 DEB4 DEB3 DEB2 DEB1 DEBO

DEE5 DEE4 DEE3 DEE2 DEE1 DEEO

— — DRR3 DRR2 DRR1DRRO

H SyNC V SyN C

Block Start A ddress lo

D isplay Enable Begin

Display Enable End

DRAM Refresh rate

Horiz, Vert Sync Polarity

Figure 10 -1 . 8S63 V D C Register Map

The numbers in the left column are the register numbers. When programming the

8563, the registers are referenced by number only, since they have no actual address in the C l 28 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.

PROGRAMMING THE 8Q-COLUMN (8563) CH IP 295

The 16K of 8563 RAM is organized by the Kernal in the following default structure:

TY PE O F M EM ORY 8563 RAM LOCATION

Character Display area (screen) $0000-$07FF

Character Attributes (color) $0800-$0FFF

Character Definitions $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.

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 C l 28 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 o f 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 — — VERO V E R 1V E R 2

$D601 -> data (r/w) : D7 D

D5 D4 D3 D3 D2 DO

Figure 10-2. M apped 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.

296 COMMODORE 128

This is the sequence of steps to perform a read or write operation:

1. Address the registers (by number) or internal RAM location.

2. Check the value of bit 7 until it equals 1 in order for the data to be valid.

3. 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 m ust pass through this register.

FU N DA M EN TAL BACKGROUND

A B O U T 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 THE 8 O-COLUMN (8563) CH IP 297 s b k h b h b h h b a. Visible 8 by 8 pixel character.

b. H o riz o n ta l in te rch a rac ter spacing.

c. V e rtic a l in te rch a rac ter 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, respec tively. The size o f 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 fram e 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.

298 COMMODORE 128

H AS AD KH AD KS FD K H A

H A S A D K H A D K S FD K H A

H AS AD KH AD KS FD K H A

H A S A D K H A D K S FD K H A

H AS AD KH AD KS FD K H A

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 (R l)

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 THE 8Q-COLUMN (8563) CH IP 299

UNDERSTANDING THE 8 O-COLUMN

CHARACTER DISPLAY A N D

ATTRIBUTE MEMORY

As you learned earlier in this chapter, the 8563 has three areas o f 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 o f 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 o f 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:

T Y P E O F M E M O R Y

Display Memory

Character Attributes

Character Definitions

8563 R A M L O C A T IO N

$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 indepen dent 8563 RAM, or a total o f 8K for both character sets. The VIC chip requires a total of 4K o f 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.

300 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 o f 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 o f 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 o f the first (top-left) character in the frame (display memory). The default start address o f 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 THE 8Q-COLUMN (8563) CH IP 301

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 o f 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 m em ory locations to store the contents o f 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 enhance ment 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 o f 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:

B IT

A T T R IB U T E

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.

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 UNDER

LINE 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 fore ground 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 Black

2 White

3 Dark Red

4 Light Cyan

5 Light Purple

6 Dark Green

7 Dark Blue

8 Light Yellow

Dark Purple

Dark Yellow

Light Red

Dark Cyan

Medium Gray

14 Light Green

15 Light Blue

16 Light Gray

B A S IC C o lo r Codes in 80-C olum n O u tp u t

ADDRESSING CHARACTER ATTRIBUTES

The contents of registers 20 (high-byte) and 21 (low-byte) define the address of the start o f 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 80-CQLUMN (8563) CH IP 303

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 o f 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 o f 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 o f 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 o f these topics are covered later in this chapter.

CHARACTER DEFINITIO NS

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 (4-0) of register 9. If the value of the lower five bits of

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 o f 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 o f 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 o f 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 o f 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 o f 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 A N D ) 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 THE 80-CQLUMN (8563) CH IP 305

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. Load (immediate) the X register with the register number that you want to read.

2. Store the contents of the X register (the 8563 register number) into the 8563 address register ($D600).

3. Check the status bit, bit 7 of address register $D600, until it is high (1).

4. If the status bit is low (0), go back and check it again.

5. Otherwise, load the accumulator with the contents of the 8563 data register

$D601. Store the contents of the data register into a C l 28 RAM location (a variable) for future use and print the variable value.

Since 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.

E X A M P LE :

Reading a register (attribute base address)

306 COMMODORE 128

1 0 S Y S D E C ( " 1 8 0 0 " )

2 0 A $ = H E X $ ( P E E K ( 2 5 1 ) )

3 0 B $ = H E X $ ( P E E K ( 2 5 2 ) )

4 0 C $ = R I G H T $ ( A $ , 2 )

5 0 D $ = R I G H T $ ( B ? , 2 )

6 0 E $ = C $ + D $

7 0 F $ = " $ "

8 0 G $ = F $ + E $

9 0 P R I N T " S T A R T A D D R E S S = " ; G $

R E A D Y .

M O N I T O R

P C S R A C X R ' YR S P

F B 0 0 0 0 0 0 0 0 0 i0 0 F 8

0 1 8 0 0

0 1 8 0 2

0 1 8 0 5

0 1 8 0 7

0 1 8 0 8

0 1 8 0 B

0 1 8 0 D

0 1 8 0 E

0 1 8 0 F

0 1 8 1 2

0 1 8 1 5

0 1 8 1 7

0 1 8 1 A

A 2 1 4 L D X # $ 1 4

2 0 O F 1 8 J S R $ 1 8 0 F

8 5

E 8

F B S T A $ F B

I N X

2 0 O F 1 8 J S R $ 1 8 0 F

8 5

6 0

F C S T A $ F C

R T S

0 0 B R K

8 E 0 0 D 6 S T X $ D 6 0 0

2 C 0 0 D 6 B I T $ D 6 0 0

1 0 F B B P L $ 1 8 1 2

AD 0 1 D 6 L D A $ D 6 0 1

6 0 R T S

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) o f 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 bit

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 microproces sor, 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 condition ally branch to instructions that carry out an operation according to the value of this flag.

T hat’s where the third instruction in the above subroutine ($1815) comes into play.

PROGRAMMING THE 8Q-COLUMN (8563) CH IP 307

■ 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 ($D 601) 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

$D601 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 o f 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.

308 COMMODORE 128

WRITING TO AN

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.

H ere’s an algorithm to write to an 8563 register:

1. Load the X register with the register number in which you want to write.

2. Load the accumulator with a value that you are writing to the 8563 register.

3. Store the contents of the X register into the 8563 address register at $D600.

4. Check bit 7, the status bit, of the Address Register until it is high (1).

5. If the status is low (0), loop back and check it again until it is high.

6. When the status bit (7) is high, store the value contained in the accumulator into the 8563 data register ($D601).

H ere’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 w e’ll illustrate how to write to an 8563 register. Later in this chapter, w e’ll take it a step farther to explain how to read and write to the 16K of independent 8563 RAM.

R E A D Y .

0 1 8 0 0

0 1 8 0 2

0 1 8 0 4

0 1 8 0 7

0 1 8 0 8

0 1 8 0 A

0 1 8 0 D

0 1 8 0 E

0 1 8 1 0

0 1 8 1 3

0 1 8 1 5

0 1 8 1 6

0 1 8 1 9

0 1 8 1 B

0 1 8 1 C

0 1 8 1 D

0 1 8 1 E

0 1 8 2 1

0 1 8 2 4

0 1 8 2 6

0 1 8 2 9

0 1 8 2 A

0 1 8 2 B

0 1 8 2 C

0 1 8 2 F

0 1 8 3 2

0 1 8 3 4

0 1 8 3 7

M O N I T O R

P C S R A C X R Y R S P

F B 0 0 0 0 0 0 0 0 0 0 0 F 8

A 2 1 2

A 9 2 0

L D X # $ 1 2

L D A # $ 2 0

2 0 I E 1 8 J S R $ 1 8 1 E

E 8 I N X

A 9 0 0 L D A # $ 0 0

2 0 I E 1 8 J S R $ 1 8 1 E

E A

A 2 1 2

N O P

L D X # $ 1 2

2 0 2 C 1 8 J S R $ 1 8 2 C

8 5 F B S T A $ F B

E 8 I N X

2 0 2 C 1 8 J S R $ 1 8 2 C

8 5

6 0

F C S T A $ F C

R T S

0 0 B R K

8 E 0 0 D 6 S T X $ D 6 0 0

2 C 0 0 D 6 B I T $ D 6 0 0

1 0 F B B P L $ 1 8 2 1

8 D 0 1 D6 S T A $ D 6 0 1

6 0 R T S

E A N O P

8 E 0 0 D 6 S T X $ D 6 0 0

2 C 0 0 D 6 B I T $ D 6 0 0

1 0 F B B P L $ 1 8 2 F

AD 0 1 D 6 L D A $ D 6 0 1

6 0 R T S

PROGRAMMING THE 8 O-COLUMN (8563) CH IP 309

■ 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 $18IE , 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 $D 601. 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 o f 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 $18 IE 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.

W RITING T O 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.

H ere’s the listing:

310 COMMODORE 128

R E A D Y .

M O N I T O R

P C S R A C X R YR S P

F B 0 0 0 0 0 0 0 0 0 0 0 F 8

0 1 8 0 0

0 1 8 0 2

0 1 8 0 4

0 1 8 0 7

0 1 8 0 8

0 1 8 0 B

0 1 8 0 D

0 1 8 0 F

0 1 8 1 1

0 1 8 1 3

0 1 8 1 6

0 1 8 1 7

0 1 8 1 9

0 1 8 1 B

0 1 8 1 D

0 1 8 1 E

0 1 8 1 F

0 1 8 2 1

0 1 8 2 4

0 1 8 2 7

0 1 8 2 9

0 1 8 2 C

A 2 1 2 L D X # $ 1 2

A 9 0 0 L D A # $ 0 0

2 0 2 1 1 8 J S R $ 1 8 2 1

E 8 I N X

2 0 2 1 1 8 J S R $ 1 8 2 1

A 0 0 0

A 9 0 8

L D Y # $ 0 0

L D A # $ 0 8

8 5 F A S T A $ F A

A 9 6 6 L D A # $ 6 6

2 0 I F 1 8 J S R $ 1 8 1 F

C 8

DO F A

C 6 F A

I N Y

B N E $ 1 8 1 3

D E C $ F A

0 0

F 6 B N E $ 1 8 1 3

B R K

0 0 B R K

A 2 I F L D X # $ 1 F

8 E 0 0 D 6 S T X $ D 6 0 0

2 C 0 0 D 6 B I T $ D 6 0 0

1 0 F B B P L $ 1 8 2 4

8 D 0 1 D 6 S T A $ D 6 0 1

6 0 R T S

To execute this program, issue the Go (G) command within the Machine Lan guage 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 F I 800

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 o f pages to fill with screen code 102. The instruction stored at $1811, LDA # $ 6 6 , loads the accumulator with the hexadecimal value ($66) o f decimal screen code 102.

The instruction starting in location $1813, JSR $ 18IF, calls the subroutine located at address $ 18IF. 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 $ 18IE and $1829, the one from the last section. However, there is one key difference. The first instruction of the subroutine stored starting at $ 1 8 IF, LDX

# $ 1 F , loads the X register with the register number 31 ($1F). W hen writing to 8563

PROGRAMMING THE 8 O-COLUMN (8563) CH IP 311

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 SD600

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 automati cally. 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. Remem ber, 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.

312 COMMODORE 128

1 0 0 V I = D E C ( " 1 8 0 0 " ) : V 0 = D E C ( " 1 8 0 C " ) : B A N K 1 5

1 1 0 R E A D A $

1 1 5 DO U N T I L A $ = " E N D "

1 1 6

1 1 7

1 1 8

POKE VI+I,DEC(A$)

= 1 + 1

READ A$

1 1 9

120

LOOP

DATA 8E,00,D6,2C,00,D6,10,FB,AD,01,D6,60

DATA 8E,00,D6,2C,00,D6,10,FB,8D,01,D6,60,END

1 3 0

1 4 0

1 5 0

1 6 0

1 7 0

1 8 0

INPUT"ADDRESS (0-16383)";AD

SYS VO, AD/256, 18

SYS VO, A D A N D 25 5,19

1 9 0

200

210

220

2 3 0

2 4 0

2 5 0

2 6 0

SYS V I ,,31

RREG A

PRINT"THE 8563 MEMORY A T ” ;A D ;" IS";A

INPUT"NEW DATA (0-255) ";A

SYS VO, AD/256, 18

SYS VO, ADAN D 25 5,19

SYS VO, A ,31

LOOP

(install ML routines)

(update location HIGH)

(update location LOW)

(READ memory data)

(update location HIGH)

(update location LOW)

(WRITE memory data)

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

0 1 8 0 0

0 1 8 0 3

0 1 8 0 6

0 1 8 0 8

0 1 8 0 B

0 1 8 0 C

0 1 8 0 F

0 1 8 1 2

0 1 8 1 4

0 1 8 1 7

8 E 0 0 D 6

2 C 0 0 D 6

1 0 F B

AD 0 1 D 6

6 0

8 E 0 0 D 6

2 C 0 0 D 6

1 0 F B

8 D 0 1 D 6

6 0

S T X $ D 6 0 0

B I T $ D 6 0 0

B P L $ 1 8 0 3

L DA $ D 6 0 1

R T S

S T X $ D 6 0 0

B I T S D 6 0 0

B P L $ 1 8 0 F

S T A $ D 6 0 1

R T S

(routine to READ 8563 register in .X)

(routine to W RITE .A register in .X)

BLOCK WRJTE A N D 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. H ere’s the procedure:

1. Place the initial address, where writing in RAM begins, into registers 18

(high byte) and 19 (low byte).

2. Next, load the accumulator with the data you want to place in successive 8563

RAM locations.

3. Load the X register with the number 31 which specifies the data register within the 8563.

4. 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.

5. 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 THE 80-CQLUMN (8563) CHIP 313

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 deter mined 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 CO PY

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).

2. Wait for the Update Status Ready bit to become high (1).

3. 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).

4. Place the number of successive memory locations to copy into register 30.

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 RAH

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

0 0

0 1

1 0

1 1

C H A RA CTERISTIC

Solid cursor

No visible cursor

Slow cursor blink rate (Vi6 the frame rate)

Fast cursor blink rate C

/3 2

the frame rate)

314 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 o f 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 C l 28 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 P O S IT IO N IN G

Register 14 (high byte) and 15 (low byte) determine the position o f 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 o f 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 $0A35 in C128 RAM is the shadow register for the 8563 cursor column and row selection.

BIT-MAPPING THE

80-CQLUMN 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 o f 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 o f the HOME position stores the second eight pixels o f the first eight visual raster rows. The 200 visible VIC screen raster rows are 320 pixels wide. The 200

PROGRAMMING THE 80-CQLUMN (8563) CH IP 315 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 o f 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 CH ARACTER COLUMNS

RASTER

R OW 1 2 3 4 5 6 7 8 9 10 11 . 80

1 $0000 $0001 $0003 $40004$0005 $0006 $0007 $0009 $000A $000B $000C . . . $004F

2 $0050 $0051 $0052 $0053 $0054 $0055 $0056 $0057 .......................................... $009F

3 S 0 0 A 0 ...........................................................................................................................................

4 $00F0 ...........................................................................................................................................

25 $ 3 E 3 0 ............................................................................................................................. $3E7F

Figure 10 -5 . T h e Relationship B etw een 8563 B it M ap D a ta and Screen Pixels

The collection o f 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.

TH E BIT-MAP POINTER

The pointer to the start of the 8563 bit map defaults to the start o f 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.

CO LO R ASSIGNM ENTS

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.

316 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.

T H E 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 o f 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 com mands 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.

H ere’s the program listing as it appears in the Machine Language Monitor. Enter the Monitor and start entering the program at address $1800.

. 0 1 8 0 0

. 0 1 8 0 3

. 0 1 8 0 5

. 0 1 8 0 7

. 0 1 8 0 A

. 0 1 8 0 C

. 0 1 8 0 E

. 0 1 8 1 0

. 0 1 8 1 2

. 0 1 8 1 4

. 0 1 8 1 7

. 0 1 8 1 8

. 0 1 8 1 B

. 0 1 8 1 D

. 0 1 8 1 F

. 0 1 8 2 1

. 0 1 8 2 3

. 0 1 8 2 5

. 0 1 8 2 7

2 0 B 3 1 8 J S R $ 1 8 B 3

A 2 1 9 L D X # $ 1 9

A 9 8 0 L D A # $ 8 0

2 0 7 7 1 8 J S R $ 1 8 7 7

A 9 2 0 L D A # $ 2 0

8 5 F B

A 9 0 0

S T A $ F B

L D A # $ 0 0

8 5 F A

A 2 1 2

S T A

L D X

$ F A

# $ 1 2

2 0 7 7 1 8 J S R $ 1 8 7 7

E 8 I N X

2 0 7 7 1 8 J S R $ 1 8 7 7

A 9 0 0 L D A # $ 0 0

S T A $ B l 8 5 B l

A 9 1 9

8 5 9 B

A 9

8 5 9 C

A 9

0 7

2 7

L D A

S T A

L D A # $ 0 7

S T A

# $ 1 9

$ 9 B

$ 9 C

L D A # $ 2 7

8 5 F E

E A

S T A

N O P

$ F E

A 2 0 0

A l F A

N O P

L D X

L D A

# $ 0 0

( $ F A , X )

2 0 7 5 1 8 J S R $ 1 8 7 5

2 0 8 3 1 8 J S R $ 1 8 8 3

E A

C 6 F E

DO E F

A 5

E A

B l

1 C

N O P

D E C $ F E

B N E $ 1 8 2 D

L D A $ B l

B N E $ 1 8 5 E

N O P

A 2 0 0

A l F A

L D X # $ 0 0

L D A ( $ F A , X )

2 0 7 5 1 8 J S R $ 1 8 7 5

2 0 8 F 1 8 J S R $ 1 8 8 F

2 0 9 B 1 8 J S R $ 1 8 9 B

C 6 9 C

DO D l

A 9 0 1

8 5 B l

D E C $ 9 C

B N E $ 1 8 2 7

L D A

S T A

# $ 0 1

$ B l

4 C 2 7 1 8 J M P $ 1 8 2 7

E A N O P

A 9 0 0

8 5 B l

L D A # $ 0 0

S T A $ B l

A 2 0 0

A l F A

L D X

L D A

# $ 0 0

( $ F A , X )

2 0 7 5 1 8 J S R $ 1 8 7 5

2 0 8 F 1 8 J S R $ 1 8 8 F

2 0 A 9 1 8 J S R $ 1 8 A 9

C 6 9 B D E C $ 9 B

0 0

A 2 I F

B N E $ 1 8 2 3

B R K

L D X # $ 1 F

8 E 0 0 D 6 S T X $ D 6 0 0

2 C 0 0 D 6 B I T $ D 6 0 0

1 0 F B B P L $ 1 8 7 A

8 D 0 1 D 6 S T A $ D 6 0 1

6 0 R T S

1 8

A 5 F A

C L C

L D A $ F A

6 9 0 8

8 5 F A

9 0 0 2

E 6 F B

A D C # $ 0 8

S T A

B C C

I N C

$ F A

$ 1 8 8 E

$ F B

6 0

AO 2 8

A 9 0 0

R T S

L D Y # $ 2 8

L D A # $ 0 0

2 0 7 5 1 8 J S R $ 1 8 7 5

8 8

DO F 8

DE Y

B N E $ 1 8 9 1

6 0

E A

3 8

A 5 F B

R T S

N O P

S E C

L D A $ F B

S B C # $ 0 1

S T A $ F B

E 9 0 1

8 5 F B

A 5 F A

E 9 3 7

8 5 F A

6 0

E 6

F A

0 2

F B

L D A

S B C

S T A

$ F A

# $ 3 7

$ F A

R T S

I N C $ F A

B N E $ 1 8 A F

I N C $ F B

0 1 8 7 1

0 1 8 7 3

0 1 8 7 4

0 1 8 7 5

0 1 8 7 7

0 1 8 7 A

0 1 8 7 D

0 1 8 7 F

0 1 8 8 2

0 1 8 8 3

0 1 8 8 4

0 1 8 8 6

0 1 8 8 8

0 1 8 8 A

0 1 8 8 C

0 1 8 8 E

0 1 8 8 F

0 1 8 9 1

0 1 8 9 3

0 1 8 9 6

0 1 8 9 7

0 1 8 9 9

0 1 8 9 A

0 1 8 9 B

0 1 8 9 C

0 1 8 9 E

0 1 8 A 0

0 1 8 A 2

0 1 8 A 4

0 1 8 A 6

0 1 8 A 8

0 1 8 A 9

0 1 8 A B

0 1 8 A D

0 1 8 2 9

0 1 8 2 B

0 1 8 2 C

0 1 8 2 D

0 1 8 2 F

0 1 8 3 1

0 1 8 3 4

0 1 8 3 7

0 1 8 3 8

0 1 8 3 9

0 1 8 3 A

0 1 8 3 C

0 1 8 3 E

0 1 8 4 0

0 1 8 4 2

0 1 8 4 3

0 1 8 4 4

0 1 8 4 5

0 1 8 4 7

0 1 8 4 9

0 1 8 4 C

0 1 8 4 F

0 1 8 5 2

0 1 8 5 4

0 1 8 5 6

0 1 8 5 8

0 1 8 5 A

0 1 8 5 D

0 1 8 5 E

0 1 8 6 0

0 1 8 6 2

0 1 8 6 4

0 1 8 6 6

0 1 8 6 9

0 1 8 6 C

0 1 8 6 F

PROGRAMMING THE 80-CQLUMN (8563) C H IP 317

318 COMMODORE 128

0 1 8 A F

0 1 8 B 0

0 1 8 B 1

0 1 8 B 2

0 1 8 B 3

0 1 8 B 5

0 1 8 B 7

0 1 8 B 9

0 1 8 B B

0 1 8 B D

0 1 8 B F

0 1 8 C 2

0 1 8 C 3

0 1 8 C 4

0 1 8 C 6

0 1 8 C 8

0 1 8 C B

0 1 8 C C

0 1 8 C D

0 1 8 C E

0 1 8 D 1

0 1 8 D 3

0 1 8 D 6

0 1 8 D 8

0 1 8 DA

0 1 8 D C

0 1 8 D E

6 0

E A

R T S

N O P

E A

N O P

A 9 0 0 L D A # $ 0 0

8 5 F C

A 9 3 F

8 5 F D

A 2 1 9

S T A $ F C

L D A # $ 3 F

S T A $ F D

L D X # $ 1 9

A 9 8 0 L D A # $ 8 0

2 0 7 7 1 8 J S R $ 1 8 7 7

E A N O P

E A

A 9 0 0

A 2 1 2

N O P

L D A

L D X # $ 1 2

2 0 7 7 1 8 J S R $ 1 8 7 7

E 8 I N X

E A

N O P

2 0 7 7 1 8 J S R $ 1 8 7 7

A 9 0 0 L D A # $ 0 0

2 0 7 5 1 8 J S R $ 1 8 7 5

C 6 F C D E C $ F C

DO F 7 B N E $ 1 8 D 1

C 6 F D D E C $ F D

DO F 3 B N E $ 1 8 D l

6 0 R T S

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) jum ps 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 o f 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 o f 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 TH E 8 O-COLUMN (8563) CH IP 319

H ere’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. H ere’s the general scheme you need to follow:

1. Start at the beginning of both the VIC and 8563 bit map locations.

2. Get a VIC bit map byte.

3. Store it in the 8563 bit map.

4. Increment the VIC bit map pointer 8 times (the 8563 pointer increments itself after a write).

5. 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. After each raster row is transferred, subtract 311 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.

7. 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.

320 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 o f the algorithm.

The instructions that perform step 2 o f 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 o f 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 o f 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 o f 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 THE 80-CQLUMN (8563) CHIP 321

VERTICAL SCROLLING

Scrolling in the vertical direction is easier than scrolling horizontally. The general algorithm to scroll vertically is as follows:

1. 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.

2. 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

$28IF in 8563 memory. This moves the characters up one character row. The

“ old” first character row has moved off the top o f the screen and the “ new ” 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.

3. 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.

4. To scroll subsequent scan lines, increment the value o f the lower four bits of register 24. By incrementing this value to 2, the entire screen is smoothly scrolled an additional scan line.

5. 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.

6. 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.

322 COMMODORE 128

0 1 8 0 0

0 1 8 0 2

0 1 8 0 4

0 1 8 0 6

0 1 8 0 9

0 1 8 0 A

0 1 8 0 C

0 1 8 0 E

0 1 8 1 1

0 1 8 1 2

0 1 8 2 A

0 1 8 2 C

0 1 8 2 E

0 1 8 3 0

0 1 8 3 1

0 1 8 3 3

0 1 8 3 5

0 1 8 3 7

0 1 8 3 9

0 1 8 3 C

0 1 8 3 D

0 1 8 3 F

0 1 8 4 2

0 1 8 4 4

0 1 8 4 6

0 1 8 4 8

0 1 8 4 A

0 1 8 4 C

0 1 8 4 E

0 1 8 1 4

0 1 8 1 6

0 1 8 1 7

0 1 8 1 A

0 1 8 1 B

0 1 8 1 C

0 1 8 1 D

0 1 8 1 F

0 1 8 2 1

0 1 8 2 2

0 1 8 2 3

0 1 8 2 5

0 1 8 2 8

0 1 8 5 0

0 1 8 5 2

0 1 8 5 4

0 1 8 5 6

0 1 8 5 9

0 1 8 5 A

0 1 8 5 B

0 1 8 5 C

0 1 8 5 D

0 1 8 5 E

0 1 8 5 F

0 1 8 6 0

0 1 8 6 3

0 1 8 6 6

0 1 8 6 8

0 1 8 6 B

A 2 OC L D X

#$oc

L D A # $ 2 0 A 9 2 0

8 5 F B S T A $ F B

2 0 6 0 1 8 J S R $ 1 8 6 0

E 8 I N X

A 9 0 0

8 5 F A S T A $ F A

2 0 6 0 1 8 J S R $ 1 8 6 0

E A

A 2 1 8

L D A

N O P

L D X

# $ 0 0

# $ 1 8

A 9 0 1

A 8

L D A

T A Y

# $ 0 1

2 0 6 0 1 8 J S R $ 1 8 6 0

E A N O P

C 8

9 8

CO 0 8

DO F 6

E 6

F A

0 2

F B

C P Y

B N E

# $ 0 8

$ 1 8 1 7

E A N O P

E A

A 9 0 0

N O P

L D A # $ 0 0

2 0 6 0 1 8 J S R $ 1 8 6 0

A 0 0 0 L D Y # $ 0 0

I N C $ F A

B N E $ 1 8 3 0

I N C $ F B

C 8

CO 5 0

I N Y

T Y A

I N Y

C P Y # $ 5 0

DO F 5

A 2 OC

A 5 F B

B N E $ 1 8 2 A

L D X

#$oc

L D A $ F B

2 0 6 0 1 8 J S R $ 1 8 6 0

E 8

A 5 F A

I N X

L D A $ F A

2 0 6 0 1 8 J S R $ 1 8 6 0

A 9 0 0 L D A # $ 0 0

8 5 F D S T A $ F D

A 9

8 5

0 0

F C

L D A # $ 0 0

S T A $ F C

E 6

F C

F D

I N C $ F C

B N E $ 1 8 4 A

I N C $ F D

A 5 F D

C 9 A 0

DO F 0

LD A

CMP

$ F D

# $ A 0

B N E $ 1 8 4 6

4 C 1 2 1 8 J M P $ 1 8 1 2

E A N O P

E A

N O P

E A

N O P

8 E 0 0 D 6 S T X $ D 6 0 0

2 C 0 0 D 6 B I T $ D 6 0 0

1 0 F B B P L $ 1 8 6 3

8 D 0 1 D 6 S T A $ D 6 0 1

6 0 R T S

H O R IZ O N T A L 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 THE 80-CQLUMN (8563) CH IP 323 in the 8563 “ w indow .” This means that to display a window of 25 rows o f 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 “ window” of 80 characters, the 8563 must first read the first 80 display memory locations and attributes from the first 132-character row, and then “ skip” 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 “ skip” must be written to R27.

In this case “ 52” is written to R27 at system initialization.

When horizontal scrolling is not used, a “ zero” 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 o f 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 “ left” one character. The first character of each character row will be scrolled “ off” the left side o f 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.

S M O O TH H O R IZ O N T A L 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 o f pixels to the

“ left,” 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 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

“ one” and increasing the contents of R 22(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 R22(7^1). 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 AD

DRESS) and R20/R21 (ATTRIBUTE START ADDRESS) each by one to scroll hori zontally by one character. This sequence will have smooth-scrolled left by one character.

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 (m sb-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 b it” 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 H O R IZ O N T A L T O T A L

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 H O R IZ O N T A L DISPLAYED

The number o f characters displayed on each character row. This number sets the width of the displayed part of the character row.

R2 H O R IZ O N T A L SYNC P O SITIO N

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 o f the text on the CRT screen. This number should be greater than the number in Rl

(horizontal displayed).

R3(3-0) H O R IZ O N T A L SYNC W ID T H

The width of the horizontal sync pulse in characters, plus 1.

R3(7-4) VERTICAL SYNC W ID T H

The width o f the vertical sync pulse in scan lines. This number sets the duration o f 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 8Q-COLUMN (8563) CH IP 325

R4 VERTICAL T O T A L

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 T O T A L 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 o f the frame.

R7 VERTICAL SYNC PO SITIO N

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).

R 8 (l-0 ) INTERLACE MODE C O N TR O L

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 m ode, 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 [R 8 (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( 1—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 [R3(7^4-)] 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 TO T A L , VERTICAL

The number o f 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 o f a character row.

326 COMMODORE 128

R l0(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.

R l0(6-5) CURSOR MODE

The cursor can be programmed to four different modes by programming R 10(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 o f the last (bottom) scan line o f the reverse-video cursor, plus 1.

RI2, RI3 DISPLAY START ADDRESS (H IG H , LOW )

The address o f the first (left) 8 pixels of the top scan line of the frame is defined by R 12 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 o f 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 o f 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 7-4 are background R, G, B and I, respectively. For a frame of i rows o f 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 o f 25 characters high and 80 characters wide, 2000 attributes will be needed.

RI2, RI3 DISPLAY START ADDRESS (H IG H , 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 adja cent 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 (R 12/13) through (R12/13 + 1999).

RI4, RI5 CURSOR P O S ITIO N

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 THE 8Q-COLUMN (8563) CHIP 327

R 10(4—0) and R 1 1(4-0). These registers allow the 8563 to be programmed for a reverse-video “ block” 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 LIG H T PEN VERTICAL, H O R IZ O N T A L

The 8563 supports a light pen function. W hen 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 R 16. 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 UPDATE L O C A T IO N

R31 CPU D A TA

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 R 3 1, which the CPU may then read. During the time that the “ read” 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 o f 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 “ read” 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, R2I A TTRIBUTE START ADDRESS (H IG H , 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

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, H O R IZ O N T A L

This number sets the width of the displayed part o f 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

R 22(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 TO T A L , H O R IZ O N T A L

The number o f pixels (horizontal) in a character, minus 1. This number includes the displayed part o f 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 m ode, the value written to R22(7-4) 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, o f 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 R 9(4-0). If they are equal, then the displayed part o f the character is equal to the total character, and the entire character is displayed, with no vertical intercharacter spacing.

R24(4-0) VERTICAL SM O O TH SCROLL

The sudden scroll o f an entire character row is too abrupt a change for some applica tions. 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 moved ‘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 THE 8Q-COLUMN (8563) CH IP 329

The number in R24(4-0) can be increased, increasing the number of scan lines scrolled, until R24(4—0) equals R 9(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) BLOCK CO PY

R30 W ORD 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 W rite 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 of R18/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.

N O TE: 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) SM O O TH H O R IZ O N T A L 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

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 R 25(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 o f 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 R 22(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 o f a character) plus (the value of

R25(3-0), horizontal smooth scroll)] modulo [(the value of R22(7^1), 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

Scroll 3

Scroll 4

Scroll 5

Scroll

Scroll 7

R22(7-4)

R25(3-6)

R22(3-0)

There are two different versions of the 8563 chip (80-column RGBI) in produc tion, 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 o f 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

PROGRAMMING THE 80-CQLUMN (8563) CH IP 331 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 I/O 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

7 A

$40

$47

This situation does not directly affect software which utilizes the resident C l 28 operating system (Kernal). The Kernal correctly determines which version of the 8563 is present and initializes it accordingly. Software which relies on the Kernal IOINIT routine to accomplish this initialization will not have any problems. Software which performs the initialization itself, or alters the contents o f the affected register, may exhibit the 80-column display anomalies described above, but will otherwise function normally.

R25(5) PIXEL DOUBLE W ID T H

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 “ idle” time spent with RAS and CAS “ hig h .” Note that the contents of the horizontal initialization registers, and the contents of R22(7^1-) 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 o f 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) A TTR IB UTE 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

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 R26(7^1). The background color will still be set by R 26(3-0). If R25(6) is a 1, then attributes will be used normally.

R25(7) MODE SELECT (Text/B it 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

W hen attributes are disabled, the foreground color for all characters is determined by

R26(7-4).

R27 ADDRESS INCREM ENT 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

“ skip” (k-i) bytes on every scan line, because only i bytes are displayed o f a virtual line o f 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 ad dresses, so can address up to 64K bytes of 8563 RAM. The 8563 RAM addresses may

PROGRAMMING THE 80-CQLUMN (8563) CH IP 333 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, A1/A8,

A0/A8

4164: Row/Col = A7/A15, A6/A14, A5/A13, A4/A12, A 3/A 11, A2/A10, A1/A9,

A0/A8

R28(7-5) CHARACTER SET START ADDRESS

The starting location of the character set in display 8563 RAM is determined by

R 28(7-5). These bits form the most significant 3 bits of the 16-bit address used to access character data. If R 9(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 CO PY 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) o f the horizontal blanking interval.

Register R34 is programmed with the number o f characters from the first dis played 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.

334 COMMODORE 128

R36(3-0) 8563 RAM REFRESH/SCAN LINE

The number o f 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.

il

SOUND AND

MUSIC ON THE

COMMODORE 128

336 COMMODORE 128

IN TR O D U C TIO N

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 parame ters 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 form at. The second half describes how to program the SID chip in m achine language.

ENVELOPE

Define a musical instrument envelope where:

ENVELOPE n,[,atk] [,dec] [,sus] [rel][,wf] [,pw] n Envelope number (0-9) atk Attack rate (0-15) dec Decay rate (0-15) sus Sustain (0-15) rel Release rate (0-15) w f Waveform: 0 = triangle

1 = sawtooth

2 = variable pulse (square)

3 = noise

4 = ring modulation pw Pulse width (0-4095)

SO UND A N D MUSIC O N THE COMMODORE 128 337

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 (w f = 2) only.

The Commodore 128 has initialized the following ten envelopes:

N A D s R wf pw

ENVELOPE

ENVELOPE 3,

ENVELOPE 4,

0 , 0 ,

12 ,

9, 0 , o ,

2 , 1536

12 , 0 ,

1 , o ,

2 , 0 , 0 ,

15,

0 , 0

0 , 5, 5, 0 ,

ENVELOPE 5,

ENVELOPE

6 ,

9, 4, 4, 0 , 0

0 ,

9, 2 , 1 ,

9, 0 , 0 ,

2 , 512

ENVELOPE 7,

ENVELOPE

8 ,

0 ,

8 ,

9, 9, 0 ,

9, 4, L

2 , 2048

2 , 512

ENVELOPE 9, 0 , 9, 0 , 0 , 0 instrum ent piano accordion calliope drum flute guitar harpsichord organ trumpet xylophone

FILTER

Define sound (SID chip) filter parameters where:

F IL T E R [fr e q ], [,lp ] [,b p ] [,h p ] [,r e s] freq

Ip b p h p 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.

338 COMMODORE 128

EX A M P LE S :

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 “ V n,O n,T n,U n,X n,elem ents”

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:

Elements:

A ,B ,C ,D ,E ,F ,G

$ w

Sharp

Flat

Whole note

Half note

Quarter note

Eighth note

Sixteenth note

Dotted

Rest

Wait for all voices currently playing to end current measure

The PLAY statement gives you the power to select voice, octave and tune envelope (including ten predefined musical instrument envelopes), the volume and the notes you want to PLAY. All these controls are enclosed in quotes.

All elements except R and M precede the musical notes in a PLAY string.

SO UND A N D MUSIC ON THE COMMODORE 128 339

EX A M P LE S :

PLAY “ V1O4T0U5X0CDEFGAB” Play the notes C ,D ,E ,F ,G ,A and

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

PLAY “ V 305T6U 7X 1#B $A W .C H D Q E IF” Play the notes B-sharp, A-flat, a w hole dotted-C note, a half

D-note, a quarter E-note and an eighth F-note.

SO UN D

Create sound effects and musical notes where:

SOUND v,f,d[,dir][,m ][,s][,w ][,p] v voice (1-3) f frequency d duration (0-32767) value (0-65535) dir step direction (0(up), l(down) or 2(oscillate)) default = 0 m minimum frequency (if sweep is used) (0-65535) default = 0 s step value for sweep (0-32767) default = 0 w waveform (0 = triangle, 1 = sawtooth, 2 = variable, 3 = p pulse width (0-4095) default = 2048 noise) default = 2

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 o f 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 o f 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.

E X A M P LE S:

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 frequen cies starting at 2000 and incrementing upward in units of 100. Each frequency is played for

50 jiffies.

340 COMMODORE 128

SOUND 3,5000,90,2.3000,500,1 This example outputs a range of sounds start ing at a minimum frequency of 3000, through

5000, in increments o f 500. The direction of the sweep is back and forth (oscillating). The selected waveform is sawtooth and the voice selected is 3.

EX A M P LE S :

SOUND 1, 49152, 240, 1, 0, 100, 1. 0

F requency________________

Duration _____________ __________

Sweep Direction ____________________

Minimum Sweep Frequency _____________

Step Value for S w e e p __________________

Waveform ____________________________

Pulse W idth for Variable Width Waveform

1 0 DO

2 0 P R I N T " V C F R E Q D I R

3 0 V = I N T ( R N D ( 1 ) * 3 ) + l

4 0 F = I N T ( R N D ( 1 ) * 6 5 5 3 5 )

5 0 D = I N T ( R N D ( 1 ) * 3 2 7 6 7 )

6 0 D I R = I N T ( R N D ( 1 ) * 3 )

7 0 M = I N T ( R N D ( 1 ) * 6 5 5 3 5 )

8 0 S = I N T ( R N D ( 1 ) * 3 2 7 6 7 )

M I N S V

R E M V O I C E

W F

R E M F R E Q

R E M D U R A T I O N

R E M S T E P D I R

R E M M I N F R E Q

R E M S T E P V A L

9 0 W = I N T { R N D { 1 ) * 4 ) R E M W A V E F O R M

1 0 0 P = I N T ( R N D ( 1 ) * 4 0 9 5 )

1 1 0 P R I N T V ;

1 2 0 S O U N D V ,

R E M P U L S E W

F ; D I R ; M ; S ; W ; P

F , D , D I R , M,

P R I N T : P R I N T

S , W , P

1 3 0 S L E E P 4

1 4 0 S O U N D V ,

1 5 0 L O O P

0 , 0 , D I R , 0 , 0 , W,

PW P R I N T

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.

SO UND A N D MUSIC ON THE COMMODORE 128 341

EX A M P LE S:

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. VOL affects all voices.

E X A M P LE S:

VOL 0 Sets volume to its lowest level.

VOL 15 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.

Ill II III 41 III II I m

3=

M i d d l e

F igure 11-1. Musical S taff

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 SID chip in the Commodore 128. Here are the opening measures o f Invention 13.

Inventio 13

Figure 11-2. P art o f B ach’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 o f 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.

L et’s say the upper staff begins with a string of four eighth notes. In addition, say the lower staff begins with a string o f 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 = 8A 8B 8C 8D

V2 = 16D 16E 16F 16G 16A 16B 16C 16D

F igure 11-3. Synchronizing N o te s fo r T w o Voices

SO UND A N D MUSIC ON THE COMMODORE 128 343

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.

H ere’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!

1 0 R E M I N V E N T I O N 1 3 B A C H

2 0 T E M P O 6

3 0 P L A Y " V 1 O 4 T 7 U 8 X 0 " : R E M V O I C E 1 = 0 R G A N

4 0 P L A Y " V 2 O 4 T 0 U 8 X 0 " : R E M V O I C E 2 = P I A N 0

5 0 R E M F I R S T M E A S U R E

6 0 A $ = " V 2 0 1 I A V 1 0 3 I E V 2 0 2 Q A V 1 0 3 S A 0 4 C 0 3 B E V 2 0 2 I # G V 1 0 3 S B 0 4 D V 1 0 4 I C V 2 0 2 S A E M

7 0 B $ = " V 1 0 4 I E V 2 0 2 S A 0 3 C V 1 0 3 I # G V 2 0 2 S B E V 1 0 4 I E V 2 0 2 S B 0 3 D "

8 0 R E M S E C O N D M E A S U R E

9 0 C $ = " V 2 0 3 I C V 1 0 3 S A E V 2 0 2 I A V 1 0 3 S A 0 4 C V 2 0 2 I # G V 1 0 3 S B E V 2 0 2 I E V 1 0 3 S B 0 4 D "

1 0 0 D $ = " V 1 0 4 I C V 2 0 2 S A E V 1 0 3 I A V 2 0 2 S A 0 3 C V 1 0 4 Q R V 2 0 2 S B E B 0 3 D "

1 1 0 R E M R E M T H I R D M E A S U R E

1 2 0 E $ = " V 2 0 3 I C V 1 0 4 S R E V 2 0 2 I A V 1 0 4 S C E V 2 0 3 I C V 1 0 3 S A 0 4 C V 2 0 2 I A V 1 0 2 S E G "

1 3 0 F S = " V 1 0 3 I F V 2 0 3 S D 0 2 A V 1 0 3 I A V 2 0 2 S F A V 1 0 4 I D V 2 0 2 S D F V 1 0 4 I F V 2 0 1 S A 0 2 C "

1 4 0 RE M F O U R T H M E A S U R E

1 5 0 G $ = " V 2 0 1 I B V 1 0 4 S F D V 2 0 2 I D V 1 0 3 S B 0 4 D V 2 0 2 I G V 1 0 3 S G B V 2 0 2 I B V 1 0 3 S D F "

1 6 0 H $ = " V 1 0 3 I E V 2 0 2 S G E V l 0 3 I G V 2 0 2 S E G V 1 0 4 I C V 2 0 2 S C E V 1 0 4 I E V 2 0 1 S G B "

1 7 0 RE M F I F T H M E A S U R E

1 8 0 I $ = " V 2 0 1 I A V 1 0 4 S E C V 2 0 2 I C V 1 0 3 S A 0 4 C V 1 0 3 I F V 2 0 2 S D F V 1 0 4 I D V 2 0 1 S B 0 2 D "

1 9 0 J $ = " V 2 0 1 I G V 1 0 3 S D B V 2 0 1 I B V 1 0 3 S G B V 1 0 3 I E V 2 0 2 S C E V 1 0 4 I C V 2 0 1 S A 0 2 C "

2 0 0 RE M S I X T H M E A S U R E

2 1 0 K $ = " V 2 0 1 I F V 1 0 4 S C 0 3 A V 2 0 1 I D V 1 0 3 S F A V 1 0 3 I D V 2 0 1 S G 0 2 G V 1 0 3 I B V 2 0 2 S F G "

2 2 0 M $ = " V 2 0 1 1 A V 1 0 4 S C 0 3 A V 2 0 2 1 # F V 1 0 4 S C E V 2 0 1 I B V 1 0 4 S D 0 3 B V 2 0 2 1 # G V I 0 4 S D F "

2 3 0 R E M S E V E N T H M E A S U R E

2 4 0 N $ = " V 2 0 2 I C V 1 0 4 S E C V 2 0 2 1 A V 1 0 4 S E G V 2 0 2 I D V 1 0 4 S F E V 2 0 2 I $ B V 1 0 4 . S D C "

2 5 0 0 $ = " V 2 0 2 I # G V 1 0 3 S B 0 4 C V 2 0 2 I F V 1 0 4 S D E V 2 0 2 I D V 1 0 4 S F D V 2 0 1 I B V 1 0 4 S # G D "

2 6 0 R E M E I G H T H M E A S U R E

2 7 0 P $ = " V 2 0 2 I # G V 1 0 4 S B D V 2 0 2 I A V 1 0 4 S C A V 2 0 2 I D V 1 0 4 S F D V 2 0 2 I E V 1 0 3 S B 0 4 D "

2 8 0 Q $ = " V 2 0 2 I F V 1 0 3 S # G B V 2 0 2 I # D V 1 0 4 S C 0 3 A V 2 0 2 I E V 1 0 3 S E A V 2 0 2 I E V 1 0 3 S B # G "

2 9 0 RE M N I N T H M E A S U R E

3 0 0 R $ = " V 2 0 1 H A V 1 0 3 S A E C E 0 2 Q A "

3 1 0 P L A Y A $ : P L A Y B $ : P L A Y C $ : P L A Y D $ : P L A Y E $

3 2 0 P L A Y F $ : P L A Y G $ : P L A Y H S : P L A Y I 5 : P L A Y J $

3 3 0 P L A Y K $ : P L A Y M $ : P L A Y N $ : P L A Y 0 $ : P L A Y P $

3 4 0 P L A Y Q $ : P L A Y R $

344 COMMODORE 128

Here are two sample sounds programs that you can try:

1 0 R E M S O U N D L O O P S

2 0 R E M C H A N G E S S T E P V A L U E , D I R E C T I O N A N D WA V E F O R M

3 0 S V = 1 0 0 0 : R E M S T E P V A L U E

4 0 DO

5 0 P R I N T : P R I N T " S V = " ; S V : P R I N T

6 0 : D I R = 0 : R E M S W E E P D I R E C T I O N

7 0 : DO

8 0 : W F = 0 : R E M WA V E F O R M

9 0 :

1 0 0 :

1 1 0 :

1 2 0 :

1 3 0 :

S O U N D 1 , 4 0 0 0 0 , 1 2 0 , D I R , 2 0 0 0 , S V , W F

P R I N T " W F = " ; W F ; : W F = W F + 1

L O O P U N T I L W F = 4

P R I N T " D I R = " ; D I R : D I R = D I R + 1

1 4 0 : L O O P U N T I L D I R = 3

1 5 0 S V = S V + 2 0 0 0

1 6 0 L O O P U N T I L S V > 2 0 0 0 0

1 0 R E M C l 2 8 - M O D E J O Y S T I C K M U S I C I A N

2 0 R E M P L A Y S N O T E S C T H R O U G H A I N E A C H O C T A V E

3 0

4 0

R E M

T O

I N C R E A S E T H E N O T E V A L U E ,

D E C R E A S E N O T E V A L U E ,

P U S H J O Y S T I C K F O R WA R D

P U L L B A C K

5 0 R E M T O I N C R E A S E O C T A V E V A L U E , P U S H J O Y S T I C K T O T H E R I G H T

6 0 R E M T O D E C R E A S E O C T A V E V A L U E , P U S H J O Y S T I C K T O T H E

7 0 A $ ( 1 ) = " C " : A $ ( 2 ) = " D " : A $ ( 3 ) = " E " : A $ ( 4 ) = " F

L E F T

A $ ( 5 ) = " G " : A $ ( 6 ) = " A " : A $ ( 7 ) = " E

8 0 Z = 4 : R E M I N I T I A L I Z E T O F O U R T H O C T A V E

9 0 S C N C L R : R E M C L E A R S C R E E N

1 0 0 I N P U T " E N T E R V O I C E 1 I N S T R U M E N T N U M B E R ( 0 - 9 ) " ; N $

1 1 0 I N P U T " E N T E R V O I C E 2 I N S T R U M E N T N U M B E R ( 0 - 9 ) " ; 0 $

1 2 0 I N P U T " E N T E R V O I C E 3 I N S T R U M E N T N U M B E R ( 0 - 9 ) " ; P $

1 3 0 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 "

1 4 0 P R I N T : P R I N T " ~ " : P R I N T

1 5 0 P R I N T " D E C R E A S E O C T A V E < — — > I N C R E A S E O C T A V E "

1 6 0 P R I N T : P R I N T " V " : P R I N T

I N C R E A S E N O T E ”

1 7 0 P R I N T : P R I N T " D E C R E A S E N O T E " : P R I N T

1 8 0 P R I N T : P R I N T " T O I N C R E A S E O R D E C R E A S E N O T E O R O C T A V E " ;

1 9 0 P R I N T : P R I N T " W I T H O U T P L A Y I N G N O T E S , H O L D DOWN T H E " ;

2 0 0 P R I N T " F I R E B U T T O N W H I L E P O S I T I O N I N G T H E " ;

2 1 0 P R I N T : P R I N T " J O Y S T I C K I N T H E A P P R O P R I A T E D I R E C T I O N " ;

2 2 0 Q $ = " V 1 " + " T " + N $ : R E M V O I C E 1 I N S T R U M E N T

2 3 0 R $ = " V 2 " + " T " + 0 $ : R E M V O I C E 2 I N S T R U M E N T

2 4 0 S $ = " V 3 " + " T " + P $ : R E M V O I C E 3 I N S T R U M E N T

2 5 0 DO

2 6 0

2 7 0

2 8 0

2 9 0

A = J O Y ( l ) : R E M G E T J O Y V A L U E

I F A = 0 T H E N L O O P : R E M I F Z E R O L O O P A N D G E T A N O T H E R

B = A : R E M S T O R E T H E V A L U E F O R L A T E R C H E C K I N G

3 0 0

3 1 0

3 2 0

Z $ = " O " + S T R $ ( Z ) : R E M U P D A T E O C T A V E

T $ = Z $ + Q $ + A $ ( I ) : R E M C O N S T R U C T V O I C E 1 P L A Y

U $ = Z S + R $ + A $ ( I ) : R E M C O N S T R U C T

V $ = Z $ + S $ + A $ ( I ) : R E M C O N S T R U C T

V O I C E 2 P L A Y

V O I C E 3 P L A Y

S T R I N G

S T R I N G 3 3 0

3 4 0

3 5 0

3 6 0

3 7 0

3 8 0

I F ( A A N D 1 2 8 ) = 1 2 8 T H E N 4 0 0

P L A Y T $ : R E M P L A Y V O I C E 1

P L A Y U $ : R E M P L A Y V O I C E 2

P L A Y V $ : R E M P L A Y V O I C E 3

3 9 0

4 0 0

4 1 0

4 2 0

I F ( A = l

I F ( A = 5

O R A = 1 2 9 )

O R A = 1 3 3 )

A N D ( I < 8 ) T H E N I = I + 1 : R E M I N C R E M E N T N O T E V A L U E

A N D ( I > 0 ) T H E N 1 = 1 - 1

I F ( A = 3 O R A = 1 3 1 ) A N D ( Z < 6 ) T H E N

4 3 0 I F ( A = 7 O R A - 1 3 5 )

4 4 0

4 5 0 L O O P W H I L E A = B

4 6 0 L O O P : R E M DO I T A G A I N

A N D ( Z > 0 ) T H E N

A = J O Y ( l ) : R E M G E T N E X T J O Y V A L U E

: R E M D E C R E M E N T N O T E V A L U E

Z = Z + 1 : R E M I N C R E M E N T O C T A V E

Z = Z - 1 : R E M D E C R E M E N T O C T A V E

SO UND A N D MUSIC O N THE COMMODORE 128 345

SOUND AND MUSIC

IN C l28 MODE

BAC KG R O U N D :

TH E CHARACTERISTICS OF SO UND

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 11-4).

Figure 11-4. Sine W ave

The sound wave moves (oscillates) at a particular rate (frequency) which deter mines 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 of the 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 I l-S . Frequency and Harm onics

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.

346 COMMODORE 128

— PULSE W ID TH —

Figure 11-6. Sound W a v e fo rm Types

SO UND A N D MUSIC O N THE COMMODORE 128 347

The volume of a sound changes throughout the duration o f 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 proper ties o f the volume of the sound.

Figure 11-7. A D S R Phases

One of the most powerful Commodore 128 sound statements— the one that controls the ADSR and waveform— is 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 o f the note. For example, the envelope for a guitar note has a different ADSR and waveform than that for a flute.

W a v efo rm The type of sound wave created by the combination of accompanying musical harmonics o f 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 W id th The length o f 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 settings— this is already done for you. All you have to do is specify the envelope number. The rest of the parameters are chosen

348 COMMODORE 128 automatically by the Commodore 128. Here are the preselected envelopes for different types of musical instruments:

ENVELOPE

NUMBER INSTRUM ENT

Piano

Accordion

Calliope

Drum

Flute

Guitar

Harpsichord

Organ

Trumpet

Xylophone

1 2

ATTACK DECAY SUSTAIN RELEASE W AVEFORM

1 2

1536

512

2048

512

Figure 11-8. D e fa u lt P aram eters fo r E N V E L O P E S ta te m e n t

TH E SID FILTER

Once you have selected the ENVELOPE, ADSR, VOLume and TEM PO, 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 o f Sound, 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 o f 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.

SO UND A N D MUSIC ON TH E COMMODORE 128 349

Figure 11-9. Low-pass F ilte r

Conversely, the high-pass filter allows all the frequencies above the cutoff fre quency 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.

Figure 11-10. High-pass F ilte r

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.

350 COMMODORE 128

Figure 11-11. Band-pass F ilte r

A D V A N C E D FILTERING

Each o f 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.

Figure 11-12. Notch Reject F ilte r

CUTOFF

FREQUENCY

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.

SO UND AN D MUSIC ON THE COMMODORE 128 351

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 “ movies” complete with sound tracks.

A U D IO IN P U T T O 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) instrument— you can actually “ ja m ” with the C l 28.

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.

H ere’s the pinout:

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.

352 COMMODORE 128

TY PE

LUM/SYNC

GND

AUDIO OUT

VIDEO OUT

AUDIO IN

COLOR OUT

NOTE

Luminance/SYNC output

Composite signal output

Chroma signal output

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 C l28 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, TV— and don’t forget the electric guitar!

PROGRAMMING THE SID CHIP

IN M AC H IN E 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. H ere’s an abbreviated SID memory map, which is exactly the same in both C128 and C64 modes.

SO UND A N D MUSIC O N THE COMMODORE 128 353

_l _______ I ____________ I ____________ l —I ___________ I

Z Z Z Z Z Z o o o o o o z z z z z z z o o o o o o o tr <r cc a: cc cc

5 5 5 5 5 $ cc cc cc tr cc cc cc

5 5 5 cc a: a: a: cc a: cc

5 5 5 5 5 5 z z z z cc cc cc cc

5 5 5 5

Q Q a Q a: cc cc cc o

3 f H

O <

® O o a:

IL CL CL O < C/)

5 5

O < ui

UJ f 1 —1

0 2 ?

o <

Z H c/j o < w

_ i Q £

0 2 ?

I _J x != < H

5 5 o i- o a. cl o < co i -J x

: O O

J 5

IS S 03 ® < CO O o >- o

«- — r - o O O O

0 0 0

< j O O O O O O O 0 0 0 0 0 0 0 0 0

— — o o o o »-

0 0 0 0 0 0 0 0

0 0 " - N O

N N N N

354 COMMODORE 128

Here’s the general algorithm to output sound from the SID chip in voice 1.

1. Clear the sound chip (For $D400-$D41C)

2. Select ATTACK and DECAY for each voice ($D405)vl

3. Select SUSTAIN and release for each voice ($D406) vl

4. Select a waveform ($D404 for v l)

5. Set the volume ($D 418)

6. 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:

Fn = F out/.06097

Round off the (Fn) frequency with the integer function and divide the result into the low byte and high byte.

In decimal:

F h i

= Fn/256 is the high byte and:

Flow = Fn -(2 5 6 * Fhi) is the low byte

To get a feel for the ranges of notes, experiment with the SOUND command in

BASIC.

7. Place the high byte in Frequency Control Register (in $D401) for the appropriate voice.

8. Place the low byte in the (low byte) frequency control register for the appropriate voice ($D400).

9. Initiate (GATE) the note or tone. Gating means to start the ATTACK,

DECAY and SUSTAIN cycle of the tone. Set bit 0 of $D404 (V I), $D40B(V2) and $D412(V3), respectively.

10. Leave bit 0 set for the duration you wish to play the note or tone.

11. Clear the GATE bit.

The durations of the standard musical notes are as follows:

NOTE TY PE DURATION

'/■ 6

128

DOTTED 'A

*/4 + '/ . 6

DOTTED >/4

'/2

256

384

512

640

768

1024

'/2 + ‘/l6 1152

Vl + Vs 1280

DOTTED Vi

WHOLE

1536

2048

SO UND A N D MUSIC O N THE COMMODORE 128 355

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 o f equal proportion, next. For example, one staff has an eighth note. The staff below it has two sixteenth notes. Play the note o f 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 o f 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.

H ere’s the program listing as it appears in the Machine Language Monitor:

READY.

MONI TOR

PC SR AC XR YR S P

; F B O O O 0 0 0 0 0 0 0 0 F 8

. 0 1 8 0 0

. 0 1 8 0 2

. 0 1 8 0 3

. 0 1 8 0 6

. 0 1 8 0 7

. 0 1 8 0 9

. 0 1 8 0 B

. 0 1 8 0 C

. 0 1 8 0 D

. 0 1 8 0 E

. 0 1 8 1 0

. 0 1 8 1 2

. 0 1 8 1 5

. 0 1 8 1 6

. 0 1 8 1 7

. 0 1 8 1 8

. 0 1 8 1 A

. 0 1 8 1 C

. 0 1 8 1 F

. 0 1 8 2 0

. 0 1 8 2 1

. 0 1 8 2 2

. 0 1 8 2 3

. 0 1 8 2 5

. 0 1 8 2 7

. 0 1 8 2 A

. 0 1 8 2 B

. 0 1 8 2 C

. 0 1 8 2 D

. 0 1 8 2 F

. 0 1 8 3 1

A 2 0 0 # $ 0 0

8 A T X A

9 D 0 0 D4 S T A $ D 4 0 0 , X

E 8

E 0 1 9

DO F 8

L D X

I N X

C P X # $ 1 9

B N E $ 1 8 0 3

E A N O P

E A

A 2 0 5

A 9 F 5

N O P

LD X # $ 0 5

L D A # $ F 5

9 D 0 0 D4 S T A $ D 4 0 0 , X

E A N O P

E A

A 2 0 6

N O P

L D X # $ 0 6

A 9 A 3 L D A # $ A 3

9 D 0 0 D4 S T A $ D 4 0 0 , X

E A NO P

E A N O P

E A

N O P

A 2 1 8

A 9 O F

L D X # $ 1 8

LD A # $ OF

9 D 0 0 D4 S T A $ D 4 0 0 , X

E A N O P

E A

A 0 0 0

N O P

L D Y # $ 0 0

A 2 0 0 L D X # $ 0 0

B 9 9 0 1 8 L D A $ 1 8 9 0 , Y

356 COMMODORE 128

0 1 8 4 5

0 1 8 4 8

0 1 8 4 A

0 1 8 4 B

0 1 8 4 E

0 1 8 5 0

0 1 8 5 2

0 1 8 5 4

0 1 8 5 7

0 1 8 5 8

0 1 8 5 9

0 1 8 5 A

0 1 8 5 B

0 1 8 5 D

0 1 8 5 F

0 1 8 6 1

0 1 8 6 3

0 1 8 6 4

0 1 8 6 6

0 1 8 6 8

0 1 8 6 B

0 1 8 3 4

0 1 8 3 6

0 1 8 3 9

0 1 8 3 A

0 1 8 3 B

0 1 8 3 E

0 1 8 4 1

0 1 8 4 2

0 1 8 4 3

0 1 8 4 4

0 1 8 6 C

0 1 8 6 D

0 1 8 6 E

0 1 8 6 F

0 1 8 7 2

0 1 8 7 3

0 1 8 7 4

0 1 8 7 5

0 1 8 7 7

0 1 8 7 9

0 1 8 7 C

F 0 3 F B E Q $ 1 8 7 5

9 D 0 0 D 4 S T A $ D 4 0 0 , X

E 8

C 8

I N X

I N Y

B 9 9 0 1 8 L D A $ 1 8 9 0 , Y

9 D 0 0 D 4 S T A $ D 4 0 0 , X

E A N O P

E A

C 8

N O P

I N Y

B 9 9 0 1 8 L D A $ 1 8 9 0 , Y

8 5 F A S T A $ F A

C 8 I N Y

B 9 9 0 1 8 L D A $ 1 8 9 0 , Y

8 5

A 2

A 9 2 1 L D A # $ 2 1

9 D 0 0 D 4 S T A $ D 4 0 0 , X

E A

F B

0 4

S T A $ F B

L D X # $ 0 4

N O P

E A N O P

E A

C 6

F A

F C

F B

N O P

D E C $ F A

B N E $ 1 8 5 B

D E C $ F B

DO F 8

E A

B N E

N O P

$ 1 8 5 B

A 2 0 4

A 9 2 0

LD X # $ 0 4

L D A # $ 2 0

9 D 0 0 D 4 S T A $ D 4 0 0 , X

E A N O P

E A

C 8

N O P

I N Y

4 C 2 F 1 8 J M P $ 1 8 2 F

E A N O P

E A

A 2 1 8

N O P

L D X # $ 1 8

A 9 0 0 L D A # $ 0 0

9 D 0 0 D4 S T A $ D 4 0 0 , X

0 0 BRK

> 0 1 8 9 0 I E 1 9 8 0 0 0 1 C 4 1 8 0 0 0

> 0 1 8 9 8 I E 1 9 8 0 0 0 1 C 4 1 8 0 0 0

> 0 1 8 A 0 I E 1 9 8 0 0 0 1 C 4 1 0 0 0 0

> 0 1 8 A 8 I E 1 9 8 0 0 0 1 C 4 1 8 0 0 0

> 0 1 8 B 0 I E 1 9 8 0 0 0 I E 1 9 8 0 0 0

> 0 1 8 B 8 I E 1 9 8 0 0 1 I E 1 9 8 0 0 1

> 0 1 8 C 0 I E 1 9 8 0 0 4 1 C 1 9 8 0 0 4

> 0 1 8 C 8 I E 1 9 8 0 0 4 1 C 4 1 8 0 0 0

> 0 1 8 D 0 I E 1 9 8 0 0 0 1 C 4 1 0 0 0 0

> 0 1 8 D 8 2 1 2 1 0 0 0 0 0 0 0 0 0 0 0 0

> 0 1 8 E 0 0 D 5 4 0 8 DO D 7 AD 7 B 0 8

> 0 1 8 E 8 8 D 6 C 0 8 AD 7 C 0 8 8 D 6 D

Enter the program in memory with the Machine Language Monitor and save it.

Run the program with the following command:

SOUND AN D MUSIC ON THE COMMODORE 128 357

G F I 800

The program plays a series of notes in a single voice (voice 1). H ere’s a line by line description o f the instructions in the program.

The instructions stored in locations $1800 through $180A clear the SID 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 $ 1 8 IE 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 o f 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 o f 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 357. The low-byte duration is stored in zero page location $FA. The Y

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 o f location $D404 is the gate bit for voice 1. To gate a bit, set bit 0 and also set the bit for the desired wave form 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.

H ere’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 jum ps 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 o f zero is encountered. W hen 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 o f the musical notes. Use this program as a basis for your own full-featured musical program.

S Y N C H R O N IZA TIO N A N D

RING M O D U LA TIO N

The 6581 SID chip lets you create more complex harmonic structures through synchro nization or ring modulation of two voices.

The process of synchronization is basically a logical ANDing o f two wave forms.

When either is zero, the output is zero.

H ere’s a synchronization algorithm:

SO UND A N D MUSIC O N THE COMMODORE 128 359

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 volum e 15.

Set start triangle, sync waveform control for voice 1.

Timing loop.

Clear triangle, sync waveform control for voice 1.

W ait, then turn off volume.

The synchronization feature is enabled (turned on) in step 6, where bits 0, 1, and 4 o f register SD404 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 o f register $D404 in step 6 of the algorithm) replaces the triangular output of oscillator 1 with a “ ring m odulated” 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.

VO ICE 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:

Fou« = (F„ X FcIk/ 16777216) Hz

Where Fn is the 16-bit number in the Frequency registers and Fc!k is the system clock applied to the 02 input (pin 6). For a standard 1.0-MHz clock, the frequency is given by:

Fout = (Fn 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:

360 COMMODORE 128

PWout = (PW n/40.95) %

W here PWn 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 o f 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.

C O N TR O L REGISTER (Register 04)

This register contains eight control bits which select various options on Oscillator 1.

G A T E (B it 0): The GATE bit controls the Envelope Generator for Voice 1. W hen 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 RE

LEASE 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 (B it I): The SYNC bit, when set to a one, synchronizes the fundamental frequency of Oscillator 1 with the fundamental frequency of Oscillator 3, produc ing “ Hard Sync” 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. In 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 IN G M O D (B it 2): The RING MOD bit, when set to a one, replaces the Triangle waveform output of Oscillator 1 with a “ Ring M odulated” 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 (B it 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, allow ing the generation of highly complex waveforms under real-time software control.

(B it 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.

(B it 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.

SO UND A N D MUSIC ON THE COMMODORE 128 361

(B it 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 “ phas ing” effect which adds a sense of motion to the sound. Rapidly jum ping between different pulse widths can produce interesting harmonic sequences.

N O IS E (B it 7): When set to a one, the Noise output waveform o f 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.

A T T A C K /D E C A Y (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.

362 COMMODORE 128

Bits 0 -3 (RLS0-RLS3) select 1 of 16 RELEASE rates for the Envelope Genera tor. 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.

N O T E : The cycling of the Envelope Generator can be altered at any point via the Gate bit. The Envelope Generator can be gated and re leased 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)

(

)

(

)

(7)

(

)

(9)

(A)

(B)

(

)

(

)

(3)

(4)

(5)

(C)

(D)

(E)

(F)

1 0

1 1

1 2

A T T A C K R A T E

(TIM E/CYCLE)

16 ms

24 ms

38 ms

56 ms

6 8

80 ms

1 0 0

250 ms

500 ms

800 ms

3 s

5 s

D E C A Y / R E L E A S E R A T E

TIM E/CYCLE)

24 ms

48 ms

72 ms

114 ms

168 ms

204 ms

240 ms

300 ms

750 ms

1.5 s

2.4 s

3 s

9 s

15 s

24 s

N O T E : 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 o f time per cycle. For example, given an ATTACK value o f 2, the ATTACK cycle would take 16 ms to rise from zero to peak am pli tude. 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

SO UND AN D MUSIC ON TH E COMMODORE 128 363

VO IC E 2

Registers $07-$0D control Voice 2 and are functionally identical to registers $00-$06 with these exceptions:

1. When selected, SYNC synchronizes Oscillator 2 with Oscillator 1.

2. When selected, RING MOD replaces the Triangle output of Oscillator 2 with the ring modulated combination o f Oscillators 2 and 1.

VO IC E 3

Registers $0E-$14 control Voice 3 and are functionally identical to registers $00-$06 with these exceptions:

1. When selected, SYNC synchronizes Oscillator 3 with Oscillator 2.

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: fre quency, 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.

W hen 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 $15,$16)

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:

F IL T I ( B i t 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.

364 COMMODORE 128

F IL T 2 (B it I): Same as bit 0 for Voice 2.

F IL T 3 (B it 2): Same as bit 0 for Voice 3.

F IL T E X (B it 3): Same as bit 0 for External audio input (pin 26).

M O D E/VO L (REGISTER $18)

Bits 4 -7 o f this register select various Filter mode and output options:

LP (B it 4): W hen 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 o f 12 dB/Octave. The Low-Pass mode produces full-bodied sounds.

BP (B it 5): Same as bit 4 for the Bandpass output. All frequency components above and below the Cutoff are attenuated at a rate o f 6 dB/Octave. The Bandpass mode produces thin, open sounds.

H P (B it 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 O F F (B it 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.

N O T E : 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 Fre quency in real-time.

Bits 0 -3 (VOLO-VOL3) select 1 o f 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.

SO UND A N D MUSIC ON THE COMMODORE 128 365

MISCELLANEOUS

P O T X (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.

P O T Y (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 jum p 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; how ever, 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 o f another oscillator. Synthesizer “ Sample and H old” 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 o f 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 o f the

Voice 3 Envelope Generator. This output can be added to the Filter Frequency to produce harmonic envelopes, W AH-WAH, and similar effects. “ Phaser” sounds can be created by adding this output to the frequency control registers o f 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.

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 of each semitone is exactly the 12th root of 2 ( ^ 2 ) times the frequency of the previous semitone. The table is based on a 02 clock o f 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 o f 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 te# , 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.

SO UND A N D MUSIC O N THE COMMODORE 128 367

Figure 11-15. Music N o te Values

M U S I C A L N O T E

NOTE OCTAVE

F - l

F # - l

G — 1

G # - l

A - l

A # - l

B - l

C -2

# - 2

D -2

# - 2

E -2

F -2

F # - 2

G -2

G # - 2

A -2

A # - 2

B -2

€ - 3

C # - 3

D -3

D # - 3

E -3

F -3

F # - 3

G -3

G # - 3

G # - 0

A -0

A # - 0

- 0

C - l

C # - l

D - l

D # - l

E - l

C -0

C # - 0

D -0

D # - 0

E -0

F -0

F # - 0

G -0

1 1

2 0

1 0

2 1

2 2

O S C I L L A T O R F R E Q

DECIM AL HI LOW

268

284

301

318

337

358

379

401

425

451

477

506

536

568

602

637

675

716

758

803

851

902

955

1 0 1 2

1072

1136

1204

1275

1351

1432

1517

1607

1703

1804

1911

2025

2145

2273

2408

2551

2703

2864

3034

3215

3406

1 1 2

180

251

152

237

167

1 2

119

233

225

104

247

143

218

143

2 2 1

250

125

163

204

246

134

187

244

1 0 2

123

145

169

195

1 2

1 1

1 2

1 0

1 1

368 COMMODORE 128

M U S I C A L N O T E

NOTE OCTAVE

A -3

A # - 3

B -3

C -4

C # - 4

D -4

D # - 4

E -4

1 - 4

F # - 4

G^4

G # - 4

A -4

A # - 4

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

- 6

# - 6

- 6 l

) # - 6

- 6

# - 6

- 6

# - 6

- 6

# - 6

- 6

C -7

C # - 7

D -7

D # - 7

E -7

1 1 2

113

114

115

116

1 0 2

103

104

105

106

107

6 6

6 8

8 6

8 8

1 0 0

1 0 1

Figure 11—15. Music N o te Values (continued)

O S C I L L A T O R F R E Q

DECIM AL HI LOW

239

2 1 0

223

165

135

134

162

223

193

107

190

195

209

239

181

156

1 2

191

125

131

214

1 2 1

115

199

124

151

139

126

250

1 0 0

106

1 1 2

119

126

134

142

150

159

168

2 2

2 1

16203

17167

18188

19269

20415

21629

22915

24278

25721

27251

28871

30588

32407

34334

5728

6069

6430

6812

7217

7647

8101

8583

9094

3608

3823

4050

4291

4547

4817

5103

5407

9634

10207

10814

11457

12139

12860

13625

14435

15294

36376

38539

40830

43258

SO UND A N D MUSIC O N THE COMMODORE 128 369

M U S I C A L N O T E

NOTE

117

118

119

1 2 0

1 2 1

1 2 2

123

OCTAVE

F -7

F # - 7

G -7

G # - 7

A -7

A # - 7

B -7

O S C I L L A T O R F R E Q

DECIM AL HI LOW

45830

48556

51443

54502

57743

61176

64814

179

189

2 0 0

2 1 2

225

238

253

172

243

230

143

248

Figure 11-15. Music N o te Values (continued)

LO CA TION

54293

54294

54295

54296

F I L T E R S E T T I N G S

CONTENTS

Low cutoff frequency (0-7)

High cutoff frequency (0-255)

Resonance (bits 4-7)

Filter voice 3 (bit 2)

Filter voice 2 (bit 1)

Filter voice 1 (bit 0)

High pass (bit

)

Bandpass (bit 5)

Low pass (bit 4)

Volume (bits 0-3)

Figure 11-16. F ilte r Settings

r n n n

12____

INPUT/OUTPUT

GUIDE

372 COMMODORE 128

IN T R O D U C TIO N

Besides being a calculator and a data manipulator, the Commodore 128 is a communica tor. 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 o f communicating with various devices.

IN P U T /O U T P U T PORTS

M ost o f 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 o f 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.

FO RM ATTING 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 o f 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

IN P U T /O U T P U T GUIDE 373 you change disks— so, for your own protection, try to assign each disk a unique code.

The format command for C l 28 mode is as follows:

HEADER “ disk nam e” , lxy,DO,ON U8

For C64 or C l28 modes, use:

OPEN 15,8,15, “ NO:diskname, xy”

Note that xy is any two-digit code you select, such as 01, 45, W 3, 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 nam e” ,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 again— otherwise everything saved on it will be erased. To simply “ w ipe” 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 clean— a 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 storing programs on a disk does not remove the program from the computer. It simply “ copies” the program or file from the computer onto the disk in the disk drive. Nothing is lost in the process. BASIC programs are saved to a formatted disk with the following commands:

C128 or C64 SAVE“ program nam e” ,8

C128 only DSAVE“ program nam e”

DSAVE“ program nam e” ,DO,U9

(if the drive is device number 9).

In C l 28 mode, machine language programs or binary files can be saved through these BASIC commands:

BSAVE“ filenam e” ,Bb,Ps TO Pe or BSAVE1 ‘filenam e” ,D 0,U 9,B b,Ps TO Pe

(if the drive is device number 9).

374 COMMODORE 128 m

In these formats:

“ b ” is the memory bank number (0 through 15)

“ s” is the starting address

“ e ” is the ending address

E X A M P LE :

BSAVE“ filenam e” ,B2,P3584 TO P4096

This saves the binary file named “ filenam 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 “ filenam 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: DS A VE“ © program nam e”

In BASIC 2.0: SAVE“ @ 0:program nam e” ,8

The @ symbol tells the computer to store this program in place o f 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 V E R IFY 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:

D VERIFY ” filenam e” or

D VERIFY ‘ ‘ filename ” , DO, 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 ‘ ‘ fi lename ” , 8 or VERIFY “ filename” ,8,1

IN P U T /O U T P U T GUIDE 375

(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.

TH E 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.

O f 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:

DIRECTORY or CATALOG or CATALOG D0,U9 or 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:

LO 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 o f the LOAD command.

In BASIC 7.0, use the following command:

DLOAD “ filename” or DLOAD“ filenam e” ,DO,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:

BLO AD ‘ ‘ filename ” , B b, Ps

376 COMMODORE 128 or BLO A D “ filenam e” ,DO,U9,Bb,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“ filenam e” ,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 A N D STORING FILES

A file is a series o f 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, 12,“ 0:NAME, S ,W ”

IN P U T /O U T P U T GUIDE 377 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 REM STORE DATA

11 REM NOTE PROGRAM STOPS WHEN YOU RESPOND WITH “ EN D ” .

20 OPEN 5 ,8 ,5 ,“ EX A M PLE,S,W ”

25 DO

30 INPUT “ NAME OF A FRIEND” ;N$

40 PR IN T #5,N $

50 IF N $ = “ EN D ’T H E N CLOSE 5:END

60 LOOP

N O T E : 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 com mands. 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 P R IN T # 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 marker— the word

“ end” at the end of the file. Line 50 closes the file after all data has been written.

H ere’s a program that reads the data from the sequential file you just created:

10 REM RETRIEVE FILES

20 OPEN 6 ,8 ,6 ,“ EX A M PLE,S.R”

25 DO

30 IN PU T #6,L $

40 IF L$ = “ EN D ’T H E N CLOSE6:END

50 PRINT L$

60 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

IN P U T # 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:

378 COMMODORE 128

A P P E N D # 7 ,“ EXAM PLE”

This command opens the file called “ EXAM PLE.” Any data sent to it in a PR IN T #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

D C LO SE#7

In BASIC 2.0, use this command:

O PEN 7,8,7, “ 0:EXAM PLE,A”

The letter A allows subsequent P R IN T # statements to enter data at the end of the file “ E xam ple.” This BASIC 2.0 technique also requires a CLOSE statement: CLOSE7.

OTHER FILES

C128 BASIC includes several direct disk drive housekeeping commands including

SCRATCH, RENAM E, 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 C l 28 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.

C H A N G IN G TH E 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 :PR1NT# 15, ‘ ‘M -W ’ ’CHR$( 119)CHR$(0)CHR$(2)

CH R $(41 )CHR$(73):CLOSE 15

The 1571 has a device number switch on the back.

O U T P U T 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

IN P U T /O U T P U T GUIDE 379 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 o f 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 third- party 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.

PR IN TIN G A PROGRAM LISTING

The following commands will produce a printed listing:

OPEN3,4:CM D3:LIST

The CMD command redirects all screen output to the printer. Any subsequent output is sent to the printer until turned off with:

PRIN T#3:CLO SE3

These statements are necessary to clear the channel and ensure that all commands have been properly sent to the printer.

N O T E : 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:PRIN T# 131 :CLOSE 131

380 COMMODORE 128

PR IN TIN G A TYPED LINE

A PR IN T # command to an opened print file number outputs the associated data to the printer. The following commands output whatever is typed:

OPEN3 ,4:PR IN T #3, ‘‘TYPE 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.

PR IN TIN G TH R O U G H A PROGRAM

Instructions to a printer require a P R IN T # statement and can be mixed with the

PRINT statement for video display. The following program prints five lines o f text for each P R IN T # statement while using the screen display to obtain the input:

10 OPEN 3,4,7

20 DO UNTIL L = 5

25 IF L = 0THEN30 :ELSE INPUTA$:G OT040

30 INPUT“ PLEASE TY PE” ;A$

40 PR IN T #3,A $

50 L = L + 1

60 LOOP

70 CLOSE3

This is the beginning of a simple word processor and could be expanded into a complex system through printer control.

C O N TRO LLIN G YO U R PRINTER

Each printer capability (such as lower case characters, line feed, double width charac ters, 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 code— either 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:

P R IN T # 3 , CHR$(27)CHR$(33) or P R IN T #3, CHR$(27)“ !” and turned off with:

P R IN T # 3, CHR$ (27)CHR$(34) assuming channel 3 was previously opened.

IN P U T /O U T P U T GUIDE 381

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 o f 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 O PEN3,4,0. Generally a secondary address o f 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 OPEN 3 ,8 ,3 ,“ EX A M PLE,S,R ”

20 OPEN 4,4,0

25 DO

30 IN PU T #3,L $

40 IF L$ = “ EN D ’ 'THEN80ELSE50

50 PR IN T #4,L $

60 PRINT L$

70 LOOP

80 CLOSE4:DCLOSE3:END

O U T P U T T O 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. Com m odore’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,C),CHR$(6)CHR$(l 12) 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

Command Register Map.

382 COMMODORE 128

TH E RS-232 C HA N NEL

The RS-232 capabilities can be accessed from either BASIC or machine language.

The BASIC commands IN P U T # and G E T # are used to fetch data from the receiving buffer while P R IN T # and CM D 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 o f data when transmitting or receiving RS-232 information.

The Commodore 128 RS-232 I/O buffers consist o f 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 “ OUT OF

M EM ORY” error can occur, and your program in memory will not get “ stepped o n .”

O PEN IN G THE RS-232 C H A N N EL

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 S Y N T A X

OPEN lfn ,2 ,0 ” <control re g .> <com m and re g .> C opt baud lo w > < o p t baud h ig h > ”

The logical file number (lfn) then can be any number from 1 through 255. But be aware o f the fact that if you choose a logical file number that is greater than 127, then a line feed will follow all carriage returns.

TH E C O N TR O L REGISTER

The C o n tro l R egister is a single-byte required to specify the baud rates and other RS-232

IN P U T /O U T P U T GUIDE 383 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 8 4 2 0

@ @ 0 0 || [| 0 0

STOP BITS —

0-1 STOP BIT

1-2 STOP BITS

W ORD L E N G T H '

BIT

6 5

DATA

W ORD LENG TH

0 0 8 BITS

0 1

1 0

1 1

7 BITS

6 BITS

5 BITS

U NUSED

BAUD RATE

0 0 0 0 USER RATE

0 0 0 1

0 0 1 0

0 0 1 1

0 1 0 0

0 1 0 1

50 BAUD

110

134.5

150

0 1 1 0

0 1 1 1

1 0 0 0

300

600

1200

1 0 0 1

1 0 1 0

1800

2400

1 0 1 1 3600

1 1 0 0

1 1 0 1

4800

7200

1 1 1 0 9600

1 1 1 1 19200

[N l]

Figure 12-1. C o n tro l Register M ap

TH E C O M M A N D REGISTER

The C o m m a n d R e g iste r 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:

384 COMMODORE 128

OPEN3,4,O.CHR$(168)CHR$(32) specifies odd parity, full duplex. A baud rate other than those listed in the Control

Command Register.

The “ opt baud low ” 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.

BIT

PARITY O P T IO N S -

BIT

O P E R A T IO N S

PARITY D IS A B LE D , N O N E

G E N E R A TE D /R E C E IV E D

ODD PARITY

R E C E IV ER /TR AN S M ITTE R

EVEN PARITY

R E C E IV ER /TR AN S M ITTE R

M A R K T R A N S M IT T E D

PARITY C H E C K D IS A B LE D

SPAC E T R A N S M IT T E D

PARITY C H E C K D IS A B LE D

D U P L E X -----------------

0-F U LL DUPLEX

1-H A LF DUPLEX

U NUSED

Figure 12 -2 . C o m m an d Register Map

L -H A N D S H A K E

0-3 LIN E

1-X LIN E

IN P U T /O U T P U T GUIDE 385

E X A M P LE :

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 to 412)

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.

N O TE: 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 C l 28 mode, since the RS-232 I/O buffers are permanently allocated.

G ETTIN G D A TA FROM THE

RS-232 C H A N N EL

The Commodore 128 receiver buffer ($OCOO-$OCFF) will hold up to 255 characters before overflowing. This is indicated in the RS-232 status word ST. If an overflow occurs, sub sequent 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 C l 28 mode only).

Use G E T # with the file number corresponding to the OPEN statement. Machine code Kernal entries include BASIN and GETIN.

SENDING D A TA T O THE

RS-232 C H A N N EL

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 trans mission is allowed or the R U N / S T O P and R E S T O R E keys are used to recover the system.

Use CMD or P R IN T # with the proper file number to send data. Acceptable

Kernal entries include BSOUT (CHROUT).

CLOSING THE RS-232 C H A N N EL

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.

386 COMMODORE 128

N O T E : 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 W HILE PEEK (2575) and 3

30 CLOSE lfn

Location 2575 is the RS-232 “ ENABL” location.

Table 12-1 defines the User Port RS-232 channel lines.

(6526 D EVICE # 2 Loc. $DDOO-$DDOF)

ID c

6526

PBO

PB1

PB2

PB3

PB4

PB5

PB7

DESCRIPTIO N

Received Data

Request to Send

B FLAG2 Received Data

M PA2 Transmitted Data

A GND Protective Ground

N GND Signal Ground

EIA ABV

Received Line Signal (CF) DCD

Unassigned

Clear to Send

( ) XXX

(CB) CTS

Data Set Ready (CC) DSR

IN/

OUT

(BB) Sin IN

1 2

(CA) RTS OUT

1 * 2

Data Term inal Ready (CD) DTR OUT

1 * 2

Ring Indicator (CE) R l IN 3

MODES

(BB)

(BA)

Sin IN

1 2

Sout OUT

1 2

(AA) GND

(AB) GND

1 2

1 2 3

MODES:

1. 3-Line Interface (Sjn,S0Ut,GND).

2. X-Line Interface.

3. User Available Only (Unused/unimplemented in code).

* These lines are held high during 3-Line mode.

T a b le 12-1. U ser P o rt Lines

[ 7 ] [ 6 ] [ 5 ] [ 4 ] [ 3 ] [ 2 ] [ 1 ] [ 0 ] ( M a c h i n e L a n g . — RSSTAT)

: : : : : : : : _ P A R I T Y ERROR BIT

: :

: :______ F R A M I N G ERROR BIT

:___________ RECEIVER BUFFER O V E R R U N

:________________RECEIVER BUFFER — EMPTY

BIT

(USE T O TEST AFTER A G E T # )

.-____________________ CTS S I G N A L M I S S I N G BIT

:________________________ UN U S ED BIT

:_____________________________ DSR S I G N A L M I S S I N G BIT

:__________________________________ BREAK DETECTED BIT

Figure 12-3. RS-232 Status Register

IN P U T /O U T P U T GUIDE 387

N O TES to F igure 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 C H A N N EL

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 D IM F %(255),T%(255)

50 FORJ=3 2T06

60 T%(13)=13:T%(20)=8:RV=18:CT=0

70 FORJ=6 5T090:K=J+3

80 FORJ=91T095:T%(J)=J:NEXT

9 0 F O R J = l 9 3 T 0 2 1 8 : K = J - 1 2 8 : T % ( J ) = K : N E X T

100 T%(146)=16:T%(133)=16

110 T%(137)=3:T%(134)=17:T%(138)=19

120 FORJ=0TO255

130 K = T % (J )

150 NEXT

160 PRINT" "CH R S (147)

170 GET#5,A$

180 IFA$=""ORST<>0THEN220

1 9 0 P R I N T " " C H R $ ( 1 5 7 ) ; C H R $ ( F % ( A S C ( A $ ) ) ) ;

200 I F F % (A S C {A $ ) )=34THENPOKE212,0

210 GOT0170

220 P RI NTCHR?(R V )" "C H R $ (157);C H R $ (146);:GETA$

240 CT=CT+1

250 IFCT=8THENCT=0:RV=164-RV

260 GOT0170

ZERO-PAGE MEMORY LO C A TIO N S A N D

USAGE FOR RS-232 SYSTEM INTERFACE

The zero-page RS-232 storage locations for both C128 and C64 modes are as follows:

$00A 7-IN B IT — Receiver input bit temp storage.

$00A 8-B IT C I— Receiver bit count in.

$OOA9-RINONE— Receiver flag start bit check.

388 COMMODORE 128

$00AA-RIDATA — Receiver byte buffer/assembly location.

$00AB-RIPRTY — Receiver parity bit storage.

$00B4-BITTS — Transmitter bit count out.

$00B5-NXTBIT — Transmitter next bit to be sent.

$OOB6-RODATA — Transmitter 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 LO C A TIO N S A N D

USAGE FOR RS-232 SYSTEM INTERFACE

The general (nonzero-page) RS-232 storage locations for C l 28 mode are as follows:

(The addresses in parentheses are for C64 mode.)

$OA10($0293)-M51CTR — Pseudo 6551 Control Register (see Figure 12-1).

$0A11($0294)~M51CDR — Pseudo 6551 Command Register (see Figure 12-2).

$0A12($0295)-M 51AJB — Two 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) — RSSTAT — The RS-232 Status Register (see Figure 12-3).

$0A15($0298)-BITNUM — The number of bits to be sent/received.

$OA16($0299)-BAUDC)F — Two bytes that are equal to the time of one bit cell (based on system clock/baud rate).

$0A18($029B)-RIDBE — The byte index to the end o f the receiver FIFO buffer.

$0A19($029C)-RIDBS — The byte index to the start of the receiver FIFO buffer.

$OA1A($()29D)-RODBS — The byte index to the start o f the transmitter FIFO buffer.

$OA1B($()29E)-RODBE — The byte index to the end of the transmitter FIFO buffer.

$0A0F($02A1)-ENABL — Holds current active interrupts in the CIA # 2 ICR. When bit

4 is turned on, the system is waiting for the Receiver Edge. W hen bit 1 is turned on, then the system is receiving data. When bit 0 is turned on, then the system is transmitting data.

O U T P U T TO 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

IN P U T /O U T P U T GUIDE 389 and involve no tuners. The C l 28 includes a port to accept the traditional monitors as well as Com m odore’s 40-column 1702 color monitor. The C l 28 80-column color capability is enhanced with the new 40/80-column color monitor Model 1902. In this RGB I 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 C l 28. 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 o f 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 com mand. 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

ESC 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 CH R$(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.

O U T P U T 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:

LOAD1 ‘N A M E’ ’,1,1

Access to tape for sequential files is made with an OPEN statement to device 1:

OPEN 1,1

A secondary address of 0 (default value) assumes the file is opened for reading

(using IN P U T # or G E T #). A secondary address for writing (PR IN T # statements) requires a 1 or 2, where 2 includes an end-of-tape marker.

390 COMMODORE 128

OPEN 1,1,2 ‘ ‘FILENAM E”

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.

N O TE: Do not connect the Datassette and the 1571 disk drive to the C l 28 at the same time. If they are used at the same time, the data transfers may not be reliable.

IN P U T FROM THE

CONTROLLER PORTS

The C l 28 has two controller ports (numbered 1 and 2) that allow the use o f 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-A.

(Top)

FIRE

(Sw itch 4)

(Switch 0)

LEFT

(Switch 2)

RIG HT

(Sw itch 3)

D O W N

(Switch 1)

Figure 12-4. Joystick Sw itch A rra n g e m e n t

These switches correspond to the lower 5 bits o f 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:

IN P U T /O U T P U T G UIDE 391

1 0 R E M J O Y S T I C K R E A D R O U T I N E F O R C 1 2 8 O R C 6 4 M O D E S

2 0 J V = P E E K ( 5 6 3 2 1 )

3 0 I F ( J V A N D 1 5 ) < 1 5 T H E N P R I N T 1 5 - ( J V A N D 1 5 )

4 0 F I R E = J V A N D 1 6

5 0 I F F I R E 0 1 6 T H E N P R I N T " F I R E "

6 0 G O T O 2 0

NOTE: For the first joystick, set JV = PEEK (56320).

The values for JV correspond to the joystick directions shown in Table 12-2.

J V E Q U A L T O

D IR E C T IO N

NONE

DOWN

—

LEFT

UP & LEFT

DOWN & LEFT

—

RIGHT

UP & RIGHT

DOWN & RIGHT

T a b le 12 -2 . Joystick D irection 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 special joystick functions. To determine the position of joystick

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).

1 0 R E M C l 2 8 - M O D E S P R I T E - M O V E J O Y S T I C K R O U T I N E

2 0 S P R I T E 1 , 1 , 7 : R E M E N A B L E S P R I T E 1

3 0 M O V S P R 1 , 1 6 0 , 1 5 0 : RE M P L A C E S P R I T E 1 ON C E N T E R O F T H E S C R E E N

4 0 DO

5 0 :

6 0

7 0

8 0

9 0

1 0 0 :

A = J O Y ( l ) : R E M G E T J O Y S T I C K D I R E C T I O N V A L U E

I F A = 0 T H E N L O O P : R E M L O O P I F Z E R O

B = A : R E M S E T B E Q U A L T O A

Z = ( A - l ) * 4 5 : R E M C A L C U L A T E A N G L E

- T H I S K E E P S S P R I T E S T A T I O N A R Y

1 1 0 :

M O V S P R 1 , 5 ; Z : RE M MOV E S P R I T E 5 U N I T S A T T H E C A L C U L A T E D A N G L E

A = J O Y ( l ) : R E M C H E C K J O Y S T I C K V A L U E A G A I N

1 2 0 : L O O P W H I L E A = B : R E M MOV E I N T H E S A M E D I R E C T I O N W H I L E NE W V A L = O L D J O Y V A L U E

1 3 0 L O O P : R E M O T H E R W I S E C H E C K J O Y V A L U E A G A I N AN D MOVE I N D I F F E R E N T D I R E C T I O N

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”

TH E 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 o f 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 m ouse 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 read fro m 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:

1 0 R E M C 1 2 8 - M O D E S P R I T E - M O V E P A D D L E R O U T I N E

2 0 R E M P L A C E D U A L P A D D L E S I N C O N T R O L L E R P O R T A

3 0 R E M P A D D L E 1 C O N T R O L S H O R I Z O N T A L S P R I T E M O V E M E N T

4 0 R E M P A D D L E 2 C O N T R O L S V E R T I C A L M O V E M E N T

5 0 S P R I T E 1 , 1 , 7

6 0 DO

7 0 A = P O T ( 1 ) : RE M G E T P O S I T I O N ( X ) O P P A D D L E 1

8 0 B = P O T ( 2 ) : R E M G E T P O S I T I O N ( Y ) O F P A D D L E 2

9 0 P R I N T A ; B : R E M P R I N T V A L U E S

1 0 0 M O V S P R 1 , A , B : R E M MOV E S P R I T E 1 A C C O R D I N G T O P A D D L E V A L U E S

1 1 0 I F ( A > 2 5 5 ) O R ( B > 2 5 5 ) T H E N B E G I N : R E M C H E C K F O R F I R E B U T T O N

1 2 0 : S O U N D 2 , 6 4 0 0 0 , 6 0 , 0 , 1 0 0 0 , 1 6 0 0 0 , 3 : R E M F I R E

1 3 0 :

1 4 0 :

C O L O R 0 , 3 : R E M C H A N G E S C R E E N C O L O R

S L E E P 1 : R E M D E L A Y

1 5 0 : C O L O R 0 , 1 : R E M C H A N G E S C R E E N C O L O R BA C K

1 6 0 B E N D : R E M E N D T H E B E G I N / B E N D S T R U C T U R E

1 7 0 L O O P : R E M DO I T A G A I N

IN P U T /O U T P U T GUIDE 393

L IG H T PEN

The light pen input latches the current screen position into a pair o f 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 o f 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 C l 28 mode:

1 0 R E M C l 2 8 M O D E L I G H T P E N DRAW R O U T I N E

2 0 R E M P L A C E L I G H T P E N I N C O N T R O L L E R P O R T 1

3 0 C O L O R 0 , 2 : C O L O R 4 , 2 : C O L O R 1 , 1 : R E M S E L E C T S C R E E N C O L O R S

4 0 G R A P H I C 1 , 1 : R E M S E L E C T B I T MAP MODE

5 0 DO

6 0 :

7 0 :

8 0 :

X = P E N ( 0 )

Y = P E N ( 1 )

: RE M G E T H O R I Z O N T A L C O O R D I N A T E

: R E M G E T V E R T I C A L C O O R D I N A T E

DRAW 1 , X , Y : R E M P L O T P O I N T

9 0 L O O P : R E M DO I T A G A I N

1 0 0 :

1 1 0 R E M I F YOU L I K E T H E D R A W I N G ,

1 2 0 R E M

1 3 0 R E M

1 4 0 R E M

B R E A K T H E P R O G R A M AND

S A V E I T A S A B I N A R Y F I L E

F R O M $ 2 0 0 0 - $ 3 F F F .

O U T P U T CO NTRO L TO

ALL DEVICES

Each peripheral device is identified by a device number, as listed in Table 12-3.

D EVICE

Keyboard

Datasette

M odem (RS232)

Screen

Printer

Disk Drive

DEVICE NUMBER SECONDARY ADDRESSES

4 or 5

8,9,10,11

1 , 2

0 , 1

0 ,7 ,etc

2 -14,15

T a b le 12-3. Device N u m b ers

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:

394 COMMODORE 128

1 0 I N P U T " S E L E C T D E V I C E N U M B E R " ; D *

2 0 I N P U T " S E L E C T S E C O N D A R Y A D D R E S S " ; S%

3 0 I N P U T " N A M E O F F I L E O R C O N T R O L R E G I S T E R " ; A $

4 0 O P E N 9 , D % , S % , A $

5 0

6 0

G O S U B

C L O S E

7 0 E N D

8 0 R E M P L A C E S U B R O U T I N E H E R E

9 0 R E T U R N

8 0

THE IN P U T/O U T P U T

PINO UTS

TH E SERIAL PORT

The Serial Port is a daisy chain 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 operation— three 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 C l 28 serial bus protocol.

SERIAL I/O

PIN TYPE

SERIAL SRQIN

GND

SERIAL ATN IN/OUT

SERIAL CLK IN/OUT

SERIAL DATA IN/OUT

RESET

Figure 12-5. Serial P o rt Pinouts

USER PORT (RS-232 C H AN N EL)

The User Port (RS-232 Channel) connects the Com m odore 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.

IN P U T /O U T P U T G UIDE 395

1 2 3 4 5 6 7 8 9 10 11 12

A B C D E F H J K L M N

Figure 12 -6 . U s er P o rt Pinouts

PIN

T O P SIDE D ESCRIPTIO N

GROUND

+ 5V

RESET

1 0

1 1

1 2

CNT1

SP1

CNT2

SP2

PC2

SERIAL

ATN IN

9 VAC + phase

9 V A C -phase

GROUND

BO TTO M SIDE

GROUND

FLAG2

PBO

PB1

PB2

PB3

PB4

PB5

PB7

PA2

GROUND

T a b le 12 -4 . U s er P o rt Pin Descriptions

NOTES

(100 mA M A X.)

By grounding this pin, the Commodore 128 will do a cold start, resetting com pletely. The pointers to a BASIC program will be reset, but m em ory 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 o f the serial bus.

Connected directly to the Comm odore 128 trans former (100 mA M ax.).

The Comm odore 128 gives you control over Port

B on CIA chip 1. Eight lines for input or output are available, as well as tw o 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 IN PUT, or

POKE it to set an OUTPUT. Each o f the eight

I/O lines can be set up as either an IN PUT or an

OUTPUT by setting the Data Direction Register properly.

The D a ta D ir e c tio n R e g iste r has its location at 56579 ($DD03 hex). Each o f 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

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 o f 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 11 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:

25 + 24 + 23 = 32 + 16 + 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.

TH E COMPOSITE

VID E O C O N N EC TO R

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.

IN P U T /O U T P U T GUIDE 397

Figure 12-7. C o m p o site V id e o C o n necto r Pinouts

TYPE

LUM/SYNC

GND

AUDIO OUT

VIDEO OUT

AUDIO IN

COLOR OUT

NOTE

Luminance/SYNC output

Composite signal output

Chroma signal output

No connection

T a b le 12-5. C o m p o site V id e o C o n necto r Pin Descriptions

TH E RGBI

V ID E O C O N N EC TO R

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.

F igure 12-8. RGBI C o n n e c to r P inouts

398 COMMODORE 128

SIGNAL

Ground

Red

Green

Blue

Intensity

M onochrome

Horizontal Sync

Vertical Sync

T a b le 12-6. RGBI C o n necto r Pin Descriptions

TH E CASSETTE C O N N EC TO R

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 2 3 4 5 6

A B C D E F

Figure 12 -9 . Cassette P o rt Pinouts

A -l

B-2

C-3

D-4

E-5

- 6

TY PE

GND

+ 5V

CASSETTE MOTOR

CASSETTE READ

CASSETTE W RITE

CASSETTE SENSE

T a b le 12 -7 . Cassette P o rt Pin Descriptions

TH E 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.

IN P U T /O U T P U T GUIDE 399

CO NTRO L PORT I

PIN TYPE

JOYAO

JOYA1

3 JOYA2

4 JOYA3

5 POT AY

BUTTON A/LP

+ 5V

GND

9 POT AX

NOTE

M AX. 50mA

C O N T R O L P O R T 2

PIN TY PE

JOYBO

JOYB1

3 JOYB2

4 JOYB3

5 POT BY

BUTTON B

+ 5V

GND

9 POT BX

N O TE

M AX. 50mA

T a b le 12-8. C o n tro lle r P o rt Pin Descriptions

TH E EXPANSIO N PORT

Vhe expansion port connector is a 44-pin female edge connector accessing the comput er’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 expan sion 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.

2 22 1 20 191B 17 1615 14 13 12 11 10 9 8 7 6 5 4 3 2 1

Z V X W 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 I 2 - I I . Expansion P o rt Pinouts

400 COMMODORE 128

1 1

1 2

2 0

2 1

2 2

1 0

TY PE

GND

+ 5V

IRQ

R/W

Dot Clock

I/O 1

GAM E

EXROM

I/O 2

ROML

DMA

D l

GND

TYPE

A13

A12

A l l

A10

GND

ROMH

RESET

NMI

S 02

A15

A14

GND

T a b le 12-9. Expansion P o rt Pin Descriptions

13 THE

COMMODORE 128

OPERATING

SYSTEM

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 K e rn al, which contains about 16K of machine language instructions. These instruc tions make up the routines that control all the m achine’s functions— even 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 com puter’s memory.

TA K IN G FULL ADVA N TA G E OF THE

COMMODORE 128 OPERATING SYSTEM

The 16K o f operating system instructions contained in the Kernal are available for use with your own programs. Instead of “ reinventing the w heel” 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 microcom puter industry, the entry points in the jum p table are revised to reflect address changes o f 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 jum p 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.

TH E COMMODORE 128 OPERATING SYSTEM 403

HOW TO USE (CALL)

THE KERNAL ROUTINES

YOUR OWN PROGRAMS

M ost 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 registers— either 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 jum p 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 instruc tion is stored at location $FFA5 and the address of the entry point o f 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 jum p table address ($FFA5, for example); then the JMP instruction at $FFA5 jum ps 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 jum p table, and then a second jum p (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 C l 28 system vector and jump table that includes the name, address and function description of the operating system Kernal routines.

404 COM M ODORE 128

C l 28 S Y S T E M V E C T O R S

1 .

$FFFB SYSTEM

$FFFA NMI

$FFFC RESET

$FFFE IRQ

;operating system vector (R AM I) p rocessor NMI vector

;processor RESET vector p rocessor IRQ/BRK vector

C B M S T A N D A R D K E R N A L J U M P T A B L E C A L L S

1 .

$FF81 JM P CINT

$FF84 JM P IOINIT

$FF87 JM P RAMTAS

$FF

A JM P RESTOR

$FF

D JM P VECTOR

$FF90 JM P SETM SG

$FF93 JM P SECND

$FF96 JM P TKSA

$FF99 JM P M EM TOP

;init screen editor and devices

;init I/O devices

;init RAM and buffers

;init indirect vectors (system)

;init indirect vectors (user)

;kernal messages on/off

;serial: send SA after LISTN

;serial: send SA after TALK

;set/read top of system RAM

1 0

$FF9C JM P M EM BOT

1 1

$FF9F JM P KEY

1 2

SFFA2 JM P SETTM O

13.

$FFA5 JM P ACPTR

14.

$FFA

JM P CIOUT

15.

$FFAB JM P UNTLK

16.

$FFAE JM P UNLSN

17.

$FFB1 JM P LISTN

18.

$FFB4 JM P TALK

19.

$FFB7 JMP READSS

2 0

$FFBA JM P SETLFS

2 1

$FFBD JM P SETNAM

;set/read bottom o f system RAM

;scan keyboard preserved)

;serial: byte input

;serial: byte output

;serial: send untalk

;serial: send unlisten

;serial: send listen

;serial: send talk

;read I/O status byte

;set channel L A , FA, SA

;set filename pointers

2 2

$FFC0 JM P (IOPEN)

23.

$FFC3 JM P (ICLOSE)

24.

$FFC

JM P (ICHKIN)

;open logical file

;close logical file

;set input channel

25.

$FFC9 JM P (ICKOUT)

26.

$FFCC JM P (ICLRCH)

27.

$FFCF JM P (IBASIN)

28.

$FFD2 JM P (IBSOUT)

29.

$FFD5 JM P LOAD

30.

$FFD

JM P SAVE

31.

$FFDB JMP SETTIM

32.

$FFDE JM P RDTIM

33.

$FFE1 JMP (ISTOP)

;set output channel

;restore default channels

;input from channel

;output to channel

;load from file

;save to file

;set internal clock

;read internal clock

;scan STOP key

THE COMMODORE 128 OPERATING SYSTEM 405

34.

35.

36.

$FFE4

$FFE7

$FFEA

JM P (IGETIN)

JM P (ICLALL)

JM P UDTIM

37.

$FFED JM P SCRORG

38.

$FFF0 JM P PLOT

39.

$FFF3 JM P IOBASE

;read buffered data

;close all files and channels in crem en t internal clock

;get current screen window size

;read/set cursor position

;read base address o f I/O block

N E W C l 28 K E R N A L JU M P T A B L E C A LL S

$FF47 JM P SPIN SPOUT ;setup fast serial ports for I/O

$FF4A JM P CLOSE ALL

$FF4D JM P C64M ODE

$FF50 JM P DMA CALL

;close all files on a device

;reconfigure system as a C64

;send command to DMA device

$FF53 JM P BOOT CALL ;boot load program from disk

$FF56 JM P PHOENIX

$FF59 JM P LKUPLA

;init function cartridges

;search tables for given LA

$FF5C JM P LKUPSA

$FF5F JM P SW APPER

1 0

$FF62 JM P DLCHR

1 1

$FF65 JM P PFKEY

1 2

$FF

6 8

JM P SETBNK

13.

$FF

B JM P GETCFG

14.

$FF

E JM P JSRFAR

15.

$FF71 JM P JM PFAR

16.

$FF74 JM P INDFET

17.

$FF77 JM P INDSTA

18.

$FF7A JM P INDCM P

19.

$FF7D JM P PRIMM

;search tables for given SA

;switch between 40 and 80 colum ns

;init 80-col character RAM

;program a function key

;set bank for I/O operations

;lookup MMU data for given bank

;gosub in another bank

;goto another bank

;LDA (fetvec),Y from any bank

;STA (stavec),Y to any bank

;CMP (cm pvec),Y to any bank

;print im mediate utility

Figure 13-1. U ser-C allab le Kernal Routines

Figure 13-2 lists the conventions used in the description of each Kernal subrou tine. The figure is followed by descriptions o f the C l 28 system vectors and Kernal subroutines. Included in each description are the subroutine name, call address, prepara tory 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.

406 COM M ODORE 128

USER CALLABLE

KERNAL ROUTINE C O N V E N T IO N S

C all Address: This is the call address of the Kemal routine, given in hexadecimal.

Function N am e : Name of the Kemal routine.

Register: Registers, memory and flags listed under this heading are used to pass parameters to and from the Kemal routines.

P rep arato ry Routines: Certain Kemal routines require that data be set up by prepara tory routines before the target routine can be called. The necessary routines are listed here.

E rro r Returns: A return from a Kemal routine with the carry set indicates an error was encountered in processing. The accumulator will contain the number o f the error.

E rro r Codes: Below is a list of error messages that can occur when using the

Kemal routines. If an error occurs during a Kemal routine, the carry bit of the accumulator is set, and the number of the error message is returned in the accumulator.

N O T E : Some Kemal I/O routines do not use these codes for error messages. Instead, errors are identified using the Kemal READST routine.

NUMBER

MEANING

Routine terminated by the STOP key

Too many open files

File already open

File not open

File not found

D evice 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 A ffected: All registers, memory and flags used by the Kem al routine are listed here.

Examples: An example of each Kemal routine is listed.

Description: A short explanation of the function of the Kernal routine is given here.

F igure 13-2. U ser-C allable K ernal R outine C o nventions

THE COMMODORE 128 OPERATING SYSTEM 407

C l 28 SYSTEM VECTORS

The vectors listed below, with the exception o f the SYSTEM vector, are located not only in system ROM but in each RAM bank. The beginning and end o f 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 configu ration. 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 jum ps, 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 (RAM I)

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 arm ” reset and a “ cold” 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 JM P is performed. In most cases, the user need only call IOINIT beore resuming control. The layout in RAM-1 is:

$FFF5 ‘C ’

$FFF6 ‘B ’

($43)

($42)

$FFF7 ‘M ’ ($4D)

$FFF8 SYSTEM vector low

$FFF9 SYSTEM 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 M onitor itself and thus regain control with minimal RAM loss, simply by pressing the RESET button. To accomplish this, the programmer would enter: a. > 1FFF8 00 13 :aim SYSTEM to $1300 b. A 1300 JSR $FF84 :call IOINIT

JMP $B000 :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 o f N M I’s under normal conditions: the R E ST ORE key and RS-232 I/O. In the event of an

NM I, the operating system disables IRQ ’s, saves the registers and current memory

408 COMMODORE 128 configuration on the stack, brings the system configuration (ROM ’s, I/O, RAMO) 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 R E S T O R E key is assumed, and for safety, the CBM convention of requiring the S T O P key to be simultaneously de pressed 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. N M I’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 RAMO, 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 M onitor whenever STOP/

RESTORE is detected, enter: a. > A 0 0 00 BO :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 when ever you press R E S T O R E (or cause any other NMI). Enter: a. > 3 1 8 00 13 :aim indirect to $1300 b. A 1300 INC $D020 :change border color

JMP $FF33 :retum 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 o f the system while the 8502 is held in a waiting state. When the 8502 finally starts after a reset, the Kemal initialization routine START always receives control and immediately performs the following actions:

1. Brings the system map into context.

2. Disables IRQ ’s.

3. Resets the processor stack pointer.

4. Clears decimal mode.

5. Initializes the MMU.

6. INSTALLS the Kernal RAM code.

THE COMMODORE 128 OPERATING SYSTEM 409

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 GAM E or EXROM signal being pulled low. If so, G 0 6 4 is executed

(see the Kernal jum p 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 C l 28 cartridges and function RO M ’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 —» cold start entry

$x003 - » warm start entry (unused)

$x006 ID. ($01-$FF)

$x007 -> “ CBM ” key string where x = $8— or $C— .

The ID of any C l 28 cartridge found is entered into the Physical Address Table

(PAT) located at SAC1-SAC4. ID ’s must be non-zero. Cartridges may recognize each other by examining the PAT for particular ID ’s. An ID o f 1 indicates an auto-start cartridge, and its cold start entry will be called immediately. All others will be called later (see PHOENIX jum p), 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 SEI

$x001 JMP STARTUP

$x004 NOP

$x005 NOP

The balance of the C l28 initialization is:

9. IOINIT: Initialize I/O devices.

10. Check for STOP AND O keys.

11. RAMTAS: Initialize system RAM.

12. RESTOR: Initialize system indirects.

13. CINT: Initialize video displays.

14. Enable IR Q ’s (except foreign systems).

15. Dispatch.

IOINIT is perhaps the major function of the Reset handler. It initializes both C IA ’s

(timers, keyboard, serial port, user port, cassette) and the 8502 port (keyboard,

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 jum p table.

During initialization, the user may press certain keys as a means of selecting an operating mode. One key checked is the Commodore key O , 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 Kemal needs to know if RAMTAS should be skipped. Only if the S T O P key is depressed and this was a “ w arm ” reset

(vs. “ cold” 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 BA

SIC 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 “ cold” and a “ w arm ” system. If DEJAVU contains $A5, the system is “ w arm ” 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 S T O P key is scanned, RAMTAS is skipped, and the Monitor

(rather than BASIC) is selected. RAMTAS is callable by the user via the jum p table.

RESTOR initializes the Kemal indirect vectors. This must be done before many system routines will function. Applications that complement the operating system via “ wedges” must install them after they are initialized. RESTOR is user callable from the jum p table (see also the VECTOR call).

Finally, the IR Q ’s are enabled and control is passed to either BASIC initialization, G 0 6 4 code, or the ML M onitor. BASIC will call the Kernal

PHOENIX routine upon the conclusion of its initialization, which will call any installed C l 28 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 o f the Reset code, and as specific stages are completed, a particular bit is set. The layout is:

B7 —> 8563 characters installed

B6 —* CINT performed

BO —» BASIC initialized

TH E COMMODORE 128 OPERATING SYSTEM 411

Any IOINIT calls, including Reset, will not result in 8563 character RAM initial ization 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 N M I’s, for example, can call IOINIT and CINT without destroying users’ setups. Finally,

BASIC initialization must be complete before BO 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. Hold down S T O P key to enter Monitor.

2. Press and release

RESET button.

3. Release S T O P key.

4. Enter: > A 0 4 C l :re-enable BASIC IRQ.

5. 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 BO reset. If BO had not been set,

BASIC IRQ routines such as SOUND, PLAY, and SPRITE handlers would not have functioned, usually resulting in an apparent “ hang.”

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 adjust ments have to be made for PAL (50Hz) systems]. The usual source of IR Q ’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,

RAMO) 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 M onitor 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:

412 COMMODORE 128

1. IR Q ’s disabled.

2. Editor: split screen handler.

3. Editor: clear VIC raster IRQ.

4. IR Q ’s enabled.

5. Editor: keyboard scan.

6. Editor: VIC cursor blink.

7. Kernal: “ jiffie ” clock.

8. Kernal: cassette switches.

9. Kernal: clear CIA-1 ICR.

10. BASIC: sprites, sounds, etc.

11. Return from interrupt.

As indicated in the preceding description, the C l 28 operating system uses the

IRQ heavily. In particular, the Editor split screen handler has rather strict require ments 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 ain” 60Hz IRQ and the “ m iddle” 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. Program mers 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 G R A PH M , 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 jum ps, K E Y L O G and K E Y PU T , 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 jum p 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 jum p 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 o f 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 IRQ_W RAP

_FLA G . It is normally used by the system to block IRQ-ed IRQ calls, but can be set by the user with the effect o f 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 o f the IRQ indirect ($314) by an application usually requires more care than most other wedges for several reasons. The likelihood o f an IRQ occur ring 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 413 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 $D 011

BPL $1324

LDA $D505

ORA # $ 8 0

STA $D505

LDA $D 011

AND # $ 6 F

LDX #$01

BIT $D505

BPL $ 13 IE

ORA # $ 1 0

DEX

131E STX $D030

STA $D 011

1324 JMP ($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

;lM H z

;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 $314

STA $1300

LDA $315

STA $1301

LDA #$ 0 2

STA $314

LDA #$13

STA $315

CLI

RTS

;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 4 0 / 8 0 key now puts you in FAST mode; releasing it SLOWS you down, and the keyscan, etc., continues to function. Note, however, that on this

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 C l 28 system IRQ: First, be sure to keep the raster compare value on-screen to keep the

IR Q ’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 Kemal 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: none system map none none

Memory:

.A used

,X used

.Y used init Editor RAM init Editor I/O none Flags:

E X A M P LE :

SEI

JSR $FF81

CLI initialize screen editor

C IN T 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

THE COMMODORE 128 OPERATING SYSTEM 415 does not do that pertains to the Editor is I/O 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 IR Q ’s prior to calling it. CINT utilizes the status byte INIT_STATUS ($A04) as follows:

$A04 bit 6 = 0 —> Full initialization.

(set INIT_STATUS bit 6)

1 —> Partial initialization.

(not key matrix pointers)

(not program key definitions)

CINT is also an Editor jum p table entry ($C000).

2. $FF84 IOINIT ;init I/O devices

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers: none system map none none

Memory:

Flags:

.A used

.X used

.Y used initialize I/O none

E X A M P LE :

SEI

JSR $FF84

CLI initialize system I/O

IO IN IT is perhaps the major function of the Reset handler. It initializes both

C IA ’s (timers, keyboard, serial port, user port, cassette) and the 8502 port (key board, 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 neces sary). 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 —>- Full initialization.

(set INIT—STATUS bit 7)

= 1 —» Partial initialization.

(not 8563 character definitions)

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

E X A M P LE :

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 SY STEM .V EC TO R ($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 Kemal indirects

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers: none system map none none

Memory:

Flags:

.A used

.X used

.Y used

Kemal indirects restored none

THE COMMODORE 128 OPERATING SYSTEM 417

E X A M P LE :

SEI

JSR $FF8A

CLI

;restore Kernal indirects

RESTOR restores the default values of all the Kemal indirect vectors from the Kemal 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:

.X = adr (low) of user list

.Y = adr (high) of user list system map

.C = 0 —* load Kemal vectors

,C = 1

— * copy Kemal vectors none Calls:

RESULTS:

Registers:

Memory:

Flags:

.A used

.Y used as per call none

E X A M P LE :

LDX # sa v e _ lo

LDY #sav e_ h i

SEC

JSR $FF87 ;copy indirects to “ save”

VECTOR reads or writes the Kernal RAM indirect vectors. Calling VEC

TOR 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.

418 COMMODORE 128

6. $FF90 SETMSG ;Kemal messages on/off

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers:

Memory:

Flags:

.A = message control system map none none none

MSGFLG ($9D) updated none

E X A M P LE :

LDA # 0

JSR $FF90 ;turn OFF all Kernal messages

SETM SG updates the Kernal message flag byte MSGFLG ($9D) that deter mines 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 iserial: send SA after LISTN

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers:

Memory:

Flags:

.A = SA (secondary address) system map none

LISTN

.A used

STATUS ($90) none

E X A M P LE :

LDA # 8

JSR $FF81

LDA # 1 5

JSR $FF93

;LISTN device 8

;pass it SA # 1 5

THE COMMODORE 128 OPERATING SYSTEM 419

SECND is a low-level serial routine used to send a secondary address (SA) to a LISTNing device (see LISTN Kemal 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).

8. $FF96 TKSA ;serial: send SA after TALK

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers:

Memory:

Flags:

.A = SA (secondary address) system map none

TALK

.A used

STATUS ($90) none

E X A M P LE :

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 Kemal call). An SA is usually used to provide setup inform ation 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 MEMTOP ;set/read top of system RAM

PREPARATION:

Registers:

Memory:

Flags:

Calls:

.X = lsb of MEMSIZ

.Y = msb of MEMSIZ system map

C = none

0 —* set top of memory

.C = 1 —» read top of memory

420 COMMODORE 128

RESULTS:

Registers:

Memory:

Flags:

.X = lsb of MEMSIZ

.Y = msb of MEMSIZ

MEMSIZ ($A07) none

E X A M P LE :

SEC

JSR $FF99

DEY

CLC

JSR $FF99

;get top of user RAMO

;lower it 1 block

MEM TOP is used to read or set the top of system RAM, pointed to by

MEMSIZ ($A07). This call is included in the C l 28 for completeness, but neither the

Kernal nor BASIC utilizes MEMTOP since it has little meaning in the banked memory environment of the C l 28 (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 (RAMO). The Kernal initially sets MEMSIZ to $FF00 (MMU and

Kernal RAM code start here).

10. $FF9C MEMBOT ;set/read bottom o f system RAM

PREPARATION:

Registers:

Memory:

Flags:

.X = lsb of MEMSTR

.Y = msb o f MEMSTR system map

.C = 0 —* set bot of memory

.C = 1 —» read bot o f memory none Calls:

RESULTS:

Registers:

Memory:

Flags:

.X = lsb of MEMSTR

.Y = msb o f MEMSTR

MEMSTR ($A05) none

E X A M P LE :

SEC

JSR $FF9C

INY

CLC

JSR $FF9C

;get bottom of user RAMO

;raise it 1 block

THE COMMODORE 128 OPERATING SYSTEM 421

MEMBOT is used to read or set the bottom of system RAM, pointed to by

MEMSTR ($A05). This call is included in the C128 for completeness, but neither the Kemal 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 (RAMO). The Kemal 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

Flags: none keyboard buffer keyboard flags none

E X A M P LE :

JSR $FF9F ;scan the keyboard

KEY is an Editor routine that scans the entire C l 28 keyboard (except the

40/ 80 key). It distinguishes between ASCII keys, control keys, and program mable 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 driv ing the key line on which the S T O P key is located.

There are two indirect RAM jum ps 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:

$33E Mode 1

$340 Mode 2

$342 Mode 3

$344 Mode 4

$346 Mode 5

$348 Mode 6 normal keys

S H I F T keys

O keys

C O N T R O L keys

C A P S L O C K keys

A L T keys

422 COMMODORE 128

The following list briefly describes some of the more vital variables utilized or maintained by K EY :

ROWS

COLM

$DC01

$DC00

VIC # 4 7 $D02F

8502 P6 $0001

NDX $D0

KEYD

XMAX

$34A

$A20

SHFLAG $D3

RPTFLG $A22

LOCKS $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 preserved)

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers:

Memory:

Flags: none system map none none none

TIMOUT ($A0E) none

E X A M P LE :

LDA #value

JSR $FFA2 ;update TIMOUT byte

SETTMO is not used in the C l 28 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 COMMODORE 128 OPERATING SYSTEM 423

RESULTS:

Registers:

Memory:

Flags:

E X A M P LE :

JSR $FFA5

STA data

.A = data byte

STATUS ($90) none

;input a byte from serial bus

A C P T R 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.

(M ost applications should use the higher-level I/O routines; see BASIN and

GETIN).

14. $FFA8 CIOUT ;serial: byte output

PREPARATION:

Registers:

Memory:

Flags:

Calls:

.A = data byte system map none

LISTN

SECND (if necessary)

RESULTS:

Registers:

Memory:

Flags:

.A used

STATUS ($90) none

E X A M P L E :

LDA data

JSR $FFA8 ;send a byte via serial bus

C IO U T 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.)

424 COM M ODORE 128

15. $FFAB UNTLK ;serial: send untalk

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers:

Memory:

Flags: none system map none none

.A used

STATUS ($90) none

E X A M P LE :

JSR $FFAB ;UNTALK serial device

U N T L K is a low-level Kemal 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:

RESULTS:

Registers:

Memory:

Flags: none system map none none

.A used

STATUS ($90) none

E X A M P LE :

JSR $FFAE ;UNLISTEN serial device

UNLSN is a low-level Kemal 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 42S

17. $FFB1 LISTN ;serial: send listen command

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers:

Memory:

Flags:

.A = device (0-31) system map none none

.A used

STATUS ($90) none

E X A M P LE :

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 read ing data. (M ost applications should use the higher-level I/O routines; see

ICKOUT.)

18. $FFB4 TALK ;serial: send talk

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers:

Memory:

Flags:

.A = device (0-31) system map none none

.A used

STATUS ($90) none

E X A M P LE :

JSR $FFB4 ;command device to TALK

TA L K is a low-level Kemal 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.)

426 COMMODORE 128

19. $FFB7 READSS ;read I/O status byte

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers:

Memory:

Flags: none system map none none

.A = STATUS ($90 or $A14)

STATUS cleared if RS-232 none

E X A M P LE :

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

E X A M P LE :

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

TH E COMMODORE 128 OPERATING SYSTEM 427 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 Kemal

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

E X A M P LE :

See OPEN

SETNAM sets up the filename or command string for higher-level Kemal 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

428 COMMODORE 128

RESULTS:

Registers:

Memory:

Flags:

.A = error code (if any)

.X used

.Y used setup for I/O

STATUS, RSSTAT updated

.C — 1 —> error

E X A M P L E : OPEN 1,8 ,1 5 ,“ 10”

LDA #length fnlen

LDX # < file n a m e fnadr (command)

LDY # > filen am e

JSR $FFBD SETNAM

LDX # 0

JSR $FF68 fnbank (RamO)

SETBNK

LDA #1

LDX # 8

LDY # 1 5

JSR $FFBA

JSR $FFC0

BCS error filename .BYTE ‘10’ length = 2 la fa sa

SETLFS

OPEN

OPEN prepares a logical file for I/O operations. It creates a unique entry in the Kemal 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 $31 A. 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

TH E COMMODORE 128 OPERATING SYSTEM 429

RESULTS:

Registers:

Memory:

Flags:

.A = error code (if any)

.X used

.Y used logical tables updated

STATUS, RSSTAT updated

.C = 1 —* error

E X A M P LE :

LDA #1

JSR $FFC3

BCS error

:1a

;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

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

E X A M P LE :

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

Kemal 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 $ 3 IE. 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:

.X = LA (logical # ) system map none

OPEN

Memory:

Flags:

.A = error code (if any)

.X used

.Y used

LA, FA, SA, DFLTO

STATUS, RSSTAT updated

.C = 1 —* error

TH E COMMODORE 128 OPERATING SYSTEM 431

E X A M P LE :

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

E X A M P LE :

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.

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:

RESULTS:

Registers:

Memory:

Flags: none system map none

CHKIN (if necessary)

.A = character (or error code)

STATUS, RSSTAT updated

.C = 1 if error

EX A M P L E :

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 w ritten, the end o f line (EOL) is not recog nized. Users must therefore count characters themselves or otherwise detect when the logical EOL has been reached.

TH E COMMODORE 128 OPERATING SYSTEM 433 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:

RESULTS:

Registers:

Memory:

Flags:

.A = character system map none

CKOUT (if necessary)

.A = error code (if any)

STATUS, RSSTAT updated

.C = 1 if error

E X A M P LE :

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.

434 COM M ODORE 128

29. $FFD5 LOAD ;load from file

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers:

.A = 0 —> LOAD

.A > 0 —> VERIFY

.X = load adr lo (if SA = 0)

.Y = load adr hi (if SA = 0) system map none

SETLFS, SETNAM, SETBNK

Memory:

Flags:

.A = error code (if any)

.X = ending adr lo

.Y = ending adr hi per command

STATUS updated

.C = 1 —» error

E X A M P LE : L O A D “ p ro g ram ” ,8 ,1

LDA #length ;fnlen

LDX # < file n a m e ;fnadr

LDY # > file n a m e

JSR $FFBD SETNAM

LDA # 0

LDX # 0

JSR $FF68

LDA # 0

LDX # 8

LDY # $ F F

JSR $FFBA la (not used) fa sa (S A X ) normal load)

SETLFS

LDA # 0

LDX # < lo a d adr

LDY # > lo a d adr

JSR $FFD5

BCS error

STX end lo

STY end hi load, not verify

(used only if SA = 0)

LOAD filename .BYTE “ program ” length = 7 load/verify bank (RAM 0) fnbank (RAM 0)

SETBNK

This routine LOADs data from an input device into C l 28 memory. It can also be used to VERIFY that data in memory matches that in a file. LOAD performs

THE COMMODORE 128 OPERATING SYSTEM 43S 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 I/O, 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 o f .A passed at the call to LOAD deter mines 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:

.A = pointer to start adr

.X = end adr lo

.Y = end adr hi system map none

SETLFS, SETNAM, SETBNK

Memory:

Flags:

.A = error code (if any)

.X = used

.Y = used

STATUS updated

.C = 1 —» error

E X A M P LE : SAVE “ program ” ,8

LDA #len g th ;fnlen

LDX # < file n a m e ;fnadr

LDY # > file n a m e

JSR $FFBD ;SETNAM

436 COMMODORE 128

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 e n d + 1

JSR $FFD8

BCS error

;pointer to start address

;ending address lo

;ending adr hi

;SAVE filename .BYTE “ program ’ length = 7 start end

.WORD address 1 ;page-0

.WORD address2

This routine SAVEs data from C128 memory to an output device. SAVE per forms 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) = 0

= 1 —> absolute

—*

(plf) file relocatable (blf) file

SA (bit 1) = 0 —»

= 1 —* write EOT header at end normal 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

THE COMMODORE 128 OPERATING SYSTEM 437

RESULTS:

Registers:

Memory:

Flags: none

TIME ($A0) updated none

E X A M P LE :

LDA # 0

TAX

TAY

JSR $FFDB

;reset clock

;SETTIM

SETTIM sets the system software (jiffic) 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 IR Q ’s.

32. $FFDE RDTIM ;read internal clock

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers:

Memory:

Flags: none system map none none

.A =

.X =

,Y = none none low byte middle byte high byte

E X A M P LE :

JSR $FFDE ;RDTIM

RDTIM reads the system software (jiffie) clock, which counts sixtieths (1/60) o f a second. The timer is incremented during system IRQ processing (see UDTIM). and reset at the 24-hour point. RDTIM disables IR Q ’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

438 COMMODORE 128

RESULTS:

Registers:

Memory:

Flags:

.A = last keyboard row

.X = used (if STOP key) none status valid

E X A M P L E :

JSR $FFE1

BEQ stop

;scan STOP key

;branch if down

STOP checks a Kemal variable STKEY ($91), which is updated by UDTIM during normal IRQ processing and contains the last scan o f 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: 7 6 5 4 3 2

Key: STOP Q O SPACE 2 CTRL

1 0

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

E X A M P L E : 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 439 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 automatically jumps to BASIN. See BASIN serial I/O.

d. Cassette input: GETIN automatically jum ps to BASIN. See BASIN cassette

I/O.

e. Screen input: GETIN automatically jumps 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:

ULTS:

Registers:

Memory:

Flags:

EXAMPLE:

JSR $FFE7 none system map none none

.A used

.X used

LDTND, DFLTN, DFLTO updated none

;close files

C L A L L 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 increm ent internal clock

PREPARATION:

Registers:

Memory:

Flags:

Calls: none system map none none

440 COMMODORE 128

RESULTS:

Registers:

Memory:

Flags:

E X A M P LE :

SEI

JSR $FFEA

CLI

.A used

.X used

TIME, TIMER, STKEY updated none

;UDTIM

UDTIM increments the system software (jiffie) clock, which counts sixtieths

(1/60) o f a second when called by the system 60Hz IRQ. TIM E, a 3-byte counter located at $A0, is reset at the 24-hour point. UDTIM also decrements TIM ER, also a 3-byte counter, located at $A1D (BASIC uses this for the SLEEP command, for example). You should be sure IR Q ’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 Kemal routine STOP utilizes this variable.

37. $FFED SCRORG ;get current screen window size

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers: none system map none none

Memory:

Flags:

E X A M P LE :

JSR $FFED

.A = screen width

.X = window width

.Y = window height none none

;SCRORG

SCRORG is an Editor routine that has been slightly changed from previous

CBM systems. Instead o f returning the maximum SCREEN dimensions in .X and

.Y, the C l 28 SCRORG returns the current WINDOW dimensions. It does return the maximum SCREEN width in .A. These changes make it possible for applica tions to “ fit” themselves on the current screen window. SCRORG is also an Editor jum p table entry ($C00F).

THE COMMODORE 128 OPERATING SYSTEM 441

38. $FFF0 PLOT ;read/set cursor position

PREPARATION:

Registers:

Memory:

Flags:

.X = cursor line

.Y = cursor column system map

,C = 0 —» set cursor position

.C = 1 —> get cursor position none Calls:

RESULTS:

Registers:

Memory:

Flags:

.X = cursor line

.Y = cursor column

TBLX, PNTR updated

.C = 1 —> error

E X A M P LE :

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

P L O T 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

$E4 -> window bottom

$E5

$E6

$E7

—> window top window left side window right side

TBLX

PNTR

$EB cursor line

SEC -> cursor column

LINES $ED maximum screen height

COLUMNS SEE ->• 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).

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

E X A M P LE :

JSR $FFF3 ;find the I/O block

IO B A SE is not used in the C l28 but is included for compatibility and complete ness. It returns the address of the I/O block in .X and .Y.

NEW C l 28 KERNAL CALLS

The following system calls are a set o f extensions to the standard CBM jum p table.

They are specifically for the C l 28 and as such should not be considered as permanent additions to the standard jum p table. With the exception of C64 MODE, they are all true subroutines and will terminate via an RTS. As with all Kemal 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: none system map

.C = 0 -> select SPINP

,C = 1 —» select SPOUT none Calls:

RESULTS:

Registers:

Memory:

Flags:

.A used

CIA-1, MMU none

THE COMMODORE 128 OPERATING SYSTEM 443

E X A M P LE :

CLC

JSR $FF47 ;setup for fast serial input

The C 128/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 o f 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 values— consequently they cannot be pre served). 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:

.A —» device # (FA: 0-31) system map none none

Memory:

Flags:

.A used

.X used

.Y used none none

E X A M P LE :

LDA #$ 0 8

JSR $FF4A ;close all files on device

The FA T 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 Kemal BOOT routine.

444 COMMODORE 128

3. $FF4D C64MODE ;reconfigure system as a C64

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers:

Memory:

Flags:

E X A M P LE :

JM P $FF4D none system map none none none none none

;switch to C64 mode

There is no return fro m this routine.

The 8502 DDR and port are initialized, and the VIC is set to 1MHz (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 jum p 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 C l 28 mode; only a hardware reset or power off/on will restore the C l 28 mode of operation. A reset will always initiate C l 28 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:

.X = bank (0-15)

.Y = DMA controller command

DMA registers set up system map none none

M e m o ry :

F lags:

.A used

.X used changed as per command none

THE COMMODORE 128 OPERATING SYSTEM 445

E X A M P LE :

LDA # $ 0 0

STA $DF02

LDA # $ 2 0

STA $DF03

LDA # $ 0 0

STA $DF04

STA $DF05

STA $DF06

LDA # $ 4 0

STA $DF07

LDA # $ 1 F

STA $DF08

LDX # $ 0 0

LDY # $ 8 4

JSR $FF50

;setup C l28 base address

;low

;high

;setup expansion RAM address

;low

;high

;bank (0-n, where n = 3 if 256K)

;setup number of bytes

;low

;high

;C 128 bank

;DMA command to “ STASH”

;execute DMA command

DMA CALL is designed to communicate with an external expansion car tridge capable o f DMA and mapped into system memory at 102 ($DFxx). The

DMA CALL converts the logical C l 28 bank parameter to MMU configuration via

GETCFG, O R ’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 C l 28 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 # $ 0 0 ;C 128 bank

LDY # $ 8 4 ;DMA command to ‘STASH’

JSR $FF6B ;GETCFG

TAX

JSR $3F0 ;execute DMA command

446 COMMODORE 128

5. $FF53 BOOT CALL ;boot load program from disk

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers:

.A = drive number (ASCII)

.X = device number (0-31) system map none none

Memory:

Flags:

.A used

.X used

.Y used changed as per command

.C 1 if I/O error

E X A M P LE :

LDA # $ 3 0

LDX #$ 0 8

;drive 0

;device 8

JSR $FF53

BCS 10 ERROR

;BOOT

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. Close all open files on boot device.

b. Read track 1 sector 0 into TBUFFR ($B00).

c. Check for auto-boot header, RTS if not.

d. If (b lk # > 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 $01 $02 $03 $04 $05 $06

C B M adrl adrh bank b lk # title 0

A where: A = $07 + LEN(title)

B = A + LEN(filename)

C = B + 1

B C file 0 code

THE COMMODORE 128 OPERATING SYSTEM 447

The following examples illustrate the flexibility o f this layout. This loads and runs a

BASIC program:

$00 CBM

$03

—

» $00,$00,$00.$00

$07 -> NA M E,$00

$0C

$0D

$00

$A2,$13,$A0,$0B

$4C,$A5,$AF

$14 -> RU N“ PROGRAM ”

$20 $00

:key

:no other BOOT sector

:message “ NAM E”

:no filename

:code

:data (BASIC stmt)

This results in the message Booting N A M E ... being displayed and, utilizing a

C128 BASIC jum p table entry that finds and executes a BASIC statement, loads and runs the BASIC program named “ PRO G RA 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 h * CBM :key

$03 —» $00,$00,$00,$00 :no other BOOT sector

$07 —> $00

$0C —» $00

:no

:no message filename

$0D - » $20,$7D ,$F F ,$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

$ 0 D ,$20, $ 3 2 ,$ 2 E ,$20, $ 4 3 ,$ 3 1 , $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,$C 9, $31

$D0, $03,$4C ,$4D , $FF,$C 9, $32,$D0

$03,$4C , $03, $40,$C 9, $33,$D 0, $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.

448 COMMODORE 128

6. $FF56 PHOENIX ;init function cartridges

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers: none cartridge map none none

Memory:

Flags:

.A used

.X used

.Y used changed as per command none

E X A M P LE :

JSR $FF56 ;PHOENIX

The C l 28 Kernal initialization routine POLL creates a Physical Address

Table (PAT) containing the ID ’s of all 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 Kemal

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

$FF5C LKUPSA ;search tables for given SA

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers:

.A = LA (logical file number) if LKUPLA

.Y = SA (secondary address) if LKUPSA system map none none

M e m o ry :

F lags:

.A = LA (only if found)

.X = FA (only if found)

.Y = SA (only if found) none

.C = 0 if found

.C = 1 if not found

THE COMMODORE 128 OPERATING SYSTEM 449

E X A M P LE :

LDY # $ 6 0

AGAIN INY

CPY # $ 6 F

;find an available SA

BCS TOO MANY ;too many files open

JSR $FF5C ;LKUPSA

BCC AGAIN ;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: none system map none none

Memory:

Flags:

.A used

.X used

.Y used local variables swapped none

E X A M P LE :

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: $ 8 0 = 80-column, $ 0 0 = 40-column.

450 COMMODORE 128

10. $FF62 DLCHR ;init 80-col character RAM

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers: none system map none none

Memory:

Flags:

.A used

.X used

.Y used

8563 character RAM initialized none

E X A M P LE :

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:

.A = pointer to string adr

(lo/hi/bank)

.Y = string length

.X = key number (1-10) system map none none

M em o ry :

F lags:

.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 451

E X A M P LE :

LDA # $F A

LDY # $ 0 6

LDX # $ 0 A

JSR $FF65

BCS 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 C l 28 function key string with a user’s string. Keys 1-8 are F 1-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 HELP 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 o f 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:

E X A M P LE :

See OPEN

.A = BA, memory bank (0-15)

.X = FNBANK, filename bank system map none

SETNAM none

BA, FNBANK updated none

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 O PEN ’s. See the Kernal

OPEN, LOAD and SAVE calls for examples.

452 COMMODORE 128

13. $FF6B GETCFG ;lookup MMU data for given bank

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers:

Memory:

Flags:

.X = logical bank # (0-15) system map none none

.A = MMU configuration data none none

E X A M P LE :

LDX # $ 0 0

JSR $FF6B

STA $FF01

;logical bank 0 (RAM O)

;GETCFG

;setup MMU pre-config #1

G E T C F G 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 concern ing memory configuration. The C128 Kemal memory banks are assigned as follows: o. %oo l i n n RAM 0 only

1. %01 1 1 11 1 1

2. %1 0 1 11 1 11

RAM 1 only

RAM 2 only

3. % 1 1111111 RAM 3 only

4. % 0 0 0 1 0 1 1 0 INT ROM, RAM 0, I/O

5. % 0 1 0 1 0 1 1 0 INT ROM, RAM 1, I/O

6. % 1 0 0 1 0 1 1 0 INT ROM, RAM 2, I/O

7. % 1 1010110 INT ROM, RAM 3, I/O

8. % 0 0 1 0 1 0 1 0 EXT ROM, RAM 0, I/O

9. % 0 1 101010 EXT ROM, RAM 1, I/O

10. % 1 0 1 0 1 0 1 0

11. % 1 1101010

EXT ROM, RAM 2, I/O

EXT ROM, RAM 3, I/O

12. % 0 0 0 0 0 1 1 0 KERNAL, INT LO, RAM 0, I/O

13. % 0 0 0 0 1 0 1 0 KERNAL, EXT LO, RAM 0, I/O

14. %0 00 0 0 00 1 KERNAL, BASIC, RAM 0, CHAR ROM

15. % 0 0 0 0 0 0 0 0 KERNAL, BASIC, RAM 0, I/O

THE COMMODORE 128 OPERATING SYSTEM 453

14. $FF6E JSRFAR ;gosub in another bank

15. $FF71 JMPFAR ;goto another bank

PREPARATION:

Registers:

Memory: none system map, also:

$02 bank (0-15)

$03 PC high

$04 -> PC low

$05 .S (status)

$06

$07

$08 none none

Flags:

Calls:

RESULTS:

Registers:

Memory: none as per call, also:

$05 —> .S (status)

$06 -> .A

$07 .X

$08 .Y none Flags:

The two routines, JSRFAR and JM PFAR, enable code executing in the system bank of memory to call (or JM P 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 NM I’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 IR Q ’s and N M I’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 $08

STX $07

STA $06

PHP

PLA

STA $05

;assumes registers and status

;already setup for call

454 COMMODORE 128

LDA #1

LDY # $ 2 0

LDX # $ 0 0

STA $02

STY $03

STX $04

JSR $FF6E

LDA $05

PHA

LDA $06

LDX $07

LDY $08

PLP

;want to call $2000 in bank 1

;JSRFAR

;restore status and registers

16. $FF74 INDFET ;LDA (fetvec),Y from any bank

PREPARATION:

Registers:

Memory:

Flags:

Calls:

RESULTS:

Registers:

.A = pointer to address

.X = bank (0—15)

.Y = index setup indirect vector none none

Memory:

Flags:

.A = data

.X used none status valid

E X A M P LE :

LDA # $ 0 0

STA $FA

LDA # $ 2 0

STA $FB

LDA # $ F A

LDX #$01

LDY # $ 0 0

JSR $FF74

BEQ etc

;setup to read $2000

;in bank 1

;LDA ($FA,RAM 1),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 455 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 (IR Q ’s and N M I’s) will be handled properly (or disabled beforehand).

17. $FF77 INDSTA ;STA (stavec),Y to any bank

PREPARATION:

Registers:

Memory:

.A = data

.X = bank (0-15)

.Y = index setup indirect vector setup STAVEC ($2B9) pointer none none

Flags:

Calls:

RESULTS:

Registers:

Memory:

Flags:

.X used changed per call status invalid

E X A M P LE :

LDA # $ 0 0

STA $FA

LDA # $ 2 0

STA $FB

LDA # $ F A

STA $2B9

LDA data

LDX #$01

LDY # $ 0 0

JSR $FF77

;setup write to $2000

;in bank 1

;STA ($FA,RAM 1),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 N M I’s) will be handled properly (or disabled beforehand).

456 COMMODORE 128

18. $FF7A INDCMP ;CMP (cmpvec),Y to any bank

PREPARATION:

Registers:

Memory:

.A = data

.X = bank (0-15)

.Y = index setup indirect vector setup CMPVEC ($2C8) pointer none none

Flags:

Calls:

RESULTS:

Registers:

Memory:

Flags:

.X used none status valid

E X A M P LE :

LDA # $ 0 0

STA $FA

LDA # $ 2 0

STA $FB

LDA # $F A

STA $2C3

LDA data

LDX #$01

LDY # $ 0 0

JSR $FF7A

BEQ same

;setup to verify $2000

;in bank 1

;CMP ($FA,RAM 1),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 JM P’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 N M I’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 457

RESULTS:

Registers:

Memory:

Flags: none none none

E X A M P LE :

JSR $FF7D ;display following text

.BYTE “ m essage”

.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.

C l 28 DEVICE NUMBERS

The following are the device numbers for the Commodore 128:

0 —* Keyboard

1 —» Cassette

2 -> RS-232

3 —» Screen (current)

4 —» Serial bus device:

4—7 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.

458 COMMODORE 128

MEMORY MANAGEMENT IN

THE COMMODORE 128

COM MODORE 128 MODE

In Commodore 128 mode, all memory management organization depends on the cur rently selected memory configuration. In C128 BASIC and the Machine Language

M onitor, 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 C l28 on system power-up.

BANK

1 0

1 1

1 2

CONFIG U RATIO N

RAM(O) only

R A M (l) only

RAM (2) only (same as 0)

RAM (3) only (same as 1)

Internal R ()M ,R A M (0),I/0

Internal R 0 M ,R A M (l),I /0

Internal R 0 M ,R A M (2 ),I /0 (same as 4)

Internal R 0 M ,R A M (3 ),I/0 (same as 5)

External R C)M ,R AM (0),I/0

External R 0 M ,R A M (l),I /0

External R 0 M ,R A M (2 ),I/0 (same as

)

External R 0 M ,R A M (3 ),I/0 (same as 9)

Kernal and Internal ROM (LOW ), R A M (0),I/0

Kernal and External ROM (LOW ), R A M (0),I/0

Kernal and BASIC ROM , RAM (0), Character ROM

Kernal and BASIC ROM , RAM(O), I/O

Figure 13-3. M e m o ry C o n figuration (B a n k ) T ab le

THE MEMORY MANAGEMENT

U N IT (M M U)

In Commodore 128 mode, all memory management is controlled through a series of

I/O registers called the Memory M anagement Unit (MMU). The Memory Manage ment Unit consists o f 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 459

When this occurs, some features of the MMU are no longer available to the programmer. So before switching out I/O in the $D 000-$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.

$ F F 0 4 -----

$ F F 0 3 -----

$ F F 0 2 ------

$ F F 0 1 ------

$ F F 0 0 ------

L C R D

L C R C

L C R B

L C R A

- L O A D C O N F I G U R A T I O N R E G D

- L O R D C O N F I G U R A T I O N R E G C

- L O A D C O N F I G U R A T I O N R E G B

- L O A D C O N F I G U R A T I O N R E G A

- C O N F I G U R A T I O N R E G I S T E R

$ D 5 0 B ----

$ D 5 Q H ----

$ 0 5 0 9 ----

$ D 5 0 8 ----

$ 0 5 0 7 ----

$ D 5 0 6 ----

$ 0 5 0 5 ----

$ D 5 0 4 ----

$ 0 5 0 3 ----

$ 0 5 0 2 ----

$ D 5 0 1 ----

$ 0 5 0 0 ----

P 1 H

P 1 L

P 0 H

P O L

R C R

M C R

P C R D

P C R C

P C R B

P C R H

Figure 13-4. M M U Register M ap

- V E R S I O N R E G I S T E R

- P A G E 1 P O I N T E R H I G H

- P A G E 1 P O I N T E R L O W

- P A G E 0 P O I N T E R H I G H

- P A G E 0 P O I N T E R L O N

- R A M C 0 N F I G 0 R A T I 0 N R E G I S T E R

- M O D E C O N F I G U R A T I O N R E G I S T E R

- P R E C O N F I G U R A T I O N R E G I S T E R 0

- P R E C O N F I G U R A T I O N R E G I S T E R C

- P R E C O N F I G U R A T I O N R E G I S T E R B

- P R E C O N F I G U R A T I O N R E G I S T E R A

^ - C O N F I G U R A T I O N R E G I S T E R

H O W T O SW ITCH 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 com puter’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

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 o f the registers [in particular the Configuration Register (CR), Load Config uration 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 M onitor as they appear in Figure 13-3.

There are four PC R ’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 o f 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 o f 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.

TH E C O N FIG U R A TIO N 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 Commo dore 128 memory in C l 28 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. W hen 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 461

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 manage ment 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 Kemal 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 o f the value of bits 4 and 5 o f 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 imple mented. When bit 6 is high (1), RAM bank 1 is selected. When bit 6 is low (0), RAM bank 0 is selected.

The 128K o f 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

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 S EL EC T

6 5

HI SPA CE

($C000-$FFFF)

4 3

M ID-SPACE

($8000-$BFFF)

2 1 0

LO -SPA CE

($4000-

$7FFF)

I/O SPA CE

($D000-

$DFFF)

00 = RAM BANK 0

01 = RAM BANK 1

10 = EXPANSION BANK 2

11 = EXPANSION BANK 3

00 = K ERNA L ROM

01 = INT. FU NCTIO N ROM

10 = EXT. FU NCTIO N ROM

11 = RAM

00 = BASIC ROM HI

01 = IN T. FU NCTIO N ROM

10 = EX T. FU NCTIO N ROM

1 1 = RAM

0 = BASIC

RO M LO

1 = RAM

0 = 1/0

REGISTERS

1 = RAM/ROM

Figure 13-5. C o n fig uratio n Register

PRECONFIGURING COMMODORE 128 MEMORY

As noted, the Configuration Register in the MMU is the means by which the Commo dore 128 organizes the memory layout. Commodore 128 memory management has a mechanism that allows the programmer to set up four predefined memory configura tions besides the one already operating. The four Preconfiguration Registers (PCR) and the four Load Configuration Registers (LCR) are designed to provide this feature.

W hen 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 inter changeably; 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

L C R ’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

TH E COMMODORE 128 OPERATING SYSTEM 463 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.

$ F F 0 4 -----

$ F F 0 3 -----

$ F F 0 2 -----

$ F F Q 1 -----

$ F F 0 0 -----

L C R D

L C R C

L C R B

L C R R

L O R D C O N F I G U R A T I O N R E G R

C O N F I G U R A T I O N R E G I S T E R

$ D 5 0 B -----

$ D 5 0 A -----

$ 0 5 0 9 -----

$ 0 5 0 8 -----

$ D 5 0 7 -----

$ D 5 0 6 -----

$ 0 5 0 5 -----

$ D 5 0 U -----

$ 0 5 0 3 -----

$ 0 5 0 2 -----

$ 0 5 0 1 -----

$ 0 5 0 0 -----

P 1 H

P 1L

P 0 H

P O L

R C R

M C R

P C R D

P C R C

P C R B

P C R R

P R E C 0 N F I G U R A T I O N R E G I S T E R A

C O N F I G U R A T I O N R E G I S T E R

Figure 13-6. M M U Register M ap

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.

W hen 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:

464 COMMODORE 128

PART 1

PART 2

LDA # $ 0 E

STA $D501

STA $FF01

Load accumulator with 14

This selects

I/O ($D000-$DFFF)

RAM ($4000-$7FFF,$8000-$BFFF)

Kernal and Character ROM ($C000-$FFFF)

RAM Bank 0

Store in PCR A— no immediate results

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 organiza tion 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

I/O

RAM

Kernal, Char

RAM BANK 0

ADDRESS RANGE

$D 000-$DFFF

$4000-$7FFF

$8000-$B FFF

$C 000-$FFFF

BIT(S) AFFECTED IN CR

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 micro processor. 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 PC R ’s are not acces sible 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 465 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, Kemal and character ROM, internal and external function ROM, and I/O. The MMU has additional registers that determine the mode (C l28, 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 regis ters o f the Memory Management Unit operate.

THE MODE C O N FIG U R A TIO N REGISTER

The Mode Configuration Register (MCR) specifies which microprocessor is .currently in operation (8502, Z80A) and which operating system mode is currently invoked ( C l28 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 o f 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 MSI 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 /GAM E 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

466 COMMODORE 128 mode is selected. Thus, a C l 28 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 C l 28 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 40/ 80 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 7

5 4 3

2 1 0

Mode Configuration Register

V A L U E

BIT FU N CTIO N D ESCRIPTION H IG H LOW

/Select m icroprocessor

1 Unused

2 Unused

3 Fast serial DD control

4 /GAME Access game cartridge

(C64 mode only)

5 /EXRO M Access external software cartridge (C64 mode only)

Select operating system

7 Read position

4 0 / 8 0 key

8502

—

Fast serial out

Z80A (inverted)

—

Fast serial in

C64 mode set on power up

C64 mode C128 m ode,

(M M U disappears assert MMU from memory map) registers

40/80 column key is UP

40/80 column key is DOWN

Figure 13-7. M ode C o n fig uratio n Register S u m m a ry

THE COMMODORE 128 OPERATING SYSTEM 467

TH E RAM C O N FIG U R A TIO N 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 o f shared RAM between banks. If both bits 0 and 1 equal 0, IK of RAM becomes common. If bit 0 is equal to 1 (high) and bit 1 is low (0), then 4K o f 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.

468 COMMODORE 128

BANKO

$F000

Hi Common RAM

BANK 1 BANKO

$F000 •

Hi Common RAM

BANK 1

S03FF

Low Common RAM

1KCOMMON RAM

BANK 1 BANKO

$E000 -

Hi Common

RAM

$0FFF

Low Common RAM

4KCOMMON RAM

BANK 1 BANKO

Common

RAM

$C000 -

$0FFF -

Low

RAM

$03FF -

Low Common

RAM

8 K C O M M O N RAM

Figure 13 -8 . C o m m o n RAM

16K 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),

THE COMMODORE 128 OPERATING SYSTEM 469 a section o f the bottom of RAM bank 0 replaces the corresponding section o f 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 CASO enable line low and CAS 1 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 o f 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 CASO 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 7

5 4 3

2 1 0

RAM Configuration Register

BITS FUNCTIONAL DESCRIPTIO N

1 0

- Determine amount o f shared RAM between RAM banks

= IK common RAM

= 4K comm on RAM

K common RAM

= 16K common RAM

- Determine which portions o f RAM are shared

= No comm on RAM

= Bottom o f RAM bank 0 is common

= Top o f RAM bank 0 is common

= Both top and bottom o f RAM bank 0 are common

5 4

- Not implemented; reserved for future expansion

- Selects RAM bank for the VIC chip (Bit 7 is ignored)

= Select Bank 0 for VIC chip

= Select Bank 1 for VIC chip

Note: X = not implemented

Figure 13-9. R A M C o n fig uratio n Register S u m m ary

470 COMMODORE 128

TH E PAGE POINTERS

The Commodore 128 has a feature that allows you to relocate page 0 ($00-$FF) and page 1 ($100-$1FF) 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 Page 0 Pointer (low)

$D508 Page 0 Pointer (high)

$D509 Page 1 Pointer (low)

$D50A Page 1 Pointer (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 CASO 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. W hen 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 o f 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 o f whether the RAM is zero page, page one or any other page of RAM memory. If you need to use the

Kem al, the necessary variables required for the Kemal 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 471

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. Other wise, 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.

TH E 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 C l 28 memory. This allows the programmer to check the version of the C l 28 and the memory size, and make it compatible with systems that will be expanded in the future. The current version of the C l 28 contains the value $20, signifying two 64K blocks.

A U T O STARTING A

ROM

APPLICATIO N 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 C l 28 and C64 modes.

COM MODORE 128 MODE

Any C64 cartridge is asserted automatically if the system recognizes the /GAME or

/EXROM as being pulled low.

If any C l 28 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).

472 COMMODORE 128

The first 9 bytes of the Commodore 128 auto start sequence are:

BYTE

$X000 Cold Start Vector

$X003 Warm Start Vector (not used but must be specified)

$X006 Cartridge I.D . (The I.D . = 1 for an auto start card)

$X007 The ASCII Character “ C ” with the high bit set

$X008 The ASCII Character “ B ” with the high bit set

$X009 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

$XOOO

$X003

Cold Start Vector

Warm Start Vector

$X006 The ASCII Character “ C ” with the high bit set

$X007 The ASCII Character “ B ” with the high bit set

$X008 The ASCII Character “ M ” with the high bit set

$X009 The ASCII Character “

” with the high bit set

$X00A 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

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 473

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.

C l 28 EDITOR ESCAPE CODES

To use the following ESCAPE functions, press the E S C A P E key and then press the key for the function you want.

KEY

V w

FUNCTION

Enable auto-insert mode

Set bottom right o f 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 o f 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 o f current line

Erase to end o f 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 o f screen

474 COMMODORE 128

C l 28 EDITOR C O N TRO L 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

1 1

1 2

130

143

1 0

[

Underline ON (80-column screen only)

Produces bell tone

Tab character

Line feed character

Disable shift Commodore key (formerly code 9)

Enable shift Commodore key (formerly code

)

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)

C l 28 EDITOR JUMP TABLE

The editor calls listed below are a set of extensions to the standard CBM jum p table.

They are specifically for the C l 28 and should not be considered as permanent additions to the standard jum p 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 475

$C000 CINT

$C003 DISPLY

$C006 LP2

SC009 LOOP5

$C00C PRINT

$C00F SCRORG

$C012 SCNKEY

$C015 REPEAT

$C018 PLOT

1 0

$C018 CURSOR

1 1

$C01E ESCAPE in itia lize 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 o f current window

;scan keyboard subroutine

;repeat key logic and CKIT2

;read or set cursor position

;move 8563 cursor subroutine

;execute escape function

1 2

$C021 KEYSET

13.

$C024 IRQ

14.

$C027 INIT80

;redefine a programm able key

;irq entry in itia lize 80-column char set

15.

$C02A SW APPER ;40/80 mode change

16.

$C02D WINDOW ;set UL or BR o f window

17.

$C033 LDTB2 ;screen lines low byte table

;screen lines high byte table 18.

$C04C LDTB1

19.

$334 CONTRL

2 0

2 1

$336

$338

SHIFTD

ESCAPE

;print C T R L indirect

;print S H F T indirect

;print E S C indirect

2 2

$33A

23.

$33C

24.

$33E

KEYVEC ;keyscan logic indirect

KEYCHK ;keyscan store indirect

DECODE ;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.

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-C 128-dependent aspects of CP/M on the Commodore

128. For detailed information on C l 28-dependent CP/M 3.0, see Appendix K o f this guide. For detailed information on non-C 128-dependent CP/M 3.0, see the Commodore- produced volume that includes D RI’s CPIM 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 o f 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 press ing the C O N T R O L key and the appropriate CURSOR key

(left or right).

CP/M 3.0 can also be used with the 1541 disk drive. In this case, only single sided 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 ON TH E COMMODORE 128 479

COMMODORE ENHANCEMENTS

T O 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 o f 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:

■ PR O G R A M 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 o f a collection of related information (e.g ., a list of customer names and addresses; inventory records; accounting records; the text o f a document).

FILE SPECIFICATION

A CP/M file is identified by a file specification that can consist o f up to four individual elements, as follows:

■ D rive 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.)

■ Filenam e (mandatory), which can be from one to eight characters long. (Note that this is the only mandatory element of the file specification.) a 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. M ust be separated from the filetype (or filename, if no filetype is included) by a semicolon.

E X A M P LE :

The following file specification contains all four possible elements, all separated by the appropriate symbols:

A:DOCUMENT.LAW ;FIREBIRD

480 COMMODORE 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 the CP/M text editor (ED).

■ Using the PIP command to copy and rename a file.

■ Using a program such as MAC (a CP/M machine language assembler program), which creates output files as it processes input files.

USING W ILDCARD CHARACTERS TO

ACCESS MORE T H A N ONE FILE

A wildcard is a character that can be used in a filename or filetype in place o f 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 wild card 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.

CH ARACTER MEANING

<$, :!>[]

T A B , S P A C E ,

C A R R I A G E R E T U R N ]

]

File specification delimiters

;

* ?

< > & ! I \ H—

[ ]

( )

/ $

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

Option list delimiters

Option list delimiters for global and local options

D elim iters for m ultiple m odifiers inside square brackets for options that have modifiers

Option delimiters in a command line

T a b le 14-1. C P /M 3.0 Reserved C haracters

CP/M 3.0 O N THE COMMODORE 128 481

RESERVED FILETYPES

The filetypes defined in Table 14—2 are reserved for system use.

ASM

BAS

COM

HEX

HLP

$$$

PRN

REL

SUB

SYM

SYS

RSX

FILETY PE MEANING

Assembler source file

BASIC source program

Z80 or equivalent machine language program

Output file from MAC (used by HEXCOM)

HELP message file

Tem porary file

Print file from MAC or RMAC

Output file from RMAC (used by LINK)

List o f commands to be executed by SUBMIT

Symbol file from M AC, RMAC or LINK

System file

Resident System Extension (a file autom atically loaded by a comm and file when needed)

T a b le 14-2. C P /M 3.0 Reserved Filetypes

CP/M COMMANDS

There are two types o f commands in CP/M 3.0:

■ Built-in commands, which identify programs in memory.

■ Transient utility commands, which identify program 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-com patible application programs. In addition, experienced programmers can write utilities that operate with CP/M 3.0.

BUILT-IN COM M ANDS

Built-in commands are entered in the com puter’s memory when CP/M 3.0 is loaded, and are always available for use, regardless of which disk is in which drive. Table 14—3 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 com mand and has a filetype of COM.

482 COMMODORE 128

COMMAND FUNCTION

DIR

DIRSYS

Displays filenames of all files in the directory except those marked with the SYS attribute.

Displays filenam es o f 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.

T a b le 14-3. B u ilt-In C om m ands

TR AN SIEN T U T IL IT Y COM M ANDS

The CP/M 3.0 transient utility commands are listed in Table 14-4. When a command key word 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 CONTRO L CHARACTERS

FOR LINE EDITING

Table 14—5 lists the line-editing control characters for CP/M 3.0 on the Commodore 128.

H O W T O MAKE COPIES OF

CP/M 3.0 DISKS A N D FILES

NOTE: The Digital Research Inc. COPYSYS command, used in many

CP/M systems in formatting a disk, is not implemented on the Commo dore 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 C l28 single-sided or C l 28 double-sided diskette.

CP/M 3.0 ON THE COMMODORE 128 483

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

DUM P

Displays directory with files and their characteristics.

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 T em porarily gets console input from a disk file rather than the keyboard.

FORM AT Initializes disk in GCR format for CP/M use.

HELP Displays information on how to use CP/M 3.0 com m ands.

INITDIR Initializes a disk directory to allow time and date stamping.

KEYFIG Allows redefinition o f keys.

PATCH Displays or installs patches to CP/M system .

PIP

PUT

Copies files and combines files.

Temporarily directs printer or console output to a disk file.

R ENAM E Changes the name of a file, or a group of files, using wildcard characters.

SAVE

SET

Saves a program in memory to disk.

Sets file options including disk labels, file attributes, type o f time and date stam ping and password protection.

SETDEF Sets system options including the drive search chain.

SHOW Displays disk and drive statistics.

SUBM IT Automatically executes multiple comm ands.

TYPE Displays contents of text file (or group o f files, if wildcard characters are used) on screen (and printer if desired).

T a b le 14-4. T ran sie n t U tility C o m m an ds

484 COMMODORE 128

CH ARACTER MEANING

CTRL-A or

SHIFT-LEFT CURSOR

CTRL-B

Moves the cursor one character to the left.

CTRL-E

Moves the cursor to the beginning of the command line without having any effect on the contents o f the line. If the cursor is at the beginning, CTRL-B moves it to the end o f the line.

Forces a physical carriage return but does not send the command line to CP/M 3.0. M oves the cursor to the begin ning o f the next line without erasing the previous input.

Moves the cursor one character to the right.

CTRL-F or

RIGHT CURSOR

CTRL-G Deletes the character at current cursor position. The cursor does not m ove. Characters to the right o f the cursor shift left one place.

CTRL-H Deletes the character to the left o f the cursor and moves the cursor left one character position. Characters to the right o f the cursor shift left one place.

CTRL-I Moves the cursor to the next tab stop. Tab stops are auto matically set at each eighth colum n. Has the sam e effect as pressing the T A B key.

CTRL-J Sends the command line to CP/M 3.0 and returns the cursor to the beginning o f a new line. Has the same effect as a

R E T U R N or a CTRL-M keystroke.

CTRL-K Deletes to the end o f the line from the cursor.

CTRL-M 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.

CTRL-R 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.

CTRL-U

CTRL-W or f CRSR | Recalls and displays previously entered command line both at the operating system level and within executing program s, 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 in the comm and line, places a

# character at the current cursor position, and m oves the cursor to the next line. However, you can use a CTRL-W to recall any characters that were to the left o f the cursor when you pressed CTRL-U.

Discards all the characters left of the cursor and m oves the cursor to the beginning o f the current line. CTRL-X saves any characters to the right of the cursor.

T a b le 14-5. C P /M 3.0 Line-Editing C o n tro l C haracters

CP/M 3.0 O N TH E COMMODORE 128 485

MAKING COPIES W IT H 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 >FO R M A T and follow the instructions given on the screen. When the copy disk is formatted, type:

A > P IP E: = A :C PM + .SYS

When the CPM + SYS file is copied, you type:

A > P IP E: = A:CCP.COM

To copy everything on a disk, use the following command sequence:

A >FO R M A T

A > P IP 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 hardware— it is strictly a logical drive.

M AKING COPIES W IT H T W O 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 IP B: = A:CPM + .SYS

W hen 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 IP 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.

486 COMMODORE (28

GENERAL CP/M 3.0 SYSTEM LA YO U T

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 C l 28.

When CP/M is running, the normal functions of the C l 28 are not supported

(CP/M and BASIC cannot run at the same time). Also, CP/M does not directly support all the display modes o f 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

C O M PO NENTS

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 o f the operating system. The CCP supplies the six built-in commands: DIR, DIRS, ERASE,

RENAM E, 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 particu lar hardware environment. The BIOS performs all physical I/O in the system. The BIOS consists o f 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.

C O M M U N IC A T IO N 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 ON THE COMMODORE 128 487

The BDOS contains a set o f 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, C O N IN 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 o f 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 o f 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 o f the operating system. If a program modifies these parameters, the operating system can crash. See Section 3 of the DRI CPIM Plus System Guide and the description of

BDOS Function 49 in the DRI CPIM 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, includ ing 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 jum p 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.

O R G A N IZ A T IO N 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 CPIM 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,

488 COMMODORE 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 jum p vectors. The jum p table is a set of thirty-three jump instructions that pass program control to the individual BIOS subroutines.

NO.

INSTRUCTION D ESCRIPTION

JM P BOOT

JM P WBOOT

Perform cold start initialization.

Perform warm start initialization.

JM P CONST Check for console input character ready.

3 JM P CONIN Read console character in.

4 JM P CONOUT Write console character out.

5 JM P LIST Write list character out.

JM P AUXOUT Write auxiliary output character.

7 JM P AUXIN Read auxiliary input character.

JM P HOME

JM P SELDSK

Move to Track 00 on selected disk.

Select disk drive.

1 0

1 1

JM P SETTRK

JM P SETSEC

Set track number.

Set sector number.

1 2 JM P SETDMA Set DMA address.

13 JM P READ Read specified sector.

14 JM P W RITE

15 JM P LISTST

Write specified sector.

Return list status.

16 JM P SECTRN Translate logical to physical sector.

17 JM P CONOST Return output status of console.

18 JM P AUXIST Return input status o f aux. port.

19 JM P AUXOST Return output status o f aux. port.

2 0

2 1

JM P DEVTBL Return address o f char. I/O table.

JM P DEVINI Initialize char. I/O devices.

2 2

JM P DRVTBL Return address of disk drive table.

23 JM P MULTIO Set number o f logically consecutive sectors to be read or

24 JM P FLUSH

25 JM P MOVE

26 JM P TIME written.

Force physical buffer flushing for user-supported deblocking.

Memory to memory move.

Time set/get signal.

27 JM P SELMEM Select bank of memory.

28 JM P SETBNK

29 JM P XMOVE

Specify banks for inter-bank M OVE.

Set banks for an inter-bank MOVE.

30 JM P USERF Commodore CP/M system functions.

31 JM P RESERV1 Reserved for future use.

32 JM P RESERV2 Reserved for future use.

T a b le 14-6. C P /M 3.0 B IO S Jump V ectors

CP/M 3.0 O N THE COMMODORE 128 489

BIOS.

All the entry points in the BIOS jum p vector are included in the C l 28 CP/M 3.0

Each jum p 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 o f 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.

O PERA TIO N

System

Initialization

FUNCTION

BOOT, W BOO T, D EVTBL, DEV IN I, DRVTBL

Character I/O CONST, CONIN, CONOUT, LIST, AUXOUT, A UXIN, LISTST,

CONOST, AUXIST, AUXOST

Disk I/O HOM E, SELDSK, SETTRK, SETSEC, SETDM A, REA D, W R ITE,

SECTRN, M ULTIO, FLUSH

Memory Selects and Moves

M OVE, SELM EM , SETBNK, XMOVE

Clock Support TIME

T a b le 14-7. C P /M 3 B IO S Functions

Appendix K illustrates how to call a Commodore CP/M system function in Z80 machine language.

SYSTEM MEMORY

O R G A N IZA TIO N

Figure 14—1 shows the general memory organization of CP/M 3.0.

490 128

F000

EOOO

DOOO

COOO

BOOO

AOOO

9000

8000

7000

6000

5000

4000

3000

2000

1000

0000

C O M M O N SY STEM M E M O R Y

B A N K E D SYSTEM

C C P BUFFER

VIC SCREEN

8502 BIOS

40-COLUMN

LOGICAL SCREEN

KEY TABLES

R O M C O D E

14-1. C P /M 3.0 G en eral M e m o ry O rg an iza tio n

T

A

CP/M 3.0 O N THE COMMODORE 128 491

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 O R G A N IZA TIO N

CP/M 3.0 supports a number o f 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 o f the full disk capacity by setting up the FCB with 638 tracks of 1 sector each and a track offset o f 0.

This has the effect o f having CP/M set the track to the block number relative to the beginning o f 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 > = TRACK > 355

355 > = TRACK > 487

487 > = TRACK > 595

595 > = TRACK > 680

680 > = TRACK > 1360

ACTUAL TRACK

((TRACK + 1)121) + 1

((TRACK - 354)/19) + 18

((TRACK - 487V18) + 25

((TRACK - 595)/17) + 31

SET SIDE 2 TRACK = TRACK - 680

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.

N O T E : 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

C64 GCR single-sided

C128 GCR single-sided

C128 GCR d o ub le-sided

MFM fo r m a t

1541 DRIVE

1571 DRIVE

C64 CP/M DISK FORMAT

(SINGLE-SIDED)

This format, shown in Figure 14—2, is provided to allow the user to read/write files created using the C64 CP/M 2.2 cartridge. (However, do n o t use the CP/M 2.2 cartridge with the C128.) Notice the unused space in this format.

CP/M 3.0 ON THE COMMODORE 128 493

S E C T O R

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

0 B B B B B B B B B B B B B B B B B

X X X X

1 B B B B B B B B B B B B B B B B B x

2 x

X X

17 D D D D D D D D D D D D D D D D D D D

0 ...............................................................

1 ......................................................

...............................................................

. U sed by C P /M .

B B oot S ecto r (System ).

D D ire c to ry S ecto r (D isk D O S), x N ot u sed by C P /M .

Figure 14-2. C 64 C /P M Disk F o rm a t

C l 28 CP/M DISK FORMATS

(SINGLE- A N D DOUBLE-SIDED)

F ig u re 1 4 -3 sh o w s th e C l 28 C P /M P lu s fo rm a t fo r a sin g le -s id e d d isk .

494 COMMODORE 128

S E C T O R

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

0 B .

X ...........................................................................................................................

...................................................................................................................

2 ...........................................................................................................................................................................

3 ................................................................................................................................................................

4 ................................................................................................................................................................

5 ................................................................................................................................................................

6 ................................................................................................................................................................

7 ................................................................................................................................................................

8 ................................................................................................................................................................

...........................................................................................................................................................................

1 0 ...........................................................................................................................................................................

1 1 ...........................................................................................................................................................................

1 2 ...........................................................................................................................................................................

1 3 ..................................................................................................................................................................

1 4 ..................................................................................................................................................................

1 5 ...................................................................................................................................................................

1 6 .................................................................................................................................

1 7 ................................................................................................................................................

18 D .................................................................................................................................................

1 9 ................................................................................................................................................

2 0 ...................................................................................................................

2 1 .........................................................................................................................................................

2 2 .........................................................................................................................................................

2 3 .................................................................................................................................................

2 4 .......................................................................................................................................

2 5 .......................................................................................................................................

2 6

.................................................................................................................

7 .......................................................................................................................................

2 8 ...................................................................................................................

9 .......................................................................................................................................

0 ..............................................................................................................................

3 1 ...............................................................................................................................

3 2 ..............................................................................................................................

..............................................................................................................................

U sed by C P /M , re g . = reg io n (1-4).

B B oot S ecto r (System ).

D D irecto ry S ecto r (Disk D O S), x N ot used by C P /M .

SK EW TABLE

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

1 00 17 13 09 05 01 18 14 10 06 02 19 15 11 07 03 20 16 12 08

2 00 04 08 12 16 01 05 09 13 17 02 06 10 14 18 03 07 11 15

3 00 11 04 15 08 01 12 05 16 09 02 13 06 17 10 03 14 07

4 00 07 14 04 11 01 08 15 05 12 02 09 16 06 13 03 10

Figure 14-3. C l 28 C P /M Plus Disk F o rm a t

CP/M 3.0 ON THE COMMODORE 128 495

N O T E : 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 C l 28. 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 C l 28, 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 o f 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.

N O T E : 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.

496 COMMODORE 128

KEYBOARD SCANNING

The keyboard scan routine that is called to get a keyboard character returns the key code o f 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:

L E F T S H I F T

R I G H T S H I F T

S H I F T L O C K

C O N T R O L

R E S T O R E ( 8502 N M I )

40/ 80 D I S P L A Y

C A P S LOCK KEY

The keyboard recognizes the following special functions:

Cursor left key-U sed to define a key

Cursor right key-Used to define a string

(points to function keys)

ALT key-U sed 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.

D EFINING A KEY

The K E Y F IG 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 o f the codes that can be assigned to a key. See KEYFIG HELP for more information.

CP/M 3.0 O N TH E COMMODORE 128 497

CODE FUNCTION

0 0 h Null (same as not pressing a key)

Olh to 7Fh Normal ASCII codes

80h to 9Fh String assigned

AOh to AFh 80-column character color

BOh to BFh 80-column background color

COh to CFh 40-column character color

DOh to DFh 40-column background color

EOh to EFh 40-column border color

FOh Toggle disk status on/off

F lh

F2h

F3h

System Pause

(Undefined)

40-column screen window right

F4h 40-column screen window left

F5h to FFh (Undefined)

DEFINING A STRING

The D E FIN E ST R IN G 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 o f 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 RI GHT

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

R E T U R N

4- symbol*

— symbol*

Right Cursor

Left Cursor

FUNCTION

End string definition.

Insert space in string.

Delete cursor character.

Move cursor to right.

Move cursor to left.

*On main keyboard only.

A LT 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.

498 COMMODORE 128

U PD A TIN G THE

40/80 COLUM N 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 C l 28 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 ADM-31 (ADM-3A is a subset of this) driver. The terminal driver is divided into two parts: term inal emulation and term inal functions. Term inal em ulation 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.

TERM INAL EM ULATIO N PROTOCOLS

FUNCTION CHARACTER SEQUENCE HEX CHAR CODE

Position Cursor

Cursor Left

Cursor Right

Cursor Down Control J

Cursor Up Control K

Home and Clear Screen Control Z

Carriage Return

Escape

Bell

ESC (ro w # + 32) (c o l# + 32) IB 3D 2 0 + 20 +

Control H 08

Control L OC

Control M

Control [

Control G

NOTE: Display is 24 (1—24) by 80 (1-80); cursor origin is always 1/1.

Figure 14-4. L ear S iegler ADM-3A P rotocol

CP/M 3.0 O N THE COMMODORE 128 499

N O TE: The following have been added to allow the system to emulate the KayPro II display more closely.

FU N CTIO N

CH ARA CTER

SEQUENCE

Home Cursor Control t

CEL (Clear to End of Line) Control-X

CES (Clear to End of Screen) Control-W

CHARACTER SEQUENCE HEX CHARACTER CODES

Clear to end of line ESC T

ESC t

Clear to end of screen ESC Y

ESC

Home cursor and clear screen ESC y

H alf intensity on

H alf intensity off

Reverse video on

ESC *

ESC )

ESC (

ESC G4

Blinking on

Underline on *

ESC G2

ESC G3

Select alternate character set* ESC G1

IB 47 32

IB 47 33

Reverse video and blinking off ESC GO

Insert line

Insert character

Delete line

Delete character

Set screen colors*

ESC E

ESC Q

ESC R

IB 47 31

IB 47 30

IB 45

IB 51

IB 52

ESC W

ESC ESC ESC color #

IB 57 where color # = 20h to 2Fh haracter color

30h to 3Fh i— background color

40h to 4Fh border color (40 colum ns only)

50h to 50Fh character color

60h to 60Fh — background color

70h to 70Fh i— border color (40 colum ns only)

*Indicates this is not a normal ADM31 sequence.

IB 54

IB 74

IB 59

IB 79

IB 3A

IB 2A

IB 29

IB 28

IB 47 34

Note: Display is 24 (1 -2 4 ) by 80 (1-80); cursor origin is always 1/1.

Physical

Colors

Logical

Colors

F igure 14—5. L ear S iegler ADM-31 P rotocol

500 COMMODORE 128

SYSTEM OPERATIONS

SETTING SYSTEM TIME

The time of day is set with this function. The time o f 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.

U P D A T IN G SYSTEM TIME

The SCB time is updated from the time of day clock on the 6526 by doing a system call.

8502 BIOS O R G A N IZA TIO N

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 o f 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.

15 THE

COMMODORE 128

AND

COMMODORE 64

MEMORY MAPS

502 COMMODORE 128

MEMORY

ADDRESS

LABEL

D6510

R6510

BANK

PC—HI

P C _L O

S _R E G

A R E G

X _R E G

Y _R E G

STKPTR

This chapter provides the memory maps for both C l 28 and C64 modes. A memory map tells you exactly how memory is laid out internally in both RAM 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 o f 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 2 Column 3 Column 4 Column 1

MEMORY

ADDRESS

LABEL

HEXADECIMAL DECIMAL

ADDRESS ADDRESS DESCRIPTION

See Appendix K for the Z80 memory map for CP/M on the Commodore 128.

C l 28 MEMORY MAP

INTEGR

CHARAC

ENDCHR

TRM POS

VERCK

HEXADECIMAL DECIMAL

ADDRESS ADDRESS DESCRIPTION

0 0 0 0

0 0 0 1

0 0 0 2

0003

0004

0005

0006

0007

0008

0009

6510 DATA DIRECTION REGISTER

6510 DATA REGISTER

TOKEN ‘SEA R C H ’ LOOKS FOR , OR

BANK #

ADDRESS FOR BASIC SYS

C OM M AND OR M ONITOR AND

LONG CALL/JUM P ROUTINES

ADDRESS, STATUS, A-REG , X-REG ,

Y-REG

STATUS REG TEM P

.A REG TEMP

.X REG TEMP

.Y REG TEMP

STACK POINTER TEMP

0009

BASIC ZERO PAGE STORAGE

000A

000B oooc

1 0

1 1

1 2

SEARCH CHARACTER

FLAG: SCAN FOR QUOTE AT END

OF STRING

SCREEN COLUMN FROM LAST TAB

FLAG: 0 = LQAD,

= VERIFY

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 503

CHANNL

POKER

LINNUM

TEM PPT

LASTPT

TEM PST

INDEX

INDEX 1

INDEX2

RESHO

RESM OH

ADDEND

RESM O

RESLO

TXTTAB

VARTAB

C128 M emory M ap (continued)

M EM ORY

ADDRESS

LABEL

COUNT

DIM FLG

VALTYP

INTFLG

GARBFL

HEXADECIM AL DECIM AL

ADDRESS ADDRESS D ESCRIPTIO N

OOOD

OOOE

000F

0 0 1 0

0 0 1 1

INPUT BUF.PTR / # OF SUBSCRIPTS

FLAG: DEFAULT ARRAY DIMENSION

DATA TYPE: $FF = STRING ,

$00 = NUMERIC

DATA TYPE: $00 = FLO A T.PT ,

$80 = INTEGER

FLAG: DATA SCAN / LIST QUOTE /

GARBAGE COLLECTION

DORES

SUBFLG

0 0 1 2

INPFLG 0013 19

FLAG: SUBSCRIPT R EF. / USER

FUNC. CALL

FLAG: $00 = INPUT, $40 = GET,

$98 = READ

DOM ASK

TANSGN

0014

2 0

FLAG: TAN SIGN / COM PARISON

RESULT

ARYTAB

STREND

FRETOP

FRESPC

M A X _M E M _1

CURLIN

TXTPTR

FORM

FNDPNT

0015

0016

0018

0019

001B

0024

0026

0028

0029

002A

002B

002D

002F

0031

0033

0035

0037

0039

003B

003D

003F

2 1

2 2

TEM P INTEGER VALUE

POINTER: TEM P STRING STACK

LAST TEM P STRING ADDRESS

STACK FOR TEM P 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

4- 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

CHRG ET,ETC.

USED BY PRINT USING

POINTER TO ITEM FOUND BY

SEARCH

504 COMMODORE 128

OLDOV

TEMPF1

PTARG1

PTARG2

STR1

STR2

POSITN

M ATCH

ARYPNT

HIGHDS

HIGHTR

TEM PF2

DECCNT

C l28 M emory M ap (continued)

M EM ORY

ADDRESS

LA BEL

DATLIN

DATPTR

INPPTR

VARNAM

FDECPT

VARPNT

LSTPNT

FORPNT

HEXADECIM AL DECIM AL

ADDRESS ADDRESS D ESCRIPTION

0041

0043

0045

0047

0049

BASIC ZERO PAGE STORAGE

CURRENT DATA LINE NUM BER

VECTOR: INPUT ROUTINE

CURRENT DATA ITEM ADDRESS

C URRENT BASIC VARIABLE NAME

POINTER: CURRENT BASIC

VARIABLE DATA

004B 75

POINTER: INDEX V ARIABLE FOR

FOR/NEXT

ANDM SK

EORM SK

VARTXT

OPPTR

OPM ASK

GRBPNT

TEM PF3

DEFPNT

DSCPNT

004C

004D

004F

0050

HELPER

JM PER

0052

0054

0055

0056

0057

0058

0059

8 6

8 8

FLAGS ‘H ELP’ OR ‘L IST ’

005B

005D

0060

0063

0064

005A

005C

005E

005F

1 0 0

M ULTIPLY DEFINED FOR INSTR

NUM BER OF DIGITS AFTER THE

DECIM AL POINT

TENEXP

0060 96

ML M ONITOR Z .P. STORAGE IN

FAC

GRBTOP

DPTFLG

LOW TR

EXPSGN

FAC

0061

0062

0063

DECIM AL POINT FLAG

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 505

MEMORY

ADDRESS

LABEL

DSCTM P

LEFT__FLAG

FACEXP

R IG H T_FLA G

FACHO

FACM OH

INDICE

FACM O

FACLO

FACSGN

DEGREE

SGNFLG

ARGEXP

ARGHO

ARGM OH

IN IT _A S _0

ARGMO

ARGLO

ARGSGN

STRNG1

ARISGN

FACOV

STRNG2

POLYPT

CURTOL

FBUFPT

AUTINC

M VDFLG

Z _ P _ T E M P _ 1

HULP

KEYSIZ

SYNTM P

DSDESC

TXTPTR

TOS

RUNM OD

PARSTS

POINT

0078

0079

007A

007D

007F

0080

0067

0068

0069

006A

006B

006C

006D

006E

006F

0070

HEXADECIMAL DECIMAL

ADDRESS ADDRESS DESCRIPTION

BASIC ZERO PAGE STORAGE

0064

0065

0066

100

101

102

PAINT-LEFT FLAG

F A C #1E X P O N E N T

M ONITOR Z .P. STORAGE IN FAC

PAINT-RIGHT FLAG

F A C #1 MANTISSA

0071

0072

103

104

105

106

107

108

109

110

111

112

113

114

M ONITOR Z .P. STORAG E IN FAC

F A C # 1 SIGN

POINTER: SERIES-EVAL. CONSTANT

F A C # 2 E X P O N E N T

F A C # 2 M ANTISSA

JUST A COUNT FOR INIT

F A C # 2 SIGN

SIGN COM PARISON RESULT:

F A C #1 VS # 2

F A C # 1 LOW -ORDER (ROUNDING)

0074

0076

0077

116

118

119

120

121

122

125

127

128

POINTER: CASSETTE BUFFER

INC. VAL FOR AUTO (0 = OFF)

FLAG IF 10K HIRES ALLOCATED

PRINT USING ’S LEADING ZERO

COUNTER

M OVSPR & SPRITE TEM PORARY

M ID$ TEM PORARY

COUNTER

USED AS TEM P FOR INDIRECT

LOADS

DESCRIPTOR FOR DS$

M ONITOR Z .P. STORAGE

TOP OF RUN TIM E STACK

FLAGS RUN/DIRECT M ODE

DOS PARSER STATUS WORD

USING ’S POINTER TO DEC .PT

506 COMMODORE 128

STATUS

STKEY

SVXT

VERCK

C3P0

BSOUR

SYNO

XSAV

LDTND

DFLTN

DFLTO

PRTY

DPSW

M SGFLG

PTR1

T I

PTR2

TIME

R2D2

PCNTR

BSOUR1

FIRT

COUNT

CNTDN

BUFPT

C128 Memory Map (continued)

MEMORY

ADDRESS

LABEL

PARSTX

OLDSTK

HEXADECIMAL DECIMAL

ADDRESS ADDRESS DESCRIPTION

0081

0082

BASIC ZERO PAGE STORAGE

129

130

COLSEL

M U L T IC O L O R _l

M ULTICOLOR—2

FOREGRO UND

SC A L E _X

SC A L E _Y

STOPNB

BASIC Z-P STORAGE FOR GRAPHIC COMMANDS

0083

0084

0085

0086

0087

0089

008B

131

132

133

134

135

137

139

CURRENT COLOR SELECTED

SCALE FACTOR IN X

SCALE FACTOR IN Y

STOP PAINT IF NOT BACKGROUND/

NOT SAM E COLOR

GRAPNT

VTEMP1

VTEM P2

008C

008E

008F

140

142

143

0090

0091

0092

0093

0094

0095

0096

0097

0098

0099

009A

009B

009C

009D

009E

009F

00A0

00 A3

00A4

KERNAL/EDITOR STORAGE

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

163

164

I/O OPERATION STATUS BYTE

STOP KEY FLAG

TAPE TEM PORARY

LOAD OR VERIFY FLAG

SERIAL BUFFERED CHAR FLAG

CHAR BUFFER FOR SERIAL

CASSETTE SYNC #

TEM P FOR BASIN

INDEX TO LOG ICAL FILE

DEFAULT INPUT DEVICE #

DEFAULT OUTPUT DEVICE #

CASSETTE PARITY

CASSETTE DIPOLE SW ITCH

OS M ESSAGE FLAG

CASSETTE ERROR PASS1

TEM PORARY 1

CASSETTE ERROR PASS2

TEM PORARY 2

24 HOUR CLOCK IN 1/60TH SECONDS

SERIAL BUS USAGE

CASSETTE

TEM P USED BY SERIAL ROUTINE

00A5

00A6

165

166

TEM P USED BY SERIAL ROUTINE

CASSETTE SYNC COUNTDOW N

CASSETTE BUFFER POINTER

M EM ORY

ADDRESS

LABEL

INBIT

SHCNL

BITCI

RER

RINONE

REZ

RIDATA

RDFLG

RIPRTY

SHCNH

SAL

SAH

EAL

EAH

CMPO

TEMP

TAPE1

BITTS

SNSW1

NXTBIT

DIFF

RODATA

PRP

FNLEN

FNADR

ROPRTY

OCHAR

FSBLK

DRIVE

M YCH

CAS1

TRACK

STAL

SECTOR

STAH

M EMUSS

TMP2

DATA

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 507

0 0

00C0

00C1

00C2

00C3

00C5

00B7

00B8

00B9

00BA

00BB

00BD

00BE

OOBF

HEXADECIM AL DECIM AL

ADDRESS ADDRESS D ESCRIPTION

00A7

00A8

00A9

00AA

00AB

OOAC

KERNAL/EDITOR STORAGE

167

168

169

170

171

172

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

OOAD

OOAE

173

174 TAPE END ADDRESSES / END OF

PROGRAM

00 AF

00B0

0 0

00B2

00B4

175

176

177

178

180

TAPE TIM ING CONSTANTS

ADDRESS OF TAPE BUFFER

RS-232 TRNS BIT COUNT

00B5 181

182

183

184

185

186

187

189

190

191

192

193

194

195

197

RS-232 TRNS NEXT BIT TO BE SENT

RS-232 TRNS BYTE BUFFER

LENGTH CURRENT FILE N STR

CURRENT FILE LOGICAL ADDR

CURRENT FILE 2ND ADDR

C URRENT FILE PRIM ARY ADDR

ADDR CURRENT FILE NAM E STR

RS-232 TRNS PARITY BUFFER

CASSETTE READ BLOCK COUNT

SERIAL W ORD BUFFER

CASSETTE M ANUAL/CNTRLED

SW ITCH (UPDATED DURING IRQ)

I/O START ADDRESS (LO)

I/O START ADDRESS (HI)

CASSETTE LOAD TEM PS (2 BYTES)

TAPE READ/W RITE DATA

508 COMMODORE 128

C128 M em ory M ap (continued)

MEMORY

ADDRESS

LABEL

FNBANK

RIBUF

ROBUF

HEXADECIMAL DECIMAL

ADDRESS ADDRESS DESCRIPTION

0 0

00C7

0 0

00CA

KERNAL/EDITOR STORAGE

198

199

2 0 0

2 0 2

BANK FOR CURRENT LOAD/SAVE/

VERIFY OPERATION

BANK WHERE CURRENT FN IS

FOUND (AT ‘F N A D R ’)

RS-232 INPUT BUFFER POINTER

RS-232 OUTPUT BUFFER POINTER

KEYTAB

IMPARM

NDX

KYNDX

KEYIDX

SHFLAG

SFDX

LSTX

CRSW

M ODE

GRAPHM

CHAREN

GLOBAL SCREEN EDITOR VARIABLES

oocc

00CE

00D0

00D1

00D2

00D3

00D4

00D5

00D6

00D7

00D8

00D9

204

206

208

209

2 1 0

2 1 1

2 1 2

213

214

215

216

217

KEYSCAN TABLE POINTER

PRIM M 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 COLUM N M ODE FLAG

TEXT/GRAPHIC M ODE FLAG

RAM/ROM VIC CHARACTER FETCH

FLAG (BIT-2)

THE FOLLOW ING LOCATIONS ARE SHARED BY SEVERAL EDITOR ROUTINES.

SEDSAL

BITM SK

SAVER

00DA

00DB

218

219

POINTERS FOR M OVLIN

TEM PORARY FOR TAB & LINE

W RAP ROUTINES

ANOTHER TEM PORARY PLACE TO

SAVE A REG.

SEDEAL

SEDT1

SEDT2

KEYSIZ

KEYLEN

KEYNUM

KEYNXT

KEYBNK

KEYTMP

00DC

00DE

00DF

00DA

00DB

00DC

00DD

00DE

00DF

2 2 0

2 2 2

223

218

219

2 2 0

2 2 1

2 2 2

223

SAVPOS

PROGRAM M ABLE KEY VARIABLES

PNT

USER

LOCAL SCREEN EDITOR VARIABLES.

THESE ARE SW APPED OUT TO $0A40

WHEN SCREEN (40/80) MODE CHANGES.

00E0

00E2

224

226

POINTER TO CURRENT LINE (TEXT)

POINTER TO CURRENT LINE

(ATTRIBUTE)

TH E COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 509

MEMORY

ADDRESS

LABEL

COLOR

TCOLOR

RVS

QTSW

INSRT

INSFLG

LOCKS

SCROLL

BEEPER

FREKZP

SCBOT

SCTOP

SCLF

SCRT

LSXP

LSTP

INDX

TBLX

PNTR

LINES

COLUMNS

DATAX

LSTCHR

LOFBUF

BAD

FBUFFR

XCNT

HEXADECIMAL DECIMAL

ADDRESS ADDRESS DESCRIPTION

LOCAL SCREEN EDITOR VARIABLES.

THESE ARE SWAPPED OUT TO $0A40

WHEN SCREEN (40/80) MODE CHANGES

00E4

00E5

00E6

00E7

00E8

00E9

00EA

00EB

00EC

OOED

00EE

00EF

00F0

00F1

00F2

OOF3

00F4

00F5

00F6

00F7

00F8

00F9

00FA

234

235

236

237

228

229

230

231

232

233

238

239

240

241

242

243

244

245

246

247

248

249

250

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

< ES 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 IF T > < C'>,

< C T R L > S

DISABLES SCREEN SCROLL, LINE

LINKER

DISABLES <C T R L > G

FREE ZERO PAGE RESERVED FOR

APPLICATIONS SOFTWARE

($FA-$FE)

00FF 255

0100

0110

BASIC/DOS INTERFACE VARS

256

272

TAPE READ ERRORS

AREA TO BUILD FILENAME IN

(16 BYTES)

DOS LOOP COUNTER

510 COMMODORE 128

BNR

ENR

DOLR

FLAG

SWE

USGN

UEXP

POSP

FESP

ETOF

CFORM

SNO

BLFD

BEGFD

LFOR

ENDFD

SYSTK

BUF

DOSF1L

DOSDS1

DOSF2L

DOSDS2

DOSF2A

DOSOFL

DOSOFH

DOSLA

DOSFA

DOSSA

DOSRCL

DOSBNK

DOSDID

DIDCHK

C128 M em ory M ap (continued)

MEMORY

ADDRESS

LABEL

HEXADECIMAL

ADDRESS

DECIMAL

ADDRESS

CHSN

DESCRIPTION

012E

012F

0130

0131

0132

0133

0134

0135

0136

0137

0 2 0 0

0123

0124

0125

0126

0127

0128

0129

012A

0 1 1 1

0 1 1 2

0113

0114

0115

0117

0119

011B o n e

011D

011E

011F

0 1 2 0

0 1 2 2

012B

012C

012D

BASIC/DOS INTERFACE VARS

273

274

275

276

277

279

281

283

284

285

286

287

288

290

DOS FILENAM E 1 LEN

DOS DISK DRIVE 1

DOS FILENAM E 2 LEN

DOS DISK DRIVE 2

DOS FILENAM E 2 ADDR

BLOAD/BSAVE STARTING ADDRESS

....A N D ENDING ADDRESS

DOS LOGICAL ADDR

DOS PHYS ADDR

DOS SEC. ADDR

DOS RECORD LENGTH

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

512

DOS DISK ID

DOS DSK ID FLG

SPACE USED BY PRINT USING

POINTER TO BEG IN. NO.

POINTER TO END NO.

DOLLAR FLAG

COMMA FLAG

COUNTER

SIGN EXPONENT

POINTER TO EXPONENT

# OF DIGITS BEFORE DECIM AL

POINT

JUSTIFY FLAG

# OF POS BEFORE DECIM AL POINT

(FIELD)

# OF POS AFTER DECIM AL POINT

(FIELD)

+ / - FLAG (FIELD)

EXPONENT FLAG (FIELD)

SWITCH

CHAR COUNTER (FIELD)

SIGN NO

BLANK/STAR FLAG

POINTER TO BEGIN OF FIELD

LENGTH OF FORM AT

POINTER TO END OF FIELD

SYSTEM STACK ($0137-$01FF)

INPUT BUFFER: BASIC & MONITOR

0 2 0 0

- $

0 2

A l)

TH E COMMODORE 128 AN D COMMODORE 64 MEMORY MAPS 511

MEMORY

ADDRESS

LABEL

FETCH

FETVEC

STASH

STAVEC

CM PARE

CMPVEC

JSRFAR

JM PFAR

E S C _F N _V E C

BNKVEC

IERROR

IM AIN

ICRNCH

IQPLO P

IGONE

IEVAL

IESCLK

IESCPR

IESCEX

IIRQ

CINV

IBRK

CBINV

INMI

IOPEN

ICLOSE

ICHKIN

ICKOUT

ICLRCH

02FC

02FE

0300

0302

0304

0306

0308

030A

030C

030E

0310

0314

0316

0318

031A

031C

031E

0320

0322

HEXADECIMAL

ADDRESS

DECIMAL

ADDRESS DESCRIPTION

BASIC/DOS INTERFACE VARS

02A2

02AA

02AF

02B9

02BE

0 2

02CD

02E3

674

682

687

697

702

712

716

739

L D A (-),Y FROM ANY BANK

ST A (-),Y TO ANY BANK

C M P (-),Y TO ANY BANK

JSR XXXX TO ANY BANK & RETURN

JM P XXXX TO ANY BANK

790

792

794

796

798

800

802

VECTORS

764

766

768

770

772

774

776

778

780

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 DIRECT

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-TO KEN

CRUNCH,

...L IS T ,

...A N D EXECUTE.

IRQ RAM VECTOR

BRK INSTR RAM VECTOR

NMI VECTOR

KERNAL OPEN ROUTINE VECTOR

KERNAL CLOSE ROUTINE VECTOR

KERNAL CHKIN ROUTINE VECTOR

KERNAL CHKO UT ROUTINE

VECTOR

KERNAL CLRCHN ROUTINE

VECTOR

512 COMMODORE 128

CTLVEC

SHFVEC

ESCVEC

KEYVEC

KEYCHK

DECODE

KEYD

TABM AP

BITABL

C128 Memory Map (continued)

MEMORY

ADDRESS

LABEL

IBASIN

IBSOUT

ISTOP

IGETIN

ICLALL

EXM ON

ILOAD

ISAVE

0328

032A

032C

032E

0330

0332

HEXADECIMAL DECIMAL

ADDRESS ADDRESS

VECTORS

DESCRIPTION

0324

0326

804

806

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

M ONITOR COM M AND VECTOR

KERNAL LOAD ROUTINE VECTOR

KERNAL SAVE ROUTINE VECTOR

LAT

FAT

SAT

CHRGET

CHRGOT

QNUM

035E

0362

036C

0376

0380

0386

0390

0334

0336

0338

033A

033C

033E

034A

EDITOR INDIRECT VECTORS

820

822

824

826

828

830

842

EDITOR: PRINT ‘CONTRL’ INDIRECT

EDITOR: PRINT ‘SHIFTD’ INDIRECT

EDITOR: PRINT ‘ESCAPE’ INDIRECT

EDITOR: KEYSCAN LOGIC INDIRECT

EDITOR: STORE KEY INDIRECT

VECTORS TO KEYBOARD M ATRIX

DECODE TABLES

IRQ KEYBOARD BUFFER (10 BYTES)

0354 852

862

8 6 6

876

8 8 6

896

902

912

BITM AP OF TAB STOPS (10 BYTES,

$0354-D)

BITM AP OF LINE WRAPS

TABM AP AND BITABL GET

SW APPED TO $0A60 W HEN SCREEN

40/80 MODE IS CHANG ED.

LOGICAL FILE NUM BERS

PRIM ARY DEVICE NUM BERS

SECONDARY ADDRESSES

INDSUB_RAMO

IN DSU B_RA M 1

INDIN1_R AM 1

INDIN2

INDTXT

INDIRECT LOAD SUBROUTINE AREA

039F

03AB

03B7

03C0

03C9

927

939

950

959

968

SHARED ROM FETCH SUB

INDEX 1 INDIRECT FETCH

INDEX2 INDIRECT FETCH

TXTPTR

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 513

MEMORY

ADDRESS

LABEL

ZERO

C U R R E N T _

BANK

TM PDES

FIN _BA N K

SAVSIZ

BITS

SPRTM P_1

SPR T M P_2

FG _B G

FG _M C 1

VICSCN

HEXADECIMAL

ADDRESS

DECIMAL

ADDRESS DESCRIPTION

INDIRECT LOAD SUBROUTINE AREA

03D2

03D5

03D6

03DA

03DB

977

979

980

984

985

NUM ERIC CONSTANT FOR BASIC

CONTEXT FOR SY S,PO K E,PEEK

FROM BANK CMMD

TEMP FOR INSTR

BANK POINTER FOR STRING/

NUM BER CONVERT RTN

TEM P W ORK LOCATIO NS FOR

SSHAPE

F A C # 1 OVERFLOW DIGIT

TEM P FOR SPRSAV

03DF

03E0

03E1

03E2

989

990

991

992

03E3 993

PACKED FOREGROUND/

BACKGROUND COLOR NYBBLES

PACKED FOREGROUND/

M ULTICOLOR 1 COLOR NYBBLES

PAGE FOUR & HIGHER DECLARATIONS

0400

0800

1024

2048

(BEGINNING OF BANKABLE RAM )

VIDEO MATRIX # 1 : VIC 40-COLUMT>

TEXT SCREEN

$0400-$07FF

BASIC RUN-TIM E STACK (512

BYTES)

$0800-$09FF

SY ST E M _ VECTOR

DEJAVU

PALNTS

IN IT_STATU S

M EM STR

MEM SIZ

IRQTM P

CASTON

KIKA26

STUPID

TIM OUT

ENABL

ABSOLUTE KERNAL VARIABLES

0A00

0A02

0A03

0A04

0A05

0A07

0A09

0A0B

0A0C

0A0D

0A0E

0A0F

2560

2562

2563

2564

2565

2567

2569

2571

2572

2573

2574

2575

VECTOR TO RESTART SYSTEM

(BASIC WARM)

KERNAL W ARM /CO LD IN IT ’N

STATUS BYTE

PAL/NTSC SYSTEM FLAG

FLAGS RESET VS. NMI STATUS

FOR IN IT ’N RTNS

PTR TO BOTTOM OF AVAIL.

M EM ORY IN SYSTEM BANK

PTR TO TOP OF AVAILABLE

M EM ORY IN SYSTEM BANK

TAPE HANDLER PRESERVES IRQ

INDIRECT HERE

TOD SENSE DURING TAPE

OPERATIONS

TAPE READ TEM PORARY

TAPE READ D1IRQ INDICATOR

FAST SERIAL TIM EOUT FLAG

RS-232 ENABLES

514 COMMODORE 128

C128 M emory M ap (continued)

M EM ORY

ADDRESS

LA BEL

M 51CTR

M51CDR

M51AJB

RSSTAT

BITNUM

BAUDOF

RIDBE

RIDBS

RODBS

RODBE

SERIAL

TIM ER

HEXADECIM AL DECIM AL

ADDRESS ADDRESS D ESCRIPTION

ABSOLUTE KERNAL VARIABLES

0A10

0A11

0A12

0A14

0A15

0A16

0A18

0A19

0A1A

0A1B

0A1C

0A1D

2576

2577

2578

2580

2581

2582

2584

2585

2586

2587

2588

2589

RS-232 CONTROL REGI STER

RS-232 COM M AND REGISTER

RS-232 USER BAUD RATE

RS-232 STATUS REGISTER

RS-232 NUM BER 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/EXTERNAL

FLAG

DECREM ENTING JIFFIE REGISTER

XM AX

PAUSE

RPTFLG

KOUNT

DELAY

LSTSHF

BLNON

BLNSW

BLNCT

GDBLN

GDCOL

CURM OD

VM1

VM2

VM3

VM4

LINTM P

GLOBAL ABSOLUTE SCREEN EDITOR DECLARATIONS

0A20

0A21

0A22

0A23

0A24

0A25

0A26

0A27

0A28

0A29

0A2A

0A2B

0A2C

0A2D

0A2E

0A2F

0A30

2592

2593

2594

2595

2596

2597

2598

2599

2600

2601

2602

2603

2604

2605

2606

2607

2608

KEYBOARD QUEUE MAXIMUM SIZE

< C T R L > S F L A G

ENABLE KEY REPEATS

DELAY BETW EEN KEY REPEATS

DELAY BEFORE A KEY STARTS

REPEATING

DELAY BETW EEN < 0 > < S H F T >

TOGGLES

VIC CURSOR M ODE (BLINKING,

SOLID)

VIC CURSOR DISABLE

VIC CURSOR BLINK COUNTER

VIC CURSOR CHARACTER BEFORE

BLINK

VIC CURSOR COLOR BEFORE BLINK

VDC CURSOR M O D E (WHEN

ENABLED)

VIC TEXT SCREEN/CH ARACTER

BASE POINTER

VIC BIT MAP BASE POINTER

VDC TEXT SCREEN BASE

VDC ATTRIBUTE BASE

TEM PORARY POINTER TO LAST

LINE FOR LOOP4

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 515

MEMORY

ADDRESS

LABEL

HEXADECIMAL

ADDRESS

DECIMAL

ADDRESS DESCRIPTION

SAV80A

SAV80B

CURCOL

SPLIT

FNADRX

PALCNT

SPEED

SPRITES

BLANKING

H O L D _O FF

L D T B 1_SA

C L R _E A _L O

C L R _E A _H I

XCNT

HULP

FORM AT

LENGTH

M SAL

SXREG

SYREG

W RAP

XSAVE

DIRECTION

COUNT

NUM BER

SHIFT

TEM PS

GLOBAL ABSOLUTE SCREEN EDITOR DECLARATIONS

0A31

0A32

0A33

0A34

0A35

0A36

0A37

0A38

0A39

0A3A

0A3B

0A3C

0A3D

0A40

2609

2610

2611

2612

2613

2614

2615

2616

2617

2618

2619

2620

2621

2624

TEMPORARY FOR

VDC CURSOR COLOR BEFORE

BLINK

O-COL ROUTINES

VIC SPLIT SCREEN RASTER VALUE

SAVE .X DURING BANK

OPERATIONS

COUNTER FOR PAL SYSTEMS

(JIFFIE ADJUSTM ENT)

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 M OVE SCRN)

8563 BLOCK FILL

$0A4ft-$0A7F RESERVED SW AP

AREA FOR SCREEN VARIABLES

W HEN (40/80) M ODE CHANGES

M O N ITO R ’S DOM AIN

COM PARE BUFFER (32 BYTES) OA

OAAO

OAAA

OAAB

OAAC

OAAF

OABO

0AB1

0AB2

0AB3

0AB4

0AB5

0AB6

0AB7

2688

2720

2730

2731

2732

2735

2736

2737

2738

2739

2740

2741

2742

2743

ASM/DIS

FOR ASSEM BLER

1 BYTE TEM P USED ALL OVER

1 BYTE TEM P FOR ASSEM BLER

SAVE .X HERE DURING INDIRECT

SUBROUTINE CALLS

DIRECTION INDICATOR FOR

TRA NSFER ’

PARSE NUMBER CONVERSION

PARSE NUM BER CONVERSION

PARSE NUMBER CONVERSION

CURBNK

FUNCTION KEY ROM CARD TABLES

OACO 2752 CURRENT FUNCTION KEY ROM

BANK BEING POLLED

516 COMMODORE 128

DOSSTR

VW ORK

XYPOS

XPOS

YPOS

XDEST

YDEST

XYABS

XABS

YABS

XYSGN

XSGN

YSGN

FCT

ERRVAL

LESSER

G REATR

ANGSGN

SINVAL

C128 M emory M ap (continued)

MEMORY

ADDRESS

LABEL

HEXADECIMAL DECIMAL

ADDRESS ADDRESS DESCRIPTION

PAT

D K _FLA G

TBUFFR

RS232I

R S 2 3 2 0

PKYBUF

PKYDEF

FUNCTION KEY ROM CARD TABLES

0AC1

0AC5

0AC6

OBOO

0C00

0D00

0E00

1000

100 A

2753

2757

2758

2810

3072

3328

3584

4096

4106

PHYSICAL ADDRESS TABLE(IDS OF

LOGGED-IN CARDS)

RESERVED FOR FOREIGN SCREEN

EDITORS

$0A C 6-$0A FF RESERVED FOR

SYSTEM

CASSETTE BUFFER (192 BYTES)

$0B 00-$0B C 0, THIS PAG E 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)

$0E 00-$0FFF, 512 BYTES

PRO GRAM M ABLE FUNCTIO N KEY

LENGTHS TABLE FOR 10 KEYS

(F 1-F 8, < S H IF T R U N > , HELP)

PRO GRAM M ABLE FUNCTIO N KEY

STRINGS

1100

1131

1133

1135

1137

1139

113B

113D

113F

1141

1145

1147

1148

1149

114A

DOS/VSP AREA

4352 DOS OUTPUT STR. BUF

48 BYTES TO BUILD DOS STRING

GRAPHICS VARS 4401

4401

4403

4405

4407

4409

4411

4413

4415

4417

4421

4423

4424

CURRENT X POSITION

CURRENT Y POSITION

X-COORDINATE DESTINATIO N

Y-COORDINATE DESTINATION

LINE DRAW ING VARIABLES

4425

4426

ANGLE ROUTINE VARIABLES

SIGN OF ANGLE

SINE OF VALUE OF ANGLE

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 517

MEMORY

ADDRESS

LABEL

COSVAL

ANGCNT

XCIRCL

YCIRCL

XRADUS

YRADUS

ROTANG

ANG BEG

ANGEND

XRCOS

YRSIN

XRSIN

YRCOS

XCENTR

YCENTR

XDIST1

YDIST1

XDIST2

YDIST2

DISEEND

COLCNT

ROW CNT

STRCNT

XCORD1

YCORD1

BOXANG

XCOUNT

YCOUNT

BXLENG

XCORD2

YCORD2

KEYLEN

KEYNXT

STRSZ

HEXADECIMAL DECIMAL

ADDRESS ADDRESS DESCRIPTION

114C

114E

DOS/VSP AREA

4428

4430

COSINE OF VALUE OF ANGLE

TEM PS FOR ANGLE DISTANCE

ROUTINES

BASIC GRAPHIC VARIABLES.

THE FOLLOW ING 24 BYTES ARE M ULTIPLY DEFINED.

1150

1152

1154

1156

1158

115C

115E

1160

1162

1164

1166

4432

4434

4436

4438

4440

4444

4446

4448

4450

4452

4454

CIRCLE DRAW ING 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)

1150

1152

1154

1156

1158

115A

115C

115E

1150

1152

1154

1156

1158

115A

115C

115E

115F

1160

BASIC GENERAL USE PARAM ETERS

4432

4434

4436

4438

4440

4442

4444

4446

4447

4448

PLACEHOLDER

CH A R ’S COL. COUNTER

4432

4434

4436

4438

4440

4442

4444

4446

BOX-DRAW ING VARIABLES

POINT 1 X-COORD.

POINT 1 Y-COORD.

ROTATION ANGLE

LENGTH OF A SIDE

SHAPE AND MOVE-SHAPE VARIABLES

1151

1152

1153

4433

4434

4435 STRING LEN

518 COMMODORE 128

C128 M em ory M ap (continued)

M EM ORY

ADDRESS

LA BEL

GETTYP

STRPTR

OLDBYT

NEW BYT

XSIZE

YSIZE

XSAVE

STRADR

BITIDX

HEXADECIM AL DECIM AL

ADDRESS ADDRESS D ESCRIPTIO N

SHAPE AND M OVE-SHAPE VARIABLES

1154

1155

1156

1157

1158

1159

115B

115D

115F

1161

4436

4437

4438

4439

4440

4441

4443

4445

4447

4449

REPLACE SHAPE M ODE

STRING PO S’N COUNTER

OLD BIT M AP BYTE

NEW STRING OR BIT M AP BYTE

PLACEHOLDER

SHAPE COLUM N LENGTH

SHAPE ROW LENGTH

TEM P FOR C OLUM N LENGTH

SAVE SHAPE STRING DESCRIPTOR

BIT INDEX INTO BYTE

CHRPAG

BITCNT

SCALEM

W IDTH

FILFLG

BITM SK

NUM CNT

TRCFLG

R E N U M _T M P _1

R E N U M _T M P _2

VTEM P3

VTEM P4

VTEM P5

ADRAY1

ADRAY2

SPR ITE_D A TA

V IC _SA V E

U PPER _LO W ER

U PPER _G R A PH IC

DOSSA

1169

116A

116B

116C

116D

116E

116F

1170

1172

1174

1175

1177

1178

1179

117 A

1168

117C

117E

11D6

11EB

11EC

11ED

BASIC GRAPHIC VARIABLES

4456

4457

4458

4459

4460

4461

4462

4463

4464

4466

4468

4469

4471

4472

4473

4474

HIGH BYTE: ADDR OF CHARROM

FOR ‘CH A R ’ CM D.

TEM P FOR GSHAPE

SCALE M ODE FLAG

DOUBLE W IDTH FLAG

BOX FILL FLAG

TEM P FOR BIT M ASK

FLAGS TRACE M ODE

A TEM P FOR RENUM BER

GRAPHIC TEM P STORAGE

4476

4478

4566

4587

4588

4589

PTR TO ROUTINE: CONVERT

FLOAT - * INTEGER

PTR TO ROUTINE: CONVERT

INTEG ER -> FLOAT

SPRITE SPEED/DIRECTION TABLES

($117E-D 5)

COPY OF VIC R E G ’S, USED TO

UPDATE CHIP DURING RETRACE

(21 BYTES, $11D6--EA)

POINTER TO UPPER/LOW ER CHAR

SET FOR CHAR

PTR. TO UPPER/GRAPHIC CHAR. SET

TEM P STORAGE FOR FILE SA

DURING RECORD CMD

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 519

MEMORY

ADDRESS

LABEL

OLDLIN

OLDTXT

HEXADECIMAL DECIMAL

ADDRESS ADDRESS DESCRIPTION

BASIC GENERAL NON-ZP STORAGE

1200

1202

4608

4610

PREVIOUS BASIC LINE NUM BER

POINTER: BASIC STATEM ENT FOR

CONTINUE

PUCHRS

PUFILL

PUCOM A

PUDOT

PUM ONY

ERRNUM

ERRLIN

TRAPNO

TM PTRP

ERRTXT

T E X T _T O P

M A X _M E M _0

TM PTXT

TM PLIN

USRPOK

PRINT USING DECLARATIONS

1204

1205

1206

1207

1208

1209

120B

4612

4613

4614

4615

4616

4617

4619

PRINT USING FILL SYMBOL

PRINT USING D .P . SYM BOL

PRINT USING COM M A SYM BOL

PRINT USING M ONETARY SYM BOL

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 # TEM PO R.

120D

120E

1210

1212

1214

4621

4622

4624

4626

4628

TOP OF TEXT POINTER

TO BASIC IN RAM 0

HIGHEST ADDRESS AVAILABLE

USED BY DO-LOO P. COULD BE

M ULT. ASSIGNED

1216

1218

RNDX 121B

CIRCLE . SEGM ENT 1220

DEJAVU 1221

4630

4632

4635

4640

4641

DEGREES PER CIRCLE SEGM ENT

‘CO LD ’ OR ‘W A R M ’ RESET STATUS

T EM PO _R A TE

VOICES

NTIME

OCTAVE

SHARP

PITCH

VOICE

W AVE0

DNOTE

FLTSAV

FLTFLG

NIBBLE

TONNUM

1222

1223

1229

122B

122C

122D

122F

1230

1233

1234

1238

1239

123A

BASIC STORAGE FOR MUSIC VECTORS

4642

4656

4659

4660

4664

4665

4666

4643

4649

4651

4652

4653

4655

520 COMMODORE 128

C128 M emory M ap (continued)

MEMORY

ADDRESS

LABEL

HEXADECIMAL DECIMAL

ADDRESS ADDRESS DESCRIPTION

TONVAL

PARCNT

ATKTAB

SUSTAB

W AVTAB

PULSLW

PULSHI

FILTERS

BASIC STORAGE FOR MUSIC VECTORS

123B

123E

123F

1249

1253

125D

1267

1271

4667

4668

4669

4681

4691

4701

4711

4721

IN T _T R IP _F L A G

IN T _A D R _L O

IN T _A D R _H I

INTVAL

C O LTYP

1276

1279

127C

127F

1280

INTERRUPT VECTORS

4726

4729

4732

4735

4736

SO U N D _V OICE

SO U N D _T IM E _L O

SO U N D _T IM E _H I

S O U N D _M A X _L O

SO U N D _M A X _H I

SO U N D _M IN _L O

1281

1282

1285

1288

128B

128E

SO U N D _M IN _H I 1291

SOUND_DIRECTION 1294

SO U N D _ST E P_L O

SO U N D _ST E P_H I

SO U N D _F R E Q _L O

S O U N D _F R E Q _H I

T E M P _T IM E _L O

TEM P_TIM F, HI

1297

129 A

129D

12A0

12A3

12A4

T E M P _M A X _L O

T E M P _M A X _H I

12A5

12A6

T E M P _M IN _L O

T E M P _M IN _H I

12A7

12A8

TEM P_D IR EC TIO N 12A9

T E M P _ST E P_L O

T E M P _ST E P_H I

T E M P _F R E Q _L O

T E M P _F R E Q _H I

12AA

12AB

12AC

12AD

T E M P _P U L SE _L O

T E M P _P U L SE _H I

12AE

12AF

TEM P_W A VEFO R M 12B0

BASIC SOUND COM M AND VARS

4765

4768

4771

4772

4773

4774

4775

4776

4777

4778

4779

4780

4781

4782

4783

4784

4737

4738

4741

4744

4747

4750

4753

4756

4759

4762

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 521

MEMORY

ADDRESS

LABEL

P O T _ T E M P _ l

P O T _T E M P _2

W IN DO W _TEM P

SAVRAM

DEFM OD

LINCNT

SPRITE_N UM BER

IR Q _W R A P _F L A G

RAM BOT

HEXADECIMAL DECIMAL

ADDRESS ADDRESS DESCRIPTION

BASIC SOUND COM M AND VARS

12B1 4785 TEM PORARIES FOR ‘P O T ’

FUNCTION

12B2

12B3

12B7

12FA

12FB

12FC

12FD

1300

1C00

4786

4787

4791

4858

4859

4860

4861

4864

7168

USED BY SPRDEF & SAVSPR

USED BY BASIC IRQ TO BLOCK

ALL BUT ONE IRQ CALL

APPLICATION PROGRAM AREA

$1300-$1BFF

START OF BASIC TEXT $1C 00-

$EFFF (KERNAL SETS MEM BOT

HERE)

VIDEO MATRIX # 2 (1KB OF

COLORS FOR BITM AP, IF

ALLOCATED) $1C 00-$1FFF

2000 8192 VIC BITM AP (8K B, IF ALLOCATED)

$2000-$3FFF

BEGINNING OF ROM OVER RAM

4000 16384 C128 BASIC LO ROM

START OF BASIC TEXT IF BIT M AP

IS ALLOCATED (RAM)

$4000-$EFFF

8000 32768 C128 BASIC HI ROM (OR FUNCTION

ROM ) $8000-$B FFF

BASIC JUMP TABLE

MEMORY

ADDRESS

LABEL

HEXADECIMAL DECIMAL

ADDRESS ADDRESS DESCRIPTION

JM P H A R D _R ESE T 4000

JM P SO FT _R E SE T 4003

JM P B A SIC _IR Q 4006

BASIC ENTRY

16384

16387

16390

COLD ENTRY

WARM ENTRY

IRQ ENTRY

JM P AYINT

JM P GIVAYF

AFOO

AF03

FORM AT CONVERSIONS

44800

44803

CONVERT F .P. TO INTEGER

CONVERT INTEGER TO F .P.

522 COMMODORE 128

Basic Jump Table (continued)

M EM ORY

ADDRESS

LABEL

JM P FOUT

JM P VAT, I

JM P GETADR

JM P FLOATC

HEXADECIM AL DECIM AL

ADDRESS ADDRESS D ESCRIPTIO N

AF06

AF09

AFOC

AFOF

FORM AT CONVERSIONS

44806

44809

44812

44815

CONVERT F .P . TO ASCII STRING

CONVERT ASCII STRING TO F .P.

CONVERT F .P . TO AN ADDRESS

CONVERT ADDRESS TO F .P.

JM P FSUB

JM P FSUBT

JM P FADD

JM P FADDT

JM P FM ULT

JM P FM ULTT

JM P FDIV

JM P FDIVT

JM P LOG

JM P INT

JM P SQR

JM P NEGOP

JM P FPWR

JM P FPW RT

JM P EXP

JM P COS

JM P SIN

JM P TAN

JM P ATN

JM P ROUND

JM P ABS

JM P SIGN

JM P FCO M P

JM P RND 0

AF12

AF15

AF18

AF1B

AF1E

AF21

AF24

AF27

AF2A

AF2D

AF30

AF33

AF36

AF39

AF3C

AF3F

AF42

AF45

AF48

AF4B

AF4E

AF51

AF54

AF57

44818

44821

44824

44827

44830

44833

44836

44839

44842

44845

44848

44851

44854

44857

44860

44863

44866

44869

44872

44875

44878

44881

44884

44887

MATH FUNCTIONS

MEM - FACC

ARG - FACC

MEM + FACC

ARG - FACC

M EM * FACC

ARG * FACC

M EM / FACC

A R G / FACC

COMPUTE NATURAL LOG OF FACC

PERFORM BASIC INT ON FACC

COMPUTE SQUARE ROOT OF FACC

NEGATE FACC

RAISE ARG TO THE M EM POW ER

RAISE ARG TO THE FACC POW ER

COM PUTE EXP OF FACC

COM PUTE COS OF FACC

COM PUTE SIN OF FACC

COM PUTE TAN OF FACC

COM PUTE ATN OF FACC

ROUND FACC

ABSOLUTE VALUE OF FACC

TEST SIGN OF FACC

COM PARE FACC W ITH M EM

GENERATE RANDOM F.P. NUMBER

JM P CONUPK

JM P ROM UPK

JM P M OVFRM

JM P MOVFM

JM P M OVM F

JM P MOVFA

JM P M OVAF

JM P OPTAB

JM P DRAW LN

AF5A

AF5D

AF60

AF63

AF66

AF69

AF6C

MOVEM ENT

44890

44893

44896

44899

44902

44905

44908

M OVE RAM M EM TO ARG

M OVE ROM M EM TO ARG

M OVE RAM M EM TO FACC

M OVE ROM M EM TO FACC

M OVE FACC TO MEM

M OVE ARG TO FACC

M OVE FACC TO ARG

AF6F

AF72

OTHER BASIC ROUTINES

44911

44914

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 523

M EM ORY

ADDRESS

LABEL

JM P GPLOT

JM P CIRSUB

JM P RUN

JM P RUNC

JM P CLEAR

JM P NEW

JM P LNKPRG

JM P CRUNCH

JM P FNDLIN

JM P NEW STT

JM P EVAL

JM P FRM EVL

JM P R U N _ A _

PROGRAM

JM P SETEXC

JM P LINGET

JM P GARBA2

JM P E X E C U T E _A _

LINE

AF99

AF9C

AF9F

AFA2

AFA5

HEXADECIM AL

ADDRESS

D ECIM AL

ADDRESS DESCRIPTIO N

OTHER BASIC ROUTINES

AF75

AF78

AF7B

AF7E

AF81

AF84

AF87

AF8A

AF8D

AF90

AF93

AF96

44917

44920

44923

44926

44929

44932

44935

44938

44941

44944

44947

44950

44953

44956

44959

44962

44965

JM P CALL

JM P BREAK

JM P M ONCM D

BOOO

B003

B006

cooo

M ONITOR ENTRY

45056

45059

45062

49152

M ONITOR CALL ENTRY

M ONITOR BREAK ENTRY

M ONITOR COM M AND PARSER

ENTRY

KERNAL (OR FUNCTION) ROM

$C 000-$FFFF

EDITOR JUMP TABLE

M EM ORY

ADDRESS

LABEL

HEXADECIM AL DECIM AL

ADDRESS ADDRESS

JM P CINT

JM P DISPLY

COOO

C003

49152

49155

JM P LP2

JM P LOOP5

JM P PRINT

JM P SCRORG

C006

C009

COOC

COOF

49158

49161

49164

49167

D ESCRIPTIO N

INITIALIZE EDITO R & 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 R O W S, COLS

INTO X&Y

524 COMMODORE 128

VICREGO

VICREG1

VICREG2

VICREG3

VICREG4

VICREG5

VICREG6

VICREG7

VICREG8

VICREG9

VICREG10

VICREG11

VICREG12

VICREG13

VICREG14

VICREG15

VICREG16

Editor Jum p Table (continued)

M EM ORY

ADDRESS

LA BEL

JM P SCNKEY

JM P REPEAT

JM P PLOT

JM P CURSOR

JM P ESCAPE

JM P KEYSET

JM P IRQ

JM P INIT80

JM P SW APPER

JM P W INDOW

HEXADECIM AL DECIM AL

ADDRESS ADDRESS D ESCRIPTION

C012

C015

C018

C01B

C01E

C021

C024

C027

C02A

C02D

DOOO

49170

49173

49176

49179

49182

49185

49188

49191

49194

49197

53248

SCAN KEYBOARD SUBROUTINE

HANDLE REPEAT KEY&STORE

DECODED KEY

READ OR SET CRSR PO SITIO N IN

.X , .Y

MOVE 8563 CURSOR SUBROUTINE

EXECUTE ESC FUNCTION USING

CHR IN .A

REDEFINE A PROGRAM M ABLE

FU N C ’N KEY

IRQ ENTRY

INITIALIZE

O-COLUMN

CHARACTER SET

SW AP EDITOR LOCALS (40/80

CHANGE)

SET TOP-LEFT OR BOT-RIGH T OF

W INDOW

VIC CHARACTER ROM

($D 000-$D FFF)

DOOO

D001

D002

D003

D004

D005

D006

D007

D008

D009

DOOA

DOOB

DOOC

DOOD

DOOE

DOOF

D010

VIC CHIP REGISTERS

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-LOC ATION

SPRITE 2, X-LOCATION

SPRITE 2, Y-LOC ATION

SPRITE 3, X-LOCATION

SPRITE 3, Y-LOC ATION

SPRITE 4, X-LOCATION

SPRITE 4, Y-LOC ATION

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-LOCATIO N FOR

SPRITES 0 -7

M EM ORY

ADDRESS

LABEL

VICREG17

VICREG18

VICREG19

VICREG20

VICREG21

VICREG22

VICREG23

VICREG24

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 525

D012

D013

D014

D015

D016

HEXADECIM AL D ECIM AL

ADDRESS ADDRESS D ESCRIPTION

D O ll

VIC CHIP REGISTERS

53265 VIC CONTROL REGISTER 1

53266

53267

53268

53269

53270

7 RASTER COM PARE BIT

6 EXTENDED COLOR TEXT

MODE (1 = ON)

BIT MAP MODE (1 = ENABLE)

BLANK SCREEN TO BORDER

CLR (0 = BLANK)

2-0

SELECT 24/25 ROW TEXT

DISPLAY (1 = 25)

SM OOTH SCROLL TO Y

DOT POSITION

READ/W RITE RASTER VALUE FOR

COM PARE IRQ

LIGHT PEN LATCH X-POSITION

LIGHT PEN LATCH Y-POSITION

SPRITES 0 -7 DISPLAY ENABLE

(1 = ENABLE)

VIC CONTROL REGISTER 2

BITS

DO 17

D018

7 -6

2 -0

UNUSED

RESET

M ULTI-COLO R M ODE

(1 = ENABLE)

SELECT 38/40 COLUM N

DISPLAY (1 = 40 COLS)

SM OOTH SCRO LL TO

X-POSITION

53271 SPRITES 0 -7 Y EXPAND

53272 VIC MEMORY CONTROL REGISTER

BITS ($D018)

7 -4

3 -0

VIDEO M ATRIX BASE

ADDRESS

CHARACTER DOT-DATA

BASE ADDRESS

526 COMMODORE 128

VICREG27

VICREG28

VICREG29

VICREG30

VICREG31

VICREG32

VICREG33

VICREG34

VICREG35

VICREG36

VICREG37

VICREG38

V ICREG39

V ICREG40

VICREG41

V1CREG42

C128 M emory M ap (continued)

M EM ORY

ADDRESS

LA BEL

VICREG25

HEXADECIM AL DECIM AL

ADDRESS ADDRESS D ESCRIPTION

D019

VIC CHIP REGISTERS

53273 VIC INTERRUPT FLAG REGISTER

(1 = IRQ OCCURRED)

VICREG26 D01A 53274

6 -4

SET ON ANY ENABLED VIC

IRQ CONDITION

NOT USED

LIGHT PEN TRIGGERED

IRQ FLAG

SPRITE TO SPRITE

COLLISION IRQ FLAG

SPRITE TO BACKG RO UND

COLLISION IRQ FLAG

RASTER C O M PARE IRQ

FLAG

RQ ENABLE (1 = ENABLED) BITS

D01B

D01C

D01D

D01E

D01F

D020

D021

D022

D023

D024

D025

D026

D027

D028

D029

D02A

53275

53276

53277

53278

53279

53280

53281

53282

53283

53284

53285

53286

53287

53288

53289

53290

7 -4

NOT USED

LIGHT PEN

SPRITE TO SPRITE

SPRITE TO BACKG RO UND

IRQ

SPRITES 0 -7 BACKG RO UND

PRIORITY (1 = SPRITE)

SPRITES 0-7 MULTI-COLOR MODE

(1 = M ULTI-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 M ULTI-COLOR REGISTER 0

SPRITE M ULTI-COLOR REGISTER 1

SPRITE 0 COLOR

SPRITE 1 COLOR

SPRITE 2 COLOR

SPRITE 3 COLOR

M EM ORY

ADDRESS

LABEL

VICREG43

VICREG44

VICREG45

VICREG46

VICREG47

VICREG48

SIDREGO

SIDREG1

SIDREG2

SIDREG3

SIDREG4

SIDREG5

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 527

HEXADECIM AL DECIM AL

ADDRESS ADDRESS DESCRIPTIO N

VIC CHIP REGISTERS

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

2-0

NOT USED

K 2, K1 AND KO

D030 53296 CLOCK SPEED

BITS

7 -2

NOT USED

TEST

2 MHZ

D400

D401

D402

D403

D404

D405

SID REGISTERS

54272

54273

54274

54275

54276

VOICE 1 FREQUENCY LO

VOICE 1 FREQUENCY HI

VOICE 1 PULSE W IDTH LO

VOICE 1 PULSE W IDTH HI (0-15)

VOICE 1 CONTROL REGISTER

54277

NOISE (1 = NOISE)

PULSE (1 = PULSE)

SAW (1 = SAW TOOTH)

TRI (1 = TRIANGLE)

TEST (1 = DISABLE

OSCILLATOR)

RING (1 = RING 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

7 -4 ATTACK (0-15)

3 -0 DECAY (0-15)

528 COMMODORE 128

C128 M em ory M ap (continued)

M EM ORY

ADDRESS

LA BEL

SIDREG6

SIDREG7

SIDREG8

SIDREG9

SIDREG10

SIDREG11

SIDREG12

HEXADECIM AL DECIM AL

ADDRESS ADDRESS DESCRIPTIO N

D406

D407

D408

D409

D40A

D40B

D40C

SID REGISTERS

54278 VOICE 1 SUSTAIN/RELEASE

54279

54280

54281

54282

54283

54284

7 -4

3 -0

SUSTAIN (0-15)

R ELEASE (0-15)

VOICE 2 FREQUENCY LO

VOICE 2 FREQUENCY HI

VOICE 2 PULSE W IDTH LO

V OICE 2 PULSE W IDTH HI (0-15)

V OICE 2 CONTROL REGISTER

NOISE (1 = NOISE)

PULSE (1 = PULSE)

SAW (1 = SAW TOOTH)

TRI (1 = TRIANGLE)

TEST (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/

D ECAY/SUSTAIN

0 = START RELEASE)

VOICE 2 ATTACK/DECAY

7 -4

3 -0

ATTACK (0-15)

DECAY (0-15)

SIDREG13 D40D 54285 VOICE 2 SUSTAIN/RELEASE

7 -4

3 -0

SUSTAIN (0-15)

RELEASE (0-15)

SIDREG14

SIDREG15

SIDREG16

SIDREG17

D40E

D40F

D410

D411

54286

54287

54288

54289

VOICE 3 FREQUENCY LO

VOICE 3 FREQUENCY HI

VOICE 3 PULSE W IDTH LO

VOICE 3 PULSE W IDTH HI (0-15)

M EM ORY

ADDRESS

LABEL

SIDREG18

SIDREG19

SIDREG20

SIDREG21

SIDREG22

SIDREG23

THE COMMODORE 128 AN D COMMODORE 64 MEMORY MAPS 529

HEXADECIM AL DECIM AL

ADDRESS ADDRESS DESCRIPTIO N

SID REGISTERS

D412 54290 VOICE 3 CONTROL REGISTER

D413 54291

NOISE (1

PULSE (1

SAW (1

NOISE)

PULSE)

SAW TOOTH)

TRI ( l = r

TEST (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)

VOICE 3 ATTACK/DECAY

7 -4

3-0

ATTACK (0-15)

DECAY (0-15)

D414 54292 VOICE 3 SUSTAIN/RELEASE

7-4

3 -0

SUSTAIN (0-15)

RELEASE (0-15)

D415

D416

D417

54293

54294

54295

FILTER CUTOFF FREQUENCY LO

FILTER CUTOFF FREQUENCY HI

RESONANCE/FILTER

7-4

FILTER R ESONANCE (0-15)

FILTER EXTERNAL INPUT

(1 = YES)

FILTER VOICE 3 OUTPUT

(1 = YES)

FILTER VOICE 2 OUTPUT

(1 = YES)

FILTER VOICE 1 OUTPUT

(1 = YES)

530 COMMODORE 128

C128 Memory M ap (continued)

M EM ORY

ADDRESS

LABEL

SIDREG24

HEXADECIM AL

ADDRESS

DECIM AL

ADDRESS

D418

DESCRIPTIO N

SID REGISTERS

54296 M ODE/VOLUM E

SIDREG25

SIDREG26

SIDREG27

SIDREG28

D419

D41A

D41B

D41C

54297

54298

54299

54300

CUTOFF VOICE 3 OUTPUT

(1 = OFF)

SELECT HI-PASS FILTER

( l = ON)

SELECT BAND-PASS FILTER

(1 = ON)

SELECT LO-PASS FILTER

(1 = ON)

OUTPUT VOLUM E (0-15) 3 -0

POT X, A/D CONVERTER, PADDLE 1

POT Y, A/D CONVERTER, PADDLE 2

OSCILLATOR 3, RANDOM NUM BER

GENERATOR

ENVELOPE GENERATOR 3 OUTPUT

MMUCR1

PCRA

PCRB

PCRC

PCRD

C128 M EM ORY M ANAGEM ENT UNIT, PRIM ARY REGISTERS

IM PLEM ENTS C128, C64, & CP/M 3.0 MODES

D500

D501

D502

D503

D504

54528

54529

54530

54531

54532

CONFIGURATION REGISTER

BITS ($D 500-$D 504)

PRECONFIGURATION R EG ISTER A

PRECONFIGURATION R EG ISTER B

PRECONFIGURATION R EG ISTER C

PRECONFIGURATION R EG ISTER D

7 -6

5 -4

3 -2

RAM BANK (0-3)

ROM HI (SYSTEM , INT,

EXT, RAM)

ROM MID (SYSTEM , INT,

ROM LO

I/O

EXT, RAM)

(SYSTEM , RAM)

(I/O BLO CK,

ELSE ROM -HI)

MMUMCR D505 54533

2-1

MODE CONFIGURATION REGISTER

40/80 KEY SENSE

OS M O D E, 0 = C128/1 = C64

/EXROM LINE SENSE

/GAM E LINE SENSE

FSDIR

NOT USED

PROCESSOR, 0 == Z80/1 = 8502

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 531

M EM ORY

ADDRESS

LABEL

M M URCR

HEXADECIM AL

ADDRESS

D506

DECIM AL

ADDRESS DESCRIPTIO N

C128 M EM ORY M ANAGEM ENT UNIT, PRIM ARY REGISTERS

IM PLEM ENTS C128, C64, & CP/M 3.0 MODES

54534 RAM CONFIGURATION REGISTER

MMUPOL

MMUPOH

MM UP1L

M M UP1H

D507

D508

D509

D50A

54535

54536

54537

54538

7 -6

5 -4

3 -2

1-0

VIC RAM BANK (VA17 &

VA16)

RAM BLOCK (FOR FUTURE

EXPANSION) /

RAM SHARE STATUS (NONE,

BOT, TOP, BOTH)

RAM SHARE AM OUNT (IK ,

4K, 8K, 16K)

PAGE 0

POINTER LOW

PAGE 0

POINTER HIGH

SW APS PAGEO

AND/OR PAGE1

W ITH ANY

PAGE 1

POINTER LOW

OTHER PAGE IN

THE 256K

PAGE 1

POINTER HIGH

ADDRESS SPACE

BITS ($D508 & $D50A)

7 -4

3 -2

1-0

A 19-A 18 (USED IN 1MB

SYSTEM)

A 17-A 16 (256K SYSTEM)

M M UVER D50B 54539

BITS ($D507 & $D509)

7 -0 A 15-A 8

M M U VERSION NUM BER

7 -4

3 -0

BANK VERSION

M M U VERSION

V DCADR

C128

O-COLUMN VIDEO DISPLAY CONTROLLER

D600 54784 8563 ADDRESS REGISTER

532 COMMODORE 128

C128 M emory M ap (continued)

M EM ORY

ADDRESS

LABEL

D600------ WRITE

VDCDAT

D 601-

READ

-DATA

HEXADECIM AL DECIM AL

ADDRESS ADDRESS D ESCRIPTION

ADDRESS AND DATA REGISTER BITS

7 6

STATUS LP

D601

5 4 3 2 1 0

VBLANK

54785

—

R l

—

8563 DATA REGISTER

D7 D6 D5 D4 D3 D2 D l DO

VICCOL

ADDITIONAL 8563 REGISTERS ARE NOT VISIBLE TO THE 8502

D700

D800

55040 RESERVED I/O BLOCK

55296 VIC COLOR M A TR IX , 1 KB

($D 800-$D BFF)

D1PRA

6526 C IA # 1 , COM PLEX INTERFACE ADAPTER # 1

KEYBO ARD, JOY STIC K, PADDLES, LIGHTPEN, FAST DISK

DC00 56320 PORT A (OUTPUT KEYBOARD

COLUM NS)

BITS ($DC00)

PRAO

PRA1

PRA2

PRA3

PRA4

PRA5

PRA6

PRA7

KEYBD O/P CO/JOY # 1 DIRECTION

KEYBD O/P C l/JO Y # 1 DIRECTION

KEYBD O/P C2/JOY # 1 DIRECTION/PADDLE FIRE BUTTON

KEYBD O/P C3/JOY # 1 DIRECTION/PADDLE FIRE BUTTON

KEYBD O/P C4/JOY # 1 FIRE BUTTON

KEYBD O/P C5/

KEYBD O/P C 6/

KEYBD O/P C7/

/SELECT PORT # 1 PADDLES

/SELECT PORT # 2 PADDLES

D1PRB

BITS ($DC01)

DC01 56321 PORT B (INPUT KEYBOARD ROWS)

PRBO

PRB1

PRB2

PRB3

PRB4

PRB5

PRB6

PRB7

KEYBD I/P RO/JOY # 2 DIRECTION

KEYBD I/P R l/JO Y # 2 DIRECTION/PADDLE FIRE BUTTON

KEYBD I/P R2/JOY # 2 DIRECTION/PADDLE FIRE BUTTON

KEYBD I/P R3/JOY # 2 DIRECTION/

KEYBD I/P R4/JOY # 2 FIRE BUTTON

KEYBD I/P R5/

KEYBD I/P R6/TIM ER B: TOGGLE /PULSE OUTPUT

KEYBD I/P R7/TIM ER A: TOGGLE /PULSE OUTPUT

D1DDRA

D1DDRB

D1T1L

DC 02

DC03

DC04

56322

56323

56324

DATA DIRECTION PORT A

DATA DIRECTION PORT B

TA LO

THE COMMODORE 128 AN D COMMODORE 64 MEMORY MAPS 533

M EM ORY

ADDRESS

LABEL

D1T1H

D1T2L

D1T2H

D1TOD1

D1TODS

D1TODM

D1TODH

D1SDR

D1ICR

D1CRA

D1CRB

HEXADECIM AL DECIM AL

ADDRESS ADDRESS D ESCRIPTION

6526 C IA # 1 , COM PLEX INTERFACE ADAPTER # 1

KEYBO ARD, JOY STIC K, PADDLES , LIGH TPEN, FAST DISK

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

D2PRA

6526 C IA # 2 COM PLEX INTERFACE ADAPTER # 2

USER PO R T,R S-232,SER IAL BUS,VIC M EM O R Y,N M I

DDOO 56576 PORT A, SERIAL BUS, RS-232, VA14

& VA15

BITS

PRAO : VA14

PRA1 : VA15

PRA2 : RS232 DATA

OUTPUT

PRA3 : SERIAL ATN

OUTPUT

PRA4 : SERIAL CLK

OUTPUT

P R A 5 : SERIAL DATA

OUTPUT

PRA6 : SERIAL CLK INPUT

P R A 7 : SERIAL DATA INPUT

534 COMMODORE 128

D2DDRA

D2DDRB

D2T1L

D2T1H

D2T2L

D2T2H

D2TOD1

D2TODS

D2TODM

D2TODH

D2SDR

D2ICR

D2CRA

D2CRB

101

102

C128 M emory M ap (continued)

M EM ORY

ADDRESS

LABEL

D2PRB

HEXADECIM AL DECIM AL

ADDRESS ADDRESS D ESCRIPTIO N

D D 0 1 56577 PORT B , USER PO R T, RS-232

BITS

PRBO : USER PORT / RS-232

R ECEIVED DATA

PRB1 : USER PORT / RS-232

R EQUEST TO SEND

PRB2 : USER PORT / RS-232

DATA TERM INAL 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

DM A ST

DD02

DD03

DD04

DD05

DD06

DD07

DD08

DD09

DDOA

DDOB

DDOC

DDOD

DDOE

DDOF

DEOO

DFOO

56578

56579

56580

56581

56582

56583

56584

56585

56586

56587

56588

56589

56590

56591

56832

57088

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

(N M I’S)

CONTROL REGISTER A

CONTROL REGISTER B

EXPANSION I/O SLOT (RESERVED)

C128 DMA CONTROLLER FOR

EXPANSION RAM ACCESS

OPTIONAL DEVICE M APPED INTO

1 0 2 BLOCK VIA SYSTEM

EXPANSIO N PORT (PRELIM INARY)

DMA CONTROLLER STATUS

REGISTER (READ ONLY)

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 535

M EM ORY

ADDRESS

LA BEL

DMA CMD

DMA ADL

DMA ADH

DMA LO

DM A HI

DM A BNK

DF02

DF03

DF04

DF05

DF06

HEXADECIM AL DECIM AL

ADDRESS ADDRESS DESCRIPTIO N

D F O l 57089

57090

57091

57092

57093

57094

INTERRUPT

PENDING (1 = INT.

W AITING TO BE

SERVICED)

END OF BLOCK

(1 = TRANSFER

COM PLETE)

FAULT (1 = BLOCK

VERIFY ERROR)

SIZE (0 = EXP.

M EM ORY =

128K)

(1 = EXP.

M EM ORY =

512K)

VERSION

DMA CONTROLLER COM M AND

REGISTER

1-0

EXECUTE

RESERVED

LOAD (1 = ENABLE

AUTO = LOAD)

$FF00 (1 = DISABLE $FF00

DECADES)

RESERVED

MODE (00 = TRANSFER

FROM INTERNAL TO

EXTERNAL,

0 1 = FROM EXT TO INT,

10 = SW A P, 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)

536 COMMODORE 128

C128 M emory M ap (continued)

M EM ORY

ADDRESS

LA BEL

HEXADECIM AL DECIM AL

ADDRESS ADDRESS D ESCRIPTION

DM A DAL

DM A DAH

DMA SUM

DM A VER

M M UCR

LCRA

LCRB

LCRC

LCRD

7-3

2-0

NOT USED

EXPANSION BANK NUMBER

DF07

DF08

DF09

DFOA

EOOO

57095

57096

57097

57098

57344

LSB OF BYTE COUNT

M SB OF BYTE COUNT (BLOCK

COUNT)

INTERRUPT M ASK REGISTER

INTERRUPT ENABLE

(1 = INTERRUPTS ENABLED)

END OF BLOCK M ASK

(1 = INTERRUPT ON END

OF BLOCK)

VERIFY ERROR

(1 = INTERRUPT ON VERIFY

ERROR)

ADDRESS CONTROL REGISTER

BITS 7 AND 6

0,0 = INCREMENT BOTH ADDRESS

(DEFAULT)

0,1 = FIX EXPANSION A DDRESS.

1.0 = FIX C128 ADDRESS.

1.1 = FIX BOTH ADDRESSES.

KERNAL ROM (8K OPERATING

SYSTEM , $E000-$FFFF)

MMU SECONDARY REGISTERS

FFOO

FFOl

FF02

FF03

FF04

65280

65281

65282

65283

65284

CONFIGURATION REGISTER

(SECONDARY)

LOAD CONFIGURATION

REGISTER A

LOAD CONFIGURATION

REGISTER B

LOAD CONFIGURATION

REGISTER C

LOAD CONFIGURATION

REGISTER D

BITS ($FFOO-$FF04)

7 -6

5 -4

3 -2

RAM BANK (0-3)

ROM HI (SY STEM , INT,

EXT, RAM)

ROM MID (SY STEM , IN T,

EXT, RAM)

ROM LO

I/O

(SYSTEM, RAM)

(I/O ELSE ROM-

HI)

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 537

KERNAL JUMP TABLE

NEW ENTRIES FOR C l 28

JM P SPIN SPOUT FF47

JM P CLOSE ALL

JM P C64M ODE

JM P DM A CALL

JM P BOOT CALL

JM P PHOENIX

JM P LKUPLA

JM P LKUPSA

JM P SW APPER

JM P DLCHR

JM P PFKEY

JM P SETBNK

JM P GETCFG

JM P JSRFAR

JM P JM PFAR

JM P INDFET

JM P INDSTA

JM P INDCM P

JM P PRIMM

JM P CINT

FF4A

FF4D

FF50

FF53

FF56

FF59

FF5C

FF5F

FF62

FF65

FF68

FF6B

FF6E

FF71

FF74

FF77

FF7A

FF7D

65351

65354

65357

65360

65363

65366

65369

65372

65375

65378

65381

65384

65387

65390

65393

65396

65499

65402

65405

SET UP FAST SERIAL PORT

FOR I/O

CLOSE ALL LOGICAL

FILES FOR A DEVICE

RECONFIGURE SYSTEM

AS A C64 (NO RETURN)

INITIATE DM A REQUEST

TO EXTERNAL RAM

EXPANSION, SEND

COM M AND TO DMA

DEVICE

BOOT LOAD PROGRAM

FROM DISK

CALL ALL FUNCTION

C AR DS’ COLD START

RO U TINES, INITIALIZE

SEARCH TABLES FOR

GIVEN LA

SEARCH TABLES FOR

GIVEN SA

SW ITCH BETW EEN 40 AND

80 COLUM NS (EDITOR)

INIT

O-COL CHARACTER

RAM (EDITOR)

PROGRAM FUNCTIO N KEY

(EDITOR)

SET BANK FOR I/O

OPERATIONS

LOOKUP M M U DATA FOR

GIVEN BANK

JSR TO ANY BAN K , RTS

TO CALLING BANK

JMP TO ANY BANK

LDA (FETV EC), Y FROM

ANY BANK

STA (STA VEC), Y TO ANY

BANK

CMP (C M PVEC),Y TO ANY

BANK

PRINT IMMEDIATE UTILITY

(ALW AYS JSR TO THIS

ROUTINE)

FF80

FF81

STANDARD KERNAL JUMP TABLE

65408

65409

RELEASE NUM BER OF

KERNAL

INIT EDITO R & DISPLAY

CHIPS (EDITOR)

538 COMMODORE 128

C128 M emory M ap (continued)

STANDARD KERNAL JU M P TABLE

JM P IOINIT

JM P RAM TAS

JM P RESTOR

JM P VECTOR

JM P SETM SG

JM P SECND

JM P TKSA

JM P M EM TOP

JM P M EM BOT

JM P KEY

JM P SETTMO

JM P ACPTR

JM P CIOUT

JM P UNTLK

JM P UNLSN

JM P LISTN

JM P TALK

JM P READSS

JM P SETLFS

JM P SETNAM

JM P (IOPEN)

JM P (ICLOSE)

JM P (ICHKIN)

JM P (ICKOUT)

JM P (ICLRCH)

JM P (IBASIN)

JM P (IBSOUT)

JM P LOADSP

JM P SAVESP

JM P SETTIM

JM P RDTIM

JM P (ISTOP)

JM P (IGETIN)

JM P (ICLALL)

FF84

FF87

FF8A

FF8D

FF90

FF93

FF96

FF99

FF9C

FF9F

FFA2

FFA5

FFA8

FFAB

FFAE

FFB1

FFB4

FFB7

FFBA

FFBD

FFCO

FFC3

FFC6

FFC9

FFCC

FFCF

FFD2

FFD5

FFD8

FFDB

FFDE

FFE1

FFE4

FFE7

OPEN

CLOSE

CHKIN

65412

65415

65418

65421

65424

65427

65430

65433

65436

65439

65442

65445

65448

65451

65454

CKOUT 65481

CLRCH 65484

BASIN

BSOUT

STOP

GETIN

CLALL

65457

65460

65463

65460

65469

65472

65475

65478

65487

65490

65493

65496

65599

65502

65505

65508

65511

INIT I/O DEVICES (PORTS,

TIM ERS, ETC.)

INITIALIZE RAM AND

BUFFERS FOR SYSTEM

RESTORE VECTORS TO

INITIAL SYSTEM

CHANGE VECTORS FOR

USER

CONTROL O .S. M ESSAGE

SEND SA AFTER LISTEN

SEND SA AFTER TALK

SET/READ TOP OF SYSTEM

RAM

SET/READ BOTTOM OF

SYSTEM RAM

SCAN KEYBOARD

(EDITOR)

SET TIM EOUT IN IEEE

(RESERVED)

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 L A , FA , SA

SET LENGTH AND FILE

NAM E ADDRESS

OPEN LOGICAL FILE

CLOSE LOGICAL FILE

SET CHANNEL IN

SET CHANNEL OUT

RESTORE DEFAULT I/O

CHANNEL

INPUT FROM CHANNEL

OUTPUT TO CH ANNEL

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 A N D COMMODORE 64 MEMORY MAPS 539

JM P UDTIM

JM P SCRORG

JM P PLOT

JM P IOBASE

SYSTEM

NMI

RESET

IRQ

FFFO

FFF3

FFF8

STANDARD KERNAL JUM P TABLE

FFEA

FFED

FFFA

FFFC

FFFE

CLOCK 65514

65517

65520

65523

65528

65530

65532

65534

INCREM ENT INTERNAL

CLOCK

RETURN SCREEN WINDOW

SIZE (EDITOR)

READ/SET X ,Y CURSOR

COORD (EDITOR)

RETURN I/O BASE

OPERATING SYSTEM

VECTOR (R AM I)

PROCESSOR NMI V ECTOR

PROCESSOR RESET

VECTOR

PROCESSOR IRQ/BRK

VECTOR

KERNAL/EDITOR FLAGS A N D

SHADO W 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 o f 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 o f VIC register 24 ($D018). VM1 will be used by the editor to update

VIC register 24.

ADDRESS/NAME

S00D8/GRAPHM

S00D9/CHAREN

$0A2C/VM1

$0A2D/VM 2

$0A2E/VM 3

$0A2F/VM 4

$0A34/SPLIT

$OA2B/CURMOD

$0A21/PAUSE

EXPLANATION

SEE BELOW. IF = $FF THEN EDITOR LEAVES VIC ALONE.

M ASK FOR 8502 /CHAREN BIT.

VIC TEXT M ODE VIDEO M ATRIX & CHARACTER BASE

POINTER.

VIC GRAPHIC M ODE VIDEO M ATRIX & BIT M AP

POINTER.

8563 TEXT DISPLAY BASE ADDRESS.

8563 ATTRIBUTE BASE ADDRESS.

IN SPLIT SCREEN M ODE, CONTAINS VALUE FOR

M IDDLE RASTER IRQ.

8563 CURSOR M ODE.

CONTROL S FLAG (IN EFFECT = $13)

540 COMMODORE 128

E X P L A N A T IO N O F V A R IO U S K E R N A L /E D IT O R F L A G B Y T E S , E T C .

0000

0001

00F7

00F8

00D3

0A22

0A26

00F9

00D8

00D7

0A 04

A D D R E S S S Y M B O L D E S C R I P T I O N

7 6 5 4 3 2 l 0

D6510

R 6510

LO CK S

SC R O LL

SH FLAG

RPTFLG

BLNO N

BEEPER

—

CASE

OFF

—

ALL

G RAPH M

M O D E

MCM

40/80

IN IT _

STATUS

CHRSET

(IN) (OUT) (IN) (OUT) (OUT) (OUT) (OUT)

C APKEY CASM TR CASSEN CASW RT C H AREN H IRA M LORAM

C T L S

LINKER

— -----— — — —

— —

ALT ALPHA CTRL SHIFT

NONE

BLNK

—

SPLIT

—

C I N T

—

BM M

—

■—~"

—

BASIC

Notes on Kernal Symbols: ln it_S tatus. 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 ystem _V ecto r. W here 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 RAMI at $FFF8. Set at power-up to C128MODE, user may redirect it to his code. Taken at reset always providing user with control (protection) from reset.

COMMODORE 64 MEMORY MAP

LABEL

D6510

R6510

ADRAY1

ADRAY2

CHARAC

ENDCHR

HEX

ADDRESS

0000

0001

0002

0003-0004

0005-0006

0007

0008

DECIM AL

LOCATION

3 -4

5 -6

D ESCRIPTIO N

6510 On-Chip Data-Direction Register

6510 On-Chip 8-Bit Input/Output

Register

Unused

Jump Vector: C onvert Floating—

Integer

Jump Vector: Convert Integer—

Floating

Search Character

Flag: Scan for Quote at End o f String

TH E COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 541

INPFLG

TANSGN

LINNUM

TEM PPT

LASTPT

TEM PST

INDEX

RESHO

TXTTAB

VARTAB

ARYTAB

STREND

FRETOP

FRESPC

M EM SIZ

LABEL

TRM POS

VERCK

COUNT

DIM FLG

VALTYP

INTFLG

GARBFL

SUBFLG

CURLIN

OLDLIN

OLDTXT

DATLIN

DATPTR

INPPTR

VARNAM

VARPNT

FORPNT

FACEXP

FACHO

FACSGN

57-58

59-60

61-62

63-64

65-66

67-68

69-70

71-72

DECIMAL

LOCATION

20-21

23-24

25-33

34-37

38-42

43-44

45—46

47-48

49-50

51-52

53-54

55-56

73-74

75-96

98-101

102

HEX

ADDRESS

0009

000A

000B

OOOC

000D

000E

000F

0010

0011

0012

0013

0014-0015

0016

0017-0018

0019-0021

0022-0025

0026-002A

002B-002C

002D -002E

002F-0030

0031-0032

0033-0034

0035-0036

0037-0038

0039-003A

003B-003C

003D -003E

003F-0040

0041-0042

0043-0044

0045-0046

0047-0048

0049-004A

004B -0060

0061

0062-0065

0066

DESCRIPTION

Screen Column From Last TAB

Flag: 0 = Load, 1 = Verify

Input Buffer Pointer/No. o f Subscripts

Flag: Default Array DIM ension

Data Type: $FF = String, $00 =

Numeric

Data Type: $80 = Integer, $00 =

Floating

Flag: DATA scan/LIST quote/

Garbage Coll

Flag: Subscript R ef / User Function

Call

Flag: $00 = INPUT, $40 = G ET,

$98 = READ

Flag: TAN sign / Comparison Result

Flag: INPUT Prompt

Temp: Integer Value

Pointer: Tem porary String Stack

Last Temp String Address

Stack for Tem porary Strings

Utility Pointer Area

Floating-Point Product o f Multiply

Pointer: Start of BASIC Text

Pointer: Start of BASIC Variables

Pointer: Start of BASIC Arrays

Pointer: End of BASIC Arrays ( + 1)

Pointer: Bottom o f String Storage

Utility String Pointer

Pointer: Highest A ddress Used by

BASIC

Current BASIC Line Number

Previous BASIC Line Number

Pointer: BASIC Statem ent 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 Accum ulator # 1 :

Exponent

Floating Accum. # 1 : M antissa

Floating Accum. # 1 : Sign

542 COMMODORE 128

BSOUR

SYNO

LDTND

DFLTN

DFLTO

PRTY

DPSW

M SGFLG

PTR1

PTR2

TIM E

FACOV

FBUFPT

CHRGET

CHRGOT

TXTPTR

RNDX

STATUS

STKEY

SVXT

VERCK

C3PO

Commodore 64 M emory Map (continued)

LABEL

HEX

ADDRESS

DECIMAL

LOCATION

SGNFLG

BITS

ARGEXP

0067

0068

0069

103

104

105

ARGHO

ARGSGN

ARISGN

006A -006D

006E

006F

106-109

110

111

CNTDN

BUFPNT

INBIT

BITCI

RINONE

0070

0071-0072

0073-008A

0079

007A -007B

008B -008F

0090

0091

0092

0093

0094

0095

0096

0097

0098

0099

009A

009B

009C

009D

009E

009F

OOAO-OOA2

00A 3-00A 4

00A5

00A6

00A7

00A8

00A9

112

113-114

115-138

121

122-123

139-143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160-162

163-164

165

166

167

168

169

DESCRIPTION

Pointer: Series Evaluation Constant

Floating Accum. # 1 : Overflow Digit

Floating-Point Accum ulator # 2 :

Exponent

Floating Accum. # 2 : Mantissa

Floating Accum. # 2 : Sign

Sign Comparison Result: A ccum . # 1 vs # 2

Floating Accum. # 1 . Low-Order

(Rounding)

Pointer: Cassette Buffer

Subroutine: Get Next Byte o f BASIC

Text

Entry to Get Same Byte o f Text

Again

Pointer: Current Byte o f 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 Bus— Output Char.

Buffered

Buffered Character for Serial Bus

Cassette Sync No.

Temp Data Area

No. o f Open Files / Index to File

Table

Default Input Device (0)

D efault Output (CM D) Device (3)

Tape Character Parity

Flag: Tape Byte-Received

Flag: $80 = D irect M ode, $00 =

Program

Tape Pass 1 Error Log

Tape Pass 2 Error Log

R eal-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 328 A N D COMMODORE 64 MEMORY MAPS 543

HEX

ADDRESS

OOAA

DECIMAL

LOCATION

170

171 OOAB

00A C -00A D 172-173

OOAE-OOAF 174-175

00B0-00B1 176-177

00B 2-00B 3

00B4

178-179

180

00B5 181

00B6

00B7

00B8

00B9

OOBA

00BB-00BC

OOBD

OOBE

OOBF

OOCO

00C 1-00C 2

00C 3-00C 4

00C5

182

183

184

185

186

187-188

189

190

191

192

193-194

195-196

197

00C6

00C7

198

199

00C8

00C 9-00C A

OOCB

OOCC

200

201-202

203

204

OOCD

OOCE

OOCF

00D0

00D 1-00D2

00D3

00D4

00D5

205

206

207

208

209-210

211

212

213

LABEL

RIDATA

RIPRTY

SAL

EAL

CMPO

TAPE1

BITTS

NXTBIT

RODATA

FNLEN

FNADR

ROPRTY

FSBLK

MYCH

CAS1

STAL

M EMUSS

LSTX

NDX

RVS

INDX

LXSP

SFDX

BLNSW

BLNCT

G DBLN

BLNON

CRSW

PNT

PNTR

QTSW

LNMX

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 o f Tape Buffer

RS-232 Out Bit Count / Cassette

Temp

RS-232 Next Bit to Send / Tape EOT

Flag

RS-232 Out Byte Buffer

Length o f 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/W rite Block Count

Serial W ord Buffer

Tape M otor 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 C hars.— 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 O n/O ff

Flag: INPUT or GET from Keyboard

Pointer: Current Screen Line Address

Cursor Column on C urrent Line

Flag: Editor in Quote M ode, $00 =

Physical Screen Line Length

544 COMMODORE 128

BAD

BUF

LAT

FAT

SAT

KEYD

M EMSTR

M EM SIZ

TIMOUT

COLOR

GDCOL

HIBASE

XMAX

RPTFLG

KOUNT

DELAY

SHFLAG

LSTSHF

KEYLOG

M ODE

AUTODN

M 51CTR

M51CDR

C o m m o d o re 6 4 M e m o r y M a p (c o n tin u e d )

LABEL

HEX

ADDRESS

DECIMAL

LOCATION

TBLX 00D6 214

INSRT

LDTB1

USER

00D7

00D8

00D 9-00F2

00F3-00F4

215

216

217-242

243-244

KEYTAB

RIBUF

ROBUF

FREKZP

BASZPT

611-620

621-630

631-640

641-642

643-644

645

646

647

648

649

650

651

652

653

654

655-656

657

658

659

660

245-246

247-248

249-250

251-254

255

256-511

256-266

256-318

512-600

601-610

00F5-00F6

00F7-00F8

00F9-00FA

00FB-00FE

00FF

0100-01FF

0100-010A

0100-013E

0200-0258

0259-0262

0263-026C

026D -0276

0277-0280

0281-0282

0283-0284

0285

0286

0287

0288

0289

028A

028B

028C

028D

028E

028F-0290

0291

0292

0293

0294

D ESCRIPTION

Current Cursor Physical Line

Number

Temp Data Area

Flag: Insert M ode, > 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 Program s

BASIC Temp Data Area

M icro-Processor System Stack Area

Floating to String W ork Area

Tape Input Error Log

System INPUT Buffer

KERNAL Table: Active Logical File

N o’s.

KERNAL Table: Device No. for Each

File

KERNAL Table: Second Address

Each File

Keyboard Buffer Queue (FIFO)

Pointer: Bottom of M emory for O .S.

Pointer: Top o f M emory for O .S.

Flag: Kernal Variable for IEEE

Timeout

Current Character Color Code

Background Color Under Cursor

Top o f Screen M em ory (Page)

Size o f Keyboard Buffer

Flag: REPEAT Key Used, $80 =

Repeat

Repeat Speed Counter

Repeat Delay Counter

Flag: K eyb’rd SHIFT Key / CTRL

Key / Key

Last Keyboard Shift Pattern

Vector: Keyboard Table Setup

Flag: $00 = Disable SHIFT K eys,

$80 = Enable SHIFT Keys

Flag: Auto Scroll D own, 0 = ON

RS-232: 6551 Control Register Im age

RS-232: 6551 Command Register

Image

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 545

LABEL

M 51AJB

RSSTAT

BITNUM

BAUDOF

RIDBE

RIDBS

RODBS

RODBE

IRQTM P

ENABL

IERROR

IM AIN

ICRNCH

IQ PLO P

IGONE

IEVAL

SAREG

SXREG

SYREG

SPREG

USRPOK

USRADD

CINV

CBINV

NM INV

IOPEN

ICLOSE

ICHKIN

ICKO UT

ICLRCH

IBASIN

IBSOUT

ISTOP

IGETIN

ICLALL

USRCM D

DECIMAL

LOCATION

661-662

663

664

665-666

667

668

669

670

671-672

673

674

675

676

677

678

697-767

768-769

770-771

772-773

790-791

792-793

794-795

796-797

798-799

800-801

802-803

804-805

806-807

808-809

810-811

774-775

776-777

778-779

780

781

782

783

784

785-786

787

788-789

812-813

814-815

HEX

ADDRESS

0295-0296

0297

0298

0299-029A

029B

029C

029D

029E

029F-02A 0

02 A 1

02A2

02A3

02A4

02A5

02A6

02A 7-02FF

0300-0301

0302-0303

0304-0305

0306-0307

0308-0309

030A -030B

030C

030D

030E

030F

0310

0311-0312

0313

0314-0315

0316-0317

0318-0319

031A -031B

031C -031D

031E -031F

0320-0321

0322-0323

0324-0325

0326-0327

0328-0329

032A -032B

032C -032D

032E -032F

DESCRIPTION

RS-232 Non-Standard BPS

(Tim e/2-100) USA

RS-232: 6551 Status Register Im age

RS-232 Number o f Bits Left to Send

RS-232 Baud Rate: Full Bit Time ( |xs)

RS-232 Index to End o f Input Buffer

RS-232 Start of Input Buffer (Page)

RS-232 Start of Output Buffer (Page)

RS-232 Index to End o f Output

Buffer

Holds IRQ Vector During Tape I/O

RS-232 Enables

TOD Sense During Cassette I/O

Temp Storage For C assette Read

Temp D1IRQ Indicator For Cassette

Read

Temp for Line Index

PAL/NTSC Flag, 0 = NTSC, 1 =

PAL

Unused

Vector: Print BASIC E rror Message

Vector: BASIC W arm Start

Vector: Tokenize BASIC Text

Vector: BASIC Text LIST

Vector: BASIC C har. 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 Jum p Instr (4C)

USR Address Low Byte / High Byte

Unused

Vector: Hardware IRQ Interrupt

Vector: BRK Instr. Interrupt

Vector: Non-M askable Interrupt

KERNAL OPEN Routine Vector

KERNAL CLOSE R outine 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

546 COMMODORE 128

Commodore 64 Memory M ap (continued)

LABEL

HEX

ADDRESS

DECIMAL

LOCATION

ILOAD

ISAVE

TBUFFR

VICSCN

0330-0331

0332-0333

0334-033B

033C -03FB

03FC -03FF

0400-07FF

0400-07E 7

816-817

818-819

820-827

828-1019

1020-1023

1024-2047

1024-2023

07F8-07FF 2040-2047

0800-9FFF 2048-40959

8000-9FFF 32768-40959

A 000-BFFF 40960-49151

C 000-CFFF 49152-53247

D 000-DFFF 53248-57343

E 000-FFFF 57344-65535

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 ROM— 8192 Bytes

BASIC ROM— 8192 Bytes (or 8K

RAM)

RAM— 4096 Bytes

Input/Output Devices and Color

RAM or Character Generator ROM or RAM— 4096 Bytes

KERNAL ROM— 8192 Bytes (or 8K

RAM)

COM M ODORE 64 IN P U T /O U T P U T ASSIGNMENTS

HEX

0000

0001

DECIMAL

BITS

7 -0

6 -7

DESCRIPTION

MOS 6510 Data Direction Register

( x x l O l l l l )

Bit = 1 : Output, Bit = 0:

Input, x = Either

MOS 6510 M icro-Processor On-Chip

I/O Port

/LORAM Signal (0 = Switch BASIC

ROM Out)

/H IRAM 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

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 547

HEX DECIMAL BITS

D 000-D 02E 53248-54271

DOOA

DOOB

DOOC

DOOD

DOOE

DOOF

D 010

D011

DOOO

D001

D002

D003

D004

D005

D006

D007

D008

D009

53258

53259

53260

53261

53262

53263

53264

53265

53248

53249

53250

53251

53252

53253

53254

53255

53256

53257

2 -0

DO 12

D013

0 0 1 4

D015

D016

53266

53267

53268

53269

53270

7 -6

2 -0

D017

D018

53271

53272

7 -4

DESCRIPTION

MOS 6566 VIDEO INTERFACE

CONTROLLER (VIC)

Spr te 0 X Pos

Spr te 0 Y Pos

Spr te 1 X Pos

Spr te 1 Y Pos

Spr te 2 X Pos

Spr te 2 Y Pos

Spr te 3 X Pos

Spr te 3 Y Pos

Spr te 4 X Pos

Spr te 4 Y Pos

Spr te 5 X Pos

Spr te 5 Y Pos

Spr te 6 X Pos

Spr te 6 Y Pos

Spr te 7 X Pos

Spr te 7 Y Pos

Spr tes 0 -7 X Pos (msb o f X coord.)

VIC Control Register

Raster Compare: (Bit 8) See 53266

Extended Color Text Mode: 1 =

Enable

Bit-M ap 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

ALW AYS SET THIS BIT TO 0

M ulti-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 M atrix Base Address (inside

VIC)

S48 COMMODORE 128

Commodore 64 Input/Output Assignments (continued)

HEX DECIM AL BITS D ESCRIPTIO N

3 -1

D019 53273

D01A

D01B

D01C

D01D

D01E

D01F

D020

D021

D022

D023

D024

D025

D026

D027

D028

D029

D02A

D02B

D02C

D02D

D02E

D 400-D 7FF

D400

D401

D402

54272

54273

54274

53274

53275

53276

53277

53278

53279

53280

53281

53282

53283

53284

53285

53286

53287

53288

53289

53290

53291

53292

53293

53294

54272-55295

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

R aster Compare IRQ Flag

IRQ M ask Register: 1 = Interrupt

Enabled

Sprite to Background

Display Priority: 1 = Sprite

Sprites 0 -7 M ulti-Color M ode 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 M ulti-Color Register 0

Sprite M ulti-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 Control— Low-Byte

Voice 1: Frequency Control— High-

Byte

Voice 1: Pulse W aveform W idth—

Low-Byte

D4U5

D406

D407

D40B

D409

D40A

D40B

HEX

D403

D404

D40C

54279

54280

54281

54282

54283

D ECIM AL

54275

54276

BITS

7 -4

3 -0

54277

54278

7 -4

3 -0

7 -4

3 -0

7 -4

3 -0

54284

7 -4

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 549

DESCRIPTIO N

Unused

Voice 1: Pulse W aveform W idth—

High-Nybble

Voice 1: Control Register

Select Random Noise W aveform , 1 =

Select Pulse W aveform , 1 = On

Select Sawtooth W aveform , 1 = On

Select Triangle W aveform , 1 = On

Test Bit: 1 = Disable Oscillator 1

Ring M odulate Osc. 1 with Osc. 3

O utput, 1 = On

Synchronize Osc. 1 with Osc. 3

Frequency, 1 = On

Gate Bit: 1 = Start A tt/Dec/Sus, 0 =

Start Release

Envelope Generator 1: Attack / Decay

C ycle 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 -1 5

Select Release Cycle Duration: 0-15

Voice 2: Frequency Control— Low-Byte

Voice 2: Frequency Control—

High-Byte

Voice 2: Pulse W aveform Width—

Low-Byte

Unused

Voice 2: Pulse W aveform Width—

High-Nybble

Voice 2: Control Register

Select Random Noise W aveform , 1 =

Select Pulse W aveform , 1 = On

Select Sawtooth W aveform , 1 = On

Select Triangle W aveform , 1 = On

Test Bit: 1 = Disable Oscillator 2

Ring M odulate Osc. 2 with Osc. 1

O utput, 1 = On

Synchronize Osc. 2 with Osc. 1

Frequency, 1 = On

Gate Bit: 1 = Start A tt/Dec/Sus, 0

= Start Release

Envelope Generator 2: Attack / Decay

Cycle Control

Select Attack Cycle Duration: 0 -15

550 COMMODORE 128

Commodore 64 Input/Output Assignments (continued)

HEX DECIM AL BITS D ESCRIPTIO N

D40D

D40E

D40F

D410

D411

D412

D413

D414

D415

D416

D417

54285

54286

54287

54288

54289

54290

54291

54292

54293

54294

54295

3 -0

7^»

3 -0

7 -4

3 -0

1 -4

3 -0

7 -4

3 -0

7 -4

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 Control— Low-Byte

Voice 3: Frequency Control—

High-Byte

Voice 3: Pulse W aveform W idth—

Low-Byte

Unused

Voice 3: Pulse W aveform W idth—

High-Nybble

Voice 3: Control Register

Select Random Noise W aveform , 1 =

Select Pulse W aveform , 1 = On

Select Sawtooth W aveform , 1 = On

Select Triangle W aveform , 1 = On

Test Bit: 1 = Disable Oscillator 3

Ring M odulate Osc. 3 with Osc. 2

O utput, 1 = On

Synchronize Osc. 3 with Osc. 2

Frequency, 1 = On

Gate Bit: 1 = Start A tt/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 -1 5

Select Release Cycle Duration: 0-15

Filter Cutoff Frequency: Low-Nybble

(Bits 2 -0 )

Filter Cutoff Frequency: High-Byte

Filter Resonance Control / Voice

Input Control

Select Filter Resonance: 0-15

Filter External Input: 1 = Y es, 0 =

Filter Voice 3 Output: 1 = Y es, 0 =

Filter Voice 2 Output: 1 = Y es, 0 =

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 551

HEX DECIM AL BITS

D418 54296

D419

D41A

D41B

54297

54298

54299

D41C

D 500-D7FF

54300

54528-55295

D 800-D B FF 55296-56319

DCOO-DCFF 56320-56575

DCOO 56320

3 -0

7 -0

7 -6

3 -2

3 -0

DC01 56321

7 -0

3 -2

3 -0

DC02

DC 03

DC04

DC05

DC 06

56322

56323

56324

56325

56326

D ESCRIPTIO N

Filter Voice 1 Output: 1 = Yes, 0 =

Select Filter Mode and Volume

C ut-O ff Voice 3 Output: 1 = O ff, 0

= On

Select Filter High-Pass Mode: 1 =

Select Filter Band-Pass Mode: 1 =

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 (K eyboard, 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 (K eyboard, 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 Register— Port A

(56320)

Data Direction Register— Port B

(56321)

Timer A: Low-Byte

Timer A: High-Byte

Timer B: Low-Byte

552 COMMODORE 128

Commodore 64 Input/Output Assignments (continued)

HEX DECIM AL BITS D ESCRIPTION

DC07

DC08

DC09

DCOA

DCOB

DCOC

DCOD

DCOE

DCOF

56327

56328

56329

56330

56331

56332

56333

56334

56335

6 -5

4 -0

Timer B: High-Byte

Time-of-Day Clock: 1/10 Seconds

Time-of-Day Clock: Seconds

Time-of-Day Clock: M inutes

Time-of-Day Clock: Hours +

AM /PM Flag (Bit 7)

Synchronous Serial I/O Data Buffer

CIA Interrupt Control Register (Read

IR Q ’s/W rite 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 H z, 0 = 60 Hz

Serial Port I/O Mode: 1 = O utput, 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 M ode 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 Tim er A Underflows

W hile CNT Positive

Same as CIA Control Reg. A— for

Timer B

THE COMMODORE 128 A N D COMMODORE 64 MEMORY MAPS 553

DD02

DD03

DD04

DD05

DD06

DD07

DD08

DD09

DDOA

DDOB

DDOC

DDOD

HEX D ECIM A L

DDOO-DDFF 56576-56831

DDOO 56576

BITS

1-0

DD01 56577

56578

56579

56580

56581

56582

56583

56584

56585

56586

56587

56588

56589

DDOE 56590

D ESCRIPTIO N

MOS 6526 Complex Interface

Adapter (CIA) # 2

Data Port A (Serial B us, R S-232,

VIC M emory 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 M em ory Bank

Select (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 Register— Port A

Data Direction Register— Port 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: M inutes

Time-of-Day Clock: H ours +

AM /PM Flag (Bit 7)

Synchronous Serial I/O Data Buffer

CIA Interrupt Control Register (Read

N M I’s/W rite Mask)

NMI Flag (1 = NM I Occurred) /

Set-Clear Flag

FLAG1 NM I (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 = O utput, 0

= Input

554 COMMODORE 128

Commodore 64 Input/Output Assignments (continued)

HEX DECIM AL BITS D ESCRIPTIO N

DDOF 56591

DEOO-DEFF 56832-57087

DFOO-DFFF 57088-57343

6 -5

4 -0

Timer A Counts: 1 = CNT Signals, 0

= System 02 Clock

Force Load Timer A: 1 = Yes

Tim er A Run Mode: 1 = One-Shot,

0 = Continuous

Timer A Output M ode 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-CIock: 1 = A larm , 0

= Clock

Timer B Mode Select:

00 = Count System 02 Clock

Pulses

01 = Count Positive CNT

Transitions

10 = Count Tim er A Underflow

Pulses

11 = Count Timer A Underflows

W hile CNT Positive

Same as CIA Control Reg. A— for

Tim er B

Reserved for Future I/O Expansion

16____

C128 HARDWARE

SPECIFICATIONS

555

556 COMMODORE 128

This chapter describes the Commodore C128 hardware, VLSI integrated circuit require ments, and the relationship between the hardware configuration and the operating system.

The C l 28 personal computer is compatible with C64 software and peripherals. In addition to C64 compatibility, a C l 28 mode exists in which 128K o f 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 C l 28 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 C l 28 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 C l 28 mode, twenty- six extra keys are available, including separate cursor keys, a H E L P key, addi tional function keys, and a true C A PS L O C K 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)) a 2 MHz 8502 operation in 80-column mode a 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 and separate cursor-control keys.

CAPS LOCK key, HELP key

C l 28 HARDWARE SPECIFICATIONS 557

SYSTEM ARCHITECTURE

The C l 28 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 ROM, 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 o f the machine cycle.

The C l28 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, <l>0. Chip selects for the I/O and system ROM are generated by the PLA that tracks the microprocessor addresses during (1> 1.

For system RAM access, the row address is the address from the microproces sor, and the column address is the MMU output address (called the T r a n sla te d A d d r e ss).

The Translated Address outputs are calculated by considering the contents o f the

M M U ’s Configuration Register and RAM Configuration Register. From these values, the MMU generates either normal or translated addresses, a CAS selection. The

CAS-gating circuitry in the MMU enables either one o f 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 MMU 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 MMU 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 V IC’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

558 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 repro duced 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 C l 28 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 imple mented 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 lum i nance 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 discusses various features and constraints of the C128 system. Included are descriptions of the system and its configurations and limiting factors such as power, loading and environment.

Figure 16-1 shows the C l 28 system.

560 COMMODORE 128

SYSTEM BUS ARCHITECTURE

The buses described include:

■ Processor bus

■ Translated address bus

■ Shared address bus

H Color data bus

■ Multiplexed address bus ■ Display bus

T H E PROCESSOR BUS

The Processor Bus includes the data and address buses that are connected directly to the

8502 processor. These buses are designated D0-D7 for the 8-bit data bus and A0-A 15 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

M M U, 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 ZD0-ZD7. 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 o f the different processors. For more information on this logic, consult the section on the Z80 processor and the C l 28 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.

TH E TRANSLATED ADDRESS BUS

Another C l 28 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-T A 15.

These lines reflect the action o f 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 561 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 T A 12- T A 15 high, while TA g-TA n are tri-stated. This allows the VIC chip to drive TA8- T A n as VIC addresses VAg- V A u .

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 Ag to A 15. Thus allows the DMA source to access any peripheral chip except the

MMU. The action of the VIC during a VIC cycle is described below.

T H E M ULTIPLEXED ADDRESS BUS

This section describes two related address buses, the Multiplexed Address Bus and the

VIC M ultiplexed Address Bus, known respectively as MA0-M A 7 and VMA0-V M A 7.

The VIC multiplexed address bus is created during AEC high by multiplexing the high-order translated address bus (TA8- T A 15) with the low-order processor address bus

(A0- 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 o f 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 VMA0-V M A 7 and address lines that are tri-stated during AEC high. M ost of the VIC addresses come out of the VIC chip already multiplexed, but two of them, VA6 and VA7, do not supply column information, as the VIC chip supplies only 14 bits of addressing. The higher- order address bits V A 14 and V A ,5 come from CIA-2, as in the C64. This means the VIC supplies complete VMA0-V M A 7 for a VIC DRAM access or DRAM refresh. The

TA8- T A U supplied by VIC are used in conjunction with another addressing bus for nonmultiplexed VIC cycle addresses, such as character ROM and color RAM accesses.

T H E 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 ROM and color RAM (and the 8563 system RAM indirectly). During AEC high, the shared address bus, designated Sa0- S A 7, is driven by A0- A 7, the low er-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 VA0-V A 7 (VMA0-V M A 7) must come onto the shared address bus. Since VA0-V A g 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 high- order 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

562 COMMODORE 128 drive the shared address bus. During DM A, 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.

TH E COLO R D A T A 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 FLAM. 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.

TH E DISPLAY BUS

The Display Bus is a bus local to the 8563 video controller, consisting of the Display

Address (DA0-D A 7) and the Display Data Bus (DD0-D D 7). This local bus supports the 8563 display RAM, which is completely isolated from the rest of the C l 28 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

O R G A N IZ A T IO N

This section describes the C l 28 memory system. Figure 16-2 is a detailed diagram of the C l 28 Memory Map.

*-< cr

3=0_

CD <-> m

cr siQ- —1 CL

L _ CD CD

Li_ CD CD

L l

_ CJ CD li_ Li_ U_

V *

& -tA-

■W

□

4ft

CD c r w-

Figure 16-2. C l 28 M e m o ry M ap (C 6 4 M ode)

V I

L ,

CD CD C\J

CD CD CD

CD = r

«—<

V *

564 COMMODORE 128

C l 28 ROM MEMORY O R G A N IZ A T IO N

C128 mode is achieved at system reset and is controlled by a bit in the MMU

Configuration Register. In C l 28 mode, the MMU asserts itself in the C l 28 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 for the 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 Kemal provide the C64 mode with the normal Commodore 64 operating system in

ROM. This ROM actually duplicates some of the ROM used in C l 28 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 RO M ’s priority, if one exists. This allows much more flexibility than the hard-wired ROM substitution method, since the

Kemal 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 accom plished 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.

z r

: d d l i J O c c cc

3E X

O —■ CE X

■ - Q Q Q

II II II II d d l i J O x x s : x o •— a: x

_J X CD UJ

=3 t r

Q . ^ II II II II r z z

CE CC UJ O cc x x cc o - a x

- J X O U J d J J

GD CD t_)

»A

0 2

°= tr

1 i d

151

0 3 0 x ~ - a acc o co c ddUJO cc az

: cc

O ' - ' G X r\

\ \ \ aa_ l

3: x ->

□ 0 to cc c

J J

II II II II es

: z x x x x o >-■ a x

—I X LO UJ

5Z X

X X X X o « a x

—I X CD UJ l\ ■ \, \ , \

F igure 16-3. C64 A lte rn a te M em ory C on fig u ratio n s o o

J J

W a

-IA

0 .- 0

O O

566 COMMODORE 128

C l 28 RAM MEMORY O R G A N IZ A T IO N

As shown in Figure 16-2, the RAM 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 o f the 8502 and Z80, according to the RAM banking rules set in the RAM configuration register of the MMU. This area shown as RAM 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 personal ized ahead of time; e.g ., bank 1 as a data bank might be strictly a RAM 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.

W hen dealing with 64K banks of memory at once, it may be desirable to bank in bank 1 but still retain the system RAM (stack, zero page, screen, etc.). The MMU has provisions for what is referred to as com m on 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, IK will be common. Values o f 1, 2 and 3 produce common areas o f 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 RAM is physically located in bank 0.

Zero page and page one can be located (or relocated) independently o f the

RCR. W hen the processor accesses an address that falls within zero page or page one, the MMU adds to the high-order processor address the contents o f the P0 register pair or the PI register pair, respectively, and puts this new address on the bus, including the extended addressing bit A16. RAM banking will occur as appropriate to access the new address. Writes to the P0 and PI registers will be stored in pre latch until a write to the respective low byte page pointer occurs. This prevents a PxH 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 PI 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 o f any kind. Note that upon system reset, the pointers are set to true zero page and true page one.

C l 28 HARDWARE SPECIFICATIONS 567

N O TE: 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 16, 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 MMU 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 C O N S U M P T IO N

Table 16-1 contains values for C l 28 power consumption, including various add-on options.

I.C .

1 Typ

(5v)

I Max I Typ

(9v)

1 Max I Typ I

(12v)

Max

61 2.63

3.83

0.03

0.05

0 0

Unit

SUBTOTAL

PERIPH ER A LS

M agic Desk

RS-232

Auto M odem

Cassette

PE R IPH ER A L TOTAL

C128 AND PERIPH ER A LS

0.24

0.35

0.07

0.10

0 0.07

0.10

0 0.28

0.40

4 0.31

0.45

0.35

0.50

2.94

4.28

0.38

0.55

TO TA L PO W ER , W ORST CASE (WATTS)

5V 12V

Voltage 5.25 9.45 12.60 t o t a l

Power 22.47 5.20 0.00 27.67

T ab le 16-1. C l 28 P o w er C on su m p tion

BUS LO A D IN G

Table 16-2 details AC and DC device loading for the C l 28 system. All capacitances are in picofarads and currents are in microampheres.

568 COMMODORE 128

Dev: DRAM ROM VIC 8563 4016 2332 LS MMU PLA 8502 Z80 4066 SID TOTAL

Signal TTL CIA LOADS

T A .-T A ,,

I c s a 0s a 7

C d „d 7

R/w

R E S

1MHz

. . .

1 1 — 1 1 2

10 2.5 — 10 10 800

8 8 — 4 8 30

............................... 1 1 1

........................ 10 10 400

........................ 4 8 15

5 1

1 . . .

50 2.5

2.5 — — 400

40 8 8 — — 15

................ 1 1 .............. 2

................. 2.5 2.5 .............. 800

................. 8 8 .............. 30

1 1 1 3

2.5

— 2.5

— 0.1

7.5

8 8 8 24

1 1 1 .............. 3

2.5 2.5 2.5 .............. 7.5

8 8 8 .............. 24

........................... 1 ........................ 1 — 1 1 — 3

........................... 2.5 ........................ 2.5 — 2.5 2.5 — 7.5

........................... 8 ........................ 8 — 8 8 — 24

833

420

488

129

820

.......................................................... 2000

.......................................................... 75

............................................. 7.5

............................................. 24

2008

T a b le 16-2. Bus Loading P o w er Requirem ents (Capacitances and C u rren ts)

EN VIR O N M EN TA L 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.

C l 28 HARDWARE SPECIFICATIONS 569

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 C l 28 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 o f 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 M Hz 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 CK) 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.

M A X IM U M RATINGS

Table 16-3 gives the absolute maximum ratings of the 8502 microprocessor.

RATING SYMBOL VALUE

Supply Voltage

Input Voltage v cc

Vin

Storage Temperature Tstg

Operating Temperature Ta

-0.5 to

+7.0

UNIT

Vdc

-0.5 to +7.0

Vdc

-55 to +

150 °C

0 to +70 °C

T a b le 16-3. 8502 Absolute M a x im u m 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.

570 COMMODORE 128

C H A RA CTERISTIC

Input High Voltage

<t>o (in)

/R ES, P0- P 7,/IRQ, Data

Input Low Voltage

4>o (in)

/R ES, P0- P 7,/IRQ, Data

Input Leakage Current

(Vin = 0 to 5.25V , Vcc = 5.25V)

Logic

<l>o (in)

3-State (Off) Inp. Cur.

(Vin = 0 .4 to 2.4V , Vcc = 5.25V)

Data Lines

Output High Voltage

(IOH = -100|xA dc, V cc = 4.75V)

Data, A0- A is , R /W , P

- P

Output Low Voltage

( I 0 L = l-6m A d c, Vcc = 4.75V)

Data, A o-A ]

, R /W , Po-P7

Power Supply Current

Capacitance

(Vin = 0, Ta = 25 C, f = 1MHz)

Logic, Po-P7

Data

A0- A 7

4>o

I t s

VOH

Lc c

C0ut

C<})0

T a b le 16-4. 8502 Basic Electrical Specifications

SYMBOL MIN

VlH

TYP MAX

Vss + 2.4

Vss + 2.2

—

— cc

VlL

Vss-0 .3

— —

UNIT

Vdc

V ss + 0.5

Vdc

Y ss + 0.8

Vdc

IlN

—

Vss + 2.4

—

125

—

2.5

10.0

|xA

|xA jxA

Vdc

V s s

+ 0.4

Vdc

—

50 mA pF pF pF pF

SIG NAL DESCRIPTION

Below is a description o f all the 8502 signals from a functional and electrical point of view:

C L O C K (<£0)— 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 B U S ( A 0- A | 5) — TTL output. Capable o f driving 2 TTL loads at

130 pF.

D A T A BUS ( D o - D 7) — 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 571

RESET — This 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. W hen 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 R/W line will become valid.

IN T E R R U P T R E Q U E S T (IR Q ) — TTL input; requests that the processor initiate an interrupt sequence. The processor will complete execution o f the current instruc tion 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 IN T E R R U P T R E Q U E S T ( N M I) — TTL 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 ES S E N A B L E C O N T R O L (A E C ) — The Address Bus is only valid when the

AEC line is high. W hen low, the address bus is in a high impedance state. This allows D M A ’s for dual processor systems.

I/O P O R T (P o-P 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/W — TTL 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.

R D Y — Ready. TTL level input, used to DMA the 8502. The processor operates normally while RDY is high. When RDY makes a transition to the low state, the processor will finish the operation it is on, and any subsequent operation if it is a write cycle. On the next occurrence of read cycle the processor will halt, making it possible to gain complete access to the system bus.

PROCESSOR TIM IN G

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 M Hz mode.

572 COMMODORE 128

Electrical Characteristics Vcc = 5v ± 5% , Vss = Ov, Ts = 0 °C to 70 °C

CHARACTERISTIC SYMBOL MIN MAX UNITS

AEC setup time

T aec

25 60 ns

Up data setup from <| jo T mds

100 ns

Up write data hold

T hw

40 ns

Data bus to tri-state from AEC

T aedt

120 ns

Read data stable

T dsu

40 ns

Read data hold

T hr

40 ns

Address setup from <j>o

T ads

40 75 ns

Address hold

T ha

40 ns

Address setup from AEC

T aads

60 ns

Address tri-state from AEC

T aeat

120 ns

Port input setup

TpDSU 105 ns

Port input half

TpDH 65 ns

Port output data valid

Tpow 195 ns

Cycle time

T cyc

489 ns

()>o (in) pulse width @ 1.5v (crystal clock) P wh 4>0 235 265 ns

4 ) 0

(in) rise time TR<t>o 10 ns

4>o (in) fall time TF4> o 10 ns

RDY setup time

T rdy

80 ns

T a b le 16-5. Processor T im in g C h a rt

CLO CK 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 1MHz <E>1, 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 M Hz 4>2 cycle, no special attention is necessary.

C l 28 HARDWARE SPECIFICATIONS 573

1 M H z

C l o c k

“ 1

2 M H z

C l o c k

I / O f l e e

Pr o c

C l o c k

I / O f l e e

P r o c __

C l o c k L

Figure 16—4. Clock S tretching in 2 M H z M ode

Note the speed implications of this. In 2 MHz mode, half the I/O access given will occur at an effective speed of 1MHz.

Figure 16-5 is a diagram of the 8502 microprocessor pin configuration.

PHI 1

I/O

H c c e s s

P HI 2

I / O

A c c e s s

574 COMMODORE 128

VUD

PH I _ 0

£4

2 5

2 6

2 7

2_9_

P I

R 1 5

2 3

R 1 4

R 1 3

2jf

R 1 2

R 1 1

R I G

7

] | j |

] I

7

R 1

O J

0 3

J ?

RDT

/ N M I

/ R E S

. 3

/ I R Q

R/ W x 5

REC

□ 7

3 ^

3 3

3J4

3 5

D 1

H

37, v ss

Figure 16-5. T h e 8502 Microprocessor Pin C o n figuration

For information on programming 8502 Machine Language, see Chapter 5, Machine

Language on the C l 28.

Z80 MICROPROCESSOR

HARDWARE SPECIFICATION

The Z80 microprocessor is used as a secondary processor in the C l 28 to run CP/M based programs. Covered in this section is not only the operation of the Z80 as part of

C l 28 HARDWARE SPECIFICATIONS 575 the C128 system, but some important electrical and timing specifications o f the Z80. For more information on Z80 bus interfacing, consult the Zilog Z80 Data Book.

SYSTEM DESCRIPTION

The Z80A, a 4M Hz version of Zilog’s standard Z80 processor, is included as an alternate processor in the C l 28 system. This allows the C l 28 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 o f the shared nature of the bus during Z80 mode, the Z80 must be isolated from the bus during AEC low. Thus, a tri-statable buffer must drive the processor bus during Z80 data writes. The reverse situation occurs during a Z80 read— the 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 AEC high.

C O N T R O L 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.

576 COMMODORE 128

S y s t e n

C l o c k

Z - 8 0

C l o c k

Z - 8 0

0 d d r

Z - 8 0

0 a t a

R e a d

0 a t a

L a t c h

0 a t a

A d d r e s s V a l i d

D a ta V a l i d

V a l i d

Figure 16-6. Z 8 0 Bus T im in g

PROCESSOR SW ITC H IN G

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 C l 28 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 C l 28 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 o f 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.

C l 28 HARDWARE SPECIFICATIONS 577

When the /Z80EN line goes high, it triggers a Z80 /BUSRQ. The Z80 then relin quishes the bus by pulling /BUSACK low. This action drives the 8502 AEC high and

(providing VIC does not request a DMA) also drives the 8502 RDY line high, enabling the 8502. To switch back, a low on the Z80 /BUSRQ will result in Z80 /BUSACK 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 o -A |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 ta 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 o f a two-byte opcode, /Mi is generated, as each byte is fetched. /M j also occurs with an input/output request (/IORQ) to indicate an interrupt acknowledge cycle. The M, line is used to disable the I/O decoder during an interrupt acknowl edge cycle (See Input/Output Request).

M e m o ry 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.

In p u t/O u tp u t Request (/IN 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 /M] 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 /M j; I/O operations never occur during /M ,.

M em o ry Read (/R D ): 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 em o ry W r ite (/W R ): 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 (/R FS H ): 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 lt State (/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.

W hile in the halt state, the Z80 continuously executes NOPs to continue refresh activity.

W a it (/W A IT ): 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.

578 COMMODORE 128

N O TE: 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.

In te rru p t Request (/IN T ): 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 o f the current instruction. When the Z80 acknowledges an interrupt, it generates an interrupt acknowledge signal

(/INRQ during /M i) at the beginning of the next instruction cycle. There are three different modes o f response to a given interrupt. See Bus Request.

N on-M askable In te rru p t (/N M I): Active low input. This interrupt is edge-triggered and cannot be masked against. It is always recognized at the end o f 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 (/B U S R Q ): Active low input that requests the CPU address, data and tri-statable output control signals to go tri-state for sharing and D M A ’s. The lines go tri-state upon termination of the current machine cycle.

Bus Acknow ledge (/B U S A K ): 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.

C lock (4>): Single phase system clock.

C l 28 HARDWARE SPECIFICATIONS 579

J ^ - C

/ M l 7

/ M E M R E Q

/ I N R Q

/ R D

/ W R

^ < 3

/ R F S H

- c

/ H A L T

/ W H I T

/ I N T

/ N M I

8 G

AG 30

A 1 31

A ?

A S

A 4

' A S

A 7

A R

A S

A 1 n 40

A 1 1 1

A 1 ?

A 1 S 3

A 1 4

A 1 5

/ R E S E T

2 9

/ B U S R Q

/ B U S R K

P H I

+ 5 V

G N D

DG 14 n i

15 n ?

n s

A 4 n s 9

12 n s 10

D 7

Figure 16-7. Z 80 M icroprocessor Pin C onfiguration

ELECTRICAL SPECIFICATIONS

ABSOLUTE M A X IM U M 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.

580 COMMODORE 128

PARAM ETER SYMBOL RANGE UNITS

Operating Temperature

Storage Temperature

Input Voltage

Power Dissipation

Tst

Vin

Pcc

0 to + 7 0

-6 5 to + 1 5 0

- 0 .3 to 7.0

1.5

T a b le 16-6. Z 80 A b solute M a x im u m Ratings

°C

°c

Vdc

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.

PA RA M ETER SYMBOL RANGE

Power Supply Variance

Clock Input Low Voltage

Clock Input High Voltage

Input Low Voltage

Input High Voltage

Output Low Voltage v cc

VILC

V,HC

V,L

VlH

V0 L

(IOL= 1.8m A)

Output High Voltage

VoH

(I oh = -250(j.A)

Power Supply Current

Input Leakage Current

(Vjn = 0 tO Vcc)

Icc

I l i

Tri-State Leakage Current

I l o

(V o U T V()H> VOUT = VoiJ

Data Bus Input Leakage Current In)

< V- < V )

2.4 to V cc

200

+10

±10

, -1 0

UNITS

5 ± 5%

- 0 .3 to 0.8

2.0 to Vcc

Vss to 0.4

Vdc

Vcc- 0 .6 to Vcc + 0.3

Vdc

- 0 .3 to 0.8

Vdc

Vdc mA

(JtA

| ji A

(j,A

T a b le 16-7. Z80 D C O p e ra tin g Characteristics

C A PA C ITA N C E

The line capacitance values for the Z80 are given in Table 16-8. All measurements are at T = 25 degrees, F = 1 MHz.

PARAM ETER SYMBOL MAXIMUM UNIT

Clock Capacitance

Input Capacitance

Output Capacitance

C4>

C in

Cout

T a b le 16-8. Z80 Capacitance Values pF pF pF

C l 28 HARDWARE SPECIFICATIONS 581

THE PROGRAMMED

LOGIC ARRAY (PLA)

The 8721 C128 PLA is a programmed version of the Commodore 48 Pin Programmable

Logic Array (Commodore Part #315011). 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 RAM 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 -1, 1/0-2, CIA-1, CIA-2, SID, 8563).

■ I/O access signal indicating an I/O operation is occurring, a CAS ENaBle for DRAM enable.

CH IP SELECT G ENERATION

This PLA device is responsible for defining the banking rules for ROM and RAM 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: ROMBANKLO, ROMBANKH1,

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 o f the PLA font. The C64 selects I/O, RAM and ROM based upon internal control lines: BA, HIRAM, LORAM, and CHAREN.

The status o f 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.

O THE R F U N C TIO N S

The PLA performs a variety o f functions other than chip selects. It creates the write enable strobes for both DRAM and Color RAM. In C128 mode, the C64 control lines

(HIRAM, LORAM and CHAREN) are not needed, since the MMU controls the more sophisticated C l 28 method of banking. Thus, these lines are used to extend the functionality o f the C l 28 at little or no additional cost in hardware. The CHAREN line is

582 COMMODORE 128 used in C l 28 mode to turn the Character ROM on and off in the VIC bank selected; in

C l 28 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 o f 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.

el v c c

R 1 5

| 2

H 1 4

3 li

H 1 3

0 1 2 f i l l

A 1 0

/ R 0 M 4

/ R 0 M 3

/ R 0 M 2

/ R O M 1 y +

-->.36

y +

^37

/ F R O M ■ j i

B A

4 7

C L K

R / W

M A 4

M A 5

2 6

/ V A 1 4

A E C

P L A

/ R O M H

/ R O M L

/ C H A R O M

/ C O L R A M

R 0 M B A N K L 0

R O M B A N K H I

/ 1 O S E

C 1 2 8 / 6 4

/ V I C

/ 1 0 A C C

/ I O C S

/ G A M E

/ E X R O M

/ S D E N

D I R

3 9

1 2 8 / 2 5 6 / ' D W E

/ G W E

L O R A M

H I R A M

C H A R E N

/ D M A A C K

/ Z 8 0 _ E N

/ Z 8 0 _ I 0

/ C A S E N B

C L R B N K

3 2

G N D

Figure 16-8. T h e C l 28 PLA Chip

C l 28 HARDWARE SPECIFICATIONS 583

THE MEMORY

MANAGEMENT UNIT (MMU)

The MMU is designed to allow complex control of the C l 28 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 C l 28 modes including the Z80 mode. The M M U’s features include:

■ Generation of translated address bus (TA8-TA15).

■ Generation of control signals for different processor modes ( C l28, C64, Z80).

■ Generation of CAS selects lines for RAM banking.

■ Generation o f ROMBANK lines for ROM banking.

Programming the MMU is described in detail in Chapter 13.

PH YSIC AL DESCRIPTION

Many of the MMU input and output signals have been discussed informally so far.

This section contains descriptions of the MMU as a physial 48-pin device, includ ing a description o f all pin requirements, input and output signals, and electrical requirements.

PIN REQUIREMENTS

Table 16-9 lists the required MMU pins, indicating the number in each signal category and the total number.

584 COMMODORE 128

SIGNAL NAMES

A 0 - A 3 , A 8 - A 15

A 4 / 5 , A 6/7

D 0 - D 7

T A s-T A 15

Vee

GND

PHI„

RESET

R/W

/C AS 0 -/C A S ,

AEC

/Z 8 OEN

/GAM E

/EXROM

M So-M S,

I/O (M S2)

C128/64 (M S3)

40/80

/FSDIR

MUX

DESCRIPTIO N

Address Lines In

Combined Address Lines In

Data Lines In/Out

Translated Addr. Lines Out

+ 5V

Ground

2 M Hz 4>„ Clock In

System Reset In

Read/W rite 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

M emory Status Out

I/O Select Out

C128 or C64 M ode Out

40/80 Status In

Fast Serial Direction Out

M emory M ultiplex In

TOTAL

Table 16-9. M M U Pin Requirements

NUMBER O F PINS

PIN DESCRIPTION

The following comprises a signal-by-signal description o f the MMU input and output signals. Figure 16—9 shows the MMU pin configuration. Included here are any available bond options.

The MMU input signals are:

■ A0- A 3, A8- A 15: Addresses from the microprocessor. Used to derive chip selects as well as multiplexed address lines. A0- A 3 are found at pins 18-21 on the MM U, while A8- A i 5 are located at pins 24—31.

b A4/5, A6/7: Combined addresses from the microprocessors. Used along with simple addresses, combined in this fashion to lower the pin count of the

M MU. Located at pins 22 and 23 respectively.

h PHIo: 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

CI28 HARDWARE SPECIFICATIONS 585 bus and V A 16 have the processor bus, and no pointer or BIOS translation takes place. This signal occupies pin 16.

■ MUX: The memory multiplex signal, used to clock various sections of the

MMU. It is located at pin 17.

■ Vdd: System + 5 Vdc supply, connected at pin 1.

■ Vss: System Ground, connected at pin 34.

The following represents the MMU bidirectional lines. Some of the port bits detailed here are left for future expansion in a one-directional sense.

■ D0- D 7: Data inputs from microprocessor. Used for writing to internal regis ters. 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 C l 28 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.

n /GAME: This signal is used to sense the /GAME line on the expansion connector in C64 mode and as the color RAM bank control line in C l 28 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 o f 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 MMU output signals, their physical locations on the MMU and their logical levels if applicable.

a TA8- T A 15: 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 12 to T A )5 are each defined to have an internal, depletion mode pull-up with an equivalent resistance of 3.3K O . TA g to T A n each go tri-state during VIC time (AEC low). These are located on the

MMU at pins 10 to 3.

■ MS q -M S i : Also called ROMBANKO and ROMBANK1, 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 C l 28 mode. If they are both low, a system ROM has been selected. If MS] alone is

586 COMMODORE 128 high, then a built-in function ROM has been selected. If MS0 alone is high, then an external function ROM has been selected. Finally, if both 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 MS2. 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 C l 28 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.

■ /CAS q

-C A S ,: CAS enables to control RAM banking. CAS0 enables the first bank of 64K; CAS) enables the second bank of 64K. These are pins 12 and

11, respectively.

ABSOLUTE M A X IM U M RATINGS

IT E M

Irtput Voltage

Supply Voltage

Operating Temperature

Storage Temperature

S Y M B O L R A N G E v in

Vcc

Ts,

U N IT S

-2.0 to +7.0

Vdc

-2.0 to +7.0

Vdc

0 to 70

-55 to 150

°C

Table 16-10. Absolute Maxim um Ratings for the M M U

M A X IM U M OPERATING C O N D IT IO N S

IT E M

Voltage Variance Vcc

Input Leakage Current

Input High Voltage

V ,H

Input Low Voltage

Output High Voltage

V lL

VoH

( I o h

= -200(xA. Vcc = 5V ± 5%)

Output Low Voltage VoL

(IOL = -3 .2 m A , Vcc = 5V ± 5%)

Maxim um Input Current Icc

S Y M B O L R A N G E U N IT S

5.0 ± 5% Vdc

- 1 .0

|xA

Vss + 2.4 to Vcc+ 1 .0

Vdc

Vss—2.0 to Vss + 0.8

Vdc

VS5 + 2.4

Vdc

Vss + 0.4

250

Vdc mA

T ab le 16 - I I. M axim um O p e ra tin g C ond itio n s fo r th e MMU

C l 28 HARDWARE SPECIFICATIONS 587 j l

V O D

R 1 5

R 1 4 f l 1 3

H 1 2

H I 1 f l 1 G

A 9

R 8

A 6 / 7

F m / 5

M U X

R / W

R E C

/ Z 8 0 E N

R 3

R 2

H I

D 3

D 2

D 1

D 0

D 7

D 6

0 5

D 4

P H I __ 0

/ E X R O M

/ G R M E

4 0 / 8 0

MMU

C 1 2 8

I / O

R O M B R N K H I

R O M B R N K L O

/ C R S 0

/ C H S 1

R E S E T

F S D I R

T R 1 5

T R 1 4

T R 1 3

T R 1 2

T R I 1

T R 1 0

T H 9

T R 8

V S S

34[

F igure 16-9. T h e M em ory M a n ag e m en t U n it Pin C onfig u ratio n

588 COMMODORE 128

THE 8564

VIDEO INTERFACE CHIP

The 8564 VIC chip used in the C l 28 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 sup ports 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 V IC OPERATIONS

The 8564 VIC supports all the operations of the previous VIC chip. These functions, quickly summarized, are:

■ Standard color character display mode.

■ M ulticolor character display mode.

■ Extended color character display mode.

■ Standard bit map mode.

■ M ulticolor bit map mode.

■ M ovable image blocks.

■ Movable image block magnification.

■ Movable image block priority

■ M ovable 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.

EXTE N D E D KEYBOARD SC A N N IN G

The 8564 contains a register called the K e y b o a r d C o n tr o l R e g is te r . 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

C l 28 HARDWARE SPECIFICATIONS 589 retaining C64 keyboard compatibility in C64 mode. In this register (register 53295

($D02F)), bits 0 -2 are directly reflected in output lines K0 to K2, while bits 3-7 are unused, returning high when read.

2 M Hz OPERATIO N

The VIC chip contains a register that allows the C l 28 system to operate at 2 MHz instead of the standard 1 MHz speed of the C64. This operating speed, however, disallows the use o f 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 RAM 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 o f the setting o f this bit.

The 2MHz speed is available in C64 mode by setting bit 0 of location 53296

($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 53296 ($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 CLO CK C O N TR O L

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. M ost 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

- D 7: These are the bidirectional data bus signals. They are for communica tion between the VIC and the processor, and can be accessed only during AEC high. They occupy pins 7 through 1 and 47, respectively.

■ D g- D n : These are the extended data bus signals. They are used for VIC communication with the color RAM. 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.

590 COMMODORE 128

■ A0- A 6: Multiplexed address lines, pins 32 through 38. During row address time, A0- A 8 are driven on A0- A 5. During column address time, A8- A 13 are driven on A0- A5 and A6 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 i0: 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.

■ 1MHz: 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 M Hz 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.

B 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 DRAM s, 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 lumi nance 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 591

ITEM SYMBOL RANGE UNIT

Input Voltage

Supply Voltage

Operating Temperature

Storage Temperature

Vin

VCC

Ts,

- 0 .5 to + 7 .0

Vdc

- 0 .5 to + 7 .0

Vdc

0 to 75 °C

-6 5 to 150 °C

Table 16-12. Absolute Maxim um Ratings for V IC Chip

Below is a list o f the maximum operating specifications for the new VIC chip:

ITEM SYMBOL RANGE

Power Supply Variance

Input Leakage Current

Input High Voltage

Input Low Voltage

Output High Voltage

( I o h = -2 0 0 | x A , V cc = 5.0 ± 5% Vdc)

Output Low Voltage

( I 0 L

= -3 .2 m A , V cc = 5.0 ± 5% Vdc)

M ax Power Supply Current

V cc

V ,H

V IL

VoH

VOL

5 .0 ± 5%

- 1 .0

Vss + 2.0 to Vcc

Vss- 0 .5 to V ss + 0.8

V ss

200

+ 2.4

+ 0.4

Table 16-13. Maxim um Operating Specifications for V IC 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.

UNIT

Vdc

|xA

Vdc

Vdc mA

592 COMMODORE 128

LATCH

BIT

ENABLE

BIT

IRST ERST

IMDC EMDC

IMMC EMMC

ILP ELP

IRQ

W HEN SET

Actual raster count = stored raster count (bit 0)

M OB-DATA collision (first bit only) (bit 1)

M OB-M OB 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 BLN K 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 o f 25 rows of 40 character regions per row. For special display purposes, the display window is reduced to 2.4 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.

C l 28 HARDWARE SPECIFICATIONS 593

RSEL NUMBER O F ROWS

24 rows

25 rows

CSEL NUMBER OF COLUMNS

38 columns

40 columns

The R SE L bit (bit 3) is in register 53265 ($D011), and the C SE L bit (bit 3) is in register 53270 ($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 o f 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

0 -2

REG ISTER

53270 ($D016)

53265 ($D011)

FUNCTION

Horizontal Position

Vertical Position

LIG H T 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 subse quent 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.

594 COMMODORE 128

VuU

^ 5

4 3

6 o 5

^ 3

2 o 1

D0

Dl

D2

D3

DU

D5

D6

D7

D8

D9

DIO

Dll

PH_I N

PH_CL

KG

K1

K2

LP

30^

29^

2 6

2 7

2 8

Z80_PH

25^

2MHZ

/ 1 ORCC

■i^o

23^

22^>

3 ±

3 2

^33

3}l_

035

036

3 1 _

.39 o4 0

; 4 2

R5

R6

R7

R8

R9

RIO

Rl 1

RQ

Rl

R2

R3

RU

CO

LO

CO

/RRS

/CRS

R/W

/CS

/IRQ

BR

REC

1 9 ,

20,

2_1^

10^

12c

1 1

15 a16

, 1 7

COLOR

SYNC vss

I24

Figure 16-10. The 8564 V IC Chip

C l 28 HARDWARE SPECIFICATIONS 595

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 informa tion 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 o f 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 program mable bit selects either two 4416 DRAMs (16K total) or eight 4164 DRAMs (64K total) for the display RAM. The C l 28 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.

W hen written to, the five least significant bits convey the address o f an internal register to access in some way. On a read of this register, a status byte is returned. Bit 7 o f 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.

IN TER N A L 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 o f data to the chip through the two levels of indirection. Figure 16-11 is a display of the 8563 internal register map.

596 COMMODORE 128

R 0 Q

R 0 1

R 0 2

R 0 3

R 0 4

R 0 5

R 0 6

R 0 7

R 0 8

R3 9

R 1 0

R l 1

R 1 2

R 1 3

R 1 4

R 1 5

R 1 6

R 1 7

R 1 8

R 1 9

R 2 0

R 2 i

R 2 2

R 2 3

R 2 4

R 2 5

R 2 6

R 2 7

R 2 8

R 2 9

R 3 0

R 3 1

R 3 2

R 3 3

R 3 U

R 3 5

R 3 6

B i t 7 nvwWwwivww'wwu y

B i t 6 B i t 5 B i t 4 B i t 3

H o r i z o n t o l T o t o 1

H o r i z o n t a l D i s p l a y e d

| Bi t 2 |

H o r i z o n t o l S y n c P o s i t i o n

V e r t i c a l S y n c W i d t h H o r i z o n t o l S y n c W i d t h

V e r t i c a 1 T o t a l

V e r t i c a l T o t a l A d j u s t

YV iy

\ \ y w

\ v

\ \

V e r t i c a 1 3 i s p 1 a y e d

V e r t i c a l S y n c P o s i t i o n

Y\Y\Y\V\Y\Y\YIVIYIY\YU y

\ y

; y w

\ y

\ \ y

\ y

\ v

\ yiy

\ y

\V\ y

\ y

\ \ yi

B i t 1 | B i t 0

I n t e r l a c e M o d e

U1.I1.IU1.II.IU1.I1.I1.II.II

C u r s o r M o d e ' nv\v\v\v\Y\Y\v\v\v\v\vivmv\YW\vw\v\viv\v\nv\Y\v\v\Yw\Ymvumi

L n e r e c t e r l o t s 1 V e r t i c a l

C u r s o r S t o r t S c o n _ l n e

C u r s o r E n d S c o n L i n e

D i s p l a y S t o r t H d d r e s s ( h i g h )

D i s p 1 o y S t o r t H d d r e s s (Low)

C u r s o r P o s i t i o n ( H i g h )

C u r s o r P o s i t i o n ( L ow)

L i g h t P e n V e r t i c a l

L i g h t P e n H o r i z o n t a l

U p d a t e L o c o t i o n ( H i g h )

U p d a t e L o c a t i o n ( L ow)

A t t r i b u t e S t a r t H d d r e s s ( H i g h )

H d d r e s s (Low) H t tr b u t e S t a r

C h a r a c t e r I o t o 1 - H o r i z o n t a 1 a wn wvvwiYwivvvn VYY\V\Y\Y\V\V\Y\\VYYYYY

UJ.IJ.IJ.IJ.IJ.IJ.IJ.IJ.tUJ.il

1.I1.II.IUUUJ.IUJ.IJ.1J.IJ

C o p y / F iI 1 R e v S c r e e n B l i n k R a t e

G r e p h / T e x t fltrb £ n b S e n i g r a p h P i x U b l

C h o r o c t e r U i s p 1 o y e d - H o " i z o n t o 1

C h o r o c t e r U i s p i e y e d - V s r t i c o l

V e r t i c o l S m o o t h S c r o l l

H o r i z o n t o l S m o o t h S c r o l l

F o r e g r o u n d C o l o r B a c k g r o u n d C o l o "

A d d r e s s I n c r e n e n t p e r R o w

C h a r a c t e r S e t A d d r e s s uui.ii.ii.ii.ii.ii.ii.ii.ij.ii.ij.ii.ij.ii.ii.ii.ii.iui.ii.ii.iijiui.ii.ii.ii.ii.iuui.ii.ii.ii

U 1 R U / L I U 1 R |Y\Y!Y\Y\Y\Y\Y\Y\Y\Y\YYYl\'\Y\YlY\Y\Y\YlYu\Y\Y\Y[Y\Y\Y\Y\Y\YW\YIVU'IYVYIYIYIY\Y\Y\Y\Y\Y\V\YYYIY

U n d e r l i n e S c a n L i n e

W o r d C o u n t ( c o u n t - 1)

C P U H e a d / W r i t e U a t a b l o c k C o p y S o u r c e H d d r e s s ( H i g h ) b l o c k C o p y S o u r c e H d d r e s s (L ow)

D i s p l a y L n a b l e b e g i n

D i s p l a y E n a b l e E n d

LUJUlJUUUIMlJlJWJUUlJUl.ll.ll.ll.ll.ll.lllll.lUULII.U.II.IUl.lLll.lih.lLI/JLII.IUIJUIJIJIJl

U R H M R e f r e s h p e r S c a n L i n e

Figure 16-11. 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.

T H E 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:

■ D0- 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 o f the chip. Located at pin 4.

■ /CS: Chip select input. This input must be low for selection and proper operation o f the chip. Located at pin 7.

C l 28 HARDWARE SPECIFICATIONS 597

■ /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. In 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.

■ IN IT: Active low input for clearing internal control latches, allowing the chip to begin operation following initial power-on. Connect to /RES in the C l 28, at pin 23.

■ DISPEN: Display Enable output signal, unused in the C l 28. Found at pin 19.

■ RES: This input initializes all internal scan counters, but not control registers.

It is not actively used in the C l 28 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.

TH E LO CAL BUS M A N A G EM EN T 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.

■ DD0-D D 7: Bidirectional local display DRAM data bus, comprising pins 35-36 and 38-42.

■ DA0-D A 7: Local display DRAM multiplexed address bus. Takes up pins

26-33.

■ DR/W: Local display DRAM Read/W rite, pin 21.

■ /RAS: Row Address Strobe for local DRAM, pin 47.

■ /CAS: Column Address Strobe for local DRAM, pin 48.

TH E V ID E O INTERFACE

The final set o f 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 C l28 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,I: 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.

598 COMMODORE 128

;

141 D D 6 oiS. DD 5

3 3 9

D D 4 y 3 8

D D 3 a 3 6

D D 2 a 3 5

D D 1

0 314

D D 0

I 3 7 u

C S D R 7

D R 6

3 3 g

32;

3 1

D R 5

3 Q ^

D n ^

2 9 g

D R 3

D H 2

D H 1

D R 0

2 8

_26^

3 IB D7

1 1 D6

3 1 3

D 5

3 m

D 4

0 1 5

0 1 6 a 1 7

. 1 8

D 2

D 1

DO o n

C D

L O

0 0

/ c n s

/ R f l S

D R / H

H7o

45^

13^

; 8

0 9

3 2 3

/ R S

/ C S

R / W

/ R E S a 2 5 / L P 2

^ 2 / D C L K

V S T N

H S Y N

2 0 g

V S S

112

C C L K

D I S P E N

1 9

T S T

I N I T

2i4p

2 g g

F igure 16-12. T h e 8563 C hip Pin C onfig u ratio n

C l 28 HARDWARE SPECIFICATIONS 599

6581 SOUND INTERFACE DEVICE (SID)

CH IP 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 mini mizes software overhead, facilitating use in arcade/home video games and low-cost musical instruments.

FEATURES

■ 3 TONE OSCILLATORS

Range: 0 -4 kHz

■ 4 WAVEFORMS PER OSCILLATOR

Triangle, Sawtooth,

Variable Pulse, Noise

B 3 AMPLITUDE MODULATORS

Range: 48 dB a 3 ENVELOPE GENERATORS

Exponential response

Attack Rate: 2m s-8 s

Decay Rate: 6 m s-24 s

Sustain Level: 0-peak volume

Release Rate: 6 m s-24 s a OSCILLATOR SYNCHRONIZATION

■ RING MODULATION

■ PROGRAMMABLE FILTER

C utoff range: 30 H z-12 kHz

12 dB/octave Rolloff

Low pass, Bandpass,

High pass, Notch outputs

Variable Resonance

» MASTER VOLUME CONTROL

■ 2 A/D POT INTERFACES

■ RANDOM NUMBER/MODULATION GENERATOR

■ EXTERNAL AUDIO INPUT

600 COMMODORE 128

C A P 1 a 1 c a p 1 b

2 c a p 2A 3 c a p 2B 4

RES 5

<t>2 6

R/W 7

CS 8

A i 10 a 2 11

12 a 4 13

GND 14

.. ^

6581

SID

..... .. ’

22 Dj

21 06

20 d 5

18 d 3

17 d 2

16 Di

28 V DD

27 AUDIO OUT

26 EXT IN

25 < o o

24 P O T X

23 P O T Y

Figure 16-13. 6581 SID Pin Configuration

a C L

C l 28 HARDWARE SPECIFICATIONS 601

Figure 16-14. 6581 Block D iag ra m

602 COMMODORE 128

DESCRIPTION

The 6581 consists o f three synthesizer “ voices” 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/W aveform Generator, an Envelope Generator and an

Amplitude M odulator. The Tone Oscillator controls the pitch o f 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 o f tone color. The volume dynamics of the oscillator are controlled by the Amplitude M odulator 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. Two 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

CAP I A, CAP IB, (PINS 1,2)/ CAP2A.CAP2B (PINS 3,4)

These pins are used to connect the two integrating capacitors required by the program mable filter. C l connects between pins 1 and 2, C2 between pins 3 and 4. Both capacitors should be the same value. Normal operation o f the filter over the audio range

(approximately 30 H z-12 kHz) is accomplished with a value of 2200 pF for C l 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 high- frequency response. In this case, large values for C l 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:

FCmax = 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.

C l 28 HARDWARE SPECIFICATIONS 603

4>2 (PSN 6)

This TTL-level input is the master clock for SID. All oscillator frequencies and envelope rates are referenced to this clock. <J>2 also controls data transfers between SID and the microprocessor. Data can only be transferred when <|>2 is high. Essentially, 4>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 o f 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, <j>2 is high and R/W is high. A W rite to the selected SID register can only occur if CS is low, <j>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 (PIN S 9-13)

These TTL-level inputs are used to select one o f 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.

G N D (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.

D 0-D 7 (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 o f driving two TTL loads in the output mode. The data buffers are usually in the high-impedance off state. During a

W rite 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 o f the microprocessor.

604 COMMODORE 128

P O T X ,P O T Y (PINS 24,23)

These pins are inputs to the A/D converters used to digitize the position of potentiome ters. 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 .7 E -4

W here 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 470 kO and 1000 pF. Note that a separate pot and cap are required for each POT pin.

v cc (PIN 25)

As with the GND line, a separate -1-5 VDC line should be run between SID Vcc and the power supply in order to minimize noise. A bypass capacitor should be located close to the pin.

E X T 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 o f 100 k fl. Any signal applied directly to the pin should ride at a DC level of 6 volts and should not exceed 3 volts p -p . In order to prevent any interference caused by DC level differences, external signals should be

AC-coupled to EXT IN by an electrolytic capacitor in the 1-10 (xf 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 IO O U T (PIN 27)

This open-source buffer is the final audio output of SID, comprised o f the three

SID voices, the filter and any external input. The output level is set by the output volume control and reaches a maximum o f 2 volts p -p at a DC level o f 6 volts. A source resistor from Audio Out to ground is required for proper operation. The recom mended resistance is 1 kO for a standard output impedance.

As the output of SID rides at a 6-volt DC level, it should be AC-coupled to any audio amplifier with an electrolytic capacitor in the 1-10 |xf range.

V DD (PIN 28)

As with Vcc, a separate + 12 VDC line should be run to SID VDD and a bypass capacitor should be used.

C l 28 HARDWARE SPECIFICATIONS 60S

6581 SID CHARACTERISTICS

ABSOLUTE M A X IM U M RATINGS

RATING

Supply Voltage

Input Voltage (analog)

V dd

Vcc v ina

Input Voltage (digital) Vind

Operating Temperature T A

Storage Temperature

T stg

SYMBOL VALUE UNITS

- 0 .3 to + 1 7 VDC

- 0 .3 to + 7 VDC

- 0 .3 to + 1 7 VDC

- 0 .3 to + 7 VDC

0 to + 7 0 °C

-5 5 to + 1 5 0 °C

ELECTRICAL CHARACTERISTICS

(VDD = 12 V D C ± 5 % , Vcc = 5 VDC ± 5 % , T A = 0 to 70° C)

CHARACTERISTIC

Input High Voltage

Input Low Voltage

(RES, 4>2, R/W , CS

A 0-A 4, D 0-1)7)

Input Leakage Current (RES, 4>2, R/W , CS,

A 0-A 4; Vj„ = 0 -5 VDC)

Three-State (Off) (D 0-D 7; Vcc = max)

Input Leakage Current

Output High Voltage

Vin = 0 .4 -2 .4 VDC

Output Low Voltage

(D 0-D 7; Vcc = min,

1 load = 200 (xA)

(D 0-D 7; Vcc = max,

1 load = 3.2 mA)

Output High Current

Output Low Current

(D 0-D 7; Sourcing,

V oh = 2.4 VDC)

(D 0-D 7; Sinking

V ol = 0.4 VDC)

SYMBOL MIN TYP MAX

VIH

VIL lin

I tsi

VoH

VoL

IoH lo

—

- 0 .3

—

2.4

GND —

200

3.2

—

— v cc

0.8

2.5

VDC

|xA

V cc- 0 .7

VDC

0.4

—

UNITS

|xA

VDC

(J l A mA

Input Capacitance (RES, 4>2, R/W , CS,

A 0-A 4, D 0-D 7)

Cin — —

10 pF

Pot Trigger Voltage

Pot Sink Current

(POTX, POTY)

(POTX, POTY) vP„,

Ipot

—

500

Vcc/2 —

— —

VDC jxA

606 COMMODORE 128

CH ARA C TERISTIC

Input Im pedance

Audio Input Voltage

(EXT IN)

Audio Output Voltage (AUDIO OUT; 1 kH load, volume = max)

One Voice on:

All Voices on:

Power Supply Current (VD0)

Power Supply Current (Vcc)

Power Dissipation (Total)

SYMBOL MIN

R„

Vin

100

5.7

—

TYP MAX

150 —

0.5

6.3

3 v ou,

I dd l Cc

P d

—

5.7

0.4

1.0

0.5

1.5

600

6.3

0.6

2.0

100

1000

UNITS k fl

VDC

VAC

VDC

VAC

VAC mA mA mW

6581 SID TIMING

t c y c

T c y c

T c

T r

, T f

T r s

T r h

T a c c

T a h

T c h

T d h

SYMBOL NAME MIN TYP MAX UNITS

Clock Cycle Time 1

—

JJ.S

Clock High Pulse Width 450 500 10,000 ns

Clock Rise/Fall Time

— —

25 ns

Read Set-Up Time

Read Hold time

—

— ns ns

Access Time

Address Hold Time

—

300

— ns ns

Chip Select Hold Time

Data Hold Time

—

— ns

Figure 16-15. Read Cycle

C l 28 HARDWARE SPECIFICATIONS 607

1 R,w WWWW_____________

J ~ ~

T A W S 4 ~ j wmr~

| (-------- t a h

n~x~

«

wxxxw_______

L r k - t v d

— | |-------* - t d h t T

* T W Is m e a s u r e d fr o m th e la te s t o c c u r r in g o f o 2, C S , R /W

T w h

T a w s

T a h

T c h

T v d

T d h

SYMBOL NAME

Write Pulse Width

Write Hold Time

A ddress Set-up Time

Address Hold Time

Chip Select Hold Time

Valid Data

Data Hold Time

Figure 16-16. W rite Cycle

MIN TYP MAX

300

-- --

10 — —

UNITS ns ns ns ns ns ns ns

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 each semitone is exactly the 12th root o f 2 C ^ 2 ) times the frequency of the previous semitone. The table is based on a <j>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 = 440 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 generat ing 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

608 COMMODORE 128 entries (24 bytes) consist o f 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 o f 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 o f the twelve semitones is desired, and which o f the eight octaves the semitone is in.

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 o f envelope parameters allows the simulation of a wide range o f 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:

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 609

ATTACK:

DECAY:

SUSTAIN:

RELEASE:

10 ($A) 500 ms

10 ($A)

300 ms

9 750 ms

Note that the tone can be held at the intermediate SUSTAIN 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

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 o f pianos and harpsichords is somewhat more complicated, but can be generated quite easily with the

ADSR. 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 o f 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:

610 COMMODORE 128

ATTACK:

DECAY:

SUSTAIN:

RELEASE:

15 ($F)

2 ms

6 ms

The real power o f SID lies in the ability to create original sounds rather than simulations o f acoustic instruments. The ADSR is capable of creating envelopes which do not correspond to any “ real” instruments. A good example would be the “ back w ards” 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)

15 ($F)

500 ms

6 ms

72 ms

G E

j

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 6581/SID A pplication

C l 28 HARDWARE SPECIFICATIONS 611

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 16-19 shows the 6526 pin configuration. Figure 16-20 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 o f 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 IN FO R M A TIO N

MXS 6526

FREQUENCY RANGE

NO SUFFIX = lMHz

A = 2MHz

PACKAGE DESIGNATOR

C = CERAMIC

P = PLASTIC

612 COMMODORE 128

Figure 16-19. 6526 C IA Pin Configuration

C128 HARDWARE SPECIFICATIONS 6 13

C N T

TOD

B U F F E R

C N T

B U F F E R

T O D

B U F F E R

D0-D7

SERIAL

P ORT

TOD/

A L A R M

DATA BUS BUFFERS

----------7 \ -------------

P R A

B U F F E R S

D O R A

> PA 0 -PA 7

B U F F E R

B U F F E R S

])> PB 0 -PB 7

D D R B

IRQ

T I M E R I

C R B

FLAG

B U F F E R

IRQ

B U F F E R M A S K

\ _

T I M E R A

C R A

C H IP A C C ES S C O N T R O L

R/W 02 CS R S 3 RS2 RS1 RSO RES

Figure 16-20. 6526 Block Diagram

ABSOLUTE M A X IM U M RATINGS

Supply Voltage, Vcc

Input/Output Voltage, VIN

Operating Temperature, T qp

Storage Temperature, T STg

-0 .3 V to + 7.0V

-0 .3 V to + 7 .0 V

0° C to 70° C

-55° C to 150° C

614 COMMODORE 128

All inputs contain protection circuitry to prevent damage due to high static discharges. Care should be exercised to prevent unnecessary application o f voltages in excess o f the allowable limits.

C O M M E N T

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 o f this specification is not implied and exposure to absolute maximum rating conditions for extended periods may affect device reliability.

ELECTRICAL CHARACTERISTICS

(V cc ± 5%, V ss - O V, T a =

Q-70°C)

CH ARA C TERISTIC

Input High Voltage

Input Low Voltage

Input Leakage Current;

V ,N = VSS + 5 V

(TOD, R /W , FLAG,4>2,

RES, R S 0-R S 3, CS)

Port Input Pull-up Resistance

Output Leakage Current for

High Im pedance State (Three

State); V IN = 4V to 2.4V;

(D B 0-D B 7, SP, CNT, IRQ)

Output High Voltage

Vc c = M IN , I l o a d

- 2 0 0 A (P A 0-P A 7, PC

PB 0-P B 7, D B0-D B7)

Output Low Voltage

Vc c = M IN , I l o a d

< 3.2 mA

Output High Current (Sourcing);

VOH > 2.4V (PA 0-PA 7,

PB 0-P B 7, PC , D B0-D B 7

Output Low Current (Sinking);

VOL < -4V (P A 0-P A 7, PC,

P B 0-P B 7, D B0-D B7)

Input Capacitance

Output Capacitance

Power Supply Current

SYMBOL MIN.

VIH

VIL

I l N

TYP.

+ 2.4

—

-0 .3

—

1.0

MAX.

V cc

—

2.5

UNIT

(xA

R p i

I t s i

I o L

3.1

5.0

± 1 .0

—■

± 1 0 .0

K n

|xA

V q H + 2.4

V cc

V o L

Io H

— —

-2 0 0 -1 0 0 0

+ 0.40

V jjl

3.2

-----

ClN

C o U T

I c c

—

70 mA

100

Pf pf mA

0 2 I N P U T

PERIPHERAL

DATA OUT

DATA IN

D B 7 -D B 0

Figure 16-21. 6526 W rite Tim ing Diagram

C128 HARDWARE SPECIFICATIONS 6 15

Figure 16-22. 6526 Read Tim ing Diagram

6526 INTERFACE SIGNALS

4)2— CLOCK IN P U T

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.

CS—C H IP SELECT IN P U T _

The CS input controls the activity of the 6526. A low level on CS while <J>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 <)>2 by the appropriate address combination.

616 COMMODORE 128

R/W— READ/WRITE IN P U T

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-RS0— ADDRESS INPUTS

The address inputs select the internal registers as described by the Register Map.

DB7-DB0— D A T A BUS IN P U TS /O U TP U TS

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 4>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.

IRQ— INTERRUPT REQUEST O U T P U T

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.

RES— RESET IN P U T

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 TIM ING CHARACTERISTICS

T c y c

T r

, t f

T c h w

T c l w

T p d

Twcs

T a d s

T a d h

T r w s

T r w h

T ds

T d h

SYM BOL C H A RA CTERISTIC

(|>2 Clock

Cycle Time

Rise and Fall Time

Clock Pulse Width (High)

Clock Pulse Width (Low)

Write Cycle

Output Delay From ct>2

CS low while <\>2 high

Address Setup Time

Address Hold Time

R/W Setup Time

R/W Hold Time

Data Bus Setup Time

Data Bus Hold Time

1 MHz

MIN MAX

2MHz

M IN MAX UNIT

1000 20,000 500 20,000 ns

—

25 ns

420 10,000 200 10,000 ns

420

150

—

1000

—

200

—

500 ns ns ns ns

—

— ns ns ns ns

C128 HARDWARE SPECIFICATIONS 6 17

6526 TIM ING CHARACTERISTICS (continued)

SYMBOL CHARACTERISTIC

1 MHz

MIN MAX

Read Cycle

Tps Port Setup Time

Tyvcs(2) CS low while <j>2 high

T ads

Address Setup Time

T a o h

Address Hold Time

T r w s

R/W Setup Time

T r w h

R/W Hold Time

T a c c

Data Access from R S3-R S0

Ico(3) Data Access from CS

T dr

Data Release Time

300

420

—

550

320

—

2MHz

MIN MAX

150

—

UNIT

—

— ns ns

275 ns

150 ns

— ns ns ns ns ns

1. All timings are referenced from VtL max and V1H min on inputs and VOL max and

VDH min on outputs.

2- TWCs is measured from the later of c{>2 high or CS low. CS must be low at least until the end of <J>2 high.

3. TCo is measured from the later of <j>2 high or CS low. Valid data is available only after the later of TACC or Tc o .

REGISTER MAP

RS3 RS2 RSI RS0 REG NAME

DESCRIPTION

0 PRA

1 PRB

2 DDRA

DDRB

TA LO

TA HI

PERIPHERAL DATA REG A

PERIPHERAL DATA REG B

DATA DIRECTION REG A

DATA DIRECTION REG B

TIMER A LOW REGISTER

TIMER A HIGH REGISTER

TB LO

TB HI

TIMER B LOW REGISTER

TIMER B HIGH REGISTER

TOD 10THS 10THS OF SECONDS REGISTER

9 TOD SEC SECONDS REGISTER

A TOD MIN MINUTES REGISTER

B TOD HR HOURS— AM/PM REGISTER

C SDR

D ICR

E CRA

F CRB

SERIAL DATA REGISTER

INTERRUPT CONTROL REGISTER

CONTROL REG A

CONTROL REG B

618 COMMODORE 128

6526 F U N C T IO N A L 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 (PA 0-PA 7,

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.

H A N D S H A K IN G

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 d 7 d 6 d 5 d 4 d ., d 2 d , D„

PRA

PRB p a 7 p a 6 p a 5 p a 4 p a 3 PA2 PA!

PAo p b 7 p b 6 p b 5 p b 4 PB j

PB, PBj PB0

DDRA d p a 7 d p a 6 DPA s d p a 4 d p a 3 DPA2 DPA j DPA|

DDRB d p b

7 d p b

6 d p b

5 d p b 4 d p b , DPB2 DPB!

DPB(

INTERVAL TIMERS (TIM ER A, TIMER B)

Each interval timer consists of a 16-bit read-only Timer Counter and a 16-bit write- only 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 tim er modes allow generation o f 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 6 19

PB O N/O FF

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 o f one cycle duration. The toggle output is set high whenever the timer is started and is set low by RES.

O N E -S H O T /C O N T IN U O U S

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.

IN P U T MODE

Control bits allow selection o f the clock used to decrement the timer. TIMER A can count c)>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.

REG

READ (TIMER)

NAME

TA LO TAL7 t a l 6 TALS TAL4 t a l 3 t a l 2 TAL i TAL o

TA HI t a h 7 t a h 6 t a h 5 t a h 4 t a h 3 t a h 2 TAH!

TAH o

TB LO t b l 7 t b l 6 TBLS t b l 4 TBL, t b l 2 TBL!

TBL o

TB HI t b h 7 t b h 6 TBHS t b h 4 t b h 3 t b h 2 TBH, TBH0

REG

WRITE (PRESCALER)

NAME

TA LO p a l 7 p a l 6 p a l 5 PAL4 p a l 3 p a l 2 PAL] PAL0

TA HI p a h 7 p a h 6 p a h 5 p a h 4 p a h 3 PAH, PAH] PAH0

TB LO p b l 7 p b l 6 PBLS p b l 4 p b l 3 PBL2 PBL, PBL0

TB HI p b h 7 p b h 6 PBHS p b h 4 p b h 3 p b h 2 PBHi PBH0

620 COMMODORE 128

TIM E OF D A Y CLOCK (T O D )

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 regis ters: lOths 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 correspond ing 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 lOths o f 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 O f 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 lOths 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

“ on the fly ,” provided that any read of Hours is followed by a read of lOths o f seconds to disable the latching.

READ

REG NAME

TOD 10THS

TOD SEC

TOD MIN

TOD HR

0 s h

0 0 t 8 t 4 t 2 T,

4 s h

2 SH!

s l 8 s l 4 s l 2 SL, m h

4 m h 2 m h .

m l 8 m l 4 m l 2 ML!

PM 0 0 h h h l 8 h l 4 h l 2 HLj

WRITE

CRB7 = 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 o f 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

C l 28 HARDWARE SPECIFICATIONS 621 shifted out on the SP pin at one half the underflow rate of TIMER A. The maximum baud rate possible is (J>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 TIM ER 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 o f CNT and remains valid until the next falling edge.

A fter 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.

R EG NAME

C SDR S7 Sg S5 S4 S3 S2 Sj So

INTERRUPT C O N TR O L (ICR)

There are five sources of interrupts on the 6526: underflow from TIM ER 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) o f 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 o f 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

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 o f 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

D ICR IR 0 0 FLG SP ALRM TB TA

W RITE (INT MASK)

R EG NAME

D ICR S/C X X FLG SP ALRM TB TA

C O N TR O L 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 = START TIMER A , 0 = STOP TIMER A , This bit is autom at

PBON

OUTM ODE 1 = TOG GLE, 0 = PULSE

RUNM ODE 1 = ONE-SHO T, 0 = CONTINUOUS

LOAD ically reset when underflow occurs during one-shot m ode.

1 = TIM ER A output appears on PB6, 0 = PB6 normal operation.

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).

INM ODE

SPM ODE

1 = TIMER A counts positive CNT transitions, 0 = TIMER A counts

4)2 pulses.

1 = SERIAL PORT output (CNT sources shift clock). 0 = SERIAL

TODIN

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.

C l 28 HARDWARE SPECIFICATIONS 623

CRB:

BIT NAME

5 ,6 INM ODE

7 ALARM

FUNCTION

(Bits C R B0-C R B4 are identical to C R A 0-C R A 4 for TIM ER B with the exception that bit 1 controls the output o f TIM ER B on

PB7).

Bits CRB5 and CRB6 select one o f four input modes for TIM ER

B as:

CRB6

CRB5

TIMER B counts 4>2 pulses.

TIM ER B counts positive CNT transitions.

TIM ER B counts TIMER A underflow pulses.

TIMER B counts TIM ER A underflow pulses while CNT is high.

1 = writing to TOD registers sets ALARM , 0 = writing to TOD registers sets TOD clock.

R E G N A M E

T O D

M O D E

M O D E LO AD

RUN

M O D E

O U T

MO D E PS ON S T A R T

C R A 0 = 6 0 H z

1 = 5 0 H z

0 = I N P U T

0 = <})2

1 = O U T P U T

1 = C N T

1 = F O R C E

L O A D

( S T R O B E )

0 = C O N T 0 = P U L S E

1 = 0 . 5 1 = T O G G L E

-TAo = p b 6 o f f 0 = S T O P

1 = p b 6 o n

1 = S T A R T

R EG

N A M E A LAR M

C R S 0 = T O D

IN M O D E

1 =

A L A R M

LOAD M O D E M O D E PS ON

0 = 4 ) 2

1 = C N T

0 = T A

1 = C N T T A

1 = F O R C E

L O A D

0 = C O N T .

( S T R O B E ) i=o.s.

0 = P U L S E

1 = T O G G L E

0 = P S 7 O F F i = p s 7 o n

ST A R T

G = S T O P

1 = S T A R T

All unused register bits are unaffected by a write and are forced to zero on a read.

624 COMMODORE 128

DYNAMIC RANDOM ACCESS

MEMORY

This section discusses the characteristics of the C l 28 dynamic RAM s, which are currently the 4164 64K-bit RAM. This RAM device is in the 64K by 1-bit configura tion. 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 C l 28 system contains 128K of processor-addressable DRAM in the 64K by 1 configuration, organized into two individual 64K banks. Additionally, the system contains 16K o f 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 Regis ter, 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 o f 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 C l 28 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).

C l 28 HARDWARE SPECIFICATIONS 62S

NAME

Din

/W E

/RAS

Ao a 2

A i

V cc a 7 a 5 a 4 a 3

A<s

Dout

/CAS v

’ ss

Table 16-15. 4164 Pinout

D ESCRIPTION

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

Figure 16-23. T h e 4164 Chip

626 COMMODORE 128

NAME

/OE

D, d 2

/W E

/RAS

As a 4

V dd a 7 a 3 a 2

A ,

Ao d 3

/CAS d 4

Vss

Table 16-16. 4416 Pinout

DESCRIPTIO N

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

A ddress Bit 0

Data Bit 3

Column Address Strobe (Active Low)

Data Bit 4

Power Supply Ground

Figure 16-24. T h e 4464 Chip

C l 28 HARDWARE SPECIFICATIONS 627

READ ONLY MEMORY (ROM)

This section describes the C l 28 system ROM, both from a logical and a hardware point of view. It mentions aspects o f the ROM banking structure, the management of Kernal and BASIC, and explains the physical specifications o f the ROM devices themselves.

SYSTEM ROM DESCRIPTION

In C64 mode, the operating system resides in 16K of ROM, which includes approxi mately 8K for Kemal and 8K for BASIC. In C128 mode, the operating system resides in

48K o f ROM and includes advanced Kemal and BASIC features. The Kernal, by definition, is the general operating system o f 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-4 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 C l 28 mode, each consisting of 16K o f 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 C l 28 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 C l 28, if an address falls into the range of an enabled ROM , the MMU will communicate the status o f 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

628 COMMODORE 128

T IM IN G SPECIFICATION

IN TER N A L 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 M Hz, see Table 16-18.

PARAM ETER

Address Valid to Output Delay

Chip Enable to Output Delay

Output Enable to Output Delay

SYMBOL

T a c c

T c e

T o e

Table 16-17. Internal ROM Tim ing

MIN

300

120

MAX

—

UNIT ns ns ns

R D D R E S 5 -

C H I P

E N A B L E

O U T P U T

E N A B L E

D A T A

Figure 16-25. ROM Tim ing Diagram

EXTERNAL ROMS

All C64 mode external ROMs and many C l 28 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.

PARAM ETER

Address Valid to Output Delay

Chip Enable to Output Delay

Output Enable to Output Delay

SYMBOL

T a c c

T c e

T oe

T a b le 16-18. E xte rn al 2 M H z R O M T im in g

MIN

250

200

100

MAX

—

UNIT ns ns ns

C l 28 HARDWARE SPECIFICATIONS 629

TH E 23128 ROM

P IN

N A M E d 3 d 4 d 5 d 6 d 7

/CE v pp

A n a 7

A5 a 4 a 3

A 2

D„

Dj d 2

GND

A i o

/OE

A n a 9

A i 3

/PGM

V cc

Table 16-19. 23128 ROM Pinout

D E S C R IP T IO N

Programming Voltage

Address Bit 12 (AJ3 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

630 COMMODORE 128

0 ------------

V P P o -------------

H 1 P o ------------n 7 o ------------f l f i

R 5

0 — o ------------n 4 o -------------

H 3 r p o —

0 ------------f l l o -----------f l n

6 ------------n n o ------------m

< 5 -----------n p

G N D

4 —

2 3 1 2 8 v c c

-----------0

/ P G M o f l 1 3

-----------0 f l l i

-----------0

/ 0 E o f l 1 0

— ©

/ C E

D 7

— ©

D 6

-----------0

D 5

-------------©

D 4 :

-------------©

D 3

-------------©

Figure 16-26. The 23128 ROM Chip (BASIC, Kernal, Editor and External Function

ROMs)

C128 HARDWARE SPECIFICATIONS 631

TH E 23256 ROM

2 0

2 1

2 2

1 2

1 0

1 1

NAME

A h

A i

CC v pp a

4 a

3 a

D, d

GND d

3 d

5 d

6 d

/C E -/PG M

/OE

DESCRIPTIO N

Programming Voltage

Address Bit 12

Address Bit 7

Address Bit

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

Data Bit 7

Chip E nable-Program Enable (Active Low)

Address Bit 10

Output Enable (Active Low)

Address Bit 11

Address Bit 9

Address Bit

Address Bit 13

Address Bit 14

Power Supply + 5 Vdc

Table 16-20. 23256 ROM Pinout (Internal or External Function ROMs)

632 COMMODORE 128

0 —

V P P o ------------

R 1 2

0 ------------

R 7

R G o —

0 ------------

R E o ------------

R 4 o ------------

R 3

R P

0 —

________ R 1 o -------------

R R

0 ------------n n o — n i o -----------n p

G N D

- 4 —

2 3 2 5 6

V C C

— e

R 1 4

— o

R 1 3

— o

R 8

— o

R 9

-----------0

R 1 1

— e

/ O E o

R 1 0

— o

/ C E / P G M

D 7

— e

D 6

-----------0

D 5

— 0

D 4

— o

D 3

— 0

Figure 16-27. The 23256 ROM Chip

C l 28 HARDWARE SPECIFICATIONS 633

THE SERIAL BUS

The C l 28 Serial Bus is an improved version of the C64 serial bus. This bus uses

IEEE-488-type addressing, thus maintaining software compatibility between the con sumer 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 transmis sion 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 C l 28 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 o f 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 M ode.)

■ 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.

634 COMMODORE 128

FAST SERIAL BUS

FAST PRO TO CO L

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 C l 28 then assumes it is talking with a slow device. The status o f 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 o f 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 C l 28 mode (at least not simultaneously with the elimination of fast to slow interference).

C l 28 HARDWARE SPECIFICATIONS 63S

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 A D D IT IO N

The C128 can use larger and more sophisticated cartridges than the C64. One o f the main reasons for this is the new banking scheme used in the C l 28 for external cartridges. The C64 uses two hardware control lines, /EXROM and /GAM E, to control banking out o f 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 o f internal routines and naturally become an extended part o f 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 o f 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. O f course, neither can be asserted on C l 28 power-up or C64 mode will automati cally be set.

DM A CAPABILITY

The C l 28 expansion bus supports DMAs in a fashion similar to that o f 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 <3>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 3>2 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 <52 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

636 COMMODORE 128

DMA priority. W hen 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 C l 28 memory mapping the memory map must be set up before being D M A ’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 D M A ’s nondestructively.

C l 28 HARDWARE SPECIFICATIONS 637

EXPA N SIO N BUS P IN O U T

2 d 7 d 6 d 5 d 4 d 3 d 2

D ,

GND

/R O M h

/RESET t a 8 s a 7 s a 6 s a 5 s a 4 s a 3 s a 2

SA ,

/NM I

1MHz

T A 15

T A 14 t a 13 t a 12

T A n

TA,„ t a 9

SA0

GND

H w

NAME

GND

+ 5V

/IRQ

R/W

DCLOCK

I/O,

/GAM E

/EXROM

I / 0 2

/R O M l

/DM A

D ESCRIPTIO N

System Ground

System Vcc

System V cc

Interrupt Request

System Read W rite Signal

8.18 M Hz Video Dot Clock

I/O Chip Select: $DEOO-$DEFF, Active Low

Sensed for M emory Map Configuration

I/O Chip Select: $D F00-$D FFF, Active Low.

External ROM Chip Select, $8000-$B FFF in C128 M ode

($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

External ROM Chip Select, $C 000-$FFFF in C128 M ode

($C 000-$FFFF in C64 mode)

System Reset Signal

Non-M askable Interrupt Request

System 1MHz cb0 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

T ab le 16-21. E xpansion Bus P in o u t

638 COMMODORE 128

THE VIDEO INTERFACE

The C l 28 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 C l 28 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.

TH E 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.

M O D U L A T O R SPECIFICATIO N

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.

M O N IT O R O U T P U T

The VIC video output provides the signals shown in Table 16-22.

SIGNAL

Lum inance/Sync

Chroma

Composite

Audio

LEVEL

1 V p-p

I V p-p

1 V p-p

IM PEDENCE

75 f l

IK f l

Table 16-22. V IC Video O utput Signals

DC O FFSET

0.5 V

V ID E O C O N N E C T O R P IN O U T

The VIC video connector exists physically as an eight-pin DIN connector. It provides the signals shown in Table 16-23.

C l 28 HARDWARE SPECIFICATIONS 639

SIGNAL

Lum inance/Sync

Ground

Audio Out

Composite

Audio In

Chroma

N .C .

Table 16-23. Video Connector Signals

TH E 8563 VID E O 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.

M O N IT O R O U T P U T

Table 16-24 shows the signals provided by the 8563 output.

SIGNAL

Red

Green

Blue

Intensity

HSync

VSync

Composite

Full Intensity

H alf Intensity

Sync

LEVEL

TTL

2.0 V

1.5 V

0.5 V

Table 16-24. 8563 O utput Signals

IM PEDEN CE

TTL

7 5

V ID E O C O N N E C T O R P IN O U T

The 8563 video connector is an IBM-style D9 connector, providing the signals shown in

Table 16-25.

640 COMMODORE 128

SIGNAL

Ground

Red

Green

Blue

Intensity

M onochrome (non-standard)

Horizontal Sync

Vertical Sync

T a b le 16-25. 8563 V ideo C o n necto r Pinout

THE KEYBOARD

The C l 28 Keyboard is an advance over the standard C64 keyboard, while still maintain ing full compatibility. It has several extra keys that are used in C l 28 mode, but not in

C64 mode. It features a numeric keypad, a H E L P key, extended function keys, a true CA P S L O C K key, and a 40/ 80 column switch key, all o f which are strobed by the VIC chip or tied to dedicated 8502 or MMU I/O lines.

CONNECTOR PINOUT

The C l 28 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.

D-TYPE

SIGNAL

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

K„

Ki k 2

40/80

Alpha Lock

T a b le 16-26. T h e Keyboard C o n necto r Pinout

C128 HARDWARE SPECIFICATIONS 641

642 COMMODORE 128

THE C l28 KEYBOARD TABLE

CO C l C2 C3 C4 C5 C6 C7 K0 K1 K2

PIN13 PIN19 PIN18 PIN17 PIN16 PIN15 PIN14 PIN20 PIN21 PIN22 PIN23

GND

PIN-1

PIN12

R l

PIN11

PIN10

PIN5

PIN8

PIN7

PIN6

PIN9

INS

DEL

RET

F5 t

Z s

—

LEFT

SHIFT

)

P lb

* i

« -

HELP ESC ALT

8 + 0

(

[

]

CLR

HOM

CTRL

5 -

TAB LINE

FEED

RIGHT SPACE

SHIFT BAR

2 ENTER

= 4 6 t

« -

@ •ir Q 7 9

•>

RUN

STO P

1 3 NO

SCRL

/ (LOCKING)

NM I

PIN3

40/80

PIN24

P6510

PIN25

40/80

DSPLY

/ (LOCKING)

CAPS

LOCK

N O T E : Pins RO through R7 pertain to the keyboard row values for the keyboard SCAN.

These pins correspond to bits 0 through 7 o f location 56321 ($DC01).

Pins CO through C7 are the keyboard’s column values, which correspond to bits 0 through 7 o f location 56320 (SDC00).

Pins K0 through K2 pertain to the C128 keyboard control register bit, 0 through 2 o f location 53295 ($D02F).

APPENDIXES

A ppendix A - B A SIC Language E rro r Messages

Appendix B - D O S E rro r Messages

Appendix C - Connectors/Ports fo r Peripheral

Equipm ent

A ppendix D - Screen Display Codes

644

648

652

658

A ppendix E - A S C II and C H R $ Codes

A ppendix F - Screen and C olor M em o ry Maps

Appendix G - D erived T rig o n o m etric Functions

Appendix H - C o ntro l and Escape Codes

Appendix I - B A SIC 7.0 A bbreviations

Appendix J - Disk C om m an d S u m m ary

A ppendix K -

P a rt 1-C om m odore 128 C P/M 676

P art 11-Calling C P /M B IO S , 8502 B IO S , and C P/M

User Functions in Z80 Machine Language 702

709 P a rt lll-T h e C P/M System M em o ry M ap

A ppendix L - C o m m o d ore 128 System Schematics 721

660

663

665

666

670

674

643

644 COMMODORE 128

A PPEN D IX 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 # ERROR NAME DESCRIPTION

TOO MANY FILES

FILE OPEN

FILE NOT OPEN

FILE NOT FOUND

DEVICE NOT PRESENT

NOT INPUT FILE

NOT OUTPUT FILE

8 MISSING FILE NAME

9 ILLEGAL DEVICE NUMBER

NEXT WITHOUT FOR

SYNTAX

There is a limit of ten files OPEN at one time.

An attempt was made to open a file using the number o f an already open file.

The file number specified in an I/O state ment must be opened before use.

Either no file with that name exists (disk) or an end-of-tape marker was read (tape).

The required I/O device is not available or buffers deallocated (cassette). Check to make sure the device is connected and turned on.

An attempt was made to GET or INPUT data from a file that was specified as output only.

An attempt was made to send data to a file that was specified as input only.

File name missing in command.

An attempt was made to use a device im properly (SAVE to the screen, etc.).

Either loops are nested incorrectly, or there is a variable name in a NEXT statement that doesn’t correspond with one in FOR.

A statement not recognized by BASIC. This could be because of a missing or extra parenthesis, a misspelled key word, etc.

APPENDIXES 64S

ERROR # ERROR NAME

12 RETURN WITHOUT GOSUB

OUT OF DATA

ILLEGAL QUANTITY

OVERFLOW

OUT OF MEMORY

UN DEF’D STATEMENT

BAD SUBSCRIPT

REDIM ’D ARRAY

DIVISION BY ZERO

ILLEGAL DIRECT

TYPE MISMATCH

STRING TOO LONG

FILE DATA

FORMULA TOO COMPLEX

C A N T CONTINUE

UN D EF’D FUNCTION

DESCRIPTION

A RETURN statement was encountered when no GOSUB statement was active.

A READ statement is encountered without any data left to READ.

A number used as the argument of a func tion or statement is outside the allowable range.

The result of a computation is larger than the largest number allowed (1.7014118 34E

+ 38).

Either there is no more room for program code and/or program variables, or there are too many nested DO, FOR or GOSUB state ments in effect.

A referenced line number doesn’t exist in the program.

The program tried to reference an element of an array out of the range specified by the DIM statement.

An array can only be DIMensioned once.

Division by zero is not allowed.

INPUT, GET, IN P U T #, G E T # and GET-

KEY statements are allowed only within a program.

This error occurs when a numeric value is assigned to a string variable or vice versa.

A string can contain up to 255 characters.

Bad data read from a tape or disk file.

The computer was unable to evaluate this expression. Simplify the expression (break into two parts or use fewer parentheses).

The CONT command does not work if the program was not RUN, if there was an error, or if a line has been edited.

A user-defined function that was never de fined was referenced.

646 COMMODORE 128

ERROR # ERROR NAME

28 VERIFY

LOAD

BREAK

C A N ’T RESUME

LOOP NOT FOUND

LOOP WITHOUT DO

DIRECT MODE ONLY

NO GRAPHICS AREA

BAD DISK

BEND NOT FOUND

38 LINE NUMBER TOO LARGE

UNRESOLVED REFERENCE

UNIMPLEMENTED

COMMAND

DESCRIPTION

The program on tape or disk does not match the program in memory.

There was a problem loading. Try again.

The STOP command was issued in a pro gram or the S T O P key was pressed to halt program execution.

A RESUME statement was encountered without a TRAP statement in effect.

The program has encountered a DO state ment and cannot find the corresponding

LOOP.

LOOP was encountered without a DO state ment active.

This command is allowed only in direct mode, not from a program.

A command (DRAW, BOX, etc.) to create graphics was encountered before the

GRAPHIC command was executed.

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 “ IF . . . THEN

BEGIN” or “ IF . . . 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 re sult in a line number greater than 63999 being generated; therefore, the renumbering was not performed.

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.

A command not supported by BASIC 7.0 was encountered.

ERROR # ERROR NAME

41 FILE READ

APPENDIXES 647

DESCRIPTION

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).

648 COMMODORE 128

A PPEN D IX 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 MESSAGE AND DESCRIPTION

READ ERROR (block header not found)

The disk controller is unable to locate the header o f the requested data block. Causes: an illegal sector number, or the header has been destroyed.

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 unformat ted or improperly seated diskette. Can also indicate a hardware failure.

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.

READ ERROR (checksum error in data block)

This error message indicates there is an error in one or more o f 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 ground ing problems.

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.

W RITE 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.

W RITE 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 649

ERROR

NUMBER

ERROR MESSAGE AND DESCRIPTION

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.

W RITE ERROR

This error message is generated when a data block is too long and overwrites the sync mark of the next header.

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.

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.

SYNTAX ERROR (invalid command)

The DOS does not recognize the command. The command must start in the first position.

SYNTAX ERROR (invalid command)

The command sent is longer than 58 characters. Use abbreviated disk commands.

SYNTAX ERROR (invalid file name)

Pattern matching is invalidly used in the OPEN or SAVE command. Spell out the file name.

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.

SYNTAX ERROR (invalid command)

This error may result if the command sent to the command channel

(secondary address 15) is unrecognized by the DOS.

RECORD NOT PRESENT

Result of disk reading past the last record through IN P U T # 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 PR IN T # command), the error message may be ignored. IN PU T # and G E T # should not be attempted after this error is detected without first repositioning.

650 COMMODORE 128

ERROR

NUMBER

ERROR MESSAGE AND DESCRIPTION

OVERFLOW IN RECORD

P R IN T # 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.

FILE TOO LARGE

The record position within a relative file indicates that disk overflow will result.

W RITE FILE OPEN

This message is generated when a write file that has not been closed is being opened for reading.

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.

FILE NOT FOUND

The requested file does not exist on the indicated drive.

FILE EXISTS

The file name o f the file being created already exists on the diskette.

FILE TYPE MISMATCH

The requested file access is not possible using files of the type named.

Reread the chapter covering that file type.

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.

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.

ILLEGAL SYSTEM T OR S

This special error message indicates an illegal system track or sector.

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 651

ERROR

NUMBER

ERROR MESSAGE AND DESCRIPTION

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.

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.

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.

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.

652 COM M ODORE 128

A PPEN D IX C

CONNECTORS/PORTS FOR

PERIPHERAL EQUIPMENT

1. Power Socket

2. Power Switch

3. Reset Button

4. Controller Ports

5. Expansion Port

6. Cassette Port

Serial Port

Composite Video Connector

Channel Selector

10.

RF Connector

11.

RGBI Connector

12.

User Port

5 6 7 8 9 10 11 12

APPENDIXES 653

SIDE PANEL C O N N E C T IO N S

1. Power Socket— The free end of the cable from the power supply is attached here.

2. Power Switch— Turns on power from the transformer.

3. Reset Button— Resets computer (warm start).

4. Controller Ports— There are two Controller ports, numbered 1 and 2. Each Con troller 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

TYPE

JOYAO

JOYA1

JOYA2

JOYA3

POT AY

BUTTON A/LP

+ 5V

GND

POT AX

NOTE

M AX. 50mA

CONTROLLER PORT 2

TY PE

JOYBO

JOYB1

JOYB2

JOYB3

POT BY

BUTTON B

+ 5V

GND

POT BX

NOTE

M AX. 50mA

REAR C O N N E C T IO N S

5. Expansion Port— This rectangular slot is a parallel port that accepts program or game cartridges as well as special interfaces.

654 COMMODORE 128

CARTRIDGE

EXPANSION PORT

TY PE

D l

DMA

GND

TYPE

GND

+ 5V

IRQ.

R/W

Dot Clock

I/O 1

GAME

EXROM

I/O 2

ROML

PIN w

TYPE

GND

TYPE

GND

ROMH

RESET

NMI

S 02

A15

A14

A13

A12

A l l

A10

22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 8 5 4 3 2

W W f W ■

.................................................................

Z Y X W V U T S R P N M L K J H F E 0 C 8 A

(view of port from the back of the C128)

6. Cassette Port— A 1530 Datassette recorder can be attached here to store programs and information.

CASSETTE PORT

A -l

B-2

C-3

D -4

E-5

F-6

TY PE

GND

+ 5 V

CASSETTE M OTOR

CASSETTE READ

CASSETTE W RITE

CASSETTE SENSE

1 2 3

5 6

APPENDIXES 655

7. Serial Port— A Commodore serial printer or disk drive can be attached directly to the Commodore 128 through this port.

SERIAL I/O PORT

PIN TYPE

SERIAL SRQIN

GND

SERIAL ATN IN/OUT

SERIAL CLK IN/OUT

SERIAL DATA IN/OUT

RESET

8. Composite Video Connector— This DIN connector supplies direct audio and com posite 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

TYPE

LUM/SYNC

GND

AUDIO OUT

VIDEO OUT

AUDIO IN

COLOR OUT

NOTE

Luminance/SYNC output

Composite signal output

Chroma signal output

No connection

656 COMMODORE 128

9. Channel Selector— Use this switch to select which TV channel (L = channel 3, H

= channel 4) the com puter’s picture will be displayed on when using a television instead of a monitor.

10. RF Connector— This connector supplies both picture and sound to your television set. (A television can display only a 40-column picture.)

11. RGBI Connector— This 9-pin connector supplies direct audio and an RGBI (Red/

Green/ Blue/Intensity) signal. This is the 80-column output.

4 3 2

O O O 0

1 o o o o

9 8 7 6

RGBI CONNECTOR

PIN SIGNAL

1 Ground

2 Ground

3 Red

4 Green

5 Blue

6 Intensity

7 M onochrome

8 Horizontal Sync

9 Vertical Sync

12. User Port— Various interface devices can be attached here, including a Commo dore modem.

U SER I/O P O R T

TYPE

GND

+ 5V

RESET

CNT1

SP1

CNT2

SP2

PC2

SER. ATN IN

9 VAC

GND

NOTE

M AX. 100mA

TYPE

GND

FLAG2

PBO

PB1

PB2

PB3

PB4

PB5

PB6

PB7

PA2

GND

NOTE

1 2 3 4 5 6 7 8 9 10 11 12

A B C D E F H J K L M N

APPENDIXES 657

658 COMMODORE 128

APPENDIX D

SCREEN DISPLAY CODES

SCREEN DISPLAY CODES

40 CO LUM NS

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 SET 2 POKE SET 1 SET 2 POKE

B a

N b 2

C c 3

E d 4

F e f

9 h

8 i

9 w j

X k

L I

M m

[ z

T n 14

0 15 q

17 r 18 s 19 t

20 u

22 w

24 y

25 z

SET 1 SET 2 POKE

£ 28

]

29 t

« -

SPACE p f f e 32

)

(

I 33

APPENDIXES 659

SET 1 SET 2 POKE SET 1 SET 2 POKE SET 1 SET 2 POKE

J m

□

□ m

□ a

□ S

E a a

□ a

□

□ m n 0

79 n

P 80

□

82 R

□

83 S

84 T

85 U

86 V f f l

87 w D

X 88

Y 89

□

90 z n

92 a

93 m

0 a

SPACE

1 a

□

B a

99 n

2 5

C o d e s from 128-255 are reversed im ages of co d e s 0-127.

100

101

102

103

104

117

122

123

124

125

126

127

118

119

120

121

110

111

112

113

114

115

116

105

106

107

108

109

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 character- based commands (such as switch to upper/lower case) that could not be enclosed in quotes.

PRINTS PRINTS CHR*

B53 oisABiEsQggB

ENABLES U f l j J Q 9 ■ SPACE 1

■ return^H 13 r s

■

1 s owl i

R cast

1 4

JHB

J E li*

)

(

CHR*

PRINTS CHR*

6 1

PRINTS

V w

Y z

[

CHR*

PRINT!

CHRS PRINTS CHRS PRINTS CHRS PRINTS CHRS n n

□

£ 92 115 f4 38 161

B t

]

□

116

117 f6 f8

162

H n

163 q

□ a

□

96 □

118

119

■ S W U l ' M TO

■ u P P t H cast

I 42

96 □

120

121

□

164

165

43 m

166

EOL 44

□

167

99 122 fm n a 168

100

101

102

103

104

105

106 f f l

123

124 ■ clr m

MmM

□

169

170 a

127 Lt. Red 150

H i

— i

171 m 125 B 148 f f l

126 Brown 149

D3 172

173

174

128 Dk. Gray 151

— i

175

Orange 129 Gray 152 y i

— i

130 Lt. Green 153

176

107

108

109

110

111 f1 f3

131 Lt. Blue 154

132 Lt. Gray 155

133

134

156

157

B 177

B 178 f f l 179

C 180 f5 135 112

113

114 f7

136

H I *

137 ^

. S P A C E

158

159

160

181 c

182 □ n

183

CHRS PRINTS CHRS PRINTS CHRS PRINTS CHRS

PRINTS n

184

□

186

188

190 y

185

187 y j

189 i

191

C O D E S

CO D E S

CO D E

192-223

224-254

255

SA M E AS

96-127

160-190

126

APPENDIXES 661

662 COMMODORE 128

N O TE: 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$

129

149

151

40-COLUM N (VIC C O M PO SITE)

Orange

Brown

Dark Gray

8 O-COLUMN (8563 RGBI)

Dark Purple

Dark Yellow

Dark Cyan

APPENDIXES 663

A PPEN D IX F

SCREEN A N D COLOR MEMORY MAPS—

C l 28 MODE, 40-COLUMN

A ND C64 MODE

The maps below display the memory locations used in 40-column mode (C l28 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 IC C H IP (4 Q -C O L U M N ) SCREEN M E M O R Y M AP

COLUMN

55656

55696

55736

55776

55816

55856

55896

55936

55976

56016

55296 -

55336

55376

55416

55456

55496

55536

55576

55616

56056

56096

56136

56176

56216

56256

55335

10 o

The Screen Map is POKEd with a Screen Display Code value (see Appendix D).

For example:

P O K E 1024, 13 (from BANK 0 or 15) will display the letter M in the upper-left corner of the screen.

664 COMMODORE 128

V IC C H IP (4 0 -C Q L U M N ) C O L O R M E M O R Y M AP

0 10

COLUMN

20 30

1784

1824

1864

1904

1944

1984

1464

1504

1544

1584

1624

1664

1704

1744

1 024 ------- -

1064

1104

1144

1184

1224

1264

1304

1344

1384

1424

1063

10 o t

2023

If the color map is POKEd with a color value, this changes the character color. For example:

P O K E 55296,1 (from BANK 15) will change the letter M inserted above from light green to white.

C O L O R C O D E S — 4 0 C O L U M N S

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 M edium Gray

13 Light Green

14 Light Blue

15 Light Gray

Border Control M emory 53280

Background Control Memory 53281

APPENDIXES 665

A PPEN D IX G

DERIVED TRIGONOMETRIC

FUNCTIONS

FUNCTION

SECANT

COSECANT

COTANGENT

INVERSE SINE

INVERSE COSINE

INVERSE SECANT

INVERSE COSECANT

INVERSE COTANGENT

HYPERBOLIC SINE

HYPERBOLIC COSINE

HYPERBOLIC TANGENT

HYPERBOLIC SECANT

HYPERBOLIC COSECANT

HYPERBOLIC COTANGENT

INVERSE HYPERBOLIC SINE

INVERSE HYPERBOLIC COSINE

INVERSE HYPERBOLIC TANGENT

INVERSE HYPERBOLIC SECANT

INVERSE HYPERBOLIC COSECANT

INVERSE HYPERBOLIC COTANGENT

BASIC EQUIVALENT

SEC(X) = l/COS(X)

CSC(X) = 1/SIN(X)

COT(X) = 1/TAN(X)

ARCSIN(X) = ATN(X/SQR(-X*X +1))

ARCCOS(X) = -ATN(X/SQR

(-X*X + 1)) + tt/2

ARCSEC(X) = ATN(X/SQR(X*X-I))

ARCCSC(X) = ATN(X/SQR(X*X-1))

+ (SGN(X)-1)* tt /2

ARCCOT(X) = -ATN(X) + tt /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 + X)/(l-X))/2

ARCSECH(X) = LOG(SQR

(-X *X +1)+1/X )

ARCCSCH(X) = LOG(SGN(X)*SQR

(X*X+1)/X)

ARCCOTH(X) = LOG((X + l)/(x-l))/2

666 COMMODORE 128

A PPEN D IX H

CONTROL AND ESCAPE CODES

C O N TR O L 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.

PR IN T

C O D ES K EY CO D ES

(CHR$) KEY SEQUENCE FUNCTION

CHR$(2)

CHR$(5)

CHR$(7)

CHR$(8)

CHR$(9)

CHR$(10)

CHR$(11)

CHR$(12)

CHR$(13)

CHR$(14)

CHR$(15)

CHR$(17)

CHR$(18)

CHR$(19)

CTRL B

CTRL 2 or CTRL E

CTRL G

CTRL H

CTRL I

CTRL J

CTRL K

CTRL L

CTRL M

CTRL N

CTRL 0

CRSR DOW N/CTRL

CTRL 9 or CTRL R

HOME

N O T E : (40) = 40-column screen only.

(80) = 80-column screen only.

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)

M ove the cursor down one row

Cause characters to be printed in reverse field

Move the cursor to the home po sition (top left) of the display (the current window)

EFFEC T IV E

IN M ODE:

C64 C128

/ y y y

/ y y y y

/ y y y y y y y y y y

APPENDIXES 667

P R IN T

C O D ES K EY CODES

(CHR$)

CHR$(20)

KEY SEQUENCE

DEL or CTRL T

FUNCTION

Delete last character typed and move all characters to the right o f the deleted character one space to the left

CHR$(24)

CHR$(27)

CHR$(28)

CHR$(29)

CHR$(30)

CHR$(31)

CHR$(34)

CHR$(129)

CHR$(130)

CHR$(131)

CHR$(133)

CHR$(134)

CHR$(135)

CHR$(136)

CHR$(137)

CHR$(138)

CHR$(139)

CHR$(140)

CHR$(141)

CTRL X, CTRL TAB or O TAB

ESC or CTRL[

CTRL 3 or CTRL £

CRSR or CTRL]

CTRL 6 or CTRL

CTRL 7 or CTRL =

O 1

SHIFT RETURN,

CTRL ENTER,

O ENTER or

O RETURN

CHR$(142)

CHR$(143)

N O T E : (40) = 40-column screen only.

(80) = 80-column screen only.

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 FI 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)

EFFEC T IV E

IN M ODE:

C64 C12

/ y y

/ y

J y

J y y y y y y y y y y y

668 COMMODORE 128

PR IN T

CO D ES KEY CODES

(CHR$)

CHR$(144)

CHR$(145)

CHR$(146)

C HR $(I47)

CHR$(148)

CHR$(149)

CHR$(150)

CHR$(151)

CHR$(152)

CHR$(153)

CHR$(154)

CHR$(155)

CHR$(156)

CHR$(157)

CHR$(158)

CHR$(159)

KEY SEQUENCE

CTRL 1

CRSR UP

CTRL 0

CLEAR HOME

INST

CTRL 5

CRSR LEFT

CTRL 8 or CTRL 4

N O T E : (40) = 40-column screen only.

(80) = 80-column screen only.

FUNCTION

Set character color to black (40) and (80)

M ove 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 o f 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 m edium 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)

EFFEC T IV E

IN M ODE:

C64 C12 y y y y y y y y y y y y y y y y y y y y y y y y y y y y y y

APPENDIXES 669

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 ESC key, fol lowed by pressing the key listed in the right column.

ESCAPE FUNCTION

Cancel quote, reverse, flash

Erase to end o f current line

Erase to start o f current line

Clear to end o f screen

M ove to start o f current line

M ove to end o f current line

Enable auto-insert mode

Disable auto-insert mode

Delete current line

Insert line

Set default tab stop (8 spaces)

Clear all tab stops

Enable scrolling

Disable scrolling

Scroll up

Scroll down

Enable bell (by controI-G)

Disable bell

Set cursor to nonflashing mode

Set cursor to flashing mode

Set bottom right corner of screen window at cursor position

Set top left corner o f screen window at cursor position

Swap 40/80 colum n display output device

SEQUENCE KEY

ESC o

ESC Q

ESC P

ESC @

ESC J

ESC K

ESC A

ESC C

ESC D

ESC I

ESC Y

ESC Z

ESC L

ESC M

ESC V

ESC W

ESC G

ESC H

ESC E

ESC F

ESC B

ESC T

ESC X

The following ESCape sequences have an effect on an 80-column screen on

ESCA PE FUNCTION

Change to underlined cursor (80)

Change to block cursor (80)

Set screen to reverse video (80)

Return screen to normal (non reverse video) state (80)

SEQUENCE KEY

ESC U

ESC S

ESC R

ESC N

670 COMMODORE 128

A PPEN D IX I

BASIC 7.0 ABBREVIATIONS

N O T E : 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 follow ing the word SHIFT.

KEYW ORD

ABS

APPEND

ASC

ATN

AUTO

BACKUP

BANK

BEGIN

BEND

BLOAD

BOOT

BOX

BSAVE

BUM P

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 0

C SHIFT L

C SHIFT M

COLL SHIFT E

COL SHIFT L

COL SHIFT O

C SHIFT O none

CO SHIFT P none

D SHIFT A none

DCL SHIFT E

D SHIFT C none

DE SHIFT L

D SHIFT I

K EYW ORD

A PPEN D IX J

DISK COMMAND SUMMARY

This appendix lists the commands used for disk operation in C l 28 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 C l 28 mode. All BASIC 2.0 commands can be used in both C l 28 and C64 modes.

c o m m a n d

APPEND

BLOAD

BOO T

BSAVE

CATALO G

CLOSE

CM D

C OLLECT

CONCAT

COPY

DCLEAR

DCLO SE

DIRECTO RY

DLOAD

DOPEN

DSAVE

DVERIFY

G E T #

HEADER

LOAD

OPEN

P R IN T #

RECORD

RENAM E u s e

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 o f contents o f 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 o f a file on disk*

BASIC 2.0 BA SIC 7.0

APPENDIXES 675 c o m m a n d

RUN filename

SAVE

VERIFY u s e

Execute BASIC program from disk

Store program in memory to disk

Verify program in memory against program on disk

BASIC 2.0 BASIC 7.0

*Although there is no single equivalent command in BASIC 2 .0 , there is an equivalent m ulti-com m and instruction. See your disk drive m anual for these BASIC 2 .0 conventions.

676 COMMODORE 128

A P PEN D IX K

p a r t

I— COMMODORE 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 o f this reference guide. See “ Suggestions for

Reading” at the end of this guide.

Part I o f 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) Function Name b) Input Parameters c) Output Parameters d) Brief Description e) 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 microproces sor 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:

(Accumulator)

PSW (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 “ Sugges tions for Further R eading.” 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 677

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 o f the system. Each of these routines can be accessed via the CP/M BIOS jump table below. The jum p 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 o f this appendix.

NO.

INSTRUCTION D ESCRIPTION

0 JM P BOOT

1 JM P WBOOT

2 JM P CONST

JM P CONIN

JM P CONOUT

JM P LIST

JM P AUXOUT

JM P AUXIN

JM P HOM E

JM P SELDSK

JM P SETTRK

JM P SETSEC

JM P SETDMA

JM P READ

JM P W RITE

JM P LISTST

JM P SECTRN

JM P CONOST

JMP AUXIST

JM P AUXOST

JM P DEVTBL

Perform cold start initialization

Perform warm start initialization

Check for console input character ready

Read Console Character in

W rite Console Character out

W rite 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

W rite Specified Sector

Return List Status

Translate Logical to Physical Sector

Return Output Status o f Console

Return Input Status of Aux. Port

Return Output Status o f Aux. Port

Return Address o f Char. I/O Table

JM P DEVINI

JM P DRVTBL

JMP M ULTIO

Initialize Char. I/O Devices

Return Address o f Disk Drive Table

JMP FLUSH

JM P MOVE

JM P TIM E

JM P SELMEN

Set Number of Logically Consecutive sectors to be read or written

Force Physical Buffer Flushing for user-supported deblocking

Memory to M emory Move

Time Set/Get signal

Select Bank o f Memory

JM P SETBNK

JMP XMOVE

JM P USERF

Specify Bank for DMA Operation

Set Bank W hen a Buffer is in a Bank other than 0 or 1

Reserved for System Im plementor

JM P RESERV1 Reserved for Future Use

JM P RESERV2 Reserved for Future Use

CP/M 3 BIOS Jump Vector Table

678 COMMODORE 128

0 BOOT

Bank:

Input:

Output:

Function:

None

This code does all o f the hardware initialization, sets up zero page, prints any sign-on message and loads the CCP and then transfers control to the CCP.

WBOOT

Bank:

Input:

Output:

Function:

0 or 1

None

This code sets up page zero, reloads the CCP and then exe cutes the CCP.

CONST

Bank:

Input:

Output:

Function:

0 or 1

None

A = 0FFH 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.

CONIN

Bank:

Input:

Output:

Function:

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.

CONOUT

Bank:

Input:

Output:

Function:

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.

LIST

Bank:

Input:

Output:

Function:

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 679

AUXOUT

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.

AUXIN

Bank:

Input:

Output:

Function:

0 or 1

None

A = ASCII character from AUX device

Reads a character from any ONE of the assigned AUXIN devices.

A scan of each assigned device is done until an input character is found. The character is returned in the A register.

HOME

Bank:

Input:

Output:

Function:

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.

SELDSK

Bank:

Input:

Output:

Function:

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 o f 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.

10 SETTRK

Bank:

Input:

Output:

Function:

BC = Track number

None

11 SETSEC

Bank:

Input:

Output:

Function:

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).

680 COMMODORE 128

12 SETDMA

Bank:

Input:

BC = Direct memory access address

Output: None

Function: 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.

13 READ

Bank: 0

Input: None

Output: A = 000H if no errors

A = 001H if nonrecoverable error

A = OFFH if media has changed

Function: 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 0 0 1H. 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.

14 WRITE

Bank:

Input:

C = Deblocking code (not used)

Output: A = 000H if no errors

A = 001H if nonrecoverable error

A = 002H if disk is read only

A = OFFH if media has changed

Function: 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.

15 LISTST

Bank:

Input:

Output:

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.

Function: 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 681

16 SECTRN

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.

17 CONOST

Bank:

Input:

Output:

Function:

0 or 1

None

A = OFFH if Ready

A = 000H if not Ready

This routine scans the currently assigned console 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 000H.

18 AUXIST

Bank:

Input:

Output:

Function:

0 or 1

None

A = OFFH if console character present

A = 000H if no console character

Checks the status of the current AUXIN device. If any o f the devices have a character available, OFFH is returned, otherwise

OOOH is returned.

19 AUXOST

Bank:

Input:

Output:

Function:

0 or 1

None

A = OFFH if ready

A = OOOH if not ready

This routine scans the currently assigned AUXOUT devices and returns with A set to OFFH if ALL devices are ready to accept a character. If any assigned device is not ready then A is set to 00H.

20 DEVTBL

Bank:

Input:

Output:

Function:

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 o f 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.

682 COM M ODORE 128

21 DEVINI

Bank:

Input:

Output:

Function:

0 or 1

C = device number

None

Initializes the physical character device specified in the C register to the BAUD rate in the DEVTBL.

22 DRVTBL

Bank:

Input:

Output:

Function:

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.

23 MULTIO

Bank:

Input:

Output:

Function:

C = multisector count

None

The multisector count is set before the track, sector, and DMA address and the read/write o f the sectors occur. A maximum o f 16K can be transferred by each multisector count.

24 FLUSH

Bank:

Input:

Output:

Function:

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 .

25 MOVE

Bank:

Input:

Output:

Function:

0 or 1

HL = destination address

DE = source address

BC = count

HL = HL(in) + 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.

26 TIME

Bank:

Input:

Output:

0 or 1

C = 000H (Time Get) / OFFH (Set Time)

None

APPENDIXES 683

Function: This function is called with C = 000H if the system time in the

SCB needs to be updated by the clock. If C = 0FFH, 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.

SELMEM

Bank:

Input:

0 or 1

A = memory bank

None Output:

Function: Changes the current memory bank. This code MUST be in common memory.

N O T E : ONLY A can be changed.

SETBNK

Bank:

Input:

Output:

Function:

XMOVE

Bank:

Input:

A = DMA memory bank

None

Sets the DMA bank for the next READ/W RITE operation.

Output:

Function:

B = destination bank

C = source bank

None

Provides the system with the ability to perform memory-to- memory DMA through the entire system space.

30 USERF

Banks

Input:

Output:

Function:

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.

RESERV1

Bank:

Input:

Output:

Function:

RESERV2

Bank:

Input:

Output:

Function:

N/A

Not available to the user.

N/A

Not available to the user.

684 COMMODORE 128

D A TA 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)

PHO through D P H I5

A list of 16 word pointers (reverse-byte format). The first pointer (DPHO) 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.

E X T E N D E D DISK PARAMETER HEADER (X D P H )

(N O R M A L DPH W IT H A HEADER)

W RT READ LO G IN IN IT TYPE UNIT XLT -0- M F DPB CSV ALV DIRBCB DTABCB HASH HBANK

16b 16b 16b 16b 8b 8b 16b 72b 8b 16b 16b 16b 16b

-1 0 - 8 - 6 - 4 - 2 -1 0 2 11 12 14 16 18

16b 16b

20 22

WRT Contains the

READ Contains the address of the sector write routine for this drive.

address of the sector read routine for this drive.

INIT

TYPE

UNIT 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 o f density and media type.

drive number relative to the disk controller.

XLT

-0-

M F

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

DPB

CSV has changed.

Contains a pointer to the current DPB that describes the current media type.

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 BLOCK— DPB

SPT BSH BLM EXM

16b 8b 8b 8b

DSM DRM ALO AL1 CKS O FF PSH PH M

16b 16b 8b 8b 16b 16b 8b 8b

SPT

BSH

BLM

EXM

DSM

DRM

ALO

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, (D R M + l)/4

Number of reserved tracks at the beginning of the disk

Physical record shift factor

Physical record mask

BUFFER C O N TR O L BLOCK (LRU C O N TR O L BLOCK— BCB)

DRV R E C # W FLG 00 TRA CK SECTO R BUFFAD BANK LINK

8b 24b 8b 8b 16b 16b 16b 8b 16b

DRV

R E C #

Drive associated with this record. Set to OFFH when not

Contains the absolute sector number of the buffer.

used.

WFLG Set to OFFH when buffer contains data that must be written to disk.

00 Scratch byte used by BDOS

TRACK Physical track address of buffer.

SECTOR Physical sector address of buffer.

BUFFAD Address of the buffer associated with this BCB.

BANK Bank number of buffer associated with this BCB.

LINK 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 o f the standard CP/M system that is transportable from one m anufacturer’s computer to another. They are written to run only on the Commodore 128.

Most of these customized C l 28 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) Function Name b) Input Parameters c) Output Parameters d) B rief Description e) Additional Information

0 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 ($FF0Q-$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 o f matrix position) is found in memory

Address = Tablestart + (4 * B) 4- C (bits 1 and 0)

C = Returns control code information, where each bit has a specific meaning as follows:

Bits 1 & 0

0 0 = lower case

0 1 = upper case

1 0 = shifted

1 1 = control key

APPENDIXES 687

C = Bit 2 1 = control key down, 0 = up

Bit 3 Not implemented

Bit 4 1 = Right shift key down, 0 = up

Bit 5 1 = C* key is active (not necessarily down)

Bit 6 Not implemented

Bit 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 Information— Important 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) lower case b) upper case c) shifted key and character d) control key and character

These four definitions are labeled in columns in the ASCII table.

1292 7F7F7F16

1296 0D0D0D0D

129A 06060101

129E 86868787

12A2 80808181

12A6 82828383

12AA 84848585

12AE 1717171A

12B2 333323A2

12B6 77575717

12BA 61414101

12BE 343424A3

12C2 7A5A5A1A

12C6 73535313

12CA 65454505

12CE 00000000

12D2 353525A4

12D6 72525212

12DA 64444404

12DE 363626A5

12E2 63434303

12E6 66464606

ASCIISTBL: A B C D

DB 7FH ,7FH ,7FH ,16H

DB 0D H ,0D H ,0D H ,0D H

DB 06H ,06H ,01H ,01H

DB 86H ,86H ,87H ,87H

DB 80H ,80H ,81H ,81H

DB 82H ,82H ,83H ,83H

DB 84H ,84H ,85H ,85H

DB 17H ,17H ,17H ,1A H

DB 33H ,33H ,23H ,0A 2H

DB 77H ,57H ,57H ,17H

DB 61H ,41H ,41H ,01H

DB 34H ,34H ,24H ,0A 3H

DB 7A H ,5A H ,5A H ,1A H

DB 73H ,53H ,53H ,13H

DB 65H ,45H ,45H ,05H

DB 00H ,00H ,00H ,00H

DB 35H ,35H ,25H ,0A 4H

DB 72H ,52H ,52H ,12H

DB 64H ,44H ,44H ,04H

DB 36H ,36H ,26H ,0A 5H

DB 63H ,43H ,43H ,03H

DB 66H ,46H ,46H ,06H

5 %

6 &

INS DEL matrix 0 position

RETURN

LF RT

F7 F8

FI F2

F3 F4

F5 F6

UP DOW N

3 #

4 $

Z s

(LF SHIFT)

688 COMMODORE 128

12EA 7 4 545414

12E E 7 8 585818

12F2 373 7 2 7 A 6

12F6 79 5 9 5 9 1 9

12FA 67474707

12FE 383 8 2 8 A 7

1302 6 2 424202

1306 6 8 484808

130A 7 5 555515

130E 7 6 565616

1312 3 9 392900

1316 6 9 494909

131A 6A 4A 4A 0A

131E 3 0 303000

ASCIISTBL: A B C

DB 7 4 H ,5 4 H ,5 4 H ,1 4 H

DB 7 8 H ,5 8 H ,5 8 H ,1 8 H

DB 3 7 H ,3 7 H ,2 7 H ,0 A 6 H

DB 7 9 H ,5 9 H ,5 9 H ,1 9 H

DB 6 7 H ,4 7 H ,4 7 H ,0 7 H

DB 3 8 H ,3 8 H ,2 8 H ,0 A 7 H

DB 6 2 H ,4 2 H ,4 2 H ,0 2 H

DB 6 8 H ,4 8 H ,4 8 H ,0 8 H

DB 7 5 H ,5 5 H ,5 5 H ,1 5 H

DB 7 6 H ,5 6 H ,5 6 H ,1 6 H

3 9 H ,3 9 H ,2 9 H ,0 0 H

6 9 H ,4 9 H ,4 9 H ,0 9 H

6 A H ,4 A H ,4 A H ,0 A H

3 0 H ,3 0 H ,3 0 H ,0 0 H

1322 6 D 4 D 4D 0D

1326 6 B 4B 4B 0B

132A 6 F 4F 4F 0F

132E 6E 4 E 4 E 0 E

1332 2B 2 B 2 B 0 0

1336 7 0 505010

133A 6C 4C 4C 0C

133E 2D 2 D 2 D 0 0

1342 2E 2 E 3 E 0 0

1346 3A 3A 5B 7B

134A 404 0 4 0 0 0

134E 2C 2 C 3 C 0 0

1352 2 3232360

1356 2 A 2 A 2 A 0 0

135A 3B 3 B 5 0 7 0

135E 000000F 5

1362 0 0000000

1366 3D 3D 3D 7E

136A 5 E 5E 7C 7C

136E 2F 2F 3F 5C

1372 313 1 2 1 A 0

1376 5 F 5F 5F 7F

137A 09153000

6 D H ,4 D H ,4 D H ,0 D H

6 B H ,4 B H ,4 B H ,0 B H

6 F H ,4 F H ,4 F H ,0 F H

6 E H ,4 E H ,4 E H ,0 E H

DB 2 B H ,2 B H ,2 B H ,0 0 H

DB 7 0 H ,5 0 H ,5 0 H ,1 0 H

6 C H ,4 C H ,4 C H ,0 C H

DB 2 D H ,2 D H ,2 D H ,0 0 H

DB 2 E H ,2 E H ,3 E H ,0 0 H

DB 3 A H ,3 A H ,5 B H ,7 B H

DB 4 0 H ,4 0 H ,4 0 H ,0 0 H

2 C H ,2 C H ,3 C H ,0 0 H

DB 2 3 H ,2 3 H ,2 3 H ,6 0 H

DB 2 A H ,2 A H ,2 A H ,0 0 H

3 B H ,3 B H ,5 D H ,7 D H

DB 0 0 H ,0 0 H ,0 0 H ,0 F 5 H

DB 0 0 H ,0 0 H ,0 0 H ,0 0 H

DB 3 D H ,3 D H ,3 D H ,7 E H

DB 5 E H ,5 E H ,7 C H ,7 C H

2 F H ,2 F H ,3 F H ,5 C H

3 1 H ,3 1 H ,2 1 H ,0 A 0 H

DB 5 F H ,5 F H ,5 F H ,7 F H

DB 0 9 H ,1 5 H ,3 0 H ,0 0 H

137E 3 2 3 2 2 2 A 1

1382 2 0202000

1386 2 1200000

138A 71515111

138E 000000F 0

DB 3 2 H ,3 2 H ,2 2 H ,0 A 1 H

DB 2 0 H ,2 0 H ,2 0 H ,0 0 H

DB 2 1 H ,2 0 H ,0 0 H ,0 0 H

DB 7 1 H ,5 1 H ,5 1 H ,1 1 H

DB 0 0 H ,0 0 H ,0 0 H ,0 F 0 H

; T

; x

; 7 ’

; y

; G

; 8 (

; b

; h

; u

; v

; 9 )

; I

; J

; o

; M

; K

; o

; N

; +

; p

; l

; , <

; : [ {

; @

; , <

; P O U N D

. *

; ; ] }

; C L E A R /H O M E

; (R T S H IF T )

; PI

; / ? \

; 1

; <-

; (C O N T R O L ) S O U N D 1

S O U N D 2

; 2 "

; S P A C E

; (C O M M O D O R E ) S O U N D 3

; Q

; R U N S T O P

APPENDIXES 689

1392 9F9F9F9F

1396 383838B7

139A 353535B4

139E 09090900

13A2 323232B1

13A6 343434B3

13AA 373737B6

13AE 313131B0

ASCIISTBL: A B C I)

DB 9FH ,9FH ,9FH ,9FH

DB 38H ,38H ,38H ,0B 7H

DB 35H ,35H ,35H ,0B 4H

DB 09H ,09H ,09H ,00H

DB 32H ,32H ,32H ,0B1H

DB 34H ,34H ,34H ,0B 3H

DB 37H ,37H ,37H ,0B 6H

DB 31H ,31H ,31H ,0B 0H

/HELP/

/8/

151

/TAB/

121

141

111

I I I

13B2 1B1B1B00

13B6 2B2B2B00

13BA 2D2D2D00

13BE 0A0A0A0A

13C2 0D0D0DFF

13C6 363636B5

O C A 39393900

B C E 333333B2

13D2 00000000

13D6 30303000

13DA 2E2E2E00

13DE 05050512

13E2 18181803

13E6 1313138D

13EA 0404048E

13EE F1F1F1F2

DB 1B H ,1BH ,1BH ,00H

DB 2BH ,2B H ,2BH ,00H

DB 2D H ,2D H ,2D H ,00H

DB 0A H ,0A H ,0A H ,0A H

DB 0D H ,0D H ,0D H ,0FFH

DB 36H ,36H ,36H ,0B 5H

DB 39H ,39H ,39H ,00H

DB 33H ,33H ,33H ,0B 2H

DB 00H ,00H ,00H ,00H

DB 30H ,30H ,30H ,00H

DB 2EH ,2EH ,2E H ,00H

DB 05H ,05H ,05H ,12H

/ESC/

/ + /

/-/

/LINE FEED/

/ENTR/

161

191

131

/ALT/

101 l.l

/UP/

DB 18H ,18H ,18H ,03H

DB 13H ,13H ,13H ,08D H

/DN/

/LF/

DB 04H ,04H ,04H ,08E H IR T I

DB 0F1H ,0F1H ,0F1H ,0F2H /NO SCRO LL/

13F2

» LOGICAL COLOR TABLE (USED WITH ESC ESC ES

(W HERE CHAR IS 50H

00112233 DB 000H ,011H ,022H ,033H

13F6 44556677

13FA 8899AABB

13FE CCDDEEFF

DB 044H ,055H ,066H ,077H

DB 088H ,099H ,0A A H ,0BBH

DB 0C C H ,0DD H ,0EEH ,0FFH

III.

a) b) c) d)

User Function 3: Execute a Z80 ROM function

A = 3

L = subfunction number

Additional input parameters may be necessary

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.

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.

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

III. 8a) Subfunction 8: Cursor Up one position b) cursor$up c) no values returned d) This subfunction moves the cursor up one row on the current screen (40 or 80), but not past the top o f the screen.

III. 12a) Subfunction 12: Cursor down one row b) cursor$down c) no values returned d) 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) Subfunction 16: Cursor left one column b) cursor$left c) no values returned d) This subfunction moves the cursor left one column, but not past the left margin.

III. 20a) Subfunction 20: Cursor right one column b) cursor$rt c) no values returned.

d) This subfunction moves the cursor right one column, but not past the right edge of the screen.

III. 24a) Subfunction 24: Execute a carriage return b) do$cr c) No values returned.

d) This subfunction executes a carriage return and places the cursor at the left margin.

III. 28a) Subfunction 28: Clear to end of line b) CEL c) No values returned.

d) This subfunction clears the cursor row starting where the cursor is currently located and ending at the end of the line.

APPENDIXES 691

III. 32a) Subfunction 32: Clear to end of screen b) CES c) No values returned.

d) This subfunction clears the screen starting where the cursor is currently located through the end o f screen.

III. 36a) Subfunction 36: Character insert b) char$ins c) No values returned.

d) This subfunction inserts a character at the current cursor position, the last character on the line is lost.

III. 40a) Subfunction 40: character delete b) char$del c) No values returned.

d) This subfunction deletes a character at the current cursor position, and places a space in the last position in the line.

III. 44a) Subfunction 44: Line insert b) line$ins c) No values returned.

d) This subfunction inserts a line o f spaces on the current cursor row, the current cursor row is moved down one and the last line (24) is lost.

III. 48a) Subfunction 48: Line delete b) line$del c) No values returned.

d) This subfunction deletes a line at the character row marked by the current cursor position. The bottom line (24) is filled with spaces.

III. 50a) Subfunction 50: Not Implemented b) -----c) -----d) ------

III. 52a) Subfunction 52: Set Cursor Color b) color

B register returns color code value c) No values returned.

d) This function sets the current cursor color code with the value in color.

III. 56a) Subfunction 56: Set 80-column Attributes b) attr

B = bit to set/clear

C = bit value c) No values returned.

d) 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.

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) Subfunction 80: Convert record (GCR only) b) @ trk c) VICStrk, VICSSEC d) 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 ( C l28 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) Subfunction 84: Bell Function b) Sound 1, Sound 2, Sound 3 ($FD10, $FD12, $FD14, respectively) c) Outputs a bell sound d) This function outputs a bell sound from the SID chip.

Subfunctions 86-95 are not defined

APPENDIXES 693

III. 96a) Subfunction 96: Track 40 b) trk$40 c) @ off 40 d) 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) Subfunction 98: Set cursor position b) set$cur$40 c) No value returned.

d) 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) Subfunction 100: Line Paint b) line$paint c) No value returned.

d) This function updates the current character line only if @ off 40 and old $offset are the same. If old $offset = - 1 , 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 80- column screen.

III. 102a) Subfunction 102: Screen paint b) screen$paint c) No value returned.

d) 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 documenta tion for the source listings.

III. 104a) Subfunction 104: Print Message (BOTH) b) prt$msg$both c) No value returned.

d) 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.

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) Subfunction 108: Incripted Messages b) update$it c) No value returned d) This function displays incripted messages.

Subfunction 110 is not implemented.

III. 112a) Subfunction 112: ASCII to PET ASCII Conversion b) ASCII$pet, B register = ASCII character ($20—$7F) c) A register = converted PET ASCII character.

d) 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 o f cursor on screen

DE = cursor line (row) start address

BC = # of characters to end o f line (< 8 0 , 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 (< 8 0 , 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 = 40-

B = $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 695

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.

N O T E : 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 o f system memory ( C l28 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.

I V .- 1 . 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 sub function is not normally used. It performs the same actions as pressing reset.

IV. O.a) Subfunction 0: Initialize 8502 BIOS b) A = 4

L = 0 c l) Sets up interrupt vector $0314—$0319 to vector to the 8502 interrupt handler c2) Copies ROM interrupt vector to RAM

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:

LO W ER NYBBLE

O F VICTORY

BIT VALUE

0001

0010

0100

1000

D EVICE NUMBER

DRIVE

Values o f the Lower Nybble of VICDRV

EQUIVALENT OPEN

STATEM ENT IN BASIC

OPEN 8,11,15

OPEN 9,12,16

OPEN 10,13,17

OPEN 11,14,18 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 respec tively. 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 condi tions described for the outputs in c. See subfunction 1 for details.

APPENDIXES 697 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 o f 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.

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)— Disk drive device number variable 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) $FE00-TRACK STATUS (on track below)

2) $FE01-Number of Sectors

3) $FE02-Logical Track

4) $FE03-Minimum Sector Number (on this track)

5) $FE04-Maximum Sector Number (on this track)

6) $FE05-Physical Interleave

If an error occurs:

VICDATA = 11

VICDATA = 12

VICDATA = 13

VICDATA = 15

(SOB) if disk in drive has been changed

($0C) if drive is not a fast (1571) disk drive

(SOD) if channel error occurs

($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.

Disk E rro r Status T a b le

MD DN II 12 D l D2 D3 D4

MD ................ Mode: 1 = M FM , 0 = GCR.

DN .............................................. Drive Number.

II, 12 ........................................... Sector Size.

a) 00 = 128 bytes b) 01 = 256 bytes c) 10 = 512 bytes d) 11 = 1024 bytes

D 1-D 4 .................................... Controller Status

GCR

OOOx = Ok.

0010 = Sector not found.

0011 = No Sync.

0100 = Data block not found.

0101 = Data block checksum.

0110 = Format error.

0111 = Verify error.

1000 = W rite protect error.

1001 = Header block checksum.

1010 = Data extends into next block.

1011 = Disk ID mismatch/Disk change.

1100 = Drive is not fast (1571).

1101 = Channel Error.

1110 = Syntax.

1111 = No Drive present.

MFM

OOOx = Ok.

0010 = Sector not found.

0011 = No address mark.

0100 = Unused.

0101 = Data CRC error.

0110 = Format error.

0111 = Verify error.

1000 = Write protect error.

1001 = Header CRC error.

1010 = Unused.

1011 = Disk change.

1100 = Drive is not fast (1571).

1101 = Channel Error.

1110 = Syntax.

1111 = No Drive present.

Disk E rro r Status T ab le

APPENDIXES 699

700 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) Sub function 8: Format a 1541 or 1571 Diskette b) A = 4

L = 8

D R IV E #

FAST c) VICDATA d) This subfunction formats a 1541 or 1571 diskette in the appropriate drive. If FAST is enabled, (FAST ANDed with D R IV E # (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 “ U 0” 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 o f execution of the user routine)

VICDATA = ($FD06) high-byte address of 8502 routine c) U ser 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 C l 28

APPENDIXES 701

KERNAL routine, you must enable the KERNAL after you have trans ferred 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 o f 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. 11.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 $D 505, the mode configura tion 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 o f days (in binary) since 1/1/78

VII. a) User Function 255: System Date b) A = -1 ($FF) c) HL = number of days (in binary) since 1/1/78 d) By specifying A = - 1 , the system date is returned.

702 COMMODORE 128

A PPEN D IX K

PART II

CALLING CP/M BIOS, 8502 BIOS A N D

CP/M USER FU N CTIO N S IN

Z80 M ACHINE 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 infor mation 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 o f 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 o f 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 703 recalling the CP/M jum p vector on page 677 o f Appendix K. The first 30 jum ps (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 jum p 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 B— test 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 ;place HL reg. pair on stack

LHLD 1 ;load address of jump vector 1 (WBOOT) into HL

MVI L, useroffset * 3 ;get offset of 90 (30*3) to L

XTHL

RET

;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 jum ps 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 jum p vectors are on and the low byte is always 3 (Jump # 1 the warm boot vector). Next the jum p number times 3 is loaded into the low byte (L) of register pair HL. This adds the offset o f 90 memory locations to base address of the CP/M BIOS jum p table, which now points to jump number 30, USERF.

704 COMMODORE 128 m

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 o f HL back in HL. When the RETum instruction is reached by the Z80, program control is therefore passed to the USERF vector, entry 30 in the CP/M BIOS jum p 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 sub function, load the L register with a subfunction number on the beginning o f 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 o f 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 enter jum p number 30 in the CP/M BIOS jum p table. A direct BIOS call enters any of the first 30 (0-29) jum p vectors. These are the input and output routines that are a part of any CP/M system on any microcomputer. The standard method o f calling a

CP/M BIOS routine is via BIOS function 50. This function handles the banking of the two 64K RAM banks in the C l 28.

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.

H ere’s a program example that illustrates how to call a CP/M BIOS function.

main

MVI C,50 ;store function no. 50 in reg. C

LXI D,bios$pb ;load immediate a 16 bit pointer in DE

CALL 5 standard BIOS call

APPENDIXES 705

Rest o f Program bios$pb:

RET db FUNNUM db AREG dw BCREG dw DEREG dw HLREG

;BIOS variable table

;BIOS function no. variable tem porary A reg. storage

;temp BC reg. pair storage

;temp 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 o f 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 o f 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) Epson QX10 (double sided) a l) Epson QX10 (double sided) b) IBM-8 (single sided) b l) IBM-8 (double sided) c) KayPro IV (double sided) d) KayPro II (single sided) e) Osborne (single sided)

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 C l 28 system. This portion o f 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.

Number o f tracks 40

Block alloc size a

2048 b

Disk Type

Starting pos. (t/s)

DSDD SSDD

2/1

Sector size (bytes) 256

1/1

Number of sec/trk 32

512

1024

# of dir entries

# of resvd tracks

128

M anufacturers c d

DSDD SSDD

0/10 1/0

512 512

2048

128

1024

1 e

SSDD

3/1

1024

3 a l b l

DSDD DSDD

2/1 1/1

512 512

20 8

80 40

2048 2048

64 128

2 1

SS = single sided

DS = double sided

DD = double density

M F M Disk F o rm a t T a b le

N O T E : Epson (a) labels sector numbers 1 through 16. The other Epson

QX10 format (a l) 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 707 db db dw dpb

S256*2 + (16*2-8) + 1

M FM + S256 + TypeO + CO + SI

256,32,40,2048,128,2 db db db db dw dpb db db db db dw dpb db db db db db db db dw dpb

‘Epson Q X 10’

80h + S512*2 + ( 10*2-8) + 1

S256*2

MFM + S512 + TypeO + CO + SI

512,20,40,2048,128,2

‘Epson Q X 10’

S512*2 + (8*2-8) + 1

MFM + S512 + Type2 + CO + SI

512,8,40,1024,64,1

’ IBM -8 SS’

S512*2 + (8*2-8) + 1

M FM + S 5 12 + Type2 + CO + SI

512,8,80,2048,64,1

’ IBM -8 D S’ db db dw dpb db db

S512*2 + (1 0 * 2 -8 )+ 0

MFM + S512 + T yp el + C l + SO

512,10,80,2048,128,1

‘KayPro IV ’ db db dw dpb

S512*2 + (10*2-8)4-0

MFM + S512 + TypeO + C l + SO

512,10,40,1024,64,1 db db

‘KayPro IP

MFM Format Table

256 byte sect, 16 sect/trk

DSDD start on track 2 sect 1 (2 ale) se c t# 1 to 16

(top and bottom numbered the same)

1 Epson QX10

,512 byte sect, 10 sect/trk track 0 is 256 bytes/sector

DSDD start on track 2 sect 1 (2 ale) se c t# 1 to 10

(top and bottom numbered the same)

512 byte sect 8 sect/trk

SSDD start on track 1 sector 1 (2 ale) se c t# 1 to 8

512 byte sect 8 sect/trk

DSDD start on track 1 sector 1 (1 ale) se c t# 1 to 8

(top and bottom numbered the same)

512 byte sector, 10 sect/trk

DSDD start on track 0 sector 10 (2 ale) se c t# 0 to 9 on top (even tracks)

5 se c t# 10 to 19 on bottom (odd tracks)

512 byte sect, 10 sect/trk

SSDD start on track 1 sector 0 (4 ale) se c t# 0 to 9

708 COMMODORE 128 db db dw dpb

S1024*2 + (5*2-8) + 1

MFM + S1024 + TypeO + CO + SI

1024,5,40,1024,64,3 db db

‘Osborne D D ’

M F M F o rm a t T a b le (continued)

; 1024 byte sect, 5 sect/trk

; SSDD

; start on track 3 sector 1 (2 ale)

; se c t# 1 to 5

;

APPENDIXES 709

APPEN D IX 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.

710 COMMODORE 128

$*MACRO f a l s e t r u e b a n k e d

EXTSYS p r e $ r e l e a s e e q u e q u e q u e q u e q u

0 n o t f a l s e t r u e f a l s e f a l s e

; u s e e x t e r n a l s y s t e m a s d i s k a n d c h a r

; s t a r t a t J a n 1 , 1 9 7 8 d t $ h x $ y r e q u

1 9 8 5 d a t e $ h e x e q u d a t e m a c r o d b e n d m

D e c 8 5 '

7 8 7 9 8 0 8 1 8 2 8 3 8 4

3 6 5 + 3 6 5 + 3 6 6 + 3 6 5 + 3 6 5 + 3 6 5 + 3 6 6

1 2

4 5

9 1 0 1 1 1 2 d t $ h x $ y r + 3 1 + 2 8 + 3 1 + 3 0 + 3 1 + 3 0 + 3 1 + 3 1 + 3 0 + 3 1 + 3 0 + 6

; b o o t m e m o r y m a p ( b a n k

o n l y ) b i o s

02 b l o c k $ b u f f e r b o o t $ p a r m e q u e q u e q u

3 0 0 0 h

3 4 0 Oh

3 C 0 0 h

; b a n k

l o w m e i r p r y r r e p

; u s e s 2K

; u s e s a b o u t 2 5 6 b y t e s

ROM

V I C $ c o l o r

S Y S $ k e y $ a r e a s c r e e n $ 4 0

B A N K $ p a rm $ b lk

B I O S 8 5 0 2

V I C $ s c r e e n c c p $ b u f f e r b a n k

$ f r e e e q u e q u e q u e q u e q u e q u e q u e q u e q u

OOOOh lO O O h lO O O h

1 4 0 0 h

2 4 0 G h

2 6 0 0 h

2 C 0 0 h

3 0 0 0 h

4 0 0 Oh

; I / O p a g e o n l y ( I 0 $ 0 s e l e c t e d )

; 3 2 5 6 b y t e b l o c k s ( a l l o w 4 )

; 2 X 8 0 X 2 5 = 4 0 0 0

; a l l o w 0 . 5 K o f p a r a m e t e r s

; 1 . 5K

; IK

; 0 c 8 0 h ( a l l o w 4 K )

; s t a r t o f f r e e a r e a i n b a n k 0

; m a p p e d I / O l o c a t i o n s

V IC

S ID

MMU

D S 8 5 6 3

V IC $ C $ H

V IC $ C $ L

C I A l

C IA 2

USART

R A M $ d s k $ b a s e e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u

ODOOOh

0 D 4 0 0 h

0 D 5 0 0 h

0 D 6 0 0 h

0 D 8 0 0 h

OlOOOh

ODCOOh

ODDOOh

ODEOOh

ODFOOh

8 5 6 3

( m e m o ry m a p p e d o n l y i n I

)

( m e m o ry a n d i / o m a p p e d i n

6 5 2 6

6 5 5 1 ( e x t r n c a r d )

8 7 2 6

; C o m r o n m e m o r y a l l o c a t i o n i n t $ b l o c k p a r m $ b l o c k

@ b u f f e r e q u e q u e q u

OFCOOh ; m o d e 2 i n t e r r u p t p o i n t e r s ( t o FD FD h)

OFDOOh ; s y s t e m p a r a m e t e r s

OFEOOh ; d i s k b u f f e r ( 2 5 6 b y t e s )

OFFOOh ; t o O F F F F h u s e d b y 8 5 0 2 t h e f o l l o w i n g a r e C l 2 8 s y s t e m e q u a t e s e n a b l e $ z 8 0 r e t u r n $ z 8 0 e n a b l e $ 6 5 0 2 r e t u r n $ 6 5 0 2 e q u e q u e q u e q u

OFFDOh

OFFDCh

OFFEOh

O F FEEh

; 8 5 0 2 c o d e

; Z 8 0 c o d e v i c $ a n d v i c $ d r v v i c $ t r k e q u e q u e q u p a r m $ b l o c k + l v i c $ c m d + l v i c $ d r v + l

; 1 s t b y t e u s e d a s I n t t e r r u p t p o i n t e r

; ; b i o s 8 5 0 2 c c m m a n d b y t e

; b i o s 8 5 0 2 d r i v e ( b i t 0 s e t , d r v

; ; b i o s 8 '5 0 2 t r a c k #

0 )

APPENDIXES 711 v i c $ s e c t v i c $ c o u n t v i c $ d a t a c u r $ d r v f a s t k e y $ t b l f u n $ t b l c o l o r $ t b l $ p t r f u n $ o f f s e t s o u n d $ l s o u n d

$2 s o u n d ? 3 e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u v i c $ t r k + l v i c $ s e c t + l v i c $ c o u n t + l v i c $ d a t a + l c u r $ d r v + l f a s t

+1 k e y $ t b l f u n $ t b l

+2 c o l o r $ t b l $ p t r

+2 f u n $ o f f s e t + l s o u n d $ l s o u n d $

2+2

@ t r k

@ d i m e q u e q u s o u n d ? 3 + 2

@ t r k

; b e l o w h e r e n o t u s e d b y ROM

@ s e c t

@ c n t

(3 c b n k

@ d b n k

( a a d r v

@ r d r v c c p $ c o u n t s t a t $ e n a b l e e q u e q u e q u e q u e q u e q u e q u e q u

@ d m a

@ s e c t

@ c n t

@ c b n k

(? d b n k

@ a d r v + l

( a r d r v

+1 c c p $ c o u n t + l e m u l a t i o n ? a d r u s a r t $ a d r

; C X IO e q u a t e s i n t $ h l i n t $ s t a c k u s e r $ h l $ t e m p h l $ t e m p d e $ t e m p a $ t e m p s o u r c e $ b n k d e s t $ b n k e q u e q u

M F M $ t b l $ p t r

;

1 s t r e l e a s e e n d e q u p r t $ c o n v $ l p r t $ c o n v

$2 e q u e q u k e y $ F X $ f u n c t i o n e q u

X x D $ c o n f i g e q u e q u e q u e q u e q u e q u e q u e q u e q u s t a t $ e n a b l e + l a n u l a t i o n $ a d r

+2 u s a r t $ a d r i n t $ h l +

2+20 i n t $ s t a c k u s e r $ h

$ t e m p

+2 h l $ t e m p d e $ t o n p

+2 a $ t e m p + l s o u r c e $ b n k + l d e s t $ b n k + l b i o s 8 5 0 2 s e c t o r # b i o s 8 5 0 2 s e c t o r c o u n t b i o s 8 5 0 2 d a t a b y t e t o / f r o m c u r r e n t d i s k i n s t a l l e d t o V i r . d r i v e b i t

s e t , d r v

i s f a s t . e c t .

p o i n t e r t o k e y b o a r d t a b l e p o i n t e r t o f u n c t i o n t a b l e p o i n t e r t o l o g i c a l c o l o r t a b l e f u n c t i o n # t o b e p r e p o r m e d u n u s e d c u r r e n t t r a c k n u m b e r c u r r e n t DMA a d d r e s s c u r r e n t s e c t o r n u m b e r r e c o r d c o u n t f o r m u l t i s e c t o r t r a n s f e r b a n k f o r p r o c e s s o r o p e r a t i o n s b a n k f o r DMA o p e r a t i o n s c u r r e n t l y s e l e c t e d d i s k d r i v e c o n t r o l l e r r e l a t i v e d i s k d r i v e n u m b e r o f r e c o r d s i n t h e CCP s t a t u s l i n e e n a b l e

7 k y b r d , k e y c o d e s ( 1 ) , f u n c t i o n s ( 0 )

4 0 c o l u m n t r a c k i n g o n ( 0 ) , o f f ( l )

d i s k s t a t , e n a b l e ( l ) , d i s a b l e ( O ) a d d r e s s o f c u r r e n t e m u l a t i o n p o i n t e r t o USART ( 6 5 5 1 ) r e g i s t e r i n t e r r u p t HL h o l d l o c a t i o n c u r r e n t l y o n l y 5 * 2 u s e d u s e r f u n c t i o n HL h o l d l o c a t i o n m i s c t e m p s t o r a g e ( u s e d b y VECTOR) m i s c t e m p s t o r a g e ( u s e d b y VECTOR) m i s c t e m p s t o r a g e ( u s e d b y VECTOR) i n t e r b a n k m o v e s o u r c e b a n k # i n t e r b a n k m o v e d e s t b a n k # p o i n t e r t o MFM t a b l e

R S 2 3 2 $ s t a t u s x m i t $ d a t a r e c v $ d a t a e q u e q u e q u

M F M $ t b l $ p t r + 2 p r t $ c o n v $ l p r t $ c o n v $

2+2 k e y $ F X $ f u n c t i o n + 2

X x D $ c o n f i g + l b i t 7 0 = n o p a r i t y b i t

6 0

= m a r k / s p a c e b i t 5 0 = s p a c e / e v e n

= p a r i t y

= o d d / e v e n

= m a r k / o d d b i t b i t

1 0 = 1

s t o p b i t

1 = 2

s t o p b i t s

0 = 7 d a t a b i t s

1 = 8

d a t a b i t s b i t 7 , l = s e n d d a t a , b i t

, l = s e n d i n g d a t a

= n o d a t a b i t 5 , l = r e c v q u e a c t i v e b i t 4 , l = p a r i t y e r r o r b i t 3 , l = f r a m i n g e r r o r b i t

, l = r e c v o v e r r u n ( n o u s e d ) b i t

, l = r e c e i v i n g d a t a b i t 0 , l = D a t a b y t e r e a d y

R S 2 3 2 $ s t a t u s + l x m i t $ d a t a + l d a t a b y t e t o s e n d r e c e i v e d d a t a b y t e

T h e f o l l o w i n g e q u a t e s a r e u s e d b y t h e i n t e r r u p t d r i v e n k e y b o a r d h a n d l e r

712 COMMODORE 128 i n t $ r a t e e q u r e c v $ d a t a + l

1 s t b y t e i s a p o i n t e r i n t o t a b l e ,

2 n d t o

12 t h b y t e r e p r e s e n t t h e k e y b o a r d s c u r r e n t s t a t e ( a c t i v e l o w ) , N O TE: o n l y c u r r e n t i f k e y $ b u f f e r i s n o t f u l l k e y $ s c a n $ t b l e q u i n t $ r a t e + l k e y b o a r d r o l l o v e r b u f f e r k e y $ b u f $ s i z e k e y $ g e t $ p t r k e y $ p u t $ p t r k e y $ b u f f e r e q u e q u e q u e q u

8*2 k e y $ s c a n $ t b l + l k e y $ g e t $ p t r

+2 k e y $ p u t $ p t r

; s o f t w a r e UART r e c v b u f f e r m u s t b e a n

R x D $ b u f $ s i z e

R x D $ b u f $ c o u n t

R x D $ b u f $ p u t

R x D $ b u f $ g e t

R x D $ b u f f e r t i c k $ v o l

I N T $ v e c t o r e q u e q u e q u e q u e q u e q u e q u e q u

6 4 k e y $ b u f f e r + k e y $ b u f $ s i z e

R x D $ b u f $ c o u n t + l

R x D $ b u f $ p u t + l

R x D $ b u f $ g e t + 1

R x D $ b u f f e r + R x D $ b u f $ s i z e t i c k $ v o l + l

OFDFDh c o n t a i n s

; ( i n co m m o n

; = > 4 0 c o l u m n m i s c p a r m t e m p $ l e q u

@ o f f 4 0 c u r $ o f f s e t o l d $ o f f s e t e q u e q u e q u

B A N K $ p a rm $ b lk t e n p $ l

@ o f f 4 0

@ o f f 4 0 + 2 p r t $ f l g e q u o l d $ o f f s e t + l f l a s h $ p o s e q u p r t $ f l g + l

;

; = = > 4 0 c o l u m n p o s i t i o n a n d c o l o r s t o r a g e p a i n t $ s i z e e q u f l a s h $ p o s

; c h a r $ a d r $ 4 0 e q u p a i n t $ s i z e + l ; c h a r $ c o l $ 4 0 c h a r $ r o w $ 4 0 e q u e q u c h a r $ a d r $ 4 0 + 2 c h a r $ c o l $ 4 0 + l

;

; a t t r $ 4 0 b g $ c o l o r $ 4 0 b d $ c o l o r $ 4 0 r e v $ 4 0 e q u e q u e q u e q u c h a r $ r o w $ 4 0 + l a t t r $ 4 0 + l b g $ c o l o r $ 4 0 + l b d $ c o l o r $ 4 0 + l

;

? = > 8 0 c o l u m n p o s i t i o n a n d c o l o r s t o r a g e c h a r $ a d r c h a r $ c o l c h a r $ r o w c u r r e n t $ a t r e q u e q u e q u e q u r e v $ 4 0 + l c h a r $ a d r

+2 c h a r $ c o l + l c h a r $ r o w ^ l

;

; b g $ c o l o r $ 8 0 c h a r $ c o l o r $ 8 0 e q u e q u c u r r e n t $ a t r + l b g $ c o l o r $ 8 0 + l

;

; ROM u s e s l o c a l t i o n s a b o v e t h i s p o i n t

; = > E m u l a t i o n p a r a m e t e r s p a r m $ b a s e p a r m $ a r e a $ 8 0

• p a r m $ a r e a $ 4 0 b u f f e r $ 8 0 $ c o l e q u e q u d s d s e q u d s d s e q u c h a r $ c o l o r $ 8 0 + l p a r m $ b a s e

+2 p a r m $ a r e a $ 8 0 + 3

1 p a r m $ a r e a $ 4 0 + 3

; 8 0 c o l u m n

8 0 c o l u m n

4 0 c o l u m n

; = > C X IO p a r a m e t e r s

; i n t $ c o u n t n o t u s e d b y r e l e a s e s p a s t 1 0 O c t 8 5 i n t $ c o u n t q u b u f f e r $ 8 0 $ c o l + 4 0 * 2 ; o n e a d d e d e v e r y l / 6 0 t h s e c k e y $ b u f ev. i i n t $ c o u n t + l

APPENDIXES 713

;==> 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

; c o n t r o l $ k e y s e q u k e y $ d o w n $ t b l + l

*^ ; b y t e , n o t u s e d a n y m o r e ( i n t c o d e ) c o m m o d o r e $ m o d e m s g p t r o f f s e t c u r $ p o s e q u e q u e q u e q u k e y $ d o w n $ t b l + l

1*2 c o m m o d o r e $ m o d e + l m s g p t r o f f s e t

+1 c u r $ p o s + l s t r i n g $ i n d e x e q u

; 1 s t r e l e a s e e n d ( 3 J u n e 8 5 ) s y s $ f r e q e q u s t r i n g $ i n d e x + l

; 2 n d r e l e a s e e n d ( 1 A u g 8 5 ) e q u s y s $ f r e q + l

; - l = 5 0 H z , 0 = 6 0 H z b o o t $ s t a c k

•

; = = > t e m p ROM b o o t d a t a s t o r a g e b l k $ p t r $ c n t e q u 3 2 l o a d $ c o u n t l d $ b l k $ p t r b l k $ u n l d $ p t r b l o c k $ s i z e b l o c k $ e n d b l o c k $ p t r s i n f o $ b u f f e r e q u e q u e q u e q u e q u e q u e q u b o o t $ p a r m l o a d $ c o u n t l d $ b l k $ p t r

+2 b l k $ u n l d $ p t r n u m b e r o f 1 2 8 b y t e b l o c k s t o l o a d c u r r e n t s e c t o r d m a p o i n t e r r e a d m e m o r y b l o c k ( l k , 2 K ) p o i n t e r

+2 b l o c k s i z e ( 1 K = 3 2 o r 2 K = 6 4 ) b l o c k $ s i z e + l b l o c k $ e n d

+2 a l l o w 4 8 K c p m . s y s t o l o a d e n d o f b l o c k l o a d b u f f e r (+ 1 K o r + 2K b l o c k $ p t r s + b l k $ p t r $ c n t e x t $ n u m r e t r y e q u i n f o $ b u f f e r

; C f ^ l 3 . s y s l o a d a d r ' s a n d c o u n t s

+12

C P M 3 .S Y S c u r r e n t e x t # e x t $ n u m + l e q u e q u e q u r e t r y + 1 + 6 4 b o o t $ s t a c k a l l o w 6 4 b y t e s o f s t a c k

;= = = > s p e c i a l e q u a t e s u s e d b y CXKEY s p e c i a l e q u

00010111 b

S F $ e x i t e q u

l h

S F $ i n s e r t e q u 0 2 8 h

S F $ d e l e t e a l p h a $ t o g g l e a l t $ k e y

S F $ l e f t

I f $ a r r o w

S F $ r i g h t r t $ a r r o w e q u e q u e q u e q u e q u e q u e q u

0 2 B h

0 3 D h

0 5 Oh

0 5 5 h

0 5 6 h

0 5

6 h

RETURN KEY

PLU S KEY

M INUS KEY c c m m o d o r e k e y a l t e r a n t k e y l e f t a r r o w k e y l e f t a r r o w k e y r i g h t a r r o w k e y r i g h t a r r o w k e y b u f f $ l a r g e b u f f $ s m a l l b u f f $ p o s e q u e q u e q u

2 5

; = = > E x t e r n a l R S 2 3 2 i n t e r f a c e c o n t r o l s r x d $ 6 5 5 1 e q u USART+0 t x d $ 6 5 5 1 s t a t u s $ 6 5 5 1 e q u e q u

USART+0

USART+1 r e s e t $ 6 5 5 1 c a n m a n d $ 6 5 5 1 c o n t r o l $ 6 5 5 1 t x r d y e q u e q u e q u e q u

USART+1

USART+2

USART+3 l O h r x r d y c r r d $ i n i t c n t r $ i n i t $ 1 9 2 0 0 c n t r $ i n i t $ 9 6 0 0 c n t r $ i n i t $ 6 0 0 e q u e q u e q u e q u e q u

0 8 h

O b h l F h l E h

0 1 7 h r e a d w r i t e r e a d w r i t e r e a d / w r i t e r e a d / w r i t e

; n o p a r i t y , e n a b l e t x d + r x d , i n t e r r u p t s o f f

; 1 s t o p ,

; 6 0 0 b a u d

b i t s , 1 9 2 0 0 b a u d

b i t s , 9 6 0 0 b a u d ( i n t e r n a l )

; = > m e m o r y m a n a g e m e n t l o a c t i o n s m m u $ s t a r t c o n f $ r e g c o n f $ r e g $ l c o n f $ r e g

$2 c o n f $ r e g $ 3 c o n f $ r e g $ 4 r r o d e $ r e g e q u e q u e q u e q u e q u e q u e q u

MMU

MMU+1

MMU+2

MMU+3 m u+ 4

MMU+5

3 e h

3 f h

7 f h

3 e h

7 e h b l h

714 COMMODORE 128 r a m ? r e g p a g e $

$ l p a g e $

$ h p a g e $ l $ l p a g e $ l $ h r r m u $ v e r s i o n e n a b l e $ C 6 4 z 8 0 $ o f f z 8 0 $ o n f a s t $ r d $ e n f a s t $ w r $ e n co m m o n $ 4 K c o rr m o n $

K c o m m o n $ 1 6 K e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u

MMU

MMU+7

MVIU

MMU+9

MWJ

+10

MMU

+11

11110001 b

10110001 b

10110000 b

Z 8 0 $ o n + 0

Z 8 0 $ o n + 8

0 9 h

O a h

O b h

; = > p r e c o n f i g u r a t i o n m a p s f o r c e $ m a p b a n k

$0 b a n k $ l e q u e q u e q u e q u

O ffO O h

O f f O l h

0 f f

02 h

O f f 0 3 h i o i o

$0 i o $ l e q u e q u

O f f 0 3 h

O f f 0 4 h

3 f h

7 f h

3 e h

7 e h

; = > 8 0 c o l u m n d i s p l a y e q u a t e s

D S $ i n d e x $ r e g e q u D S 8 5 6 3

D S $ s t a t u s $ r e g

D S $ d a t a $ r e g e q u e q u

; = > r e g i s t e r p o i n t e r s

D S 8 5 6 3

D S 8 5 6 3 + 1

D S $ c u r s o r $ h i g h

D S $ c u r s o r $ l c w

D S $ r w $ p t r $ h i g h

D S $ r w $ p t r $ l c w

D S $ r w $ d a t a

D S $ c o l o r e q u e q u e q u e q u e q u e q u

1 4

1 5

1 9

3 1

2 6

; = > s t a t u s b i t s

D S $ r e a d y e q u

D S $ l t $ p e n e q u

4 0 h

; = > d i s p l a y m e m o r y l a y o u t ( 1 6 K ) 0 - 3 f f f h

D S $ s c r e e n

D S $ a t t r i b u t e

D S $ c h a r $ d e f e q u e q u e q u

OOOOh

0 8 OOh

2000 h

; = > V IC e q u a t e s

; v i e c o l o r s b l a c k e q u w h i t e r e d c y a n p u r p l e e q u e q u e q u e q u g r e e n b l u e y e l l o w o r a n g e b r o w n l t $ r e d d a r k $ g r e y m e d $ g r a y l t $ g r e e n l t $ b l u e l t $ g r e y e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u

1 3

1 5

R M $ s t a t u s

;

; b i t 7

6 e q u R A M $ d s k $ b a s e

I n t e r r u p t p e n d i n g i f 1

T r a n s f e r c o m p l e t e i f 1

5 B l o c k v e r i f y e r r o r i f 1 n o t e : b i t s 5 - 7 a r e c l e a r e d w h e n r e a d

; r e a d

4 1 2 8 K i f 0 , 5 1 2 K i f 1

3 - 0 V e r s i o n #

O bh 1 6K t o p C a n n o n

OOh

O l h

? ? h

F S = 0 v a l u e t o b e w r i t e t o f a s t s e r i a l r e a d f a s t s e r i a l w r i t e t o p 4K c c m m o n t o p

K c c m m o n t o p 16K c c m m o n

APPENDIXES 715

RM$ c o m m a n d b i t 7

3 , 2

1 , 0 e q u R A M $ d s k $ b a s e + l ; r / w e x e c u t e p e r c u r r e n t c o n f i g . i f s e t r e s e r v e d e n a b l e a u t o r e l o a d i f s e t ( r e s t o r e s a l l r e g i s t e r t o v a l u e b e f o r e c o m m a n d w a s d o n e , e l s e p o i n t t o n e x t b y t e t o r e a d / w r i t e . ) d i s a b l e F F 0 0 d e c o d e i f s e t ( d o o p e r a t i o n a f t e r c o m m a n d w r i t e n ) r e s e r v e d

0 0 = t r a n s f e r C l 2 8 — > R am D i s k

0 1 = T r a n s f e r C l 2 8 < — R am D i s k

1 0 = s w a p C l 2 8 < - > R am D i s k

1 1 = V e r i f y C l 2 8 = R am D i s k

R M $ 1 2 8 $ lo w

; e q u R A M $ d s k $ b a s e + 2 b i t s 0 t o 7 o f C l 2 8 a d d r e s s

; r / w

R M $ 1 2 8 $ m id

; b i t s e q u R A M $ d s k $ b a s e + 3 ; r / w

t o 1 5 o f t h e C 1 2 8 a d d r e s s

R M $ e x t $ lo w

; e q u R A M $ d s k $ b a s e + 4 ; r / w b i t s 0 t o 7 o f R am D i s k a d d r e s s

R M $ e x t$ m id

; b i t s e q u R A M $ d s k $ b a s e + 5 ; r / w t o 1 5 o f R am D i s k a d d r e s s

R M $ e x t $ h i b i t 1 6 e q u R A M $ d s k $ b a s e

; r / w o f R am D i s k a d d r e s s i f 1 2 8 K v e r s i o n b i t s 1 6 t o 1 8 o f R am D i s k a d d r e s s i f 5 1 2 K v e r s i o n

R M $ c o u n t $ l o w

; e q u R A M $ d s k $ b a s e + 7 l o w b y t e t r a n s f e r c o u n t ( b i t s 0 - 7 )

; r / w

R M $ c o u n t $ h i

; e q u R A M $ d s k $ b a s e

; r / w h i b y t e t r a n s f e r c o u n t ( b i t s 8 - 1 5 )

R M $ i n t r $ m a s k b i t 7

5 e q u R A M $ d s k $ b a s e + 9 ; r / w l = e n a b l e c h i p i n t e r r u p t s l = e n a b l e e n d o f b l o c k i n t e r r u p t s l = e n a b l e v e r i f y e r r o r i n t e r r u p t s

R M $ c o n t r o l

; b i t 7

,6 e q u

0 1

1 0

R A M $ d s k $ b a s e + 1 0 ; r / w

I n c r o r i e n t b o t h a d d r e s s e s ( d e f a u l t )

F i x e x p a n s i o n a d d r e s s

F i x C l 2 8 a d d r e s s

F i x b o t h a d d r e s s e s

; = = > C IA e q u a t e s

D a t a $ a

D a t a $ b

D a t a $ d i r $ a

D a t a $ d i r $ b t i m e r $ a $ l o w t i m e r $ a $ h i g h t i m e r $ b $ l c w t i m e r $ b $ h i g h t o d ? s e c $ 6 0 t o d $ s e c t o d $ m i n t o d $ h r s s y n c $ d a t a i n t $ c t r l c i a $ c t r l $ a c i a $ c t r l $ b

C I A $ h o u r s e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u k e y ? r o w e q u

OOh

O l h

02 h

0 3 h

0 4 h

0 5 h

0 6 h

0 7 h

0 8 h

0 9 h

O a h

O bh

O c h

O dh

O e h

O f h

C I A l + t o d $ h r s

C I A 1 + D a t a $ a ; o u t p u t

716 COMMODORE 128 k e y $ c o l

V I C $ k e y $ r o w e q u e q u

C I A 1 + D a t a $ b

0 d

02 f h ;

; i n p u t o u t p u t

R S 2 3 2 d a t a l i n e H I

R S 2 3 2 d a t a l i n e LOW d a t a $ h i d a t a $ l o w l f $ s h i f t $ k e y r t $ s h i f t $ k e y c o m m o d o r e $ k e y c o n t r o l $ k e y t y p e $ l o w e r t y p e $ u p p e r t y p e $ s h i f t t y p e $ c n t r l t y p e $ f i e I d b n k l p a g e O p a g e l e q u e q u e q u

M M U $tbl$M d b d b d b e n d m

;

TJM P

ROM f u n c t i o n s m a c r o r s t

! d b x e n d m

TCALL r a c r o

X r n v i l , x ! r s t 4 e n d m

RJM P m a c r o

X r s t 3 ! d b x e n d m

RCALL i r a c r o

X r n v i l , x ! r s t 5 e n d m

F R $ 4 0

E R $ w r $ c h a r

F R $ c u r s o r $ p o s

F R $ c u r s o r $ u p

F R $ c u r s o r $ d c w n

F R $ c u r s o r $ l e f t

F R $ c u r s o r $ r t

F R $ d o $ c r

FR $C EL

FR $C ES

F R $ c h a r $ i n s

F R $ c h a r $ d e l

F R $ l i n e $ i n s

F R $ l i n e $ d e l

F R $ c o l o r

F R $ a t t r

F R $ r d $ c h r $ a t r

F R $ w r $ c h r $ a t r

F R $ r d $ c o l o r

; F R $ w r $ c o l o r

; e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u

0 e q u e q u e q u e q u

1 e q u e q u e q u e q u e q u

8 0 h l O h

20 h

0 4 h

00000011 b m a c r o

3 f h , 3 f h , 7 f h , 3 e h , 7 e h z

0 $ o n , c a r m o n $

K p a g e O , b n k l , p a g e l f b n k l

OOh

0 4 h

0 8 h

OCh l O h

1 4 h

1 8 h

I C h

20 h

2 4 h

2 8 h

2 C h

3 Oh

3 4 h

3 8 h

3 C h

4 0 h

4 4 h

4 8 h

4 C h c o n f i g r e g ' s m o d e & m em p a g e r e g ' s o f f s e t t o 4 0 c o l u m n ROM f u n c t i o n s

D = c h a r a u t o a d v a n c e

B = r o w , C = c o l u m n

;

B = c o l o r

B = b i t t o s e t / c l e a r , O b i t v a l u e i n D = r o w , E = c o l o u t H = r o w , L = c o l , B = c h a r , C = a t t r ( r e a l ) i n D = r o w , E = c o l , B = c h a r , C = a t t r ( r e a l ) o u t H = r o w , L = c o l

APPENDIXES 717

F R $ t r k $ s e c t

F R $ c h e c k $ C B M

F R $ b e l l

F R $ t r k $ 4 0

F R $ s e t $ c u r $ 4 0

F R $ l i n e $ p a i n t

F R $ s c r e e n $ p a i n t

F R $ p r t $ m s g $ b o t h

F R $ p r t $ d e $ b o t h

F R $ u p d a t e $ i t

F R $ A S C I I $ t o $ p e t

F R $ c u r $ a d r $ 4 0

F R $ c u r $ a d r $ 8 0

F R $ l o o k $ c o l o r

;

F R $ b l k $ f i l l

F R $ b lk $ m o v e

F R $ c h a r $ i n s t e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u

5 Oh

5 2 h

5 4 h

5 6 h

5 8 h

5A h

5 C h

5 E h

6 2 h

6 4 h

66 h

68 h

A h

C h

E h

7 Oh

7 2 h

7 4 h

7 6 h

7 8 h

7A h

7 C h

7 E h

HL p a s s e d o n t h e s t a c k f i x e d ROM l o c a t i o n s

R $ c m p $ h l $ d e

R $ w r i t e $ m e m o r y

R $ r e a d $ m e m o r y

R $ s e t $ u p d a t e $ a d r

R $ w a i t

R $ s t a t u s $ c o l o r $ t b l

R $ c o l o r $ c o n v e r t $ t b l e q u e q u e q u e q u e q u e q u e q u

-6

1 8 0 h + 0

1 8 0 h + 3

1 8 0 h + 6

1 8 0 h + 9

1 0 0 0 h - 2 4 6 - 1 6

1 0 0 0 h - 2 3 0 - 1 6

D i s k t y p e b y t e d e f i n i t i o n b i t 7 0 = G C R , 1=MFM

MFM

C l

C l $ b i t

T y p e O

T y p e l

T y p e 2 e q u e q u e q u e q u e q u e q u e q u i f b i t 7 i s 1 (MFM)

C 0 = 0 ,

5 , 4

C l = l ( s i d e 2 #, 0 t o ( n / 2 ) - l o r n/'.

0 0 = 1 2 8 , 0 1 = 2 5 6 , 1 0 = 5 1 2 , 1 1 = 1 0 2 4 b y t e / s e c t o r

3 , 2 , 1

0 d i s k t y p e (MFM) s t a r t i n g s e c t o r # (

o r

) i f b i t 7 i s 0 (GCR)

6 u n u s e d ( s e t t o

5 , 4

) a l w a y s 0 1 ( 2 5 6 b y t e s e c t o r s )

3 , 2 , 1 d i s k t y p e (G CR )

T y p e O = n o n e , s e t t r a c k a n d s e c t o r a s p a s s e d

T y p e l = C 6 4 t y p e d i s k

T y p e 2 = C l 2 8 t y p e d i s k u n u s e d ( s e t t o

)

1 * 1 2 8

0 * 6 4

1 * 6 4

0*2

1*2

2*2

;

2 n d s i d e s t a r t a t b e g i n i n g

2 n d s i d e c o n t i n u e s f r o m f i r s t

; (MFM) t o p , b o t t c m t h e n n e x t t r a c k

(TR K # 0 t o ( 3 4 o r 3 9 ) )

; (MFM) t o p ( t r k 0 e v e n ) , b o t t c m ( t r k

(TR K # 0 t o ( 6 9 o r 7 9 ) )

; (MFM) t o p TRK# 0 t o 3 9 , b o t t o n TRK#

(TR K # o n b a c k s t a r t a t 3 9 a n d g o t o 0 )

718 COMMODORE 128

T y p e 7 e q u

T y p e X e q u

S i e q u e q u

S i 2 8

S 2 5 6

S 5 1 2

S 1 0 2 4 e q u e q u e q u e q u

7 * 2

0*1

1*1

0 * 1 6

1 * 1 6

2 * 1 6

3 * 1 6

; (MFM) p a s s t h e b y t e v a l u e s s u p p l i e d

; a n d ' s e c t

; s t a r t a t s e c t o r

1 d s k $ n o n e d s k $ c 6 4 d s k $ c l 2 8 d i r $ t r a c k e q u e q u e q u e q u

\ 6 5 1 0 c o m m a n d s v i c $ r e s e t v i c $ i n i t v i c $ r d v i c $ w r v i c $ r d F v i c $ w r F v i c $ t e s t v i c $ q u e r y v i c $ p r t v i c $ f r m t v i c $ u s e r $ f u n v i c $ R M $ r d v ic $ R M $ w r e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u e q u

- 1

1 0

1 1

T y p e 0 + S 2 5 6

T y p e l + S 2 5 6

T y p e 2 + S 2 5 6

1 8

; a c c e s s t o a n y s e c t o r o n t h e

; C 6 4 d i s k d i r t r a c k

; r e b o o t C l 2 8

; i n i t i l i z e t h e b i o s 8 5 0 2

; r e a d o n e s e c t o r o f d a t a ( 2 5 6 b y t e s )

; w r i t e o n e s e c t o r o f d a t a

; s e t - u p f o r f a s t r e a d ( m a n y s e c t o r s )

; s e t - u p f o r f a s t w r i t e

; t e s t c u r r e n t d i s k i n d r i v e

; g e t s t a r t s e c t o r s a n d # s e c t o r / t r k

; p r i n t d a t a c h a r a c t e r

; f o r m a t a d i s k ( 1 5 4 1 )

; RAM d i s k r e a d

; RAM d i s k w r i t e

; e o m b e l l b s

I f c r x o n x o f f e s c c o n t r o l c h a r a c t e r s e q u e q u e q u e q u e q u e q u e q u e q u

OOh

0 7 h

0 8 h

O ah

O dh l l h

1 3 h l b h

APPENDIXES 719 fa p o

< a s

H C o o g h £ h os os s

0 3 " 3 S 2

C Q H U U U O r. -t o « o n r t O O N N U i s

00 f! z o , S

5 fa

os as

7 J 2

2 3 s s o E S ^ S S ;

S Z S l C i i H y U Q j w o u u a o a a o a a

— , A T t

® 2 j a “

B Q f a S j M < ( OS

J u W J < ( a ! P n S y w u P o

C j « C Q U U Q fa fa fa fa fa fa fa

U H

S * ! « 0

H Z H

OS 3 Z fa fa- K

T( X h-

© fa c-j

2 ® fisS

O n o aa

“ « g s

- B 5 S Z

P u u u p

^ z o o w a sa g s ^ 05

O S -3

S z

•< H H u

0 0 « > - C H » l

U U U U O O Q

-T

VO 0 j

U O

§ w us o» ps

H fa fa

05 PH

C4 o o

C/3 fa

05 £5

C/3 fa O P P

U U U U fa fa fa fa

H fa « o ps o S

PS H Z 5 fa fa fa &

^ ®

3 S ° ° o o fa fa a

O p e>

30 fa hi fa

—i

P z 3 o * ^ sa ea p o u

OS fa

0= OS g w — g f l Z O > J H K ^

H q o W O Z B ?

P S s s a s a S H Q a o | s f a H a < ( £ j S S z z k h K o o o o o p c w

U U U U U U f l f l

PS o aa o

PS e

PS vo g

P U S

V bi PS t» C/3 C/3

Q Q Q

U u w ffl u u

C< ts< ta

H f - ^ 0 g Z O ^ ® p s ^ s a ^ s a o ^ w S p

55 a P S p

£4

5 * ffl fa

U h -3 fa P< c/3

- I fa fa fa fa fa

J 05 j h O

^ Z a

1 p

p s

C S C O C Q U U U U

§ o S a < M ' 9 - i « r j ! §

<J fa

H p x £2 as W ct

O C Q X h ft. < W H s h h 3

D <! -< 03 u a a a

© © © o

< PS

H t» oo <( g

^ ^

C/D CC c/3

Q Q Q

R 1/1

U <s

IT)

© © z

Z O ^ z M

U H a - O

O 53 S SS ^ a o « < « c/s fa ffi P

U t e C B U O sc •< OS PS PS PS

Tt Tt < u <s ©

H s o VO r r j s o T t

3 fa fa

< pH fa

P5 a

PS P fa aa fa OS 2 u s 5 2 p y z 5 u ^ f a o a ^ ^ K P S

S S p u B ^ S z

W f a c q u p p o p

P -H p O

Z2 © c* © © ©

CQ © © u f a u

CQ t^> ©

O irj td

S o

Z D

-<! O

S S

S S o o p o o ^ a o

PS PS fa H

Z Z

O O

P P h aa o a > os S

* c o S

^ Z O

^ fa c

M J « C < S o - c < « 3 o

« ^ ^ oo p 5

P < < C/3 C/3 C/3

U Q Q f l Q Q w p o

Cfi5 X K

C/3

© o g H

Z d | Q ° §

^ < ps os S

„ H o f a 3 = P P &

| « ° B U P U J fafafafafafafafa s §

O o

2 H p fa fa fa

Z H fa fa

« ^

* fa fa m P W

OS PS ps fa fa o

^ w

<*“»i

<■**>

720 COMMODORE 128 a! « g i o n z > o < !>

| s o td pa s a

^ ^ R ^ o a c s w o S a * < ; o i i J ^ « 5 0 s . f t . D .

§ o X c u w

S s s a£ as a!

q a

C£ o rj M

Q O o «

W H Tt u o o fa O Q ta

C* ta ta ta .

O 05 >

Z E- Q y c h a z * h *< h ^ o ^

< O

U Q H

55 o £ 5 £ g S e g l i l S s i l S g i g -

£ g g g £ £ i S S 3 S 8 £ s i o t a ^ ^ : * l t a t a S O t a c i < a < Q ! ; o ! ! a ! ! t f c *

O t£4 o

C£

h z £ j g = g

W r* ^ w ^ 2 « os a 3

CO GO CO CO if'- ’T* *

: 5

53 ,_ ta

*C 2 Z

^ h u g a ^ >

«< 9 H g s 9 g g u Q f t , K H ^ Q ^

§ § “ & £ a a a a a 3 3 ®

O O H O O ® ^ O O S f t f t Q

X ta

Z ta

H g O H « 5 s fc

H O u

5 ta h

L^!

. « l £ ? ? £ s « P o w a w S z z > <

U t * ! 0 S H ™ O S Q «

I/} ^ O ta ta W rN ^ ^ »•■* ^ M t-M ^ 00 /r-}. /r^i

S | N c m h g t q g Q ^ o o o o i l b e S e o l , 1 - Q ® n o a - i $ f e N b b N Q o Q Q N H M b o Q Q C i Q b o o E i i o o o t a M N o Q o o Q b Q b o

0 taso o o U- U-

APPENDIXES 721

A PPEN DIX 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

7 6 5

APPENDIXES 723

4 3 2 1

724 COMMODORE 128

A U D IO O U T r

I D A C C

7 A 5 - T A I I

C L R B N K

I t k A 7

4 vA;- s lc

U55

A2 7 kA0

-i

D/ft OE

18 SA7y

10> SA <0/

14 SA5, l£ SA4,

13 SA2,

15 SA I /

1 7 5A0/

VAI4

VA 15

VMA® -VMA7

7 6 5

APPENDIXES 725

726 COMMODORE 128

CN 13

LED

R 4 2 l8o -n_

R 3 2

APPENDIXES 727 m t e ; :

/ \ L O W E N D O N L Y f e \ H I G H O J D O N L Y

I/O CONNECTOR

I/O — C o n tro l P o rts , K e y b o a rd ,

U s e r P o rt, S e ria l P o rt, C a s s e tte P o rt

S C S C H E M A T IC 3 1 0 3 7 8

728 COMMODORE 128

OPEN- 1 2 8 k ROM

CLOSE - 25G>K ROM

- 0 1 ONLY

- 0 1 ONLY | R A S dw

G C A 5 0

MAffl - M A T

D 0 - D l

8 7 6 5

C /P S . o t p f

APPENDIXES 729

R A M , R O M

S C H E M A T I C 3 1 0 3 7 8

2 1

GLOSSARY

This glossary provides brief definitions o f frequently used computing terms.

Acoustic C oupler o r Acoustic M odem : 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.

Alphanum eric: Letters, numbers and special symbols found on the keyboard, exclud

A L U : ing graphic characters.

Arithmetic Logic Unit. The part of a Central Processing Unit (CPU) where mathematical operations are performed.

A n im atio n : The use of computer instructions to simulate motion of an object on the screen through gradual, progressive movements.

A rra y : 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.

A S C II: Acronym for American Standard Code for Information Interchange, which is a seven-bit code used to represent alphanumeric characters. It is a useful communi cation code for such things as sending information from a keyboard to the computer, and from one computer to another. See Character String Code.

Assem bler: A program that translates assembly language instructions into machine language instructions.

Assem bly 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.

Assignm ent S ta te m en t: 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 trans mission to about 2400 baud (bps). See Synchronous Transmission.

A tta ck : The rate at which the volume of a musical note rises from zero to peak volume.

Background C olor: The color of the portion of the screen that the characters are placed upon.

731

732 COMMODORE 128

B A SIC : Acronym for Beginner’s All-purpose Symbolic Instruction Code.

Baud: A unit o f 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 o f Os and

Is.

Bit: The abbreviation for Binary diglT. A bit is the smallest unit in a com puter’s memory. Each binary digit can have one of two values, 0 or 1. A bit is referred to as set or “ on” if it equals 1. A bit is clear or “ off” if it equals 0.

B it C ontrol: 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.

B it M ap Mode: An advanced graphic mode in the Commodore 128 in which you can control every pixel on the screen.

B order Color: The color of the edges around the screen.

Branch: To jum p to a section of a program and execute it. GOTO and GOSUB are examples of BASIC branch instructions.

Bubble M em ory: 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 C l 28 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 N e tw o rk : 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.

C a rr ie r Frequency: A constant signal transmitted between communicating devices that is modulated to encode binary information.

C h aracter: Any symbol on the computer keyboard that is printed on the screen.

Characters include numbers, letters, punctuation and graphic symbols.

C h ara cte r M em ory: The area in Commodore 128’s memory that stores the encoded character patterns that are displayed on the screen.

C h ara cte r Set: A group o f related characters. The Commodore 128 character sets consist of upper case letters, lower case letters and graphic characters.

C h ara cte r 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 o f data that is modulated to encode binary information.

C oaxial Cable: A transmission medium, usually employed in local networks.

GLOSSARY 733

Collision D etection: Determination of collision between two or more sprites or between sprites and data.

C o lo r M em ory: The area in the Commodore 128’s memory that controls the color of each location in screen memory.

C om m and: A BASIC instruction used in direct mode to perform an action. See Direct

Mode.

C o m p iler: A program that translates a high-level language, such as BASIC, into machine language.

C om posite M onitor: A device used to provide the C128 40-column video display.

C o m p uter: 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.

C oordinate: A single point on a grid having vertical (Y) and horizontal (X) values.

C oun ter: A variable used to keep track of the number of times an event has occurred in a program.

C P U : 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.

D ata: 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.

D a ta Link Layer: A logical portion of data communications control that mainly ensures that communication between adjacent devices is error-free.

D a ta Packet: A means of transmitting serial data in an efficient package that includes an error-checking sequence.

D a ta Rate o r D a ta T ransfer Rate: The speed at which data is sent to a receiving computer— given in baud, or bits per second (bps).

D atassette: 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.

D ecrem en t: To decrease an index variable or counter by a specific value.

D edicated Line o r 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.

D e la y Loop: An em pty FOR . . . N EX T loop that slows the execution o f a program.

D ia l-U p Line: The normal switched telephone line that can be used as a transmission medium for data communications.

D ig ital: Of or relating to the technology of computers and data communications where all information is encoded as bits of Is or Os that represent on or off states.

734 COMMODORE 128

Dim ension: 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.

D ire c t Connect M odem : A device that converts digital signals from a computer into electronic impulses for transmission over telephone lines. Contrast with Acoustic

Coupler.

D ire ct 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 D rive: A random access, mass-storage device that saves and loads files to and from a floppy diskette.

Disk O p e ratin g System: A program used to transfer information to and from a disk.

Often referred to as a DOS.

D u ratio n : The length of time a musical note is played.

Electronic M ail, o r E-M ail: A communications service for computer users in which textual messages are sent to a central computer, or electronic “ m ailbox,” and later retrieved by the addressee.

Enable: To turn on a bit, byte or specific operation of the computer.

Envelope G en erato r: Portion of the Commodore 128 that produces specific wave forms (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 PR O M .

E rro r Checking o r E rro r 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

File: logical, mathematical or relational operators that return a numeric value.

A program or collection of data treated as a unit and stored on disk or tape.

F irm w are : Computer instructions stored in ROM, as in a game cartridge.

Frequency: The number of sound waves per second o f a tone. The frequency corre sponds to the pitch of the audible tone.

F ull-D uplex 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 o f instructions.

G CR: 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.

G raphic Characters: Nonalphanumeric characters on the computer’s keyboard.

Graphics: Visual screen images representing computer data in memory (i.e., charac

G rid: ters, symbols and pictures).

A two-dimensional matrix divided into rows and columns. Grids are used to design sprites and programmable characters.

GLOSSARY 735

H a lf-D u p le x 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.

H a rd w a re : Physical components in a computer system, such as the keyboard, disk drives and printer.

H exadecim al: Refers to the base-16 number system. Machine language programs are often written in hexadecimal notation.

H o m e: The upper-left corner of the screen.

1C: The abbreviation for Integrated Circuit. A silicon chip containing an electrical circuit made up of components such as transistors, diodes, resistors and capaci tors. Integrated circuits are smaller, faster and more efficient than the individual circuits used in older computers.

In crem en t: 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 o f 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 o f 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 N e tw o rk : 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 o f times.

M achine Language: The lowest-level language the computer understands. The com puter 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.

M a trix : A two-dimensional rectangle with row and column values.

M em o ry: Storage locations inside the computer. ROM and RAM are two different types of memory.

M e m o ry Location: A specific storage address in the computer. There are 131,072 memory locations (0-131,071) in the Commodore 128.

M FM : The abbreviation for Modified Frequency Modulation, a method o f 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). M icropro cessors used in Commodore personal computers include the 6510, the 8502 and the Z80.

Mode: A state of operation.

736 COMMODORE 128

M odem : 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.

M on ito r: A display device resembling a television set but with a higher-resolution

(sharper) image on the video screen.

M otherboard: In a bus-oriented system, the board that contains the bus lines and edge connectors to accommodate the other boards in the system.

M u lti-C o lo r B it 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.

M u lti-C o lo r C h aracter Mode: A graphic mode that allows you to display four different colors within an 8 by 8 character grid.

Multiple-Access N e tw o rk : 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.

N u ll 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.

O ctave: One full series of eight notes on the musical scale.

O p e ratin g System: A built-in program that controls everything a computer does.

O p e ra to r: 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.

O r d e r of Operations: Sequence in which computations are performed in a mathemat ical expression. Also called Hierarchy of Operations.

P arallel Port: A port used for transmission of data 1 byte at a time using 8 data lines, one for each bit.

P a rity 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 or joystick.

Pitch: The highness or lowness of a tone that is determined by the frequency o f 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 o f 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 com puter’s m em ory.

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 transmis sion medium, in turn, whether they have information to send.

Port: A channel through which data is transferred to and from the CPU.

P rin te r: Peripheral device that outputs the contents of the com puter’s memory onto a sheet of paper. This paper is referred to as a hard copy.

GLOSSARY 737

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 com puter’s memory, or be listed on a printer.

P rogram Line: A statement or series o f statements preceded by a line number in a program. The maximum length of a program line on the Commodore 128 is 160 characters.

Program m able: Capable of being processed with computer instructions.

PR O M : 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 M em o ry (R A M ): The programmable area o f the com puter’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 N u m b er: A nine-digit decimal number from 0.000000001 to 0.999999999 generated by the RaNDom (RND) function.

Read O n ly M em o ry (R O M ): The permanent portion of the com puter’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 pat terns 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.

R em ark: 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 M onitor: A high-resolution display device necessary to produce the C128 80- column 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 N e tw o rk : 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 o f 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 M em ory: The area of the Commodore 128’s memory that contains the infor mation displayed on the video screen.

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.

Softw are: Computer programs (set of instructions) stored on disk, tape or cartridge that can be loaded into random access memory. Software, in essence, tells the com puter what to do.

Sound Interface Device (S ID ): The MOS 6581 sound synthesizer chip responsible for all the audio features o f 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 M ov able Object Block (MOB).

Standard C h aracter Mode: The mode the Commodore 128 operates in when you turn it on and when you write programs.

S ta rt Bit: A bit or group o f bits that identifies the beginning of a data word.

S tatem en t: 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 clock ing, signal between sending and receiving devices.

Syntax: The grammatical rules of a programming language.

Tone: An audible sound of specific pitch and waveform.

T ransparent: Describes a computer operation that does not require user intervention.

V ariab le: 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 C ontroller (V IC ): 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 o f a tone oscillator/waveform generator, an envelope generator and an amplitude modulator.

W avefo rm : A graphic representation of the shape o f a sound wave. The waveform determines some o f the physical characteristics of the sound.

W ord: 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

Abbreviations, 670-673

ABS, 73

Accumulator, 127-129 addressing, 138 loading, 147-148

ACPTR, 422-423

ADC, 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

AND, 152, 162

APPEND, 27

Arithmetic instructions, 151-152 operations, 18-20

Arrays, 13, 16-18

ASC, 73, 660-662

ASL, 163

Assembler, 126-127

ATN, 73

AUTO, 27

BACKUP 27-28

BANK, 28

BASIC advanced programming techniques,

103-107 color RAM in C128, 218 color RAM in C64, 218-219

C l 28 bit map mode, 221 crunching of programs, 95

C64 bit map mode, 222

C64 character modes, 222 entering machine language subrou tines 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 C l 28, 215-217 screen memory in C64, 217

BASIN, 423-433

BCC, 163

BCS, 163

BEGIN/BEND, 28-29

BEQ, 164

BIOS (Basic Input Output System),

486-489, 500, 677-683, 704-

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, 98-99

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

Cassette connector, 398

CATALOG, 31

CHAR, 31-32, 115

Character mode accessing character ROM, 229 character memory, 226-229,

234-235 color data, 225-226, 235-237 color memory, 226

C l28 BASIC, 219-220

C64 BASIC, 222 multi-color, 233-237 programmable characters, 230-233 screen location, 224, 234 screen memory data, 224—225 standard, 223-233

CHKIN, 429-430

CHR$, 74, 660-662

CIA (6526) chip, 611-623 control registers 622-623 description, 611, 618-622 electrical characteristics, 613-615 interface signals, 615-616 interrupt control, 621-622 serial port, 620-621 timing, 616-617, 618-620

CINT, 410, 414

CIOUT, 423

CIRCLE, 32-33, 115-116

CKOUT 430-431

CLALL, 439

CLC, 166

CLD, 166

CLI, 166

CLOSE, 33, 428-429

CLOSE ALL, 443

CLR, 33

CLRCH, 431-432

CLV, 166

CMD, 33

CMP, 167

CMPSTA, 456

COLLECT, 34

COLLISION, 34, 267

COLOR, 34-35, 116-117

Color mode extended background, 237-239 memory map, 664 sprites, 283-285

A B O U T THE AUTHORS

LARRY GREENLEY, the principal author of the Commodore 128 Programmer's

Reference Guide, is a Senior Technical Writer in the Commodore Documentation

Group. In addition to writing text for the Guide, Larry created most of the examples and programs shown in the book. His previous publications include the C128 System Guide, the new (1984) C64 User’s Manual, and the Modem/300 User’s M anual, as well as a number of articles in computer magazines.

FRED BOW EN, the Senior Systems Engineer at Commodore, originated the overall

C l 28 design concept, which involves incorporating three computers in a single unit. He designed the C l 28 software system architecture and the software operating system, including the C l 28 Kernal, the Machine Language Monitor and the C l28 Editor. He also contributed to the development of the BASIC 7.0 language.

BILL HERD, the Senior Hardware Design Engineer at Commodore, was Project Leader for the C128 hardware design effort. He originated the C128 hardware design and architecture and was responsible for the integration of the Memory M anagement Unit.

He is co-author of the C l 28 hardware specifications.

DAVE HAYNIE, a Hardware Design Engineer at Commodore, was a principal contrib utor to the C l 28 hardware design effort. He was responsible for the intricate timing analysis and for integrating the Programmed Logic Array. He is co-author of the C l 28 hardware specifications.

TERRY RYAN, a Software Engineer at Commodore, was the major contributor to the development and implementation of the BASIC 7.0 language and cocreator of the software architecture.

VON ERTW INE, an independent software engineer, customized the Digital Research

CP/M 3.0 operating system for use with the C128. This included creating the 8502

BIOS routines, adapting several standard disk formats, and providing several enhance ments to CP/M 3.0.

KIM ECKERT, an Integrated Circuit Design Engineer at Commodore, was responsible for the design and development of the 8563 chip, which controls the C128’s 80-column display.

M ARIO EISENBACHER , an independent technical writer, is the author of a number of books and magazine articles in the computer field.

NORM AN M CVEY is independent technical writer/editor with a particular interest in information technologies. He is the co-author of the C128 Introductory Guide, the C128

System Guide and the new (1984) C64 User’s Manual.

GET FREE SOFTWARE

WHEN YOU SUBSCRIBE TO

COMMODORE MAGAZINE

Y ou’ll find u n b ia se d in -d e p th re v ie w s o f d ie b e s t n e w so ftw a re and h a r d w a r e . .. d isc o v e r h o w to m ake y o u r o w n p r o g ra m s . . . le a rn p ra c tic a l h o m e a n d bu sin e ss ap p licatio n s. A nd m u c h , m u c h m ore.

Plus, in e v e ry issue, y o u ’ll r e c e iv e free p ro g ra m s— b o th g am es an d p ra c tic a l ap p licatio n s— y o u c a n ty p e in an d u se rig h t away!

And, if y o u a c t n o w w e ’ll se n d y o u a FREE "B est o f L oadstar" d isk . . fu ll o f great gam es, p ra c tic a l p ro g ram s, p lu s u tilitie s, g rap h ics, m usic, tu to ria ls a n d m u c h m ore!

S u b scrib e o r r e n e w y o u r su b s c rip tio n n o w at th e lo w ra te o f S26.95 an d w e ’ll send you a full y ear o f C o m m o d o r e M a g a z i n e (12 issues, to ta l ) PLUS y o u r FREE “B est o f

L oadstar” d isk (S6.95 v alu e).

8 0 0 - 3 4 5 - 8 1 1 2

CALL

i n PA: 8 0 0 -6 6 2 -2 4 4 4

I C S , I w a n t to s a v e 10% o f f th e b a s ic s u b s c r ip tio n r a te o f $ 30.00f o r

C om m odore M agazine a n d r e c e iv e th e

“B e st o f L o a d s ta r ” D isk , FREE.

N a m e _____________________________________________________

A ddress___________________________________________________

C ity ______________________State___________Z ip__________

S ig n atu re__________________________________________________

□ E nclosed is m y c h e c k o r m o n ey o rd e r for $ _______ (M a k e ch eck o r m o n e y order, f o r S2 6 .9 5 p e r su b scrip tio n , p a y a b le to COM MODORE PUBLICATIONS)

□ Bill m e 128PRG

□ C harge m y VISA o r M asterC ard ( circle o n e ) C ard n u m b e r

E x p iratio n D ate____________________ a l l p r i c e s i n us c u r r e n c y .

o r call 800 -3 4 5 -8 1 1 2 to o rd e r (in Penna. 8 0 0 -6 6 2 -2 4 4 4 )

C anadian add 110.00 to ea ch su b scrip tio n to co v er postage. Overseas: $50.00/12 issues

Commodore 128

Programmer’s Reference Guide

This book is an indispensable reference guide and sourcebook for anyone using the new and powerful Commodore 128 computer. This machine has many new and exciting built-in features, such as the advanced BASIC programming language Version 7.0, superior graphics, and excellent sound and music capabilities. All information on these and other technical details, such as machine language programming, memory maps, input/output guide, pinout diagrams of primary chips, and schematics of the computer, are here in this, the only official Commodore 128 Programmer’s Reference Guide.

Whether you are a new user or an advanced programmer, you’ll benefit from all of the material in this book. Find out more about:

■ The New BASIC 7.0—Explaining new BASIC with advanced features

■ G raphics—Utilizing the Commodore 128’s graphics programming

■ Sound and M usic—Getting the notes out of the C128

■ Machine Language—Programming in machine language and combining it with BASIC

1 Operating System — Understanding the C128 operating system, the kernal, and memory management

■ Screen Editor and Memory M aps—Deciphering the C128, C64, and CP/M modes

■ Input/Output G uide—Controlling peripherals through software

■ Chips—Specifications and pinouts of all important chips

■ All this and much, much more

N D - S S 3 - 3 4 E T E - 4 > E n S

34292-4 ■ IN U.S. $21.95 (IN CANADA $24.95) ■ BANTAM COMPUTER BOOKS

Hello! I am an AI chatbot specifically trained to assist you with the Commodore 128 Reference manual. I have thoroughly reviewed the document and can help you locate the exact information you need or explain the content in clear and simple terms. Whether you’re looking for guidance on specific features, troubleshooting steps, or general usage, feel free to ask your questions. The more details you provide about your concerns or needs, the more accurately and effectively I can assist you!

Show related prompts

Assistant typing

Assistant is out of keyboard. Please, try again later.

Key features

128K RAM (expandable to 256K or 640K)
80-column display
C64 software compatibility
CP/M 3.0 operation
Enhanced BASIC 7.0
Three operating modes (C128, C64, CP/M)

Frequently asked questions

The standard Commodore 128 has 128K of RAM, but this can be expanded to 256K or 640K using optional RAM modules.

Yes, you can. The Commodore 128 is compatible with Commodore 64 software when in C64 mode.

The Commodore 128 can run in three primary modes: C128 mode, C64 mode, and CP/M mode. The CP/M mode allows you to utilize CP/M 3.0 software.