// -----------------------------------------------------------------------
-// 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 <time.h>
-#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_
projects / frescor / frsh-include.git / blobdiff