SynAssembler#
SYNASSEMBLER
SynAssembler by SYNAPSE SOFTWARE
An Adaptation by Steve Hales of the S.C. Assembler II - Version 4.0
SynAssembler (c) 1982 SYNAPSE SOFTWARE
Introduction#
SYNASSEMBLER is a convenient and powerful tool for software development on the Atari computer system. The assembler uses standard 6502 mnemonics and syntax, and includes many useful features for creating, editing, assembling and testing your assembly language programs. Now assembly language programming is almost as easy as programming in BASIC.
Here is a summary of the most exciting features:
- Full use of the standard Atari Screen Editor
- Tab stops for opcode, operand, and comment fields
- Fast parameterized renumber and delete command
- Uses BASIC like commands for files (eg. LOAD, SAVE, BLOAD etc.)
- Labels up to 32 characters long (lowercase letters and . accepted)
- English ERROR messages
- Ability to append source programs from tape or disk
- Display of memory usage
- Multiple source files, using .IN directive
- Store object code directly to disk file, using the .TF directive
- Listing to screen option using .LI ON and .LI OFF
- Assembles 6500 lines/minute
- Local labels
- Offending line is listed after an ERROR occurs
- Value of .EQ and address of .BS are printed on listing
- ASSEMBLER, DOS, HARDWARE, and OS locations protected during assembly
- ATASCII literals in address expressions
- Symbol table printed in alphabetical order
Synassembler requires 48K of RAM and one disk drive to operate. Very large programs can now be developed, using the "INCLUDE" and "TARGET FILE" capabilities. These allow the assembly of multiple source files, and direct storage of object code on binary files.
Manual#
We have included several sample programs to illustrate the use of the SYNASSEMBLER as well as being useful routines. These include:
- HARSH SCROLL :A Utility to coarse scroll the Atari screen display
- FINE SCROLL :A utility to fine scroll the Atari screen display
- PM MOVER :A utility to move players and missiles on the screen
- BELL :Ring the bell using Atari sound generators.
Blanks are compressed in source files to conserve memory and save space on disks. The compression algorithm replaces any string of consecutive blanks with a single code byte. Also, Atari assembler files are compatible and only require minor modification to assemble correctly. (See APPENDIX for further detail). Synassembler uses a memory-efficient method of storing the symbol table, with variable length entries. The symbol table is maintained in alphabetical order, using a high speed hashing scheme. The symbol table is maintained in memory until a new assembly is started or the NEW command is typed. This allows the RUN and VAL commands to be more useful and effective.
Assembler error messages are printed on the Screen and accompanied by a pleasant bell like tone on the speaker. (At least as pleasant as an ERROR message can be). After an assembly error is detected the offending line is listed to the screen automatically, in a position for easy editing.
EDITING FEATURES#
Any time the cursor is at the beginning of a line, typing [TAB] will cause the next line number to be generated. Immediately after loading, the "next line number" will be 10. The number will be displayed as five digits and a trailing blank. The cursor will be in a position for the first character of a label, or the asterisk for a comment line, or a semi-colon.
The "next line number" is always the value of the previously entered line number plus the current "increment". The increment is normally 10, but you can set it to any reasonable value with the INCREMENT command.
If you type the [TAB] in any other position than the beginning of a line, it will cause a "tab" to the next tab stop.
TAB STOPS#
The standard tab stops have been changed to allow for a nine character label before the opcode. Of course, you may use any length label from 1 to 32 characters followed by a blank and an opcode; but the use of the tab stops make for nicer looking programs. (Longer labels look nicer, if left on a line by themselves.)
CURSOR CONTROL#
SYNASSMBLER allows continued use of the ATARI cursor controls by pressing the CTRL key plus one of the four arrow keys on the right side of the keyboard. In addition, SynAssembler makes full use of the ATARI screen editor.
MEMORY USAGE#
The SYNASSEMBLER program is about 8000 bytes long, and occupies $9C00 through $BC1F in memory. The screen begins at $BC1F and goes through $BFFF, while the source program begins at the top of DOS and goes to $9C00.
During source program entry or editing, memory usage is monitored so that the source program does not grow so large as to overlap the symbol table. Overlapping will cause the "MEMORY FULL" error. message to print. During assembly, memory required by the symbol table is monitored to prevent the symbol table from overlapping the source program. Overlapping will generate the "MEMORY FULL" error message and abort the assembly.
In addition, memory usage by the object program is monitored, so that it will not destroy the source program, DOS, the Operating System, and hardware. Therefore, if the object program bytes are directed at any memory protected addresses the "MEMORY PROTECT" error message will be printed and assembly.
There are three types of commands in the SYNASSEMBLER: EDITING commands DOS commands and MONITOR commands. The EDITING commands are used to control the Editor and the assembler. Commands are typed immediately after the prompt symbol, which looks like this Ok..
EDITING COMMANDS#
There are seventeen editing commands in the SYNASSEMBLER. All editing commands may be abbreviated to the first three letters if you so desire.
command | description |
---|---|
ASM | Assemble source program, put object program into memory, and produce assembly listing. |
COPy | Duplicates specified lines in the source. |
DELete | Delete specified line. |
FINd | List all lines containing the specified string. |
HIDe | Changes the HIMEM pointer to 'hide' current source code prior to a MERge command. |
INCrement | Set the line # increment for automatic line numbering. |
LISt | List the source program or specified lines of source code. |
MEMory | Display the beginning and ending address. |
MERge | Use with HIDe to join source programs. |
MOVe | Moves a line of source code from one specified location to another. |
NEW | Delete the entire source program. |
RENumber | Renumber all or specified lines of source code. |
REPlace | Replace a specified string with another specified string. |
REStore | Restores HIMEM pointer after HIDe and MERge. |
RUN | Begins execution of your object program. |
VAL | Evaluates an operand expression and prints the value in hexadecimal. |
MON | Exit the editor and enter the monitor. |
EDITING COMMAND DETAIL#
The SYNASSEMBLER editor, combines the powerful Atari screen editing features with a BASIC-like line editor, Source programs are entered and edited in almost exactly the same way you would enter and edit an Atari BASIC program.
ASM command:
SYNASSEMBLER is a two pass assembler. The ASM command initiates assembly of your source program. During the first pass it builds a symbol table with the definition of every label that is used in your program. During the second pass the assembler stores the object code into memory or disk and produces an assembly listing. At the end of the second pass a list, in alphabetical order, of all the labels and their definitions is produced.
If any errors are detected during either pass, an error message will be printed as well as the offending line. The error message will briefly explain the type of error encountered and the line will be positioned for easy editing. All of these messages abort the assembly process so that as soon as you correct the error condition you may immediately restart the assembly.
If you are listing the assembly to the screen you may use the [CTRL]+[1] control to start and stop your listing. You may abort the assembly process by hitting the [BREAK] key in pass two of the SYNASSEMBLER.
COPY L1 L2
This command places a copy of line L2 just before L1 in the source. The new line is assigned line number L1. The old line L2 remains in the source. This command should be followed by a renumber command if there are multiple lines with the same line number in the source.
COPY L1 L2 L3
This command places a copy of lines L2 through L3 just before line L1 in the source. The old lines are assigned line number L1. The old line L2 through L3 remain in the source. This command should be followed by a renumber command if there are any multiple lines with the same line number in the source.
DELete command:
Deletes a line or a range of lines from your source program. Another way to delete a single line is to type it's line #, followed immediately by a carriage return.
HIDe AND MERge
These two commands, when used with the LOAD command allow you to join a program from disk or tape to a program that is already in memory.
HIDe temporarily changes the HIMEM pointer so that it appears as if there were no source proaram in memory. To remind you that you are HIDe-ing, the prompt symbol changes to [H] ok. After HIDe-ing a program, you can load another one from disk or tape. Then you type MERge to join the two programs together.
After this sequence of commands the program which was already in memory will follow after the program just LOADed. If the line numbers are not already as you wish them to be, you can use the RENUMBER command to assign new ones.
For example, suppose that we have 2 source programs on the disk named "PART1" and "PART2". We want to join them together so that "PART1" precedes "PART2".
Ok. LOAD "D:PART1" Ok. LIST 00010 * PROGPAM NUMBER ONE 00020 MAIN JSR SUBROUTINE 00030 RTS Ok. LOAD "D:PART2" Ok. LIST 00010 * PROGRAM NUMBER TWO 00020 SUBROUTINE 00030 LDA BOAT.LOC 00040 ASL 00050 ASL 00060 RTS Ok. HIDE [H] Ok. LOAD "D:PART1" [H] Ok. LIST 00010 * PROGRAM NUMBER ONE 00020 MAIN JSR SUBROUTINE 00030 RTS [H] Ok. MERGE Ok.
INCrement
Sets the increment used for automatic line number generation. The increment is normally 10, but you may set it to any value between 0 and 9999. INC 5
FINd
The FINd command allows you to search through your source program for a given text string, and list all the lines that contain that string. The correct procedure for use of this command is as follows: Type FINd, followed by a space and then the string for which you are searching. Every character you type between the space and the carriage return is part of the search key. (NOTE: you may append or prefix spaces to any string to perform label searches.)
LIST L1 L2
Lists a single line, a range of lines or your entire program. It works just like the list command in BASIC. While a program or range of lines is listing you can use the standard Atari pause control [CTRL1], to start and stop the listing to the screen. You may abort the listing by pressing the [BREAK] key.
MEMory
Displays the beginning and ending memory address of the source program and of the symbol table.
Source program: $9B99-9C1F Source length: $0086 Symbol table: $1F00-1F00Memory between the top of the symbol table and the bottom of the source program is free to be used without clobbering anything.
MERge; SEE "HIDe and MERge"
MOVe L1 L2
This command places a copy of line L2 just before L1 in the source. The new line is assigned line number L1. The old line L2 is removed from the source . This command should be followed by a renumber command if there are multiple lines with the same line number in the source.
MOVe L1 L2 L3
This command places a copy of lines L2 through L3 just before line L1 in the source. The new lines are assigned line number L1. The old lines L2 through L3 are removed from the source. This command should be followed by a renumber command if there are multiple lines with the same line number in the source.
NEW
This command acts just like it's BASIC counterpart. It deletes the current source program from memory and restarts SYNASSEMBLER just as though you were to reboot the program.
NOTE: A source program must, of course, be assembled into memory before it can be executed with the RUN command.
RENumber
Renumbers all or part of the lines in your source program with the specified starting line number and increment. There are three optional parameters for specyifying the line number to assign the first renumbered line (base), the increment, and the place in your program to begin renumbering (start). There are four possible forms of the command:
REN Renumber the whole source program: BASE=1000, INC=10, START=0 REN # Renumber the whole source program: BASE=#, INC=10, START=0 REN #1,#2 Renumber the whole source program: BASE=#1, INC=#2, START=0 REN #1,#2,#3 Renumber all lines from #3 through the end. BASE=#1, INC=#2, START=#3 The last form above is useful for opening up a "hole" in the line numbers for entering a new section of code. OK. LIST 00000 * A RENUMBER EXAMPLE 00003 START LDA #100 00013 STA $95 00058 LDA #99 00103 STA $A0 00110 RTS Ok. REN Ok. LIST 00010 * A RENUMBER EXAMPLE 00020 START LDA #100 00030 STA $95 00040 LDA #90 00050 STA $A0 00060 RTS Ok. REN 100 Ok. LIST 00100 * A RENUMBER EXAMPLE 00110 START LOA #100 00120 STA $95 00130 LDA #90 00140 STA $A0 00150 RTS Ok. REN 2000,4 Ok. LIST 02000 * A RENUMBER EXAMPLE 02004 START LDA #100 02008 STA $95 02012 LDA #90 02016 STA $A0 02020 RTS OK. REN 3000,10,2008 OK. LIST 02000 * A RENUMBER EXAMPLE 02004 START LDA #100 03000 STA $95 03010 LDA #90 03020 STA $A0 03030 RTS
REPlace dS1dS2d
This command replaces all occurences of string S1 with string S2 in the source. d is a delimiter and must be a non-space printable character that does not appear in either, S1 or S2.
REPlace dSidS2dtP
This command causes a search to be made for string S1. The search starts at the beginning of the source. Whenever S1 is found, the line containing it is listed and the user is prompted for 1 of 3 actions:
Y or [RETURN]-relace S1 with S2 and continue. N do not replace S1 with S2 and continue search. X do not replace S1 with S2 and stop search. d is a delimiter and must be a non-space, printable character not appearing in either SI or S2.
REStore
Restores the root source program if an assembly is aborted while inside an "included" module.
The 'root source program" is the source program that is in memory at the time the "ASM" command is issued. If this source program uses the ".IN" directive to include additional source files, it is possible that assembly might be aborted either manually by typing a [BREAK] key during the listing phase, or automatically due to an error in the source program.
If the assembly is aborted during the time that the root program is hidden, the prompt character changes from "Ok" to "I Ok". The RESTORE command will reset the memory pointers so that the root program is no longer hidden, and change the prompt character back to "Ok".
You do not have to use the REStore command after an abort unless you wish to get back to the root source program for editing purposes. If you type the ASM command, the assembler automatically restores before starting the assembly.
If an assembly aborts due to an error in a source line, you may correct the source line, SAVE the module on the appropriate file, and type ASM to restart the assembly.
RUN
Begins execution of your object program. An expression MUST follow the RUN command to define the place to begin execution of the program. For example, "RUN BEGIN" will cause execution to begin at the point in your program where the label BEGIN is defined. Your program will return to SYNASSEMBLER by using an RTS instruction in your program. You may abort your program by hitting the RESET key. Or, you may use the [BREAK] key to break and fall back to the monitor.
VALue
The VAL command will evaluate any legal operand expression, and print the value in hexadecimal. It may be used to quickly convert decimal numbers to hexadecimal, to determine the ASCII code for a character or to find the value of a label from the last assembled program.
EXAMPLE: VAL 'T $0054 00084 OK. VAL 3493 + $3493 $4238 16952 OK. VAL START + S12 $4200 16896 OK.
DOS commands:#
LOAD and SAVE commands:
These commands are used to store your source files onto Disk or Tape in the internal compressed form. This saves disk space and speed.
EXAMPLE: LOAd "D:GAME1.TXT" or SAVE "D:MISC.SRC"
BLOad and BSAve commands:
These commands are used to load and save BINARY files to disk.
NOTE: BLOad and BSAve function in the same manner as the L and K options in Atari DOS II.
EXAMPLE: BLOad "D:GAME.OBJ". (This will load the binary file called GAME.OBJ into memory at the address where it was saved.) BLOad "D:GAME.OBJ",$2000 (this will load GAME.OBJ starting at HEX 2000, not at the address where i t was saved.) EXAMPLE: BSAve "D:GAME.OBJ",$2000,$4000 (This saves a binary file called GAME.OBJ from Hex location $2000 to $4000.NOTE: the $ always must precede a hexadecimal number. SYMASSEMBLER assumes a decimal number if the $ sign is not present.
ENTer
This command allows you to enter ASCII text directly from tape or disk. It functions like the ENTER command in Atari BASIC. You can use this command to ENTER Atari assembler source files and then convert them to SYNASSEMBLER format.
EXAMPLE: ENTer "D:ATARIFIL.SRC" or ENTer"C:".
TYPe
The TYPE command is used to save your source to any device in full ASCII format.
EXAMPLE: TYPe "D:MYSOURCE.TXT" (This comand saves the full ASCII source under the MYSOURCE.TXT file, to disk drive 1) TYPe "P:" ... sends the source file to the printer.
DIRectory
The directory command is used to examine the contents of your diskettes.
EXAMPLE: DIR by itself will show you the catalog for disk drive 1 DIR "D:*.OBJ" will show anything in the catalog on drive 1 with an OBJ extender. DIR "D2:*.TXT" will show anything in the catalog on drive 2 with an OBJ extender.
DOS
The DOS command jumps from SYNASSEMBLER into the resident DOS in your system.
OUTput
The OUTput command is used to redirect the output of SYNASSEMBLER to another device; eg. printer, disk, screen etc.
EXAMPLE: OUT "P:"
After changing the output you may use the ASM command to send assembled listings to the device specified. To cancel the redirection simply type OUTput without a filespec.
EXAMPLE: OUTput.
ZYNAPSE MONITOR#
The ZYNAPSE monitor in SYNASSEMBLER allows you to examine, change, move, and verify memory. You may read and write to disk and cassette, dis-assemble machine-language programs; execute programs; perform hexadecimal arithmetic; read and write sectors directly to and from disk; and monitor program execution for debugging purposes.
MONITOR COMMANDS #
DISPLAY MEMORY: adrs1.adrs2 RETURN This command allows you to display the memory from address1 to address2.
EXAMPLE: 2000.4000 and [RETURN]
CHANGE MEMORY: adrs;data data .....
In order to change data at a particular address enter the address (in HEX of course), and then a semi-colon(;) after which you may enter as much data as you wish making sure that each byte is separated by exactly one space.
EXAMPLE: 2000;4C 00 9DAfter having entered an address, you may just use a semi-colon to indicate the next location for your next data entry.
EXAMPLE: 2000;4C ;00 ;9DThis example has the same effect as the previous example.
DIS-ASSEMBLING MEMORY: adrsL
This command allows you to dis-assemble 20 instructions starting at the specified address. By typing L again the next 20 instructions will be dis-assembled.
ADDITION AND SUBTRACTION (HEX): data+data or data-data
You may add or subtract data (in HEX) simply by entering data and pressing RETURN.
MOVING MEMORY: adrs1<adrs2.adrs3M
You may easily move data from one part memory to another. You first specify the address into which you wish to move, and then the range of memory that is to be moved.
EXAMPLE: 2000<3FF0.4000M
VERIFY MEMORY: adrs1<adrs2.adrs3V
If you wish to compare two blocks of memory, you can easily do so by specifying the starting address of the block you wish to compare and then the range that you wish it compared to.
EXAMPLE: 2000<3FF0.4000VDISK (READ and WRITE): adrs>sec1.sec2r (READ); adrs>sec1.sec2w (WRITE)
This unique feature of the ZYNAPSE monitor allows you to access the disk directly. The first parameter is the starting address of the buffer in which you wish to store the contents of the sec1 through sec2. Note:The READ and WRITE commands are lowercase. (CAUTION: BE EXTREMELY CAREFUL WHEN ACCESSING THE DISK DIRECTLY. YOU CAN EASILY OVERWRITE THE CONTENTS OF YOUR DISK.)
EXAMPLE: 2000<1.4r (reads sector 1 through 4 into buffer starting at 2000) 2000<1.4w (wites the contents of buffer starting at 2000 to sectors 1 through 4.)
RESTORING NORMAL MODE: N
This command tells the assembler to restore the original screen color and tab stops to the power-up specifications.
OTHER COMMANDS #
These commands are mainly used for execution and debugging assembly language programs.
EXECUTE: G
The G command is used to execute a program from the monitor, by typing the program address and the G command.
[*] Ok. 4000G
This will execute a program at 4000
EXAMINE and MODIFY registers: R
The R command allows you to examine and modify the 6502 registers (A,X,Y,P,S).
[*] Ok. R A=05 X=10 Y=50 P=30 S=F7They can now be modified with the ";" command
STEP and TRACE: S, T (see also DEBUGGING)
The S and T commands are for single stepping your assembly language program but the T repeats the S command indefinitely. The S command will execute one instruction:
[*] Ok 4000S 4000: A9 03 LDA #$03 A=03 X=00 Y=00 P=90 S=F0
At this point you may modify the register.
The T command will do the same thing as the S command except it will just repeat it forever. To get out of this mode, just tap the [BREAK] key.
QUIT: Q
The Q command will return you to the assembler.
Help File#
00010 * 00020 * SYNASSEMBLER DIRECTIVES 00030 * 00040 .AS ASCII STRING 00050 .AS "TEST" 00060 .AT ATASCII STRING 00070 .AT "SCORE:" 00080 .BS BLOCK STORAGE 00090 .BS 5 SKIPS 5 BYTES 00100 .DA WORD 00110 .DA HELLO 00120 .EN END OF SOURCE (OPTIONAL) 00130 .EN 00140 .EQ EQUATE 00150 TEST .EQ 5 00160 .HS HEX STRING 00170 .HS 0001AA5500339944344 00180 .IN INCLUDE FILE WITH ASM 00190 .IN "D:FILE NAME" 00200 .LI LIST ON OR OFF 00210 .LI OFF 00220 .OR SET ORG 00230 .OR $6000 00240 .TA SET TARGET FOR OBJECT 00250 .TA $9000 00260 .TF SEND OBJECT TO DISK 00270 .TF "D:FILE NAME" 00280 * 00290 * SYNASSEMBLER COMMAND 00300 * 00310 LOAD "D:FILE NAME" 00320 SAVE "D:FILE NAME" 00330 BLOAD "D:FILE NAME",<START> 00340 BSAVE "D:FILE NAME",<START>,<END> 00350 ENTER "D:FILE NAME" 00360 DIR DIRECTORY DRIVE 1 00370 DIR "D4:*.* DIRECTORY DRIVE 4 00380 DOS 00390 MEM MEMORY STATUS 00400 LIST L1,L2 00410 NEW 00420 REN L1,L2 00430 RENUMBER L1 USING INC OF L2 00440 REN L1,L2,L3 00450 RENUMBER L1 USING INC OF L2 00460 STARTING AT L3 00470 COPY L1,L2 00480 COPY L1 AT L2 00490 COPY L1,L2,L3 00500 COPY L1 TO L2 AT L3 00510 MOVE L1,L2 00520 MOVE L1 TO L2 00530 MOVE L1,L2,L3 00540 MOVE L1 TO L2 AT L3 00550 FIND STRING 00560 ASM 00570 DEL L1,L2 00580 HID 00590 HID CURRENT SOURCE PROGRAM 00600 MER 00610 COMBINE HIDDEN SOURCE WITH 00620 CURRENT SOURCE 00630 RUN EXPRESSION 00640 RESTORE 00650 RETURN FROM AN INCLUDE FILE 00660 OR TO UN-HIDE A HIDDEN FILE 00670 SYM 00680 PRINT SYMBOL TABLE 00690 VAL EXPRESSION 00700 REP /.BYTE/.HS/,P 00710 REPLACE WITH PROMPT 00720 PRESS 'Y' TO CHANGE 00730 PRESS 'N' FOR NO CHANGE 00740 PRESS 'X' TO CANCEL REPLACE 00750 REP /.BYTE/.HS/ 00760 REPLACE ALL 00770 OUT "P:" 00780 PRINT OUTPUT TO DEVICE 00790 TYPE "P:" 00800 LIST TO DEVICE 00810 LOMEM $4000 OR LOM $4000 00820 LOMEM OF SYMBOL TABLE 00830 HIMEM $8000 OR HIM $8000 00840 HIMEM OF SOURCE CAUTION 00850 DESTROYS SOURCE 00860 MON 00870 JUMP TO MONITOR 00880 Q 00890 JUMP BACK TO ASSEMBLER 00900 ************************ 00910 * MONITOR INSTRUCTIONS * 00920 ************************ 00930 EXAMINE MEMORY 00940 * 00950 adrs C0F2 00960 adrs1.adrs2 1024.1048 00970 (RETURN) DISPLAY NEXT 8 LOC 00980 .adrs .4096 00990 * 01000 CHANGE MEMORY 01010 * 01020 adrs;data data A256;EF 20 43 01030 ;data data data ;F0 A2 12 01040 * 01050 MOVE MEMORY 01060 * 01070 adrs1<adrs2.adrs3M 100<B010.B410M 01080 FROM adrs2 TO adrs3 STARTING AT adrs1 01090 * 01100 VERIFY MEMORY 01110 * 01120 adrs1<adrs2.adrs3V 100<B010.B410V 01130 * 01140 * READ SECTOR(S) 01150 * 01160 adrs<sec1.sec2r 2000<1.AFr 01170 READ SECTORS 1 TO AF 01180 AND PUT THEM INTO BUFFER 01190 AT 2000 01200 * 01210 * WRITE SECTOR(S) 01220 adrs<sec1.sec2w 2000<1.AFw 01230 WRITE SECTORS 1 TO AF 01240 AND GET THEM FROM BUFFER 01250 AT 2000 01260 * 01270 * 01280 adrsL C080L 01290 L NEXT 20 INSTRUCTIONS 01300 * 01310 DEBUGGING 01320 * 01330 adrsG 300G RUN 01340 adrsT 800T TRACE 01350 adrsS C050S SINGLE STEP 01360 R DISPLAY REGISTERS 01370 TO CHANGE REGISTERS 01380 TYPE ; THEN DATA 01390 FOR EACH ONE