Path: utzoo!utgpu!news-server.csri.toronto.edu!rpi!zaphod.mps.ohio-state.edu!caen!uflorida!gatech!usenet.ins.cwru.edu!ysub!psuvm!art100 From: ART100@psuvm.psu.edu (Andy Tefft) Newsgroups: comp.binaries.apple2 Subject: LISA Assembler docs (3 of 3) Message-ID: <91128.205805ART100@psuvm.psu.edu> Date: 9 May 91 00:58:05 GMT Organization: Penn State University Lines: 688 THE BUILT-IN CALCULATOR AND REFERENCE TABLES The built in hexadecimal calculator is probably the most-often used "new" feature in the ALE program. By pressing the ESC (escape) key twice, you open up the calculator mode. Note that the calculator can be turned on at any point except in the middle of a list operation or when the FIND & REPLACE command prompts you for a YES/NO/QUIT reply. At any other time you can enter the calculator by double-striking the ESC key. In particular, you can enter the calculator mode even in the middle of a input line while in the insert mode. When you turn off the calculator, the screen will be restored to the display it contained before the calculator was turned on and you can continue any input you were entering when you turned the calculator on. The ALE hex calculator operates in one of two modes: decimal or hexadecimal. If the number in the display is prefaced by a dollar sign ("$"), then the calculator if operating in the hexadecimal mode. If the number in the display contains no such prefix, then the calculator is operating in the decimal mode. At any point you can switch between the hex and decimal modes using the "H" and "M" keys. Pressing "H" moves you into the hexadecimal mode and converts the number in the display to hexadecimal; pressing "M" switches the calculator into the decimal mode and converts the number in the display into its decimal form. While in the decimal mode, you can enter a value into the calculator using the 0I9 keys on the keyboard. In the hexadecimal mode the 0I9 and AIF keys are active. In the decimal mode, the AIF keys are ignored. The calculator supports two byte arithmetic. If you attempt to enter a value larger than $FFFF in hex mode, only the last four digits will be retained. In the decimal mode, entering a value between 32,767 and 65,535 will produce a negative number which is the two's complement representation of the number. Entering a number greater than 65,535 produces a value which is MOD 65,536 that is consequently displayed as a signed two's complement number. Moral of the story-- while operating in decimal mode, keep your decimal numbers below 32,768. The calculator supports fifteen different functions. Each function is executed by pressing a single key on the Apple's keyboard. The "H" and "M" commands you've already seen, the remaining commands are: addition + subtraction - multiplication * division / modulo or remainder % logical AND & logical OR | logical exclusive-OR ^ shift left < or , shift right > or . logical NOT ~ sign reversal S clear the calculator L Except for the last five operators and "H" and "M", all of these operators are binary operators which operate on the number in the display and the next number entered. A pending operation can be completed by pressing "=" or return. The shift left and right, logical NOT, sign reversal, clear the calculator, "H" and "M" operators are unary and operate directly on the value in the display. While in the calculator mode, pressing "T", "Q", "P", or "O" will display one of the reference charts available in ALE. Pressing "T" will display an ASCII character set chart ("A" can be used to toggle between standard and alternate character sets on an Apple //e or Apple //c); pressing "Q" will display a list of the ANIX entry point addresses; pressing "O" displays the ANIX CHARIO subroutine opcodes; and pressing "P" displays the values for the ProDOS opcodes. While the ProDOS opcodes are displayed, you can press the letter to the left of any particular ProDOS function and ALE will display the parameter list for that function. You can return back to the calculator mode by pressing ESC key. Likewise, you can return from the calculator back to ALE by pressing the ESC key. ALE's built-in calculator and reference charts are extremely valuable tools in the ALE program. We're sure you'll find them quite indispensable once you get used to them. THE NEW LISA MONITOR PROGRAM NOTE: This program is not available to LISA.64K users. Use the Apple monitor instead. Since the Apple monitor is not particularly compatible with ANIX, you should only operate it in the 40 column mode. First of all, the LISA monitor is not particularly compatible with the Apple monitor(s). The LISA monitor is not a stand-alone terminal program, it expects ANIX v2.1 to provide all of the console and device related operations. Furthermore, the LISA v3.2 monitor only maintains the most-often called entry points in the monitor, and these entry points are converted to ANIX calls. These entry points are supported only for the benefit of peripheral cards which insist on calling routines in the Apple monitor, they are not to be called by your assembly language subroutines. Call the equivalent ANIX routine instead! By removing most of the code dedicated to I/O functions in the Apple monitor program, enough space was freed to allow several important extensions to the debugger/monitor portion of the monitor. In addition to these extensions, an ANIX interface is provided that allows you to make ANIX calls while the monitor is switched into memory in the auxiliary language card bank on a 128K Apple //e or Apple //c (normally you could not call ANIX while the auxiliary language card bank is switched in because the stack and zero pages are also switched). Since the new LISA monitor program calls ANIX to perform all of its I/O, it automatically works with any console driver connected to ANIX. If an eighty-column (or greater) console driver is attached to ANIX, the monitor program will automatically display sixteen bytes across the screen when dumping memory (rather than eight bytes supported on the forty-column display). So if you're operating in an eighty-column mode, you'll be able to dump twice as much memory as before. The first new command command in the LISA v3.2 monitor is a generalized memory fill command. The syntax for the memory fill command is: adrs1.adrs2:byte1 {byte2...byten} Note the similarity between this command and the normal memory change command. The fill command fills all of the memory locations from adrs1 to adrs2 with the data following the colon. If there is a single byte following the colon, that byte is repeatedly stored into the specified memory range. If there are several byte values after the colon, the fill command circulates through these values as needed. ASCII strings as well as hexadecimal values are allowed in the data field. Examples: 800.900:0 Same as 800.900Z in old LISA monitor. 800.17FF:FF 1000.17FF:"hello there" 800.FFF:0 "ABC" 55 35 "DEF" 20 'GH' Another really useful addition to the LISA v3.2 monitor is the search command. This command lets you search though memory for the first occurrence of a string of bytes. The syntax for the command is: adrs1.adrs2=byte1 {byte2...byten} The search command searches, within the specified memory range, for the first occurrence of the data string which follows the equal sign. Like the memory fill command, the search command accepts hexadecimal data, ASCII data, or any mixture of the data in the data field. For example, the following command searches for the zero-terminated string "Hello there" in the memory range 800.8FFF: 800.8FFF="Hello there"00 The search command will print the address of the first occurrence of the string within the memory range specified (providing the string is present in this range). LISA V3.2 ERROR MESSAGE DESCRIPTIONS Edit Time Errors: BAD CHARACTER IN SYMBOL Illegal character in symbol. ILLEGAL MNEMONIC Mnemonic is not a valid LISA v3.x mnemonic. TOO MANY LABELS IN PROGRAM More than 512 labels in this source file. ILLEGAL LABEL Illegal character or label not allowed here. LABEL REQUIRED HERE Equates and other pseudo-opcodes require a label. ILLEGAL ADDRESSING MODE Invalid addressing mode for this instruction. ILLEGAL CHARACTER/OPERAND An illegal character was encountered in the operand field. BAD NUMERIC VALUE Value entered contained illegal characters or it was out of range. BAD STRING OR CHAR Usually a closing quote or apostrophe is missing. SYNTAX ERROR Catch all for general syntax errors. BAD LOCAL LABEL REFERENCE Illegal use of a numeric local label. MEMORY FULL Out of memory error. ILLEGAL COMMAND Bad LISA v3.x edit command. Assembly Time Errors: SYMBOL TABLE FULL Assembly-time symbol table overflow. OBJECT OVERFLOW The object code generated by the assembler was outside the range $800.... Either your program generated too much object code or you need to use an OBJ directive to move the object code down to location $800. TYPE CONFLICT Attempted to use a macro label as a variable name. DUPLICATE LABEL Label was previous defined in the source file. BAD FWD REFERENCE Address expression contains a symbol which has not been defined. Certain pseudo-opcodes req- uire all symbols in the address expression to be well-defined. BAD MACRO ID/PARAMETER Either the macro name is bad (or undefined) or one of the macro's parameters is bad. MISSING END The end-of-file was encountered without an END or CHN directive. SYMBOL IS NOT LOCAL Attempted to release a local label with RLS, but the label was not localized with a corres- ponding LCL directive. **DAMAGE** TO THE SOURCE FILE The source file has been corrupted. OUTSTANDING IF, WHL, OR MD The end of the source file was encountered with an open .IF, IF1, IF2, WHL, or .MD dir- ective. EL/FI W/O .IF An .EL or .FI directive was encountered with- out a corresponding .IF, IF1 or IF2 directive. SYMBOL PREVIOUSLY REFERENCED Occurs when an EPZ statement tries to define a symbol which was already referenced in the operand field of some instruction. WE W/O WHL A .WE directive was encountered without the corresponding WHL directive. BRANCH OUT OF RANGE The specified branch instruction contains an operand which is to far away for a relative branch. VALUE MUST BE ZERO PAGE The current addressing mode requires a zero page address expression. UNDEFINED SYMBOL A symbol in the operand field is undefined. PAU LISA v3.x encountered the PAU directive. PHASE ERROR A phase error has occurred on the second pass of the assembly. A QUICK GUIDE TO ANIX* FOR LISA V3.2 USERS The ANIX* v2.1 shell for Apple's ProDOS operating system brings a much-needed user interface to this powerful operating system. When ANIX is first booted, it prints an equal sign as a prompt character. ANIX commands are typed after this prompt command. ANIX contains two types of commands: intrinsic commands and extrinsic commands. An intrinsic command is a built-in command which is immediately executed by the ANIX operating system. Intrinsic commands can also be executed within most user-written programs. An extrinsic command is simply a program stored on the disk. Whenever a command is entered after the equal sign prompt, ANIX checks the command to see if it is an intrinsic command; if it is, it's immediately executed. If the command is not a built-in ANIX command, then ANIX checks to see if a BIN or SYS type file exists the the current ProDOS directory. If so, the program is loaded and executed. Disk-based programs are usually executed as extrinsic commands. LISA, ALE, and SETUP.LISA are three good examples of ANIX extrinsic commands. Intrinsic commands include CAT, CATALOG, DELETE, LOCK, UNLOCK, PREFIX, ONLINE, EXEC, RUN, LOAD, SAVE, BRK, RENAME, CLOSE, SYSSAVE, BOOT, DATE, and TIME. These commands may be executed from within LISA by prefacing the command with a control-D character (just like LISA v2.6 and LISA v3.0). You can execute any of these commands from an program during assembly using the ANX assembler directive. A brief description of these commands follows: CAT, CATALOG- These commands display the files in the currently selected ProDOS directory. The command can be optionally followed by a sub-directory name, a volume name, or ".Dn" (n=1I8). The ".Dn" form refers to a physical disk drive (slot six, drive one is .D1; Slot six, drive two is .D2; Slot five, drive one is .D3; etc., see below). DELETE Deletes the specified file from the disk. LOCK/UNLOCK Locks or unlocks the specified file. PREFIX Set the ProDOS file prefix to the specified name. If the name is absent, the current prefix is displayed. ONLINE Prints the names of the volumes currently online. EXEC Redirects keyboard input from the specified file. RUN
Calls the 6502 program at
. E.g., "RUN 1F00". LOAD {
} Loads the specified BIN or SYS file. If the optional hex address is present, the file is loaded at this address. E.g., "LOAD MYFILE", or "LOAD MYFILE 1AF0". SAVE , , Saves a file of type BIN starting at memory location of length . E.g., "SAVE MYFILE 800 1F0". BRK Transfers control to the Apple monitor program RENAME , Renames to . CLOSE Closes any open files left open by an applica- tion program. SYSSAVE , , Similar to SAVE, except the file is saved as a SYS type file. BOOT Boots the disk in slot six, drive one. DATE Prints the current ProDOS date. TIME Prints the current ProDOS time. ANIX PATHNAMES ANIX filenames differ only slightly from ProDOS filenames. ANIX supports two extensions to pure ProDOS pathnames: one extension provides you with the ability to specify a logical volume name by its physical drive location; the other extension lets you easily specify pathnames in a directory one level above the current sub-directory. ProDOS does not support a convenient mechanism for specifying a pathname beginning with a physical disk drive name. Pure ProDOS pathnames require the logical volume name, the disk drive in which the diskette can be found is usually irrelevant to ProDOS. A volume name of the form ".Dn" (where n is an integer value in the range 1..8) may be substituted anywhere a valid ProDOS volume name is allowed. The default assignments for the ".Dn" drives are: Spec Slot Drive ==== ==== ===== .D1 6 1 .D2 6 2 .D3 5 1 .D4 5 2 .D5 7 1 .D6 7 2 .D7 4 1 .D8 4 2 These default values can be changed by running the SETUP.ANIX program. Whenever ANIX encounters a prefix of the form ".Dn", a ProDOS ONLINE call is made to determine the logical name of the specified file. This logical name replaces the ".Dn" and (hopefully) you're left with a valid ProDOS filename. For example, suppose that the diskette "/ANIX.DEMO" is present in slot five, drive one. If you issue the command "LOAD .D3/X" the file "/ANIX.DEMO/X" would be loaded into memory. The ".Dn" drive specification can be used anywhere a volume name is allowed: after CATALOG, after PREFIX, etc. Another shorthand form of the current pathname available to ANIX users is "^". This symbol is used to specify the parent directory of the current working directory. For example, while working on the LISA assembler and ALE editor, all of the working files were kept in a directory labeled "LISA.SRC". Within the LISA.SRC directory were two additional directories: "ASM" and "ALE". The ASM directory contained the source listings of the assembler, the ALE directory contained the source listings of the Advanced LISA Editor. The parent directory, LISA.SRC, contained several files common to both programs. While working in the ASM subdirectory, files in the LISA.SRC directory could be accessed by typing "^/filename". This is a lot more convenient than typing "/LISA.DISK/LISA.SRC/filename". The caret prefix can also be used with the PREFIX command to set the current working directory to the parent directory of the current working subdirectory. Likewise, the caret prefix can be used with the CATALOG command to list the directory of the current directory's parent. If the caret prefix is used when the current working directory is the volume directory (i.e., the outermost level), the caret prefix is ignored. Redirected I/O ANIX*, like UNIX* and MS-DOS*, supports redirected I/O via the ">" and "<" operators. An ANIX command of the form: =cmdname {optional parameters } >outname redirects all of the output sent to the ANIX standard output device to the specified file. For example, the command "CATALOG >CATFILE" sends the directory listing to the TXT type file "CATFILE". Since most programs send their output to the ANIX standard output device, the output of most programs can be redirected to a text file using this technique. In addition to sending output to a text file on the disk, you can also redirect the output of a program to one of four ANIX physical devices. If "fname" is ".P", ".C", ".Sn" (n=0I7), or ".N" then ANIX will send the output of the program to the printer, communications driver, slot driver, or null device (respectively). The printer and communications drivers can be installed with the SETUP.ANIX program. Currently ANIX defines an Apple parallel printer interface card or a Pascal 1.1 Firmware protocol card in slot one as the ANIX printer device (this covers 95% of the printer interface cards available for the Apple II). The communications driver recognizes a Pascal 1.1 Firmware protocol card in slot two. Most serial and modem interfaces use the Pascal 1.1 Firmware protocol, so the ANIX communications driver will operate with such devices. The ANIX slot driver simply calls the peripheral card BASIC initialization entry point on a peripheral card ROM. The slot driver can be used as a last resort if your particular interface card is not hardware compatible with the Apple parallel interface card or the Pascal 1.1 Firmware protocol. Since peripheral card drivers aren't necessarily compatible with the ANIX operating system, you should avoid using the slot driver. The null device (a.k.a. "bit bucket") simply gobbles up characters without sending them anywhere. Input can be redirected to a program in a manner quite similar to output redirection. An ANIX command of the form: =cmdname {optional parameters} lisafilename The specified LISA file may be R)ead into LISA v3.2. For the most part, TK2LISA handles the conversion automatically. You should, however, assemble and compare the object code output of the two versions to catch a possible error in the TK2LISA conversion program. PRINT The ANIX v2.0 PRINT utility is used to dump all or part of a TXT type file to the standard output device. The simplest form of the PRINT command is: PRINT filename This command will dump the contents of the file "filename" to the Apple's video screen. You can dump several TXT files at the same time by stringing several filenames after the PRINT command. For example, the following command prints the three TXT files "FILE1", "FILE2", and "FILE3": PRINT FILE1, FILE2, FILE3 ANIX's redirected output facility can be used to print files (">.P"), send a file through the communications port (">.C") or some other ANIX device, or write the file to another TXT type file. PRINT, for example, can be used to join several files together. The previous example, if followed by a redirection of output command, would join FILE1, FILE2, and FILE3 together (concatenate them) into a single file. The PRINT command supports several options (called switches in ANIX terminology). A PRINT switch, like most ANIX switches, always begins with a hyphen and immediately precedes the file to which it applies. A list of some of the PRINT switches includes "-P" (page eject), "- " (numbered lines), "-(mm:nn)" (a range of lines), and "-[mm:nn]" (a range of column values). LPRINT The LPRINT command is used in a manner identical to PRINT except it reads, detokenizes, and lists LSF files (LISA Source Files) rather than TXT type files. ANIX Source Listings and Programmer Documentation The ANIX operating system shell was developed to help make writing 6502 assembly language programs easier under Apple's ProDOS operating system. Lazerware has released the ANIX operating system shell to the public domain, so you can make use of the ANIX operating system and all of the extrinsic programs in the EXTRINSICS library on the ANIX master diskette in any way you see fit (note that this does not include any programs or files on the the LISA assembler master disk). Lazerware is currently in the process of putting together an ANIX v2.1 programmer's reference guide. For those interested in writing programs that run under the ANIX shell, Lazerware will sell you a complete set of source listings for ANIX v2.1 and all of the extrinsics on the ANIX master diskette along with a copy of a rough draft of the ANIX programmer's guide for $50.00. To order this package, call Lazerware at (714) 735-1041. A DISCUSSION OF THE NMOS 6502 VS. THE CMOS 65C02 AND 65C802 Three primary versions of the LISA interactive assembler are provided with the 3.1 release: LISA, LISAC02, and LISAC802. These three assemblers accept code for the NMOS 6502, CMOS 65C02, and CMOS 65C802 assemblers (respectively). Since the 65C02 is upwards compatible from the 6502, and the 65C802 is upwards compatible from the 65C02, you could argue that only one version of the assembler, the 65C802 version, is actually required. Three versions of the assembler are supplied so you can easily tailor your software for a particular class of Apple II machines. If you want your software to run on all Apple II machines, you must restrict yourself to the original NMOS 6502 instruction set. Using the LISAC02 or LISAC802 assembler for this task is dangerous because you might, inadvertently, insert a 65C02 or 65C802 instruction into your program. If you are writing code for the Apple //c (or enhanced Apple //e systems) you can use the 65C02 version of LISA and your program will work properly on this class of machines. If you've installed a 65C802 chip in you machine, or you're working with a newer version of the Apple II family which supports the 65C802/C816, you can use the LISAC802 version. NOTE: 65C02 and 65C802 chips and data sheets can be purchased from Western Design Center 2166 East Brown Road Mesa, Az., 85203 (602) 962-4545 The 65C02, which is upwards compatible to the original NMOS 6502 chip, provides several new instructions and addressing modes for 6502 users. The new instructions and addressing modes are: NEW INSTRUCTIONS: BRA label Branch always. PHX Push the X-register. PHY Push the Y-register. PLX Pull the X-register. PLY Pull the Y-register. STZ zpg Store a zero into memory. STZ zpg,x Store a zero into memory. STZ abs Store a zero into memory. STZ abs,x Store a zero into memory. TRB zpg Test and reset bits. TRB abs Test and reset bits. TSB zpg Test and set bits. TSB abs Test and set bits. NEW ADDRESSING MODES: ADC (zpg) Add with carry, indirect. AND (ZPG) AND, indirect. BIT Imm Bit test, immediate. BIT zpg,x Bit test, zero page indexed by X. BIT abs,x Bit test, absolute indexed by X. CMP (ZPG) Compare, indirect. DEC Decrement accumulator. EOR (ZPG) Exclusive-or, indirect. INC Increment accumulator. JMP (ABS,X) Jump, indexed by X, indirect. LDA (ZPG) Load accumulator, indirect. ORA (ZPG) Or accumulator, indirect. STA (ZPG) Store accumulator, indirect. The 65C802 chip, which is upwards compatible to the 65C02 chip, provides several new instructions and addressing modes for 65C02 users. The new instructions and addressing modes are: NEW INSTRUCTIONS: BRL label Branch always, long. COP Coprocessor (often renamed "Call OPerating system") MVN Block move, negative (MOVERIGHT). MVP Block move, positive (MOVELEFT). PEA value Push immediate 16-bit value onto stack. PEI zpg Push 16-bit value at zpg onto stack. PER relabs Push program counter relative address onto stack (16-bit). PHB Push data bank register onto stack (normally zero). PHD Push direct register onto stack. PHK Push program bank register onto stack (normally zero). PLB Pull data bank register from stack. PLD Pull direct register from stack. REP Reset status bits. SEP Set status bits. STP Stop the clock (not implemented in LISAC802). TCD Transfer 16-bit accumulator value to direct register. TCS Transfer 16-bit accumulator value to 16-bit stack pointer. TDC Transfer direct register to accumulator. TSC Transfer stack to accumulator. TXY Transfer X to Y. TYX Transfer Y to X. WAI Wait for interrupt (not implemented in LISAC802). WDM NOP (not implemented in LISAC802). XBA Exchange upper and lower bytes in accumulator. XCE Exchange carry flag with emulation flag. NEW ADDRESSING MODES FOR GROUP ONE INSTRUCTIONS (ADC, AND, CMP, EOR, LDA, ORA, SBC, STA): zpg,S Stack relative (zpg is a 256-byte offset value). (zpg,S),Y Stack relative indirect indexed by Y. NOTE: LISAC802 does not support 24-bit addressing and the additional long address modes supported on the 65C816 chip. If you need to use these instructions, write macros for them. The LISAC802 MVN and MVP instructions do not allow operands. The source and destination blocks are always assumed to be in segment zero. Again, write macros if you are using the 65C816 and you need to move data between segments on the 65C816. Consult the Western Design Center 65C816 data sheet for more details on the 65C802/816 chip. ************************************************************************* Some notes: If you think the thought of writing macros for 65C816 instructions is horrible, LISA 816 (a.k.a. LISA v4.0) is commercially available. LISA v3.2 is free, so you can't complain too loudly. NOTE: Everything in the Lazerware package on BIX is public domain except the LISA assembler and its immediate support packages (XREF, SETUP.LISA, etc.). Feel free to pass any of these programs around to your friends, but commercial uses without my (Randall Hyde) express written permission is prohibited. Commercial use means selling the program, alone or in combination with some other package, for more than $10. This allows companies who are selling PD software to sell a LISA disk (as long as they don't sell it for more than $10), but it prevents someone from modifying the source listings, renaming the assembler, and selling it themselves (unless, of course, they sell it for less than $10). I will get more than a little upset if I see a rash of new assemblers that are assembling programs at speeds greater than 20,000 lines per minute available on the commercial market. After all these years (with almost no one else bothering to use the tokenization scheme in LISA) I'm going to be more than suspicious to find a rash of such products AFTER I've released the source listings to the product. These source listings to LISA are for your edification and as a form of support for an unsupported product. They are not a license to you to market the assembler (even in a somewhat modified form). Feel free to look at the algorithms present in LISA and write your own assembler based on the algorithms (but not the code). However, if you decide to do this, be prepared to defend yourself and your code to my satisfaction. And, not to end this discussion on a negative note, I encourage all of you to freely modify, improve, and exchange your own versions of LISA. If you change the version number, please keep it less than 4.0 to avoid confusion with the commercial versions of the assembler. Perhaps you should apply your name to the sign-on message along with your own personal version number -- E.G.: "Version 3.2 -- R. Hyde: 1.0" Since I am retaining the copyright to LISA, I am expressedly forbidding that you attach your own copyright to LISA, even if you've made substantial changes to the program. I've spent eight years improving LISA and I've turned it over sources and all to you guys. Please don't get greedy: reciprocate and pass your work along as well. Thanx for all the support in the past. Hope you get gobs of great use out of LISA. *** Randy Hyde