CP/M

home *** CD-ROM | disk | FTP | other *** search

/ CP/M / CPM_CDROM.iso / beehive / program / xasm.arc / XASM68.HLP < prev next >

Wrap

Text File | 1990-08-26 | 20.3 KB | 563 lines

Introduction to XASM68.COM Running the Cross-Assembler Source file syntax Pseudo-Operations Errors Listing format Error messages Object file format Known bugs :XASM6╕ i≤ ß cross-assemble≥ designeΣ t∩ ruε oε an∙ CP/═ 8░ ì machine«á I⌠ generate≤ codσ fo≥ thσ Motorolß 6800¼ 6802¼ ì anΣá 680╕ famil∙ oµ microprocessor≤ anΣ thσ 6801¼á 680│ famil∙ oµ ì microprocessors¼á acceptinτ standarΣ Motorolß mnemonic≤á anΣ ì syntax. XASM68 assembles instructions for both groups, and has provisions for flagging instructions not available in a specified target machine. XASM68 accepts its input from a CP/M text file, and generates as output an object code file, an assembly listing, and an alphabetized listing of all symbols defined in the assembly. The object file may be in Intel HEX format or Motorola S1 format or may be omitted altogether, at the user's discretion. The listings are normally sent to the system's LIST device, but may be directed to the console or to a disk file. :Invoking the 6800 cross-assembler. XASM68 {d:}filename{.ext} {d:} {switches} Where the d:'s are optional drive specifiers, the filename extension is optional and if omitted defaults to .ASM. The second drive name specifies the destination of any output from the cross-assembler if omitted the output files will be placed on the default drive. The switches are (optional) single characters which control the output of the assmbler, as described below. XASM68 Switches The switches following the filename, if supplied, control various options as follows: C Send listing, if any, to console instead of LST: D Send listing, if any, to disk file with same name as source file but with an extension of `.PRN'. K Generate object code in Motorola S1 format rather than Intel he°á format¼á thσá objec⌠á filσá tha⌠ i≤á generateΣá ha≤á aε ì extension of `.MIK'. L Listing only; i.e. no object file. O Object only; equivalent to XY X No assembly listing. Y No symbol-table listing Any combination of the switches may be used to achive a desired output. Clarification ------------- Whilσ thi≤ ma∙ bσ misseΣ oε ß cursor∙ readinτ oµ thσ manual¼á thσ ì defaul⌠ destinatioε fo≥ thσ assembl∙ listinτ i≤ thσ PRINTER«á Iµ ì thσ printe≥ i≤ no⌠ ready¼ o≥ n∩ printe≥ i≤ present¼ thσ assemble≥ ì wil∞ appea≥ t∩ "hanτ up"«á Notσ tha⌠ line≤ containinτ error≤ arσ ì alway≤á listed¼á eveεá iµá thσá "Oó o≥á "Xóá switche≤á havσá beeε ì specified. Listing output can be diverted to the console or to a PRN file by using the "C" and "D" switches, respectively, in the command line. :Syntax of Assembler Source Files Statements Source files consist of a sequence of statements of one of the forms: {label:} operator {arguments} {;comment} symbol operator {arguments} {;comment} {;comment} If a label or a leading symbol is present, it must begin in column 1. Labels must be followed by a colon. Blank lines are treated as comments. Elements of a statement may be separated by blanks or tabs. Symbols Symbols may be up to 8 characters in length, and may include any of the following characters: A..Z 0..9 $ . The first character of a symbol must be a letter or a period. Numeric Constants Numeric constants consist of a sequence of digits, optionally preceeded or followed by a radix specifier. The first character must be either a leading radix specifier or a decimal number (0..9). The default radix is ten. For compatibility with existing assemblers, other bases may be denoted by either a leading or a trailing specifier. The radix specifiers are: % (binary) @ (octal) $ (hex) The trailing specifiers are: B (binary) Q (octal) H (hex) Character Constants Character constants may be used whenever a numeric value is allowed. A character constant consists of one or two characters enclosed in single or double quotes (' or "). The single quote may be used as a character between double quotes, and vice-versa. Thus, the following are equivalent: 'A' "A" and 41H 'AB' "AB" and 4142H Location-Counter Reference The character "$" may be usd as an element in expressions. Its value is the value of the location counter at the beginning of the current statement. Expressions Arithmetic expressions are composed of symbols, numeric constants, character constants, and operators. All operators execpt +, -, *, and / must be separated from thier operands by at least one space. Symbols which are operators are reserved, and may not be redefined as user symbols. Arithmetic Operators These treat their operands as 16-bit unsigned quantities, and return 16-bit results. No overflow checking is performed. + and - Sum and Difference. Operands and results may be thought of as unsigned or as twos-complement quantities. unary + +x is defined as 0+x unary - -x is defined as 0-x * / Product and Quotient (unsigned) MOD Remainder; x MOD y gives the remainder of x/y Shift Operators SHL Binary left shift. x SHL y yields x shifted left y places (ie. x multiplied by 2**y). SHR Binary right shift, logical. x SHR y yields x shifted right y places (ie. x multiplied by 2**y). The direction of shift is reversed if the argument is negative. Byte-Extraction Operators HIGH Returns the value of the most significant byte of its argument. LOW Returns the value of the least significant byte of its argument. These are unary operators, taking an argument on the right. For example: HIGH 1122H is 11H, and LOW 1122H is 22H. Boolean Operators NOT Unary logical negation. Complements all the bits in its argument. AND Logical product; ie. each bit of the result is obtained by ANDing together the corresponding bit in the arguments. OR Logical sum. XOR Exclusive-OR. These are all bitwise operators; that is, the same operation is performed on each operand bit position, with no carry from one bit position to the next. For example: NOT 0 is 0FFFFH 101B AND 010B is 101B OR 010B is 111B 101B XOR 010B is 111B 101B XOR 100B is 001B Relational Operators These perform unsigned 16-bit comparison of their operands, returning 1 for TRUE and 0 for FALSE. For comparison x R y, where R is a relational operator, the results are as follows: EQ TRUE iff x and y are equal NE TRUE iff x and y are not equal LE TRUE iff x is less than or equal to y LT TRUE iff x is strictly less than y GE TRUE iff x is greater than or equal to y GT TRUE iff x is strictly greater than y Evaluation of Expressions Parentheses may be used to specify the order of evaluation of subexpressions. In the absence of parentheses, this order is determined by operator precedence; higher-precedence operators are evaluated first. In the case of operators with equal precedence, evaluation proceeds from left to right. The operators are lited below in groups according to precedence. Operators in the same horizontal group have the same precedence: unary +, unary - (Highest precedence) HIGH LOW * / MOD SHR SHL + - EQ NE LT LE GT GE NOT AND OR XOR (Lowest precedence) :Pseudo-Operations Storage Definition DB arg{,arg...} Define bytes. Each arg may be either an expression or a string. Expressions must evaluate to 8-bit values (high byte either 0 or 255). Strings may be delimited by single or double quotes, as for character constants. Fo≥á eacΦá expression¼á ßá singlσ bytσ oµá storagσá i≤ ì reserved¼á initializeΣ t∩ thσ lo≈ bytσ oµ thσá expression'≤ ì value« Fo≥ eacΦ string¼ thσ character≤ oµ thσ strinτ arσ ì storeΣ iε sequentia∞ reserveΣ bytes. If a compound expression beginning with a character constant is used in a DB, then the expression must be enclosed in parentheses to keep it from being incorrectly parsed as a string. For example, DB ('A'+1) will give the expected result, while DB 'A'+1 would be in error. DW expression{,expression} Each expression reserves one word (2 bytes), initialized to the value of the expression. The value is placed in memory with the high-order byte first. DS expression Reserves n bytes, where n is the value of the expression. The bytes are not initialized. ORG and END ORG expression Set program origin. This should precede the first code- generating statement in the souce file. It sets the program counter initial value to the value of the expression, thus setting the location of code which follows. Additional ORG statements which will load at different locations. END {expression} The last statement of the source file must be an END statement. An optional argument is allowed; if this is supplied, its value becomes the start address specified in the last record of the HEX object file. Symbol Definition EQU and SET These take the form: symbol EQU expression symbol SET expression They cause the symbol to be defined and given the value of the argument expresson. Symbols defined with EQU serve as symbolic constants, and may not have their values changed. Symbols defined with SET are treated as variables; their values may be changed by additional SET's Conditional Assembly IF, ELSE, and ENDIF The construct IF expression statement . . . ENDIF causes the first sequence of statements to be processed if the expression is TRUE (non-zero), and the second sequence to be processed otherwise. Conditionals may be nested to a depth of 10. The value of the expression if the IF statement must be known in Pass 1. Machine Type MOD00 Thi≤á cross-assemble≥á default≤á t∩ assemblinτá al∞á 6800/0▒ ì mneumonic≤á withou⌠ erro≥ howeve≥ iµ thσ pseudo-o≡ MOD0░á i≤ ì placeΣá iεá thσ sourcσ codσ al∞ 6800/0▒ mneumonic≤á wil∞á bσ ì assembleΣ bu⌠ bu⌠ mneumonic≤ uniquσ t∩ thσ 680▒ wil∞ causσ ß ì W error to be flagged. Listing Control PAGE {expression} If the argument is omitted, then this causes an immediate page eject (ie. a skip to the top of the next page). If an argument is supplied occurs only if there are less than n lines remaining on the current page. WIDTH expression Sets the assumed width of the listing page. The value of the argument may be between 32 and 132, and defaults to 132. PGLEN expression Sets the number of lines which will be printed on each page of the listing. Note that the page heading takes up 7 of these lines. The value of the argument may be between 8 and 255, and defaults to 58. TITLE dtextd Cause the specified text to become the listing page title, beginning with the next page header printed. The delimiter d may be any printing character. If no TITLE statement is used, then XASM68 supplies a default title consisting of the text "SOURCE FILE NAME: " followed by the name and extension of the input file. SBTTL dtextd Just like TITLE, but sets the listing page subtitle, which is printed on the line after the title line. LIST and NOLIST These allowselective listing of portions of a program. NOLIST turns off the assembly listing, and LIST turns it back on. If listing has bee turned off with NOLIST, then the next LIST encountered will begin a new page. Commnd-line switches which disable listing (ie. X and O) will take precedence over LIST. NOLIST does not turn off listing of the symbol table. External Source File INCLUD d:name.ext This pseudo-op causes the specified file to be included as if it were present at this point in the source file. INCLUD's may not be nested; that is, the file read by INCLUD may not contain another INCLUD statement. The file must end with an END statement. Operator Synonyms The Statement symbol OPSYN operator causes the given symbol to be defined as a synonym for the operator or pseudo-op specified as argument. This is particularly useful when assembling source file written for another assembler. For example, if a program uses .BYTE instead of DB, it could be correctly assembled by including the statement .BYTE OPSYN DB :Errors Fatal errors result in the printing of an error message on the console and immediate return to CP/M. Fatal errors may be caused by missing source files, inadequate disk space for output files, or overflow of the symbol table or various stacks. Non-fatal errors are flagged with a character in the first column of the assembly listing. Lines containing errors are always listed, even if listing is turned off. A count is maintained of lines containing errors; if the count is non-zero at the end of the assembly, it is printed on the console in the message: ***** nnn LINES CONTAINED ERRORS ***** Only one error is listed per line; hence, if a line contains multiple errors some may not be caught until successive assembler runs«á Thσá fata∞ erro≥ message≤ anΣ non-fata∞ erro≥á flag≤á arσ ì described later. :Format of Listings Page Headings All listings begin with a heading consisting of seven lines: (blank line) (blank line) (assembler name and version) (blank line) (title and page number) (subtitle) (blank line) If no title is supplied in the source program, then the assembler provides a default title consisting of the message SOURCE FILE NAME: followed by the name of the input file in the form name.ext. The page number is listed at the right-hand end of this same line, always within the specified page width. If no subtitle is supplied, the subtitle line is left blank. Both title and subtitle will be truncated, if necessary, to satisfy page width constraints. Line Headings Each code-generating line of the listin begins with the error flag (blank if no error) and the 4-digit hexadecimal value of the location counter as of the start of the line. This is followed by up to four bytes of generated code, also in hexadecimal with two digits per byte. Statements which generate more than 4 bytes will be assembled correctly, but only the first four bytes will be listed. Lines which do not generate code but which evaluate an operand (such as EQU or WIDTH) list the operand value in their headers, in place of the location counter. Symbol-Table Listing The symbol-table listing shows all symbols defined in the current assembly, with their hexadecimal values. Only user-defined symbols are listed. Symbols are in vertical columns, sorted alphabetically according to the ASCII collating sequence. The number of columns is adjusted automatically to fit in the specified page width. All pages of the symbol-table listing are automatically subtitled. ---- SYMBOL TABLE ---- Because the sorting scheme used is strictly lexicographic, the way it orders numbers may be counterintuitive. A typical sequence of labels might be listed as follows: SYM19, SYM2, SYM20, SYM21, SYM3, SYM4 :Error Messages and Flags Non-Fatal Error Flags C Conditional Err Unmatched IF, ELSE, or, ENDIF; or conditionals nested too deeply. I Includ Err File not found, or nested INCLUD's. L Label Err Label too long. (>8 characters) M Multipule Defn Symbol already defined. O Operator Err Undefined or illegal operator P Phase Err Symbol has different value on pass 2 than on pass 1 R Range Err Argument out of bounds, branch out out of range, or illegal register/ port number. S Syntax Err Ill-formed argument or expression W Warning Instruction not available on specified target machine. Fatal Error Messages SOURCE FILE NOT FOUND The specified source file doesn't exist. UNABLE TO CREATE OUTPUT FILE The directory is full on the disk specified for output OUTPUT FILE WRITE ERROR The output disk is full EVALUATION STACK IS FULL An arithmetic expression was encountered which had too many levels of parentheses or of precedence nesting SYMBOL TABLE FULL Not enough memory remains to to create a table entry for a symbol being defined. Non-Fatal Error Messages NO ROOM FOR SYMBOL-TABLE SORT Not enough memory is available to sort the symbol table. Symbol-table listing is therefore omitted. :Object File Format Objec⌠ file≤ caε bσ iε onσ oµ tw∩ formats« Thesσ arσ eithe≥ Inte∞ ì HE╪ forma⌠ o≥ Motorolß S▒ format«á Thσ extensioε fo≥ aε Inte∞ HE╪ ì forma⌠á filσá i≤á `.HEXº anΣ thσ extensioε fo≥á thσá Motorolßá S▒ ì format file is `.MIK'. (See option switch K in section B) Inte∞ HE╪ format¼ whicΦ represent≤ binar∙ datß byte≤ a≤ two-digi⌠ ì ASCI╔ hexadecima∞ numbers«á Aε objec⌠ filσ consist≤ oµ ß sequencσ ì oµ datß records¼ followeΣ b∙ ß singlσ enΣ record. Thσá checksuφá i≤ thσ two'╙ complemen⌠ oµ thσá 8-bi⌠á sum¼ ì withou⌠á carry¼á oµá al∞ thσ datß bytes¼á thσ tw∩ byte≤ oµá loaΣ ì address¼ and the byte count. The record formats are: Data Record: Byte 1 Colon (:) 2..3 Number of binary data bytes in this record. 4..5 Load address for this record, high byte. 6..7 Load address " " " low byte 8..9 Unused, should be "00". 10..X Data bytes, two characters each. X+1..X+2 Checksum (2 characters). X+3..X+4 CR/LF End Record: Like data record, but number of data bytes is zero and the load address field contains the program starting address. Motorolßá S▒ format¼á whicΦ represent≤ binar∙ datß byte≤ a≤á two-ì digi⌠á ASCI╔ hexadecima∞ numbers«á Aε objec⌠ filσ consist≤á oµá ß ì sequencσ oµ datß records¼ followeΣ b∙ 'S9º t∩ indicatσ thσ enΣ oµ ì the data block. The record formats are: Data Record: Byte 1 'S' 2 '1' 3..4 Number of binary data bytes in this record. 5..6 Load address for this record, high byte. 7..8 Load address " " " low byte 9..X Data bytes, two characters each. X+1..X+2 Checksum (2 characters). X+3..X+4 CR/LF The checksum is the two'S complement of the 8-bit sum, without carry, of all the data bytes, the two bytes of load address, and the byte count. :Known Bugs in Version 2.00 (28-Oct-81) --------------------------------------- 1. The presence of a non-printing ASCII character in a source line may cause an 'S' error, or may cause the line to be interpreted incorrectly.