The well-known GNU C/C++ Compiler (GCC), an optimizing 32-bit compiler at the heart of the GNU project, supports the x86 architecture quite well, and includes the ability to insert assembly code in C programs, in such a way that register allocation can be either specified or left to GCC. GCC works on most available platforms, notably Linux, *BSD, VSTa, OS/2, *DOS, Win*, etc.
The original GCC site is the GNU FTP site ftp://prep.ai.mit.edu/pub/gnu/ together with all the released application software from the GNU project. Linux-configured and precompiled versions can be found in ftp://sunsite.unc.edu/pub/Linux/GCC/ There exists a lot of FTP mirrors of both sites. everywhere around the world, as well as CD-ROM copies.
GCC development has split in two branches recently. See more about the experimental version, egcs, at http://www.cygnus.com/egcs/
Sources adapted to your favorite OS, and binaries precompiled for it, should be found at your usual FTP sites.
For most popular DOS port of GCC is named DJGPP, and can be found in directories of such name in FTP sites. See:
There is also a port of GCC to OS/2 named EMX, that also works under DOS, and includes lots of unix-emulation library routines. See around:
The documentation of GCC includes documentation files in texinfo format. You can compile them with tex and print then result, or convert them to .info, and browse them with emacs, or convert them to .html, or nearly whatever you like. convert (with the right tools) to whatever you like, or just read as is. The .info files are generally found on any good installation for GCC.
The right section to look for is:
C Extensions::Extended Asm::
Invoking GCC::Submodel Options::i386 Options::
might help too.
Particularly, it gives the i386 specific constraint names for registers:
abcdSDB correspond to
respectively (no letter for
The DJGPP Games resource (not only for game hackers) has this page specifically about assembly:
Finally, there is a web page called, ``DJGPP Quick ASM Programming Guide'', that covers URLs to FAQs, AT&T x86 ASM Syntax, Some inline ASM information, and converting .obj/.lib files:
GCC depends on GAS for assembling, and follow its syntax (see below); do mind that inline asm needs percent characters to be quoted so they be passed to GAS. See the section about GAS below.
Find lots of useful examples in the
subdirectory of the sources for the Linux kernel.
Be sure to invoke GCC with the
-O flag (or
to enable optimizations and inline assembly.
If you don't, your code may compile, but not run properly!!!
Actually (kudos to Tim Potter, email@example.com),
it is enough to use the
-fasm flag (and perhaps
which is part of all the features enabled by
So if you have problems with buggy optimizations in your
particular implementation/version of GCC, you can still use inline asm.
Similarly, use -fno-asm to disable inline assembly (why would you?).
More generally, good compile flags for GCC on the x86 platform are
gcc -O2 -fomit-frame-pointer -m386 -Wall
-O2 is the good optimization level. Optimizing besides it yields
code that is a lot larger, but only a bit faster;
such overoptimizationn might be useful for tight loops only (if any),
which you may be doing in assembly anyway;
if you need that, do it just for the few routines that need it.
-fomit-frame-pointer allows generated code to skip the stupid
frame pointer maintenance, which makes code smaller and faster,
and frees a register for further optimizations.
It precludes the easy use of debugging tools (
but when you use these,
you just don't care about size and speed anymore anyway.
-m386 yields more compact code, without any measurable slowdown,
(note that small code also means less disk I/O and faster execution)
but perhaps on the above-mentioned tight loops;
you might appreciate -mpentium for special pentium-optimizing GCC
targetting a specifically pentium platform.
-Wall enables all warnings and helps you catch obvious stupid errors.
To optimize even more, option
and/or corresponding function attribute might help,
but might pose lots of problems when linking to foreign code...
Note that you can add make these flags the default by editing file
or wherever that is on your system (better not add -Wall there, though).
GAS is the GNU Assembler, that GCC relies upon.
Find it at the same place where you found GCC, in a package named binutils.
Because GAS was invented to support a 32-bit unix compiler, it uses standard ``AT&T'' syntax, which resembles a lot the syntax for standard m68k assemblers, and is standard in the UNIX world. This syntax is no worse, no better than the ``Intel'' syntax. It's just different. When you get used to it, you find it much more regular than the Intel syntax, though a bit boring.
Here are the major caveats about GAS syntax:
%, so that registers are
%dland suches instead of just
dl, etc. This makes it possible to include external C symbols directly in assembly source, without any risk of confusion, or any need for ugly underscore prefixes.
mov ax,dx(move contents of register
ax) will be in att syntax
mov %dx, %ax.
bfor (8-bit) byte,
wfor (16-bit) word, and
lfor (32-bit) long. For instance, the correct syntax for the above instruction would have been
movw %dx,%ax. However, gas does not require strict att syntax was, so the suffix is optional when length can be guessed from register operands, and else defaults to 32-bit (with a warning).
$prefix, as in
addl $5,%eax(add immediate long value 5 to register
movl $foo,%eaxputs the address of variable
movl foo,%eaxputs the
testb $0x80,17(%ebp)(test the high bit of the byte value at offset 17 from the cell pointed to by
A program exists to help you convert programs from TASM syntax to AT&T syntax. See
GAS has comprehensive documentation in TeXinfo format,
which comes at least with the source distribution.
Browse extracted .info pages with Emacs or whatever.
There used to be a file named gas.doc or as.doc
around the GAS source package, but it was merged into the TeXinfo docs.
Of course, in case of doubt, the ultimate documentation
is the sources themselves!
A section that will particularly interest you is
Again, the sources for Linux (the OS kernel), come in as good examples;
see under linux/arch/i386, the following files:
kernel/*.S, boot/compressed/*.S, mathemu/*.S
If you are writing kind of a language, a thread package, etc you might as well see how other languages (OCaml, gforth, etc), or thread packages (QuickThreads, MIT pthreads, LinuxThreads, etc), or whatever, do it.
Finally, just compiling a C program to assembly might show you the syntax for the kind of instructions you want. See section Do you need Assembly? above.
GAS is a 32-bit assembler, meant to support a 32-bit compiler.
It currently has only limited support for 16-bit mode,
which consists in prepending the 32-bit prefixes to instructions,
so you write 32-bit code that runs in 16-bit mode on a 32 bit CPU.
In both modes, it supports 16-bit register usage,
but what is unsupported is 16-bit addressing.
Use the directive
.code32 to switch between modes.
Note that an inline assembly statement
will allow GCC to produce 32-bit code that'll run in real mode!
I've been told that most code needed to fully support 16-bit mode programming was added to GAS by Bryan Ford (please confirm?), but at least, it doesn't show up in any of the distribution I tried, up to binutils-2.8.1.x ... more info on this subject would be welcome.
A cheap solution is to define macros (see below) that somehow produce
the binary encoding (with
.byte) for just the 16-bit mode instructions
you need (almost nothing if you use code16 as above,
and can safely assume the code will run on a 32-bit capable x86 CPU).
To find the proper encoding, you can get inspiration from
the sources of 16-bit capable assemblers for the encoding.
GASP is the GAS Preprocessor. It adds macros and some nice syntax to GAS.
GASP comes together with GAS in the GNU binutils archive.
It works as a filter, much like cpp and the like. I have no idea on details, but it comes with its own texinfo documentation, so just browse them (in .info), print them, grok them. GAS with GASP looks like a regular macro-assembler to me.
The Netwide Assembler project is producing yet another assembler, written in C, that should be modular enough to eventually support all known syntaxes and object formats.
Binary release on your usual sunsite mirror in
Should also be available as .rpm or .deb in your usual RedHat/Debian
At the time this HOWTO is written, the current NASM version is 0.96.
The syntax is Intel-style. Some macroprocessing support is integrated.
Supported object file formats are
win32, (their own format)
NASM can be used as a backend for the free LCC compiler (support files included).
Surely NASM evolves too fast for this HOWTO to be kept up to date. Unless you're using BCC as a 16-bit compiler (which is out of scope of this 32-bit HOWTO), you should use NASM instead of say AS86 or MASM, because it is actively supported online, and runs on all platforms.
Note: NASM also comes with a disassembler, NDISASM.
Its hand-written parser makes it much faster than GAS, though of course, it doesn't support three bazillion different architectures. For the x86 target, it should be the assembler of choice...
AS86 is a 80x86 assembler, both 16-bit and 32-bit, part of Bruce Evans' C Compiler (BCC). It has mostly Intel-syntax, though it differs slightly as for addressing modes.
A completely outdated version of AS86 is distributed by HJLu just to compile the Linux kernel, in a package named bin86 (current version 0.4), available in any Linux GCC repository. But I advise no one to use it for anything else but compiling Linux. This version supports only a hacked minix object file format, which is not supported by the GNU binutils or anything, and it has a few bugs in 32-bit mode, so you really should better keep it only for compiling Linux.
The most recent versions by Bruce Evans (firstname.lastname@example.org) are published together with the FreeBSD distribution. Well, they were: I could not find the sources from distribution 2.1 on :( Hence, I put the sources at my place:
The Linux/8086 (aka ELKS) project is somehow maintaining bcc (though I don't think they included the 32-bit patches). See around http://www.linux.org.uk/Linux8086.html ftp://linux.mit.edu/.
Among other things, these more recent versions, unlike HJLu's, supports Linux GNU a.out format, so you can link you code to Linux programs, and/or use the usual tools from the GNU binutil package to manipulate your data. This version can co-exist without any harm with the previous one (see according question below).
BCC from 12 march 1995 and earlier version has a misfeature
that makes all segment pushing/popping 16-bit, which is quite
annoying when programming in 32-bit mode.
A patch is published in the Tunes project
in unpacked subdirectory
The patch should also be in available directly from
Bruce Evans accepted this patch, so if there is a more recent version of
bcc somewhere someday, the patch should have been included...
Here's the GNU Makefile entry for using bcc
into both GNU a.out
%.o %.l: %.s bcc -3 -G -c -A-d -A-l -A$*.l -o $*.o $<
if you don't want any listing.
If you want something else than GNU a.out,
you can see the docs of bcc about the other supported formats,
and/or use the objcopy utility from the GNU binutils package.
The docs are what is included in the bcc package. Man pages are also available somewhere on the FreeBSD site. When in doubt, the sources themselves are often a good docs: it's not very well commented, but the programming style is straightforward. You might try to see how as86 is used in Tunes 0.0.0.25...
Linus is buried alive in mail, and my patch for compiling Linux with a Linux a.out as86 didn't make it to him (!). Now, this shouldn't matter: just keep your as86 from the bin86 package in /usr/bin, and let bcc install the good as86 as /usr/local/libexec/i386/bcc/as where it should be. You never need explicitly call this ``good'' as86, because bcc does everything right, including conversion to Linux a.out, when invoked with the right options; so assemble files exclusively with bcc as a frontend, not directly with as86.
These are other, non-regular, options, in case the previous didn't satisfy you (why?), that I don't recommend in the usual (?) case, but that could prove quite useful if the assembler must be integrated in the software you're designing (i.e. an OS or development environment).
Win32Forth is a free 32-bit ANS FORTH system that successfully runs under Win32s, Win95, Win/NT. It includes a free 32-bit assembler (either prefix or postfix syntax) integrated into the FORTH language. Macro processing is done with the full power of the reflective language FORTH; however, the only supported input and output contexts is Win32For itself (no dumping of .obj file -- you could add that yourself, of course). Find it at ftp://ftp.forth.org/pub/Forth/win32for/
Terse is a programming tool that provides THE most compact assembler syntax for the x86 family! See http://www.terse.com. It is said that there was a free clone somewhere, that was abandonned after worthless pretenses that the syntax would be owned by the original author, and that I invite you to take over, in case the syntax interests you.
You may find more about them, together with the basics of x86 assembly programming, in Raymond Moon's FAQ for comp.lang.asm.x86 http://www2.dgsys.com/~raymoon/faq/asmfaq.zip
Note that all DOS-based assemblers should work inside the Linux DOS Emulator, as well as other similar emulators, so that if you already own one, you can still use it inside a real OS. Recent DOS-based assemblers also support COFF and/or other object file formats that are supported by the GNU BFD library, so that you can use them together with your free 32-bit tools, perhaps using GNU objcopy (part of the binutils) as a conversion filter.