Procedure attributes

In order to allow programming in a multi-language environment,mixing of memory models, and handling of interrupts within your program, Stony Brookcompilers let you specify attributes that control the code generation for proceduresand procedure calls.

The attributes follow the procedure header and are enclosed insquare brackets as follows:

Modula-2

PROCEDURE name (Formals) [: ReturnType] [attributes];

If you specify any procedure attributes you must include theparentheses that enclose the parameter list, even if there are no parameters. Theattributes are separated by commas. Attributes are not case sensitive.

Ada95

PROCEDURE name (Formals) [return ReturnType]

Pragma ProcAttributes(name, attributes);

The ProcAttributes pragma should be in the source code immediatelyafter the procedure declaration. The attributes are separated by commas.

Procedure Attributes

Attribute Description
Alters(regs) Specifies a list of registers changed by the procedure.
The following registers (regs) can be specified:
AX, BX, CX, DX, SI, DI, FS, GS and ES.

Separate the registers by commas.  By default, the compiler uses registers altered by the "calling convention" presently in use.

IA-32 Note: ES can only be altered in 16-bit compilers, it is not allowed to be altered for 32-bit compilers.

IA-32 Note: Use the 16-bit registers above, even when altering 32-bit registers. For example, when altering EAX, use AX when specifying the alters.
Export Causes the compiler to generate special code for exported procedures.  All exceptions are trapped and an unhandled exception is a termination event. A special procedure prologue is also generated for Win16.
PropagateException For procedures with the export procedure attribute, specifies that the procedure should allow exceptions to be propagated beyond this procedure.
Inline Specifies that the procedure should be expanded in line, instead of being called.  Do not use inline on exported procedures or procedures that will be assigned to a procedure variable or passed as a procedure type parameter.
Interrupt
(16-bit IA-32 Only)
Specifies that the procedure is an interrupt handler.  No other attributes may be specified with interrupt.  The compiler will automatically save and restore all registers.  This procedure may not be called by normal procedure calls.   The interrupt procedure will setup the DATA segment as if the LoadDS attribute had been specified.
Leaves Specifies that the procedure leaves its parameters on the stack when returning.
LoadDS
(16-bit IA-32 Only)
Specifies that the procedure loads the DS register.  This means callers do not have to load it.
Pass(regs)
(IA-32 Only)
Specifies registers in which parameters should be passed. You can use this attribute only for procedures written in another language.

regs is a list of registers separated by commas, which correspond one-to-one with the parameters of the procedure.
If no register is specified for a parameter, it is passed on the stack.
If a parameter requires two registers, specify them in the form:
R1:R2
where R1 is used to pass the high-order word and R2 is used for the low-order word.
Rx can be AX, BX, CX, DX, SI, and DI.  ES can also be used by the 16-bit compiler.  Again, use the 16-bit registers when specifying pass values, the compiler will use the register size required by the parameter (8-bit, 16-bit, or 32-bit).  Two register parameters represent 32-bit arguments for the 16-bit compiler and 64-bit arguments for the 32-bit compiler.

Example: PASS(BX,,DI) This passes the first parameter in BX, the next on the stack and the last in DI.
Removes Specifies that the procedure removes its parameters from the stack before returning.
Returns r1 [:r2 ]
(IA-32 Only)
Specifies the registers that the function procedure uses to return its value.

16-bit compilers:
If the value is a 16-bit value or less, only r1 is specified.  If it is a 32-bit value, both registers must be specified, and r1 is the high order 16-bits of the value.

32-bit compilers:
If the value is a 32-bit value or less, only r1 is specified.  If it is a 64-bit value, both registers must be specified, and r1 is the high order 32-bits of the value.
RightToLeft Specifies that the parameters are pushed on the stack in reverse order; that is, the rightmost parameter is passed/pushed first.
LeftToRight Specifies that the parameters are passed/pushed on the in the order declared.
Variable Specifies that the procedure takes a variable number of parameters.  After the parameters specified in the list, any number of additional parameters can be given in the call.  This attribute can be used only on foreign language procedures.
Frame Forces the procedure to have a full stack frame even if it does not need one.
NeverReturns Signifies that this procedure never returns. This is useful for the uninitialized variable checking capability of the compiler. It gives the compiler more information to use in its analysis of source code.
Pure Signifies that the procedure does not alter global variables.
Invariant This only applies to functions. Signifies that the function will return the same result for the same input parameters. This attribute implies Pure.
StonyBrook The default calling convention of the compiler.

Call Attributes IA32:
[LeftToRight, Alters(AX,CX,DX,FS,GS)] for 32-bit DOS
[LeftToRight, Alters(AX,CX,DX)] for other 32-bit
[LeftToRight, Alters(AX,DX,BX,ES)] for DOS or Win16

Call Attributes SPARC: [RightToLeft]

Public Symbols:
Modula-2 public symbols are created as ModuleName_SymbolName.
For Ada95 public symbols are created as PackageName_SymbolName. Ada95 public symbols are not case sensitive, while Modula-2 symbols are case sensitive.
Cdecl, msCdecl This is the C calling convention used by most C compilers.

Call Attributes IA32:
[RightToLeft, Leaves, Alters(AX,CX,DX,FS,GS)] for 32-bit DOS
[RightToLeft, Leaves, Alters(AX,CX,DX)] for other 32-bit
[RightToLeft, Leaves, Alters(AX,CX,DX,BX,ES)] for DOS or Win16

Call Attributes SPARC: [RightToLeft, Leaves]

Public Symbols:
Public symbols are created as SymbolName.  Public symbols are case sensitive. For msCdecl an underscore character, _,  precedes the name.  
CPascal This is the Pascal calling convention used by C compilers when they use the "Pascal" calling convention.

Call Attributes IA32:
[LeftToRight, Alters(AX,CX,DX,FS,GS)] for 32-bit DOS
[LeftToRight, Alters(AX,CX,DX)] for other 32-bit
[LeftToRight, Alters(AX,CX,DX,BX,ES)] for DOS or Win16

Call Attributes SPARC: [LeftToRight]

Public Symbols:
Public symbols are created as SymbolName.  Public symbols are not case sensitive, names will be in all uppercase.  
OSCall This selects the compiler convention for the currently targeted operating system, provided that operating system has a specific calling convention.  If the targeted operating system does not have a specific calling convention (i.e. DOS), then the default calling convention for the compiler will be chosen.  
OS2System
(32-bit IA-32 Only)
Use this for calling OS/2 2.x (and later) API calls as documented in the IBM C Set/2 compiler manual.

Call Attributes:
[RightToLeft, Leaves, Alters(AX,CX,DX)]

Public Symbols:
Public symbols are created as SymbolName.  Public symbols are case sensitive.  
WatcomS
(32-bit Only)
The Watcom stack calling convention.

Call Attributes:
[RightToleft, Leaves, Alters(AX,CX,DX,FS,GS)] for 32-bit DOS
[RightToLeft, Leaves, Alters(AX,CX,DX)] for other 32-bit.

Public Symbols:
Public symbols are created as SymbolName.  Public symbols are case sensitive.

Note: The Stony Brook compilers return floating point values at the top of the floating point stack.  Watcom assumes they are returned in EAX or EDX:EAX.  You must use a Watcom compiler pragma to have the Watcom compiler return floating point values at the top of the coprocessor stack.  
StdCall
(32-bit IA-32 Only)
This is Microsoft's "new" C calling convention for 32-bit code.

Call Attributes:
[RightToLeft, Alters(AX,CX,DX,FS,GS)] for 32-bit DOS
[RightToLeft, Alters(AX,CX,DX)] for other 32-bit.

Public Symbols:
Public symbols are created as _SymbolName@number.  Where number is the number of parameter bytes in decimal.  Public symbols are case sensitive.  
Win32System
(32-bit IA-32 Only)
This is the calling convention used by the Win32 API calls. This is really the same as the StdCall calling convention. Use this calling convention for calling Win32 API functions
WinSystem
(16-bit IA-32 Only)
Use this calling convention for calling Windows 3.x API calls.

Call Attributes:
[LeftToRight, Alters(AX,CX,DX,BX,ES)]

Public Symbols: Public symbols are created as SymbolName.  Public symbols are not case sensitive.
Linux
(32-bit IA-32 Only)
This is the calling convention used by Linux.

Call Attributes IA32:
[RightToLeft, Leaves, Alters(AX,CX,DX)]

Public Symbols:
Public symbols are created as SymbolName.  Public symbols are case sensitive.
SunOS
(32-bit SPARC Only)
This is the calling convention used by SunOS / Solaris.

Call Attributes SPARC: [RightToLeft, Leaves]

Public Symbols:
Public symbols are created as SymbolName.  Public symbols are case sensitive.

The calling convention procedure attributes set predefined procedurecalling conventions.  Each procedure calling convention designates it's owncall attributes and public symbol naming convention.  All conventions sharethe same function return information.  Function returns are as follows:

Scalar function returns are in AL, AX, EAX, or EDX:EAX dependingupon the data size.
Floating point values are returned on top of the Floating point stack.
Structured value function returns are not supported by our compiler.

For example to call a C procedure using the StdCall calling conventionyou could use one of the following two declarations.

Modula-2

PROCEDURE Cfunction ["_Cfunction@8"](x, y : CARDINAL) [REVERSED,ALTERS(AX,CX,DX)];

Ada95

PROCEDURE Cfunction (x, y : Natural);

Pragma ProcAttributes(Cfunction, REVERSED, ALTERS(AX,CX,DX));

Pragma Public("_Cfunction@8");

Or you can use the predefined StdCall calling convention attribute

Modula-2

PROCEDURE Cfunction(x, y : CARDINAL) [StdCall];

Ada95

PROCEDURE Cfunction(x, y : Natural);

Pragma ProcAttributes(Cfunction, StdCall);