Calling conventions and interrupt handlers¶
__pascal (also _pascal) is the 16-bit Windows API convention:
arguments are pushed left to right, the called function removes them
(RET n), and the symbol is the upper-case name with no underscore, so
int __far __pascal MessageBox(...) matches the Windows import. A
struct return still passes its hidden pointer first. Variadic __pascal
functions use the C rules. __export (also _export) marks a function or
variable for export; it is written as an export record for a Windows
linker, and accepted and ignored in DOS programs, which have no exports.
-mwindows-prologue=exported gives __far __export functions the 16-bit
Windows entry sequence, as Open Watcom -zW does (=all gives it to every
far function, as -zw; =none is the default). The function starts with
push ds; pop ax; nop, which the Windows loader patches so that DS is
loaded from AX (the program's data segment, set by a MakeProcInstance
thunk) or from DGROUP in a DLL, marks its frame as far with inc bp, and
restores the caller's DS on return. Near functions are left alone, since
Windows cannot call them.
__loadds (also _loadds) makes a function load DGROUP into DS on entry
and restore the caller's DS on return, so it can be called with any DS:
from an interrupt handler or a resident program, for example. Combined with
the Windows sequence, the first bytes are mov ax, DGROUP, as a DLL's
loader would patch them.
__interrupt (also _interrupt) makes an interrupt handler, as in Open
Watcom and Microsoft C: void __interrupt __far on_timer(void). The
function is far (with or without __far), saves every register, loads
DGROUP into DS (CS in tiny), clears the direction flag and returns with
IRET. Its parameter, if it has one, is union INTPACK from <i86.h>,
the saved registers in Open Watcom's layout, and what the handler stores
there is what the interrupted program gets back:
void __interrupt __far on_dos(union INTPACK r) { r.w.ax = 0; }.
Microsoft C's register parameters (unsigned es, unsigned ds, unsigned di,
unsigned si, unsigned bp, unsigned sp, unsigned bx, unsigned dx,
unsigned cx, unsigned ax, unsigned ip, unsigned cs, unsigned flags, or the
first few of them) can be read too. Calling a pointer to an interrupt
function, such as the handler a vector held before, pushes the flags and
makes a far call, as the interrupt would. <dos.h> has _dos_getvect,
_dos_setvect, _chain_intr (go on to another handler with the
registers as saved, changes included) and _dos_keep (stay resident); see
libos/msdos/README.md in picolibc.
A handler runs on the stack of the program it interrupted, so SS is not
DGROUP. Locals work, but in the tiny, small and medium models a near
pointer means DS: don't pass the address of a local, or of the
INTPACK, to other functions; use static variables. A resident program
keeps its memory with _dos_keep(status, 0), which keeps the code, data
and heap and gives back the stack of a .COM.
In DOS programs these are for writing and calling Win16-style code; the
i8086-pc-win16 target below makes Windows programs and DLLs.