Merlin Manual 

1.  Introduction

1.1  Assembly Language Whys and Wherefores

Some of you may ask "What is Assembly Language?" or "Why do I  need
to  use  Assembly  Language; BASIC suites me fine?" While we do not
have the space here to do  a  treatise  on  the  subject,  we  will
attempt to briefly answer the above questions.

Computer languages are often referred to as  "high level" or "  low
level"  languages.  BASIC,  COBOL, FORTRAN, and PASCAL are all high
level languages.  A high level language is one  that  usually  uses
English  like words (commands) and may go through several stages of
interpretation  or  compilation  before  finally  being  placed  in
memory.

Up to the present time, such a process  has  "ALWAYS"  resulted  in
programs  that  execute slower and consume a great deal more memory
than a well written assembly  language  program.   As  the  art  of
programming  progresses  we will probably see the day when a "good"
programmer will have a hard time beating a top drawer compiler on a
given problem. Until that time there will be plenty of room for the
dedicated assembly language programmer to ply his/her craft.

1.2  The 6502 Processor

The 6502  microprocessor  has  five  eight-bit  registers  and  one
sixteen  bit  register  in the Arithmetic and Logic Unit (ALU). All
data is ultimately  handled  through  these  registers.  Even  this
lowest of low level code requires a "program" in order  to function
correctly.  This program is hard wired within the 6502  itself.   A
program instruction goes through three distinct steps:

  1.  The address of the next instruction is sent  to  the  RAM/ROM
      memory.   This  is  called  the  "fetch"  cycle.  The  memory
      device(s) respond by sending the contents  of  the  addressed
      location(s) back to the Central Processing Unit (CPU).

  2.  The CPU decodes it (figures out what is  being  requested  by
      the instruction) and activates various gates and/flip flops.

  3.  Finally, we enter the "Execution  phase"  where  the  actions
      called for by the instruction are carried out.

1.3  Programming Evolution

A program instruction resides in memory as a  one,  two,  or  three
byte  group.   A  byte  contains  eight binary; bits of data and is
usually notated in  hexadecimal  (base  16)  form  (as  opposed  to
decimal,  octal,  or  binary).   Please note that there is a strong
relationship between hexadecimal, octal and  binary.  The  assembly
language programmer is expected to be conversant in all three.

Some early microcomputers allowed program and/or  data  entry  only
through  front  panel  switches.   This  was  supplanted shortly by
processors where one "only" had to insert a "boot" program in  this
fashion.  Once  the boot was loaded the processor could perform the
job of reading further program and/or data in a more civilized way.
At  the  next  step  up,  the user was allowed to enter the program
instructions  as  a  mixture   of   alphabetic   instructions   and
hexadecimal addresses/data for the operand.  The Apple ][ and Apple
][+ had a built in mini-assembler that  permitted  simple  assembly
language programming.  The assembler is missing from the Apple //e.

However, the mini- assembler was not sufficient to  create  a  long
and  comprehensive  program.  In  addition  to  allowing  input  of
instructions  in  a  alphabetic  mnemonic  code,  a  full   fledged
assembler allows the programmer to use "labels", which represent an
as yet undefined area of memory where a particular segment  of  the
program  will  be  stored.  In  addition,  an assembler will have a
provision for line numbers, similar to those in  a  BASIC  program,
which  in  turn  permit  the  programmer  to  insert lines into the
program  and  perform  other   editing   operations   relative   to
operations/instructions  already  in  the  program.   This  is what
Merlin is all about.

Before using this or any other assembler, the user is  expected  to
be   somewhat   familiar  with  the  6502  architecture,  modes  of
addressing, etc. This manual is  not  intended  to  teach  assembly
language   programming.  Many  good  books  on  the  6502  assembly
programming ar available at your local dealer; some are  referenced
later in this section.

1.4  Background and Features of Merlin

Merlin is a "TED-based" editor-assembler.  This means that while it
is  essentially  new  from the ground up, it adheres to and follows
almost all of the conventions associatd with TED ][+, in  terms  of
command mnemonics, pseudo-op's, etc.

The original TED ASM was  written  by  Randy  Wiggington  and  Gary
Shannon. It has been widely distributed "under the counter" by user
groups and individuals, under many  names,  and  in  a  variety  of
versions.  Seemingly,  each  person  added his own enhancements and
improvements. Merlin is no exception.  Representing  a  major  step
forward,  with  the addition of macro capability, Merlin appears on
the scene now  as  one  of  the  most  advanced  and  sophisticated
editor-assemblers for the Apple ][, yet retains all the easy to use
features of TED that make it desirable to the beginner in  assembly
language programming.

Significant changes in Merlin, in addition to macros,  include  the
use  of  the  logical  operators  AND,  OR,  and  EOR, and the math
operators for division, the ability  to  list  a  program  with  or
without line numbers, and substantially faster editing.  Similarly,
the edit modules now include many additional commands to facilitate
editing  and  the  "Read"  command allows any Apple text file to be
read into the edit buffer, thus permitting the use of source  files
from other assemblers, such as DOS Tool Kit.

Merlin assumes that your system has  at  last  48K  of  memory  and
operates  under  3.3  DOS.  BEWARE of custom DOS's.  Merlin does an











Merlin                     Introduction



automatic MAXFILES 2 upon entry, then reverts to the usual value on
exit.

1.5  Suggested Reading

  1.  SYSTEM MONITOR Apple Computing, inc. Peeking  at  Call-Apple,
      Vol I.

  2.  APPLE II MINI ASSEMBLER Apple Computer Inc. Peeking at  Call-
      Apple Synertek Programming Manual., Synertek 6500-20.

  3.  PROGRAMING THE 6502 Rodney Zaks, Sybex C-202.

  4.  THE APPLE MONITOR PEELED Wm  E.  Dougherty,  Apple  Computer,
      Inc.

  5.  A HEX ON THEE Val J. Golding, Peeking at Call-Apple, Vol II.

  6.  FLOATING POINT PACKAGE Apple Computer, Inc., The Wozpak II.

  7.  FLOATING POINT LINKAGE ROUTINES  Don  williams,  Peeking   at
      Call-Apple Vol I

  8.  APPLE ][ and //e REFERENCE MANUALS Apple Computer, Inc.

  9.  ASSEMBLY LINES
          by Rodger Wagner
      A continuing series of tutorial articles in SOFTALK magazine.
      An  excellent  introduction, easy to follow for the beginning
      language programmer.

 10.  ASSEMBLY LINES: THE BOOK by Rodger Wagner  A  compilation  of
      the  first  eighteen  issues of the assembly lines series. In
      addition, the text has been extensively edited and an  unique
      encyclopedia-like  appendix  has  been  added.  This appendix
      shows not only the basic details of each  6502  command,  but
      also  a  brief  discussion of its most common uses along with
      concise, illustrative listings.

 11.  CONVERTING BRAND X TO BRAND Y by Randall Hyde Apple  Orchard,
      Vol   I,  No.  I,  Mar/Apr  1980.  Usefull  notes  and  cross
      references on converting among assemblers.

 12.  CONVERTING INTEGER BASIC PROGRAMS TO ASSEMBLY LANGAUAGE    by
      Randall Hyde Apple Orchard, as above.

 13.  HOW TO ENTER CALL-APPLE ASSEMBLY LANGUAGE LISTINGS      call-
      Apple, Vol IV, No. 1, Jan 1981

 14.  MACHINE TOOLS Call-Apple in Depth, No 1.

















Merlin                  System Requirements



2.  SYSTEM REQUIREMENTS

   W 48K Apple ][

   W 16K RAM Card

   W 80 Column Board (optional)

   W Lower Case Board (optional)

2.1  Hardware Compatability List

   W VIDEX VIDEOTERM

   W FULL VIEW 80 (80 column board)

   W M & R SUP'R'TERMINAL (80 column board)

   W ALS SMARTERM (80 column board)

   W OMEGA MICROWARE RAMTEX 16 (16k RAM board)

   W ANDROMEDA 16K BOARD

   W MICROSOFT 16K BOARD

   W WIZARD 80 (80 column board)

Please note that Merlin  has  been  tested  with  the  cards/boards
listed  above.   The author makes no guarantees with respect to the
operation of Merlin with any 80 column boards not listed.

A noteable exception in the above, is the Apple 80 column card!  Do
not  despair,  for  the  Apple  80  column  simply select the Videx
Videoterm and a block cursor and all is well.






























NNNN