               
               =======================================
                    LISA 2.5 DOCUMENTATION FILE #4
               =======================================
               
                         WRITTEN BY: DATA CAT
               


-WHAT HAPPENS WHEN YOU ASSEMBLE A LISA SOURCE FILE

The  6502  microproccessor  does  not  understand "assembly language".
What is does understand is "6502 machine language".  Assembly language
& machine language are one and the same, but in  fact  they  are  not.
Assembly  language consists of the labels, mnemonics, expressions, and
comments which have been previously described in this manual.  Machine
language,on the other hand, is  an  unreadable  collection  of  binary
data.   An  assembler's job is to convert assembly language to machine
language so that the 6502 will understand what's going on.  If  fairly
easy  to convert assembly language to machine language.  At some point
during an assembly, stop the assembly by pressing the space  bar.   In
addition to the source code, which is displayed on the right hand side
of  the  screen  (possibly  with warp-around) you will see several HEX
digits on the left side of the screen.   The  first  four  HEX  digits
correspond  to  the  address  where  the program will reside when run.
Following these four HEX digits, separated by one space, come zero  to
six  HEX  digits.   These  digits  correspond  to  the  matching  code
generated by LISA.  If you look up these code on the 6502 program card
you will see that these  operation  codes  correspond  to  the  actual
assembly  language  instructions  (plus  any required data).  The next
four digits correspond to the text file line number  followed  by  the
actual  source code.  Normally the object code (machine code) produced
is stored in memory at the address specified by the address listed  at
the  far  left (but see the OBJ opcode).  When you run the program the
code must be stored at this location in memory.  If the program is not
stored at this location in memory, it  will  not  work  properly  when
executed.   Some  are  an  exception to this rule called "relocatable"
programs.  Once assembled, running an  assembly  language  program  is
easy.   First  get into the monitor by issuing the LISA "BRK" command.
Once in monitor you may run your program by  using  the  monitor  "GO"
command  (similar  to BASIC "RUN").  If your program begins at address
$800 you must issue the monitor command "800G" to  run  your  program.
This  command  tells the monitor to begin running the machine language
program  located  at  location  $800.   To  terminate  you  mach.lang.
program,  there  are  several  ways.  You can issue a BRK mnem.  which
will stop  the  program,  print  the  current  contents  of  the  6502
registers  &  return  to  the  monitor.   If  you terminate with a RTS
instruction you will be returned to the calling routine (in this  case
the  monitor).   You also can use JMP instruction to enter BASIC,LISA,
Pascal or some other program directly.  NOTE ** If you  plan  to  CALL
your  routine from BASIC or Pascal, you should always end you assembly
language program with a  RTS  instruction  so  that  control  will  be
returned to the calling program. 

-RUNNING A LISA PROGRAM: FROM START TO FINISH

Decide  exactly  what  program you wish to write,once decided upon the
next step is to decide how the program is to  be  written.   Then  the
program  has  to  be entered into LISA's text editor.  To do this type
"INS" at the "!" prompt.  After hitting return your screen should look
something like this:  !INS and a blinking cursor will prompt  you  for
text   entry.   As  will  all  6502  programs  not  utilizing  decimal
arithmetic, the first instruction  should  be  a  clear  decimal  flag
instruction  or  "CLD"  .   To  enter  this  instruction  type a space
(remember, column one is reserved for labels) and the  sequence  "CLD"
followed by return. 

         !INS
            1  CLD
            2

Once  again  the  blinking  cursor tells you that its waiting for text
entry.  The first thing we want to do is load the accumulator with the
constant  $FF.   To  do  this  we  must  use  the  assembly   language
instruction  "LDA  #$FF"  (or  LDA  OFF  if  you like).  To enter this
instruction type a space (remember column one....) followed by  "LDA".
Now another space then "#$FF" followed by return. 

         !INS
            1  CLD
            2  LDA #$FF
            3

Again  the  blinking  cursor.  Now we must enter the instruction which
prints the contents of  the  accumulator  as  two  hex  digits.   This
happens  to  be "JSR" $FDDA".  To enter, type space, followed by "JSR,
followed by space, Followed by $FDAA", followed by return. 

         !INS
            1  CLD
            2  LDA #$FF
            3  JSR $FDDA
            4

Now the command to return  control  to  the  monitor.   Type  a  space
followed "RTS", followed by return. 

         !INS
            1 CLD
            2 LDA #$FF
            3 JSR $FDDA
            4 RTS
            5

As  far as the 6502 is concerned, our program is complete, but we have
to tell LISA that the end of the program has been reached. 


Follow the above inst for spaces and return

         !INS
            1  CLD
            2  LDA #$FF
            3  JSR $FDDA
            4  RTS
            5  END
            6

Note that more text is wanted (by line 6).  To get out of  text  entry
mode  type  control-E  as  the first character on line 6, upon hitting
return you will return to the  command  level.   Since  there  are  no
labels  in  our  program, printing the symbol table will prove to be a
big waste.  Why don't we issue the opcode DCM "INT"  just  before  the
END  so  that  the  symbol table info will not be printed.  To do this
type "INS 5" at the command level.  This tells  LISA  to  put  you  in
"insert" mode with all text being inserted before line 5. 

         same as above example 1-6

         addition
         !INS  5
            5

the blinking cursor reminds you that a text entry is required.Now type
in a space,followed by DCM,followed by "INT",followed by return

         same as above example 1-6

         plus
         !INS  5
            5  DCM "INT"
            6

Type  control-E  on  line  6  to end this correction.  Our program now
completed, use the L(IST) command to verify.  We must now assemble the
text file before it can be run.  To do this simply  type  ASM  at  the
command level. 

         !ASM

         *** END OF PASS ONE

         *** END OF PASS TWO

         0800 D8        1         CLD
         0801 A9FF      2         LDA #$FF
         0803 20DAFD    3         JSR #FDDA
         0806 60        4         RTS
         0807           5         DCM "INT"
         INT!

The  first  column  is  the  hexadecimal  address  where  the  current
instruction/code  reside.   The  second  field  contains  the  opcodes
produced  by LISA.  The third field is the line number followed by the
source statement.  Since we  did  not  explicitly  specify  a  program
origin,LISA  used  the  default  of  $800.  Likewise, since we did not
specify where the code was to be  stored  in  memory,  it  was  stored
beginning  at location $800.  Since the program was assembled at $800,
to run the program we must issue either a "CALL 2048"  from  BASIC  or
800G  from the monitor ($800= 2048 decimal).  To run from the monitor,
use LISA command "BRK" (type BRK while in the command  mode)  and  you
will  be  placed  in  the monitor.  When you get "*" prompt, type 800G
followed by return.  The screen will look like this: 

         !BRK
         *800G
         FF
         *

The FF was the printed result of our program and we were  returned  to
the  monitor  ("*").   If  you  wish  to  return to LISA type, "E000G"
(coldstart) or "E003G"  (warmstart).   Although  you  don't  have  to,
programmers  make  sure that the first line in their program is either
the first line to be executed, or a  JMP  to  the  first  line  to  be
executed.  This makes it easy to determine the starting address of the
program.If  you plan to go back and forth between your program & LISA,
make sure that you do not utilize the  zero  page  locations  used  by
LISA.Unpredictable  things  may  happen.  Before running your program.
ALWAYS make sure that you have saved your latest version to disk,  its
too easy for a bug in your program to wipe out everything in memory. 

-SOFTWARE PROVIDED WITH LISA

-THE LZR IOS ROUTINES (LISA P2.L)

A  collection  of  various  input/output  routines  &  several utility
routines.  Used for I/O handling inside LISA. 

-RANDY'S HIRES ROUTINES

Handy  hires  graphic  routines   intended   for   assembly   language
programing.   Intended  ranges  is  $1000-$2000.   Since  the routines
contain a considerable amount of internal docs there  was  not  enough
room  to hold the entire text file in memory all at once.  As a result
"HIRES.2" gets chained  in  during  assembly.   LO(AD)  RANDY'S  HIRES
ROUTINES & then A(SM) to text file.  An "ICL" pseudo opcode at the end
of RANDY'S HIRES ROUTINES automatically does the rest. 

-USING "SOFTWARE TOOLS"

This is a collection of routines is loosely modeled after the routines
found in the book "SOFTWARE TOOLS" by Kernighan & Plauger



APPENDIX

-A- MEMORY USAGE

PAGE 0 MEMORY LOCATIONS $50-$AF; $E0-$FF
PAGE 2 IS RESERVED I/O BUFFER
PAGE 3 IS OPEN FOR USER SUBROUTINES FROM $360-$3FF

$0800-$1800 IS RESERVED FOR USER GENERATED CODE
$1800-$7FFF IS RESERVED FOR THE TEXT FILE
$8000-$94FF IS RESERVED FOR THE SYMBOL TABLE
$9500-$95FF IS A RESERVED I/O BUFFER
$D000-$F7FF IS RESERVED FOR LISA

LISA  modifies  the  Apple  DOS  so  if you want to return to BASIC or
APPLESOFT, REBOOT a different  disk  containing  the  language.   LISA
requires  that  DOS  3.2 be used.  LISA MAY BE CONVERTED TO DOS 3.3 BY
"MUFFIN" PROGRAM. 
          
          
          ADDR           DESCRIPTION
          
          $E000          COLDSTART (CONTROL-B)
          $E003          WARMSTART (CONTROL-C)
          $E006          INSERT ENTRY
          $E009          USER COMMAND
          $E01B          HIGH ORDER BYTE OF TEXT FILE STARTING ADDRESS
          $E01C          HIGH ORDER BYTE OF SYMBOL TABLE STARTING ADDRESS
          $E01D          MNEMONIC TABLE ADDRESS
          $E01F          LINES/PAGE
          $E020          TITLE BOOLEAN   0=NO TTL PSEUDO OP. 1=TTL PSEUDO OP
          $E024          CLOCK SLOT#
          $E025          CLOCK Cn05 VALUE
          $E026          CLOCK Cn07 VALUE
          $E027          END OF SYMBOL TABLE ADDRESS
          $E029          USR PSEUDO-OP JSR'S HERE
          
          NOTE ** for LISA 48K systems subtract $8000 from  the  above
          addresses.   Control-C  &  Control-B  do  not  work  for 48K
          System.  You must type "$6000G" or "$6003G" to cold or  warm
          start LISA 48K. 








