====== Writing assembly ======

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

===== Creating an assembly file =====

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

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

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

  - Include the Wonderful toolchain's basic definitions. This provides some useful assembly defines and macros.
  - 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.
  - 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.
  - Tell the assembler to emit 80186 code; this unlocks some additional 80186-exclusive opcodes supported on the NEC V30MZ.
  - 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:

<code C>
        .global strlen
strlen:
</code>

===== Useful macros =====

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

==== Portable calling convention ====

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''.