diff options
Diffstat (limited to 'frontends/yasm/yasm.xml')
| -rw-r--r-- | frontends/yasm/yasm.xml | 552 |
1 files changed, 552 insertions, 0 deletions
diff --git a/frontends/yasm/yasm.xml b/frontends/yasm/yasm.xml new file mode 100644 index 0000000..0f07462 --- /dev/null +++ b/frontends/yasm/yasm.xml @@ -0,0 +1,552 @@ +<?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"> + +<refentry id="yasm"> + + <refentryinfo> + <title>The Yasm Modular Assembler</title> + <date>April 2007</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> + <year>2005</year> + <year>2006</year> + <year>2007</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>other options</replaceable></option> + </arg> + <arg choice="req"><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. Yasm currently supports the x86 and AMD64 instruction + sets, accepts NASM and GAS assembler syntaxes, outputs binary, + ELF32, ELF64, COFF, Win32, and Win64 object formats, and generates + source debugging information in STABS, DWARF 2, and CodeView 8 + formats.</para> + + <para>YASM consists of the <command>yasm</command> command, libyasm, + the core backend library, and a large number of modules. + Currently, libyasm and the loadable modules are statically built + into the <command>yasm</command> executable.</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 with an <replaceable>infile</replaceable> of + <quote>-</quote>, <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. Options are listed in alphabetical order.</para> + + <refsect2> + <title>General Options</title> + + <variablelist> + <varlistentry> + <term><option>-a <replaceable>arch</replaceable></option> or + <option>--arch=<replaceable>arch</replaceable></option>: Select + target architecture</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 a list of supported architectures.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-f <replaceable>format</replaceable></option> or + <option>--oformat=<replaceable>format</replaceable></option>: + Select object format</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>. See + + <citerefentry> + <refentrytitle>yasm_objfmts</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry> + + for a list of supported object formats.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-g <replaceable>debug</replaceable></option> or + <option>--dformat=<replaceable>debug</replaceable></option>: + Select debugging format</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>. See + + <citerefentry> + <refentrytitle>yasm_dbgfmts</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry> + + for a list of supported debugging formats.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-L <replaceable>list</replaceable></option> or + <option>--lformat=<replaceable>list</replaceable></option>: + Select list file format</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>-l <replaceable>listfile</replaceable></option> or + <option>--list=<replaceable>listfile</replaceable></option>: + Specify list filename</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>: + Select target machine architecture</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> + + <varlistentry> + <term><option>-o <replaceable>filename</replaceable></option> or + <option>--objfile=<replaceable>filename</replaceable></option>: + Specify object filename</term> + + <listitem> + <para>Specifies the name of the output file, overriding any + default name generated by Yasm.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-p <replaceable>parser</replaceable></option> or + <option>--parser=<replaceable>parser</replaceable></option>: + Select parser</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. Another available parser is + <quote>gas</quote>, which emulates the syntax of GNU AS. To + print a list of available parsers to standard output, use + <quote>help</quote> as <replaceable>parser</replaceable>. See + + <citerefentry> + <refentrytitle>yasm_parsers</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry> + + for a list of supported parsers.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-r <replaceable>preproc</replaceable></option> or + <option>--preproc=<replaceable>preproc</replaceable></option>: + Select preprocessor</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>-h</option> or <option>--help</option>: Print a + summary of options</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>--version</option>: Get the Yasm version</term> + + <listitem> + <para>This option causes Yasm to prints the version number of + Yasm as well as a license summary to standard output. All + other options are ignored, and no output file is + generated.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2> + <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> + + <para>The warning options are handled in the order given on the + command line, so if <option>-w</option> is followed by + <option>-Worphan-labels</option>, all warnings are turned off + <emphasis>except</emphasis> for orphan-labels.</para> + + <variablelist> + <varlistentry> + <term><option>-w</option>: Inhibit all warning messages</term> + + <listitem> + <para>This option causes Yasm to inhibit all warning messages. + As discussed above, this option may be followed by other + options to re-enable specified warnings.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-Werror</option>: Treat warnings as errors</term> + + <listitem> + <para>This option causes Yasm to treat all warnings as errors. + Normally warnings do not prevent an object file from being + generated and do not result in a failure exit status from + <command>yasm</command>, whereas errors do. This option makes + warnings equivalent to errors in terms of this behavior.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-Wno-unrecognized-char</option>: Do not warn on + unrecognized input characters</term> + + <listitem> + <para>Causes Yasm to not warn on unrecognized characters found + in the input. Normally Yasm will generate a warning for any + non-ASCII character found in the input file.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-Worphan-labels</option>: Warn on labels lacking a + trailing option</term> + + <listitem> + <para>When using the NASM-compatible parser, causes Yasm to warn + about labels found alone on a line without a trailing colon. + While these are legal labels in NASM syntax, they may be + unintentional, due to typos or macro definition + ordering.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-X <replaceable>style</replaceable></option>: + Change error/warning reporting style</term> + + <listitem> + <para>Selects a specific output style for 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> + + <para>This option is available so that Yasm integrates more + naturally into IDE environments such as <application + class="software">Visual Studio</application> or <application + class="software">Emacs</application>, allowing the IDE to + correctly recognize the error/warning message as such and link + back to the offending line of source code.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2> + <title>Preprocessor Options</title> + + <para>While these preprocessor options theoretically will affect + any preprocessor, the only preprocessor currently in Yasm is the + <quote>nasm</quote> preprocessor.</para> + + <variablelist> + <varlistentry> + <term><option>-D + <replaceable>macro[=value]</replaceable></option>: Pre-define a + macro</term> + + <listitem> + <para>Pre-defines a single-line macro. The value is optional + (if no value is given, the macro is still defined, but to an + empty value).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-e</option> or <option>--preproc-only</option>: + Only preprocess</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>: Add + include file path</term> + + <listitem> + <para>Adds directory <replaceable>path</replaceable> to the + search path for include files. The search path defaults to + only including the directory in which the source file + resides.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-P <replaceable>filename</replaceable></option>: + Pre-include a file</term> + + <listitem> + <para>Pre-includes file <replaceable>filename</replaceable>, + making it look as though <replaceable>filename</replaceable> + was prepended to the input. Can be useful for prepending + multi-line macros that the <option>-D</option> can't + support.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-U <replaceable>macro</replaceable></option>: + Undefine a macro</term> + + <listitem> + <para>Undefines a single-line macro (may be either a built-in + macro or one defined earlier in the command line with + <option>-D</option>.</para> + + </listitem> + </varlistentry> + </variablelist> + </refsect2> + </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 elf32 -Worphan-labels source.asm</screen></para> + + <para>To assemble NASM syntax AMD64 source + <filename>x.asm</filename> into Win64 file + <filename>object.obj</filename>: + + <screen>yasm -f win64 -o object.obj x.asm</screen></para> + + <para>To assemble already preprocessed NASM syntax 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> + + <para>Yasm's GAS parser and preprocessor are missing a number of + features present in GNU AS.</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 symbol maps.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para><citerefentry> + <refentrytitle>yasm_arch</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>yasm_dbgfmts</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>yasm_objfmts</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>yasm_parsers</refentrytitle> + <manvolnum>7</manvolnum> + </citerefentry></para> + + <para>Related tools: + <citerefentry> + <refentrytitle>as</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>ld</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, + <citerefentry> + <refentrytitle>nasm</refentrytitle> + <manvolnum>1</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> or selecting a 64-bit + object format such as ELF64 on the command line).</para> + </refsect1> +</refentry> |