rom/exec/stackswap.c

   1 /*
   2     Copyright © 1995-2012, The AROS Development Team. All rights reserved.
   3     $Id$
   4
   5     Desc: StackSwap() - Swap the stack of a task.
   6     Lang: english
   7 */
   8
   9 /*****************************************************************************
  10
  11     NAME */
  12 #include <exec/tasks.h>
  13 #include <proto/exec.h>
  14
  15         AROS_LH1(void, StackSwap,
  16
  17 /*  SYNOPSIS */
  18         AROS_LHA(struct StackSwapStruct *,  sss, A0),
  19
  20 /*  LOCATION */
  21         struct ExecBase *, SysBase, 122, Exec)
  22
  23 /*  FUNCTION
  24         Changes the stack used by a task. The StackSwapStruct will contain
  25         the value of the old stack such that the stack can be reset to the
  26         previous version by another call to StackSwap().
  27
  28         When the stack is swapped, the data on the stack(s) will not be
  29         altered, so the stack may not be set up for you. It is generally
  30         required that you replace your stack before exiting from the
  31         current stack frame (procedure, function call etc.).
  32
  33     INPUTS
  34         sss     -   A structure containing the values for the upper, lower
  35                     and current bounds of the stack you wish to use. The
  36                     values will be replaced by the current values and you
  37                     can restore the values later.
  38
  39     RESULT
  40         The program will be running on a new stack and sss will contain
  41         the old stack.
  42
  43         Calling StackSwap() twice consecutively will effectively do
  44         nothing.
  45
  46     NOTES
  47         Returning from the function that you call StackSwap() in can have
  48         unexpected results.
  49
  50         Use of StackSwap() is deprecated on AROS; NewStackSwap() should
  51         be used instead. StackSwap() is only retained to provide backwards
  52         compatibility. On some hosted versions with strict stack checking use
  53         of StackSwap() may cause problems.
  54         By default StackSwap() will not be defined and you have to
  55         #define __AROS_GIMME_DEPRECATED_STACKSWAP__ before including
  56         <proto/exec.h>. As said above it is highly advised to change code
  57         to use NewStackSwap() and not define __AROS_GIMME_DEPRECATED_STACKSWAP__
  58
  59     EXAMPLE
  60
  61     BUGS
  62
  63     SEE ALSO
  64         AddTask(), RemTask(), NewStackSwap()
  65
  66     INTERNALS
  67         This function MUST be replaced in $(KERNEL) or $(ARCH).
  68
  69 ******************************************************************************/
  70 {
  71     /* For an example see the StackSwap() function in either i386 or
  72        m68k-native.
  73
  74        Note that you must save any state information on the stack that is
  75        used in the current process, for example you should really save
  76        return addresses.
  77
  78        Note that even if you do save that information, it is not a good
  79        idea to return from the procedure that StackSwap() was invoked in
  80        as the stack will be quite incorrect.
  81     */
  82
  83 #ifndef __CXREF__
  84 #error The function StackSwap() has not been implemented in the kernel.
  85 #endif
  86
  87 } /* StackSwap() */