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