1asl(1)                      General Commands Manual                     asl(1)
2
3
4

NAME

6       asl - cross assembler for microprocessors and -controllers
7
8

SYNTAX

10       asl [ option(s) ] file(s) [ option(s) ] file(s) ...
11
12

DESCRIPTION

14       AS  is  a  cross assembler that can be used to write assembler programs
15       for a variety of different microprocessors and  -controllers.   asl  is
16       the  UNIX/C  implementation of AS.  A complete description of AS is far
17       beyond the scope of this manual page, which is only intended as a quick
18       reference  for AS's command line interface.  For a more detailed intro‐
19       duction into the usage of AS, see the user's manual.
20
21

COMMAND-LINE PARAMETERS

23       Every argument that starts with a slash (/), plus (+) or minus (-) sign
24       is  regarded as a command-line parameter.  Some command-line parameters
25       take an argument as additional parameter.  Every argument that  is  not
26       recognized  as  a  command-line  parameter  is regarded as an assembler
27       source file to be assembled.  A source file name that does not have  an
28       extension  is automatically extended with the default extension '.asm'.
29       Options are turned on with a parameter starting with  a  slash  (/)  or
30       minus  sign (-), whereas a parameter with a leading plus sign (+) turns
31       an option off.  In the following list, all options will be shown in the
32       form  that  is needed to change the default behaviour, which might be a
33       plus or minus sign, depening on wether the  option  is  on  or  off  by
34       default.
35
36       asl accepts the following command-line parameters:
37
38       -A
39
40              Change  the  data structure that is internally used to store the
41              symbol table.  By default, AS uses binary trees to  store  macro
42              and symbol definitions.  Turning this option on will change this
43              to AVL-balanced trees.  Depending on the ratio of symbol entries
44              and  lookups,  this might speed up assembly.  Using AVL-balanced
45              trees helps also reducing the  stack  usage,  which  is  however
46              irrelevant for the C version of AS.
47
48       -a
49
50              Instruct AS to write out the shared symbol definitions in a for‐
51              mat suitable for including into an AS  assembler  program.   The
52              file's name is constructed by replacing the source file's exten‐
53              sion with '.inc'.  See the  user  manual  for  more  information
54              about symbol sharing.
55
56       -cpu <name>
57              Set  the  target  processor  to  <name>.  Use this option if the
58              source file does not contain a CPU statement.
59
60       -alias <new name=old name>
61              Define a CPU alias.  An alias is a name that can be used  as  an
62              argument  to  the  CPU pseudo-instruction just like an intrinsic
63              CPU type.  Its usage will set the same target as the  old  name,
64              however the predefined symbols MOMCPU and MOMCPUNAME will be set
65              to the new name.  This option is primarily useful for  adding  a
66              new  member to a processor family that has the same core, but is
67              different in its internal peripherals, thus allowing to  distin‐
68              guish between them.
69
70       -C
71
72              Add  a  cross reference table to the assembler listing.  A cross
73              reference table lists all symbols that have been  referenced  at
74              least  once during assembly, including the source line number(s)
75              and count of every reference.  This option only makes sense when
76              the generation of an assembly listing has been turned on via the
77              -L or -l parameters.
78
79       -c
80
81              Instruct AS to write out the shared symbol definitions in a for‐
82              mat suitable for including into a C program.  The file's name is
83              constructed by replacing the source file's extension with  '.h'.
84              See the user manual for more information about symbol sharing.
85
86       -D <name[=value]>[,...]
87              Pre-define  symbols.   Predefined  symbols  are entered into the
88              global symbol table prior to assembly of the source file(s).  If
89              no value is given for a symbol, it is assigned the integer value
90              1.  Value expressions  may  contain  arithmetic  expressions  as
91              described  in  the  user  manual, but they may not reference any
92              other predefined or internal symbols.
93
94       -E [file]
95              Force AS to send warning and error messages to file rather  than
96              to  the standard error output.  The file names !0 to !4 are used
97              to refer to the standard input, output, error,  auxilliary,  and
98              printer  channels  predefined  by  the operating system (on some
99              systems, some of these handles might not exist).  If the  [file]
100              specification is omitted, a name is constructed by replacing the
101              source file's extension with '.log'.
102
103       +G     Supress code generation, reducing the  functionality  of  AS  to
104              macro preprocessing.
105
106       -g [MAP|Atmel|NoICE]
107
108              Instruct  AS to write an additional file containing debug infor‐
109              mation. This information covers the symbol table and  the  rela‐
110              tion  between  source  line  numbers and machine addresses.  The
111              argument specifies whether debug info shall be written  in  AS's
112              own  MAP  format,  the object format for Atmel's AVR tools, or a
113              command file suitable for John Hartman's NoICE.  If no  argument
114              is given, MAP will be chosen.  The file's name is constructed by
115              replacing the source file's extension with  '.map',  '.obj',  or
116              '.noi' respectively.
117
118       -gnuerrors
119
120              Output  errors and their location in the source code in a format
121              similar to the GNU C compiler, thus making it  easier  to  inte‐
122              grate  AS into environments designed for this format.  Note that
123              in contrast to the standard format used by AS, locations  inside
124              are not reported!
125
126       -h
127
128              Force  AS to print all hexadecimal constants with lowercase let‐
129              ters, rather than with  uppercase  letters  A..F  which  is  the
130              default.
131
132       -i <path[:path...]>
133              Add  new  entries  to  the  list  of paths that are searched for
134              include files.  New entries are prepended to the current include
135              path  list, so if multiple paths are given with one command-line
136              parameter, they will be entered into the path  list  in  reverse
137              order.
138
139       -I
140
141              Add  an  include  file list to the assembly listing.  An include
142              file list contains all  files  that  have  been  included  while
143              assembling  the  source  files,  including  multiple  and nested
144              inclusion.  Nesting of  inclusion  is  identified  by  different
145              indention.   This option only makes sense when the generation of
146              an assembly listing has been turned on via the -L or -l  parame‐
147              ters.
148
149       -L
150
151              Turn  on generation of an assembly listing and send it to a file
152              whose name is constructed by replacing the source file's  exten‐
153              sion with '.lst'.
154
155       -l
156
157              Turn  on  generation  of  an assembly listing and send it to the
158              console.
159
160       -M
161
162              Turn on generation of a macro definition file.  A macro  defini‐
163              tion  file  is  a  file that contains all macro definitions that
164              have been detected during assembly, in a format suitable for  an
165              inclusion  into  another file.  The macro definition file's name
166              is constructed by replacing the  source  file's  extension  with
167              '.mac'.
168
169       -n
170
171              Force  AS  to  extend  all error and warning messages with their
172              internal error resp. warning number.
173
174       -noicemask [mask]
175              By default, AS will only write symbols to the NoICE  debug  info
176              that  are  located in the code segment.  By changing this binary
177              mask, more and/or different masks may be chosen.  The assignment
178              is  bit  1=code,  2=data,  3=idata, 4=xdata, 5=ydata, 6=bitdata,
179              7=io, 8=reg, 9=romdata .  Negating this option reverts the  mask
180              to code-only.
181
182       -o <name>
183              Tell  AS to write the code output to a file <name>.  By default,
184              the code output file's name  is  constructed  by  replacing  the
185              source file's extension with '.p'.  If multiple files are assem‐
186              bled with one command, this parameter may also be  given  multi‐
187              ply.   If  there are less output specifications than source file
188              names, AS will switch back  to  the  default  naming  convention
189              after all output specifications have been used up.
190
191       -olist <name>
192
193              Tell  AS  to write the assembly lsting to a file <name>, instead
194              of a file with the standard name in the source file's directory.
195              This  option  only makes sense when an assembly listing has been
196              requested via the '-L' option.
197
198       -shareout <name>
199
200              Tell AS to write shared symbol definitions  to  a  file  <name>,
201              instead  of  constructing  the name from the source file's name.
202              See the user manual for more information about symbol sharing.
203
204       -P
205
206              Turn on generation of a macro output file.  A macro output  file
207              contains  the  intermediate source code that remains after macro
208              expansion and conditional assembly.   The  macro  output  file's
209              name  is  constructed  by  replacing the source file's extension
210              with '.i'.
211
212       -p
213
214              Instruct AS to write out the shared symbol definitions in a for‐
215              mat  suitable  for  including into a Pascal or Modula-2 program.
216              The file's name is constructed by replacing  the  source  file's
217              extension  with '.inc'. See the user manual for more information
218              about symbol sharing.
219
220       -q or -quiet
221              Turn on silent assembly mode.  In silent  compilation  mode,  AS
222              will not do any console output except for warning and error mes‐
223              sages.
224
225       -r [pass number]
226              Tell AS to output warnings when a situation appears in a  source
227              file  that  forces  another  pass  of assembly.  Such situations
228              either take place when a symbol is undefined in the  first  pass
229              or  a  symbol's value has changed compared to the previous pass.
230              This option is useful to track down sources of excessive  multi-
231              passing,  but be aware that it might yield a fairly large number
232              of warnings, especially in the first pass.  Optionally,  a  pass
233              number  may  be  added  to this option to inhibit output until a
234              certain pass is reached.
235
236       -s
237
238              Add a section list to the assembly listing.  A section list con‐
239              tains  all  sections that have been defined in the source files,
240              marking their nesting level by different levels of  indentation.
241              This  option only makes sense when the generation of an assembly
242              listing has been turned on via the -L or -l parameters.
243
244       -t <mask>
245              Turn on or off parts of the assembly listing that have no  indi‐
246              vidual  command  line parameter.  AS internally keeps an integer
247              value whose bits represent certain components of the listing.  A
248              positive  command line parameter (-t or /t) sets the bits set in
249              <mask>, whereas a negated parameter (+t) resets the bits set  in
250              <mask>.  The individual bits have the following meaning: bit 0 =
251              source lines and generated machine code, bit 1 =  symbol  table,
252              bit  2  = macro table, bit 3 = function table, bit 4 = line num‐
253              bering.
254
255       -u
256
257              Tell AS to do additional bookkeeping about which address  ranges
258              have  been  used  by the assembled program.  This option enables
259              the detection of overlapping memory usage.  If an assembly list‐
260              ing has been turned on via the -L or -l parameters, it will also
261              contain a list of all used memory areas.
262
263       -U
264
265              Force AS to operate in case-sensitive mode.  By  default,  names
266              of  symbols,  macros,  user-defined  functions  and sections are
267              treated in a case-insensitive manner.
268
269       -w
270
271              Suppress output of warnings.
272
273       -x
274
275              Turn on extended error reporting.  With extended  error  report‐
276              ing, several error and warning messages will also print the item
277              that created the message, e.g. the name of an  unknown  instruc‐
278              tion.   When  this  option  is given twice, the erroneous source
279              line is additinally printed.
280
281

PRESETTING PARAMETERS

283       Parameters need not neccessarily be given in the command  line  itself.
284       Before  processing  of  command line parameters starts, AS will look if
285       the ASCMD environment variable is defined.  If it exists, its  contents
286       will  be  treated as additional command line parameters whose syntax is
287       absolutely equal to normal command line parameters.   An  exception  is
288       made  if the variable's contents start with a '@' sign; in such a case,
289       the string after the '@' sign is treated as the name  of  a  file  that
290       contains  the  options.  Such a file (also called a 'key file') has the
291       advantage that it allows the options to be written in different  lines,
292       and  it  does  not have a size limit.  Some operating systems (like MS-
293       DOS) have a length limit on command lines and environment variable con‐
294       tents,  so  the  key  file may be your only option if you have a lot of
295       lengthy parameters for AS.
296
297       As parameters given in the ASCMD environment variable or a key file are
298       processed  prior to the command line itself, and can therefore be over‐
299       ridden by command line parameters.
300
301

NATIONAL LANGUAGE SUPPORT

303       AS supports the needs of different languages and countries in the sense
304       that  it  will try to adapt to the language and date/time formats valid
305       for the current environment.  Upon startup, the COUNTRY setting made in
306       the  CONFIG.SYS file is queried for DOS and OS/2 implementations of AS.
307       For UNIX systems, AS tries to read the LC_TIME resp. LC_MESSAGES  envi‐
308       ronment  variables to find out the correct format for date/time outputs
309       resp. the local language.  If this fails, the LC_ALL and  finally  LANG
310       variables are probed.  If none of these environment variables points to
311       a specific local environment  resp.  contains  a  locale  specification
312       unknown to AS, the standard english/C locale is used.
313
314       The  messages  AS can output in different languages are stored in sepa‐
315       rate files with the extension '.msg' .  AS will search for these  files
316       in the following directories:
317
318       - The current directory
319
320       - The directory the executable of AS was loaded from (only on DOS plat‐
321       forms version >=3.0 or if path was explicitly specified)
322
323       - The directory specified in the AS_MSGPATH environment variable  resp.
324       the  directories  listed in the PATH environment variable if AS_MSGPATH
325       does not exist.
326
327       - The LIBDIR directory set at compile time from the Makefile.
328
329
330

RETURN CODES

332       Depending on the assembly's turnout, asl will generate different return
333       codes:
334
335       0      No errors, warnings might have occured.
336
337       1      No  command  line parameters were given, AS printed a short list
338              of possible command line parameters and terminated thereafter.
339
340       2      Errors occured during assembly of at least one source  file,  no
341              code file was generated for the corresponding source file(s).
342
343       3      A fatal error occured during assembly that forced immediate pro‐
344              gram termination.  Code files may be generated, but are probably
345              unusuable.
346
347       4      Program termination already occured during initialization.  This
348              might be either due to a incorrect command line parameter or  an
349              error  during  loading the program's overlay file (only possible
350              on MS-DOS).
351
352       255    During initialization, an internal error  happened  that  should
353              not occur.  If the reaction is reproducable, note down the situ‐
354              ation and send a bug report to the author.
355
356

EXAMPLES

358       To assemble a source file file1.asm without any  additional  bells  and
359       whistles, use:
360
361       asl file1
362
363       which  will  create  an  output  file  file1.p  given that there are no
364       errors.  If you additionally want a listing and rename the output  file
365       to a.out, use
366
367       asl -L file1 -o a.out
368
369       To  make  the  listing  as  comprehensive  as  possible and to get more
370       detailed error messages, use:
371
372       asl -LuCIs -t 16 -nx file1
373
374

TIPS

376       calling AS without any parameters will print a  short  help  containing
377       all  command  line  parameters and implemented target processors, while
378       calling with command line parameters but without any source  file  name
379       will result in AS asking for a source file name on the console.
380
381

SEE ALSO

383       plist(1), pbind(1), p2hex(1), p2bin(1)
384
385

HISTORY

387       AS  originally  appeared  as a DOS program in 1989, written in Borland-
388       Pascal, and was ported to C and UNIX in 1996.
389
390

BUGS

392       There are too many options.
393
394       Command line interpreters of some operating systems reserve some  char‐
395       acters for their own use, so it might be necessary to give command line
396       parameters with certain tricks (e.g., with the help of  escape  charac‐
397       ters).
398
399

AUTHOR(S)

401       Alfred Arnold (alfred@ccac.rwth-aachen.de), and a few others...
402
403
404
405                                                                        asl(1)
Impressum