GPL ASSEMLER V2.1 C 1985 Weiand *************************** GPL ASSEMBLER MANUAL ******************************* PROGRAM DESCRIPTION: GPL ASSEMBLER Version 2.1 Copyright 1985 by Michael Weiand PURPOSE: Assembling of GPL Programs The program ASSM1, ASSM2, and ASSM3 are the GPL ASSEMBLER program that reads Display/Variable 80 file for input from disk which have been created by means of any editor program, for instance the EDIT1 program of the Editor Assembler (named E/A later from now on) package. Source files are translated into a list file and object file. The DIS/ VAR 80 list file will contain all necessary information for documentation of your GPL program, like source code, generated object code, symbol table and error messages. The list file resembles very much that created by the Editor Assembler. The object file (output file) is a tagged object code, DIS/FIX 80 file like the object files created by the E/A, but will contain only absolute data. Relocatable code as well as REFs/DEFs/Entries cannot be generated. This is due to the fact that GPL Loaders will not be able to use these features. The object files will later on have to be LOADed by means of a special loader into EPROMs or GRAMs. The loader is not part of this package. (*NOTE: GPL*LOADER is on the same disk.) HARDWARE AND SOFTWARE REQUIREMENTS; TI-99/4A console with E/A command module. This implies the need for a memory expansion and at least one disk drive. A printer together with its peripheral (RS232/PIO) is strongly recommended. OPERATING INSTRUCTIONS: Copy the EDIT1 program of your E/A package to the GPL disk. Then insert the disk labelled GPL-ASSM into drive 1 (instead of the E/A PARTA disk) and plug in the E/A cartirdge. The module with behave normally in all aspects. When you select the option 2 ASSEMBLE the new GPL Assembler will be loaded. The questions concering files are answered as usual, but there is a slight difference for the Options question. C = Generation of compressed object code, otherwise not compressed. (Source Command = COMP) L = Generation of a list file, otherwise no list file. (Source Command = LIST or UNL is no list) Sn = Generation of 'n' symbol tables, otherwise no symbol tables. (Source Command = SYMB) Pn = Maximum number of assembler passes 'n', otherwise n=4 (Source Command = PASS) In the above codes 'n' is a one digit hexadecimal number ranging from 0 to F (Hexadecimal F = 15 decimal). . GPL SOURCE CODE: The GPL source code is of course different from the TSM9900 machine language. The E/A manual will insofar be of little use, although it is important for an overveiw and description of the TI-99/4A architecture. For a description of the GPL language please refer to special books, for instance the German booklet 'TI-99/4A Intern' by H. Martin (1985, published by 'Verlag fuer Technik und Handwerk', Baden-Baden, Germany). The following tables are only ment as an overview of GPL commands and GPL syntax. This is not sufficient for writing GPL programs. SYNTAX: ,... : unique name up to 32 characters e.g. POINTER : xxx = 4 significant characters as given in the following table, e.g. ADD or for 'Double' Opcodes: Dxxx = 5 significant characters including 'D' e.g. DADD an must not start in column 1! : Syntax depends on , but can also be void. excess are ignored. If any field - also the - field - begins with an asterisk '*' the rest of the line is treated as a comment. Possible formats: : Text in single quotes, e.g. 'abcdefg' For a quote, insert two quotes! e.g. 'Sam''s' ------------------------------------------------------------------ : which represents a valid filename e.g. 'DSK1.TEST-COPY' ------------------------------------------------------------------ : a value consisting of (NUMBER)s, (SYMBOL)s and (OPER)ators: e.g. POINTER+1 : integer value, e.g. 13 : Hexadecimal value, e.g. >AA01 : Binary value, e.g. &10100101 : name like , e.g. POINTER : % = current GROM base address (e.g. >6000) : $ = current address in the GROM (Source Command = AORG) : + = Plus : - = Minus : * = Multiply : / = Interger Division : | = Modulo NOTE: Brackets are not allowed! No operator precedence, but strict left-to-right calculation. e.g. 1+3*4 gives 16! . ------------------------------------------------------------------ : like , but the result must be within >8300 to >83FF (Scratchpad RAM addresses) ------------------------------------------------------------------ / : Source / Drain ("General address"="gas") can be one of the following forms, indicating the type of memory (RAM/ROM, VDP and GROM) and address mode (direct, indexed, indirect) ------------------------------------------------------------------ IMM : Immediate value (Source Command = ) NOTE: ONLY VALID IN = Source !!! @IMM : direct RAM/ROM, e.g. CLR @>8300 *IMM : indirect to/from RAM/ROM into RAM/ROM e.g. CZ *FAC (the value from FAC is read as an address in RAM/ROM where the value is read) V@IMM : VDP direct, e.g. V@0 V*IMM : VDP indirect by RAM/ROM, e.g. V*PABPTR (the value from PABPTR in RAM/ROM is read as an address in VDP) @IMM(@SP) : direct in RAM/ROM, indexed by a scratchpad value e.g. @>0001(@FAC) (the value at FAC is read, >0001 is added and the result is an address in RAM/ROM) *IMM(@SP) : indirect in RAM/ROM, indexed by a scratchpad value e.g. *>0001(@FAC) (like above, but the result is an address in RAM/ROM where the final address is fetched.) V@IMM(@SP) : like @IMM(@SP), but the result is in VDP memory! V*IMM(@SP) : like *IMM(@SP), but the result is in VDP memory! ------------------------------------------------------------------ : the MOVE command accepts as source data the value and the following: G@IMM : direct GROM/GRAM e.g. G@>6000 G@IMM(@SP) : like @IMM(@SP), but the result is in GROM memory! ------------------------------------------------------------------ : the MOVE drain data is similar to , but permits VDP registers as well: #IMM : VDP register direct (number IMM = 0 to 7) e.g. #7 . ******************************************************************************** GPL COMMANDS IN ALPHABETICAL ORDER ******************************************************************************** NOTE: (D) means: the command is available as 'word' or 'Double' command. Otherwise bytes are accessed. e.g. ADD 1,@FAC adds a byte value to @FAC DADD 1,@FAC adds a word value to @FAC,@FAC+1 (D)ABS (D)ADD , ALL (D)AND , B * IMM is a GROM address BACK BR * IMM is a GROM address in the current GROM BS * IMM is a GROM address in the current GROM CALL * IMM is a GROM address CARRY (D)CASE (D)CEQ , (D)CGE , (D)CGT , (D)CH , (D)CHE , (D)CLOG , (D)CLR COINC , COL * FMT command COL+ * FMT command CONT (D)CZ (D)DEC (D)DECT (D)DIV , EX , EXEC EXIT FEND * FMT command FETCH FOR * FMT command FMT GT HCHA , * FMT command HOME * = DCLR @YPT HSTR , * FMT command HTEX / * FMT command (D)INC (D)INCT . I/O , (D)INV MOVE ,, (D)MUL , (D)NEG (D)OR , OVF PARSE POP PUSH RAND ROW * FMT command ROW+ * FMT command RTN RTNB RTNC RTGR SCAN SCRO * FMT command (D)SLL , (D)SRA , (D)SRC , (D)SRL , (D)ST , (D)SUB , SWGR , VCHA , * FMT command VTEX / * FMT command XML (D)XOR , PSEUDO COMMANDS: BYTE ,,... COMP COPY DATA ,,... END EQU IDT LENG LIST OBJE OFFS PAGE PASS STRI SYMB TEXT TITL UNL VAR . ******************************************************************************** FMT COMMANDS: Some GPL commands are applicable only within the 'formatted display'. This mode is entered with the FMT command. FEND, if not used for finishing a FOR command, will switch to 'normal' GPL mode again. Normal commands are not allowed within the FMT block! NOTE: is an value of 1 to 32 COL * Column COL+ * advance column by FEND * finishes FMT, if no FOR loop is present. FOR * repeats the following commands up to * FEND times. HCHA , * display CHAR(IMM) times * horizonally. HSTR , * display string of length , which * is stored at address HTEX * display horizontally maximum * length is 32 characters. ROW * row ROW+ * advance row by SCRO * get new screen offset at VCHA , * display CHAR(IMM) times vertically. VTEX * display vertically maximum * length is 32 characters. VTEX ,,... * display CHAR(IMM) >>> vertically. EXAMPLE OF AN FMT COMMAND BLOCK: FMT * Start FMT FOR 3 * Repeat 3 times. HTEX 'HELLO' * display 'HELLO' horizontally. ROW+ 2 * advance row by 2 FEND * finish FOR loop FEND * finish FMT Another example is file TEST-COPY on GPL ASSM disk. . ******************************************************************************** PSEUDO COMMANDS ******************************************************************************** The following assembler commands will create data structures, not executable GPL code: BYTE ,,... * (Maximum 16 values) * stores values as bytes. * e.g. BYTE 1,2,3,4,5 DATA ,,... * like BYTE, but words are stored. * e.g. DATA >AA01,0,0,POINTER TEXT * stores of ASCII values. * e.g. TEXT 'ASSEMBLER' STRI * like TEXT, but the generated code will * be preceded by the length byte. * e.g. STRI 'GPL HELP' A symbol value can be assigned not only by giving it the address value of the instruction which it precedes. The following statements will assign constants to any : SYMBOL1 EQU e.g. ID EQU >AA01 SYMBOL2 EQU e.g. BLANK EQU ' ' SYMBOL3 VAR e.g. STEP VAR 2 SYMBOL4 VAR e.g. STEP VAR '0' SYMBOL1 will get the value of . SYMBOL2 will be assigned the value of the first two bytes of or of >00xx if the string length is 1. SYMBOL3 is the same as SYMBOL1, but the VAR statement disables error messages for 'Multiple Symbols' and 'New Symbol value'. Thus you can assign different values to a symbol which is important if you want to use them as input or output variables from 'Macro' type COPY files. Be cautious using recursive values since these may result in unstable values which will cause the assembler to retry endlessly. e.g. : START EQU START+1 (!!!) This condition can be avoided using the PASS pseudo command or the P option of the assembler. . ******************************************************************************** CONTROL OF ASSEMBLER OPERATION ******************************************************************************** INPUT FILE COPY * Insert file into the source code. Be * cautious not to create loops! END * Stop assembly of source code. PASS * New value for the maximum pass count. * Default value = 4 --------> * This command overrides the assembler option P * with the same meaning! OUTPUT FILE COMP * If is 0, the object code is 'not * compressed', else compressed. * Default = compressed. --------> * This command overrides the assembler option C * with the same meamning! OBJE * Open new object file --------> * This command overrides the assembler * input 'OBJECT FILE' ! OFFS * is a 'load offset' value i.e. the * generated addresses are offset from the * calculated values by * This can be used by special loaders. * Default = 0 IDT * is a new ID field within the object * file. Default = 'GPL ASSM' LIST FILE LIST '' * (Re)starts list file generation same meaning * as the 'L' option. LIST * Open new list file and start list file * generation. --------> * This command overrides the assembler input * 'LIST FILE' ! LENG * is the lines/page value. * Default = 66 PAGE * Generate page break. SYMB * Indicate symbol tables to be generated the * value is coded bit by bit * i.e. the following values have to be added for * each table desired: * 1 = new symbols, in alphabetical order. * 2 = new symbols, sorted by value. * 4 = predefined symbols, in alphabetical order. * 8 = predefined symbols, sorted by value. --------> * This command overrides the assembler option 'S' * with the same meaning! TITL * is the new listing header line. UNL * Stop list file generation. --------> * This command overrides the assembler 'L' option. . ******************************************************************************** ASSEMBLER PRINCIPLES ******************************************************************************** The GPL ASSEMBLER had to be designed to cope with varying code length depending on the symbol values. This means that addresses can change from pass to pass, making a 2 pass assembly impossible. Therefore an 'endless pass' assembler had to be written which will stop assembly only if no more changes in the symbol values are encountered. The last pass will generate object and list files. Any error is therefore classified as follows: - Warnings (no influence on generated code) - Retry (may be better next time) - Fatal (no meaningful code will be generated) During each pass the following information is displayed: - Pass number and current error state (correct, retry, aborted) < Current Input and Copy file(s) > Current Output file(s) - Error messages together with the row number in the current input or copy file (restarts with 1 in each copy file!) The list of error messages is given below. - Total error state in case of aborted assembly. The messages are only informative till the last pass. You don't have to note all messages passing by for the first passes! List file generation is postponed till the last pass. An object file(s) 1 will also be generated in this pass if the error state is 'correct'. EXAMPLE On the GPL ASSEMBLER disk you will find a working example for a command module type GPL program. The files TEST-INPUT and TEST-COPY are accessed in the following way: INPUT FILE: DSK1.TEST-INPUT OBJECT FILE: DSK1.TEST-OUTPT LIST FILE: DSK1.TEST-LIST OPTIONS: L C S5 P4 NOTE: the input file TEST-INPUT will COPY the file TEST-COPY twice. You can of course use other filenames, like PIO for the list file, if you wish to. . ******************************************************************************** ERORR MESSAGES ******************************************************************************** ADDRESS ERROR (Fatal) Invalid address syntax ADDRESS MODE ERROR (Fatal) Invalid address mode (not allowed for this command) ADDRESS NOT EVEN (Warning) Warning: an uneven load address has been generated. COPY IGNORED (Warning) The COMP command cannot change the COMP mode of an object file when data have been written to it. COPY FILE ERROR (Fatal) Any file error on the COPY file. DEFAULT CHANGED (Warning) Warning: the value of a predefined symbol has been altered, see predefined symbols. FATAL ERROR (Fatal) Error state which means 'abort assemblation' FILE ERROR (Fatal) Any input file error. FMT MISSING (Fatal) You have used FMT commands without previous FMT. FMT NOT COMPLETE (Fatal) You have used normal commands within FMT. FORMAT ERROR (Fatal) Address mode error within FMT. "gas" ERROR (Fatal) General error in / data ("gerenal address") INVALID LABEL (Warning) A label syntax is incorrect. INVALID MNEMONIC (Fatal) A command could not be recongnized. INVALID NUMERIC (Fatal) A number could not be decoded. MULTIPLE SYMBOLS (Fatal) You tried to redefine a symbol. NEW SYMBOL VALUE (Retry) A symbol value has changed since the last pass. NO OBJECT FILE (Warning) Warning: there is no object file for your data. OBJECT FILE ERROR (Fatal) Any file error on the object file. OUT OF RANGE (Fatal) A value is out of range (in mose cases ) PARAMETER ERROR (Warning) Missing parameter = data PRINT FILE ERROR (Warning) Any list file error. STRING ERROR (Fatal) Invalid string syntax (missing ') SYMBOL TABLE FULL (Fatal) No more room for new symbols. SYNTAX ERROR (Fatal) Any other syntax error. TOO MANY ! (FMT) (Fatal) Wrong value. TOO MANY PASSES (Fatal) The maximum number of passes has been exceeded. UNDEFINED SYMBOL (Fatal) You referenced an undefined symbol. . ******************************************************************************** PREDEFINED SYMBOLS ******************************************************************************** Symbol Table #4 (Def,alpha) 0034 ACCTON 835C ARG 0032 ATN 0036 BADTON 003B BITREV 0012 CFI 0014 CNS 002C COS 0010 CSN 8372 DATSTK 0001 DIVZER 0003 ERRIOV 0006 ERRLOG 0005 ERRNIP 0002 ERRSNN 0004 ERRSQR 0028 EXP 834A FAC 0006 FADD 000A FCOMP 0009 FDIV 0008 FMUL 836C FPERAD 0007 FSUB 0038 GETSPACE 0022 INT 0010 LINK 0018 LOCASE 002A LOG 8370 MEMSIZ 003D NAMLNK 8300 PAD 0024 PWR 0012 RETURN 000B SADD 000F SCOMP 000E SDIV 8375 SGN 002E SIN 000D SMUL 8400 SOUND 0026 SQR 000C SSUB 837C STATUS 0016 STCASE 8373 SUBSTK 0030 TAN 0007 TRIGER 004A UPCASE 836E VSPTR 0001 WRNOV 837F XPT 837E YPT