uni_ass.6 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332
  1. .\" $Header$
  2. .tr ~
  3. .TH UNI_ASS VI
  4. .ad
  5. .SH NAME
  6. uni_ass \- universal assembler/loader
  7. .SH SYNOPSIS
  8. /usr/em/lib/\fImachine\fP_as [options] argument ...
  9. .SH DESCRIPTION
  10. The universal assembler is a framework allowing easy
  11. generation of an assembler for any byte oriented machine.
  12. The framework includes common pseudo instructions for name
  13. definition, label usage, storage allocation and initialization
  14. and expression evaluation.
  15. The resulting program assembles and links assembly modules.
  16. Arguments may be flags, assembly language modules or libraries.
  17. .br
  18. Flags are:
  19. .IP -d[\fIn\fP]
  20. Produce a listing on standard output, the octal number
  21. \fIn\fP is mainly used for debugging purposes.
  22. The default is 700. 500 and 600 give slightly different
  23. listings.
  24. .IP -s[\fIn\fP]
  25. Produce a human-readable symbol table on standard output.
  26. The default for \fIn\fP is 3.
  27. The value 2 causes a listing of only the symbols internal to
  28. the modules.
  29. The value 1 causes a listing of external symbols only.
  30. .IP -o
  31. The argument following this flag is taken as the name of the
  32. resulting load file.
  33. The default name is \fBa.out\fP.
  34. .PD
  35. .PP
  36. The assemblers assemble
  37. and link together assembly language modules
  38. machine
  39. from files and libraries,
  40. producing an a.out file.
  41. .PP
  42. Two different types of arguments are allowed:
  43. .IP "1-"
  44. Assembly language modules
  45. .PD 0
  46. .IP "2-"
  47. UNIX archives, as maintained by arch(I). These archives must
  48. only contain
  49. assembly language modules with \fI.define\fP as their first
  50. statement.
  51. .PD
  52. .PP
  53. Note that it is not possible to do a partial load;
  54. loading starts from assembly language and produces binary
  55. machine code. No symbol table and no relocation bits are produced.
  56. .SH "SEGMENTS and TYPES"
  57. The statements allocating and initializing space,
  58. like instructions and
  59. some pseudo-instruction reserve that space in the current
  60. segment.
  61. The currently reigning type of segment is determined by
  62. one of the pseudo-instructions: \fI.text, .data, .bss\fP and
  63. \&\fI.org\fP.
  64. The assembler concatenates all space allocated in each of the
  65. text, data and bss segments.
  66. That is: every byte in a text segment is followed by another
  67. byte in the text segment except the last, of which there is
  68. only one in each program.
  69. The org segment differs from the other three in the sense that
  70. the assembler makes no attempt to concatenate pieces of org
  71. segments.
  72. Each \fI.org\fP pseudo-instruction has a parameter telling where it
  73. should start allocating space.
  74. In the final stages of the assembly the text, data and bss
  75. segments are concatenated in that order after the length of
  76. each segment has been made a multiple of a machine dependent
  77. constant.
  78. The first segment (text) starts at the location that is given
  79. as an argument to the .base pseudo-instruction.
  80. The default is 0.
  81. .sp
  82. The labels defined in a particular segment
  83. have the type of that
  84. segment, other types are: \fIundefined\fP and \fIabsolute\fP.
  85. All variables that do not have a value have the type
  86. \fIundefined\fP, a good example is an unsatisfied external
  87. reference.
  88. Numbers have the type \fIabsolute\fP.
  89. The type of expressions depends on both the operators and the
  90. operands used.
  91. Generally, but not always, the following rule holds: whenever
  92. one of the operands is absolute and the resulting type is that
  93. of the other operand.
  94. Not every operation is allowed on every combination of types,
  95. for example: it is not allowed to add two \fItext\fP values.
  96. .SH SYNTAX
  97. .IP letters
  98. Both upper and lower case may be used and are seen as
  99. different.
  100. The underscore '_' is considered to be a letter.
  101. .IP identifiers
  102. Identifiers are a sequence of letters and digits, starting with
  103. a letter or a period '.'.
  104. Only the first eight characters are remembered by the
  105. assemblers, identifiers with the same first eight characters
  106. are considered to be identical.
  107. Identifiers can, only once, receive a value through assignment or a
  108. label definition.
  109. .IP "local labels"
  110. Local labels consist of a single digit.
  111. They can only be defined in the label part of a statement and
  112. used anywhere an identifier is allowed.
  113. They can be redefined at will.
  114. Two forms of use exist: \fIf\fPorward and \fIb\fPackward
  115. references.
  116. The first consists of the digit followed by an \fIf\fP
  117. and refers to the first definition of that label following the
  118. reference.
  119. The second consists of the digit followed by an \fIb\fP
  120. and refers to the last definition of the label before the
  121. reference.
  122. .IP strings
  123. Strings are enclosed in single "'" or double """ quotes.
  124. The use of \eddd where ddd is an octal number and \en, \er,
  125. \et, \eb and \ef is allowed and has the same meaning as in the
  126. C language.
  127. .IP numbers
  128. Numbers are a sequence of letters and digits, starting with a
  129. digit.
  130. No difference is made between small and capital letters.
  131. .br
  132. The base of the number is determined in the following way:
  133. .nf
  134. if the number ends with an 'h' it is hexadecimal else
  135. if the number starts with '0x' it is hexadecimal else
  136. if the number starts with '0' it is octal else
  137. it's decimal.
  138. .fi
  139. Note that the number '0x10h' is an illegal hexadecimal number,
  140. because 'x' is an illegal hexadecimal digit.
  141. The number should be written as '0x10' or '10h'.
  142. The range of numbers depends on the machine.
  143. A rule of the thumb is that the width of the machine's registers
  144. the same is as the number of bits allowed in numbers.
  145. .IP expressions
  146. The following operators are recognized:
  147. .nf
  148. .sp 1
  149. op type action
  150. | binary bitwise or
  151. & binary bitwise and
  152. ^ binary bitwise exclusive or
  153. + binary two's complement addition
  154. + unary no effect
  155. - binary two's complement subtraction
  156. - unary two's complement negation
  157. * binary two's complement multiplication
  158. / binary two's complement division
  159. % binary two's complement remainder
  160. .tr ~~
  161. ~ unary one's complement negation
  162. .tr ~
  163. .sp 1
  164. .fi
  165. The operator precedence is the same as in C.
  166. .br
  167. The operands allowed are: identifiers, numbers and expressions.
  168. The evaluation order can be changed using the brackets '[' and
  169. \&']'.
  170. .sp
  171. .IP comment
  172. The character '!' denotes the start of comment, every character
  173. up to the next newline is skipped.
  174. Exclamation marks in strings are not recognized as the start of
  175. comment.
  176. .IP statements
  177. Statements are separated by newlines and ';' and can be
  178. preceded by label definitions.
  179. Label definitions have the form "\fIidentifier\fP~:" or
  180. "\fIdigit\fP~:".
  181. Statements can be: empty, an assignment, an instruction or a
  182. pseudo-instruction.
  183. .IP assignment
  184. An assignment has the form:
  185. .br
  186. \fIidentifier\fP = \fIexpression\fP
  187. .br
  188. The identifier receives the value and type of the expression.
  189. .IP instruction
  190. The syntax of an instruction depends on the type of the target
  191. machine.
  192. An example of a assembly file is presented at
  193. the end of the document.
  194. .IP pseudo-instruction
  195. .de Pu
  196. .sp 1
  197. .ti +5
  198. \&\\$1
  199. .sp 1
  200. ..
  201. .Pu ".extern \fIidentifier [, identifier]*\fP"
  202. The identifiers mentioned in the list are exported and can be
  203. used in other modules.
  204. .Pu ".define \fIidentifier [, identifier]*\fP"
  205. Used for modules that are to be part of a libary.
  206. The .define pseudo's should be the first in such modules.
  207. When scanning a module in a library the univeral assembler
  208. checks whether any of its unsatified external references is
  209. mentioned in a .define list. If so, it includes that module in
  210. the program.
  211. The identifiers mentioned in the list are exported and can be
  212. used in other modules.
  213. .Pu ".byte \fIexpression [, expression]*\fP"
  214. Initialize a sequence of bytes.
  215. This is not followed by automatic alignment.
  216. .Pu ".short \fIexpression [, expression]*\fP"
  217. Initialize a sequence of shorts (2-byte values).
  218. This is not followed by automatic alignment.
  219. .Pu ".long \fIexpression [, expression]*\fP"
  220. Initialize a sequence of longs (4-byte values).
  221. This is not followed by automatic alignment.
  222. .Pu ".word \fIexpression [, expression]*\fP"
  223. Initialize a sequence of words. The number of bytes occupied by
  224. a word depends on the target machine.
  225. This is not followed by automatic alignment.
  226. .Pu ".ascii \fIstring\fP"
  227. Initialize a sequence of bytes with the value of the bytes in
  228. the string.
  229. This is not followed by automatic alignment.
  230. .Pu ".asciz \fIstring\fP"
  231. Initialize a sequence of bytes with the value of the bytes in
  232. the string and terminate this with an extra zero byte.
  233. This is not followed by automatic alignment.
  234. .Pu ".align [\fIexpression\fP]"
  235. Adjust the current position to a multiple of the value of the
  236. expression.
  237. The default is the word-size of the target machine.
  238. .Pu ".space \fIexpression\fP"
  239. Allocate the indicated amount of bytes.
  240. The expression must be absolute.
  241. .Pu ".org \fIexpression\fP"
  242. Start an org segment with the location counter at the indicated
  243. value.
  244. The value of the expression must be absolute.
  245. .Pu ".text"
  246. .Pu ".data"
  247. .Pu ".bss"
  248. Start an segment of the indicated type.
  249. .Pu ".base \fIexpresssion\fP"
  250. Set the starting address of the first of the consecutive segments
  251. (text) to the value of the expression.
  252. The expression must be absolute.
  253. .Pu ".errnz \fIexpression\fP"
  254. Stop with a fatal error message when the value of the
  255. expression is non-zero.
  256. .SH "SEE ALSO"
  257. ack(I), arch(I), a.out(V)
  258. .SH "EXAMPLE"
  259. An example of INtel 8086 assembly code.
  260. .sp 2
  261. .nf
  262. .ta 8 16 32 40 48 56 64
  263. .define begbss
  264. .define hol0,.diverr,.reghp
  265. .define EIDIVZ
  266. EIDIVZ = 6
  267. base = 0x01C0
  268. topmem = 0xFFF0
  269. .org topmem-16
  270. .extern __n_line
  271. maxmem:
  272. __n_line:
  273. .space 16
  274. .errnz __n_line-0xFFE0
  275. .base base
  276. .text
  277. cld
  278. xor ax,ax
  279. mov (2),cs
  280. mov (0),.diverr
  281. mov sp,maxmem
  282. mov di,begbss
  283. mov cx,[[endbss-begbss]/2]&0x7FFF
  284. ! xor ax,ax ! ax still is 0
  285. rep stos
  286. mov ax,1
  287. push ax
  288. call _start
  289. 3:
  290. jmp 3b
  291. .diverr:
  292. push ax
  293. mov ax,EIDIVZ
  294. call .error
  295. pop ax
  296. iret
  297. cmp 0,4(bx)(di) ! just to show this addr. mode
  298. .data
  299. begdata:
  300. hol0:
  301. .word 0,0
  302. .word 0,0
  303. .word 3f
  304. .reghp:
  305. .word endbss
  306. 3:
  307. .asciz "PROGRAM"
  308. .sp 3
  309. .fi
  310. .SH DIAGNOSTICS
  311. Various diagnostics may be produced.
  312. The most likely errors, however, are unresolved references,
  313. probably caused by the omission of a library argument.
  314. .SH BUGS
  315. The resulting a.out file contains no information about the size
  316. and starting address of the segments.
  317. .br
  318. The resulting a.out file does not contain a symbol table.
  319. .br
  320. The alignment might give rise to internal assertion errors when
  321. the alignment requestes is larger than the machine dependent
  322. segment alignment.
  323. .br
  324. Identifiers declared as externals cannot be used as locals in
  325. any following module.