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 FRSH (FRescor ScHeduler)
36 // FRSH 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. FRSH 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 FRSH; 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 FRSH header files in a file,
48 // instantiating FRSH generics or templates, or linking other files
49 // with FRSH 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 // As a special exception, if you include this header file into source
55 // files to be compiled, this header file does not by itself cause
56 // the resulting executable to be covered by the GNU General Public
57 // License. This exception does not however invalidate any other
58 // reasons why the executable file might be covered by the GNU General
60 // -----------------------------------------------------------------------
61 //frsh_implementation_specific.h
62 //==============================================
63 // ******** ******* ******** ** **
64 // **///// /**////** **////// /** /**
65 // ** /** /** /** /** /**
66 // ******* /******* /********* /**********
67 // **//// /**///** ////////** /**//////**
68 // ** /** //** /** /** /**
69 // ** /** //** ******** /** /**
70 // // // // //////// // //
72 // FRSH(FRescor ScHeduler), pronounced "fresh"
73 //==============================================
74 #ifndef _FRSH_IMPLEMENTATION_SPECIFIC_H_
75 #define _FRSH_IMPLEMENTATION_SPECIFIC_H_
77 #include "frsh_implementation_specific_types.h"
78 #include "frsh_core.h"
80 #define FRSH_IMPLEMENTATION_SPECIFIC_MODULE_SUPPORTED 1
85 * @file frsh_implementation_specific.h
90 * @defgroup implementationspec Implementation Specific module
92 * The operations defined in this module are of optional use. The
93 * intention is to provide better tunning options taking advantage of
94 * specific characteristics of the underlaying OS.
97 * e.g. being able to manually assign priorities assuming that the OS
98 * uses a fixed priority paradigm).
104 * frsh_contract_set_preemption_level()
106 * The operation updates the specified contract parameters object by
107 * setting its preemption level to the specified input parameter.
109 * OBSERVATION: if this value is changed being any contract that
110 * uses the resource already accepted, the system's behavior and
111 * particularly the acceptance tests correctness are not garantee
112 * and probably wrong.
115 int frsh_contract_set_preemption_level
116 (frsh_contract_t *contract,
117 frsh_preemption_level_t preemption_level);
121 * frsh_contract_get_preemption_level()
123 * The operation obtains from the specified contract parameters object
124 * its preemption level and copies it to the place pointed to by the
125 * specified input parameter.
127 int frsh_contract_get_preemption_level
128 (const frsh_contract_t *contract,
129 frsh_preemption_level_t *preemption_level);
132 * frsh_service_thread_set_preemption_level()
134 * This function sets the preemption level of the service thread to
135 * the specified value. The initial preemption level is a configurable
136 * parameter. This value is stored in a temporary variable and it is
137 * used the next time the service thread data is updated with the
138 * frsh_service_thread_set_data() function.
140 int frsh_service_thread_set_preemption_level
141 (frsh_preemption_level_t preemption_level);
144 * frsh_service_thread_get_preemption_level()
146 * This function stores the current preemption level of the service
147 * thread in the variable pointed to by preemption_level
149 int frsh_service_thread_get_preemption_level
150 (frsh_preemption_level_t *preemption_level);
156 * This operation shall terminate the calling thread, make the value
157 * value_ptr available to any successful join with the terminating
158 * thread, and unbind the thread from its associated vres. After
159 * cleaning up the thread management data, it is unbound and the
160 * scheduling policy is changed to fixed priority before the posix
161 * pthread_exit() function is called.
163 * There is a limitation in the current version of the
164 * MaRTE implementation that causes the information of a terminated
165 * thread to continue to be stored in the frsh scheduler, and the thread
166 * to continue to be counted in the number of threads. The
167 * frsh_thread_exit operation allows the implementation to delete the
168 * thread's information, and then terminate the thread. Therefore, it
169 * is recommended to use this function to terminate a thread under frsh.
171 * Implementation dependent issue: in the implementation with an
172 * application scheduler, after cleaning up the thread management
173 * data, it is unbound and the scheduling policy changed to fixed
174 * priority before calling the posix pthread_exit() function.
176 * NOTE: This function, together with the internal function
177 * frsh_internal_remove_thread() has been removed from FRSH
178 * because it shouldn't be necessary.
180 * If there are some problems with MaRTE in thread termination
181 * it should be fixed in the OS and not here.
183 * The function does not do anything special that is not done in the
184 * terminate callback of the FRSH scheduler.
186 * If you want to be curious about what the function did, look at the
187 * SVN repository (revision 273) or one of the past branches.
189 void frsh_thread_exit (void *value_ptr);
193 * frsh_sharedobj_set_preemption_level()
195 * The operation updates the specified shared object by setting its
196 * preemption level to the specified input parameter.
198 * OBSERVATION: if this value is changed being any contract that
199 * uses the resource already accepted, the system's behavior and
200 * particularly the acceptance tests correctness are not garantee
201 * and probably wrong.
203 int frsh_sharedobj_set_preemption_level(frsh_sharedobj_handle_t obj_handle,
204 frsh_preemption_level_t preemption_level);
207 * frsh_sharedobj_get_preemption_level()
209 * The operation obtains from the specified shared object its
210 * preemption level and copies it to the place pointed to by the
211 * specified input parameter.
213 int frsh_sharedobj_get_preemption_level(frsh_sharedobj_handle_t obj_handle,
214 frsh_preemption_level_t *preemption_level);
220 #endif // _FRSH_IMPLEMENTATION_SPECIFIC_H_