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 // -----------------------------------------------------------------------
63 //==============================================
64 // ******** ******* ******** ** **
65 // **///// /**////** **////// /** /**
66 // ** /** /** /** /** /**
67 // ******* /******* /********* /**********
68 // **//// /**///** ////////** /**//////**
69 // ** /** //** /** /** /**
70 // ** /** //** ******** /** /**
71 // // // // //////// // //
73 // FRSH(FRescor ScHeduler), pronounced "fresh"
74 //==============================================
75 #ifndef _FRSH_HIERARCHICAL_H_
76 #define _FRSH_HIERARCHICAL_H_
79 #include "frsh_hierarchical_types.h"
80 #include "frsh_core.h"
84 #define FRSH_HIERARCHICAL_MODULE_SUPPORTED 1
87 * @file frsh_hierarchical.h
91 * @defgroup hierarchical Hierarchical Scheduling Module
93 * This module includes the types and functions to use local
94 * schedulers within vres allowing to attach more than one thread
95 * to a vres and define an scheduling policy within.
101 * frsh_local_scheduler_init()
103 * This call has the following effects:
107 * Records the schedule duration, and starts the
108 * schedule at the time of the call. After the
109 * schedule duration has elapsed, the schedule in
110 * the table is repeated.
112 * @return 0 if no error \n
113 * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range,
115 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
116 * scheduled under the FRSH \n
117 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
119 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
120 * has been cancelled or it is not valid
122 int frsh_local_scheduler_init(
124 frsh_sched_init_info_t info);
128 * frsh_contract_set_sched_policy()
130 * The operation updates the specified contract parameters object by
131 * setting its scheduling policy to the specified input parameter.
132 * The default policy is FRSH_NONE, which means that only one thread
133 * may be bound to the vres
135 * @return 0 if no error \n
136 * FRSH_ERR_BAD_ARGUMENT : if sched_policy is not in range,
137 * or contract is NULL
139 int frsh_contract_set_sched_policy
140 (frsh_contract_t *contract,
141 frsh_sched_policy_t sched_policy);
145 * frsh_contract_get_sched_policy()
147 * This operation obtains from the specified contract parameters
148 * object its scheduling policy, and copies it to the place pointed to
149 * by the corresponding input parameter.
151 * @return 0 if no error \n
152 * FRSH_ERR_BAD_ARGUMENT : if sched_policy or contract are NULL
154 int frsh_contract_get_sched_policy
155 (const frsh_contract_t *contract,
156 frsh_sched_policy_t *sched_policy);
160 * frsh_thread_create_local()
162 * This operation creates a thread and binds it to the specified
163 * vres, which must have a policy different than FRSH_NONE. The new
164 * thread is created with the arguments thread, attr, thread_code and
165 * arg as they are defined for the pthread_create() POSIX function
166 * call, and its local scheduling parameters are set to the value
167 * stored in the variable pointed to by sched_params, which must be
168 * compatible with the vres's scheduling policy. Then, the function
169 * binds the created thread to the new vres. The attr /parameter is
170 * overwritten as necessary to introduce the adequate scheduling
171 * policy and priority, according to the preemption level given in the
172 * contract and the frsh_priority_map() function defined by the user.
174 * @return 0 if no error \n
175 * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range,
176 * or sched_params is NULL \n
177 * FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy
178 * in sched_params is not compatible to the vres's one \n
179 * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
181 * FRSH_ERR_NOT_CONTRACTED_VRES : if the referenced vres is not
183 * FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
184 * of the vres is FRSH_OVERHEAD \n
186 * It may also return any of the errors that may be returned by the
187 * pthread_create()POSIX function call
189 int frsh_thread_create_local(frsh_vres_id_t vres,
190 frsh_sched_params_t *sched_params,
191 frsh_thread_id_t *thread,
192 frsh_thread_attr_t *attr,
193 frsh_thread_code_t thread_code,
197 * frsh_thread_bind_local()
199 * This operation associates a thread with a vres, which must have a
200 * policy different than FRSH_NONE. The thread's local scheduling
201 * parameters are set to the value stored in the variable pointed to
202 * by sched_params, which must be compatible with the vres's
203 * scheduling policy. After the call the thread starts consuming the
204 * vres's budget and is executed according to the contract
205 * established for that vres and to its scheduling policy. If the
206 * thread was already bound to another vres, it is effectively
207 * unbound from it and bound to the specified one.
209 * Implementation dependent issue: In order to allow the usage of
210 * application defined schedulers, the given thread must not have the
211 * scheduling policy SCHED_APP and at the same time be attached to an
212 * application scheduler different than the frsh scheduler.
214 * @return 0 if no error \n
215 * FRSH_ERR_BAD_ARGUMENT : if the vres argument does not complain with
216 * the expected format or valid range, the given thread does not exist,
217 * or sched_params is NULL \n
218 * FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy
219 * in sched_params is not compatible to the vres's one. \n
220 * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
222 * FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
223 * an application defined scheduler different than the frsh
225 * FRSH_ERR_NOT_CONTRACTED_VRES : if the referenced vres is not
227 * FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
228 * of the vres is FRSH_OVERHEAD
230 int frsh_thread_bind_local(frsh_vres_id_t vres,
231 frsh_thread_id_t thread,
232 frsh_sched_params_t *sched_params);
236 * frsh_thread_set_local_sched_params()
238 * This function changes the local scheduling parameters of the thread
239 * to the value pointed to by sched_params. This value must be
240 * compatible with the scheduling policy of the vres to which the
243 * @return 0 if no error \n
244 * FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist,
245 * or sched_params is NULL \n
246 * FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the thread is already bound
247 * and the scheduling policy in sched_params is not compatible to the
248 * one of the thread's vres. \n
249 * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
251 * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
253 * FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
254 * an application defined scheduler different than the frsh
256 * FRSH_ERR_NOT_CONTRACTED_VRES : if the thread is bound and its vres
259 int frsh_thread_set_local_sched_params (frsh_thread_id_t thread,
260 const frsh_sched_params_t *sched_params);
263 * frsh_thread_get_local_sched_params()
265 * This function stores the local scheduling parameters of the
266 * specified thread in the variable pointed to by sched_params.
268 * @return 0 if no error \n
269 * FRSH_ERR_BAD_ARGUMENT : if sched_params is NULL or the thread does
271 * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
274 int frsh_thread_get_local_sched_params(frsh_thread_id_t thread,
275 frsh_sched_params_t *sched_params);
281 #endif // _FRSH_HIERARCHICAL_H_