| <?xml version="1.0"?> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> |
| |
| <!-- $Id$ --> |
| |
| <refentry id="yasm"> |
| |
| <refentryinfo> |
| <title>YASM Modular Assembler</title> |
| <date>September 2004</date> |
| <productname>YASM</productname> |
| <author> |
| <firstname>Peter</firstname> |
| <surname>Johnson</surname> |
| <affiliation> |
| <address><email>peter@tortall.net</email></address> |
| </affiliation> |
| </author> |
| |
| <copyright> |
| <year>2004</year> |
| <holder>Peter Johnson</holder> |
| </copyright> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>yasm</refentrytitle> |
| <manvolnum>1</manvolnum> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>yasm</refname> |
| <refpurpose>The YASM Modular Assembler</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>yasm</command> |
| <arg choice="opt"> |
| <option>-f <replaceable>format</replaceable></option> |
| </arg> |
| <arg choice="opt"> |
| <option>-o <replaceable>outfile</replaceable></option> |
| </arg> |
| <arg choice="opt" rep="repeat"> |
| <option><replaceable>options</replaceable></option> |
| </arg> |
| <arg choice="opt"><replaceable>infile</replaceable></arg> |
| </cmdsynopsis> |
| |
| <cmdsynopsis> |
| <command>yasm</command> |
| <arg choice="plain"> |
| <option>-h</option> |
| </arg> |
| </cmdsynopsis> |
| </refsynopsisdiv> |
| |
| <refsect1><title>Description</title> |
| |
| <para>The YASM Modular Assembler is a portable, retargetable assembler |
| written under the <quote>new</quote> (2 or 3 clause) BSD license. It |
| is designed from the ground up to allow for multiple assembler |
| syntaxes (parsers) to be supported in addition to multiple output |
| object formats and multiple instruction sets. Another primary module |
| of the overall design is an optimizer module.</para> |
| |
| <para>YASM consists of the <command>yasm</command> command, libyasm, the |
| core backend library, and a large number of loadable modules. On some |
| platforms, libyasm and the loadable modules are statically built into |
| the <command>yasm</command> executable rather than being dynamically |
| loaded.</para> |
| |
| <para>The <command>yasm</command> command assembles the file infile and |
| directs output to the file <replaceable>outfile</replaceable> if |
| specified. If <replaceable>outfile</replaceable> is not specified, |
| <command>yasm</command> will derive a default output file name from |
| the name of its input file, usually by appending |
| <filename>.o</filename> or <filename>.obj</filename>, or by removing |
| all extensions for a raw binary file. Failing that, the output file |
| name will be <filename>yasm.out</filename>.</para> |
| |
| <para>If called without an <replaceable>infile</replaceable>, |
| <command>yasm</command> assembles the standard input and directs |
| output to the file <replaceable>outfile</replaceable>, or |
| <filename>yasm.out</filename> if no <replaceable>outfile</replaceable> |
| is specified.</para> |
| |
| </refsect1> |
| |
| <refsect1><title>Options</title> |
| |
| <para>Many options may be given in one of two forms: either a dash |
| followed by a single letter, or two dashes followed by a long option |
| name.</para> |
| |
| <para>The following general options are available:</para> |
| |
| <variablelist> |
| <varlistentry> |
| |
| <term><option>--version</option></term> |
| |
| <listitem> |
| |
| <para>Prints yasm version information and license summary to |
| standard output. All other options are ignored, and no |
| output file is generated.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-h</option> or <option>--help</option></term> |
| |
| <listitem> |
| |
| <para>Prints a summary of invocation options. All other |
| options are ignored, and no output file is |
| generated.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-a <replaceable>arch</replaceable></option> or |
| <option>--arch=<replaceable>arch</replaceable></option></term> |
| |
| <listitem> |
| |
| <para>Selects the target architecture. The default |
| architecture is <quote>x86</quote>, which supports both |
| the IA-32 and derivatives and AMD64 instruction sets. To |
| print a list of available architectures to standard |
| output, use <quote>help</quote> as |
| <replaceable>arch</replaceable>. See <citerefentry> |
| <refentrytitle>yasm_arch</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> for more details.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-p <replaceable>parser</replaceable></option> or |
| <option>--parser=<replaceable>parser</replaceable></option></term> |
| |
| <listitem> |
| |
| <para>Selects the parser (the assembler syntax). The default |
| parser is <quote>nasm</quote>, which emulates the syntax |
| of NASM, the Netwide Assembler. To print a list of |
| available parsers to standard output, use |
| <quote>help</quote> as |
| <replaceable>parser</replaceable>.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-r <replaceable>preproc</replaceable></option> or |
| <option>--preproc=<replaceable>preproc</replaceable></option></term> |
| |
| <listitem> |
| |
| <para>Selects the preprocessor to use on the input file before |
| passing it to the parser. Preprocessors often provide |
| macro functionality that is not included in the main |
| parser. The default preprocessor is <quote>nasm</quote>, |
| which is an imported version of the actual NASM |
| preprocessor. A <quote>raw</quote> preprocessor is also |
| available, which simply skips the preprocessing step, |
| passing the input file directly to the parser. To print a |
| list of available preprocessors to standard output, use |
| <quote>help</quote> as |
| <replaceable>preproc</replaceable>.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-f <replaceable>format</replaceable></option> or |
| <option>--oformat=<replaceable>format</replaceable></option></term> |
| |
| <listitem> |
| |
| <para>Selects the output object format. The default |
| object format is <quote>bin</quote>, which is a flat |
| format binary with no relocation. To print a list of |
| available object formats to standard output, use |
| <quote>help</quote> as |
| <replaceable>format</replaceable>.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-g <replaceable>debug</replaceable></option> or |
| <option>--dformat=<replaceable>debug</replaceable></option></term> |
| |
| <listitem> |
| |
| <para>Selects the debugging format for debug information. |
| Debugging information can be used by a debugger to |
| associate executable code back to the source file or get |
| data structure and type information. Available debug |
| formats vary between different object formats; |
| <command>yasm</command> will error when an invalid |
| combination is selected. The default object format is |
| selected by the object format. To print a list of |
| available debugging formats to standard output, use |
| <quote>help</quote> as |
| <replaceable>debug</replaceable>.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-L <replaceable>list</replaceable></option> or |
| <option>--lformat=<replaceable>list</replaceable></option></term> |
| |
| <listitem> |
| |
| <para>Selects the format/style of the output list file. List |
| files typically intermix the original source with the |
| machine code generated by the assembler. The default list |
| format is <quote>nasm</quote>, which mimics the NASM list |
| file format. To print a list of available list file |
| formats to standard output, use <quote>help</quote> as |
| <replaceable>list</replaceable>.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-o <replaceable>filename</replaceable></option> or |
| <option>--objfile=<replaceable>filename</replaceable></option></term> |
| |
| <listitem> |
| |
| <para>Specifies the name of the output file, overriding any |
| default name selected by <command>yasm</command>.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-l <replaceable>listfile</replaceable></option> or |
| <option>--list=<replaceable>listfile</replaceable></option></term> |
| |
| <listitem> |
| |
| <para>Specifies the name of the output list file. If this |
| option is not used, no list file is generated.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-m <replaceable>machine</replaceable></option> or |
| <option>--machine=<replaceable>machine</replaceable></option></term> |
| |
| <listitem> |
| |
| <para>Selects the target machine architecture. Essentially a |
| subtype of the selected architecture, the machine type |
| selects between major subsets of an architecture. For |
| example, for the <quote>x86</quote> architecture, the two |
| available machines are <quote>x86</quote>, which is used |
| for the IA-32 and derivative 32-bit instruction set, and |
| <quote>amd64</quote>, which is used for the 64-bit |
| instruction set. This differentiation is required to |
| generate the proper object file for relocatable object |
| formats such as COFF and ELF. To print a list of |
| available machines for a given architecture to standard |
| output, use <quote>help</quote> as |
| <replaceable>machine</replaceable> and the given |
| architecture using <option>-a |
| <replaceable>arch</replaceable></option>. See |
| <citerefentry> |
| <refentrytitle>yasm_arch</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> for more details.</para> |
| |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| |
| <refsect1><title>Warning Options</title> |
| |
| <para><option>-W</option> options have two contrary forms: |
| <option>-W<replaceable>name</replaceable></option> and |
| <option>-Wno-<replaceable>name</replaceable></option>. Only the |
| non-default forms are shown here.</para> |
| |
| <variablelist> |
| <varlistentry> |
| |
| <term><option>-w</option></term> |
| |
| <listitem> |
| |
| <para>Inhibits all warning messages.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-Werror</option></term> |
| |
| <listitem> |
| |
| <para>Treats warnings as errors.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-Wno-unrecognized-char</option></term> |
| |
| <listitem> |
| |
| <para>Causes <command>yasm</command> to not warn on |
| unrecognized characters found in the input.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-Worphan-labels</option></term> |
| |
| <listitem> |
| |
| <para>Causes <command>yasm</command> to warn about labels found |
| alone on a line without a trailing colon. While these are |
| legal labels in the <quote>nasm</quote> parser, they may be |
| unintentional, due to typos or macro definition |
| ordering.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-X <replaceable>style</replaceable></option></term> |
| |
| <listitem> |
| |
| <para>Selects a specific output style of error and warning |
| messages. The default is <quote>gnu</quote> style, which |
| mimics the output of <command>gcc</command>. The |
| <quote>vc</quote> style is also available, which mimics the |
| output of Microsoft's Visual C++ compiler.</para> |
| |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| |
| <refsect1><title>Preprocessor Options</title> |
| <variablelist> |
| <varlistentry> |
| |
| <term><option>-e</option> or <option>--preproc-only</option></term> |
| |
| <listitem> |
| |
| <para>Stops assembly after the preprocessing stage; |
| preprocessed output is sent to the specified output name |
| or, if no output name is specified, the standard output. |
| No object file is produced.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-I <replaceable>path</replaceable></option></term> |
| |
| <listitem> |
| |
| <para>Adds directory <replaceable>path</replaceable> to the |
| search path for include files.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-P |
| <replaceable>filename</replaceable></option></term> |
| |
| <listitem> |
| |
| <para>Pre-includes file <replaceable>filename</replaceable>, |
| making it look as though |
| <replaceable>filename</replaceable> was prepended to the |
| input.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-D |
| <replaceable>macro[=value]</replaceable></option></term> |
| |
| <listitem> |
| |
| <para>Pre-defines a single-line macro.</para> |
| |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| |
| <term><option>-U <replaceable>macro</replaceable></option></term> |
| |
| <listitem> |
| |
| <para>Undefines a single-line macro.</para> |
| |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| |
| <refsect1><title>Examples</title> |
| |
| <para>To assemble NASM syntax, 32-bit x86 source |
| <filename>source.asm</filename> into ELF file |
| <filename>source.o</filename>, warning on orphan labels: |
| |
| <screen>yasm -f elf -Worphan-labels source.asm</screen></para> |
| |
| <para>To assemble NASM syntax AMD64 source <filename>x.asm</filename> into |
| AMD64 Win32 file <filename>object.obj</filename>: |
| |
| <screen>yasm -m amd64 -f win32 -o object.obj x.asm</screen></para> |
| |
| <para>To assemble already preprocessed NASM syntax 32-bit x86 source |
| <filename>y.asm</filename> into flat binary file |
| <filename>y.com</filename>: |
| |
| <screen>yasm -f bin -r raw -o y.com y.asm</screen></para> |
| |
| </refsect1> |
| |
| <refsect1><title>Diagnostics</title> |
| |
| <para>The <command>yasm</command> command exits 0 on success, and nonzero |
| if an error occurs.</para> |
| |
| </refsect1> |
| |
| <refsect1><title>Compatibility</title> |
| |
| <para>YASM's NASM parser and preprocessor, while they strive to be as |
| compatible as possible with NASM, have a few incompatibilities due to |
| YASM's different internal structure.</para> |
| |
| </refsect1> |
| |
| <refsect1><title>Restrictions</title> |
| |
| <para>As object files are often architecture and machine dependent, not |
| all combinations of object formats, architectures, and machines are |
| legal; trying to use an invalid combination will result in an |
| error.</para> |
| |
| <para>There is no support for list files or symbol maps.</para> |
| |
| <para>Relocatable object formats are limited to static linking |
| applications, as YASM cannot generate relocations for dynamic |
| linking.</para> |
| |
| </refsect1> |
| |
| <refsect1><title>See Also</title> |
| |
| <para><citerefentry> |
| <refentrytitle>as</refentrytitle> |
| <manvolnum>1</manvolnum> |
| </citerefentry>, |
| <citerefentry> |
| <refentrytitle>ld</refentrytitle> |
| <manvolnum>1</manvolnum> |
| </citerefentry>, |
| <citerefentry> |
| <refentrytitle>nasm</refentrytitle> |
| <manvolnum>1</manvolnum> |
| </citerefentry>, |
| <citerefentry> |
| <refentrytitle>yasm_arch</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry></para> |
| |
| </refsect1> |
| |
| <refsect1><title>Bugs</title> |
| |
| <para>When using the <quote>x86</quote> architecture, it is overly easy to |
| generate AMD64 code (using the <userinput>BITS 64</userinput> |
| directive) and generate a 32-bit object file (by failing to specify |
| <option>-m amd64</option> on the command line). Similarly, specifying |
| <option>-m amd64</option> does not default the BITS setting to |
| 64.</para> |
| |
| </refsect1> |
| |
| </refentry> |
