frsh_hierarchical.h

   1 // -----------------------------------------------------------------------
   2 //  Copyright (C) 2006 - 2007 FRESCOR consortium partners:
   3 //
   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
  10 //    ENEA                                   SWEDEN
  11 //    Thales Communication S.A.              FRANCE
  12 //    Visual Tools S.A.                      SPAIN
  13 //    Rapita Systems Ltd                     UK
  14 //    Evidence                               ITALY
  15 //
  16 //    See http://www.frescor.org for a link to partners' websites
  17 //
  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
  21 //        made of this code.
  22 //
  23 //
  24 //  based on previous work (FSF) done in the FIRST project
  25 //
  26 //   Copyright (C) 2005  Mälardalen University, SWEDEN
  27 //                       Scuola Superiore S.Anna, ITALY
  28 //                       Universidad de Cantabria, SPAIN
  29 //                       University of York, UK
  30 //
  31 //   FSF API web pages: http://marte.unican.es/fsf/docs
  32 //                      http://shark.sssup.it/contrib/first/docs/
  33 //
  34 //  This file is part of FRSH API
  35 //
  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)
  39 //  any later version.
  40 //
  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.
  45 //
  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
  49 //  02111-1307, USA.
  50 //
  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
  56 //  Public License.
  57 // -----------------------------------------------------------------------
  58 //frsh_hierarchical.h
  59
  60 //==============================================
  61 //  ******** *******    ********  **      **
  62 //  **///// /**////**  **//////  /**     /**
  63 //  **      /**   /** /**        /**     /**
  64 //  ******* /*******  /********* /**********
  65 //  **////  /**///**  ////////** /**//////**
  66 //  **      /**  //**        /** /**     /**
  67 //  **      /**   //** ********  /**     /**
  68 //  //       //     // ////////   //      //
  69 //
  70 // FRSH(FRescor ScHeduler), pronounced "fresh"
  71 //==============================================
  72 #ifndef _FRSH_HIERARCHICAL_H_
  73 #define _FRSH_HIERARCHICAL_H_
  74
  75 #include <time.h>
  76 #include "frsh_hierarchical_types.h"
  77 #include "frsh_core.h"
  78
  79
  80 #define FRSH_HIERARCHICAL_MODULE_SUPPORTED       1
  81
  82
  83 /**
  84  * @defgroup hierarchical Hierarchical Scheduling Module
  85  *
  86  * This module includes the types and functions to use local
  87  * schedulers within servers allowing to attach more than one thread
  88  * to a server and define an scheduling policy within.
  89  *
  90  * @{
  91  **/
  92
  93 /**
  94  * frsh_init_local_scheduler()
  95  *
  96  *  This call has the following effects:
  97  *    FP:  none
  98  *    EDF: none
  99  *    TABLE_DRIVEN :
 100  *       Records the schedule duration, and starts the
 101  *       schedule at the time of the call. After the
 102  *       schedule duration has elapsed, the schedule in
 103  *       the table is repeated.
 104  *
 105  *  @return
 106  *    FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range,
 107  *      or info is NULL
 108  *    FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 109  *      scheduled under the FRSH
 110  *    FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
 111  *    FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
 112  *      has been cancelled or it is not valid
 113  **/
 114 int frsh_init_local_scheduler(
 115    frsh_server_id_t       server,
 116    frsh_sched_init_info_t info);
 117
 118
 119 /**
 120  * frsh_set_contract_scheduling_policy()
 121  *
 122  *  The operation updates the specified contract parameters object by
 123  *  setting its scheduling policy to the specified input parameter.
 124  *  The default policy is FRSH_NONE, which means that only one thread
 125  *  may be bound to the server
 126  *
 127  *  @return
 128  *    FRSH_ERR_BAD_ARGUMENT : if sched_policy is not in range,
 129  *     or contract is NULL
 130  **/
 131 int frsh_set_contract_scheduling_policy
 132   (frsh_contract_parameters_t *contract,
 133    frsh_sched_policy_t         sched_policy);
 134
 135
 136 /**
 137  * frsh_get_contract_scheduling_policy()
 138  *
 139  * This operation obtains from the specified contract parameters
 140  * object its scheduling policy, and copies it to the place pointed to
 141  * by the corresponding input parameter.
 142  *
 143  *  @return
 144  *     FRSH_ERR_BAD_ARGUMENT : if sched_policy or contract are NULL
 145  **/
 146 int frsh_get_contract_scheduling_policy
 147   (const frsh_contract_parameters_t *contract,
 148    frsh_sched_policy_t              *sched_policy);
 149
 150
 151 /**
 152  * frsh_create_local_thread()
 153  *
 154  * This operation creates a thread and binds it to the specified
 155  * server, which must have a policy different than FRSH_NONE. The new
 156  * thread is created with the arguments thread, attr, thread_code and
 157  * arg as they are defined for the pthread_create() POSIX function
 158  * call, and its local scheduling parameters are set to the value
 159  * stored in the variable pointed to by sched_params, which must be
 160  * compatible with the server's scheduling policy. Then, the function
 161  * binds the created thread to the new server. The attr /parameter is
 162  * overwritten as necessary to introduce the adequate scheduling
 163  * policy and priority, according to the preemption level given in the
 164  * contract and the frsh_priority_map() function defined by the user.
 165  *
 166  * @return
 167  *   FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range,
 168  *     or sched_params is NULL
 169  *   FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy
 170  *     in sched_params is not compatible to the server's one.
 171  *   FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
 172  *     main scheduler
 173  *   FRSH_ERR_NOT_CONTRACTED_SERVER : if the referenced server is not valid
 174  *   FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
 175  *     of the server is FRSH_OVERHEAD
 176  *
 177  *   It may also return any of  the errors that may be returned by the
 178  *   pthread_create()POSIX function call
 179  **/
 180 int frsh_create_local_thread(frsh_server_id_t      server,
 181                              frsh_sched_params_t   *sched_params,
 182                              pthread_t             *thread,
 183                              pthread_attr_t        *attr,
 184                              frsh_thread_code_t      thread_code,
 185                              void                  *arg);
 186
 187 /**
 188  * frsh_bind_local_thread_to_server()
 189  *
 190  * This operation associates a thread with a server, which must have a
 191  * policy different than FRSH_NONE. The thread's local scheduling
 192  * parameters are set to the value stored in the variable pointed to
 193  * by sched_params, which must be compatible with the server's
 194  * scheduling policy. After the call the thread starts consuming the
 195  * server's budget and is executed according to the contract
 196  * established for that server and to its scheduling policy. If the
 197  * thread was already bound to another server, it is effectively
 198  * unbound from it and bound to the specified one.
 199  *
 200  * Implementation dependent issue: In order to allow the usage of
 201  * application defined schedulers, the given thread must not have the
 202  * scheduling policy SCHED_APP and at the same time be attached to an
 203  * application scheduler different than the frsh scheduler.
 204  *
 205  * @return
 206  *   FRSH_ERR_BAD_ARGUMENT : if the server argument does not complain with
 207  *     the expected format or valid range, the given thread does not exist,
 208  *     or sched_params is NULL
 209  *   FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy
 210  *     in sched_params is not compatible to the server's one.
 211  *   FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
 212  *     main scheduler
 213  *   FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
 214  *     an application defined scheduler different than the frsh scheduler
 215  *   FRSH_ERR_NOT_CONTRACTED_SERVER : if the referenced server is not valid
 216  *   FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
 217  *     of the server is FRSH_OVERHEAD
 218  **/
 219 int frsh_bind_local_thread_to_server(frsh_server_id_t      server,
 220                                      pthread_t            thread,
 221                                      frsh_sched_params_t  *sched_params);
 222
 223
 224 /**
 225  * frsh_set_local_thread_sched_parameters()
 226  *
 227  * This function changes the local scheduling parameters of the thread
 228  * to the value pointed to by sched_params. This value must be
 229  * compatible with the scheduling policy of the server to which the
 230  * thread is bound.
 231  *
 232  * @return
 233  *   FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist,
 234  *     or sched_params is NULL
 235  *   FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the thread is already bound
 236  *     and the scheduling policy in sched_params is not compatible to the
 237  *     one of the thread's server.
 238  *   FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
 239  *     under the FRSH
 240  *   FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
 241  *     main scheduler
 242  *   FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
 243  *     an application defined scheduler different than the frsh scheduler
 244  *   FRSH_ERR_NOT_CONTRACTED_SERVER : if the thread is bound and its server
 245  *     is not valid
 246  **/
 247 int frsh_set_local_thread_sched_parameters (pthread_t thread,
 248                           const frsh_sched_params_t  *sched_params);
 249
 250 /**
 251  * frsh_get_local_thread_sched_parameters()
 252  *
 253  * This function stores the local scheduling parameters of the
 254  * specified thread in the variable pointed to by sched_params.
 255  *
 256  * @return
 257  *   FRSH_ERR_BAD_ARGUMENT : if sched_params is NULL or the thread does
 258  *      not exist
 259  *   FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
 260  *      under the FRSH
 261  **/
 262 int frsh_get_local_thread_sched_parameters(pthread_t            thread,
 263                                        frsh_sched_params_t  *sched_params);
 264
 265 /*}*/
 266
 267 #endif // _FRSH_HIERARCHICAL_H_