uni_ass.6 8.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258
  1. .\" $Header$
  2. .TH UNI_ASS VI
  3. .ad
  4. .SH NAME
  5. uni_ass \- universal assembler, assembler/loader
  6. .SH SYNOPSIS
  7. ~em/lib/\fImach\fP/as [options] argument ...
  8. .SH DESCRIPTION
  9. The universal assembler is a framework allowing easy
  10. generation of an assembler for any byte oriented machine.
  11. The framework includes common pseudo instructions for name
  12. definition, label usage, storage allocation and initialization
  13. and expression evaluation.
  14. The resulting program assembles assembly modules.
  15. For some machines, it also does the link-editing (loading).
  16. Arguments may be flags, assembly language modules, or,
  17. in the case of an assembler/loader, arch(1) libraries.
  18. .br
  19. Flags are:
  20. .IP \-d\fIonum\fP
  21. This option controls the listing. Default is no listing.
  22. .I Onum
  23. is interpreted as an octal number.
  24. Each bit controls part of the listing as follows:
  25. .RS
  26. .nf
  27. 0001: addresses in pass 1
  28. 0002: generated code in pass 1
  29. 0004: not used
  30. 0010: addresses in pass 2
  31. 0020: generated code in pass 2
  32. 0040: source lines in pass 2
  33. 0100: addresses in pass 3
  34. 0200: generated code in pass 3
  35. 0400: source lines in pass 3
  36. 1000: force .list and ignore .nolist
  37. .fi
  38. .RE
  39. Thus bits in 0 to 8 control the listing format and
  40. bit 9 forces a complete listing.
  41. If
  42. .I onum
  43. is omitted or is 000 it is interpreted as 0700.
  44. If
  45. .I onum
  46. is 1000 it is interpreted as 1700.
  47. .br
  48. Note that '-d' alone (unless it contains bit 9)
  49. is not enough to get a listing.
  50. A .list pseudo is also needed in each module to be listed.
  51. .IP -s[\fIonum\fP]
  52. This option controls the
  53. amount of symbolic debug information generated.
  54. .I Onum
  55. is interpreted as an octal number.
  56. The bits have the following meaning:
  57. .RS
  58. .nf
  59. 001: external symbols
  60. 002: local symbols
  61. 004: local, compiler generated labels
  62. 010: symbols defined in
  63. .I .symb
  64. pseudo instruction
  65. 020: records for
  66. .I .line
  67. and
  68. .I .file
  69. statements
  70. 040: section names
  71. .fi
  72. .RE
  73. Default is 073: all except local compiler labels.
  74. .IP -r
  75. Generate relocation information, for assemblers that can.
  76. .IP -b
  77. Turn off branch optimization.
  78. .IP -o\fIname\fP
  79. .IP -"o \fIname\fP"
  80. .I name
  81. is taken as the name of the
  82. resulting load file.
  83. The default name is \fBa.out\fP.
  84. .PP
  85. The assembler\-loaders assemble
  86. and link together assembly language modules
  87. machine
  88. from files and libraries,
  89. producing an \fIack.out\fP(5) format file, without relocation information.
  90. The assemblers produce a relocatable \fIack.out\fP(5) format file.
  91. .PP
  92. Two different types of arguments are allowed:
  93. .IP "1-"
  94. Assembly language modules
  95. .PD 0
  96. .IP "2-"
  97. UNIX archives, as maintained by arch(1). These archives must
  98. only contain
  99. assembly language modules with \fI.define\fP as their first
  100. statement.
  101. These are only accepted by assembler\-loaders.
  102. .PD
  103. .PP
  104. Note that assembler\-loaders cannot do a partial load;
  105. loading starts from assembly language and produces binary
  106. machine code. No relocation bits are produced.
  107. On the other hand, assemblers produce a relocatable file, to be handled
  108. by \fIled\fP(1).
  109. .SH "SECTIONS and TYPES"
  110. The statements allocating and initializing space,
  111. like instructions and
  112. some pseudo-instruction reserve that space in the current
  113. section.
  114. The currently reigning type of section is determined by
  115. the pseudo-instruction \fI.sect\fP.
  116. Actually, the assembler knows nothing about section types. Sections have
  117. numbers. The first section met gets number 0, the second gets number 1, etc.
  118. Therefore, every assembly files should start with a line just mentioning the
  119. sections used in the right order, so that no confusion can arise for \fIled\fP(1).
  120. .SH SYNTAX
  121. .PP
  122. The syntax of expressions is identical to the C expression syntax,
  123. except that square brackets are used for grouping.
  124. Labels are followed by a colon, and are identifiers or
  125. numbers between 0 and 9.
  126. Numeric labels can be referenced using the label followed by 'b' of 'f'
  127. determining the direction of search, backwards or forwards.
  128. .IP letters
  129. Both upper and lower case may be used and are seen as
  130. different.
  131. The underscore '_' is considered to be a letter.
  132. .IP identifiers
  133. Identifiers are a sequence of letters and digits, starting with
  134. a letter or a period '.'.
  135. Identifiers can, only once, receive a value through assignment or a
  136. label definition.
  137. .IP strings
  138. Strings are enclosed in single "'" or double """ quotes.
  139. The use of \eddd where ddd is an octal number and \en, \er,
  140. \et, \eb and \ef is allowed and has the same meaning as in the
  141. C language.
  142. .IP numbers
  143. Numbers are a sequence of letters and digits, starting with a
  144. digit.
  145. No difference is made between small and capital letters.
  146. .br
  147. The base of the number is determined in the following way:
  148. .nf
  149. if the number starts with '0x' it is hexadecimal else
  150. if the number starts with '0' it is octal else
  151. it's decimal.
  152. .fi
  153. The range of numbers depends on the machine.
  154. A rule of the thumb is that the width of the machine's registers
  155. the same is as the number of bits allowed in numbers.
  156. .IP comment
  157. The character '!' denotes the start of comment, every character
  158. up to the next newline is skipped.
  159. Exclamation marks in strings are not recognized as the start of
  160. comment.
  161. .IP statements
  162. Statements are separated by newlines and ';' and can be
  163. preceded by label definitions.
  164. Label definitions have the form "\fIidentifier\fP:" or
  165. "\fIdigit\fP:".
  166. Statements can be: empty, an assignment, an instruction or a
  167. pseudo-instruction.
  168. .IP assignment
  169. An assignment has the form:
  170. .br
  171. \fIidentifier\fP = \fIexpression\fP
  172. .br
  173. The identifier receives the value and type of the expression.
  174. .IP instruction
  175. The syntax of an instruction depends on the type of the target
  176. machine.
  177. .IP pseudo-instruction
  178. .de Pu
  179. .sp 1
  180. .ti +5
  181. \&\\$1
  182. .sp 1
  183. ..
  184. .Pu ".extern \fIidentifier [, identifier]*\fP"
  185. The identifiers mentioned in the list are exported and can be
  186. used in other modules.
  187. .Pu ".define \fIidentifier [, identifier]*\fP"
  188. Used for modules that are to be part of a libary.
  189. The .define pseudo's should be the first in such modules.
  190. When scanning a module in a library the assembler\-loader
  191. checks whether any of its unsatified external references is
  192. mentioned in a .define list. If so, it includes that module in
  193. the program.
  194. The identifiers mentioned in the list are exported and can be
  195. used in other modules.
  196. .Pu ".data1 \fIexpression [, expression]*\fP"
  197. Initialize a sequence of bytes.
  198. This is not followed by automatic alignment.
  199. .Pu ".data2 \fIexpression [, expression]*\fP"
  200. Initialize a sequence of shorts (2-byte values).
  201. This is not followed by automatic alignment.
  202. .Pu ".data4 \fIexpression [, expression]*\fP"
  203. Initialize a sequence of longs (4-byte values).
  204. This is not followed by automatic alignment.
  205. .Pu ".ascii \fIstring\fP"
  206. Initialize a sequence of bytes with the value of the bytes in
  207. the string.
  208. This is not followed by automatic alignment.
  209. .Pu ".asciz \fIstring\fP"
  210. Initialize a sequence of bytes with the value of the bytes in
  211. the string and terminate this with an extra zero byte.
  212. This is not followed by automatic alignment.
  213. .Pu ".align [\fIexpression\fP]"
  214. Adjust the current position to a multiple of the value of the
  215. expression.
  216. The default is the word-size of the target machine.
  217. .Pu ".space \fIexpression\fP"
  218. Allocate the indicated amount of bytes.
  219. The expression must be absolute.
  220. .Pu ".comm \fIname\fP,\fIexpression\fP"
  221. Allocate the indicated amount of bytes and assign the location of the first
  222. byte allocated to
  223. .IR name ,
  224. unless
  225. .I name
  226. is defined elsewhere.
  227. If the scope of
  228. .I name
  229. is extern, then assemblers leave definition of
  230. .I name
  231. to the linkeditor \fIled\fP(1).
  232. .Pu .sect \fIname\fP
  233. section name definition.
  234. .Pu ".base \fIexpresssion\fP"
  235. Set the starting address of the first of the consecutive segments
  236. (text) to the value of the expression.
  237. The expression must be absolute.
  238. .Pu .assert \fIexpression\fP
  239. assembly-time assertion checking. Stop with a fatal error message when
  240. the value of the expression is zero.
  241. .Pu .symb, .line, .file
  242. symbolic debug
  243. .Pu .nolist, .list
  244. .br
  245. listing control
  246. .SH "SEE ALSO"
  247. ack(1), arch(1), ack.out(5)
  248. .SH DIAGNOSTICS
  249. Various diagnostics may be produced.
  250. The most likely errors, however, are unresolved references,
  251. probably caused by the omission of a library argument.
  252. .SH BUGS
  253. The alignment might give rise to internal assertion errors when
  254. the alignment requestes is larger than the machine dependent
  255. segment alignment.
  256. .br
  257. Identifiers declared as externals cannot be used as locals in
  258. any following module. This only is a problem for assembler\-loaders.