1 // -----------------------------------------------------------------------
2 // Copyright (C) 2006 - 2008 FRESCOR consortium partners:
4 // Universidad de Cantabria, SPAIN
5 // University of York, UK
6 // Scuola Superiore Sant'Anna, ITALY
7 // Kaiserslautern University, GERMANY
8 // Univ. Politécnica 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 for a link to partners' websites
18 // 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 // FSF API web pages: http://marte.unican.es/fsf/docs
32 // http://shark.sssup.it/contrib/first/docs/
34 // This file is part of FOSA (Frsh Operating System Adaption)
36 // FOSA is free software; you can redistribute it and/or modify it
37 // under terms of the GNU General Public License as published by the
38 // Free Software Foundation; either version 2, or (at your option) any
39 // later version. FOSA is distributed in the hope that it will be
40 // useful, but WITHOUT ANY WARRANTY; without even the implied warranty
41 // of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
42 // General Public License for more details. You should have received a
43 // copy of the GNU General Public License along with FOSA; see file
44 // COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
45 // Cambridge, MA 02139, USA.
47 // As a special exception, including FOSA header files in a file,
48 // instantiating FOSA generics or templates, or linking other files
49 // with FOSA objects to produce an executable application, does not
50 // by itself cause the resulting executable application to be covered
51 // by the GNU General Public License. This exception does not
52 // however invalidate any other reasons why the executable file might be
53 // covered by the GNU Public License.
54 // -----------------------------------------------------------------------
56 //==============================================
57 // ******** ****** ******** **********
58 // **///// /** ** **////// /** /**
59 // ** /** ** /** /** /**
60 // ******* /** ** /********* /**********
61 // **//// /** ** ////////** /**//////**
62 // ** /** ** /** /** /**
63 // ** /** ** ******** /** /**
64 // // /******/ //////// // //
66 // FOSA(Frescor Operating System Adaptation layer)
67 //================================================
70 #ifndef FOSA_LONG_JUMP
71 #define FOSA_LONG_JUMP
73 #include "fosa_types.h"
74 #include "fosa_opaque_types.h"
79 * @defgroup longjumps Long Jumps
82 * This module defines the types and functions that allow te
83 * application to abort a piece of running code; it can be used to
84 * stop an action that is overrunning its budget and needs to be
85 * aborted, without aborting the whole thread on which it is based.
87 * The model is that the application installs a long-jump handler for
88 * each thread that potentially needs to be aborted through the long
89 * jump mechanism. As a result of installing the handler it gets back
90 * a signal identifier. This signal is later used to notify the
91 * handler that the thread needs to be aborted. Previous to sending
92 * the signal, the application must store the context of the thread so
93 * that when it is aborted the saved context can be recovered. The
94 * signal may be sent to the handler from any thread, but must contain
95 * as attached information a pointer to the variable where the context
98 * The implementation may internally choose to implement a single long
99 * jump handler for all threads (and use a single signal), or one for each
100 * thread (requiring the reservation of a pool of signals).
107 /*************************
109 *************************/
112 * fosa_long_jump_save_context
114 * Save the context of the current thread for a future long jump
116 * This function stores in context the information required to modify
117 * the stack of the calling thread so that a later long jump may be
118 * executed in the future to restore this context
120 * This function stores in 'context' the thread id, the registers,
121 * and the stack frame of the calling thread. This information can be
122 * used by the long jump handler to change the stack of the task so
123 * that when it is scheduled again it returns to the end of this
127 * Returns 0 if successful; otherwise it returns an error code:
128 * FOSA_EINVAL: the value of context is invalid
130 * Alternatively, in case of error the implementation is allowed to
131 * notify it to the system console and then terminate the FRSH
132 * implementation and dependant applications
134 int fosa_long_jump_save_context
135 (fosa_long_jump_context_t * context);
139 * fosa_long_jump_was_performed
141 * Check whether the current thread suffered a long jump or not
143 * This function should be invoked after fosa_long_jump_save_context
144 * to determine whether the current thread is executing normally, or
145 * has suffered a long jump to the point where the context was
146 * saved. If invoked after a direct invocation to
147 * fosa_long_jump_save_context, the function shall set the variable
148 * pointed to by jumped to zero. If invoked after returning from
149 * fosa_long_jump_save_context due to a long jump caused by the long
150 * jump handler, the function shall set this variable to 1.
152 * Returns 0 if successful; otherwise it returns an error code:
153 * FOSA_EINVAL: the value of context is invalid
155 * Alternatively, in case of error the implementation is allowed to
156 * notify it to the system console and then terminate the FRSH
157 * implementation and dependant applications
159 int fosa_long_jump_was_performed
160 (const fosa_long_jump_context_t * context, int * jumped);
164 * fosa_long_jump_install_handler
166 * Install a long jump handler for the calling thread
168 * This function shall install a handler that is capable of causing a
169 * long jump operation that restores the context of a thread to a
170 * previously saved value. If the handler has already been installed
171 * for this thread the previously installed handler will be used and
172 * the call shall succeed.
174 * The long-jump handler is waiting for a signal to notify that a
175 * thread context should be restored. This signal must carry attached
176 * to it a pointer to the variable where the thread context was
177 * saved. The thread referenced in that context will have its
178 * internal context restored to the point where it was saved. For
179 * this restore operation to work properly, the program frame where
180 * the thread saved its context must still be valid.
182 * Depending on the implementation a given thread may also install a signal
183 * handler or a signal handler thread that is capable of executing
184 * the actions required to restore the context of a thread from the
185 * appropriate context. For instance, in POSIX it is necesaray that
186 * the context is restored from the same thread being restored,
187 * usually from a signal handler of that thread.
189 * The function shall store in the variable pointed to by signal the
190 * identifier of the signal that must be used to notify the request
191 * for a long jump to be executed. In the variable pointed to by
192 * handler, it shall store the thread id to which the signal must be
193 * sent. The signal must be sent with its attached information set to
194 * a pointer to the variable of type fosa_long_jump_context_t where
195 * the context of the thread to be restored was saved.
197 * Returns 0 if successful; otherwise it returns an error code:
198 * FOSA_EINVAL: the value of context is invalid
199 * FOSA_ENOMEM: there are no resources to satisfy the call at this time
201 * Alternatively, in case of error the implementation is allowed to
202 * notify it to the system console and then terminate the FRSH
203 * implementation and dependant applications
205 int fosa_long_jump_install_handler
206 (fosa_signal_t *signal, fosa_thread_id_t *handler);
215 #endif /* !FOSA_LONG_JUMP */