home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / a / asm3 / 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 sy