1 // -----------------------------------------------------------------------
2 // Copyright (C) 2006 - 2007 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 API
36 // FRSH API is free software; you can redistribute it and/or modify
37 // it under the terms of the GNU General Public License as published by
38 // the Free Software Foundation; either version 2, or (at your option)
41 // FRSH API is distributed in the hope that it will be useful, but
42 // WITHOUT ANY WARRANTY; without even the implied warranty of
43 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
44 // General Public License for more details.
46 // You should have received a copy of the GNU General Public License
47 // distributed with FRSH API; see file COPYING. If not, write to the
48 // Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
51 // As a special exception, if you include this header file into source
52 // files to be compiled, this header file does not by itself cause
53 // the resulting executable to be covered by the GNU General Public
54 // License. This exception does not however invalidate any other
55 // reasons why the executable file might be covered by the GNU General
57 // -----------------------------------------------------------------------
60 //==============================================
61 // ******** ******* ******** ** **
62 // **///// /**////** **////// /** /**
63 // ** /** /** /** /** /**
64 // ******* /******* /********* /**********
65 // **//// /**///** ////////** /**//////**
66 // ** /** //** /** /** /**
67 // ** /** //** ******** /** /**
68 // // // // //////// // //
70 // FRSH(FRescor ScHeduler), pronounced "fresh"
71 //==============================================
72 #ifndef _FRSH_HIERARCHICAL_H_
73 #define _FRSH_HIERARCHICAL_H_
76 #include "frsh_hierarchical_types.h"
77 #include "frsh_core.h"
81 #define FRSH_HIERARCHICAL_MODULE_SUPPORTED 1
84 * @file frsh_hierarchical.h
88 * @defgroup hierarchical Hierarchical Scheduling Module
90 * This module includes the types and functions to use local
91 * schedulers within vres allowing to attach more than one thread
92 * to a vres and define an scheduling policy within.
98 * frsh_local_scheduler_init()
100 * This call has the following effects:
104 * Records the schedule duration, and starts the
105 * schedule at the time of the call. After the
106 * schedule duration has elapsed, the schedule in
107 * the table is repeated.
109 * @return 0 if no error \n
110 * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range,
112 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
113 * scheduled under the FRSH \n
114 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
116 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
117 * has been cancelled or it is not valid
119 int frsh_local_scheduler_init(
121 frsh_sched_init_info_t info);
125 * frsh_contract_set_sched_policy()
127 * The operation updates the specified contract parameters object by
128 * setting its scheduling policy to the specified input parameter.
129 * The default policy is FRSH_NONE, which means that only one thread
130 * may be bound to the vres
132 * @return 0 if no error \n
133 * FRSH_ERR_BAD_ARGUMENT : if sched_policy is not in range,
134 * or contract is NULL
136 int frsh_contract_set_sched_policy
137 (frsh_contract_t *contract,
138 frsh_sched_policy_t sched_policy);
142 * frsh_contract_get_sched_policy()
144 * This operation obtains from the specified contract parameters
145 * object its scheduling policy, and copies it to the place pointed to
146 * by the corresponding input parameter.
148 * @return 0 if no error \n
149 * FRSH_ERR_BAD_ARGUMENT : if sched_policy or contract are NULL
151 int frsh_contract_get_sched_policy
152 (const frsh_contract_t *contract,
153 frsh_sched_policy_t *sched_policy);
157 * frsh_thread_create_local()
159 * This operation creates a thread and binds it to the specified
160 * vres, which must have a policy different than FRSH_NONE. The new
161 * thread is created with the arguments thread, attr, thread_code and
162 * arg as they are defined for the pthread_create() POSIX function
163 * call, and its local scheduling parameters are set to the value
164 * stored in the variable pointed to by sched_params, which must be
165 * compatible with the vres's scheduling policy. Then, the function
166 * binds the created thread to the new vres. The attr /parameter is
167 * overwritten as necessary to introduce the adequate scheduling
168 * policy and priority, according to the preemption level given in the
169 * contract and the frsh_priority_map() function defined by the user.
171 * @return 0 if no error \n
172 * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range,
173 * or sched_params is NULL \n
174 * FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy
175 * in sched_params is not compatible to the vres's one \n
176 * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
178 * FRSH_ERR_NOT_CONTRACTED_VRES : if the referenced vres is not
180 * FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
181 * of the vres is FRSH_OVERHEAD \n
183 * It may also return any of the errors that may be returned by the
184 * pthread_create()POSIX function call
186 int frsh_thread_create_local(frsh_vres_id_t vres,
187 frsh_sched_params_t *sched_params,
188 frsh_thread_id_t *thread,
189 frsh_thread_attr_t *attr,
190 frsh_thread_code_t thread_code,
194 * frsh_thread_bind_local()
196 * This operation associates a thread with a vres, which must have a
197 * policy different than FRSH_NONE. The thread's local scheduling
198 * parameters are set to the value stored in the variable pointed to
199 * by sched_params, which must be compatible with the vres's
200 * scheduling policy. After the call the thread starts consuming the
201 * vres's budget and is executed according to the contract
202 * established for that vres and to its scheduling policy. If the
203 * thread was already bound to another vres, it is effectively
204 * unbound from it and bound to the specified one.
206 * Implementation dependent issue: In order to allow the usage of
207 * application defined schedulers, the given thread must not have the
208 * scheduling policy SCHED_APP and at the same time be attached to an
209 * application scheduler different than the frsh scheduler.
211 * @return 0 if no error \n
212 * FRSH_ERR_BAD_ARGUMENT : if the vres argument does not complain with
213 * the expected format or valid range, the given thread does not exist,
214 * or sched_params is NULL \n
215 * FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy
216 * in sched_params is not compatible to the vres's one. \n
217 * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
219 * FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
220 * an application defined scheduler different than the frsh
222 * FRSH_ERR_NOT_CONTRACTED_VRES : if the referenced vres is not
224 * FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
225 * of the vres is FRSH_OVERHEAD
227 int frsh_thread_bind_local(frsh_vres_id_t vres,
228 frsh_thread_id_t thread,
229 frsh_sched_params_t *sched_params);
233 * frsh_thread_set_local_sched_params()
235 * This function changes the local scheduling parameters of the thread
236 * to the value pointed to by sched_params. This value must be
237 * compatible with the scheduling policy of the vres to which the
240 * @return 0 if no error \n
241 * FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist,
242 * or sched_params is NULL \n
243 * FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the thread is already bound
244 * and the scheduling policy in sched_params is not compatible to the
245 * one of the thread's vres. \n
246 * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
248 * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
250 * FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
251 * an application defined scheduler different than the frsh
253 * FRSH_ERR_NOT_CONTRACTED_VRES : if the thread is bound and its vres
256 int frsh_thread_set_local_sched_params (frsh_thread_id_t thread,
257 const frsh_sched_params_t *sched_params);
260 * frsh_thread_get_local_sched_params()
262 * This function stores the local scheduling parameters of the
263 * specified thread in the variable pointed to by sched_params.
265 * @return 0 if no error \n
266 * FRSH_ERR_BAD_ARGUMENT : if sched_params is NULL or the thread does
268 * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
271 int frsh_thread_get_local_sched_params(frsh_thread_id_t thread,
272 frsh_sched_params_t *sched_params);
278 #endif // _FRSH_HIERARCHICAL_H_