Miles Sound System SDK 7.2a

AIL_switch_stack

The function AIL_switch_stack allows a C or C++ module to change to a different stack whose size and location may be chosen by the programmer.

void AIL_switch_stack(
  void *stack,
  U32 size,
  U32 * SS,
  void * * ESP,
  void * * EBP
);

In Parameters

size: specifies the size in bytes of the new stack.
SS: points to a variable of type U32 which will be used later by AIL_restore_stack to return to the default application stack.
ESP: points to a variable of type void * which will be used later by AIL_restore_stack to return to the default application stack.
EBP: points to a variable of type void * which will be used later by AIL_restore_stack to return to the default application stack.

Out Parameters

stack: points to a statically declared or globally allocated area of memory suitable for use as a stack. This area must reside within the application's normal data segment, and should be a multiple of 4 bytes in size.

Discussion

This is a DOS-only function.

Auto variables may be used from within a function that calls AIL_switch_stack, but their values are not copied from the default stack to the new stack by this function. Note that some or all of a function's formal arguments are actually considered auto variables, implying that argument values should be copied to static variables before calling AIL_switch_stack. Compiler register optimizations may mask problems resulting from failure to preserve function arguments and/or auto variable contents; however, seemingly unrelated failures may occur when minor changes are made to the code at a later date.

Any Watcom C/C++ modules which contain calls to AIL_switch_stack must be compiled with the -of+ option, to force generation of traceable stack frames. Otherwise, EBP may be assigned for use as a register variable prior to the AIL_switch_stack call, resulting in improper stack frame creation.

Prior to exiting, a function which has called AIL_switch_stack must return to the normal stack by means of a call to AIL_restore_stack.

This function is used internally by the MSS system. Most applications will not need to use AIL_switch_stack, unless large interrupt handlers with extensive stack usage are implemented in C, and/or preemptive multi-threaded timer services are enabled. (By default, preemptive timer services are disabled, and the internal timer dispatcher switches to its own 2kb stack before calling any timer callback functions.) Misuse of AIL_switch_stack can cause obscure, difficult-to-trace bugs; it is not recommended that this function be used by programmers unfamiliar with C's stack frame architecture.

Group: Low-Level DOS Support Services
Related Sections: Callbacks under DOS
Related Functions: AIL_restore_stack, AIL_switch_stack
Related Basic Types: U32, void