home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / asm_1 / ASMTxt < prev    next >
Text File  |  1996-12-27  |  32KB  |  812 lines
  1. INTRODUCTION
  2. ~~~~~~~~~~~~
  3.         ASM is a (mostly) full function assembler for the Archimedes and A3000 machines,
  4. producing an AOF (Acorn Object Format) file suitable for use with the linker.
  5.  
  6.         To install ASM, simply move the file "ASM" into your Library directory.
  7.  
  8.         To assemble a file, use the command:
  9.  
  10.         ASM [options] <sourcefile>
  11.  
  12.         where <sourcefile> is the name of the file to be assembled. If no directory is specified,
  13. ASM will look for the source file in sub-directory A. For compatibility with C, the filename
  14. "SOURCE.A" is taken to refer to "A.SOURCE". The output will have the same leaf name as the
  15. sourcefile, and be stored in sub-directory O.
  16.  
  17.         Options are used to modify the standard behaviour of the assembler, and are introduced by
  18. a hyphen, the option name, and any allowed parameters. So long as enough letters of the option
  19. name are given to preclude ambiguity, any number of letters may be given; all options are case-
  20. insensitive. In the list of options below, the upper case part of the name indicates the minimum
  21. that can be specified to preclude ambiguity.
  22.  
  23. Option  Effect
  24.  
  25. -Output <filename>      The assembled code is written to <filename> rather than the
  26.                         default. If no directory is given, subdirectory O is assumed.
  27.  
  28. -List [<filename>]      An assembler listing is produced. If no filename is given, the
  29.                         file is given the same name as the sourcefile. By default, the
  30.                         file is produced in subdirectory L.
  31.  
  32. -Hex                    Include the generated hex code in the -List file. If -List is
  33.                         not explicitly specified, this option implies it.
  34.  
  35. -Include <pathlist>     Specifies a search path for use in the 'INCLUDE' directive (qv).
  36.                         <pathlist> is a comma-separated list of directories (or RISCOS
  37.                         symbols) to be searched for the file.
  38.  
  39.                         This is a slight deviation from the method use by the C compiler,
  40.                         which allows the -I option (which serves the same purpose) to be
  41.                         specified several times, each of which extended the search list.
  42.                         ASM only allows a single use of -Include, where all the paths are
  43.                         specified at once.
  44.  
  45. -VErbose                Output informational messages describing the current phase of assembly.
  46.  
  47. -VAlidate               The List file produced contains a disassembly of the generated code
  48.                         rather than the source code. It is not anticipated that users will
  49.                         make much use of this. As for -Hex, -VAlidate implies -List.
  50.  
  51. -Flags <flaglist>       Defines a number of flags to be set before beginning the assembly, for
  52.                         use in the IFDEF/IFNDEF directives. <flaglist> is a comma-separated
  53.                         list of flag names. Note that these flags are NOT assembler symbols,
  54.                         and cannot be used as such - they are only recognized by IFDEF and
  55.                         IFNDEF.
  56.  
  57. -Nocase                 Forces ASM to use case-insensitive name matching for user-defined
  58.                         symbols.
  59.  
  60. -Throwback              Enables the Acorn desktop throwback error-reporting mechanism.
  61.  
  62. -Processor <CPU>        Specifies the target processor. This constrains which of the extended
  63.                         instruction set operations are available. Legal values for <CPU> are:
  64.                                 ARM2, ARM3, ARM6 and ARM7.
  65.                         (StrongARM will be coming when I discover what additional opcodes, if
  66.                         any, are available).
  67.  
  68. -Help                   Produce brief help text for the ASM syntax and options.
  69.  
  70.  
  71. Examples
  72.  
  73.         ASM tharg
  74.  
  75.         will assemble the code in A.tharg and produce an object file O.tharg
  76.  
  77.         ASM -hex -flags debug,check -include <C$UserLibRoot>,<ASM$MylibRoot> eric
  78.  
  79.         will assemble the file A.eric and produce an object file O.eric; a listing file called
  80.         L.eric will be produced containing the hex code generated. Any 'INCLUDE' statements will
  81.         look in directories <C$UserLibRoot> and <ASM$MylibRoot> for the include files. Finally,
  82.         the conditional assembly flags debug and check will be treated as set.
  83.  
  84.  
  85. SOURCE FORMAT
  86. ~~~~~~~~~~~~~
  87.         It is assumed that the user is fully familiar with ARM assembly language (what are you
  88. doing with ASM if you aren't?) and therefore this note contains no tutorial-type introduction;
  89. only the differences between the ASM format and that in use in the BASIC assembler are detailed.
  90.  
  91.         It is recommended that users of ASM be familiar with the "RISCOS Programmer's Reference
  92. Manual" (especially those sections on the linker and Acorn Procedure Calling Standard) and Peter
  93. Cockerell's "ARM Assembly Language Programming".
  94.  
  95.         Throughout, mnemonics and their options follow the de facto standard, that in Cockerell's
  96. book. For certain FP coprocessor instructions this differs slightly from that used by the
  97. disassembler (SWI "Debugger_Disassemble"), which seems to contain a bug anyway.
  98.  
  99.         The general format of a line is:
  100.  
  101.         [<label-part>]  [<mnemonic-part>]  [<comment-part>]
  102.  
  103.         Any or all of these parts are optional. Unlike the BASIC assembler, there is no facility
  104. to put multiple mnemonics on a single line by separating them with a colon.
  105.  
  106. <label-part>    A label is any legal ASM Symbol (see below), terminated by a colon.
  107.  
  108. <mnemonic-part> This part is any ARM instruction mnemonic (eg ADDS, STMFD), generic coprocessor
  109.                 mnemonic (eg MCR, CDPEQ), or any Floating Point coprocessor mnemonic (eg MUFD,
  110.                 FIXS), plus any associated parameters.
  111.                 Alternatively, this could be the ADR pseudo-operation, or any ASM directive
  112.                 (eg IFDEF, MACRO).
  113.  
  114. <comment-part>  A comment is introduced by a semi-colon. Any text following a semi-colon on a
  115.                 line is ignored.
  116.  
  117. In addition to the above format, ASM will also accept constant definitions of the form:
  118.  
  119.         <label> = <constant-expression>
  120. and     <label> = <register-expression>
  121.  
  122. where <label> is a legal ASM identifier (without the colon this time),  <constant-expression>
  123. evaluates to an integer, and <register-expression> is one of the built-in register symbols
  124. (see “Symbols in ASM” below).
  125.  
  126. The following code fragment demonstrates both possible formats (it actually performs a 64-bit
  127. integer addition):
  128.  
  129.         result = 0
  130.         lhs = result + 1
  131.         rhs = lhs + 2
  132.         
  133.                 EXPORT  Long_Add        ; Make the function external
  134. Long_Add:       STMFD   sp!,{lhs ,lhs+1,link}
  135.                 ADDS    lhs,lhs,rhs
  136.                 ADCS    lhs+1,lhs+1,rhs+1
  137.                 BVS     overflow
  138.                 STMIA   result,{lhs ,lhs+1}
  139.                 LDMFD   sp!,{lhs ,lhs+1,pc}^
  140. overflow:       ADR     R0,oflerr
  141.                 SWI     "OS_GenerateError"
  142. oflerr:         DCD     &901
  143.                 DCS     "Arithmetic overflow"
  144.                 DCB     0
  145.                 ALIGN
  146.  
  147.                 etc
  148.  
  149.  
  150. Symbols in ASM
  151. ~~~~~~~~~~~~~~
  152.         Symbols (Identifier names) in ASM may contain the following characters: A-Z, a-z, 0-9,
  153. underscore (_) and dollar ($). These may be in any order, with the exception that an identifier
  154. cannot begin with a digit.
  155.  
  156.         There are several classes of identifiers in ASM :
  157.  
  158. Constants       Constants are defined by the use of the <constant> = <expression> format. The
  159.                 expression must evaluate to an integer, and may contain other constants. For
  160.                 example, the symbol "result" in the example above is a constant.
  161.  
  162. Local Symbols   A local symbol is a label. The symbols "overflow" and "oflerr" in the example
  163.                 above are local symbols. Local symbols may be either "Close" or "Far": see below.
  164.  
  165. Global Symbols  A global symbol is similar to a local symbol, but one that has been made
  166.                 externally visible at the link stage by the use of the EXPORT directive. Global
  167.                 Symbols may be "Close" or "Far".
  168.  
  169. Externals       An external symbol is similar to a label, but is not defined within this assembly
  170.                 unit. It is introduced by the IMPORT directive. References to External symbols
  171.                 must be resolved by the linker. External Symbols are always "Far".
  172.  
  173. User-defined symbols are case-sensitive (ie "SYMBOL" is not the same as "symbol") unless the
  174. -nocase qualifier has been specified on the command line.
  175.  
  176. In addition to the above user-defined symbols, ASM provides a set of built-in symbols of special
  177. types, which are case-insensitive. These symbols refer specifically to registers, either in the
  178. ARM itself or in the FP coprocessor.
  179.  
  180. These built-in symbols are:
  181.  
  182. r0-r15  ARM registers 0 to 15.
  183. sp      Stack Pointer. Set to R13.
  184. link    Link register (R14).
  185. pc      Program Counter/Status register (R15).
  186. f0-f7   FP Coprocessor register 0 to 7.
  187.  
  188. a1-a4   )
  189. v1-v6   )
  190. ip      )  These are defined as part of the Acorn Procedure Calling Standard.
  191. fp      )  ASM binds them to their RISCOS values (APCS-R).
  192. sp      )
  193. lr      )
  194. pc      )
  195.  
  196.         ASM tries to be as flexible as possible with its parsing: where a mnemonic requires an
  197. ARM register name, ASM will accept any of the register constants above (except the FP register
  198. f0-f7) OR an integer expression which evaluates to a number in the range 0-15. Where a FP
  199. coprocessor register is required, ASM will accept the register symbols f0-f7, or an integer
  200. expression which evaluates to a number in the range 0-7. However, if a constant is required, ASM
  201. will reject the use of any of the register symbols.
  202.  
  203.  
  204. Areas
  205. ~~~~~
  206.         When the linker is combining several AOF files, it does so on the basis of "Areas". An
  207. area is a named chunk of contiguous memory with associated attributes (eg area contains code,
  208. area contains data, area is readonly etc) (See the AREA directive). ASM allows multiple areas to
  209. be created in a single source file, but the ordering of areas in the final executable image is
  210. wholly the responsibility of the linker. This leads to the concept of Close and Far symbols.
  211.  
  212. Close and Far Symbols
  213. ~~~~~~~~~~~~~~~~~~~~~
  214.         While some ARM mnemonics allow access to the entire 26-bit address space (eg BL A_Sub)
  215.         others allow only a restricted window into the address space (eg PC-relative addressing,
  216.         such as LDR R0,Tharg). Where the entire address space is legal, ASM will accept either a
  217.         symbol which is close to the the instruction or one that is far away. Where only a
  218.         restricted address space is available, ASM will accept only a close symbol.
  219.  
  220.         ASM regards a symbol as "Close" if and only if it is a local or global symbol, AND ITS
  221.         DEFINING POINT IS IN THE SAME AREA AS THE INSTRUCTION THAT REFERENCES IT. All other
  222.         symbols are "Far".
  223.  
  224.         For example :
  225.         AREA    ASM$$CodeA,Code
  226. Y:      etc
  227.         AREA    ASM$$CodeB,Code,ReadOnly
  228.         etc
  229.         BL      X       ; Legal.
  230.         BL      Y       ; Legal. Y is Far, but allowed.
  231.         ADR     R0,X    ; Legal. X is Close
  232.         LDR     R0,Y    ; Illegal. Y is Far & address space not available
  233.         etc
  234. X:      MOV     r0,r1
  235.         etc
  236.  
  237.         The user need not particularly worry about close and far symbols; ASM handles this
  238. automatically. It is included in this documentation simply to explain the cause of the error
  239. "Local Symbol Expected" that the above code fragment will generate, despite the fact the the
  240. symbol 'Y' is defined locally.
  241.  
  242.  
  243. Other Exotica
  244. ~~~~~~~~~~~~~
  245.         Where a PC-relative address is allowed, ASM supports an additional syntax, as in:
  246.  
  247.         B       *+12
  248. or      LDR     R4,*+8
  249.  
  250.         In this notation, the asterisk * means "the address of the current instruction" (Not the
  251. PC - allowing for pipelining, the PC will be at *+8). ASM resolves this as a PC-relative address.
  252. Its use is not particularly recommended, as local code changes may require that the offset be
  253. manually changed (whereas labels are self-adjusting). However, for short jumps it does negate the
  254. need for a label, which is why it is provided.
  255.  
  256. STRINGS, CHARACTER CONSTANTS AND NUMERICS
  257. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  258.         ASM differentiates strongly between strings and character constants. A string is enclosed
  259. in double quotation marks ("), and can be of any length. A character constant is enclosed in
  260. single quotation marks (') and its maximum length depends on the current context:
  261.  
  262.         MOV     R0,'A'  ; Move ASCII 'A' (65) into R0
  263.         MOV     R0,"A"  ; Will generate an assembly error.
  264.         DCW     'AB'
  265.  
  266.         The last statement above will store two bytes, ASCII A followed by ASCII B.
  267.  
  268.         ASM, like C, uses the backslash (\) as an escape character to store odd values in
  269. strings:
  270.  
  271.             \n      Newline
  272.             \r      Carriage Return
  273.             \t      Tab
  274.             \'      Single Quote
  275.             \"      Double Quote
  276.             \\      Backslash
  277.             \xhh    Hex code hh. eg \x0E is ASCII 14 (<CTRL>N).
  278.  
  279.         Integers may be specified in a number of ways: & treats the characters following as a
  280. hexadecimal number, % treats it as binary, no character treats it as base 10.
  281.  
  282.         ADD     R0,R0,#&F0      ; Add F0 Hexadecimal (240 decimal) to R0
  283.         SUB     R1,R1,#%1100    ; Subtract 1100 binary (12 decimal) from R1
  284.         MOV     R2,#15          ; Move 15 decimal into R2
  285.  
  286.         Floating point numbers may only be specified in base 10. They may include both decimal
  287. points and exponents. However, there must be at least one digit before either the decimal point
  288. or the exponent.
  289.  
  290.         ADFD    f0,f0,#3.0      ; Add 3.0 to f0.
  291.         DCFD    1.0654E-6       ; Store a double-precision constant.
  292.         DCFE    .3421           ; Illegal - no digit before the decimal point.
  293.  
  294.         It should be remembered that there are only 8 floating point values that can be used as
  295. immediate value constants: these are 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 0.5 and 10.0.
  296.  
  297.  
  298. Arithmetic Expressions
  299. ~~~~~~~~~~~~~~~~~~~~~~
  300.         Wherever an integer or floating point number is required, ASM will accept an expression
  301. that evaluates to the correct type (ie integer expressions must not contain any floating point
  302. values). ASM recognizes the following operators:
  303.  
  304.             Operator                  Precedence
  305.             Unary +                       1
  306.             Unary -                       1
  307.                *                          2
  308.                /                          2
  309.             % (remainder)                 2
  310.             & (bitwise AND)               2
  311.             +                             3
  312.             -                             3
  313.             | (bitwise OR)                3
  314.             ^ (bitwise Exclusive OR)      3
  315.             >>  (Arithmetic shift right)  4
  316.             >>> (Logical shift right)     4
  317.             <<  (Logical shift left)      4
  318.  
  319.         Sub-expressions in parentheses are allowed, and have the highest priority. They may be
  320. nested to an arbitrary degree.
  321.  
  322.         Within a single level of priority, expressions are evaluated left to right.
  323.  
  324.         There are a number of constraints on the use of certain operators:
  325.  
  326. 1)      Only + and - operators that can be applied to non-constant symbols (ie addresses).
  327.  
  328.         Thus
  329.                 BL Tharg+2*4
  330.         is legal, but
  331.                 BL Tharg*2
  332.         is not.
  333.  
  334. 2)      Bit-based operators (&,  |, ^, >>, >>> and <<) may only be used in integer constant
  335. expressions or sub-expressions.
  336.  
  337.         Thus
  338.                 DCFE  12345.6 + (1<<12)
  339.         is legal, but
  340.                 DCFD  12345.6 >> 2
  341.         is not.
  342.  
  343. Rule 1 is to ensure that addresses are always properly relocatable. Rule 2 is because it is not
  344. very meaningful to apply bit operators to floating point values.
  345.  
  346. MACROS
  347. ~~~~~~
  348.         A Macro is a section of code defined in a single place, and then used in several places.
  349. It differs from a Branch-with-link in that the macro is copied in whole wherever it is used; it
  350. thus generates more code than a branch-with-link, but will usually process faster; in addition,
  351. it does not make any use of the stack.
  352.  
  353.         Macros may be given any number of parameters, of any type (including labels - see below).
  354. These are automatically substituted when the macro instruction is used. The handling of labels
  355. within macros is quite straightforward: if the defining point of the label is within the limits
  356. of the macro, it is regarded as a local label, and substituted; any labels referenced that are
  357. not within the bounds of the array are not substituted. Local label names generated by ASM are of
  358. the form $nnnnnn, where nnnnnn is 300000 plus a count of the number of labels generated. Thus,
  359. the first label will be called $300001, the second $300002, etc. For obvious reasons, labels of
  360. this form should be avoided by the user.
  361.  
  362.         A macro is defined with the MACRO directive, and terminated with the ENDM directive.
  363.  
  364.         A macro is used simply by giving its name as a standard mnemonic, followed by a list of
  365. its parameters.
  366.  
  367.         As an example, consider a macro to take the absolute value of 64-bit integer held in two
  368. consecutive registers. This will be defined as ABS64, and then used twice, once for register pair
  369. R0,R1 and once for register pair R2,R3.
  370.  
  371.  
  372.         MACRO   ABS64,regno
  373.         CMP     regno+1,#0      ; Is the upper word negative?
  374.         BPL     notneg
  375.  
  376.         ; It is negative. Subtract it from zero to get the abs value
  377.  
  378.         RSBS    regno,regno,#0
  379.         RSC     regno+1,regno+1,#0
  380.  
  381. notneg: ENDM
  382.  
  383.         ; Now use the macro
  384.         ABS64   R0      ; Ensure R0,R1 is positive
  385.         ABS64   R2      ; Ensure R2,R3 is positive
  386.  
  387.         etc
  388.  
  389.         When expanded, this will be assembled as:
  390.  
  391.         ; ABS64 R0
  392.         CMP     R0+1,#0 ; Is the upper word negative?
  393.         BPL     $300001
  394.  
  395.         ; It is negative. Subtract it from zero to get the abs value
  396.  
  397.         RSBS    R0,R0,#0
  398.         RSC     R0+1,R0+1,#0
  399. $300001:
  400.         ; ABS64 R2
  401.         CMP     R2+1,#0 ; Is the upper word negative?
  402.         BPL     $300002
  403.  
  404.         ; It is negative. Subtract it from zero to get the abs value
  405.  
  406.         RSBS    R2,R2,#0
  407.         RSC     R2+1,R2+1,#0
  408. $300002:
  409.  
  410.  
  411. NB The use of the INCLUDE directive is specifically forbidden within a macro definition. It is
  412. legal for the body of one macro to use another macro; however, it is illegal to nest the actual
  413. definitions.
  414.  
  415.  
  416. Labels as macro parameters
  417. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  418. As stated above, it is perfectly legal to pass a label into a macro. For example:
  419.  
  420.  
  421.         MACRO   JMPZ,regno,a_label
  422.         CMP     regno,#0
  423.         BEQ     a_label
  424.         ENDM
  425.  
  426.         JMPZ    R0,tharg
  427.  
  428.         etc
  429.  
  430. tharg:  do something
  431.  
  432.  
  433. CONDITIONAL ASSEMBLY
  434. ~~~~~~~~~~~~~~~~~~~~
  435.         ASM gives simple support to conditional assembly: ie, the code produced can be made to
  436. depend on the value of some flags defined by the assembly command.
  437.  
  438.         The directives involved in conditional assembly are IFDEF (a specified flag is defined),
  439. IFNDEF (a specified flag is not defined), ELSE and ENDIF.
  440.  
  441.         As described above, the flags used by IFDEF/IFNDEF are set using the -flags assembly
  442. options. Any flags not explicitly set are treated as unset.
  443.  
  444.         For example:
  445.  
  446.                   IFDEF   Debug
  447.                   STMFD   sp!,{r0 }
  448.                   ADR     R0,DebugMsg
  449.                   SWI     "OS_Write0"
  450.                   B       EndDBug
  451. DebugMsg:       DCD     &902
  452.                   DCS     "Hello there"
  453.                   DCB     0
  454.                   ALIGN
  455. EndDBug:
  456.                   ENDIF
  457.  
  458.         If the file was assembled using -flags debug, the code between the IFDEF and the ENDIF
  459. will be included in the output AOF file; otherwise it will not.
  460.  
  461.         IFNDEF works in exactly the same way, except the code is included if the specified flag
  462. is not set.
  463.  
  464.         ELSE works in the expected way.
  465.  
  466.         Any number of IFDEF/IFNDEFs may be nested, they may be nested inside MACRO definitions,
  467. and vice versa.
  468.  
  469.  
  470. NEW FEATURES
  471. ~~~~~~~~~~~~
  472. Version 3 has a number of new features:
  473.  
  474. a)      Throwback
  475.         ASM now fully supports Acorn’s desktop throwback error-reporting mechanism. It is
  476.         activated by the use of the ‘throwback’ qualifier on the command line.
  477.  
  478. b)      Case-insensitive symbol names
  479.         User-defined symbols can now be (optionally) be made case-insensitive. This feature is
  480.         activated by the ‘nocase’ qualifier on the command line.
  481.  
  482. c)      Extended ARM instruction set
  483.         The additional instructions introduced by the ARM3, ARM6 and ARM7 series processors are
  484.         now supported. ASM must be informed of the architecture for which the code is targetted,
  485.         using the ‘processor <proc>’ qualifier. If this qualifier is not present, ASM assumes an
  486.         ARM3 target. The use of an opcode that is not available on the specified target processor
  487.         will generate an error. The extra instructions available are:
  488.  
  489.             Mnemonic        Earliest        Description
  490.                              Target
  491.             SWP               ARM3     Single data swap
  492.             MRS               ARM6     Processor Status Register transfer (Register->PSR)
  493.             MSR                        Processor Status Register transfer (PSR->Register)
  494.             UMULL             ARM7     Unsigned 64-bit multiply
  495.             SMULL                      Signed 64-bit multiply
  496.             UMLAL                      Unsigned 64-bit multiply with accumulate
  497.             SMLAL                      Signed 64-bit multiply with accumulate
  498.  
  499.         NB. The 64-bit multiply instructions only work in 32-bit modes, while RISCOS works in
  500. 26-bit mode, which makes its use in ASM somewhat moot.
  501.  
  502.  
  503. WARNING
  504. ~~~~~~~
  505. ASM uses the Debugger_Disassemble SWI to decode the generated opcodes for the ‘validate’ option.
  506. Sadly, this SWI does not seem to recognise the SWP instruction, and they are all returned as
  507. “Undefined Instruction”. Users should ignore these errors, as ASM has been tested fairly
  508. extensively in this area, and the generated codes match with the Acorn documentation. Should you
  509. be able to shed any definitive light on this situation (ie whether the SWI or the documentation
  510. is at fault), please contact the author.
  511.  
  512.  
  513. DIRECTIVES
  514. ~~~~~~~~~~
  515.         The rest of this documentation concentrates on the assembler directives provided by ASM.
  516.  
  517.  
  518. =================================================================================================
  519. ALIGN           Ensures that the code pointer is on a word boundary.
  520.  
  521. Format: ALIGN
  522.  
  523. Certain DC directives (DCB, DCW, DCS) store a number of bytes that is not an exact multiple of
  524. four. RESB may also reserve less than a complete number of words. It is therefore possible for a
  525. label to be given an address which is not that which is required. The use of ALIGN will bump the
  526. pointer forward to ensure that it is correctly word-aligned.
  527.  
  528. NB All mnemonics and all other DC operations automatically carry out an align, and labels are
  529. adjusted to allow for this. Thus the two code fragments below lead to different values for L1 and
  530. L2 (L1 is NOT word-aligned, but L2 is aligned).
  531.  
  532. 1)              DCB     0
  533.         L1:
  534.                 B       Tharg
  535.  
  536. 2)              DCB     0
  537.         L2:     B       Tharg
  538.  
  539. If code fragment 1 had an ALIGN directive after the DCB, L1 and L2 would have the same value.
  540.  
  541. eg      ALIGN
  542.  
  543. See Also:       DC, RESB
  544.  
  545.  
  546.  
  547. =================================================================================================
  548. AREA    Instructs ASM to start a new area.
  549.  
  550. Format: AREA    <areaname>,<attributes>
  551.  
  552. The areaname parameter is any legal ASM identifier. The attributes parameter(s) must specify one
  553. of CODE or DATA. READONLY may be specified.
  554.  
  555. eg      AREA    ASM$$Code,Code,ReadOnly
  556.  
  557. Note that an AREA statement must precede any mnemonics or directives that cause data to be
  558. written to the area.
  559.  
  560. Later versions of ASM may support additional AOF area types (eg Zero-Initialized, Common Block,
  561. Common Block Reference).
  562.  
  563. See Also:       
  564.  
  565.  
  566.  
  567. =================================================================================================
  568. DC      Store a constant value.
  569.  
  570. Format: DC<type>        <value>[,<value>....]
  571.  
  572. The <type> is one or two characters that define the type of the constant being stored, and hence
  573. the type expected of <value>
  574.  
  575.      <type>  Type of Value
  576.         B       Byte
  577.         W       Word. Actually this is a 16-bit value (ie a half-word). This letter is used for
  578.                 consistency with the BASIC assembler and AASM.
  579.         D       Double Word. Actually a 32-bit value. See above.
  580.         Q       Quad Word. A 64-bit integer value.
  581.         S       String. (NB C programmers: this is NOT zero-terminated - use DCSZ below).
  582.         SZ      Zero-terminated string.
  583.         FS      Single-precision floating point
  584.         FD      Double-precision floating point
  585.         FE      Extended-precision floating point
  586.         FP      Packed floating point.
  587.         
  588. eg      DCB     &FF
  589.         DCS     "Hello there"
  590.         DCSZ    “Hello again”
  591.         DCFE    12.32E12, 3.141592
  592.  
  593. The use of DCD allows addresses to be stored, and hence the address of Far symbols to be loaded
  594. into registers:
  595.  
  596.         IMPORT  myaddress
  597.         etc
  598.         LDR     R1,addr
  599.         etc
  600. addr:   DCD     myaddress
  601.  
  602. Where a DCD is used that is interpreted as an address, ASM will automatically generate any
  603. required relocations.
  604.  
  605. See Also:       EQU, RESB
  606.  
  607.  
  608.  
  609. =================================================================================================
  610. ELSE    Part of IF/ELSE/ENDIF conditional assembly structure.
  611.  
  612. Format: ELSE
  613.  
  614. ELSE negates the current condition flag. See the section on Conditional Assembly for details of
  615. the use of IFDEF/IFNDEF/ELSE/ENDIF.
  616.  
  617. eg      ELSE
  618.  
  619. See Also:       IFDEF, IFNDEF, ENDIF
  620.  
  621.  
  622.  
  623. =================================================================================================
  624. ENDIF   Part of IF/ELSE/ENDIF conditional assembly structure.
  625.  
  626. Format: ENDIF
  627.  
  628. ENDIF terminates the current conditional assembly statement. See the section on Conditional
  629. Assembly for details of the use of IFDEF/IFNDEF/ELSE/ENDIF.
  630.  
  631. eg      ENDIF
  632.  
  633. See Also:       IFDEF, IFNDEF, ELSE
  634.  
  635.  
  636.  
  637. =================================================================================================
  638. ENDM    Part of a MACRO/ENDM macro definition structure.
  639.  
  640. Format: ENDM
  641.  
  642. ENDM terminates the current macro definition. See the section on Macros for details of the use
  643. of MACRO/ENDM.
  644.  
  645. eg      ENDM
  646.  
  647. See Also:       MACRO
  648.  
  649.  
  650.  
  651. =================================================================================================
  652. ENTRY   Define the entry address for a program.
  653.  
  654. Format: ENTRY   <symbol>
  655.  
  656. The linker requires that one and only one of the object files given to it contain an entry
  657. address; this is the location that will be called when the linked program is run. The ENTRY
  658. directive specifies a (Local or Global) symbol which will be used for the entry point.
  659.  
  660. eg      ENTRY   Start
  661.  
  662. Note, however, that there is an extensive quantity of code required to set up application memory
  663. constraints etc, during program initialization, which is outside the scope of this documentation;
  664. for this reason, the author does not advocate the use of the ENTRY directive unless you know
  665. exactly what you are doing; it is much easier to use C for the majority of an application, and
  666. just program the time-critical parts in ASM.
  667.  
  668. See Also:
  669.  
  670.  
  671.  
  672. =================================================================================================
  673. EQU     Store a constant value.
  674.  
  675. Format: EQU<type>       <value>[,<value>....]
  676.  
  677. EQU is a synonym for DC, and works in exactly the same way. It is supported simply for
  678. consistency with the BASIC assembler.
  679.  
  680. eg      EQUB    12
  681.  
  682. See Also:       DC, RESB
  683.  
  684.  
  685.  
  686. =================================================================================================
  687. EXPORT  Gives a local symbol global scope.
  688.  
  689. Format: EXPORT  <label>
  690.  
  691. By default, all labels used in an ASM source file are local, and hence other source files cannot
  692. call locally-defined routines. The EXPORT directive gives the linker visibility over the
  693. specified label.
  694.  
  695. Note that the EXPORT directive and the defining point of the label may appear in either order -
  696. ASM will accept both.
  697.  
  698. eg      EXPORT  ADD_64
  699.  
  700. See Also:       IMPORT
  701.  
  702.  
  703.  
  704. =================================================================================================
  705. IFDEF   Part of IF/ELSE/ENDIF conditional assembly structure.
  706.  
  707. Format: IFDEF   <flag>
  708.  
  709. The flag parameter is any legal ASM identifier. Note that although it follows the same naming
  710. conventions, such a flag cannot be used in any expression evaluation, for example as an integer.
  711. See the section on Conditional Assembly for details of the use of IFDEF/IFNDEF/ELSE/ENDIF.
  712.  
  713. eg      IFDEF   Debug
  714.  
  715. See Also:       IFNDEF, ELSE, ENDIF
  716.  
  717.  
  718.  
  719. =================================================================================================
  720. IFNDEF  Part of IF/ELSE/ENDIF conditional assembly structure.
  721.  
  722. Format: IFNDEF  <flag>
  723.  
  724. IFNDEF acts exactly as an IFDEF, but with the condition negated. See the section on Conditional
  725. Assembly for details of the use of IFDEF/IFNDEF/ELSE/ENDIF.
  726.  
  727. eg      IFNDEF  Verbose
  728.  
  729. See Also:       IFDEF, ELSE, ENDIF
  730.  
  731.  
  732.  
  733. =================================================================================================
  734. IMPORT  Declares the name of a symbol defined in a separate module.
  735.  
  736. Format: IMPORT  <symbol>
  737.  
  738. IMPORT informs ASM that the specified symbol needs to be visible to the current module (ie the
  739. name is referenced somewhere in the current source file). The symbol can then be used as a (Far)
  740. address, and any references to it will be handled by the linker. The IMPORT directive may be
  741. placed before or after the symbol is first used (although it is normal to declare the symbol
  742. before it is used).
  743.  
  744. eg      IMPORT  ErrorHandler
  745.  
  746.         B       ErrorHandler
  747.  
  748. See Also:       EXPORT
  749.  
  750.  
  751.  
  752. =================================================================================================
  753. INCLUDE Directs ASM to include another file in the current module.
  754.  
  755. Format: INCLUDE <filename>
  756.  
  757. The INCLUDE directive causes ASM to begin reading source text from the specified file. When that
  758. file is exhausted, ASM will continue with the calling file.
  759.  
  760. The <filename> parameter must be specified as a quoted string. If no directory specification
  761. exists, ASM will look in subdirectory 'I' for the file. For compatibility with C, ASM will accept
  762. a filename of the form "FRED.I" as meaning "I.FRED".
  763.  
  764. The -Include option on the ASM command allows the specification of a path list for the given file;
  765. if the file is not found locally, then each path will be checked in order. Only if the file is not
  766. found on any path will ASM report an error.
  767.  
  768. NB The use of INCLUDE is forbidden in a macro definition.
  769.  
  770. eg      INCLUDE "UtilityHdr.I"
  771.  
  772. See Also:
  773.  
  774.  
  775.  
  776. =================================================================================================
  777. MACRO   Part of MACRO/ENDM macro definition structure.
  778.  
  779. Format: MACRO   <macroname>[,<parameterlist>]
  780.  
  781. MACRO begins the definition of a new macro. <macroname> can be any legal ASM identifier.
  782. <parameterlist> is a comma-separated list of formal parameter names, which will be substituted
  783. when the macro is instantiated. The actual parameters may be of any type (string, integer, float
  784. etc). See the section on Macros for details of the use of MACRO/ENDM.
  785.  
  786. eg      MACRO   ERROR,errnum,errtext
  787.  
  788. A Macro is instantiated by using its name as if it were a mnemonic, and passing values for the
  789. formal parameters.
  790.  
  791. eg      ERROR   &901,"This is an error" 
  792.  
  793. See Also:       ENDM
  794.  
  795.  
  796.  
  797. =================================================================================================
  798. RESB    Reserve a (zero-initialized) block of memory.
  799.  
  800. Format: RESB    <length>
  801.  
  802. The RESB directive instructs ASM to increment the code pointer by the specified length; the
  803. block of memory so reserved will be filled with zeros. Note that <length> is specified in bytes,
  804. and hence the code pointer may not be word-aligned after executing the RESB operation.
  805.  
  806. RESB is generally used where a large buffer is required, to save the use of many DC directives.
  807.  
  808. eg      RESB    128
  809.  
  810. See Also:       DC, EQU
  811.  
  812.