X-Git-Url: https://rtime.felk.cvut.cz/gitweb/frescor/frsh-include.git/blobdiff_plain/5d9461d116883ebac0be45354a00b5ff14725e43..HEAD:/frsh_hierarchical.h diff --git a/frsh_hierarchical.h b/frsh_hierarchical.h index c5bd36f..f04812f 100644 --- a/frsh_hierarchical.h +++ b/frsh_hierarchical.h @@ -1,279 +1,275 @@ // ----------------------------------------------------------------------- -// Copyright (C) 2005 Mälardalen University, SWEDEN +// Copyright (C) 2006 - 2009 FRESCOR consortium partners: +// +// Universidad de Cantabria, SPAIN +// University of York, UK +// Scuola Superiore Sant'Anna, ITALY +// Kaiserslautern University, GERMANY +// Univ. Politécnica Valencia, SPAIN +// Czech Technical University in Prague, CZECH REPUBLIC +// ENEA SWEDEN +// Thales Communication S.A. FRANCE +// Visual Tools S.A. SPAIN +// Rapita Systems Ltd UK +// Evidence ITALY +// +// See http://www.frescor.org for a link to partners' websites +// +// FRESCOR project (FP6/2005/IST/5-034026) is funded +// in part by the European Union Sixth Framework Programme +// The European Union is not liable of any use that may be +// made of this code. +// +// +// based on previous work (FSF) done in the FIRST project +// +// Copyright (C) 2005 Mälardalen University, SWEDEN // Scuola Superiore S.Anna, ITALY // Universidad de Cantabria, SPAIN // University of York, UK // -// FRSH API web pages: http://marte.unican.es/frsh/docs/ +// FSF API web pages: http://marte.unican.es/fsf/docs // http://shark.sssup.it/contrib/first/docs/ // -// This file is part of FRSH API -// -// FRSH API is free software; you can redistribute it and/or modify -// it under the terms of the GNU General Public License as published by -// the Free Software Foundation; either version 2, or (at your option) -// any later version. +// This file is part of FRSH (FRescor ScHeduler) // -// FRSH API is distributed in the hope that it will be useful, but -// WITHOUT ANY WARRANTY; without even the implied warranty of -// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -// General Public License for more details. +// FRSH is free software; you can redistribute it and/or modify it +// under terms of the GNU General Public License as published by the +// Free Software Foundation; either version 2, or (at your option) any +// later version. FRSH is distributed in the hope that it will be +// useful, but WITHOUT ANY WARRANTY; without even the implied warranty +// of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +// General Public License for more details. You should have received a +// copy of the GNU General Public License along with FRSH; see file +// COPYING. If not, write to the Free Software Foundation, 675 Mass Ave, +// Cambridge, MA 02139, USA. // -// You should have received a copy of the GNU General Public License -// distributed with FRSH API; see file COPYING. If not, write to the -// Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA -// 02111-1307, USA. -// -// As a special exception, if you include this header file into source -// files to be compiled, this header file does not by itself cause -// the resulting executable to be covered by the GNU General Public -// License. This exception does not however invalidate any other -// reasons why the executable file might be covered by the GNU General -// Public License. +// As a special exception, including FRSH header files in a file, +// instantiating FRSH generics or templates, or linking other files +// with FRSH objects to produce an executable application, does not +// by itself cause the resulting executable application to be covered +// by the GNU General Public License. This exception does not +// however invalidate any other reasons why the executable file might be +// covered by the GNU Public License. // ----------------------------------------------------------------------- //frsh_hierarchical.h -//==================================================================== -// FFFFFFIII RRRRR SSTTTTTTT -// FF IIR RR SS -// FF IR SS -// FFFFFF RRRR SSSSST -// FF FI RRR SS -// FF II RRR SS -// FF IIIIIR RS + +//============================================== +// ******** ******* ******** ** ** +// **///// /**////** **////// /** /** +// ** /** /** /** /** /** +// ******* /******* /********* /********** +// **//// /**///** ////////** /**//////** +// ** /** //** /** /** /** +// ** /** //** ******** /** /** +// // // // //////// // // // -// FRSH(FIRST Scheduling Framework) -// hierarchical scheduling management -//=================================================================== +// FRSH(FRescor ScHeduler), pronounced "fresh" +//============================================== +#ifndef _FRSH_HIERARCHICAL_H_ +#define _FRSH_HIERARCHICAL_H_ #include -#include "frsh_basic_types.h" +#include "frsh_hierarchical_types.h" #include "frsh_core.h" -#ifndef _FRSH_HIERARCHICAL_H_ -#define _FRSH_HIERARCHICAL_H_ +FRSH_CPP_BEGIN_DECLS #define FRSH_HIERARCHICAL_MODULE_SUPPORTED 1 -//// The definition of this types is in frsh_basic_types.h -// -//// Scheduling policies -//typedef enum {FRSH_FP, FRSH_EDF, FRSH_TABLE_DRIVEN, FRSH_NONE} -// frsh_sched_policy_t; -// -//// Scheduling policy and parameters -//typedef struct { -// frsh_sched_policy_t policy; -// void * params; -//} frsh_sched_params_t; -//// The params member is a pointer to one of the -//// following: -//// FP: int (priority) -//// EDF: struct timespec (deadline) -//// TABLE_DRIVEN : struct frsh_table_driven_params_t -// -// -////Scheduling parameters for the table-driven policy (t.b.d) -//typedef struct { -// // list of target windows (t.b.d.) -// // deadline (for the API): end of september -//} frsh_table_driven_params_t; -// -// -////Initialization information for a scheduling policy -//typedef void * frsh_sched_init_info_t; -//// It shall be one of the following: -//// FP: none -//// EDF: none -//// TABLE_DRIVEN : struct timespec (schedule duration) -// - -//frsh_init_local_scheduler: This call has the following effects: -// FP: none -// EDF: none -// TABLE_DRIVEN : -// Records the schedule duration, and starts the -// schedule at the time of the call. After the -// schedule duration has elapsed, the schedule in -// the table is repeated. -/* - [ERR@RETURNED: - FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range, - or info is NULL - FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not - scheduled under the FRSH - FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running - FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread - has been cancelled or it is not valid - ] -*/ -int frsh_init_local_scheduler( - frsh_server_id_t server, - frsh_sched_init_info_t info); - +/** + * @file frsh_hierarchical.h + **/ -// Constants for assigning default values -#define FRSH_DEFAULT_SCHED_POLICY FRSH_NONE +/** + * @defgroup hierarchical Hierarchical Scheduling Module + * + * This module includes the types and functions to use local + * schedulers within vres allowing to attach more than one thread + * to a vres and define an scheduling policy within. + * + * @{ + **/ +/** + * frsh_local_scheduler_init() + * + * This call has the following effects: + * FP: none \n + * EDF: none \n + * TABLE_DRIVEN : + * Records the schedule duration, and starts the + * schedule at the time of the call. After the + * schedule duration has elapsed, the schedule in + * the table is repeated. + * + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range, + * or info is NULL \n + * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not + * scheduled under the FRSH \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not + * running \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread + * has been cancelled or it is not valid + **/ +int frsh_local_scheduler_init( + frsh_vres_id_t vres, + frsh_sched_init_info_t info); -///////////////////////////////////////////////// -// CONTRACT PARAMETERS -//////////////////////////////////////////////// - -//frsh_set_contract_scheduling_policy: The operation updates the -//specified contract parameters object by setting its scheduling -//policy to the specified input parameter. The default policy is -//FRSH_NONE, which means that only one thread may be bound to the -//server -/* - [ERR@RETURNED: - FRSH_ERR_BAD_ARGUMENT : if sched_policy is not in range, - or contract is NULL - ] -*/ -int -frsh_set_contract_scheduling_policy - (frsh_contract_parameters_t *contract, +/** + * frsh_contract_set_sched_policy() + * + * The operation updates the specified contract parameters object by + * setting its scheduling policy to the specified input parameter. + * The default policy is FRSH_NONE, which means that only one thread + * may be bound to the vres + * + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if sched_policy is not in range, + * or contract is NULL + **/ +int frsh_contract_set_sched_policy + (frsh_contract_t *contract, frsh_sched_policy_t sched_policy); -//frsh_get_contract_scheduling_policy: This operation obtains from the -//specified contract parameters object its scheduling policy, and -//copies it to the place pointed to by the corresponding input -//parameter. -/* - [ERR@RETURNED: - FRSH_ERR_BAD_ARGUMENT : if sched_policy or contract are NULL - ] -*/ - -int -frsh_get_contract_scheduling_policy - (const frsh_contract_parameters_t *contract, +/** + * frsh_contract_get_sched_policy() + * + * This operation obtains from the specified contract parameters + * object its scheduling policy, and copies it to the place pointed to + * by the corresponding input parameter. + * + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if sched_policy or contract are NULL + **/ +int frsh_contract_get_sched_policy + (const frsh_contract_t *contract, frsh_sched_policy_t *sched_policy); -//frsh_create_local_thread: : This operation creates a thread and binds -//it to the specified server, which must have a policy different than -//FRSH_NONE. The new thread is created with the arguments thread, attr, -//thread_code and arg as they are defined for the pthread_create() -//POSIX function call, and its local scheduling parameters are set to -//the value stored in the variable pointed to by sched_params, which -//must be compatible with the server's scheduling policy. Then, the -//function binds the created thread to the new server. The attr -//parameter is overwritten as necessary to introduce the adequate -//scheduling policy and priority, according to the preemption level -//given in the contract and the frsh_priority_map() function defined by -//the user. -/* - [ERR@RETURNED: - FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range, - or sched_params is NULL - FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy - in sched_params is not compatible to the server's one. - FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH - main scheduler - FRSH_ERR_NOT_CONTRACTED_SERVER : if the referenced server is not valid - FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload - of the server is FRSH_OVERHEAD - - It may also return any of the errors that may be returned by the - pthread_create()POSIX function call - ] -*/ - -int -frsh_create_local_thread - (frsh_server_id_t server, - frsh_sched_params_t *sched_params, - pthread_t *thread, - pthread_attr_t *attr, - frsh_thread_code_t thread_code, - void *arg); - -//frsh_bind_local_thread_to_server: This operation associates a thread -//with a server, which must have a policy different than FRSH_NONE. The -//thread's local scheduling parameters are set to the value stored in -//the variable pointed to by sched_params, which must be compatible -//with the server's scheduling policy. After the call the thread -//starts consuming the server's budget and is executed according to -//the contract established for that server and to its scheduling -//policy. If the thread was already bound to another server, it is -//effectively unbound from it and bound to the specified one. - -//Implementation dependent issue: In order to allow the usage of -//application defined schedulers, the given thread must not have the -//scheduling policy SCHED_APP and at the same time be attached to an -//application scheduler different than the frsh scheduler. - -/* - [ERR@RETURNED: - FRSH_ERR_BAD_ARGUMENT : if the server argument does not complain with - the expected format or valid range, the given thread does not exist, - or sched_params is NULL - FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy - in sched_params is not compatible to the server's one. - FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH - main scheduler - FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to - an application defined scheduler different than the frsh scheduler - FRSH_ERR_NOT_CONTRACTED_SERVER : if the referenced server is not valid - FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload - of the server is FRSH_OVERHEAD - ] -*/ +/** + * frsh_thread_create_local() + * + * This operation creates a thread and binds it to the specified + * vres, which must have a policy different than FRSH_NONE. The new + * thread is created with the arguments thread, attr, thread_code and + * arg as they are defined for the pthread_create() POSIX function + * call, and its local scheduling parameters are set to the value + * stored in the variable pointed to by sched_params, which must be + * compatible with the vres's scheduling policy. Then, the function + * binds the created thread to the new vres. The attr /parameter is + * overwritten as necessary to introduce the adequate scheduling + * policy and priority, according to the preemption level given in the + * contract and the frsh_priority_map() function defined by the user. + * + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range, + * or sched_params is NULL \n + * FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy + * in sched_params is not compatible to the vres's one \n + * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH + * main scheduler \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the referenced vres is not + * valid \n + * FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload + * of the vres is FRSH_OVERHEAD \n + * . + * It may also return any of the errors that may be returned by the + * pthread_create()POSIX function call + **/ +int frsh_thread_create_local(frsh_vres_id_t vres, + frsh_sched_params_t *sched_params, + frsh_thread_id_t *thread, + frsh_thread_attr_t *attr, + frsh_thread_code_t thread_code, + void *arg); -int -frsh_bind_local_thread_to_server - (frsh_server_id_t server, - pthread_t thread, - frsh_sched_params_t *sched_params); +/** + * frsh_thread_bind_local() + * + * This operation associates a thread with a vres, which must have a + * policy different than FRSH_NONE. The thread's local scheduling + * parameters are set to the value stored in the variable pointed to + * by sched_params, which must be compatible with the vres's + * scheduling policy. After the call the thread starts consuming the + * vres's budget and is executed according to the contract + * established for that vres and to its scheduling policy. If the + * thread was already bound to another vres, it is effectively + * unbound from it and bound to the specified one. + * + * Implementation dependent issue: In order to allow the usage of + * application defined schedulers, the given thread must not have the + * scheduling policy SCHED_APP and at the same time be attached to an + * application scheduler different than the frsh scheduler. + * + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if the vres argument does not complain with + * the expected format or valid range, the given thread does not exist, + * or sched_params is NULL \n + * FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy + * in sched_params is not compatible to the vres's one. \n + * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH + * main scheduler \n + * FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to + * an application defined scheduler different than the frsh + * scheduler \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the referenced vres is not + * valid \n + * FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload + * of the vres is FRSH_OVERHEAD + **/ +int frsh_thread_bind_local(frsh_vres_id_t vres, + frsh_thread_id_t thread, + frsh_sched_params_t *sched_params); -// frsh_set_local_thread_sched_params: this function changes the -// local scheduling parameters of the thread to the value pointed to -// by sched_params. This value must be compatible with the scheduling -// policy of the server to which the thread is bound. -/* - [ERR@RETURNED: - FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist, - or sched_params is NULL - FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the thread is already bound - and the scheduling policy in sched_params is not compatible to the - one of the thread's server. - FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled - under the FRSH - FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH - main scheduler - FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to - an application defined scheduler different than the frsh scheduler - FRSH_ERR_NOT_CONTRACTED_SERVER : if the thread is bound and its server - is not valid - ] -*/ - -int -frsh_set_local_thread_sched_params - (pthread_t thread, - const frsh_sched_params_t *sched_params); - +/** + * frsh_thread_set_local_sched_params() + * + * This function changes the local scheduling parameters of the thread + * to the value pointed to by sched_params. This value must be + * compatible with the scheduling policy of the vres to which the + * thread is bound. + * + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist, + * or sched_params is NULL \n + * FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the thread is already bound + * and the scheduling policy in sched_params is not compatible to the + * one of the thread's vres. \n + * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled + * under FRSH \n + * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH + * main scheduler \n + * FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to + * an application defined scheduler different than the frsh + * scheduler \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the thread is bound and its vres + * is not valid + **/ +int frsh_thread_set_local_sched_params (frsh_thread_id_t thread, + const frsh_sched_params_t *sched_params); -// frsh_get_local_thread_sched_params: this function stores the -// local scheduling parameters of the specified thread in the variable -// pointed to by sched_params -/* - [ERR@RETURNED: - FRSH_ERR_BAD_ARGUMENT : if sched_params is NULL or the thread does - not exist - FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled - under the FRSH - ] -*/ +/** + * frsh_thread_get_local_sched_params() + * + * This function stores the local scheduling parameters of the + * specified thread in the variable pointed to by sched_params. + * + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if sched_params is NULL or the thread does + * not exist \n + * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled + * under FRSH + **/ +int frsh_thread_get_local_sched_params(frsh_thread_id_t thread, + frsh_sched_params_t *sched_params); -int -frsh_get_local_thread_sched_params - (pthread_t thread, - frsh_sched_params_t *sched_params); +/*}*/ +FRSH_CPP_END_DECLS #endif // _FRSH_HIERARCHICAL_H_