1asl(1) General Commands Manual asl(1)
2
6 asl - cross assembler for microprocessors and -controllers
7
10 asl [ option(s) ] file(s) [ option(s) ] file(s) ...
11
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
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 asl accepts the following command-line parameters:
37 -A
39 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 -a
49 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 -cpu <name>
57 Set the target processor to <name>. Use this option if the
58 source file does not contain a CPU statement.
59 -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 -C
71 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 -c
80 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 -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 -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 +G Supress code generation, reducing the functionality of AS to
104 macro preprocessing.
105 -g [MAP|Atmel|NoICE]
107 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 -gnuerrors
119 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 -h
127 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 -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 -I
140 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 -L
150 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 -l
156 Turn on generation of an assembly listing and send it to the
158 console.
159 -M
161 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 -n
170 Force AS to extend all error and warning messages with their
172 internal error resp. warning number.
173 -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 -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 -olist <name>
192 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 -shareout <name>
199 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 -P
205 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 -p
213 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 -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 -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 -s
237 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 -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 -u
256 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 -U
264 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 -w
270 Suppress output of warnings.
272 -x
274 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
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 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
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 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 - The current directory
319 - 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 - 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 - The LIBDIR directory set at compile time from the Makefile.
328
332 Depending on the assembly's turnout, asl will generate different return
333 codes:
334 0 No errors, warnings might have occured.
336 1 No command line parameters were given, AS printed a short list
338 of possible command line parameters and terminated thereafter.
339 2 Errors occured during assembly of at least one source file, no
341 code file was generated for the corresponding source file(s).
342 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 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 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
358 To assemble a source file file1.asm without any additional bells and
359 whistles, use:
360 asl file1
362 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 asl -L file1 -o a.out
368 To make the listing as comprehensive as possible and to get more
370 detailed error messages, use:
371 asl -LuCIs -t 16 -nx file1
373
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
383 plist(1), pbind(1), p2hex(1), p2bin(1)
384
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
392 There are too many options.
393 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
401 Alfred Arnold (alfred@ccac.rwth-aachen.de), and a few others...
402 asl(1)