home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / programs / develop / phxass / phxass.doc < prev    next >
Text File  |  1995-02-27  |  40KB  |  1,147 lines
  1. last change: 93-10-01
  2.  
  3.              ********************************
  4.              *                    *
  5.              *       P h x A s s      V 3.xx    *
  6.              *                    *
  7.              *        MC680x0/68851/6888x     *
  8.              *          Macro Assembler        *
  9.              *                    *
  10.              *      Written by Frank Wille    *
  11.              *                    *
  12.              ********************************
  13.  
  14.  
  15.  
  16. Preface
  17. =======
  18.  
  19. PhxAss V3.xx is SHAREWARE and © copyright 1993 by Frank Wille. Commercial
  20. usage of this program, without a written permission of the author, is strictly
  21. forbidden!
  22.  
  23. PhxAss V3.xx supports all instructions and addressing modes of the following
  24. Motorola processors:  68000,68010,68020,68030,68040,68851,68881,68882
  25. I have completely rewritten huge parts of the source-code, e.g. the whole
  26. addressing mode recognition and the specific code for all instructions.
  27. Because of new searching algorithms the assembling is 15-45% (!) faster as
  28. with version V2.x. On my 7 MHz 68010 A1000 I have measured nearly 25000
  29. lines per minute.
  30. This program is SHAREWARE. So if you like it, please send me 25 DM or 15$ to
  31. become a registered user. In return you will get the newest updates.
  32.  
  33.  
  34.  
  35. Modifications to PhxAss V2.xx
  36. =============================
  37.  
  38. Register symbols (EQUR) must be declared before they are used. This enables a
  39. faster addressing mode recognition.
  40.  
  41. There are some new optimizations possible. The optimize-flags which can be
  42. specified behind the -n option or after the OPT directive have completely
  43. changed (see "Assembler Options").
  44.  
  45. If you have enabled the small-code model, all jumps which are referencing
  46. external symbols are converted to PC-relative instead of long branch.
  47.  
  48. The '*'-symbol contains the current address. For example a 'bra *+10' would
  49. branch to the location 12 bytes behind the 'bra'-opcode.
  50.  
  51. New directives: FPU, PMMU, CODE_C, CODE_F, DATA_C, DATA_F, BSS_C, BSS_F and
  52. INCDIR.
  53.  
  54. Already mentioned above: The instructions and addressing modes of 68020-68040,
  55. 68851(PMMU) and 6888x(FPCP) are completely supported. You can use Motorola's
  56. new addressing mode style even in the 68000 mode (e.g MOVE (4,A5),D0 ).
  57.  
  58. The new addressing mode recognition has no difficulties with parentheses '()'
  59. instead of brackets '[]' to indicate a term. An operand like
  60.  
  61.  -([x|y]*z)+6([addr+2,A4,regxy*QSIZE],[outerdisp+$100<<(1+3)]),((abc-xyz)+2,A3)
  62.  
  63. would cause no problems.
  64.  
  65. PhxAss enables floating-point numbers to be used with the 6888x (FPCP)
  66. instructions. For example:     fmove.d  #3.1415926536,fp7
  67. moves the double-precision number pi to the FPCP register seven.
  68.  
  69. Note: Ensure that your LIBS: directory contains the 'mathieeedoubbas.library'.
  70.  
  71. Since V3.10 PhxAss is able to optimize forward-branches, which are coming
  72. into their 8/16-bit range by optimzation of the subsequent code. As a result,
  73. other forward-branches could come into range and are also optimized, and so
  74. on.
  75.  
  76. V3.30:
  77. o Symbols which are preceded by a '.' will be regarded as local symbols too.
  78. o A special version of PhxAss is available, which is not limited to the
  79.   maximum number of 65535 lines.
  80.  
  81. V3.40:
  82. o Macro parameters may contain 63 characters now.
  83. o The extended addressing mode recognition accepts the register symbols
  84.   ZD0-ZD7 and ZA0-ZA7 to specify a suppressed register.
  85. o Two new escape codes available:
  86.   \e = escape ($1b)  and  \c = control sequence introducer ($9b).
  87.  
  88. V3.42:
  89. o Float constants may be replaced by hex-constants now.
  90. o When branch-optimization is activated, no extension-checking takes place.
  91.   The best-possible code will be generated.
  92.  
  93. V3.47
  94. o New optimization-flag: 'I' forces PhxAss to ignore a 'Too large distance'
  95.   error.
  96.  
  97. V3.50
  98. o '@' is allowed to be the first character of a symbol name, providing the
  99.   second character is non-numeric.
  100. o The RORG directive is implemented.
  101. o Two Devpac-specific directives are also supported now:
  102.   RSRESET and RS.x for faster reading of (Devpac) include files.
  103. o The new option '-c' can be used to switch off the case-sensitivity.
  104.  
  105. V3.51
  106. o RSSET was forgotten in V3.50
  107. o New directives: IDNT, COMMENT, SUBTTL
  108.  
  109. V3.55
  110. o From now on near-data symbols can be accessed not only by Absolute Addressing
  111.   but also by Address Register Indirect mode ( (An) must be the correct near-
  112.   data base register). This will make the assembling of your source much
  113.   faster, because PhxAss has to do less optimizations. As a side effect XREFs
  114.   will be interpreted correctly and must not be replaced by NREFs.
  115. o If no unit name is given (by TTL or IDNT), PhxAss will use the name of the
  116.   source code without extension as the default unit name.
  117. o The OFFSET directive is supported.
  118.  
  119. V3.60
  120. o PhxAss V3.60 is pure! You can use the CLI-command RESIDENT to add it to the
  121.   resident list.
  122.  
  123.  
  124. Bug fixes since V2.11
  125. =====================
  126.  
  127. o Some instructions had generated a wrong error, e.g. TRAP and STOP generated
  128.   'Assembly aborted' instead of 'Out of range'.
  129. o 'move.l  #xxxx,-(a0)' produced an illegal opcode.
  130. o If someone writes a program without first opening a section with CODE/CSEG,
  131.   SECTION or an initial label, all labels got wrong values.
  132. o In some cases the equates file let PhxAss crash.
  133. o A XDEF for a symbol which was already declared in another section would
  134.   add this symbol to the external-hunk of the section currently active.
  135. o Jump to Branch optimization did not check the addressing mode of the
  136.   JMP/JSR instruction. It simply optimized all modes.
  137. o A long branch to the next instruction was incorrectly optimized to $6x00.
  138. o Bcc.B was not recognized as a short branch. PhxAss accepted only Bcc.S.
  139. o The CNOP directive had disabled all optimizing in its section.
  140. o The 'Word at odd address'-error crashed PhxAss sometimes.
  141. o INITNEAR was useless in the absolute mode.
  142.  
  143. Bug fixes since V3.00
  144. =====================
  145.  
  146. o TRACKDISK now really works.
  147. o The 68020 addressing-mode ([Rn]) was assembled with a wrong size in pass one.
  148. o The near-data range was incorrectly limited to 32k in object files.
  149. o The formatted text-output should also work on OS2.xx/3.xx now.
  150. o MOVE USP,An , MOVES and MOVEP produced incorrect code.
  151. o GLOBAL and BSS destroyed the MSW-bits of the BSS-hunk type ($000003eb).
  152. o CNOP definitely bug-free (I hope).
  153. o References on "\@"-labels behind another macro nesting were impossible.
  154. o "\@" only allowed 999 macro calls (now it's unlimited).
  155. o Some extended adressing modes had made some problems:
  156.   ([..],Rn.s|*x,od) and ([PC..    got a wrong size in pass one,
  157.   ([BaseDisp])    generated an error and    (bd,An/PC,Xn) (where bd is outside of
  158.   the normal 8-bit range) crashed PhxAss.
  159. o FETOXM1 was forgotten (in my Reference Manual too).
  160. o TAB-Codes within strings could not be expanded.
  161. o Include paths which are suffixed by a ':' (volume names) were not recognized.
  162. o FMOVEM.L Dn,FPcr got four bytes more in pass one than in pass two.
  163. o Starting with page 100 the listing file became unreadable.
  164. o The 'Out of memory' error was useless, because PhxAss crashed in most cases.
  165. o CPUSHL,CINVL,CPUSHP,CINVP didn't work.
  166. o BTST Dn,#x was missing.
  167. o The new formard-branch optimization destroyed the CNOP-alignments, which
  168.   are located between the branch-instruction and the branch-destination.
  169. o NARG was not zero for a macro call without arguments.
  170. o INCLUDE/INCBIN without quotes caused an error.
  171.  
  172.  
  173.  
  174. Starting PhxAss
  175. ===============
  176.  
  177. Start the assembler by entering the command line:
  178.  
  179.    PhxAss [<-options>] <filename> [<-options>]
  180.  
  181. where [<-options>] specify optional parameters and <filename> is the name of
  182. the file to be assembled. If no extension in <filename> is given, the assembler
  183. assumes ".asm" for being the extension. Some options cannot be specified before
  184. the file name (see "Assembler Options").
  185. <filename> must be the name of an assembler source code file. The source code
  186. must be an ASCII text file where each line ends with a linefeed ($0a) character
  187. (the format, which all Amiga editors generate). TAB-codes ($09) are allowed.
  188. When the assembler is running, it can be stopped at any time with CTRL-C.
  189.  
  190.  
  191.  
  192. Assembler Options
  193. =================
  194.  
  195. The following assembler options are supported by PhxAss V3.xx :
  196.  
  197. -o<filename>        Defines the name of the output file. If not specified,
  198.             PhxAss takes the source code's filename and replaces
  199.             its extension with ".o" .
  200.  
  201. -d            The names of all global labels of each section are
  202.             written to symbol data blocks. A debugger can use
  203.             these names instead of addresses.
  204.  
  205. -a            Enable auto-align for DC.x directives. All DC.W, DC.L,
  206.             etc. directives in the code will be automatically
  207.             aligned to word-boundaries.
  208.  
  209. -c            Case-sensitivity off. All symbol names will be con-
  210.             verted to upper case. This will slow down PhxAss (5%).
  211.  
  212. -s<symname>[=value]    Predefines a symbol by SET directive. If the value is
  213.             missing, the symbol will be set to 1.
  214.  
  215. -e[<filename>]        Generates an equates file. If <filename> is missing,
  216.             the name of the source code with extension ".equ" will
  217.             be used. Cannot be specified before the name of the
  218.             source code.
  219.  
  220. -l[<filename>]        Generates a listing file. If <filename> is missing, the
  221.             name of the source code with extension ".lst" will be
  222.             used. Cannot be specified before the name of the source
  223.             code.
  224.  
  225. -x            Includes a reference list of all global symbols in the
  226.             listing file. If no listing file was opened, this
  227.             option will cause an error.
  228.  
  229. -p[<lines>]        Sets the page length for equates and listing files.
  230.             If <lines> isn't specified or set to zero, no form.
  231.             feed ($0c) characters will be generated. The default
  232.             value is 60 lines.
  233.  
  234. -q            Quiet mode. The assembler makes no outputs until an
  235.             error occurs.
  236.  
  237. -i<path1>[,<path2>..]    Defines one or more include-paths which will be used
  238.             by the INCLUDE and INCBIN directives.
  239.  
  240. -h<name1>[,<name2>..]    Defines one or more INCLUDE directives at the top of
  241.             the source code.
  242.  
  243. -mf            Forces the whole code to use the large code and large
  244.             data model. NEAR directives within the source code
  245.             will be ignored.
  246.  
  247. -mn[<areg>][,<secnum>]    Forces the whole code to use the small data model.
  248.    or       [,S...]    <areg> (default: 4) specifies the number of the
  249.             address register which will be used as pointer to the
  250.             small data section. Only the registers A2-A6 can be
  251.             used. <secnum> is the number of the section which will
  252.             be the small data section (defaults to -1).
  253.             If <secnum> is -1 or if a string, starting with 'S'
  254.             (e.g. "SmallData"), is specified instead of the
  255.             section number, all Data and Bss sections will be
  256.             treated as a whole small data section. They are
  257.             coalesced by calling the linker with the small data
  258.             option.
  259.  
  260. -mc            Forces the whole code to use the small code model.
  261.             All JSR and JMP instructions which are referencing
  262.             external symbols are converted to PC-relative jumps.
  263.  
  264. -n[<Flags>]        Sets the optimize flags. The following characters can
  265.             be specified after '-n':
  266.  
  267.             N (Normal)
  268.                Standard optimizations:
  269.                clr.l -> moveq #0, move.l -> moveq,
  270.                link.l(68020) -> link.w, adda/suba -> lea
  271.                ($xxxx).L -> ($xx).W,  0(An) -> (An)
  272.  
  273.             R (Relative)
  274.                ($xxxx) -> xx(PC)
  275.  
  276.             Q (Quick)
  277.                Conversions to addq/subq
  278.  
  279.             B (Branches)
  280.                Bcc.l(68020) -> Bcc.w -> Bcc.b, jmp/jsr -> bra/bsr
  281.  
  282.             T (Total branch optimization)
  283.                Bcc.l(68020) -> Bcc.w -> Bcc.b (forward branches)
  284.                Only active if 'B' is also selected.
  285.                WARNING! If you use this option together with a
  286.                listing file, then you can't rely on the line-
  287.                addresses.
  288.  
  289.             L (Logical Shifts)
  290.                lsl #1,Dn -> add Dn,Dn
  291.                lsl.w/b #2,Dn -> add Dn,Dn add Dn,Dn
  292.  
  293.             P (PEA/LEA conversion)
  294.                move.l #x,An -> lea x,An
  295.                     -> lea x(PC),An / lea x.w,An
  296.                move.l #x,-(SP) -> pea x -> pea x(PC) / pea x.w
  297.  
  298.             S (Special, e.g. Read-Modify-Write operations)
  299.                pea 0 -> clr.l -(SP)
  300.                add/sub #0,An or lea 0(An),An ->  (remove)
  301.                The following are not recommendable for a MC68000
  302.                accessing hardware registers:
  303.                move #0,<ea> -> clr <ea>
  304.                move.b #-1,<ea> -> st <ea>
  305.  
  306.             M (MOVEM)
  307.                movem Rn,<ea> -> move Rn,<ea>
  308.                movem ,<ea> -> (remove)
  309.  
  310.             I (Ignore too large distances)
  311.                Distances, which are currently out of range will
  312.                not cause an error. This is useful for originally
  313.                assembling a reassembler-output or when you are
  314.                sure that all distances will come into range again,
  315.                by optimization of the subsequent code.
  316.                BE CAUTIOUS!!! If a distance has not come into
  317.                range, PhxAss will write faulty code!
  318.  
  319.             There are two short cuts:
  320.    *            Selects all standard optimizations & T (-nnrqbt).
  321.    !            Enables all optimizations possible (-nnrqbtlpsm).
  322.             -n without parameters will forbid any optimizing.
  323.             If -n is not specified the assembler uses standard
  324.             optimization (-nnrqb).
  325.  
  326.  
  327.  
  328. Programmer Information
  329. ======================
  330.  
  331.  
  332. 1. Comments
  333.  
  334. Comments start with a ';' or with a '*'.  The text which follows after the
  335. operand field is also a comment and doesn't need ';' or '*'.
  336. Example:
  337.      ; Comment text
  338.       moveq   #0,d0
  339.      ** This is a comment too **
  340.       nop                  ; comment
  341.       add.l   d0,d0           comment after operand field
  342.  
  343. If no operand field is given, e.g. after the NOP instruction, the comment must
  344. be preceded by a ';'. The example above without a semicolon after the NOP
  345. would make the assembler to treat 'comment' as its operand.
  346. '*' is not allowed as a comment-introducer behind an instruction or directive.
  347.  
  348.  
  349. 2. Labels
  350.  
  351. Labels must start in the first column of a line. The colon at the label's end
  352. is optional.
  353. Example:
  354.      Label:   moveq   #0,d0
  355.  
  356. Local labels have a '$' suffixed or are preceded by a '.' (since V3.30). They
  357. are only valid between two global labels.
  358. Example:
  359.      Global1: add.w    d0,d1
  360.           beq.s    local1$
  361.           bpl.s    .local2
  362.           rts
  363.      local1$: moveq    #-1,d0
  364.      .local2: rts
  365.      Global2:
  366.  
  367. The length for global and local labels is unlimited. Valid characters for the
  368. labels are: 'a'-'z', 'A'-'Z', '0'-'9' and '_' . The first character can be a
  369. '.', but global labels cannot start with a digit.
  370.  
  371. The special '*'-symbol always contains the current address. This enables
  372. instruction like: bra *+4
  373. CAUTION! Forward references with '*' will be corrected by PhxAss, but backward
  374. references won't!
  375.  
  376.  
  377. 3. Executable M68000 instructions
  378.  
  379. They have the general format:
  380.      label      operation   operands
  381.  
  382. PhxAss recognizes all operations found in Motorola's M68000PM/AD Programmer's
  383. Reference Manual and all of the common additions and short forms like BHS
  384. instead of BCC, BLO instead of BCS, MOVE instead of MOVEA, ADD instead of
  385. ADDI, etc. . In the current version all MC68000,68010,68020,68030,68040,
  386. 68851,68881 and 68882 instructions are completely supported.
  387. The operand field consists of one to four (68851) operands seperated by a
  388. comma with no imbedded spaces.
  389.  
  390.  
  391. 4. Expressions
  392.  
  393. Expressions consist of symbols and constants. Symbols can be absolute,
  394. relocatable or external. The arithmetic operations supported by PhxAss are
  395. (from highest to lowest precedence) :
  396.  
  397.  ~    not (unary)     -    negation (unary)
  398.  <<   shift left     >>   shift right
  399.  *    multiplication     /    division               //   modulo
  400.  &    and         |    or ('!' also allowed)    ^    exclusive or
  401.  -    subtraction     +    addition
  402.  ( )  parentheses   or [ ]    brackets
  403.  
  404. For absolute symbols and constants (which are absolute too), all arithmetic
  405. operations are allowed.
  406. If relocatables or externals occur in the expression, only subtraction and
  407. addition is possible with some restrictions:
  408.  
  409.    reloc - abs        extern - abs         reloc - reloc
  410.    reloc + abs        extern + abs         abs + reloc      abs + extern
  411.  
  412. are defined, the others are illegal.
  413.  
  414. There are six types of constants:
  415. Hexadecimal, preceded by a '$', consists of '0'-'9' and 'A'-'F' (or 'a'-'f')
  416. Decimal, consists of '0'-'9'
  417. Float, has the format [+/-][integer][.fraction][E[+/-]exponent]
  418. Octal, preceded by a '@', consists of '0'-'7'
  419. Binary, preceded by a '%', consists of '0' and '1'
  420. String, embedded by ' or ", consists of one to four characters.
  421.  
  422. The character '\' is an escape-symbol, which can generate the following codes:
  423.    \\     the '\'-character itself
  424.    \'    character #39 (single quote)
  425.    \"    character #34 (quote)
  426.    \0     character #0  (string terminator)
  427.    \n     character #10 (line feed)
  428.    \f     character #12 (formular feed)
  429.    \b     character #8  (backspace)
  430.    \t     character #9  (tabulator)
  431.    \r     character #13 (carriage return)
  432.    \e     character #27 (escape)
  433.    \c     character #155(control sequence introducer)
  434.  
  435.  
  436. 5. Directives
  437.  
  438. The following paragraphs describe all directives that are supported by the
  439. assembler.
  440.  
  441. EQU
  442.      symbol   equ       <expression>
  443.      symbol   =       <expression>
  444.       The expression will be assigned to the symbol.
  445.  
  446. EQU.x
  447.      symbol   equ.x    <float symbol or constant>
  448.      symbol   =.x       <float symbol or constant>
  449.       An equate with the extension .d,.f,.p,.s,.x or .q will assign the value
  450.       of a floating-point expression to the symbol. No arithmetic operations
  451.       are allowed with floating-point. The expression must be a constant or
  452.       another floating-point symbol.
  453.  
  454. EQUR
  455.      symbol   equr       <register>
  456.       This directive assigns a register (D0-D7,A0-A7 or SP) to the symbol.
  457.       Since V3.00 a register symbol must be declared before it is used.
  458.  
  459. REG
  460.      symbol   reg       <register list>
  461.       This directive assigns the value of the register list to the symbol.
  462.       Valid register lists contain several register names (see EQUR)
  463.       separated by the '/' character. The '-' character defines a range of
  464.       registers. The following are valid register lists:
  465.      a1/a3-a5/d0/d2/d4
  466.      d0-d7/a2-a6
  467.      d1-3/d5-7/a0-1/a3-6  (since V3.56)
  468.  
  469. SET
  470.      symbol   set       <absolute expression>
  471.       This directive assigns the value of the expression to the symbol. No
  472.       relocatables or externals are allowed within the expression. A symbol
  473.       defined by a SET directive may change its value by another SET.
  474.       There are some set-symbols which are defined by PhxAss:
  475.       _PHXASS_      set       1
  476.       _VERSION_   set       version<<16+revision
  477.       According to the connected processor and co-processor PhxAss will set
  478.       _MC68000_, _MC68010_, _MC68020_ and  _MC68881_. The symbols _MC68030_,
  479.       _MC68040, and __MC68882_ will only be created when OS2/3.x is present.
  480.       NARG is zero outside a macro. Within a macro NARG is set to the number
  481.       of specified arguments.
  482.  
  483. RSRESET
  484.       This directive resets the internal RS-counter.
  485.  
  486. RSSET
  487.           rsset    [<count]
  488.       This directive sets the internal RS-counter to the <count> expression.
  489.  
  490. RS
  491.      [symbol] rs.x       [<count>]
  492.       RS assigns the value of the internal RS-counter to the symbol, then it
  493.       increases the counter by the extension size multiplied with <count>. If
  494.       <count> is missing, it defaults to zero. For valid extensions see the
  495.       DC directive.
  496.  
  497. IDNT
  498.           idnt       <name>
  499.       This directive sets the name of the object file unit which the assembler
  500.       will generate. By default, it will be the name of the source file without
  501.       the extension.
  502.  
  503. TTL
  504.       See IDNT.
  505.  
  506. SUBTTL
  507.       subttl will cause no error with PhxAss, but for now it does nothing.
  508.  
  509. COMMENT
  510.           comment  text
  511.       You may write any text you like behind this directive.
  512.  
  513. LIST
  514.       The following source code will be written to the listing file.
  515.  
  516. NOLIST
  517.       The following source code will not be written to the listing file.
  518.  
  519. OPT
  520.           opt       <optimize flags>
  521.       Changes optimization. For a listing of all optimize flags, see "Assembler
  522.       Options".
  523.  
  524. MACRO, ENDM
  525.      symbol   macro
  526.           ...text...
  527.           endm
  528.           macro    symbol
  529.           ...text...
  530.           endm
  531.       This directive assigns a macro to the symbol. The symbol may appear on
  532.       the left or the right side of the directive. The text between the MACRO
  533.       and ENDM directives will be inserted into the source code when the
  534.       assembler discovers the symbol. When calling the macro, up to nine
  535.       arguments, separated by a comma, can be specified in the operand field.
  536.       They are referenced in the macro text as '\1' through '\9'. '\0' is
  537.       reserved for the extension of the macro symbol. Example:
  538.      bhs      macro
  539.           bcc.\0   \1
  540.           endm
  541.       This macro can be called by:    bhs.s     label
  542.       ".s" will be assigned to \0 and "label" will be assigned to \1.
  543.       A "\@" within the macro is replaced by text of the form "nnn", where
  544.       nnn is a unique three-digit number for each macro call. Labels within a
  545.       macro should consist of "\@", because defining labels twice is illegal.
  546.  
  547. MEXIT
  548.       Upon encountering this directive within a macro, the assembler scans for
  549.       the ENDM directive and leaves the macro.
  550.  
  551. END
  552.       In pass one the assembler ignores the rest of the source code and starts
  553.       pass two. In pass two the assembler closes all files and terminates.
  554.       By default the assembler terminates at end of file.
  555.  
  556. FAIL
  557.       The assembler displays the error "69 Assembly aborted !" and terminates.
  558.  
  559. ECHO
  560.           echo       <string>
  561.       The assembler echoes the string. If <string> isn't specified, only a
  562.       newline is echoed.
  563.  
  564. MACHINE
  565.           machine  <processor-number>
  566.       This directive sets the processor-type for which the code will be
  567.       generated. Valid processor-numbers are:
  568.       68000, 68010, 68020, 68030, 68040
  569.  
  570. FPU
  571.           fpu [<cpID>]
  572.       This directive enables code generation for a MC68881/68882 coprocessor.
  573.       By default the <cpID> is set to one, which should be the correct ID for
  574.       most systems using a floating point coprocessor.
  575.       Never set <cpID> to zero, because this is the constant ID for a PMMU.
  576.       If you have set the processor-type to 68040 you should not use this
  577.       directive.
  578.  
  579. PMMU
  580.       This directive enables code generation for a MC68851 Paged Memory
  581.       Management Unit. PMMU only makes sense if you have set the processor-
  582.       type to '68020'.
  583.  
  584. SECTION
  585.           section  <name>[,<type>[,<memflag>]]
  586.       The following code will be placed in the section named <name>. There
  587.       are three section types: CODE, DATA and BSS. CODE contains the executable
  588.       M68000 instructions, DATA contains initialized data and BSS contains un-
  589.       initialized data (set to zero before the program is started). By default
  590.       <type> is set to CODE. The section will be loaded to the memory indicated
  591.       by the <memflag> argument. This can be FAST or CHIP. By default the
  592.       section will be loaded to the memory with the highest priority.
  593.       For compatibility reasons CODE_C, DATA_C and BSS_C are also recognized as
  594.       section type since V3.56.
  595.       Creating a section lets the assembler change into relocatable mode. In
  596.       this mode the following directives are illegal:
  597.       org, load, file, trackdisk
  598.  
  599. CODE, CSEG
  600.       These directives correspond to:  section    "CODE",code
  601.  
  602. DATA, DSEG
  603.       These directives correspond to:  section    "DATA",data
  604.  
  605. CODE_C, CODE_F, DATA_C, DATA_F, BSS_C, BSS_F
  606.       See CODE, DATA or BSS. In addition a memflag will be set, which causes
  607.       the section to be loaded to FAST (xxx_F) or to CHIP (xxx_C).
  608.  
  609. BSS (1)
  610.       This directive corresponds to:   section    "BSS",bss
  611.  
  612. BSS (2)
  613.           bss       symbol,<size>
  614.       BSS with arguments does not start a section. It defines a symbol to be
  615.       in the BSS-section, reserves <size> bytes in this section and assigns
  616.       the address of the first byte to the symbol.
  617.  
  618. GLOBAL
  619.           global   symbol,<size>
  620.       This directive does the same as BSS symbol,<size>. In addition GLOBAL
  621.       will declare the symbol as XDEF (ext_def).
  622.  
  623. OFFSET
  624.           offset   [<start offset>]
  625.       This directive indicates the beginning of a special offset-section. All
  626.       the labels, which are declared in this section, will be treated as
  627.       absolute offsets instead of addresses. <start offset> defaults to zero.
  628.       This might be useful for declaring structure offsets with the DS.x
  629.       directive. While writing programs for PhxAss you should prefer the faster
  630.       RSRESET, RSSET and RS.x directives. OFFSET was mainly implemented for
  631.       compatibility reasons.
  632.  
  633. INCDIR
  634.           incdir   <path1>[,<path2>,...]
  635.       This directive does the same like the -i option (see Assembler Options).
  636.  
  637. INCLUDE
  638.           include  <filename>
  639.       This directive causes PhxAss to suspend the assembling of the current
  640.       file and to assemble the file named <filename>. When done, the assembler
  641.       continues assembling the original file.
  642.       If PhxAss can't find the include file, it first searches within the
  643.       include directory defined by the environment variable PHXASSINC. Then
  644.       it searches within the include directories defined by INCDIR and the
  645.       -i assembler option (see "Assembler Options").
  646.  
  647. INCBIN
  648.           incbin   <filename>
  649.       This directive causes the assembler to include a binary file into the
  650.       current section (e.g. graphics, samples or trigonometrical tables).
  651.       The assembler searches in the same include directories like INCLUDE.
  652.  
  653. XREF
  654.           xref       symbol1[,symbol2,...]
  655.       This directive tells the assembler that the specified symbols are
  656.       externally defined and will be inserted by the linker.
  657.  
  658. NREF
  659.           nref       symbol1[,symbol2,...]
  660.       This directive does the same like XREF, but the assembler is forced to
  661.       use these symbols as small-data relocatables.
  662.  
  663. XDEF
  664.           xdef       symbol1[,symbol2,...]
  665.       This directive causes the assembler to add the names and values of the
  666.       specified symbols to the external-block of the object file. The linker
  667.       can read the values of these symbols and insert them into other object
  668.       files.
  669.  
  670. PUBLIC
  671.           public   symbol1[,symbol2,...]
  672.       When the specified symbols are defined in the current code, PUBLIC will
  673.       do the same like XDEF. When the symbols are unknown, PUBLIC will do the
  674.       same like XREF.
  675.  
  676. ORG
  677.           org       address
  678.       Defines the origin of the following code and lets the assembler change
  679.       into absolute mode. Since V1.8 several ORG directives are allowed and
  680.       each one can be seen as a new section. The following directives are
  681.       illegal in absolute mode:
  682.       ttl, code, cseg, data, dseg, bss, section, offset, xref, nref, xdef,
  683.       public, idnt.
  684.  
  685. LOAD
  686.           load       address
  687.       After assembling is done, the executable code will be loaded to this
  688.       address. By default the code will be loaded to the address which was
  689.       specified as origin.
  690.  
  691. FILE
  692.           file       <filename>
  693.       After assembling is done, the executable code will be written to the file
  694.       named <filename>.
  695.  
  696. TRACKDISK
  697.           trackdisk <drive>,<startblock>[,<offset>]
  698.       After assembling is done, the executable code will be written directly to
  699.       floppy disk using the 'trackdisk.device'. <drive> is valid from 0 to 3.
  700.       <startblock> is valid from 0 to 1759. <offset>, which is zero by default,
  701.       specifies the byte-offset within a block and is valid from 0 to 511.
  702.  
  703. NEAR
  704.           near       [An[,<secnum> | SmallData]]
  705.       This directive initializes the parameters used by the near-data model.
  706.       NEAR with arguments may appear only once in the whole source code. After
  707.       initializing the small-data model, it can be switched on and off by NEAR
  708.       and FAR without arguments. In this mode you are allowed to access near-
  709.       symbols via 'NearSymbol(An)'. Absolute references will be automatically
  710.       converted to Address Register Indirect, if possible.
  711.       The first argument, the address-register, is valid from A2 to A6 and will
  712.       be A4 by default. <secnum>, which defaults to zero, specifies the number
  713.       of the section which will be accessed by Address Register Indirect mode.
  714.       If <secnum> is -1 or a string starting with 'S' or 's', all Data and Bss
  715.       sections will be treated as near-sections and can be coalesced by the
  716.       linker.
  717.           near       code
  718.       If the argument equals to the string "CODE" the assembler activates the
  719.       small-code model. This will force all absolute XREF jumps into PC-
  720.       relative mode.
  721.  
  722. FAR
  723.       This directive turns off the small-data model when active.
  724.  
  725. INITNEAR
  726.       This directive inserts two M68000 instructions into the code which will
  727.       initialize the small-data model depending on the parameters set by the
  728.       NEAR directive. The assembler will generate this code (10 bytes):
  729.           lea       SmallDataBase,An
  730.           lea       32766(An),An
  731.  
  732. DC
  733.      label      dc.x       <value>[,<value>,...]
  734.      label      dc.b       "string"[,...]
  735.       The DC (Define Constant) directive causes one or more fields of memory
  736.       to be allocated and initialized. Each field has the same size, specified
  737.       by the extension of the directive. Each byte, word or longword <value>
  738.       can be an expression and may contain forward references. For floating-
  739.       point and quadword types only constants are allowed. The following
  740.       extensions are valid:
  741.       .B    (1 byte)    Byte          .W    (2 bytes)   Word
  742.       .L    (4 bytes)    Longword      .F    (4 bytes)   Fast Floating Point
  743.       .S    (4 bytes)    Single Precision  .D    (8 bytes)   Double Precision
  744.       .Q    (8 bytes)    Quadword(V3.42)   .X    (12 bytes)  Ext. Precision
  745.       .P    (12 bytes)    Packed BCD
  746.       If the extension is .B, .W or .L several values can be expressed by a
  747.       string, but when using word- or longword-size the string must be aligned.
  748.  
  749. DCB, BLK
  750.      label      dcb.x    <num>[,<fill>]
  751.      label      blk.x    <num>[,<fill>]
  752.       These directives allocate a block of memory having <num> entries. The
  753.       available entry-sizes are the same like above. The block will be
  754.       initialized with <fill> which is zero when missing.
  755.  
  756. DS
  757.      label      ds.x       <num>
  758.       This directive allocates a block of memory having <num> entries and
  759.       initializes each field with zero. See DCB, BLK.
  760.  
  761. CNOP
  762.           cnop       <offset>,<align>
  763.       This directive aligns the address of the following code to <align>. Then
  764.       the <offset> is added. Example:      cnop    2,4   . This example would
  765.       align the next address two bytes behind the next longword boundary.
  766.  
  767. EVEN
  768.       This directive equals to    cnop   0,2  which will make the address word-
  769.       aligned.
  770.  
  771. IFcond, ELSE, ENDIF, ENDC
  772.       These directives support conditional assembling. The general form of the
  773.       IF directive is:
  774.           ifcond      <expression> or symbol
  775.           ...
  776.           [else
  777.           ...]
  778.           endc (or endif)
  779.       PhxAss supports the following conditions:
  780.      IFC "string1","string2" compares two strings. This is useful within
  781.                  macros, when the strings contain macro-
  782.                  arguments '\x' .
  783.      IFD/IFND symbol     Tests if the symbol is defined (undefined).
  784.      IFEQ/IFNE <exp>     Tests if <exp> is zero (not zero).
  785.      IFGT/IFLT <exp>     Tests if <exp> is greater (less) than zero.
  786.      IFGE/IFLE <exp>     Tests if <exp> is greater (less) than or
  787.                  equal to zero.
  788.  
  789.  
  790.  
  791. Linker
  792. ======
  793.  
  794. You may use every linker which supports the standard Amiga-DOS object file
  795. format. If you want to use the small-data model, you should test how small-data
  796. references (HUNK_DREL16 = $3f8) are interpreted by your linker. They are for
  797. exmaple correctly interpreted by PhxLnk and DLink. BLink (PD and Lattice-C)
  798. displays no error but generates wrong code.
  799.  
  800.  
  801.  
  802. Assembler Errors
  803. ================
  804.  
  805. In the current version of PhxAss the following errors can be generated:
  806.  
  807. 01 Out of memory
  808.  
  809. 02 Only ONE source file can be specified
  810.    Example: phxass file1 file2     -> Error 02
  811.  
  812. 03 Listing file option was declared twice
  813.  
  814. 04 Need source file for this option
  815.    Example: phxass -e srcfile    or   phxass -l srcfile     -> Error 04
  816.         phxass srcfile -e    -> ok
  817.  
  818. 05 Equates file option was declared twice
  819.  
  820. 06 Need file name after -o option
  821.  
  822. 07 Need file name after -h option
  823.  
  824. 08 Need directory name after -i option
  825.  
  826. 09 Illegal model. Use F for far or N[2-6][,SecNum] for near
  827.  
  828. 10 Illegal base register for the near-mode
  829.    Valid base registers are: A2-A6
  830.  
  831. 11 Missing source file name
  832.  
  833. 12 File doesn't exist
  834.  
  835. 13 Missing include file name
  836.  
  837. 14 Read error
  838.  
  839. 15 String buffer overflow
  840.    Source code lines are limited to 79 characters.
  841.  
  842. 16 Too many sections
  843.    Maximum is 255 sections.
  844.  
  845. 17 Symbol can't be declared as external
  846.    XDEF can only be used with absolute or relocatable symbols.
  847.  
  848. 18 Symbol was declared twice
  849.  
  850. 19 Unable to declare XREF-symbol
  851.    A symbol, which is defined in the current source code, can't be an external.
  852.  
  853. 20 Illegal opcode extension
  854.    Legal: .b .w .l .s .f .d .x .p .q
  855.  
  856. 21 Illegal macro parameter
  857.    Possible parameters are: \0 (opcode extension), \1 - \9 and \@
  858.  
  859. 22 Illegal characters in label
  860.    See Labels chapter in Programmer Information.
  861.  
  862. 23 Unknown directive
  863.    The opcode is neither a 680x0-mnemonic nor an assembler directive or macro.
  864.  
  865. 24 Too many parameters for a macro
  866.    Nine parameters ( \1 to \9 ) are possible.
  867.  
  868. 25 Can't open trackdisk.device
  869.  
  870. 26 Argument buffer overflow
  871.    Arguments are limited to 79 chracters.
  872.  
  873. 27 Bad register list
  874.    Valid register lists: d0-d3    d3-d4/a2  d2/d3/a4-a6  d7  a0/d2  d2-6/a0-4
  875.  
  876. 28 Missing label
  877.    This directive requires a label.
  878.  
  879. 29 Illegal seperator for a register list
  880.    Valid seperators are '-' and '/'.
  881.  
  882. 30 SET, MACRO, XDEF, XREF and PUBLIC are illegal for a local symbol
  883.  
  884. 31 Not a register (try d0-d7 or a0-a7 or sp)
  885.  
  886. 32 Too many ')'
  887.  
  888. 33 Unknown addressing mode
  889.    See Motorola's "8-/16-/32-bit Microprocessor User's Manual" for a
  890.    description of all addressing modes.
  891.  
  892. 34 Addressing mode not supported
  893.    Example:   move.b  d0,a1  /    move  usp,d2  /  clr.w    (d3)+    -> Error 34
  894.  
  895. 35 Can't use macro in operand
  896.    Macros must be used as opcodes.
  897.  
  898. 36 Undefined symbol
  899.  
  900. 37 Missing register
  901.    Example:   mulu   d0,   -> Error 37
  902.  
  903. 38 Need data-register
  904.  
  905. 39 Need address-register
  906.  
  907. 40 Word at odd address
  908.    Example:   dc.b "Hallo"
  909.           dc.w 0        -> Error 40
  910.    Insert CNOP 0,2 or EVEN after string-constants.
  911.  
  912. 41 Syntax error in operand
  913.  
  914. 42 Relocatability error
  915.    Example:   move.l  label(pc),d0  , where label is not a reloc. and/or label
  916.    is not defined in the current section  -> Error 42
  917.  
  918. 43 Too large distance
  919.    Example:   move.w  50000(a0),d0   -> Error 43
  920.    Too large distance for a displacement by indirect addressing or branch.
  921.    Short branches have a range of +126/-128 bytes. Long branches have a range
  922.    of +32766/-32768 bytes.
  923.  
  924. 44 Displacement expected
  925.    Example:   label: move.l  label(a2),d1   -> Error 44
  926.  
  927. 45 Valid address expected
  928.    A program-address was expected.
  929.  
  930. 46 Missing argument
  931.  
  932. 47 Need numeric symbol
  933.  
  934. 48 Displacement outside of section
  935.    Example:   bra  label   , where label is not defined in the current section
  936.    -> Error 48
  937.  
  938. 49 Only one distance allowed
  939.    Expression can't contain several distances.
  940.    Example:   move.l  #[label1-label2]+[label3-label4],d0   -> Error 49
  941.  
  942. 50 Missing bracket/parenthesis
  943.  
  944. 51 Expression stack overflow
  945.    A maximum of 128 arguments are allowed in one expression.
  946.  
  947. 52 Unable to negate an address
  948. 53 Can't use distance and reloc in the same expression
  949. 54 Can't shift an address
  950. 55 Can't multiply an address
  951. 56 Overflow during multiplication
  952. 57 Can't divide an address
  953. 58 Division by zero
  954. 59 No logical operation allowed on addresses
  955. 60 Need two addresses to make a distance
  956. 61 Unable to sum addresses
  957.  
  958. 62 Write error
  959.  
  960. 63 Alignment error
  961.    Example:   dc.l "XYZ"   -> Error 63
  962.  
  963. 64 Can't subtract a XREF
  964.    Valid operations with externals:  ext + abs ,  abs + ext   and   ext - abs
  965.  
  966. 65 Impossible in absolute mode
  967.    These directive can't be used in absolute mode:
  968.    ttl, code, cseg, data, dseg, bss, section, xref, nref, xdef, public
  969.  
  970. 66 Unknown error (fatal program failure)
  971.    The assembler or its memory was corrupted by a faulty program running at
  972.    the same time.
  973.  
  974. 67 No externals in absolute mode
  975.    See 65.
  976.  
  977. 68 Out of range
  978.    Example:   addq.l  #9,d1   -> Error 68
  979.  
  980. 69 Assembly aborted
  981.    Generated by the FAIL directive.
  982.  
  983. 70 Missing ENDC/ENDIF
  984.  
  985. 71 Missing macro name
  986.  
  987. 72 Missing ENDM
  988.  
  989. 73 Can't define macro within a macro
  990.  
  991. 74 Unexpected ENDM
  992.  
  993. 75 Unexpected ENDC/ENDIF
  994.  
  995. 76 Impossible in relative mode
  996.    These directive can't be used in relative mode: org, file, load, trackdisk.
  997.  
  998. 77 Parameter buffer overflow
  999.    Parameters are limited to 79 characters.
  1000.  
  1001. 78 Can't open timer.device
  1002.  
  1003. 79 Unable to create file
  1004.    Maybe the destination disk is write-protected.
  1005.  
  1006. 80 Need listing file to add references
  1007.    -x option was specified without the -l option.
  1008.  
  1009. 81 No address allowed here
  1010.    Example:   ds.l label   -> Error 81
  1011.  
  1012. 82 Illegal characters in symbol
  1013.    See error 22.
  1014.  
  1015. 83 Source code too large (max. 65535 lines)
  1016.  
  1017. 84 No floating point without mathieeedoubbas.library
  1018.    To use floating point symbols, you must have the mathieeedoubbas.library
  1019.    in your LIBS: directory.
  1020.  
  1021. 85 IEEE Double Precision Overflow/Underflow
  1022. 86 IEEE Single Precision Overflow/Underflow
  1023. 87 Motorola FFP Overflow/Underflow
  1024. 88 Incompatible float types
  1025. 89 Packed BCD Overflow/Underflow
  1026.  
  1027. 90 Can't mix LOAD, FILE and TRACKDISK
  1028.    Example:   load $70000
  1029.           file "mycode"   -> Error 90
  1030.  
  1031. 91 Near mode not activated
  1032.    The near mode must be activated first, before using the INITNEAR directive.
  1033.  
  1034. 92 Instruction not implemented in your machine
  1035.    The instruction exists for another processor, but not for your one. Use
  1036.    MACHINE to change processor type.
  1037.  
  1038. 93 Illegal scale factor
  1039.    Example:    move.w  (a1,d2*3)    -> Error 93
  1040.    Valid scale factors are:  1, 2, 4 and 8
  1041.  
  1042. 94 Missing operand
  1043.    Example:    move.l  (a0)+        -> Error 94
  1044.  
  1045. 95 Section doesn't exist
  1046.    This error is caused by specifying an illegal section number in the NEAR
  1047.    directive.
  1048.  
  1049.  
  1050.  
  1051. History
  1052. =======
  1053.  
  1054. After six years of working with assemblers like SEKA, AS (Aztec-C) and A68k,
  1055. I decided in December 1991 that I need a new, powerful assembler. First, I had
  1056. the idea to buy O.M.A. or Devpac, but I don't like these modern assemblers with
  1057. an integrated editor. Other reasons for starting the development of PhxAss were
  1058. the chronic lack of money (I'm student) and the possibility to create an
  1059. assembler which will satisfy all of my demands.
  1060. I completed the first version V1.00 at the 28th of January in 1992. From now
  1061. on I used PhxAss to assemble itself (first I used A68k). It took me more than
  1062. a year and 23 versions to reach V3.00 (PhxAss was not my only project in this
  1063. period).
  1064.  
  1065. Here is a list of my hardware and literature that enabled the development of
  1066. PhxAss:
  1067. Hardware:   My good old A1000 (first version from '85) with 68010 CPU,
  1068.         2 MB Fast-RAM and a 33 MB Harddisk.
  1069.  
  1070. Literature: Motorola MC68000/68008/68010/68HC000 8-/16-/32-Bit Microprocessor
  1071.         User's Manual (Prentice Hall)
  1072.  
  1073.         Motorola MC68020 32-Bit Microprocessor User's Manual (Prentice
  1074.         Hall)
  1075.  
  1076.         Motorola MC68881/882 Floating-Point Coprocessor User's Manual
  1077.         (Prentice Hall)
  1078.  
  1079.         Motorola MC68851 Paged Memory Management Unit User's Manual
  1080.         (Prentice Hall)
  1081.  
  1082.         Motorola M68000,MC68020,MC68020,MC68040,MC68851,MC68881/882
  1083.         Programmer's Reference Manual (Prentice Hall)
  1084.  
  1085.         Amiga ROM Kernel Reference Manual: Libraries & Devices (Addison-
  1086.         Wesley)
  1087.  
  1088.         Amiga ROM Kernel Reference Manual: Includes & Autodocs (Addison-
  1089.         Wesley)
  1090.  
  1091.         Amiga Intern (Data Becker)
  1092.  
  1093.         Amiga Intern Band 2 (Data Becker)
  1094.  
  1095.  
  1096.  
  1097. Bugs
  1098. ====
  1099.  
  1100. Known bugs in version V3.60:
  1101.  
  1102. o Floating-point symbols defined by the EQU.x directive do not appear in the
  1103.   equates file.
  1104. o When the instruction xxxx is removed by optimization, PhxAss generates an
  1105.   illegal short branch with zero displacement.
  1106.       Bcc.s  label
  1107.       xxxx
  1108.     label:
  1109.   This can only happen when you have set the optimize flag 'M' and xxxx is a
  1110.   MOVEM without registers or when you have set the 'S'-flag and xxxx is a
  1111.   'ADDA/SUBA #0,An' or 'LEA 0(An),An'.
  1112. o Because of many misprints in Motorola's Programmer's Reference Manual I was
  1113.   forced to estimate the opcodes of some instructions (FSABS and FDABS).
  1114. o The Forward-Branch optimization (T-flag) doesn't change the line-addresses
  1115.   in the listing file.
  1116. o The following lines from the orignial Commodore include file "exec/types.i"
  1117.   can't be assembled and must be changed:
  1118.   \@BITDEF  SET     1<<\3
  1119.         BITDEF0 \1,\2,F_,\@BITDEF
  1120.   change to:
  1121.   BITDEF\@  SET     1<<\3
  1122.         BITDEF0 \1,\2,F_,BITDEF\@
  1123.  
  1124.  
  1125. USERS OF 32-BIT PROCESSORS AND COPROCESSORS:
  1126. Please try to test all specific instructions of your processor and send me
  1127. your bug-reports. In return you will get the newest version.
  1128.  
  1129.  
  1130. If any bugs or questions occur, please write to :
  1131.  
  1132.             Frank Wille
  1133.             Auf dem Dreische 45
  1134.             32049 Herford
  1135.             GERMANY
  1136.  
  1137.            __
  1138.           ///
  1139.          ///
  1140.         ///
  1141.    __       ///
  1142.    \\\      ///
  1143.     \\\  ///
  1144.      \\\///
  1145.       \XX/      A M I G A   F O R E V E R  !
  1146.  
  1147.