Commodore 64 MACRO User manual

THE COMMODORE 64
MACRO ASSEMBLER
DEVELOPMENT SYSTEM
t commodore
COMPUTER

THE COMMODORE 64
MACRO ASSEMBLER
DEVELOPMENT SYSTEM
Copyright 1982. Commodore Business Machines
Professional Computer Division
1200 Wilson Drive
West Chester, PA 19380

COPYRIGHT
This software product is copyrighted and all rights reserved by
Commodore Business Machines, Incorporated. The distribution and
sale of this product are intended for the use of the original
purchaser only. Lawful users of this program are hereby licenced
only to read the program, from its medium into memory of a
computer, solely for the purpose of executing the program.
Duplicating, copying, selling or otherwise distributing this product is
a violation of the law.
This manuai is copyright and all rights are reserved. This document
may not, in whole or in part, be copied, photocopied, reproduced,
translated or reduced to any electronic medium or machine readabie
form without prior consent, in writing, from Commodore Business
Machines (CBM).
DISCLAIMER
COMMODORE BUSINESS MACHINES, INC. ("COMMODORE11)
MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, WITH
RESPECT TO THE PROGRAM DESCRIBED HEREIN, ITS QUALITY.
PERFORMANCE, MERCHANTABILITY. OR FITNESS FOR ANY
PARTICULAR PURPOSE. THIS PROGRAM IS SOLD "AS IS". THE
ENTIRE RISK AS TO ITS QUALITY AND PERFORMANCE IS WITH
THE BUYER. SHOULD THE PROGRAM PROVE DEFECTIVE
FOLLOWING ITS PURCHASE, THE BUYER (AND NOT THE
CREATOR OF THE PROGRAM. COMMODORE, THEIR
DISTRIBUTORS OR THEIR RETAILERS) ASSUMES THE ENTIRE
COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION
AND ANY INCIDENTAL OR CONSEQUENTIAL DAMAGES. IN NO
EVENT WILL COMMODORE BE LIABLE FOR DIRECT. INDIRECT,
INCIDENTAL OR CONSEQUENTIAL DAMAGES RESULTING FROM
ANY DEFECT IN THE PROGRAM EVEN IF IT HAS BEEN ADVISED
OF THE POSSIBILITY OF SUCH DAMAGES. SOME LAWS DO NOT
ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED
WARRANTIES OR LIABILITIES FOR INCIDENTAL OR
CONSEQUENTIAL DAMAGES, SO THE ABOVE LIMITATION OR
EXCLUSION MAY NOT APPLY.

PREFACE
The Commodore 64 MACRO ASSEMBLER DEVELOPMENT SYSTEM
software package allows you to program in the native 6500 series
Assembly language code, directly on the Commodore 6d computer.
It provides you with a very powerful macro Assembler, editor,
loaders and two machine language monitors along with other
support routines. These development tools operate like and provide
the same level of direct machine interface as the Assemblers on
much larger computers.
This package contains everything that you will need to create,
Assemble, load and execute 6500 series Assembly language code.
You will notice that like the software contained on this diskette, this
user's manual is directed towards the experienced computer user
that already has some familiarity with the 6500 series Assembly
language and the operations of the Commodore 64 computer.
This product is not intended to provide the knowledge of 'how to' in
assembly language, but provides the software tools for the
experienced assembly language programmer.
It is recommended that the user obtain one or more of the reference
manuals listed below for a more detailed description of 6502
assembly language and the Commodore 64. (The publisher is listed
in parentheses.)
• 6502 Assembly Language Subroutines, Leventhal and Saville
(Osborne/McGraw-Hill)
• 6502 Software Design, Scanlon (Howard W. Sams & Co.)
• 6502 Assembly Language Programming, Leventhal
(Osborne/McGraw-Hill)
• Commodore 64 Programmer's Reference Guide
(Commodore/Howard W. Sams & Co.)
• Programming in 6502, Rodnay Zaks (Sybex)
This manual has been divided into five parts for easier reference.
Part One, "Introduction" provides a brief description of how an
assembler works along with some basic terminology used
throughout this manual. It is recommended that the novice user
read this section first to obtain a feel for the level of knowledge
needed to program in assembly language and use this manual.
Part Two, "'64 Macro Assembler Capabilities and Conventions", is
composed of Section 1-4 and describes those capabilities and
conventions used by this assembler.

Part Three, "Creating and Editing Assembly Source Files", is
composed of Sections 5-6 and decribes how to create and edit an
assembly language source file. Section 5 contains the instructions
for loading a support program or wedge. This program gives the
user additional commands for maintaining the disk and loading and
running programs. Section 6 contains the operating instructions for
loading and running the Editor64 program. This program allows the
user to create and edit assembly source files.
Part Four of the manual, "Assembling and Testing a Program", is
composed of Sections 7-9 and contains information on the programs
that allow the user to assemble, test, and debug object programs.
Section 7 describes the operation of the assembler program;
Section 8 describes the programs that must be used to load an
object program into memory; Section 9 describes the program that
allows the user to monitor memory for debugging purposes.
Finally. Par! Five, "Appendices", includes those charts and tables
that can be used as a reference to other sections. It also provides a
quick reference to the commands available when running certain
programs.

USER CONVENTIONS
Throughout this manual there are certain conventions used to help
make explanations less ambiguous. A list of these conventions is
given beiow. We recommend that the user become familiar with
these.
( ) Parentheses are used to denote an option. The only
exceptions to this rule are in those sections where
indirect indexed and indexed indirect addressing
are explained. In these cases the parentheses are
required.
label This is used to denote a label reference in an
assembler source program. The actuai label used is
determined by the programmer.
opcode This is used to denote one of the 6502 instructions
as specified in Appendix IV.
operand This is used to denote the operand, or argument
portion oi an instruction.
comments This is used to specify user comments-
filename This is used to specify a filename on disk. The
actual name is determined by the user.
filename* This is used to denote a wild card filename (i.e., a
filename that begins with the characters preceding
the '■■").
lower case Generally, lower case variables specify that it is up
variable to you to supply the actual data.
UPPER CASE Generally, UPPER CASE NAMES are the actual
NAME input to be typed.

TABLE OF CONTENTS
64 MACRO ASSEMBLER CAPABILITIES AND CONVENTIONS
1.0 INSTRUCTION FORMAT CONVENTIONS.. 3
1.1 Symbolic 5
1.2 Constants 6
1.3 Relative 7
1.4 Implied 7
1.5 Indexed Indirect 8
1.6 Indirect Indexed 9
2.0 ASSEMBLER DIRECTIVES 10
3.0 MACRO CAPABILITIES 14
4.0 OUTPUT FILES GENERATED BY THE ASSEMBLER 17
CREATING AND EDITING ASSEMBLY SOURCE FILES
5.0 ADDITIONAL BASIC DISK COMMANDS 19
5.1 Loading the DOS WEDGE64 Program 19
5.2 Using the DOS WEDGE64 Program 19
5.3 DOS WEDGE64 Program Commands 20
6.0 CREATING AND EDITING ASOURCE FILE 22
6.1 Loading the Editor64 Program 23
6.2 Using the Editor64 Program 23
6.3 Editor64 Program Commands 24
ASSEMBLING AND TESTING A PROGRAM
7.0 ASSEMBLING A SOURCE FILE 27
7.1 Loading the Assembler64 Program 27
7.2 Using the Assembler64 Program 28
8,0 LOADING AN OBJECT FILE 30
8.1 Loading the Loader Programs 30
8.2 Using the Loader Programs 31

9.0 TESTING AND DEBUGGING WITH THE MONITOR
PROGRAMS 32
9.1 Loading the MONITOR Programs 32
9.2 Using the MONITOR Programs 32
9.3 MONITOR Program Commands 33
APPENDICES
Appendix 1 OPERATING SYSTEM MEMORY MAP 40
Appendix II INPUT/OUTPUT REGISTER MAP 44
Appendix III DESCRIPTION OF FILES ON THE RELEASE DISK....51
Appendix IV 6500 SERIES MICROPROCESSOR INSTRUCTION
SET OPCODES 53
Appendix V A SAMPLE OUTPUT LISTING OF THE
COMMODORE 64 ASSEMBLER 55
Appendix VI EXPLANATION OF ERROR MESSAGES 57
Appendix VII ED1TOR64 COMMAND SUMMARY 64
Appendix VIM MONITOR COMMAND 65
Appendix IX DOS WEDGE64 COMMAND SUMMARY 66

INTRODUCTION
This manual describes the Assembly Language and assembly
process for Commodore 64 programs which use one of the 6500
series microprocessors. Several assemblers are available for 6500
series program development, each is slightly different in detail of
use. yef all are the same in principle. The 6500 series processors
include the 6502 through the 6515 (the instruction sets are identical).
The process of translating a mnemonic or symbolic form of a
computer program to actual machine code is called assembly, and a
program which performs the translation is an assembler. We refer to
the symbolic form of the program as source code and the actual
machine form as object code. The symbols used and rules of
association for those symbols are the Assembly Language. In
general, one Assembly Language statement will translate into one
machine instruction. This distinguishes an assmbler from a compiler
which may produce many machine instructions from a single
statement. An assembler which executes on a computer other than
the one for which code is generated, is called a cross-assembler.
Use of cross-assemblers for program development for
microprocessors is common because often a microcomputer
system has fewer resources than are needed for an assembler.
However, in the case of the Commodore 64, this is not true. With a
floppy disk and printer, the system is well suited for software
development.
Normaly, digital computers use the binary number system for
representation of data and instructions. Computers understand only
ones and zeroes corresponding to an 'ON' or "OFF' state. Users, on
the other hand, find it difficult to work with the binary number
system and hence, use a more convenient representation such as
octal (base 8). decimal {base 10), or hexadecimal (base 16). Two
representations of the 6500 series operation to 'load' information
into an 'accumulator' are:
10101001 (binary)
A9 (hexadecimal)
An instruction to move the value of 21 (decimal) to the accumulator
is:
A9 15 (hexadecimal)

Users still find numeric representations of instructions tedious to
work with, and hence1 have developed symboJic representations. For
example, the preceding instruction might be written as:
LDA #21
In this example, LDA is the symbol for A9, Load the Accumulator.
An assembler can translate the symbolic form LDA to the numeric
form A9.
Each machine instruction to be executed has a symbolic name
referred to as an operation code (opcode). The opcode for "store
accumulator" is STA. The opcode for "transfer accumulator to index
x" is TAX. The 56 opcodes for the 6500 series processors are
detailed
in Appendix IV. A machine instruction in Assembly
Language consists of an opcode and perhaps operands, which
specify the data on which the operation is to be performed.
A label is a 'name' for a line of code. Instructions may be labelled
for reference by other instructions, as shown in:
L2 LDA #12
The label is L2, the opcode is LDA, and the operand is #12. At least
one blank must separate the three parts (fields) of the instruction.
Additional blanks may be inserted by the programmer for ease of
reading. Instructions for the 6500 series processors have at most
one operand and many have none. In these cases, the operation to
be performed is totally specified by the opcode as in CLC (Clear the
Carry Bit).
Programmming in Assembly Language requires learning the
instruction set (opcodes), addressing conventions for referencing
data, the data structures within the processor, as well as the
structure of Assembly Language programs. The user will be aided in
this by reading and studying the 6500 series hardware and
programming manuals suppled with this development package.

1.0 INSTRUCTION FORMAT CONVENTIONS
Assembler instructions for the Commodore 64 assembler are of two
basic types according to function:
• Machine instructions, and
• Assembler directives
Machine instructions correspond to the 56 operations implemented
on the 6500 series processors. The instruction format is;
(label) opcode (operand) (comments)
Fields are bracketed to indicate that they are optional. Labels and
comments are always optional and many opcodes such as RTS
(Return from Subroutine) do not require operands. A line may also
contain only a label or only a comment.
A typical instruction showing all four fields is:
LOOP LDA BETA.X :FETCH BETA INDEXED BY X
A field is defined as a string of characters separated by a space.
A label is an alphanumeric string of from one to six characters, the
first of which must be alpha. A label may not be any of the 56
opcodes, nor any of the special single characters, i.e. A, S, P, X or Y.
These special characters are used by the assembler to reference
the:
• Accumulator (A)
• Stack pointer (S)
• Processor status (P)
• Index registers (X and Y)
A label may begin in any column provided it is the first field of an
instruction. Labels are used on instructions as branch targets and
on data elements for reference in operands.
The operand portion of an instruction specifies either an address or
a value. An address may be computed by expression evaluation and
the assembler allows considerable flexibility in expression
formation. An Assembly Language expression consists of a string of
names and constants separated by operators, + . - , ', and / (add,
subtract, multiply, and divide). Expressions are evaluated by the
assembler to compute operand addresses. Expressions are
evaluated left to right with no operator precedence and no
parenthetical grouping. Note that expressions are evaluated at
assembly time and not execution time.

Any siring of characters following the operand field is considered a
comment and is listed, but not further processed. If the first non-
blank character of any record is a semi-colon (;), the record is
processed as a comment. On instructions which require no operand,
comments may follow the opcode. At least one space must
separate the fields of an instruction.
Appendix V presents a sample output listing from the assembler.
Various examples of instruction format are included.

1.1 Symbolic
Perhaps the most common operand addressing mode is the
symbolic form as in:
LDA BETA ;PUT BETA VALUE IN ACCUMULATOR
In this example, BETA is a label referencing a byte in memory that
contains the value io be loaded into the accumulator. BETA is a
label for an address at which the value is located, Similarly, in the
instruction:
LDA ALPHA + BETA
the address ALPHA + BETA is computed by the assembler, and the
value at the computer address is loaded into the accumulator.
Memory associated with the 6500 series processors is segmented
into pages of 256 bytes each. The first page, page zero, is treated
differently by the assembler and processor for optimization of
memory storage space. Many of the instructions have alternate
operation codes if the operand address is in page zero memory. In
those cases, the address is only one byte rather than the normaE
two. For example:
LDA BETA
If BETA is located at byte 4B in page zero memory, then the code
generated is A5 B4. This is called page zero addressing, If BETA is
at 01 3C in memory page one. the code generated is AD 3C 01. This
is an example of "absolute" addressing. Thus, to optimize storage
and execution time, a programmer should design with data areas in
page zero memory whenever possible. (Please avoid assembling
code in page zero, as problems may he encountered.) Remember,
the asembler makes decisions on which form to uset based on
operand address computation.

1.2 Constants
Constant values in Assembler Language can lake several forms. If a
constant is other than decimal, a prefix character is used to specify
type:
$ (Dollar sign) specifies hexadecimal
@ (Commercial at) specifies octal
% (Percent) specifies binary
(Apostrophe) specifies an ASCII literal character in
immediate instructions.
The absence of a prefix symbol indicates decial value. In the
statement:
LDA BETA + 5
the decimal number 5 is added to BETA to computer the address-
Similarly;
LDA BETA + S5F
denotes that the hexadecimal value of 5F is to be added to BETA
for the address computation.
The immediate mode of addressing is signified by a # (pound sign)
followed by a constant. For example;
LDA #2
specifies that the decimal value 2 is to be put into the accumulator.
Similarly;
LDA »'G
will load the ASCII value of the character G into the accumulator.
Since the accumulator is one byte, the value loaded must be in the
range of 0 lo 255 decimal.
Immediate mode addressing generates two or three bytes of
machine code (depending on whether or not zero page addressing is
used), the opcode, and the value to be used as operand. Note that
constant values can be used in address expressions and as values
in immediate mode addressing. They can aiso be used to initialize
locations as explained in a later section as assembler directives.

1.3 Relative
There are eight conditional branch instructions available to the user.
In this example:
BEQ START ;IF EQUAL BRANCH TO START
if the values compared are equal, a transfer to the instruction
labelled START is made. The branch address is a one byte positive
or negative offset which is added to the program counter during
execution. At the time the addition is made, the program counter is
pointing to the next instruction beyond the branch instruction. The
offset is based on the location of the next instruction. A branch
address must be within 127 bytes forward or 128 bytes backward
from the conditional branch instruction. An error will be flagged at
assembly time if a branch target falls outside the bounds for relative
addressing. Relative addressing is not used for any instructions
other than branch.
1.4 Implied
Twenty-five instructions such as TAX (Transfer Accumulator to Index
X) require no operand, and hence, are single byte instructions. Thus,
the operand addresses are implied by the operation code.
Four instructions. ASL, LSR, ROL and RORT are special in that the
accumulator, A, can be used as an operand. In this special case,
these four instructions are treated as implied mode addressing and
only an operation code is generated.

1,5 Indexed Indirect
In this mode, the operand address is computed by first adding the X
register (the index) to the argument in the operand (tn the example
below, BETA). The resulting value is the indirect page zero address
which contains the actual operand address. In this example:
LDA (BETATX)
the parentheses around the operand indicates indirect mode. In the
above example, the value in index register X is added to BETA. That
sum must reference a location in page zero memory. During
execution, the high order byte of the address is ignored: thus,
forcing a page zero address. The two bytes starting at that location
in page zero memory are taken as the address of the operand in low
byte, high byte format. For purposes of illustration, assume the
following:
BETA contains $12
X contains $4
Locations $0017 and $0016 contain $01 and S25
Location $0125 contains $37
Then BETA + X is $16. the address at location 516 is S0125. the
value at $0125 is $37. and hence the instruction LDA (8ETA.X) loads
the value $37 into the accumulator. (This addressing mode is often
used for accessing a table of address vectors in page zero.) This
form of addressing is shown in the following illustration.
LDA (BETA,X
BETA ^-
$16
S17
S0125
/
\
)
12
+ 4 —
LOW BYTE
25
HUGH BYTE
01
VALUE 37
S12 + $14 = $16
^*

1.6 Indirect Indexed
Another mode of indirect addressing uses index register Y and is
illustrated by:
LDA (GAMMA),Y
In this case. GAMMA references a page zero location at which an
address is to be found. The value in index Y is added to that
address to compute the actual address of the operand. Suppose for
example that.
GAMMA contains $38
Y contains S7
Locations SQ039 and $0038 contain $00 and S54
Location S005B contains $126
The address at S38 is $0054; seven is then added to this, giving an
effective address S005B. The value at S005B is $126 which is loaded
into the accumulator.
In indexed indirect, the index X is added to the operand prior to the
indirection. In indirect indexed, the indirection is done and then the
index Y is added to compute the effective address. Indirect mode is
always indexed except for a JMP instruction which allows a
absolute indirect address, as exemplified by JMP (DELTA) which
causes a branch to the address contained in locations DELTA and
DELTA + 1. The indirect indexed mode of addressing is shown in the
following illustration.
LDA (GAMMA).Y
GAMMA -*
S38
38
54
$39
S005B
00
VALUE 126
50054 + $7 = S5B

2.0 ASSEMBLER DIRECTIVES
There are eleven assembler directives used to reserve storage and
direct information to the assembler. Nine have symbolic names with
a period as the first character. The tenth, a symbolic equate, uses
an equals sign ( = ) to establish a value for a symbol- The eleventh,
asterisk. (') means Ihe value of the current location counter. This
corresponds to the ORG directive in some assemblers. It is
sometimes read as "here" or "this location". Some equate examples
are "RED-5. BLUE = SFF. and * = $200". A list of the directives is
given below (their use is explained in this section):
.BYTE .WORD .DBYTE .PAGE .SKIP
.OPT END .FILE .LIB
Labels and symbols other than directives may not begin with a
period.
Examples of assembler directives can be seen in the sample
Assembler program in Appendix V.
If desired, all directives which are preceded by the period may be
abbreviated to the period and three characters, e.g., '.BYT.
.BYTE is used to reserve one byte of memory and load it with a
value. The directive may contain multiple operands which will store
values in consecutive bytes. ASCII strings may be generated by
enclosing the string with quotes. (All quotes are "single" quotes, i.e,
SHIFT 7.) It should be noted, however, that there is a limitation of 40
ASCII characters that can be stored in each .BYTE directive.
HERE .BYTE 2
THERE .BYTE 1, $F, @3, %101, 7
ASCII .BYTE 'ABCDEFH'
Note that numbers may be represented in the most convenient form.
In general, any valid 6500 series expression which can be resolved
to eight bits, may be used in this directive. If it is desired to include
a quote in an ASCII string, insert two quotes in the string. For
example:
BYTE 'JIM"S CYCLE1
could be used to store:
JIM'S CYCLE
It should be noted that the use of arithmetic operations in the .BYTE
directive is not supported in this version of the package.
10

.WORD is used to reserve and load two bytes of data at a time Any
valid expression, except for ASCII strings, may be used in the
operand field. For example;
HERE .WORD 2
THERE .WORD 1, SFF03. @3
WHERE .WORD HERE, THERE
The most common use for WORD is to generate addresses as
shown in the previous example labelled "WHERE", which stores the
16 bit addresses ot -HERE11 and "THERE'. Addresses in the 6500
series are fetched from memory in the order low-byte, then htgh-
byte. Therefore. .WORD generates the value in this order.
The hexadecimal portion of the example (SFF03) would be stored
Q3tFF. if this order is not desired, use .DBYTE rather than ,WORD.
.DBTYE is exactly like .WORD, except the bytes are stored in high-
byte, low-byte order. For example:
.DBYTE $FF03
will generate FF,03. Thus, fields generated by .DBYTE may not be
used as indirect addresses.
Equal ( = ) is the EQUATE directive and is used to reserve memory
locations, reset the program counter O, or assign a value to a
symbol.
reserve one byte
reserve two bytes
set program counter
assign value
assign value
the '= " directive is very powerful and can be used for a wide variety
of purposes.
Asterisk (') directive is used to change the program counter. To
create an object code program that starts assembly at any address
greater than zero, the '•' directive must be used. For example.
" - S2001. starts assembling at address $200.
Expressions must not contain forward references or they will be
flagged as an error. For example:
- = C+D-E+F
wouid be legal if C. D. E and F are all defined, but would be illegal if
any of the variables were defined later on in the program. Note also
that expressions are evaluated in strict left to right order.
HERE
WHERE
4 = $200
NB = 8
MB=NB+
5
Q
*
101
■ +
* +
1
2
11

.PAGE is used to cause an immediate jump to top of page on the
output listing and may also be used to generate or reset the title
printed at the top of the output listing.
PAGE 'THIS IS A TITLE'
PAGE
PAGE
'NEW TITLE'
If a title is defined, it-will be printed at the top of each page until it
is redefined or cleared. A title may be cleared with:
.PAGE ' '
.SKIP is used to generate blank lines in a listing. The directive will
not appear, but its position may be found in a listing. The directive
is treated as a valid input "list" and the list number printed on the
left side of the listing will jump by two when the next line is printed.
.SKIP 2 skip two blank lines
.SKIP 3*2-1 skip five lines
SKIP skip one line
.OPT is the most powerful directive and is used to control the
generation of output fields, listings and expansion of ASCII strings
in BYTE directives. The options available are: ERRORS,
NOERRORS; LIST, NOLIST; GENERATE, NOGENERATE.
.OPT ERRORS, LIST. GENERATE
.OPT NOE, NOL, NOG
Also valid is:
OPT LIST. ERR
Default settings are:
.OPT LIST, ERR, NOGEN
12