home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / programs / develop / ezasm / ezasm.doc < prev    next >
Text File  |  1995-02-27  |  33KB  |  1,445 lines
  1.  
  2.  
  3.     EZAsm   Version 1.8                  November '93   by Joe Siebenmann
  4.  
  5.  
  6.  
  7.     DISCLAIMER:
  8.  
  9.  
  10.     You have the right to freely use, copy, and distribute
  11.     the files in this collection ( A68k and Blink have their own
  12.     distribution policies ) provided the following
  13.     conditions are met:
  14.  
  15.     1.    They are distributed together, and are not modified
  16.         in any way.  Foreign language translations can be added.
  17.     
  18.     2.    They are not included in any package for profit
  19.         unless written consent from the author is obtained.
  20.         Inclusion in a PD series is OK as long as the
  21.         cost is REASONABLE.
  22.  
  23.  
  24.  
  25.     ------- NO LIABILITY FOR CONSEQUENTIAL DAMAGES -------
  26.  
  27.     IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DAMAGES
  28.     WHATSOEVER ARISING OUT OF THE USE OF OR INABILITY TO USE
  29.     THESE PROGRAMS.
  30.  
  31.  
  32.  
  33.  
  34.  
  35.         ---  New for Version 1.8  ---
  36.  
  37.  
  38. o    Bug fixes:
  39.  
  40.     -  Size arguments for "++" and "--" stopped working.
  41.        Thanks to Andreas Ackermann for the suggestions
  42.        and reporting the bug.
  43.  
  44.  
  45.         foo = Function()    foo = Function()
  46.         foo != 0 Quit        foo <op> <operand>
  47.  
  48.     -  In trying to optimize by eliminating the following "tst"
  49.        it could remove the 2nd statement by mistake.
  50.        Thanks to Martin Combs for the suggestions, testing,
  51.        ez.lib improvements, and bug reports.
  52.  
  53.     -  Problem with using "MACRO", "ENDM" above your code.
  54.  
  55.  
  56. o    Support for all the new 3.0 function calls, including
  57.     tag lists.
  58.  
  59. o    Function argument syntax is now much more relaxed.
  60.     You can now use: "Permit()", "OpenWindow(NewWin)", etc..
  61.  
  62. o    New optimizations using PC relative addressing.
  63.     A size decrease of over 11% was achieved on "scrwin".
  64.  
  65. o    Better handling for allowing assembly statements to
  66.     come before EZAsm statements, and better detection of where
  67.     your code starts.
  68.  
  69. o    Improved handling of paths for source and output files.
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.     EZAsm was written to make programming in 680X0 assembly
  77.     language MUCH easier!  EZAsm combines 680X0 assembly language
  78.     with parts of C.  The result is highly optimized code,    
  79.     with almost HALF the development time!
  80.  
  81.     A68k ( by Charlie Gibbs ) and Blink ( from The Software Distillery )
  82.     are included, so you'll have everything you need to start
  83.     producing executables. ( except Commodore's include files )
  84.  
  85.  
  86. Here are some of its advantages:
  87.  
  88.  
  89. o    Your code is converted into the fastest possible
  90.     assembly statement(s), so you automatically write
  91.     "good" code.
  92.  
  93. o    More structured.  Compare and bit test statements can have
  94.     braces and "else" like C.  Being able to use braces lets
  95.     you use assembly language in a whole new way!
  96.  
  97. o    C-like Amiga function calls!  Every 3.0 function in every
  98.     library is supported.
  99.  
  100. o    Import functions from libraries using ".fd" files.
  101.  
  102. o    All needed libraries, including ".fd"s and resources,
  103.     are opened and closed automatically.
  104.  
  105. o    Your code is much more readable, and easier to debug.
  106.     You can code nearly twice as fast, with fewer syntax errors.    
  107.  
  108. o    No more having to constantly look up which condition code to    
  109.     use for compares, bit tests, or maximum numbers for
  110.     "moveq" or "addq" etc.
  111.  
  112. o    You can freely mix assembly statements with "EZAsm statements".
  113.  
  114.  
  115.  
  116.     You need to know a little about assembly language and
  117.     C operators before you dive right in.  If you're new to
  118.     68000 assembly language, I suggest looking at one of the
  119.     many available books on the subject.  The source code
  120.     for "Mk", "scrwin" and "scrwintags" are included as examples.
  121.  
  122.  
  123. ****************************************    
  124.  
  125. Using EZAsm:
  126.  
  127.     Create a directory, and copy these files into it:
  128.  
  129.         EZAsm, A68k, Blink, Mk, ez.lib, nm1, dat1
  130.  
  131.  
  132.     You can either CD into your directory or take
  133.     advantage of the new path handling:
  134.  
  135.         1.  Add "assign EZASM: [path][YourEZAsmDir]".
  136.  
  137.         2.  Add EZASM: to your path:  "path EZASM: add"
  138.             ( Use "path" to check that it worked )
  139.  
  140.  
  141.     ( Mk and EZAsm will first check to see if you're
  142.     CD'd into the directory, then will try looking for
  143.     the ASSIGN )
  144.  
  145.  
  146.     Paths:
  147.  
  148.     If a path to the source file is given, the output file
  149.     will go to same directory.  If no path, EZAsm uses the
  150.     current directory for source and output files.
  151.  
  152.     ( Another good method is to create an ALIAS to load these
  153.     files into VD0:, or RAD:, CD into it, and work from there )
  154.  
  155.  
  156. Mk
  157.     Mk is a make-like program, written in EZAsm, that will
  158.     Execute() the necessary programs for you, creating an
  159.     executable file with a minimum of effort.  It also
  160.     supports an optional include path for A68k, and support
  161.     for a ".mak" file.  The source code is included.
  162.  
  163.     ( !! WShell users might need to rename Mk !! )
  164.  
  165.     Usage:
  166.  
  167.         Mk [-iPathToIncludes] [path]file
  168.  
  169.     ( where "file" is your source file, NO extension )
  170.  
  171.  
  172.         Execute()s these commands:
  173.  
  174.         ezasm file.s
  175.         a68k [-iPathToIncludes] file.asm
  176.         blink FROM file.o LIB ez.lib TO file
  177.  
  178. .mak
  179.     For times when you need to supply more options for A68k or
  180.     Blink, or invoke other assemblers or linkers, Mk supports
  181.     a .mak file.  Just create a file with the same name as your
  182.     source file, but with a ".mak" extension.  The file should
  183.     contain the EZAsm, A68k, Blink or other commands, with any options
  184.     or switches you need, as if you were entering them from the CLI.
  185.     Any comments should begin with a non-alpha character.
  186.     If Mk finds the .mak file, it will Execute() those commands,
  187.     otherwise it will Execute() the standard commands.
  188.  
  189.  
  190.  
  191. Getting Started:
  192.  
  193.     The best way to begin using EZAsm is to take your existing
  194.     assembly source and gradually make these changes:
  195.  
  196.     -  Eliminate all your opening and closing of libraries,
  197.        and any "SECTION" statements, EZAsm takes care of all
  198.        that for you.
  199.  
  200.     -  Declare your variables.
  201.  
  202.     -  Start replacing the statements that make up your Amiga
  203.        function calls with the simple C-style calls.
  204.  
  205.     At your own pace you can: (1) Continue to "convert" chunks of
  206.     your code, or leave them alone. (2) Code new routines using
  207.     EZAsm/assembly statements.
  208.  
  209.  
  210.  
  211. ***************************************
  212. *          Addressing Modes           *
  213. ***************************************
  214.  
  215.                     Operand Type
  216.  
  217.      Mode      [A] [B] [C] [D] [E] [F]
  218.  
  219. Dn              *   *   *   -   *   -
  220. An              *   -   *   -   -   -
  221. (An)            *   *   *   *   *   *
  222. (An)+           *   *   *   *   *   *
  223. -(An)           *   *   *   *   *   *
  224. d16(An)         *   *   *   *   *   *
  225. d8(An,Xn)       *   *   *   *   *   *
  226. 16 bit addr     *   *   *   *   *   *
  227. 32 bit addr     *   *   *   *   *   *
  228. d16(PC)         *   -   -   -   *   *
  229. d8(PC,Xn)       *   -   -   -   *   *
  230. immediate       *   -   -   -   *   -
  231.  
  232. bd(An,Xn)       *   *   *   *   *   *     68020/68030
  233. ([bd,An],Xn,od) *   *   *   *   *   *     68020/68030
  234. ([bd,An,Xn],od) *   *   *   *   *   *     68020/68030
  235. bd(PC,Xn)       *   -   -   -   *   *     68020/68030
  236. ([bd,PC],Xn,od) *   -   -   -   *   *     68020/68030
  237. ([bd,PC,Xn],od) *   -   -   -   *   *     68020/68030
  238.  
  239.  
  240.  
  241. declared variables:
  242.  
  243. "foo"  becomes  "foo(a5)"  ( d16(An) )
  244.  
  245. **************************************
  246.  
  247.  
  248. <1-8>    1 - 8
  249. <q>    -128 - 127
  250. <n>    any byte, word, or long size number
  251.  
  252.  
  253. Dn    d0 - d7
  254. An    a0 - a7
  255.  
  256. bd    32 bit displacement
  257. od    32 bit outer displacement
  258.  
  259. Xn      a0 - a7  d0 - d7
  260.  
  261.      Options:              Examples:
  262.  
  263.      size:  .w  .l         a2.w  a0.l
  264.      scale: *1 *2 *4 *8    a1*2  a0.w*4  ( 68020/68030 )
  265.  
  266. {B}    byte data size not allowed for An operands
  267.  
  268.  
  269. **********************************
  270. *       legal        *   legal   *
  271. *      operands      *   sizes   *
  272. **********************************
  273.  
  274.  
  275. Addition  Subtraction
  276.  
  277. ++
  278. --
  279.  
  280.     [C] <op>            L,W,{B}   *
  281.  
  282. +=
  283. -=
  284.     
  285.      Dn <op> [A]        L,W,B           
  286.  
  287.      An <op> [A]        L,W       *
  288.  
  289.     [D] <op> Dn         L,W,B
  290.     
  291.     [B] <op> <n>        L,W,B        
  292.     
  293.     [C] <op> <1-8>      L,W,{B}   *    
  294.  
  295.  
  296. Examples:
  297.  
  298.     Total ++    
  299.     d1 += 10
  300.  
  301. Optional Args:
  302.  
  303.     l, w, b 
  304.  
  305. *    These are optimized by making the size word (.w)
  306.     instead of long (.l) for "An" operands.  It's 4 cycles
  307.     shorter, and the upper two bytes are correctly handled!
  308.  
  309. ********************************************
  310.  
  311. Multiplication   Division
  312.  
  313.  
  314. *=
  315.  
  316.     Dn *= [E]           W
  317.  
  318.     Dn *= ##            W   *
  319.  
  320.  
  321. /=
  322.  
  323.     Dn /= [E]           W
  324.     
  325.  
  326. Examples:
  327.  
  328.     d0 *= d1
  329.     d2 /= 2
  330.  
  331. Optional Args:
  332.  
  333.     w,
  334.     s ( signed  divs/muls )
  335.  
  336.  
  337. *    ( Improved! ) This optimization results in code that's larger then
  338.     "mulu" or "muls", but will execute much faster.  Not all numbers
  339.     can be optimized.  If the number doesn't work, "mulu"
  340.     or "muls" will be used.
  341.  
  342.     ( where ## is a word or byte length number )
  343.  
  344.  
  345. *********************************************
  346.  
  347. And   Or   Exclusive-OR
  348.  
  349.  
  350. &=
  351. |=
  352.  
  353.      Dn <op> [E]        L,W,B
  354.  
  355.     [B] <op> <n>        L,W,B    
  356.     
  357.     [D] <op> Dn         L,W,B
  358.  
  359. ^=
  360.  
  361.     [B] <op> Dn         L,W,B    
  362.     
  363.     [B] <op> <n>        L,W,B
  364.  
  365.  
  366. Examples:
  367.  
  368.     Mask &= %11010000
  369.     Flags |= $f0
  370.  
  371. Optional Args:
  372.  
  373.     l, w, b 
  374.  
  375. *********************************************
  376.  
  377. Shift  Left/Right
  378.  
  379.  
  380. <<
  381. >>
  382.  
  383.      Dn <op> Dn         L,W,B
  384.     
  385.      Dn <op> 1-31       L,W,B    *
  386.  
  387.     [D] <op> 1          W
  388.  
  389.  
  390. Examples:
  391.  
  392.     d2 << d0
  393.     d1 >> 4
  394.  
  395. Optional Args:
  396.  
  397.     l, w, b,
  398.     a = Preserves the sign bit by using "asr" and "ext.l".
  399.         Use only with right shifts ( ">>" ).
  400.  
  401. *    Normally you're limited to shifting 1-8, or using a
  402.     data register to hold higher shift values.  This
  403.     optimized version is faster, and saves using a data register!
  404.  
  405.     
  406. *********************************************
  407.  
  408. Assign
  409.  
  410.  
  411. =    
  412.  
  413.     [B] = [A]           L,W,{B}
  414.     
  415.      An = [A]           L,W
  416.     
  417.  
  418. Examples:
  419.  
  420.     temp = Total
  421.     (a1)+ = 0 w
  422.  
  423. Optional Args:
  424.  
  425.     l, w, b 
  426.  
  427. ********************************************
  428.  
  429. The following Compare and Bit test statements
  430. use this syntax:
  431.  
  432.  
  433.     operand <op> operand label
  434.  
  435.  
  436.  
  437.     operand <op> operand {
  438.         .
  439.         .
  440.     }
  441.  
  442.  
  443.  
  444.     operand <op> operand {
  445.         .
  446.         .
  447.     
  448.     } else {
  449.         .
  450.         .
  451.     }
  452.  
  453.  
  454. ********************************************
  455.  
  456. Compare
  457.  
  458.  
  459. >=
  460. <=
  461. !=
  462. >
  463. <
  464. =
  465.  
  466.      Dn <op> [A]        L,W,{B}
  467.     
  468.      An <op> [A]        L,W
  469.     
  470.     [B] <op> <n>        L,W,B
  471.     
  472.   (An)+ <op> (An)+      L,W,B
  473.  
  474.  
  475.  
  476. Examples:
  477.  
  478.     Total >= 100 Over
  479.  
  480.     Buf != 0 {
  481.         FreeMem( Buf 100 )
  482.     }
  483.  
  484.     (a0)+ = $20 {    
  485.         SPCnt ++
  486.     } else {
  487.         ChrCnt ++
  488.     }
  489.  
  490.  
  491. Optional Args: ( placed AFTER label or brace )
  492.  
  493.     l, w, b,
  494.     s ( signed )
  495.  
  496.  
  497. *********************************************
  498.  
  499. Bit test
  500.  
  501.  
  502. =
  503. !=
  504.  
  505.  
  506.    Dn:0-31 <op> 0-1     L
  507.     
  508.      Dn:Dn <op> 0-1     L
  509.     
  510.     
  511.    [F]:0-7 <op> 0-1     B    
  512.     
  513.     [F]:Dn <op> 0-1     B
  514.  
  515.  
  516.  
  517. Examples:
  518.  
  519.     d1:0 != 1 EvenRtn
  520.  
  521.     ($bfe001):6 = 0 LMBDown
  522.  
  523.     d2:d0 = 1 {
  524.         rts
  525.     }
  526.  
  527.  
  528. Optional Args:
  529.  
  530.     ( ignored )
  531.     
  532. Rules:
  533.  
  534. o    No spaces inside first operand.
  535.  
  536. o    Right operand can only be 0 or 1.
  537.  
  538.  
  539. *********************************************
  540.  
  541. Additional Arguments:
  542.  
  543.  
  544.     b   forces operation to be byte
  545.  
  546.     w     "       "        "   word
  547.  
  548.     l     "       "        "   long
  549.  
  550.     a   preserves sign bit     ( >> )
  551.  
  552.     s   signed                 ( *=, /=, compares )
  553.  
  554.  
  555. ( it's OK to use multiple arguments ( "w s" etc. ))
  556.  
  557. ( these are RESERVED and can't be used as variables or labels
  558. ( unless you use upper case ) ) 
  559.  
  560. *********************************************
  561.  
  562. Functions:
  563.  
  564.  
  565. o    All 3.0 functions are now supported.
  566.     "OBSOLETE" functions are included to maintain compatibility
  567.     with earlier versions of the operating system.
  568.     See "nm1" for supported functions.
  569.  
  570. o    All needed libraries including ".fd"s and resources
  571.     are opened and closed AUTOMATICALLY, and their bases
  572.     are added to your variables. ( resources don't need to
  573.     be closed ) ( See also "XFAIL", "LVER" )
  574.  
  575.  
  576.  
  577.     All functions within these 3.0 libraries and resources
  578.     are supported:
  579.  
  580.     amigaguide.library        _AmigaGuideBase
  581.     asl.library            _AslBase
  582.     battclock.resource        _BattClockBase
  583.     battmem.resource        _BattMemBase
  584.     bullet.library            _BulletBase
  585.     card.resource            _CardResource
  586.     ciaa.resource            _CiaABase
  587.     ciab.resource            _CiaBBase
  588.     commodities.library        _CxBase
  589.     datatypes.library        _DataTypesBase
  590.     diskfont.library        _DiskfontBase
  591.     disk.resource            _DiskBase
  592.     dos.library            _DOSBase
  593.     exec.library
  594.     expansion.library        _ExpansionBase
  595.     gadtools.library        _GadToolsBase
  596.     graphics.library        _GfxBase
  597.     icon.library            _IconBase
  598.     iffparse.library        _IFFParseBase
  599.     intuition.library        _IntuitionBase
  600.     keymap.library            _KeymapBase
  601.     layers.library            _LayersBase
  602.     locale.library            _LocaleBase
  603.     mathffp.library            _MathBase
  604.     mathieeedoubbas.library        _MathIeeeDoubBasBase        
  605.     mathieeedoubtrans.library    _MathIeeeDoubTransBase
  606.     mathieeesingbas.library        _MathIeeeSingBasBase
  607.     mathieeesingtrans.library    _MathIeeeSingTransBase
  608.     mathtrans.library        _MathTransBase
  609.     misc.resource            _MiscBase
  610.     potgo.resource            _PotgoBase
  611.     rexxsyslib.library        _RexxSysBase
  612.     translator.library        _TranslatorBase
  613.     utility.library            _UtilityBase
  614.     workbench.library        _WorkbenchBase
  615.     
  616.  
  617.     All functions for these .devices are supported:
  618.  
  619.     console.device            _ConsoleDevice
  620.     input.device            _InputBase    
  621.     ramdrive.device            _RamDriveDevice
  622.     timer.device            _TimerBase
  623.  
  624.  
  625.     You're responsible for calling OpenDevice() and
  626.     loading the base to use these .device functions:
  627.  
  628.  
  629. LONG    _TimerBase TimeRequest
  630.  
  631.  
  632.     TimeRequest = AllocMem( 40 #CLEAR_PUBLIC )
  633.     beq    Exit
  634.  
  635.     OpenDevice( "timer.device" 0 TimeRequest 0 )
  636.     bne    Exit
  637.  
  638.     a0 = TimeRequest
  639.     _TimerBase = 20(a0)    ;TimeRequest->tr_node.io_Device
  640.          .
  641.          .
  642.  
  643.  
  644.  
  645. o    The cia.resource functions AbleICR(), AddICRVector(),
  646.     RemICRVector(), and SetICR() have been changed to
  647.     simplify the OpenResource().  The functions are now
  648.     AbleICRA() and AbleICRB() etc. and open the corresponding
  649.     ciaa.resource or ciab.resource.
  650.  
  651. o    The leading underscores of the bases are necessary so you can
  652.     use includes without your assembler complaining.  Some library
  653.     bases are already defined in some ".i"s resulting in
  654.     "multiply defined symbol" errors.
  655.  
  656.  
  657.                  AllocMem(100 #CLEAR_PUBLIC)
  658.                              ^
  659.                              | space required
  660.  
  661. o    Function argument syntax is now much more relaxed!
  662.     Arguments must be separated by a space or tab.
  663.  
  664.  
  665.               a2 = ViewAddress()
  666.               d1 = Read( "DF0:myfile" Buf BufLen )
  667.  
  668. o    Address or data registers can be used for returns if
  669.     they're more convenient.  Return variables can be ANY size.
  670.     Variables used in function arguments must be LONG.
  671.  
  672.  
  673. Arguments:
  674.  
  675. o    You can pass registers to function arguments directly.
  676.     If the proper register is already loaded, just pass "*".
  677.  
  678. o    You can also use these, and other addressing modes for function
  679.     arguments and returns: "(An)", "(An)+", "-(An)", "d16(An)" etc.
  680.  
  681. o    EZAsm supports argument strings surrounded by double quotes.
  682.     Strings are automatically NULL terminated.
  683.     The following C character constants are supported:
  684.  
  685.  
  686.         \b    backspace
  687.         \f    form feed
  688.         \n    newline
  689.         \r    carriage return
  690.         \t    horizontal tab
  691.         \v    vertical tab
  692.         \\    backslash
  693.         \"    double quote
  694.         \'    single quote
  695.         \nnn    octal character value
  696.         \xnn    hex character value
  697.  
  698.  
  699.     Examples:  
  700.  
  701.         "Hello, World!\n"
  702.     
  703.         "\x1b[32mEZAsm  1.8\x1b[39m\n"
  704.  
  705.  
  706.  
  707.  
  708.  
  709.     END
  710.  
  711. NewWin    ds.w    0    ;align
  712.     dc.w    0,0,640,200
  713.     dc.b    -1,-1
  714.     .
  715.     .
  716.  
  717. o    PC relative addressing is now used, when appropriate,
  718.     to reference data labels.
  719.  
  720.     The following are used with FUNCTION ARGUMENTS and STATEMENTS
  721.     when referencing declared variables and data labels:
  722.  
  723.     Address of:
  724.  
  725.         #NewWin
  726.         &NewWin
  727.  
  728.         ( These can go to an address or data register:
  729.         "move.l #NewWin,Dn", "lea NewWin[(pc)],An" )
  730.  
  731.     Contents of:
  732.  
  733.         NewWin
  734.  
  735.  
  736. o    Sometimes you have to "play around" with using "#", "&",
  737.     variables, constants etc.. Also taking into account if it's
  738.     being pushed onto the stack.  You might be giving it the
  739.     CONTENTS of a variable, when it needs its ADDRESS. ( etc. )
  740.   
  741. o    It keeps track of the current library base.  As long as no user
  742.     labels, or close braces are hit, it will skip reloading
  743.     the base register for functions which use the same library base.
  744.  
  745.  
  746.  
  747.     OpenScreenTagA( 0
  748.         SA_Width 640        
  749.         SA_Height Hgt
  750.         SA_Depth 2
  751.         SA_DetailPen -1
  752.         SA_BlockPen -1
  753.         SA_Type $f
  754.         SA_Quiet 1
  755.         SA_DisplayID $8000
  756.         TAG_END )
  757.  
  758.  
  759. Tag list Functions:
  760.  
  761.     Tag list functions are now supported.  When using the
  762.     "varargs" version of a function ( above ), the tag list
  763.     arguments are built as data, and the function argument is
  764.     converted to a pointer to the data structure.
  765.  
  766.  
  767.     The following functions HAVE BEEN CHANGED for consistancy:
  768.  
  769.          ( was )                   ( now )
  770.  
  771.    _DOSBase:
  772.  
  773.         SystemTagList             SystemA
  774.         [System]                  System
  775.  
  776.         [AllocDosObjectTagList]   AllocDosObjectA
  777.         AllocDosObject            AllocDosObject
  778.  
  779.         [CreateNewProcTagList]    CreateNewProcA
  780.         CreateNewProc             CreateNewProc
  781.  
  782.    _AslBase:
  783.  
  784.         AllocAslRequest           AllocAslRequestA
  785.         [AllocAslRequestTags]     AllocAslRequest
  786.  
  787.         AslRequest                AslRequestA
  788.         [AslRequestTags]          AslRequest
  789.  
  790.    _GfxBase:
  791.  
  792.         ExtendFont                ExtendFontA
  793.         [ExtendFontTags]          ExtendFont
  794.  
  795.    _IntuitionBase:
  796.  
  797.         OpenWindowTagList         OpenWindowTagA
  798.         [OpenWindowTags]          OpenWindowTag
  799.  
  800.         OpenScreenTagList         OpenScreenTagA
  801.         [OpenScreenTags]          OpenScreenTag
  802.  
  803.         
  804. o    It knows about every 3.0 tag ( "SA_Height", "WA_Width" etc. ) 
  805.     and they'll automatically be converted to their
  806.     equivalents ( $80000024, $80000066 ), no includes are needed.
  807.     All the supported tags are listed in the file "nm1"
  808.     below the function names.
  809.  
  810. o    It's important to use these tags!  That's how it differentiates
  811.     between 'regular' and tag list function arguments.
  812.  
  813. o    Tag lists MUST be terminated with "TAG_DONE", "TAG_END"
  814.     ( with NO '0' tag data ) or "TAG_MORE" ( with a tag list address ).
  815.  
  816. o    Be sure to add an include when using tag data arguments like:    
  817.     "TRUE", "FALSE", "CUSTOMSCREEN" etc.
  818.  
  819. o    The closing parenthesis ( ")" ) shouldn't be on a separate line.
  820.     You should have at least one argument before it. 8^(
  821.  
  822. o    Variables used for tag data arguments can be ANY size, and are
  823.     correctly loaded automatically.
  824.  
  825. o    When importing tag list functions from libraries and using
  826.     "unknown" tags, I'd recommend setting up a tag list data structure
  827.     like EZAsm does, use includes, and pass its address.
  828.  
  829.  
  830. *********************************************
  831.  
  832. Importing functions from library ".fd"s
  833.  
  834.  
  835. Usage:
  836.  
  837. PROTO    [path]LibraryName [path]FDName
  838.  
  839.  
  840. Example:
  841.  
  842. PROTO    req.library req.fd
  843.  
  844.  
  845.     Where PROTO is in upper case, begins at column 1, and
  846.     is placed ABOVE your variable declarations.  The ".fd"
  847.     file is read, and all its functions, both "##public"
  848.     and "##private", become available for use.  The
  849.     library base is added to your variables, and the
  850.     opening and closing of the library is handled
  851.     automatically.
  852.  
  853.     To avoid any conflicts with other function names, these
  854.     are used first.  Up to 10 ".fd" files can be used.
  855.  
  856.     "PROTO" is most useful for "importing" functions from
  857.     libraries like req.library and reqtools.library, and
  858.     updating the standard Amiga libraries when new versions
  859.     of the operating system come out.  You can also define YOUR
  860.     OWN functions, or fix a "buit-in" function's offset or
  861.     argument register(s).  Here's an example:
  862.  
  863.  
  864. ##base _DOSBase
  865. ##bias 102
  866. Examine()(D1,D2)    ;( arguments within the first "()" are ignored )
  867. ##end
  868.  
  869.  
  870.     ( the default bias is 30 )
  871.  
  872.  
  873. *********************************************
  874.  
  875. Option switches:
  876.  
  877.  
  878.    Using command line arguments:
  879.  
  880.     Because the automatic opening of libraries will
  881.     corrupt A0 and D0, the following "switches" are provided:
  882.  
  883.  
  884. ARGS    A0 is loaded into the variable "Args" ( automatically
  885.     created ) and "clr.b -1(a0,d0.w)" is used to NULL terminate
  886.     the argument string.  The length in D0 is lost.
  887.     ( see Mk.s for an example of using "ARGS" )
  888.  
  889. SAVEARGS
  890.     A0 and D0 are pushed onto the stack with "movem.l d0/a0,-(sp)". 
  891.     You're responsible for restoring and using them.
  892.  
  893.  
  894.  
  895.    Other useful switches:
  896.  
  897. SAVEREGS
  898.     Pushes registers YOU REQUEST onto the stack at the start of
  899.     your code, and restores them before exiting.
  900.     
  901.     Usage:        SAVEREGS  register list
  902.  
  903.     Example:    SAVEREGS  d2-d4/a0-a3/a6
  904.  
  905.     
  906.     Where register list contains no spaces, and will generate
  907.     these statements:    "movem.l d2-d4/a0-a3/a6,-(sp)"
  908.                 "movem.l (sp)+,d2-d4/a0-a3/a6"
  909.  
  910. NOPC    Turns off PC relative addressing optimizations.
  911.  
  912. NODOT    Changes labels ".cn", ".ln" and ".tn"
  913.     to "_cn", "_ln" and "_tn" for Devpak users.
  914.  
  915. OPT4    Uses "$4.w" instead of "$4" to load ExecBase, and
  916.     "lea n.w,An", "pea n.w" when appropriate.
  917.     ( If you don't use A68k, I'd recommend using this.
  918.     A68k makes these optimizations, but doesn't like the
  919.     "$4.w" syntax )
  920.  
  921. EXT    Allows you to specify the extension of the output assembly
  922.     file.  The default is ".asm".  Example:    EXT .a
  923.  
  924. NOEXTRAS
  925.     Removes the loop clearing the stack frame and insertion of
  926.     "moveq #0,d0", "rts" at the end of the code.
  927.  
  928. XFAIL    Prevents your program from exiting if OpenLibrary(), for
  929.     the specified library, fails.
  930.  
  931.     Example:    XFAIL    reqtools.library
  932.  
  933. LVER    Allows you to specify a version number for an OpenLibrary().
  934.  
  935.     Example:    LVER    intuition.library 36
  936.  
  937.  
  938. *********************************************
  939.  
  940. Optimizations:
  941.  
  942.     In addition to the many "standard" optimizations performed
  943.     on statements, the following are also performed:
  944.  
  945.  
  946.   STATEMENT          BECOMES       NOTE
  947.  
  948.  
  949.    An = 0          sub.l An,An
  950.  
  951.    [B] = 0         clr [B]          1
  952.  
  953.  
  954.  ( compares )
  955.  
  956.    [B] < 0
  957.    [B] >= 0                         5
  958.  
  959.    [B] = 0
  960.    [B] != 0        tst [B]          6
  961.                    bxx label
  962.  
  963.    ----------------------------------
  964.  
  965.    [B] += <q>
  966.    [B] -= <q>
  967.  
  968.    [B] &= <q>   
  969.    [B] |= <q>
  970.    [B] ^= <q>
  971.  
  972.    [B] = <q>       moveq   <q>,d7   2
  973.                    [opr].l d7,[B]
  974.  
  975.  
  976.    ( compares )
  977.  
  978.    Dn <op> <q>     moveq   <q>,d7   2
  979.                    cmp.l   d7,dn
  980.                    bxx     label
  981.  
  982.    An <op> <q>     moveq   <q>,d7   2
  983.                    cmpa.l  d7,an
  984.                    bxx     label
  985.  
  986.    ----------------------------------
  987.  
  988.    An += <i>       lea  i(An),An
  989.    An -= <i>       lea  -i(An),An   3, 2
  990.  
  991.    An = <n>        lea  n,An        4, 2
  992.  
  993.    
  994.  
  995.  
  996. <i> maximum:  -= 32768   += 32767
  997.  
  998.  
  999. Notes:
  1000.  
  1001. 1    For byte and word sizes the code size is smaller, for long
  1002.     its smaller and faster. ( then "move #0,[B]" )            
  1003.  
  1004. 2    Only apply to long sized operations.
  1005.  
  1006. 3    ( 1-8 handled by "addq", "subq" ( see note in Addition Subtraction ))
  1007.  
  1008. 4    ( 0 handled by "sub.l An,An" )
  1009.  
  1010. 5    Taken as signed.
  1011.  
  1012. 6    In some cases "tst" is eliminated, or D7 is loaded, see below.
  1013.  
  1014.  
  1015.  
  1016. More optimizations:
  1017.  
  1018.  
  1019.     Buf != 0 {
  1020.         FreeMem( Buf 100 )
  1021.     }
  1022.  
  1023.  
  1024.           ( standard )                    ( now )
  1025.  
  1026.     tst.l    Buf(a5)            move.l    Buf(a5),d7
  1027.     beq    .l2            beq    .l2    
  1028.     movea.l    $4,a6            movea.l    $4,a6    
  1029.     movea.l    Buf(a5),a1        movea.l    d7,a1
  1030.         .                .
  1031.         .                .
  1032.  
  1033. o    Instead of doing a "tst", the variable is loaded into D7
  1034.     ( flags set, and same size and number of cycles ) where it can
  1035.     be utilized by a following function call.  In this case it
  1036.     loads D7 into A1, saving 2 bytes, and taking only 4 cycles
  1037.     instead of 13.
  1038.  
  1039.  
  1040.  
  1041.     Fhandle = Open( "df0:myfile" 1005 )    
  1042.  
  1043.     Fhandle = 0 {
  1044.         .
  1045.         .
  1046.     }
  1047.  
  1048.         .                .
  1049.         .                .
  1050.     move.l    d0,Fhandle(a5)        move.l    d0,Fhandle(a5)
  1051.  
  1052.     tst.l    Fhandle(a5)        bne    .l5
  1053.     bne    .l5
  1054.  
  1055.  
  1056. o    The flags are set by the "move", so the "tst" instruction
  1057.     can be eliminated, saving 4 bytes and 9 cycles.
  1058.     ( a label before the "Fhandle = 0 {" statement disables this )
  1059.  
  1060.  
  1061.  
  1062.     foo > 10 {
  1063.         .
  1064.         .
  1065.         [jmp statement]
  1066.     } else {
  1067.         .
  1068.         .
  1069.     }
  1070.  
  1071. o    In cases where a [jmp statement] ( "jmp", "bra", "bra.s",
  1072.     "rts", "rte", "rtd" or "rtr" ) is immediately above
  1073.     the "else" ( above ), normal label generation ( etc. ) for
  1074.     jumping past "else" is eliminated.
  1075.  
  1076.  
  1077. *********************************************
  1078.  
  1079. General Info:
  1080.  
  1081.  
  1082. o    Statements can be indented as you like.  Operands, operator,
  1083.     and arguments must be separated by at least one space or tab. 
  1084.  
  1085. o    Braces can be nested up to 30 deep.
  1086.     
  1087. o    Only one statement per line.
  1088.  
  1089. o    Comments must begin with "*" or ";" and begin at column 1, or after
  1090.     statements ( separated from last argument or operand ) using ";".
  1091.     ( both types are transferred to the output file ( some may not ))
  1092.  
  1093. o    Operands supported:  @141 (octal),  $61 (hex),  %1100001 (binary),
  1094.     'a' (ASCII),  97  (decimal).  ASCII strings in operands can
  1095.     contain a maximum of 4 characters.
  1096.     ( no quotes within quotes permitted )    
  1097.  
  1098. o    To make labels and symbols as compatible as possible, they aren't
  1099.     checked for illegal characters.  Typically the 1st character
  1100.     must be a letter, underscore "_", or a period ".".
  1101.     The rest of the characters can be any of these plus 0-9.
  1102.  
  1103. o    Labels and symbols are limited to a length of 127.
  1104.     ( Check your assembler to find what length they're
  1105.     significant to ( usually around 30 ))
  1106.  
  1107. o    Labels that don't begin at column 1 must be followed immediately
  1108.     with ":", otherwise, use of ":" is optional.
  1109.  
  1110. o    Temporary labels of the form n$, where n consists of decimal
  1111.     digit(s), are supported.  These labels are only in effect till
  1112.     the next non-temporary label is encountered.  ( be careful
  1113.     of "hidden" labels generated by braces )
  1114.  
  1115. o    "moveq #0,d0", "rts" is automatically inserted for you in the
  1116.     closing block of code.  ( See also "NOEXTRAS" )
  1117.  
  1118. o    D7 is used as a scratch register for many optimizations, so be
  1119.     careful if you use it.
  1120.  
  1121. o    Labels and constants that are generated are in the range:
  1122.  
  1123.     ".l0" to ".ln"    Program labels
  1124.     ".c0" to ".cn"    String constants
  1125.     ".t0" to ".tn"    Tag list labels
  1126.  
  1127.     Try to avoid accidentally using them.
  1128.     ( See also "NODOT" )
  1129.  
  1130.   
  1131. o    "SP", "PC", "CCR", "SR" & "USP" ( upper or lower case )
  1132.     are supported, but you must ensure it's used correctly.
  1133.  
  1134. o    For best viewing of the output file, set your tabs to 8 spaces.
  1135.     ( printing should be fine )
  1136.  
  1137.  
  1138. IMPORTANT! :
  1139.  
  1140.     Don't use register A5!  It holds the base address of the
  1141.     stack frame used for variable storage.
  1142.  
  1143.  
  1144. *********************************************
  1145.  
  1146. Variable Declaration:
  1147.  
  1148.  
  1149. LONG    foo bar
  1150. WORD    DMASave
  1151. BYTE    Sw ViewPort[40] 
  1152.  
  1153.  
  1154. o    "xxx[n]" reserves n consecutive blocks of given size,
  1155.     with "xxx" pointing to the left-most byte.
  1156.     ( this is for advanced users who need a convenient
  1157.     way to allocate SMALL chunks of stack memory for structures,
  1158.     saving registers, etc. )
  1159.  
  1160. o    You're limited to 14 variables per line.
  1161.  
  1162. o    No other statement types may occur between these lines.
  1163.  
  1164. o    Variables must be separated by at least one space, or tab.
  1165.  
  1166. o    To keep things word aligned, if an odd number of variables are    
  1167.     declared in BYTE, an extra byte will be added.
  1168.     ( this will offset the next "equ" by one )
  1169.  
  1170. o    Declarations must occur JUST BEFORE your program code,
  1171.     and begin at column 1, with LONG, WORD, or BYTE in upper case.
  1172.  
  1173. o    EZAsm uses "link" to allocate space for variables on the stack.
  1174.     The maximum size of this space is 32K.  Since this stack space
  1175.     contains "garbage", code is added to clear it out before use.
  1176.     ( The frame size is now rounded up to the nearest LONG )
  1177.  
  1178. What the stack frame looks like:
  1179.  
  1180.  
  1181. LONG    foo
  1182. WORD    bar Total
  1183. LONG    Count
  1184.  
  1185.  
  1186. becomes...
  1187.  
  1188. foo    equ  -4
  1189. bar    equ  -6
  1190. Total  equ  -8
  1191. Count  equ  -12
  1192.  
  1193.  
  1194.         h  l           A5   base register
  1195.         i  o           |
  1196.         OOOO OO OO OOOOO    memory bytes
  1197.  (-) <- 1119 87 65 4321
  1198.         210
  1199.  
  1200.  
  1201.   ( Sometimes variables are "adjusted" for proper loading, and
  1202.   "-2(a5)" or other displacement may appear in the output file
  1203.   instead of "foo(a5)" or other variable name you might be expecting. )
  1204.  
  1205.  
  1206. *********************************************
  1207.  
  1208. General Info:
  1209.  
  1210.  
  1211. o    It's now much more forgiving about your placement of
  1212.     assembler directives, and smarter about detecting where
  1213.     your code starts.  If you experience any problems
  1214.     ( it hit an assembly directive it didn't recognize )    
  1215.     try placing your data statements below "END",
  1216.     and "equ", "xref" and "xdef" type directives above your
  1217.     variable declarations, or below "END".
  1218.     ( In the final .asm file "END" will be adjusted )
  1219.  
  1220. o    Instruction size:  IN MOST CASES YOU WON'T NEED
  1221.     A SIZE ARGUMENT.  It knows the size of your variables,
  1222.     address and data registers, and is smart enough to know
  1223.     what size to use.  You'll need to specify a size if
  1224.     the data is smaller than the instruction size you want,
  1225.     ( d1 = $20 w ) or it can't know the size of the operands
  1226.     ( (a2)+ = 3(a0) l ).
  1227.  
  1228.     Caution:  Be aware that if you load small variables into
  1229.           larger ones, the upper bytes aren't cleared and
  1230.           may garbage your result.  Always initialize those
  1231.           variables, or restrict the size of further
  1232.           operations to "b" or "w".
  1233.  
  1234. o    Try not to overuse the size arguments.  Once you get confident
  1235.     it's sizing your instructions correctly ( by checking the
  1236.     .asm file ) you'll find you can eliminate their use almost
  1237.     entirely.  By needlessly restricting a long operation to
  1238.     a word, or byte, you can miss the "quick" optimization.
  1239.  
  1240. o    Since "(a1)" refers to the CONTENTS of the byte, word, or long
  1241.     that A1 points to, "($dff180)" is used in a similar way.
  1242.     ( decimal addr's are also valid: "(14675968)" )
  1243.  
  1244. o    Numbers are "converted" for you. ( $f2 -> #$f2  37 -> #37 )
  1245.     Operands it doesn't recognize, like "wd_UserPort(a2)",
  1246.     are output "as is".
  1247.  
  1248. o    Large programs:  If your executable size is near 32K, it's
  1249.     possible that PC relative optimizations may turn off too soon,
  1250.     or stay on, incorrectly, when the displacement is exceeded.
  1251.  
  1252. o    If at any time you're unsure of what a statement is being
  1253.     output as, or want to check something out, just look
  1254.     at the output .asm file.  Well placed blank lines in your
  1255.     source code can enhance its readability.
  1256.  
  1257. o    I think it's a good idea to get away from using include files.
  1258.     Most assembly source files I see do this.
  1259.     It speeds up the assembler tremendously, and saves
  1260.     endless wear and tear on your drives.
  1261.  
  1262.  
  1263. ****************************************************
  1264.  
  1265. Converting C to EZAsm:
  1266.  
  1267.  
  1268.     Its fairly easy to convert any C code into
  1269.     EZAsm if you follow these guidelines:
  1270.  
  1271.  
  1272.   Allocating structures:
  1273.  
  1274.     Whenever you see "struct VSprite SpriteA" etc.,    
  1275.     you need to either allocate some memory for the
  1276.     structure, or set up your own:
  1277.  
  1278.  
  1279. CLEAR_PUBLIC    equ    $10001
  1280.  
  1281. LONG    SpriteA
  1282.  
  1283.  
  1284.     SpriteA = AllocMem( [structure size] #CLEAR_PUBLIC )
  1285.     beq    Exit
  1286.  
  1287. ---------- or ----------------
  1288.  
  1289. SpriteA    ds.w    0    ;align
  1290.     dc.l    0    ;NextVSprite    
  1291.     dc.l    0    ;PrevVSprite
  1292.     .
  1293.     .
  1294.  
  1295.  
  1296.     ( you could use "#vs_SIZEOF" etc. for [structure size]    
  1297.     and let the assembler get its size from the includes )
  1298.  
  1299.     Some functions will create the structures for you
  1300.     and return a pointer to it ( OpenWindow(), OpenScreen()
  1301.     etc. ) just declare a LONG, and load the returned pointer:
  1302.  
  1303. LONG    Window
  1304.  
  1305.     Window = OpenWindow( #NewWindow )
  1306.     beq    Exit
  1307.  
  1308.  
  1309.   Accessing structure elements:
  1310.  
  1311.     Often you'll need to get at data inside structures.
  1312.     First load the "structure pointer" into an address
  1313.     register, then use the offset of the structure element.
  1314.     Here's a typical example:
  1315.  
  1316.     Move( Window->RPort, 20, 20 );    /* C */
  1317.  
  1318.  
  1319.     a0 = Window
  1320.     Move( wd_RPort(a0) 20 20 )
  1321.  
  1322.     ---- or ----
  1323.  
  1324.     a0 = Window    
  1325.     Move( 50(a0) 20 20 )
  1326.  
  1327.  
  1328.     ( add an include to your source, and the assembler
  1329.     will look-up "wd_RPort" and substitute its offset or,
  1330.     even better, use "50(a0)" )
  1331.  
  1332.  
  1333.     !!! See the included file StructOffsets !!!
  1334.  
  1335.  
  1336.     Be sure to convert BPTRs ( left shift 'um 2 bits )
  1337.     before using them:
  1338.  
  1339.  
  1340.         a3 = _DOSBase
  1341.  
  1342.         Forbid()
  1343.  
  1344.         a3 = 34(a3)        ;dl_Root
  1345.         a3 = 24(a3)        ;rn_Info
  1346.  
  1347.         add.l    a3,a3    ;convert BPTR
  1348.         add.l    a3,a3
  1349.  
  1350.         .
  1351.         .
  1352.  
  1353.  
  1354. *********************************************
  1355.  
  1356. Errors:
  1357.  
  1358.  
  1359. "Illegal argument"
  1360.  
  1361.     The argument found was not valid for the operator.  See
  1362.     the list of "Optional Args" for the operator.  It must
  1363.     be lower case, and be separated from the operands
  1364.     by at least a space or a tab.
  1365.     
  1366. "Illegal operand"
  1367.  
  1368.     One, or both, of the operands are:  not valid for the operator,
  1369.     have an invalid number, or byte size was specified for an
  1370.     "An" operand ( {B} ).  In most cases it's looking for "Dn" or "An"
  1371.     as one of the operands.  ( look under the "legal operands"
  1372.     of the operator for a valid combination )
  1373.  
  1374. "Illegal size"
  1375.  
  1376.     The argument size you specified is not valid for the operator.    
  1377.     Check the "legal sizes" for the operator.
  1378.     
  1379. "Needs size argument"    
  1380.  
  1381.     It doesn't have enough size information about the operands to
  1382.     calculate an instruction size.
  1383.     You need to add an l, w, or b argument.
  1384.  
  1385. "Label not found"
  1386.  
  1387.     No label matching your label argument was found.    
  1388.  
  1389. "Brace mismatch"
  1390.  
  1391.     Checks are made when a closing brace ( "}" ) is hit, and when "END"
  1392.     is hit.  If the brace stack is "messed up" at that time, an error 
  1393.     is given.  If "}" is shown, look from there up.  Both "}" and "END"
  1394.     may appear.  If just "END", look for a "{" or "} else {" without a
  1395.     matching "}".
  1396.  
  1397. "Function not found"
  1398.  
  1399.     No function matching your function name was found.  Check case and    
  1400.     spelling of function name, and be sure there isn't a space before
  1401.     the "(".  Check the list of supported function names in the
  1402.     file "nm1".
  1403.  
  1404. "Function argument count incorrect"
  1405.  
  1406.     Check the number of arguments you used for the function.  Too many
  1407.     or not enough were used.  With string arguments, check for
  1408.     a missing '"'.  Also look for a missing end ")".
  1409.  
  1410.  
  1411. ( EZAsm doesn't do much checking of normal assembly statements.
  1412. A68k and Blink will catch any problems missed by EZAsm and bring
  1413. them to your attention )
  1414.  
  1415.  
  1416. *******************************************************************
  1417. *******************************************************************
  1418.  
  1419.  
  1420.     Try using EZAsm, I don't think you'll want to go back to
  1421.     "ordinary" assembly language programming. 8^)
  1422.  
  1423.     Why isn't EZAsm shareware?  I don't think you can make much
  1424.     money with shareware.  I'd like to get it into the hands
  1425.     of as many interested people as possible because I believe
  1426.     it'll really make a difference.  If you have any suggestions
  1427.     for improvements, found bugs, or just want to say "hello",
  1428.     please write, I'd like to hear from you!
  1429.  
  1430.  
  1431.     Enjoy!
  1432.  
  1433.  
  1434.  
  1435. You can reach me at:
  1436.  
  1437. Joe Siebenmann
  1438. 2204 Pimmit Run Lane  Apt 1
  1439. Falls Church, VA  22043
  1440. ( USA )
  1441.  
  1442. (703) 893-2579
  1443.  
  1444.  
  1445.