Writing assembly

In the Wonderful toolchain, assembly files use the .s extension. They are compiled using the GNU assembler and the C preprocessor.

It is recommended to start with a preamble similar to the following:

#include <wonderful.h> // (1)!
#include <ws.h> // (2)!

    .code16 // (3)!
    .arch i186 // (4)!
    .intel_syntax noprefix // (5)!

1. Include the Wonderful toolchain's basic definitions. This provides some useful assembly defines and macros.
2. Include the libws library's definitions. This header file supports being included in an assembler context, and provides hardware-related defines - such as I/O port names and masks.
3. Tell the assembler to emit 16-bit code; this is useful as the GNU assembler supports all kinds of x86 code, including 32-bit and 64-bit.
4. Tell the assembler to emit 80186 code; this unlocks some additional 80186-exclusive opcodes supported on the NEC V30MZ.
5. Tell the assembler to emit Intel-syntax assembly; this is entirely optional, but the examples for external assembly files in this guide all make use of the Intel syntax, as opposed to the default AT&T syntax used in inline assembly.

Note that to export a symbol (make it visible outside of the specific file, or translation unit), you need to use .global, like so:

.global strlen
strlen:

Including wonderful.h provides some useful macros from ia16.h.

The small and medium targets use different calling conventions (near vs. far functions by default). The following macros abstract these differences away:

• IA16_CALL - use this macro in place of the call instruction to call C-callable functions.
• IA16_CALL_LOCAL - use this macro in place of the call instruction when calling another function in the same section.
• IA16_JMP - use this macro in place of the jmp instruction to jump to C-callable functions.
• IA16_RET - use this macro in place of the ret instruction to return from a C-callable function.
• IA16_CALL_STACK_OFFSET(x) - for portability between code models, you can use this macro to get a stack offset with the function return address accounted for. For example, in a near code model, IA16_CALL_STACK_OFFSET(10) returns 12, but in a far code model, it returns 14.