rom/exec/stackswap.c

   1 /*
   2     Copyright © 1995-2001, 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 consequtively 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     EXAMPLE
  51
  52     BUGS
  53
  54     SEE ALSO
  55         AddTask(), RemTask()
  56
  57     INTERNALS
  58         This function MUST be replaced in $(KERNEL) or $(ARCH).
  59
  60 ******************************************************************************/
  61 {
  62     /* For an example see the StackSwap() function in either i386 or
  63        m68k-native.
  64
  65        Note that you must save any state information on the stack that is
  66        used in the current process, for example you should really save
  67        return addresses.
  68
  69        Note that even if you do save that information, it is not a good
  70        idea to return from the procedure that StackSwap() was invoked in
  71        as the stack will be quite incorrect.
  72     */
  73
  74 #ifndef __CXREF__
  75 #error The function StackSwap() has not been implemented in the kernel.
  76 #endif
  77
  78 } /* StackSwap() */