man/uni_ass.6

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