Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
asl(1)			    General Commands Manual			asl(1)

NAME
       asl - cross assembler for microprocessors and -controllers

SYNTAX
       asl [ option(s) ] file(s) [ option(s) ] file(s) ...

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

COMMAND-LINE PARAMETERS
       Every argument that starts with a slash (/), plus (+) or	minus (-) sign
       is  regarded as a command-line parameter.  Some command-line parameters
       take an argument	as additional parameter.  Every	argument that  is  not
       recognized  as  a  command-line	parameter  is regarded as an assembler
       source file to be assembled.  A source file name	that does not have  an
       extension  is automatically extended with the default extension '.asm'.
       Options are turned on with a parameter starting with a slash (/)	or mi-
       nus sign	(-), whereas a parameter with a	leading	plus sign (+) turns an
       option off.  In the following list, all options will be	shown  in  the
       form  that  is needed to	change the default behaviour, which might be a
       plus or minus sign, depening on wether the option is on or off  by  de-
       fault.

       asl accepts the following command-line parameters:

       -A

	      Change  the  data	structure that is internally used to store the
	      symbol table.  By	default, AS uses binary	trees to  store	 macro
	      and symbol definitions.  Turning this option on will change this
	      to AVL-balanced trees.  Depending	on the ratio of	symbol entries
	      and  lookups,  this might	speed up assembly.  Using AVL-balanced
	      trees helps also reducing	the stack usage, which is however  ir-
	      relevant for the C version of AS.

       -a

	      Instruct AS to write out the shared symbol definitions in	a for-
	      mat suitable for including into an AS  assembler	program.   The
	      file's name is constructed by replacing the source file's	exten-
	      sion with	'.inc'.	 See the  user	manual	for  more  information
	      about symbol sharing.

       -cpu <name>
	      Set  the	target	processor  to  <name>.	Use this option	if the
	      source file does not contain a CPU statement.

       -alias <new name=old name>
	      Define a CPU alias.  An alias is a name that can be used	as  an
	      argument	to  the	 CPU pseudo-instruction	just like an intrinsic
	      CPU type.	 Its usage will	set the	same target as the  old	 name,
	      however the predefined symbols MOMCPU and	MOMCPUNAME will	be set
	      to the new name.	This option is primarily useful	for  adding  a
	      new  member to a processor family	that has the same core,	but is
	      different	in its internal	peripherals, thus allowing to  distin-
	      guish between them.

       -C

	      Add  a  cross reference table to the assembler listing.  A cross
	      reference	table lists all	symbols	that have been	referenced  at
	      least  once during assembly, including the source	line number(s)
	      and count	of every reference.  This option only makes sense when
	      the generation of	an assembly listing has	been turned on via the
	      -L or -l parameters.

       -c

	      Instruct AS to write out the shared symbol definitions in	a for-
	      mat suitable for including into a	C program.  The	file's name is
	      constructed by replacing the source file's extension with	 '.h'.
	      See the user manual for more information about symbol sharing.

       -D <name[=value]>[,...]
	      Pre-define  symbols.   Predefined	 symbols  are entered into the
	      global symbol table prior	to assembly of the source file(s).  If
	      no value is given	for a symbol, it is assigned the integer value
	      1.  Value	expressions may	contain	arithmetic expressions as  de-
	      scribed in the user manual, but they may not reference any other
	      predefined or internal symbols.

       -E [file]
	      Force AS to send warning and error messages to file rather  than
	      to  the standard error output.  The file names !0	to !4 are used
	      to refer to the standard input, output, error,  auxilliary,  and
	      printer  channels	 predefined  by	 the operating system (on some
	      systems, some of these handles might not exist).	If the	[file]
	      specification is omitted,	a name is constructed by replacing the
	      source file's extension with '.log'.

       +G     Supress code generation, reducing	the  functionality  of	AS  to
	      macro preprocessing.

       -g [MAP/Atmel]

	      Instruct	AS to write an additional file containing debug	infor-
	      mation. This information covers the symbol table and  the	 rela-
	      tion between source line numbers and machine addresses.  The ar-
	      gument specifies whether debug info shall	be written in AS's own
	      MAP  format  or  the object format for Atmel's AVR tools.	 If no
	      argument is given, MAP will be chosen.  The file's name is  con-
	      structed by replacing the	source file's extension	with '.map' or
	      '.obj' respectively.

       -h

	      Force AS to print	all hexadecimal	constants with lowercase  let-
	      ters,  rather  than with uppercase letters A..F which is the de-
	      fault.

       -i <path[:path...]>
	      Add new entries to the list of paths that	are searched  for  in-
	      clude  files.   New entries are prepended	to the current include
	      path list, so if multiple	paths are given	with one  command-line
	      parameter,  they	will  be entered into the path list in reverse
	      order.

       -I

	      Add an include file list to the assembly	listing.   An  include
	      file  list  contains all files that have been included while as-
	      sembling the source files, including multiple and	nested	inclu-
	      sion.   Nesting  of  inclusion is	identified by different	inden-
	      tion.  This option only makes sense when the  generation	of  an
	      assembly listing has been	turned on via the -L or	-l parameters.

       -L

	      Turn  on generation of an	assembly listing and send it to	a file
	      whose name is constructed	by replacing the source	file's	exten-
	      sion with	'.lst'.

       -l

	      Turn  on	generation  of	an assembly listing and	send it	to the
	      console.

       -M

	      Turn on generation of a macro definition file.  A	macro  defini-
	      tion  file  is  a	 file that contains all	macro definitions that
	      have been	detected during	assembly, in a format suitable for  an
	      inclusion	 into  another file.  The macro	definition file's name
	      is constructed by	replacing the  source  file's  extension  with
	      '.mac'.

       -n

	      Force AS to extend all error and warning messages	with their in-
	      ternal error resp. warning number.

       -o <name>
	      Tell AS to write the code	output to a file <name>.  By  default,
	      the  code	 output	 file's	 name  is constructed by replacing the
	      source file's extension with '.p'.  If multiple files are	assem-
	      bled  with  one command, this parameter may also be given	multi-
	      ply.  If there are less output specifications than  source  file
	      names,  AS will switch back to the default naming	convention af-
	      ter all output specifications have been used up.

       -shareout <name>
	      Tell AS to write shared symbol definitions to a file <name>, in-
	      stead  of	constructing the name from the source file's name. See
	      the user manual for more information about symbol	sharing.

       -P

	      Turn on generation of a macro output file.  A macro output  file
	      contains	the  intermediate source code that remains after macro
	      expansion	and conditional	assembly.   The	 macro	output	file's
	      name  is	constructed  by	 replacing the source file's extension
	      with '.i'.

       -p

	      Instruct AS to write out the shared symbol definitions in	a for-
	      mat  suitable  for  including into a Pascal or Modula-2 program.
	      The file's name is constructed by	replacing  the	source	file's
	      extension	 with '.inc'. See the user manual for more information
	      about symbol sharing.

       -q or -quiet
	      Turn on silent assembly mode.  In	silent	compilation  mode,  AS
	      will not do any console output except for	warning	and error mes-
	      sages.

       -r [pass	number]
	      Tell AS to output	warnings when a	situation appears in a	source
	      file  that forces	another	pass of	assembly.  Such	situations ei-
	      ther take	place when a symbol is undefined in the	first pass  or
	      a	 symbol's  value  has  changed	compared to the	previous pass.
	      This option is useful to track down sources of excessive	multi-
	      passing,	but be aware that it might yield a fairly large	number
	      of warnings, especially in the first pass.  Optionally,  a  pass
	      number  may  be  added  to this option to	inhibit	output until a
	      certain pass is reached.

       -s

	      Add a section list to the	assembly listing.  A section list con-
	      tains  all  sections that	have been defined in the source	files,
	      marking their nesting level by different levels of  indentation.
	      This  option only	makes sense when the generation	of an assembly
	      listing has been turned on via the -L or -l parameters.

       -t <mask>
	      Turn on or off parts of the assembly listing that	have no	 indi-
	      vidual  command  line parameter.	AS internally keeps an integer
	      value whose bits represent certain components of the listing.  A
	      positive	command	line parameter (-t or /t) sets the bits	set in
	      <mask>, whereas a	negated	parameter (+t) resets the bits set  in
	      <mask>.  The individual bits have	the following meaning: bit 0 =
	      source lines and generated machine code, bit 1 =	symbol	table,
	      bit  2  =	macro table, bit 3 = function table, bit 4 = line num-
	      bering.

       -u

	      Tell AS to do additional bookkeeping about which address	ranges
	      have  been  used	by the assembled program.  This	option enables
	      the detection of overlapping memory usage.  If an	assembly list-
	      ing has been turned on via the -L	or -l parameters, it will also
	      contain a	list of	all used memory	areas.

       -U

	      Force AS to operate in case-sensitive mode.  By  default,	 names
	      of  symbols,  macros,  user-defined  functions  and sections are
	      treated in a case-insensitive manner.

       -w

	      Suppress output of warnings.

       -x

	      Turn on extended error reporting.	 With extended	error  report-
	      ing, several error and warning messages will also	print the item
	      that created the message,	e.g. the name of an  unknown  instruc-
	      tion.   When  this  option  is given twice, the erroneous	source
	      line is additinally printed.

PRESETTING PARAMETERS
       Parameters need not neccessarily	be given in the	command	 line  itself.
       Before  processing  of  command line parameters starts, AS will look if
       the ASCMD environment variable is defined.  If it exists, its  contents
       will  be	 treated as additional command line parameters whose syntax is
       absolutely equal	to normal command line parameters.   An	 exception  is
       made  if	the variable's contents	start with a '@' sign; in such a case,
       the string after	the '@'	sign is	treated	as the name  of	 a  file  that
       contains	 the  options.	Such a file (also called a 'key	file') has the
       advantage that it allows	the options to be written in different	lines,
       and  it	does  not have a size limit.  Some operating systems (like MS-
       DOS) have a length limit	on command lines and environment variable con-
       tents,  so  the	key  file may be your only option if you have a	lot of
       lengthy parameters for AS.

       As parameters given in the ASCMD	environment variable or	a key file are
       processed  prior	to the command line itself, and	can therefore be over-
       ridden by command line parameters.

NATIONAL LANGUAGE SUPPORT
       AS supports the needs of	different languages and	countries in the sense
       that  it	 will try to adapt to the language and date/time formats valid
       for the current environment.  Upon startup, the COUNTRY setting made in
       the  CONFIG.SYS file is queried for DOS and OS/2	implementations	of AS.
       For UNIX	systems, AS tries to read the LC_TIME resp. LC_MESSAGES	 envi-
       ronment	variables to find out the correct format for date/time outputs
       resp. the local language.  If this fails, the LC_ALL and	 finally  LANG
       variables are probed.  If none of these environment variables points to
       a specific local	environment resp. contains a locale specification  un-
       known to	AS, the	standard english/C locale is used.

       The  messages  AS can output in different languages are stored in sepa-
       rate files with the extension '.msg' .  AS will search for these	 files
       in the following	directories:

       - The current directory

       - The directory the executable of AS was	loaded from (only on DOS plat-
       forms version >=3.0 or if path was explicitly specified)

       - The directory specified in the	AS_MSGPATH environment variable	 resp.
       the  directories	 listed	in the PATH environment	variable if AS_MSGPATH
       does not	exist.

       - The LIBDIR directory set at compile time from the Makefile.

RETURN CODES
       Depending on the	assembly's turnout, asl	will generate different	return
       codes:

       0      No errors, warnings might	have occured.

       1      No  command  line	parameters were	given, AS printed a short list
	      of possible command line parameters and terminated thereafter.

       2      Errors occured during assembly of	at least one source  file,  no
	      code file	was generated for the corresponding source file(s).

       3      A	fatal error occured during assembly that forced	immediate pro-
	      gram termination.	 Code files may	be generated, but are probably
	      unusuable.

       4      Program termination already occured during initialization.  This
	      might be either due to a incorrect command line parameter	or  an
	      error  during  loading the program's overlay file	(only possible
	      on MS-DOS).

       255    During initialization, an	internal error	happened  that	should
	      not occur.  If the reaction is reproducable, note	down the situ-
	      ation and	send a bug report to the author.

EXAMPLES
       To assemble a source file file1.asm without any	additional  bells  and
       whistles, use:

       asl file1

       which  will  create  an output file file1.p given that there are	no er-
       rors.  If you additionally want a listing and rename the	output file to
       a.out, use

       asl -L file1 -o a.out

       To  make	 the  listing as comprehensive as possible and to get more de-
       tailed error messages, use:

       asl -LuCIs -t 16	-nx file1

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

SEE ALSO
       plist(1), pbind(1), p2hex(1), p2bin(1)

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

BUGS
       There are too many options.

       Command line interpreters of some operating systems reserve some	 char-
       acters for their	own use, so it might be	necessary to give command line
       parameters with certain tricks (e.g., with the help of  escape  charac-
       ters).

AUTHOR(S)
       Alfred Arnold (a.arnold@kfa-juelich.de),	and a few others...

									asl(1)

NAME | SYNTAX | DESCRIPTION | COMMAND-LINE PARAMETERS | PRESETTING PARAMETERS | NATIONAL LANGUAGE SUPPORT | RETURN CODES | EXAMPLES | TIPS | SEE ALSO | HISTORY | BUGS | AUTHOR(S)

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=asl&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help