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"
80 #define FRSH_HIERARCHICAL_MODULE_SUPPORTED 1
83 * @file frsh_hierarchical.h
87 * @defgroup hierarchical Hierarchical Scheduling Module
89 * This module includes the types and functions to use local
90 * schedulers within vres allowing to attach more than one thread
91 * to a vres and define an scheduling policy within.
97 * frsh_local_scheduler_init()
99 * This call has the following effects:
103 * Records the schedule duration, and starts the
104 * schedule at the time of the call. After the
105 * schedule duration has elapsed, the schedule in
106 * the table is repeated.
108 * @return 0 if no error \n
109 * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range,
111 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
112 * scheduled under the FRSH \n
113 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
115 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
116 * has been cancelled or it is not valid
118 int frsh_local_scheduler_init(
120 frsh_sched_init_info_t info);
124 * frsh_contract_set_sched_policy()
126 * The operation updates the specified contract parameters object by
127 * setting its scheduling policy to the specified input parameter.
128 * The default policy is FRSH_NONE, which means that only one thread
129 * may be bound to the vres
131 * @return 0 if no error \n
132 * FRSH_ERR_BAD_ARGUMENT : if sched_policy is not in range,
133 * or contract is NULL
135 int frsh_contract_set_sched_policy
136 (frsh_contract_t *contract,
137 frsh_sched_policy_t sched_policy);
141 * frsh_contract_get_sched_policy()
143 * This operation obtains from the specified contract parameters
144 * object its scheduling policy, and copies it to the place pointed to
145 * by the corresponding input parameter.
147 * @return 0 if no error \n
148 * FRSH_ERR_BAD_ARGUMENT : if sched_policy or contract are NULL
150 int frsh_contract_get_sched_policy
151 (const frsh_contract_t *contract,
152 frsh_sched_policy_t *sched_policy);
156 * frsh_thread_create_local()
158 * This operation creates a thread and binds it to the specified
159 * vres, which must have a policy different than FRSH_NONE. The new
160 * thread is created with the arguments thread, attr, thread_code and
161 * arg as they are defined for the pthread_create() POSIX function
162 * call, and its local scheduling parameters are set to the value
163 * stored in the variable pointed to by sched_params, which must be
164 * compatible with the vres's scheduling policy. Then, the function
165 * binds the created thread to the new vres. The attr /parameter is
166 * overwritten as necessary to introduce the adequate scheduling
167 * policy and priority, according to the preemption level given in the
168 * contract and the frsh_priority_map() function defined by the user.
170 * @return 0 if no error \n
171 * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range,
172 * or sched_params is NULL \n
173 * FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy
174 * in sched_params is not compatible to the vres's one \n
175 * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
177 * FRSH_ERR_NOT_CONTRACTED_VRES : if the referenced vres is not
179 * FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
180 * of the vres is FRSH_OVERHEAD \n
182 * It may also return any of the errors that may be returned by the
183 * pthread_create()POSIX function call
185 int frsh_thread_create_local(frsh_vres_id_t vres,
186 frsh_sched_params_t *sched_params,
187 frsh_thread_id_t *thread,
188 frsh_thread_attr_t *attr,
189 frsh_thread_code_t thread_code,
193 * frsh_thread_bind_local()
195 * This operation associates a thread with a vres, which must have a
196 * policy different than FRSH_NONE. The thread's local scheduling
197 * parameters are set to the value stored in the variable pointed to
198 * by sched_params, which must be compatible with the vres's
199 * scheduling policy. After the call the thread starts consuming the
200 * vres's budget and is executed according to the contract
201 * established for that vres and to its scheduling policy. If the
202 * thread was already bound to another vres, it is effectively
203 * unbound from it and bound to the specified one.
205 * Implementation dependent issue: In order to allow the usage of
206 * application defined schedulers, the given thread must not have the
207 * scheduling policy SCHED_APP and at the same time be attached to an
208 * application scheduler different than the frsh scheduler.
210 * @return 0 if no error \n
211 * FRSH_ERR_BAD_ARGUMENT : if the vres argument does not complain with
212 * the expected format or valid range, the given thread does not exist,
213 * or sched_params is NULL \n
214 * FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy
215 * in sched_params is not compatible to the vres's one. \n
216 * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
218 * FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
219 * an application defined scheduler different than the frsh
221 * FRSH_ERR_NOT_CONTRACTED_VRES : if the referenced vres is not
223 * FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
224 * of the vres is FRSH_OVERHEAD
226 int frsh_thread_bind_local(frsh_vres_id_t vres,
227 frsh_thread_id_t thread,
228 frsh_sched_params_t *sched_params);
232 * frsh_thread_set_local_sched_params()
234 * This function changes the local scheduling parameters of the thread
235 * to the value pointed to by sched_params. This value must be
236 * compatible with the scheduling policy of the vres to which the
239 * @return 0 if no error \n
240 * FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist,
241 * or sched_params is NULL \n
242 * FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the thread is already bound
243 * and the scheduling policy in sched_params is not compatible to the
244 * one of the thread's vres. \n
245 * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
247 * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
249 * FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
250 * an application defined scheduler different than the frsh
252 * FRSH_ERR_NOT_CONTRACTED_VRES : if the thread is bound and its vres
255 int frsh_thread_set_local_sched_params (frsh_thread_id_t thread,
256 const frsh_sched_params_t *sched_params);
259 * frsh_thread_get_local_sched_params()
261 * This function stores the local scheduling parameters of the
262 * specified thread in the variable pointed to by sched_params.
264 * @return 0 if no error \n
265 * FRSH_ERR_BAD_ARGUMENT : if sched_params is NULL or the thread does
267 * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
270 int frsh_thread_get_local_sched_params(frsh_thread_id_t thread,
271 frsh_sched_params_t *sched_params);
275 #endif // _FRSH_HIERARCHICAL_H_