RT-ASSEMBLER DOCUMENTATION ========================== 1. I n s t r u c t i o n l i s t Numeric instructions mov b a move b to a clr a move 0 to a (clear) inc a a = a + 1 (increment) dec a a = a - 1 (decrement) add a b a = a + b sub a b a = a - b mul a b a = a * b div a b a = a / b power a b a = b-th power of a root a b a = b-th root of a exp a a = a-th power of e exp10 a a = a-th power of 10 exp2 a a = a-th power of 2 expx a b a = a-th power of b log a natural logarithm of a (base e) log10 a common logarithm of a (base 10) log2 a binary logarithm of a (base 2) logx a b logarithm of a, base b sin a sin(a) cos a cos(a) tan a tan(a) cot a cot(a) sec a sec(a) = 1 / cos(a) csc a cosec(a) = 1 / sin(a) asin a b arcsin(a). If b=sign(cos(a)) full ±pi range acos a b arccos(a). If b=sign(sin(a)) full ±pi range atan a b arctan(a). If b=sign(cos(a)) full ±pi range acot a b arccot(a). If b=sign(sin(a)) full ±pi range asec a b arcsec(a). If b=sign(csc(a)) full ±pi range acsc a b arccosec(a). If b=sign(sec(a)) full ±pi range sinh a sinus hyperbolicus (a) cosh a cosinus hyperbolicus (a) tanh a tangens hyperbolicus (a) coth a cotangens hyperbolicus (a) sech a secans hyperbolicus (a) csch a cosecans hyperbolicus (a) asinh a area sinus hyperbolicus (a) acosh a area cosinus hyperbolicus (a) atanh a area tangens hyperbolicus (a) acoth a area cotangens hyperbolicus (a) asech a area secans hyperbolicus (a) acsch a area cosecans hyperbolicus (a) bin a if a<>0 then a=1, else 0 not a if a=0 then a=1, else 0 (negation) and a b if a<>0 then a=1 and b<>0, else 0 or a b if a<>0 then a=1 or b<>0, else 0 neg a switch the sign of a abs a absolute value of a sgn a signum of a (+1, 0 oder -1) round a round a ceil a give the smallest integer greather/equal a floor a give the greatest integer less/equal a fix a integer part of a (floor if a<0 and ceil if a>0, 0 if a=0) frac a fractional part of a clip a b c clip a into b ... c range cmod a b c clip a into b ... c by modulo (saw tooth) random a give a random number in 0 ... 1 range Branch instructions cmpgt a b m if a > b then jump to m („compare greather than“) cmpge a b m if a >= b then jump to m („compare greather equal“) cmplt a b m if a < b then jump to m („compare less than“) cmple a b m if a <= b then jump to m („compare less equal“) cmpeq a b m if a = b then jump to m („compare equal“) cmpne a b m if a <> b then jump to m („compare not equal“) tstgt a m if a >= 0 then jump to m („test greather than“) tstge a m if a > 0 then jump to m („test greather equal“) tstlt a m if a < 0 then jump to m („test less than“) tstle a m if a <= 0 then jump to m („test less equal“) tsteq a m if a = 0 then jump to m („test equal“) tstne a m if a <> 0 then jump to m („test not equal“) jump m jump to m (unconditionally) Input/output instructions input a s input of a number a with text s (with break) output a s output of a number a with text s (with break) pause s output of a message text s (with break) proof a s output of a number a with text s (no break) info s output of a message text s (no break) cls clear output text area printn a b c put number a into output text area (b/c digits before/after decimal point. b=0: variable length, c=0: integer output) prints s put text string s into output text area save s write output text area in file s read a b read a from data file a.dat. (b: number of symbols - 1) write a b write a into data file a.dat. (b: number of symbols - 1) Pointer instructions adrof p a give the adress of symbol a to pointer symbol p get a p q move the (p + q) pointed symbol to a put p q a move a to the (p + q) pointed symbol Control instructions init program initialization nop no operation. Does nothing mode a set mode a. 0: 'without stop', 1: 'stop on error', halt give a hard break on processor [2: 'stepwise' err a m move an error code to a, zeroes means no error. On error jump to m (former instructions errcode a, errjump m depreciated) exit program exit Pseudo instructions (Pseudo instructions were interpreted by assembler before running on processor.) _name s program name s _var a declare a variable a _dim a i declare an array a with the symbols a, a(0), a(1) ... a(i) _lab m define a label m. (Other notation: »m:«) _config i configure the processor with parameter i _end program end. (Marks the last line) (The letters mean operands: a, b, c, p, q numbers or variables how »2« or »x« i only numbers how »2«. A variable how »x« means 0. m labels, e. g. »l3« s strings, e. g. »Program«) 2. T h e P r o g r a m Each instruction is a text line. All instructions together are a source program. The line order is the instruction sequence on the processor. That's briefly all - mov a b ; move b to a div a 10 ; divide a by 10 sin a ; take the sine of a That program computes e. g. a=sin(b/10). Empty lines: A line can also be empty. Comment: Text after the semicolon »;« is comment. Line continuation: A »¶« sign (code Alt/182) at last in a line means that the next line continues it - without leading white spaces (spaces and tabulators). 3. O p e r a n d s Each instruction can have up to 3 operands - the RT virtual processor is a three-operand-processor. All operands were collected as symbols in a symbol table. There they have a SYMBOL NAME and a SYMBOL VALUE. The symbol name is the string from the source program. The symbol value in RT is a double float number storage cell. Also each symbol has a SYMBOL ADDRESS. That is its line number in the symbol table.A symbol is usable as variable, number, string or label. VARIABLES: Each symbol can store a numerical value. So a symbol name how a x1 alpha b11 but also ??9 (° 055$ or [PM343] is interpretable as a variable numerical value. NUMBERS: An as a numerical value interpretable symbol name will convert by the assembler and storaged at the symbol value before starting the program. Thus causes that the symbol names e. g. 1 2 +1.5 -3.3E6 -2.3E-2 become the symbol values 1, 2, 1.5, -3300000 -0.023. LABELS: Jump instructions needs a target. That are symbols with a program line (or code line) as symbol value. Such symbols were generated by the label instruction e. g. »_lab label1« or »label1:«. STRINGS: Some instructions needs as text string, e. g. as dialog text. In such cases RT uses the symbol name as string. In a string can (and must) be written a space as »~« and a line separator as »\«. Spaces are operand separators. Example: \Please~enter~the~latitude~in~degrees\\ But note: Variables, numbers, labels and strings are merely 4 several interpretations of a symbol. They are not different data types. The RT assembler doesn't know several data types. 4. P r e d e f i n e d V a r i a b l e s On starting a program the assembler generates some pre-defined symbols automatically: . Empty symbol. In each case zero. .. Instruction pointer. Pointes the actual processed code line. e Leonhard Eulers number e pi Pi pi/2 1/2 Pi pi/4 1/4 Pi ® Earth radius on equator in meters (code ® Alt/0174) ®f Earth flattening (Polar radius is ®-®f*®) º( Degree-into-arc factor. (code ° Alt/0176) (º Arc-into-degree factor eps The smallest number > 0 max The greatest number r0 ... r7 8 common usable registers x y Given coordinate - to transform (input value) x' y' Searched = transformed coordinate (output value) z unused z' unused Rx Ry Earth equator radius in source image geo coordinate units X/Y Rx' Ry' Earth equator radius in target image geo coordinate units X/Y Cx Cy Source image centre in geo coordinates X/Y Cx' Cy' Target image centre in geo coordinates X/Y 5. I n p u t a n d O u t p u t RT knows 3 input/output devices: dialog, a global output text area and data files: DIALOG: The input and output instruction allows the input and output of a symbol value by dialog. Other instructions of this group are pause, proof and info. OUTPUT TEXT AREA. That is a simple string buffer. The instructions printn and prints can write (»print«) numbers and text strings into it. The cls instruction clears the area and the save instruction writes the (internal) area to a (external) text file *.txt. DATA FILES: The instructions read and write allows the transfer of numeric values between symbols and data files *.dat. The 2nd operand of this instructions gives the transfered number of values dimished by 1. By default it is 0 (empty value) and it will be readen/written 1 symbol. Lengths > 0 can instruct array transfers (but also other parts of the symbol table.) 6. A r r a y s a n d P o i n t e r Arrays The »_dim X 5« instruction defines firstly a ordinary symbol X, but following 6 further symbols, named X(0), X(1), X(2), X(3), X(4), and X(5). That are the array elements. At last it writes on symbol X the address of symbol X(0). So symbol X becomes a pointer at the first array element X(0), briefly - a array pointer. Pointer access The put and get instruction realizes the pointer access. Here a symbol is not given by its name but by its address. They have 2 operands, p (»pointes«)and q (»offset») which give in sum the target symbol address. On that kind the »get v X i« instruction reads array element No. i of array X to variable v. The instruction »put B j 22« writes a number 22 on the j-th element of array B. Pointer access isn't restricted to array access. Also all symbols are accessable by pointer access. Then the symbol address is detectable by the adrof instruction. If the offset q isn't needed it can be displaced by the empty symbol ».«. By means of _dim, put, get and adrof it is possible to realize data structures how stacks, vectors, matrices, tables, lists and others. The read and write instruction and arrays The read and write instructions 2nd operand - the length parameter - allows the transfer of arrays in data files and return. Note: an array X with the last element index {n} must be · defined by »_dim X {n}« · written and readen by »write X {n+1}« and »read X {n+1}«. · Its length in the symbol tabel is {n+2}: array pointer, X(0) and X(1) to X(n)), · Also its length in a data file is {n+2} lines. The first line in a array data file is the array pointer. But it has after writing a non-interesting value. Important: After reading from file into symbol table it is necessary to reconstruct the array pointer! To do that, allocate immediate post a array read instruction a adrof instruction »on the zero element«: »adrof a a(o)«: read X 6 ; read 7 symbols from file f.dat into X, X(0) ... X(5) adrof X X(0) ; move the X(0) address to the array pointer X Take care Assembler typically has no pointer evaluation, also the RT assembler. Illegal pointers can destroy the whole memory - in case of RT the whole symbol table. To avoid it take care that: · he array is correctly declared by _dim. · the _dim-length must be an number - not a variable. · the puts were done with correct pointers and offsets. · Don't write a array with a too small length. Correct: array length+1 · Don't read in a array with a too large length. Correct: array length+1 · Don't forget the adrof instruction past a read instruction into an array. 7. R u n n i n g a n d D e b u g g i n g There are 3 modi to run a RT program: 0 = run 'without stop', 1 = run with 'stop on error' and 2 = 'stepwise'. The mode is selectable by operator or by the mode instruction. Then RT knows two flags to control the programs run. First the Halt flag generates a program break at the current instruction »on the machine«. It can setted by debugger user interface or by halt instruction. Second the Abort flag causes the immediately program abort. It also can be setted by the debugger user interface or by Vimages Z-Interrupt (Ctrl/Z entering). 8. N o t i c e s Numbers: Alle symbol values have the internal data type double float, but the highest absolute value is 1E99. Symbol names: In a symbol name is each ASCII, ANSI or UTF-8 character allowed, exceptly the semicolon - the comment introducer. RT is case sensitive: »AA«, »Aa and »aa« are differnent symbols. Also note that the brackets have a special meaning as array element separators. File names: In the file names of the read, write and save instruction are only lowercase letters, digits and the characters _, $, ( and ) allowed. Other characters were converted into the underscore »_«. Uppercase letters were changed into lowercase letters. The empty symbol: The empty symbol ».« replaces automatically missing operands. Its value always is 0. That ist in the most cases a useful default. Writing on symbols: The ».« and »..« are write protected. All other symbols are writable. You can write by »move 10 2« instruction the value 2 on the symbol with the name »10«. A immediately following »mul X 10« only doubles the X. It isn't a multiplication by ten! But note: That is not a fine programming style. Not declaration necessity: The assembler enteres symbols automatically, it is no declaration required. But a declaration by _val instruction is a better programming style (except small programs). So the symbol table is better readable and typing error caused double defined symbols so came at the symbol tables end - where they are easyly detectable. 4.1.270 instruction issue: - full +/- pi range of asic/acos/atan/acot/asec/acsc by means of b-operand. - more precise printn definition. b=0: variable length, c=0: integer conversion. - err instruction units (now depreciated) errcode and errjump instruction. 9. E r r o r c o d e s 101: OVR Overflow. Absolute value > 9E99 102: DB0 Division by 0 103: PZZ O-th power of 0 104: ILP Power of negative number and fraction exponent either not-one-enumerator - or even-denominator 105: ILR Root of negative number and exponent either even - or fraction with not-one-enumerator 106: RXZ Root exponent 0 107: LNN Logarithm numerus negative 108: LNZ Logarithm numerus 0 109: LBN Logarithm base negative 110: LBZ Logarithm base 0 111: LBI Logarithm base 1 112: FOR Function out of range 113: IOE File I/O error 114: [not used] 115: [not used] 116: UIC Unknown instruction code 117: USN Undefined symbol name 118: SAD Symbol already defined 119: STF Symbol table full 120: SNO Symbol name overlength > 1024 121: [not uesd]