home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilsd / extbasdis / ExtBasDoc < prev   
Text File  |  1996-03-03  |  11KB  |  365 lines
  1. Extended BASIC Assembler
  2. ————————————————————————
  3. Version 1.67, 3 March 1996
  4. by Darren Salt
  5. Contains code from v1.00 and v1.30 by Adrian Lees
  6.  
  7.  
  8. The module ExtBASICasm provides a patch for versions 1.05, 1.06 and 1.14 of
  9. BASIC V, as supplied with RISC OS 3.1, 3.5 and 3.6 respectively, to allow the
  10. direct use of the extra instructions provided by the ARM3, ARM6 and ARM7
  11. processors. The missing floating-point and general coprocessor instructions,
  12. and some assembler directives more familiar to Acorn Assembler users have
  13. been added; also the APCS-R register names may be used.
  14.  
  15. To make the necessary changes to the BASIC module it must be located in RAM.
  16. The ExtBASICasm module will therefore attempt to RMFaster the BASIC module
  17. which will require a small amount of memory in the RMA, in addition to that
  18. required by the ExtBASICasm module itself. More importantly, BASIC must not
  19. be active, ie. running, at the time because then the module cannot be removed
  20. to allow it to be moved. Loading ExtBASICasm should therefore be performed at
  21. the command line. It is safe to do this from the ShellCLI, ie. whilst the
  22. desktop is active, even with BASIC programs running because BASIC holds all
  23. its information within the application workspace.
  24.  
  25. The instructions added by the module are as follows:
  26.  
  27. Extensions
  28. ——————————
  29. OPT    <value>
  30.     Bit 4: ASSERT control (1 = enabled on 'second pass')
  31.     Bit 5: LDC/STC T flag control (1 = automatically set)
  32.     Bit 6: UMUL/UMULL control (0 = short forms, 1 = long forms)
  33.  
  34. MUL{cond}{S}    Rd,Rm,<#const>
  35.     variable length; Rd=Rm if <2 ADD/RSB
  36.     May cause 'duplicate register' if Rd=Rm and const is not simple - ie.
  37.     not 0, (2^x)-1, 2^x, (2^x+2^y)
  38.  
  39. MLA{cond}{S}    Rd,Rm,<#const>,Ra
  40.     variable length; Rd=Rm if <2 ADD/RSB
  41.     Rd=Ra causes 'duplicate register' error if const is not simple, as
  42.     for MUL; Rd=Rm=Ra is special in that MLA Rd,Rd,#c,Rd = MUL Rd,Rd,#c+1
  43.     If Rd=Ra and const=0, no code is generated (none necessary).
  44.  
  45. DIV        Rq,Rr,Rn,Rd,Rt [SGN Rs]
  46.     Integer division by register
  47.     Rq = quotient        Rn = numerator        Rt = temporary store
  48.     Rr = remainder        Rd = denominator    Rs = sign store
  49.     If Rs omitted then division is unsigned.
  50.     Rr may be same register as Rn *or* Rn may be same as Rs.
  51.     All other registers must be different.
  52.     Rt and Rs (if specified) are corrupted.
  53.  
  54. DIV        Rq,Rr,Rn,#d[,[Rt]] [SGN Rs]
  55.     Integer division by constant
  56.     Registers as above
  57.     If Rs omitted then division is unsigned.
  58.     If Rt omitted and is required for this division then error given.
  59.     All registers must be different.
  60.     If specified, Rt and Rs are corrupted.
  61.     (Uses generator to build code - fast but may be long)
  62.     Notes:    Uses Fourier method. For unsigned values, this is fixed to
  63.         handle unsigned top-bit-set properly, *except* for div by 3
  64.         which works for values up to &C0000000. Ideas and code
  65.         gratefully received...
  66.  
  67.     *** Note no conditional!
  68.  
  69. ADR{cond}L    Rd,<const>
  70.     Fixed length (two words)
  71.  
  72. ADR{cond}X    Rd,<const>
  73.     Fixed length (three words)
  74.  
  75. ADR{cond}W    Rd,<const>
  76.     Addressing relative to R12, one to three words
  77.     <const> MUST be defined before it is used
  78.     Adds/subtracts const to/from R12, storing result in Rd
  79.     Up to you to ensure that R12 correctly set up...
  80.  
  81. LDR, STR:
  82.     XXX{cond}{B}W    Rd,<offset>
  83.     Load/store word/byte at [R12,#<offset>]
  84.  
  85.     Also supported are the new ARM7M forms:
  86.     LDRxxH, LDRxxSH, LDRxxSB and equivalent STRs
  87.     The standard forms are used, with the following exceptions:
  88.         - no shifts
  89.         - constant offsets in range 0 to 255, +ve and -ve
  90.     The W forms are also supported.
  91.  
  92. SWAP{cond}    Rd,Rn
  93.     Swaps Rd and Rn without using temporary store
  94.     Uses EOR method, is therefore three words long
  95.  
  96.  
  97. VDU{cond}{X}    <const>
  98.     = SWI "OS_WriteI"+<const>
  99.     With X present, XOS_WriteI is used instead.
  100.  
  101. NOP{cond}
  102.     = MOV{cond} R0,R0
  103.  
  104.  
  105. EQUx, DCx, =
  106.     XXX <value>[,<value>]^
  107.     Extended form of EQUD, EQUW, DCB, etc.
  108.     Instead of, eg. DCD 0 : DCD 12 : DCD branch
  109.     you can now use DCD 0, 12, branch
  110.  
  111.  
  112. ARM3 and later (including ARM250)
  113. —————————————————————————————————
  114.  
  115. SWP{cond}{B}    Rd,Rm,[Rn]
  116.  
  117.  
  118. ARM6 and later
  119. ——————————————
  120.  
  121. MRS{cond}    Rd,<psr>
  122. MSR{cond}    <psr{f}>,Rm
  123.  
  124.  
  125. ARM7 and later
  126. ——————————————
  127.  
  128. UMUL, SMUL, UMLA, SMLA:
  129.     xxx{cond}{S}    Rl,Rh,Rm,Rn
  130.  
  131.     The 'official' forms UMULL, SMULL, UMLAL, SMLAL are used *instead of*
  132.     the 'short' forms if OPT bit 6 is set.
  133.     Unfortunately it's not possible to allow both forms at once: how
  134.     would you interpret "UMULLS" - UMUL condition LS or UMULL with S bit?
  135.  
  136.  
  137. Floating-point instructions
  138. ———————————————————————————
  139.  
  140. Floating point coprocessor data transfer
  141.  
  142. LDF, STF:
  143.     xxx{cond}prec    Fd,[Rn]{,#offset}
  144.     xxx{cond}prec    Fd,[Rn,#offset]{!}
  145.     xxx{cond}prec    Fd,<label | const>
  146.  
  147. LFM, SFM:
  148.     xxx{cond}    Fd,m,[Rn]{,#offset}
  149.     xxx{cond}    Fd,m,[Rn,#offset]{!}
  150.     xxx{cond}    Fd,m,<label | const>
  151.  
  152. LFM{cond}{stack}    Fd,m,[Rn]{!}
  153. SFM{cond}{stack}    Fd,m,[Rn]{!}
  154. LFS{cond}{stack}    Rn{!},<fp register list>
  155. LFS{cond}{stack}    Rn{!},<fp register list>
  156.  
  157.     LFM, SFM, LFS and SFS use extended precision. The <fp register list>
  158.     is much as for LDM and STM, with restrictions: you must specify a
  159.     register or a sequence of registers, and the list must be compatible
  160.     with LFM and SFM - eg.
  161.     LFSFD R13!,{F3}        LFMFD F3,1,[R13]!    LFM F3,1,[R13],#12
  162.     SFSFD R13!,{F5-F0}    SFMFD F5,4,[R13]!    SFM F5,4,[R13,#-36]!
  163.     LFSDB R13,{F1,F0}    LFMDB F0,2,[R13]    LFM R0,2,[R13,#-24]
  164.     - for each row, all the instructions have the same effect.
  165.     Available stack types are DB, IA, EA, FD.
  166.     Note that example 2 wraps around - F5, F6, F7, F0 _in that order_.
  167.  
  168. * Floating point coprocessor register transfer
  169.  
  170. FLT{cond}prec{round}    Fn,Rd
  171. FIX{cond}{round}    Rd,Fn
  172. WFS, RFS, WFC, RFC:
  173.     xxx{cond}    Rd
  174.  
  175. * Floating point coprocessor data operations
  176.  
  177. ADF, MUF, SUF, RSF, DVF, RDF, POW, RPW, RMF, FML, FDV, FRD, POL:
  178.     xxx{cond}prec{round}    Fd,Fn,<Fm | #value>
  179.  
  180. MVF, MNF, ABS, RND, SQT, LOG, LGN, EXP,
  181. SIN, COS, TAN, ASN, ACN, ATN, URD, NRM:
  182.     xxx{cond}prec{round}    Fd,<Fm | #value>
  183.  
  184. * Floating point coprocessor status transfer
  185.  
  186. CMF, CNF, CMFE, CNFE:
  187.     xxx{cond}    Fm,Fn
  188.  
  189.  
  190. General co-processor instructions
  191. —————————————————————————————————
  192.  
  193. * Coprocessor data operations
  194.  
  195. CDO, CDP:
  196.     xxx{cond}    CP#,copro_opcode,Cd,Cn,Cm{,const}
  197.  
  198.     The values of copro_opcode and the optional constant must lie within
  199.     the range 0..15.
  200.  
  201. * Coprocessor data transfer
  202.  
  203. MCR, MCR:
  204.     xxx{cond}    CP#,<const1>,Rd,Cn,Cm{,<const2>}
  205.  
  206. LDC, STC:
  207.     xxx{cond}{L}{T}    CP#,Cd,[Rn]{,#offset}
  208.     xxx{cond}{L}    CP#,Cd,[Rn{,#offset}]{!}
  209.  
  210.     L and T may be specified in either order. So if you want an
  211.     unconditional LDC with both flags set, use LDCTL or LDCALLT since
  212.     LDCLT will be assembled as "LDC with T and L clear, if less than".
  213.     Also, setting bit 5 of the OPT value causes the W flag to be set
  214.     automatically (in the pre-indexed form).
  215.  
  216.  
  217. Assembler directives
  218. ————————————————————
  219.  
  220. * Conditional - will STOP if expression is FALSE:
  221.  
  222. ASSERT    <expression>
  223.  
  224.     Bit 4 of the OPT value controls ASSERT. When it and bit 1 are zero,
  225.     ASSERTs are ignored.
  226.  
  227. * Constants
  228.  
  229. =    <const|string>[,<const|string>]*
  230.     The bug causing an error when used in the form
  231.         .label    = "something"
  232.     has been fixed.
  233.  
  234. EQUFS, EQUFD, EQUFE, EQUFP, EQUF
  235.     xxx    <const>
  236.  
  237. and the DC.. and |.. equivalents.
  238.  
  239.     These directives accept an expression that evaluates to either an
  240.     integer or a real number. The result is then converted into the
  241.     required precision and stored in the object code at P%, or O% if
  242.     indirect assembly is being used. EQUF is a synonym for EQUFD.
  243.  
  244.     directive    EQUFS    EQUFD    EQUFE    EQUFP
  245.     bytes used    4    8    12    12
  246.  
  247. EQUP, DCP, P
  248.     xxx    <string>,<const>
  249.     xxx    <const>,<string>
  250.     Fixed-length string allocation. If the string is too short, then the
  251.     remaining space is padded with nulls; if it is too long, it is
  252.     truncated to the specified length.
  253.  
  254. EQUZ, DCZ, Z
  255.     xxx    <string>
  256.     EQUS with automatic zero termination
  257.  
  258.     Note: *ALL* the EQU... directives (and their equivalents) may have
  259.     their arguments repeated as described in the Extensions section.
  260.  
  261. FILL, %
  262.     xxx    <const>{,<byte>}
  263.     Allocates <const> bytes of memory, initialised to <byte> (or 0).
  264.     If comma is present but no fill byte, then no initialisation is done.
  265.  
  266. FILE    <filename>
  267.     Loads the specified file, allocating just enough space for it.
  268.  
  269. ^    <offset>
  270.     Initialises the workspace address pointer to the given value.
  271.     This is used and updated by #.
  272.     Typical use:
  273.         ^ 0