1 //----------------------------------------------------------------------
2 // Copyright (C) 2006 - 2007 by the FRESCOR consortium:
4 // Universidad de Cantabria, SPAIN
5 // University of York, UK
6 // Scuola Superiore Sant'Anna, ITALY
7 // Kaiserslautern University, GERMANY
8 // Univ. Politecnica Valencia, SPAIN
9 // Czech Technical University in Prague, CZECH REPUBLIC
11 // Thales Communication S.A. FRANCE
12 // Visual Tools S.A. SPAIN
13 // Rapita Systems Ltd UK
16 // See http://www.frescor.org
18 // The FRESCOR project (FP6/2005/IST/5-034026) is funded
19 // in part by the European Union Sixth Framework Programme
20 // The European Union is not liable of any use that may be
24 // based on previous work (FSF) done in the FIRST project
26 // Copyright (C) 2005 Mälardalen University, SWEDEN
27 // Scuola Superiore S.Anna, ITALY
28 // Universidad de Cantabria, SPAIN
29 // University of York, UK
31 // This file is part of FOSA (Frsh Operating System Abstraction)
33 // FOSA is free software; you can redistribute it and/or modify it
34 // under terms of the GNU General Public License as published by the
35 // Free Software Foundation; either version 2, or (at your option) any
36 // later version. FOSA is distributed in the hope that it will be
37 // useful, but WITHOUT ANY WARRANTY; without even the implied warranty
38 // of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
39 // General Public License for more details. You should have received a
40 // copy of the GNU General Public License along with FOSA; see file
41 // COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
42 // Cambridge, MA 02139, USA.
44 // As a special exception, including FOSA header files in a file,
45 // instantiating FOSA generics or templates, or linking other files
46 // with FOSA objects to produce an executable application, does not
47 // by itself cause the resulting executable application to be covered
48 // by the GNU General Public License. This exception does not
49 // however invalidate any other reasons why the executable file might be
50 // covered by the GNU Public License.
51 // -----------------------------------------------------------------------
53 //==============================================
54 // ******** ****** ******** **********
55 // **///// /** ** **////// /** /**
56 // ** /** ** /** /** /**
57 // ******* /** ** /********* /**********
58 // **//// /** ** ////////** /**//////**
59 // ** /** ** /** /** /**
60 // ** /** ** ******** /** /**
61 // // /******/ //////// // //
63 // FOSA(Frescor Operating System Adaptation layer)
64 //================================================
67 #ifndef FOSA_LONG_JUMP
68 #define FOSA_LONG_JUMP
70 #include "fosa_types.h"
71 #include "fosa_opaque_types.h"
74 * @defgroup longjumps Long Jumps
77 * This module defines the types and functions that allow te
78 * application to abort a piece of running code; it can be used to
79 * stop an action that is overrunning its budget and needs to be
80 * aborted, without aborting the whole thread on which it is based.
82 * The model is that the application installs a long-jump handler for
83 * each thread that potentially needs to be aborted through the long
84 * jump mechanism. As a result of installing the handler it gets back
85 * a signal identifier. This signal is later used to notify the
86 * handler that the thread needs to be aborted. Previous to sending
87 * the signal, the application must store the context of the thread so
88 * that when it is aborted the saved context can be recovered. The
89 * signal may be sent to the handler from any thread, but must contain
90 * as attached information a pointer to the variable where the context
93 * The implementation may internally choose to implement a single long
94 * jump handler for all threads (and use a single signal), or one for each
95 * thread (requiring the reservation of a pool of signals).
102 /*************************
104 *************************/
107 * fosa_long_jump_save_context
109 * Save the context of the current thread for a future long jump
111 * This function stores in context the information required to modify
112 * the stack of the calling thread so that a later long jump may be
113 * executed in the future to restore this context
115 * This function stores in 'context' the thread id, the registers,
116 * and the stack frame of the calling thread. This information can be
117 * used by the long jump handler to change the stack of the task so
118 * that when it is scheduled again it returns to the end of this
122 * Returns 0 if successful; otherwise it returns an error code:
123 * FOSA_EINVAL: the value of context is invalid
125 * Alternatively, in case of error the implementation is allowed to
126 * notify it to the system console and then terminate the FRSH
127 * implementation and dependant applications
129 int fosa_long_jump_save_context
130 (fosa_long_jump_context_t * context);
134 * fosa_long_jump_was_performed
136 * Check whether the current thread suffered a long jump or not
138 * This function should be invoked after fosa_long_jump_save_context
139 * to determine whether the current thread is executing normally, or
140 * has suffered a long jump to the point where the context was
141 * saved. If invoked after a direct invocation to
142 * fosa_long_jump_save_context, the function shall set the variable
143 * pointed to by jumped to zero. If invoked after returning from
144 * fosa_long_jump_save_context due to a long jump caused by the long
145 * jump handler, the function shall set this variable to 1.
147 * Returns 0 if successful; otherwise it returns an error code:
148 * FOSA_EINVAL: the value of context is invalid
150 * Alternatively, in case of error the implementation is allowed to
151 * notify it to the system console and then terminate the FRSH
152 * implementation and dependant applications
154 int fosa_long_jump_was_performed
155 (const fosa_long_jump_context_t * context, int * jumped);
159 * fosa_long_jump_install_handler
161 * Install a long jump handler for the calling thread
163 * This function shall install a handler that is capable of causing a
164 * long jump operation that restores the context of a thread to a
165 * previously saved value. If the handler has already been installed
166 * for this thread the previously installed handler will be used and
167 * the call shall succeed.
169 * The long-jump handler is waiting for a signal to notify that a
170 * thread context should be restored. This signal must carry attached
171 * to it a pointer to the variable where the thread context was
172 * saved. The thread referenced in that context will have its
173 * internal context restored to the point where it was saved. For
174 * this restore operation to work properly, the program frame where
175 * the thread saved its context must still be valid.
177 * Depending on the implementation a given thread may also install a signal
178 * handler or a signal handler thread that is capable of executing
179 * the actions required to restore the context of a thread from the
180 * appropriate context. For instance, in POSIX it is necesaray that
181 * the context is restored from the same thread being restored,
182 * usually from a signal handler of that thread.
184 * The function shall store in the variable pointed to by signal the
185 * identifier of the signal that must be used to notify the request
186 * for a long jump to be executed. In the variable pointed to by
187 * handler, it shall store the thread id to which the signal must be
188 * sent. The signal must be sent with its attached information set to
189 * a pointer to the variable of type fosa_long_jump_context_t where
190 * the context of the thread to be restored was saved.
192 * Returns 0 if successful; otherwise it returns an error code:
193 * FOSA_EINVAL: the value of context is invalid
194 * FOSA_ENOMEM: there are no resources to satisfy the call at this time
196 * Alternatively, in case of error the implementation is allowed to
197 * notify it to the system console and then terminate the FRSH
198 * implementation and dependant applications
200 int fosa_long_jump_install_handler
201 (fosa_signal_t *signal, fosa_thread_id_t *handler);
208 #endif /* !FOSA_LONG_JUMP */