1This chapter describes the module-independent part of the assembler. It 2documents the options and extensions which are not specific to a certain 3target, syntax or output driver. Be sure to also read the chapters on the 4backend, syntax- and output-module you are using. They will 5likely contain important additional information like data-representation 6or additional options. 7 8@node General Assembler Options 9@section General Assembler Options 10 11 @command{vasm} is run using the following syntax: 12 13@example 14 @command{vasm<target>_<syntax> [options] file} 15@end example 16 17 The following options are supported by the machine independent part 18 of @command{vasm}: 19 20@table @option 21 22@item -chklabels 23 Issues a warning when a label matches a mnemonic or directive name 24 in either upper or lower case. 25 26@item -D<name>[=expression] 27 Defines a symbol with the name <name> and assigns the value of the 28 expression when given. The assigned value defaults to 1 otherwise. 29 30@item -depend=<type> 31 Print all dependencies while assembling the source with the given 32 options. No output is generated. <type> may be @option{list} for 33 printing one file name in each new line, or @option{make} for printing 34 a sequence of file names on a single line, suitable for Makefiles. 35 When the output file name is given by @option{-o} then 36 @command{vasm} will also print @code{outname:} in front of it. 37 Note that unlike with @option{-dependall} only relative include 38 file dependencies will be listed (which is the common case). 39 40@item -dependall=<type> 41 Prints dependencies in the same way as @option{-depend}, but 42 will also print all include files with absolute paths. 43 44@item -esc 45 Enable escape character sequences. This will make vasm treat the 46 escape character \ in string constants similar as in the C language. 47 48@item -F<fmt> 49 Use module <fmt> as output driver. See the chapter on output 50 drivers for available formats and options. 51 52@item -I<path> 53 Define another include path. They are searched in the order of 54 occurence on the command line. 55 56@item -ignore-mult-inc 57 When the same file is included multiple times with the same path 58 this is silently ignored, causing the file to be processed only 59 once. Note that you can still include the same file twice when 60 using different paths to access it. 61 62@item -L <listfile> 63 Enables generation of a listing file and directs the output into 64 the file <listfile>. 65 66@item -Ll<lines> 67 Set the number of lines per listing file page to <lines>. 68 69@item -Lnf 70 Do not emit any form feed code into the listing file, for starting 71 a new page. 72 73@item -Lns 74 Do not include symbols in the listing file. 75 76@item -maxerrors=<n> 77 Defines the maximum number of errors to display before assembly 78 is aborted. When <n> is 0 then there is no limit. Defaults to 5. 79 80@item -maxmacrecurs=<n> 81 Defines the maximum of number of recursions within a macro. 82 Defaults to 1000. 83 84@item -nocase 85 Disables case-sensitivity for everything - identifiers, directives 86 and instructions. Note that directives and instructions may already 87 be case-insensitive by default in some modules. 88 89@item -noesc 90 No escape character sequences. This will make vasm treat the 91 escape character \ as any other character. Might be useful for 92 compatibility. 93 94@item -noialign 95 Perform no automatic alignment for instructions. Note that 96 unaligned instructions make your code crash when executed! 97 Only set when you know what you do! 98 99@item -nosym 100 Strips all local symbols from the output file and doesn't include 101 any other symbols than those which are required for external 102 linkage. 103 104@item -nowarn=<n> 105 Disable warning message <n>. <n> has to be the number of a valid 106 warning message, otherwise an error is generated. 107 108@item -o <ofile> 109 Write the generated assembler output to <ofile> rather than 110 @file{a.out}. 111 112@item -pic 113 Try to generate position independant code. Every relocation is 114 flagged by an error message. 115 116@item -quiet 117 Do not print the copyright notice and the final statistics. 118 119@item -unnamed-sections 120 Sections are no longer distinguished by their name, but only by 121 their attributes. This has the effect that when defining a second 122 section with a different name but same attributes as a first one, 123 it will switch to the first, instead of starting a new section. 124 125@item -unsshift 126 The shift-right operator (@code{>>}) treats the value to shift as 127 unsigned, which has the effect that 0-bits are inserted on the 128 left side. The number of bits in a value depend on the target 129 address type (refer to the appropriate cpu module documentation). 130 131@item -w 132 Hide all warning messages. 133 134@item -x 135 Show an error message, when referencing an undefined symbol. 136 The default behaviour is to declare this symbol as externally 137 defined. 138 139@end table 140 141Note that while most options allow an argument without any separating blank, 142some others require it (e.g. @option{-o} and @option{-L}). 143 144@section Expressions 145 146Standard expressions are usually evaluated by the main part of vasm 147rather than by one of the modules (unless this is necessary). 148 149All expressions evaluated by the frontend are calculated in terms 150of target address values, i.e. the range depends on the backend. 151 152The available operators include all those which are common in assembler as 153well as in C expressions. 154 155C like operators: 156@itemize 157@item Unary: @code{+ - ! ~} 158@item Arithmetic: @code{+ - * / % << >>} 159@item Bitwise: @code{& | ^} 160@item Logical: @code{&& ||} 161@item Comparative: @code{< > <= >= == !=} 162@end itemize 163 164Assembler like operators: 165@itemize 166@item Unary: @code{+ - ~} 167@item Arithmetic: @code{+ - * / // << >>} 168@item Bitwise: @code{& ! ~} 169@item Comparative: @code{< > <= >= = <>} 170@end itemize 171 172Up to version 1.4b the operators had the same precedence and associativity as 173in the C language. Newer versions have changed the operator priorities to 174comply with the common assembler behaviour. The expression evaluation 175priorities, from highest to lowest, are: 176 177@enumerate 1 178@item @code{+ - ! ~} (unary +/- sign, not, complement) 179@item @code{<< >>} (shift left, shift right) 180@item @code{&} (bitwise and) 181@item @code{^ ~} (bitwise exclusive-or) 182@item @code{| !} (bitwise inclusive-or) 183@item @code{* / % //} (multiply, divide, modulo) 184@item @code{+ -} (plus, minus) 185@item @code{< > <= >=} (less, greater, less or equal, greater or equal) 186@item @code{== != = <>} (equality, inequality) 187@item @code{&&} (logical and) 188@item @code{||} (logical or) 189@end enumerate 190 191Operands are integral values of the target address type. They can either be 192specified as integer constants of different bases (see the documentation 193on the syntax module to see how the base is specified) or character 194constants. Character constants are introduced by @code{'} or @code{"} 195and have to be terminated by the same character that started them. 196 197Multiple characters are allowed and a constant is built according to the 198endianess of the target. 199 200When the @option{-esc} option was specified, or automatically enabled by 201a syntax module, vasm interprets escape character sequences as in the 202C language: 203 204@table @code 205 206@item \\ 207 Produces a single @code{\}. 208 209@item \b 210 The bell character. 211 212@item \f 213 Form feed. 214 215@item \n 216 Line feed. 217 218@item \r 219 Carriage return. 220 221@item \t 222 Tabulator. 223 224@item \" 225 Produces a single @code{"}. 226 227@item \' 228 Produces a single @code{'}. 229 230@item \e 231 Escape character (27). 232 233@item \<octal-digits> 234 One character with the code specified by the digits 235 as octal value. 236 237@item \x<hexadecimal-digits> 238 One character with the code specified by the digits 239 as hexadecimal value. 240 241@item \X<hexadecimal-digits> 242 Same as @code{\x}. 243 244@end table 245 246Note, that the default behaviour of vasm has changed since V1.7! Escape 247sequence handling has been the default in older versions. This has been 248changed to increase compatibility with other assemblers. Use @option{-esc} 249to assemble sources with escape character sequences. It is still the 250default in the @code{std} syntax module, though. 251 252@section Symbols 253 254You can define as many symbols as your available memory permits. A symbol 255may have any length and can be of global or local scope. Internally, there 256are three types of symbols: 257@table @code 258@item Expression 259 These symbols are usually not visible outside the 260 source, unless they are explicitely exported. 261@item Label 262 Labels are always addresses inside a program section. By 263 default they have local scope for the linker. 264@item Imported 265 These symbols are externally defined and must be 266 resolved by the linker. 267@end table 268 269Beginning with vasm V1.5c one expression symbol is always defined to allow 270conditional assembly depending on the assembler being used: @code{__VASM}. 271Its value depends on the selected cpu module. There may be other symbols which 272are pre-defined by the syntax- or by the cpu module. 273 274@section Include Files 275 276Vasm supports include files and defining include paths. Whether this 277functionality is available depends on the syntax module, which has to 278provide the appropriate directives. 279 280On startup vasm will define at least one default include path: the 281current working directory, where the assembler program was launched from. 282When the input file is loaded from a different directory, i.e. the input 283file is a relative or absolute path and not a single file name, then the 284path to the input file name will be added as another include path. 285 286Include paths are searched in the following order: 287@enumerate 1 288@item Current work directory. 289@item Paths specified by @option{-I} in the order of occurence on the 290 command line. 291@item Path to the input source file. 292@item Paths specified by directives inside the source text (in the order 293 of occurence). 294@end enumerate 295 296@section Macros 297 298Macros are supported by vasm, but the directives for defining them have 299to be implemented in the syntax module. The assembler core supports 9 300macro arguments by default to be passed in the operand field, 301which can be extended to any number by the syntax module. 302They can be referenced inside the macro either by name (@code{\name}) or by 303number (@code{\1} to @code{\9}), or both, depending on the syntax module. 304Recursions and early exits are supported. 305 306Refer to the selected syntax module for more details. 307 308@section Structures 309 310Vasm supports structures, but the directives for defining them 311have to be implemented in the syntax module. 312 313@section Conditional Assembly 314 315Has to be provided completely by the syntax module. 316 317@section Known Problems 318 319 Some known module-independent problems of @command{vasm} at the moment: 320 321@itemize @minus 322 323@item None. 324 325@end itemize 326 327@section Credits 328 329 All those who wrote parts of the @command{vasm} distribution, made suggestions, 330 answered my questions, tested @command{vasm}, reported errors or were otherwise 331 involved in the development of @command{vasm} (in descending alphabetical order, 332 under work, not complete): 333 334@itemize 335 @item Joseph Zatarski 336 @item Frank Wille 337 @item Henryk Richter 338 @item Sebastian Pachuta 339 @item Esben Norby 340 @item Gunther Nikl 341 @item George Nakos 342 @item Timm S. Mueller 343 @item Gareth Morris 344 @item Dominic Morris 345 @item Mauricio Mu@~noz Lucero 346 @item J@"org van de Loo 347 @item Robert Leffmann 348 @item Andreas Larsson 349 @item Miro Kropacek 350 @item Mikael Kalms 351 @item Matthew Hey 352 @item Philippe Guichardon 353 @item Romain Giot 354 @item Francois Galea 355 @item Tom Duin 356 @item Karoly Balogh 357@end itemize 358 359@section Error Messages 360 361The frontend has the following error messages: 362 363@itemize @minus 364@item 1: illegal operand types 365@item 2: unknown mnemonic <%s> 366@item 3: unknown section <%s> 367@item 4: no current section specified 368@item 5: internal error %d in line %d of %s 369@item 6: symbol <%s> redefined 370@item 7: %c expected 371@item 8: cannot resolve section <%s>, maximum number of passes reached 372@item 9: instruction not supported on selected architecture 373@item 10: number or identifier expected 374@item 11: could not initialize %s module 375@item 12: multiple input files 376@item 13: could not open <%s> for input 377@item 14: could not open <%s> for output 378@item 15: unknown option <%s> 379@item 16: no input file specified 380@item 17: could not initialize output module <%s> 381@item 18: out of memory 382@item 19: symbol <%s> recursively defined 383@item 20: fail: %s 384@item 21: section offset is lower than current pc 385@item 22: target data type overflow (%d bits) 386@item 23: undefined symbol <%s> 387@item 24: trailing garbage after option -%c 388@item 25: missing pacro parameters 389@item 26: missing end directive for macro "%s" 390@item 27: macro definition inside macro "%s" 391@item 28: maximum number of %d macro arguments exceeded 392@item 29: option -%c was specified twice 393@item 30: read error on <%s> 394@item 31: expression must be constant 395@item 32: initialized data in bss 396@item 33: missing end directive in repeat-block 397@item 34: #%d is not a valid warning message 398@item 35: relocation not allowed 399@item 36: illegal escape sequence \%c 400@item 37: no current macro to exit 401@item 38: internal symbol %s redefined by user 402@item 39: illegal relocation 403@item 40: label name conflicts with mnemonic 404@item 41: label name conflicts with directive 405@item 42: division by zero 406@item 43: illegal macro argument 407@item 44: reloc org is already set 408@item 45: reloc org was not set 409@item 46: address space overflow 410@item 47: bad file-offset argument 411@item 48: assertion "%s" failed: %s 412@item 49: cannot declare structure within structure 413@item 50: no structure 414@item 51: instruction has been auto-aligned 415@item 52: macro name conflicts with mnemonic 416@item 53: macro name conflicts with directive 417@item 54: non-relocatable expression in equate <%s> 418@item 55: initialized data in offset section 419@item 56: illegal structure recursion 420@item 57: maximum number of macro recursions (%d) reached 421@item 58: data has been auto-aligned 422@item 59: register symbol <%s> redefined 423@item 60: cannot evaluate constant huge integer expression 424@item 61: cannot evaluate floating point expression 425@item 62: imported symbol <%s> was not referenced 426@item 63: symbol <%s> already defined with %s scope 427@item 64: unexpected "else" without "if" 428@item 65: unexpected "endif" without "if" 429@item 66: maximum if-nesting depth exceeded (%d levels) 430@item 67: "endif" missing for conditional block started at %s line %d 431@item 68: repeatedly defined symbol <%s> 432@item 69: macro <%s> does not exist 433@item 70: register <%s> does not exist 434@item 71: register symbol <%s> has wrong type 435@item 72: cannot mix positional and keyword arguments 436@item 73: undefined macro argument name 437@item 74: required macro argument %d was left out 438@item 75: label <%s> redefined 439 440@end itemize 441