home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / extbasdis_2 / ExtBasDoc < prev   
Text File  |  1997-07-30  |  14KB  |  446 lines
  1. Extended BASIC Assembler
  2. ————————————————————————
  3. Version 1.76, 30 July 1997
  4. by Darren Salt <arcsalt@spuddy.mew.co.uk>
  5. Contains code from v1.00 and v1.30 by Adrian Lees
  6.  
  7.  
  8. It is recommended that you read through this document before first using
  9. ExtBASICasm, and check through it quickly when upgrading. It's entirely
  10. possible that one of the extras the module provides may cause a clash with
  11. existing programs, for example the APCS-R register names clashing with
  12. variables used as register names.
  13.  
  14. Note also that APCS-R register names are disabled by default.
  15.  
  16.  
  17. The module ExtBASICasm provides a patch for versions 1.05, 1.06, 1.14 and
  18. 1.16 of BASIC V, as supplied with RISC OS 3.1, 3.5, 3.6 and 3.7 respectively,
  19. to allow the direct use of the extra instructions provided by the ARM3, ARM6,
  20. ARM7, ARM8 and StrongARM processors. The missing floating-point and general
  21. coprocessor instructions, and some assembler directives more familiar (and a
  22. few unfamiliar) to Acorn Assembler users have been added; also the APCS-R
  23. register names may be used.
  24.  
  25. To make the necessary changes to the BASIC module it must be located in RAM.
  26. The ExtBASICasm module will therefore attempt to RMFaster the BASIC module
  27. which will require a small amount of memory in the RMA, in addition to that
  28. required by the ExtBASICasm module itself. Attempting to run it while BASIC
  29. is active and in ROM will not work - try "*RMFaster BASIC" at the BASIC
  30. prompt and you'll see why.
  31.  
  32. The instructions added by the module are as follows:
  33.  
  34.  
  35. Extensions
  36. ——————————
  37.  
  38.     Optional parts are enclosed in {}
  39.  
  40. OPT    <value>
  41.     Bit 4:    ASSERT control (1 = enabled on 'second pass')
  42.     Bit 5:  APCS register names (1 = enabled)
  43.     Bit 6:    UMUL/UMULL control (0 = short forms, 1 = long forms)
  44.  
  45. ALIGN
  46.     Zero-initialises the memory if required.
  47.  
  48. ALIGN    <const>[,<const2>]
  49.     Aligns to a multiple of const bytes plus an optional offset. const
  50.     must be a power of 2 between 1 and 65536; const2 must be between 0
  51.     and const-1 (default is 0). Also zero-initialises the memory.
  52.     P% becomes (P% AND const-1)+const2; O% is also updated if necessary.
  53.     Examples:
  54.         ALIGN 4
  55.         ALIGN 32
  56.         ALIGN 16,8
  57.  
  58. MUL{cond}{S}    Rd,Rm,#<const>
  59.     variable length; Rd=Rm if <2 ADD/RSB
  60.     May cause 'duplicate register' if Rd=Rm and const is not simple - ie.
  61.     not 0, (2^x)-1, 2^x, (2^x)+(2^y)
  62.  
  63. MLA{cond}{S}    Rd,Rm,#<const>,Ra
  64.     variable length; Rd=Rm if <2 ADD/RSB
  65.     Rd=Ra causes 'duplicate register' error if const is not simple, as
  66.     for MUL; Rd=Rm=Ra is special in that MLA Rd,Rd,#c,Rd = MUL Rd,Rd,#c+1
  67.     If Rd=Ra and const=0, no code is generated (none necessary).
  68.  
  69. DIV        Rq,Rr,Rn,Rd,Rt [SGN Rs]
  70.     Integer division by register
  71.     Rq = quotient        Rn = numerator        Rt = temporary store
  72.     Rr = remainder        Rd = denominator    Rs = sign store
  73.     If Rs omitted then division is unsigned.
  74.     Rr may be same register as Rn *or* Rn may be same as Rs.
  75.     All other registers must be different.
  76.     Rt and Rs (if specified) are corrupted.
  77.  
  78. DIV        Rq,Rr,Rn,#d[,[Rt]] [SGN Rs]
  79.     Integer division by constant
  80.     Registers as above
  81.     If Rs omitted then division is unsigned.
  82.     If Rt omitted and is required for this division then error given.
  83.     All registers must be different.
  84.     If specified, Rt and Rs are corrupted.
  85.     (Uses generator to build code - fast but may be long)
  86.     Notes:    Uses Fourier method. For unsigned values, this is fixed to
  87.         handle unsigned top-bit-set properly, *except* for div by 3
  88.         which works for values up to &C0000000. Ideas and code
  89.         gratefully received...
  90.  
  91.     *** Note no conditional for either form of DIV!
  92.  
  93. ADR{cond}L    Rd,<const>
  94.     Fixed length (two words)
  95.  
  96. ADR{cond}X    Rd,<const>
  97.     Fixed length (three words)
  98.  
  99. ADR{cond}W    Rd,<const>
  100.     Addressing relative to R12, one to three words
  101.     <const> MUST be defined before it is used
  102.     Adds/subtracts const to/from R12, storing result in Rd
  103.     Up to you to ensure that R12 correctly set up...
  104.  
  105. LDR, STR
  106.     xxx{cond}{B}W    Rd,<offset>
  107.       Load/store word/byte at [R12,#<offset>]
  108.  
  109.     LDR{cond}{B}L    Rd,<address>
  110.     LDR{cond}{B}L    Rd,[Rm,#<offset>]{!}
  111.     LDR{cond}{B}WL    Rd,<offset>
  112.     STR equivalents
  113.       Addressing range is ±1MB; some offsets outside this range are also
  114.       valid. Lengths are (in words):
  115.         LDR        2  ADD/SUB Rd,Rm,#a:LDR Rd,[Rd,#b]
  116.         LDR ...]!  2  ADD/SUB Rd,Rm,#a:LDR Rd,[Rd,#b]!
  117.         STR        3  ADD/SUB Rm,Rm,#a:STR Rd,[Rm,#b]:SUB/ADD Rm,Rm,#a
  118.         STR ...]!  2  ADD/SUB Rm,Rm,#a:STR Rd,[Rm,#b]!
  119.  
  120.     LDR{cond}{B}L    Rd,{Rn},<address>
  121.     LDR{cond}{B}L    Rd,{Rn},[Rm,#<offset>]
  122.     LDR{cond}{B}WL    Rd,{Rn},<offset>
  123.     STR equivalents
  124.       [{Rn} is NOT optional]
  125.       Equivalent to the LDR/STRs above, except that Rn (rather than Rd)
  126.       is used to hold the address; always two words long. For example,
  127.       ADRL R0,wibble:LDR R1,[R0] may be replaced with LDRL R1,{R0},wibble
  128.       - one word shorter.
  129.       Rd=Rn is not allowed.
  130.       Assembles to ADD/SUB Rn,Rm,#a : LDR/STR Rd,[Rn,#b]!
  131.  
  132.     LDR{cond}{B}L    Rd,[Rm],#<offset>
  133.     STR equivalent
  134.       Addressing range is ±1MB; some offsets outside this range are also
  135.       valid. Two words long.
  136.       Assembles to LDR/STR Rd,[Rm],#b:ADD/SUB Rm,Rm,#a
  137.  
  138.     NOTE: You should try to avoid using *sequences* of LDRLs or STRLs -
  139.     there is usually a more efficient way.
  140.  
  141.     Also supported are the new ARM7M and StrongARM forms:
  142.     LDRxxH, LDRxxSH, LDRxxSB and STRxxH
  143.         The standard forms are used, with the following exceptions:
  144.             - no shifts
  145.             - constant offsets in range -255 to 255
  146.         The W forms are also supported.
  147.         Long LDR{H|SH|SB} not yet implemented.
  148.  
  149. SWAP{cond}[S]    Rd,Rn
  150.     Swaps Rd and Rn without using temporary store.
  151.     Uses EOR method, is therefore three words long.
  152.     If S is specified, then the flags are set according to Rn.
  153.  
  154. VDU{cond}{X}    <const>
  155.     = SWI "OS_WriteI"+<const>
  156.     With X present, XOS_WriteI is used instead.
  157.  
  158. NOP{cond}
  159.     = MOV{cond} R0,R0
  160.  
  161. BRK{cond} [#<const>]
  162.     Undefined instruction. If <const> is specified, then R14 is set to
  163.     this value before the undefined instruction trap is taken.
  164.  
  165. EQUx, DCx, =
  166.     xxx <value>[,<value>]^
  167.     Extended form of EQUD, EQUW, DCB, etc.
  168.     Instead of, eg. DCD 0 : DCD 12 : DCD branch
  169.     you can now use DCD 0, 12, branch
  170.  
  171. Negative constants
  172.     Allowed in the following instructions:
  173.         ADD, SUB    ADC, SBC    ADF, SUF
  174.         AND, BIC    MOV, MVN    MVF, MNF
  175.         CMP, CMN    CMF, CNF    CMFE, CNFE
  176.     If the constant is invalid for one of these, it is negated or
  177.     inverted, as appropriate, and the instruction changed to the other of
  178.     the pair (eg. ADC becomes SBC). If the constant is still invalid, the
  179.     "bad immediate constant" error is generated as normal.
  180.  
  181.  
  182. ARMv2a (ARM3, ARM250) and later
  183. ———————————————————————————————
  184.  
  185. SWP{cond}{B}    Rd,Rm,[Rn]
  186.  
  187.  
  188. ARMv3 (ARM6) and later
  189. ——————————————————————
  190.  
  191. MRS{cond}    Rd,<psr>
  192.     <psr> may only be CPSR or CPSR_all, or SPSR equivalents
  193.  
  194. MSR{cond}    <psr><f>,Rm
  195.     <psr> must be CPSR_ or SPSR_, and <f> must be one of the following:
  196.         _ctl    control bits only
  197.         _flg    flag bits only
  198.         _all    both
  199.     or a combination of _c, _x, _s, _f. _c_f, _cf, _f_c, _fc are all
  200.     equivalent to _all.
  201.  
  202.  
  203. ARMv4 (ARM8, StrongARM) and later
  204. —————————————————————————————————
  205.  
  206. UMUL, SMUL, UMLA, SMLA:
  207.     xxx{cond}{S}    Rl,Rh,Rm,Rn
  208.  
  209.     The 'official' forms UMULL, SMULL, UMLAL, SMLAL are used *instead of*
  210.     the 'short' forms if OPT bit 6 is set.
  211.     Unfortunately it's not possible to allow both forms at once: how
  212.     would you interpret "UMULLS" - UMUL condition LS or UMULL with S bit?
  213.  
  214.  
  215. Floating-point instructions
  216. ———————————————————————————
  217.  
  218. Floating point coprocessor data transfer
  219.  
  220. LDF, STF:
  221.     xxx{cond}prec    Fd,[Rn]{,#<offset>}
  222.     xxx{cond}prec    Fd,[Rn,#<offset>]{!}
  223.     xxx{cond}prec    Fd,<label | const>
  224.     xxx{cond}precW    Fd,<offset>
  225.  
  226. LFM, SFM:
  227.     xxx{cond}    Fd,m,[Rn]{,#<offset>}
  228.     xxx{cond}    Fd,m,[Rn,#<offset>]{!}
  229.     xxx{cond}    Fd,m,<label | const>
  230.  
  231. LFM{cond}{stack}    Fd,m,[Rn]{!}
  232. SFM{cond}{stack}    Fd,m,[Rn]{!}
  233. LFS{cond}{stack}    Rn{!},<fp register list>
  234. LFS{cond}{stack}    Rn{!},<fp register list>
  235.  
  236.     LFM, SFM, LFS and SFS use extended precision. The <fp register list>
  237.     is much as for LDM and STM, with restrictions: you must specify a
  238.     register or a sequence of registers, and the list must be compatible
  239.     with LFM and SFM - eg.
  240.     LFSFD R13!,{F3}        LFMFD F3,1,[R13]!    LFM F3,1,[R13],#12
  241.     SFSFD R13!,{F5-F0}    SFMFD F5,4,[R13]!    SFM F5,4,[R13,#-36]!
  242.     LFSDB R13,{F1,F0}    LFMDB F0,2,[R13]    LFM F0,2,[R13,#-24]
  243.     - for each row, all the instructions have the same effect.
  244.     Available stack types are DB, IA, EA, FD.
  245.     Note that example 2 wraps around - F5, F6, F7, F0 _in that order_.
  246.  
  247. * Floating point coprocessor register transfer
  248.  
  249. FLT{cond}prec{round}    Fn,Rd
  250. FIX{cond}{round}    Rd,Fn
  251. WFS, RFS, WFC, RFC:
  252.     xxx{cond}    Rd
  253.  
  254. * Floating point coprocessor data operations
  255.  
  256. ADF, MUF, SUF, RSF, DVF, RDF, POW, RPW, RMF, FML, FDV, FRD, POL:
  257.     xxx{cond}prec{round}    Fd,Fn,<Fm | #value>
  258.  
  259. MVF, MNF, ABS, RND, SQT, LOG, LGN, EXP,
  260. SIN, COS, TAN, ASN, ACS, ATN, URD, NRM:
  261.     xxx{cond}prec{round}    Fd,<Fm | #value>
  262.  
  263. * Floating point coprocessor status transfer
  264.  
  265. CMF, CNF, CMFE, CNFE:
  266.     xxx{cond}    Fm,<Fn | #value>
  267.  
  268.  
  269. General co-processor instructions
  270. —————————————————————————————————
  271.  
  272. * Coprocessor data operations
  273.  
  274. CDO, CDP:
  275.     xxx{cond}    CP#,copro_opcode,Cd,Cn,Cm{,<const>}
  276.  
  277.     The values of copro_opcode and the optional constant must lie within
  278.     the range 0..15.
  279.  
  280. * Coprocessor data transfer
  281.  
  282. MCR, MCR:
  283.     xxx{cond}    CP#,<const1>,Rd,Cn,Cm{,<const2>}
  284.  
  285. LDC, STC:
  286.     xxx{cond}{L}{T}    CP#,Cd,[Rn]{,#offset}
  287.     xxx{cond}{L}    CP#,Cd,[Rn{,#offset}]{!}
  288.  
  289.     L and T may be specified in either order. So if you want an
  290.     unconditional LDC with both flags set, use LDCTL or LDCALLT since
  291.     LDCLT will be assembled as "LDC with T and L clear, if less than".
  292.     The T flag is retained for compatibility reasons; it is automatically
  293.     set anyway.
  294.  
  295.  
  296. Assembler directives
  297. ————————————————————
  298.  
  299. * Conditional - will STOP if expression is FALSE:
  300.  
  301. ASSERT    <expression>
  302.  
  303.     Bit 4 of the OPT value controls ASSERT. When it and bit 1 are zero,
  304.     ASSERTs are ignored.
  305.  
  306. * Constants
  307.  
  308. =    <const|string>
  309.     The bug causing an error when used in the form
  310.         .label = "something"
  311.     has been fixed.
  312.  
  313. EQUFS, EQUFD, EQUFE, EQUFP, EQUF
  314.     xxx    <const>
  315.  
  316. also the DC.. and |.. equivalents
  317.  
  318.     These directives accept an expression that evaluates to either an
  319.     integer or a real number. The result is then converted into the
  320.     required precision and stored in the object code at P%, or O% if
  321.     indirect assembly is being used. EQUF is a synonym for EQUFD.
  322.  
  323.     directive    EQUFS    EQUFD    EQUFE    EQUFP
  324.     bytes used    4    8    12    12
  325.  
  326. EQUP, DCP, P
  327.     xxx    <string>,<const>
  328.     xxx    <const>,<string>
  329.     Fixed-length string allocation. If the string is too short, then the
  330.     remaining space is padded with nulls; if it is too long, it is
  331.     truncated to the specified length.
  332.  
  333. EQUPW, DCPW, PW
  334.     xxx    <pad_byte>,<string>,<const>
  335.     xxx    <pad_byte>,<const>,<string>
  336.     Like EQUP, except that you specify the padding byte.
  337.  
  338. EQUZ, DCZ, Z
  339.     xxx    <string>
  340.     EQUS with automatic zero termination
  341.  
  342. EQUZA, DCZA, ZA
  343.     xxx    <string>
  344.     Equivalent to EQUZ followed by ALIGN
  345.  
  346.     Note: *ALL* the EQU... directives (and their equivalents) may have
  347.     their arguments repeated as described in the Extensions section.
  348.  
  349. FILL, %
  350.     xxx{B|W|D}    <const>{,{<value>}}
  351.     Allocates <const> bytes of memory, initialised to <value> (or 0).
  352.     B, W and D represent data lengths as for EQU; if omitted, then byte
  353.     length is assumed. If the comma is present but no fill value, this is
  354.     equivalent to adding the constant to P% (and O% if appropriate).
  355.  
  356. FILE    <filename>
  357.     Loads the specified file, allocating just enough space for it.
  358.  
  359. ^    <offset>
  360.     Initialises the workspace address pointer to the given value.
  361.     This is used and updated by #.
  362.     Typical use:
  363.         ^ 0
  364.         ...
  365.         # flags, 4
  366.         ...
  367.         LDRW    R0,flags
  368.  
  369. #    <variable>, <length>
  370.     Sets the variable to the current value of the workspace address
  371.     pointer, which is then incremented by <length>.
  372.     This does not alter P% or O%.
  373.     (Note: the variable is assigned before the length is evaluated.)
  374.  
  375. COND    <cond>
  376.     Sets the condition code for use with = (when used as a condition
  377.     code). It may be supplied as a condition code literal, a number (0 to
  378.     15), or a string containing a condition code literal. For example,
  379.     all of the following are equivalent:
  380.         COND    7        ; number
  381.         COND    VC        ; condition code literal
  382.         COND    vc        ; condition code literal
  383.         COND    "Vc"        ; string containing cond. code lit.
  384.     Example code:
  385.         COND    LT        ; select LT condition code
  386.         MOV=    R0,#2        ; MOVLT  R0,#2
  387.         MOV=S    R1,R2        ; MOVLTS R1,R2
  388.  
  389.  
  390. Notes
  391. —————
  392.  
  393. * Registers are specified in the following form:
  394.  
  395.     ARM registers:            R0..R15
  396.         using APCS-R names:    A1..A4 V1..V6 SL FP IP SP LR PC
  397.     Floating-point registers:    F0..F7
  398.     General co-processor registers:    C0..C15
  399.  
  400.   To help cope with any potential name clashes, the floating point and APCS-R
  401.   register names (except for PC) must be terminated with some character not
  402.   valid in a variable name in order to be recognised; they are otherwise
  403.   treated as part of a variable name.
  404.  
  405. * Coprocessor numbers (CP#) may be specified using either of the following
  406.   forms:
  407.  
  408.     P0..P15
  409.     CP0..CP15
  410.  
  411. * Wherever a register or coprocessor number is specified, an expression may
  412.   be substituted in the usual manner allowed by BASIC V. This module employs
  413.   the routines used within BASIC to evaluate all expressions (eg. register
  414.   numbers, offsets and labels) and hence its interpretation of expressions is
  415.   guaranteed to be the same as BASIC.
  416.  
  417.  
  418. Credits
  419. ———————
  420.  
  421.   Adrian Lees (last known at A.M.Lees-CSEE93@@cs.bham.ac.uk):
  422.   - for the original ExtBas and the EQU comma extension, and for the use of
  423.     some of his code
  424.  
  425.   Michael Rozdoba (formerly of TechForum / Acorn Answers):
  426.   - for including the "General recursive method for Rb := Ra * C, C a
  427.     constant" from Appendix C of the manual for Acorn's desktop assembler,
  428.     and the late Acorn Computing (Sept 1994) for printing it;
  429.   - for the division code generator (Archimedes World, May 1995), which was
  430.     included, slightly trimmed, and debugged to handle top-bit-set unsigned
  431.     numbers properly... I hope!
  432.  
  433.   Dominic Symes of !Zap fame (dominic.symes@armltd.co.uk):
  434.   - for pointing out that ANDEQ R0,R0,R0 could usefully be replaced by DCD 0
  435.  
  436.   Martin Willers (m.willers@tu-bs.de):
  437.   - for bug hunting :-)
  438.  
  439.   Reuben Thomas (rrt1001@cam.ac.uk):
  440.   - for pointing out it might be useful to disable the APCS register names,
  441.     suggesting B/W/D suffix for FILL (and %) and -ve immediate constants, and
  442.     bug encountering
  443.  
  444.   Mohsen Alshayef (mohsen@qatar.net.qa):
  445.   - for some useful long MUL, STRH and [CS]PSR info
  446.