revert between 56095 -> 55830 in arch
[AROS.git] / rom / exec / stackswap.c
blobbb2c7cd56f7c1d94139f8f16f129d87bb7bb9712
1 /*
2 Copyright © 1995-2012, The AROS Development Team. All rights reserved.
3 $Id$
5 Desc: StackSwap() - Swap the stack of a task.
6 Lang: english
7 */
9 /*****************************************************************************
11 NAME */
12 #include <exec/tasks.h>
13 #include <proto/exec.h>
15 AROS_LH1(void, StackSwap,
17 /* SYNOPSIS */
18 AROS_LHA(struct StackSwapStruct *, sss, A0),
20 /* LOCATION */
21 struct ExecBase *, SysBase, 122, Exec)
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().
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.).
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.
39 RESULT
40 The program will be running on a new stack and sss will contain
41 the old stack.
43 Calling StackSwap() twice consecutively will effectively do
44 nothing.
46 NOTES
47 Returning from the function that you call StackSwap() in can have
48 unexpected results.
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__
59 EXAMPLE
61 BUGS
63 SEE ALSO
64 AddTask(), RemTask(), NewStackSwap()
66 INTERNALS
67 This function MUST be replaced in $(KERNEL) or $(ARCH).
69 ******************************************************************************/
71 /* For an example see the StackSwap() function in either i386 or
72 m68k-native.
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.
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.
83 #ifndef __CXREF__
84 #error The function StackSwap() has not been implemented in the kernel.
85 #endif
87 } /* StackSwap() */