Skip to content

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.