Differences

This shows you the differences between two versions of the page.

--- wswan:guide:c_assembly [2025/08/15 14:43] – [Useful macros] asie
+++ wswan:guide:c_assembly [2025/12/31 12:59] (current) – asie
@@ Line 17: / Line 17: @@
   - Include the Wonderful toolchain's basic definitions. This provides some useful assembly defines and macros.
-  - Include the libws library's definitions. This library supports being included in an assembler, and provides hardware-related defines - such as I/O port names and masks.
+  - 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.
@@ Line 31: / Line 31: @@
 ===== Useful macros =====
-''wonderful.h'' (via ''ia16.h'') provides some useful macros:
+Including ''wonderful.h'' provides some useful macros from ''ia16.h''.
-  * **IA16_CALL** - for portability between code models, you can use this macro in place of the ''call'' instruction to call C functions.
+==== Portable calling convention ====
-  * **IA16_JMP** - for portability between code models, you can use this macro in place of the ''jmp'' instruction to jump to C functions.
-  * **IA16_RET** - for portability between code models, you can use this macro in place of the ''ret'' isntruction to return from a C-called function.
+The ''small'' and ''medium'' targets use different calling conventions (near vs. far functions by default). The following macros abstract these differences away:
-  * **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 exapmle, in a "near" code model, ''IA16_CALL_STACK_OFFSET(10)'' returns ''12'', but in a "far" code model, it returns ''14''.
+  * **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''.