frsh_hierarchical.h

   1 // -----------------------------------------------------------------------
   2 //   Copyright (C) 2005  Mälardalen University, SWEDEN
   3 //                       Scuola Superiore S.Anna, ITALY
   4 //                       Universidad de Cantabria, SPAIN
   5 //                       University of York, UK
   6 //
   7 //   FRSH API web pages: http://marte.unican.es/frsh/docs/
   8 //                      http://shark.sssup.it/contrib/first/docs/
   9 //
  10 //  This file is part of FRSH API
  11 //
  12 //  FRSH API is free software; you can  redistribute it and/or  modify
  13 //  it under the terms of  the GNU General Public License as published by
  14 //  the Free Software Foundation;  either  version 2, or (at  your option)
  15 //  any later version.
  16 //
  17 //  FRSH API  is distributed  in  the hope  that  it  will  be useful,  but
  18 //  WITHOUT  ANY  WARRANTY;     without  even the   implied   warranty  of
  19 //  MERCHANTABILITY  or  FITNESS FOR  A  PARTICULAR PURPOSE. See  the  GNU
  20 //  General Public License for more details.
  21 //
  22 //  You should have  received a  copy of  the  GNU  General Public License
  23 //  distributed  with  FRSH API;  see file COPYING.   If not,  write to the
  24 //  Free Software  Foundation,  59 Temple Place  -  Suite 330,  Boston, MA
  25 //  02111-1307, USA.
  26 //
  27 //  As a special exception, if you include this header file into source
  28 //  files to be compiled, this header file does not by itself cause
  29 //  the resulting executable to be covered by the GNU General Public
  30 //  License.  This exception does not however invalidate any other
  31 //  reasons why the executable file might be covered by the GNU General
  32 //  Public License.
  33 // -----------------------------------------------------------------------
  34 //frsh_hierarchical.h
  35 //====================================================================
  36 //       FFFFFFIII   RRRRR      SSTTTTTTT
  37 //      FF         IIR   RR    SS
  38 //     FF           IR        SS
  39 //    FFFFFF         RRRR    SSSSST
  40 //   FF       FI       RRR  SS
  41 //  FF         II     RRR  SS
  42 // FF           IIIIIR    RS
  43 //
  44 // FRSH(FIRST Scheduling Framework)
  45 // hierarchical scheduling management
  46 //===================================================================
  47
  48 #include <time.h>
  49 #include "frsh_basic_types.h"
  50 #include "frsh_core.h"
  51
  52 #ifndef _FRSH_HIERARCHICAL_H_
  53 #define _FRSH_HIERARCHICAL_H_
  54
  55 #define FRSH_HIERARCHICAL_MODULE_SUPPORTED       1
  56
  57 //// The definition of this types is in frsh_basic_types.h
  58 //
  59 //// Scheduling policies
  60 //typedef enum {FRSH_FP, FRSH_EDF, FRSH_TABLE_DRIVEN, FRSH_NONE}
  61 //    frsh_sched_policy_t;
  62 //
  63 //// Scheduling policy and parameters
  64 //typedef struct {
  65 //  frsh_sched_policy_t    policy;
  66 //  void *                params;
  67 //} frsh_sched_params_t;
  68 //// The params member is a pointer to one of the
  69 //// following:
  70 ////    FP:  int (priority)
  71 ////    EDF: struct timespec (deadline)
  72 ////    TABLE_DRIVEN : struct frsh_table_driven_params_t
  73 //
  74 //
  75 ////Scheduling parameters for the table-driven policy (t.b.d)
  76 //typedef struct {
  77 //  // list of target windows (t.b.d.)
  78 //  // deadline (for the API): end of september
  79 //} frsh_table_driven_params_t;
  80 //
  81 //
  82 ////Initialization information for a scheduling policy
  83 //typedef void * frsh_sched_init_info_t;
  84 //// It shall be one of the following:
  85 ////    FP:  none
  86 ////    EDF: none
  87 ////    TABLE_DRIVEN : struct timespec (schedule duration)
  88 //
  89
  90 //frsh_init_local_scheduler: This call has the following effects:
  91 //    FP:  none
  92 //    EDF: none
  93 //    TABLE_DRIVEN :
  94 //       Records the schedule duration, and starts the
  95 //       schedule at the time of the call. After the
  96 //       schedule duration has elapsed, the schedule in
  97 //       the table is repeated.
  98 /*
  99     [ERR@RETURNED:
 100      FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range,
 101        or info is NULL
 102      FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 103        scheduled under the FRSH
 104      FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
 105      FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
 106        has been cancelled or it is not valid
 107     ]
 108 */
 109 int frsh_init_local_scheduler(
 110    frsh_server_id_t       server,
 111    frsh_sched_init_info_t info);
 112
 113
 114 // Constants for assigning default values
 115 #define FRSH_DEFAULT_SCHED_POLICY        FRSH_NONE
 116
 117
 118 /////////////////////////////////////////////////
 119 //                       CONTRACT PARAMETERS
 120 ////////////////////////////////////////////////
 121
 122 //frsh_set_contract_scheduling_policy: The operation updates the
 123 //specified contract parameters object by setting its scheduling
 124 //policy to the specified input parameter.  The default policy is
 125 //FRSH_NONE, which means that only one thread may be bound to the
 126 //server
 127 /*
 128     [ERR@RETURNED:
 129      FRSH_ERR_BAD_ARGUMENT : if sched_policy is not in range,
 130        or contract is NULL
 131     ]
 132 */
 133
 134 int
 135 frsh_set_contract_scheduling_policy
 136   (frsh_contract_parameters_t *contract,
 137    frsh_sched_policy_t         sched_policy);
 138
 139
 140 //frsh_get_contract_scheduling_policy: This operation obtains from the
 141 //specified contract parameters object its scheduling policy, and
 142 //copies it to the place pointed to by the corresponding input
 143 //parameter.
 144 /*
 145     [ERR@RETURNED:
 146      FRSH_ERR_BAD_ARGUMENT : if sched_policy or contract are NULL
 147     ]
 148 */
 149
 150 int
 151 frsh_get_contract_scheduling_policy
 152   (const frsh_contract_parameters_t *contract,
 153    frsh_sched_policy_t              *sched_policy);
 154
 155
 156 //frsh_create_local_thread: : This operation creates a thread and binds
 157 //it to the specified server, which must have a policy different than
 158 //FRSH_NONE. The new thread is created with the arguments thread, attr,
 159 //thread_code and arg as they are defined for the pthread_create()
 160 //POSIX function call, and its local scheduling parameters are set to
 161 //the value stored in the variable pointed to by sched_params, which
 162 //must be compatible with the server's scheduling policy. Then, the
 163 //function binds the created thread to the new server. The attr
 164 //parameter is overwritten as necessary to introduce the adequate
 165 //scheduling policy and priority, according to the preemption level
 166 //given in the contract and the frsh_priority_map() function defined by
 167 //the user.
 168 /*
 169     [ERR@RETURNED:
 170      FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range,
 171        or sched_params is NULL
 172      FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy
 173        in sched_params is not compatible to the server's one.
 174      FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
 175        main scheduler
 176      FRSH_ERR_NOT_CONTRACTED_SERVER : if the referenced server is not valid
 177      FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
 178        of the server is FRSH_OVERHEAD
 179
 180      It may also return any of  the errors that may be returned by the
 181        pthread_create()POSIX function call
 182     ]
 183 */
 184
 185 int
 186 frsh_create_local_thread
 187   (frsh_server_id_t        server,
 188    frsh_sched_params_t    *sched_params,
 189    pthread_t             *thread,
 190    pthread_attr_t        *attr,
 191    frsh_thread_code_t      thread_code,
 192    void                  *arg);
 193
 194 //frsh_bind_local_thread_to_server: This operation associates a thread
 195 //with a server, which must have a policy different than FRSH_NONE. The
 196 //thread's local scheduling parameters are set to the value stored in
 197 //the variable pointed to by sched_params, which must be compatible
 198 //with the server's scheduling policy. After the call the thread
 199 //starts consuming the server's budget and is executed according to
 200 //the contract established for that server and to its scheduling
 201 //policy. If the thread was already bound to another server, it is
 202 //effectively unbound from it and bound to the specified one.
 203
 204 //Implementation dependent issue: In order to allow the usage of
 205 //application defined schedulers, the given thread must not have the
 206 //scheduling policy SCHED_APP and at the same time be attached to an
 207 //application scheduler different than the frsh scheduler.
 208
 209 /*
 210     [ERR@RETURNED:
 211      FRSH_ERR_BAD_ARGUMENT : if the server argument does not complain with
 212        the expected format or valid range, the given thread does not exist,
 213        or sched_params is NULL
 214      FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy
 215        in sched_params is not compatible to the server's one.
 216      FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
 217        main scheduler
 218      FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
 219        an application defined scheduler different than the frsh scheduler
 220      FRSH_ERR_NOT_CONTRACTED_SERVER : if the referenced server is not valid
 221      FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
 222        of the server is FRSH_OVERHEAD
 223     ]
 224 */
 225
 226 int
 227 frsh_bind_local_thread_to_server
 228   (frsh_server_id_t      server,
 229    pthread_t            thread,
 230    frsh_sched_params_t  *sched_params);
 231
 232
 233 // frsh_set_local_thread_sched_params: this function changes the
 234 // local scheduling parameters of the thread to the value pointed to
 235 // by sched_params. This value must be compatible with the scheduling
 236 // policy of the server to which the thread is bound.
 237 /*
 238     [ERR@RETURNED:
 239      FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist,
 240        or sched_params is NULL
 241      FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the thread is already bound
 242        and the scheduling policy in sched_params is not compatible to the
 243        one of the thread's server.
 244      FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
 245        under the FRSH
 246      FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
 247        main scheduler
 248      FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
 249        an application defined scheduler different than the frsh scheduler
 250      FRSH_ERR_NOT_CONTRACTED_SERVER : if the thread is bound and its server
 251        is not valid
 252     ]
 253 */
 254
 255 int
 256 frsh_set_local_thread_sched_params
 257   (pthread_t                     thread,
 258    const frsh_sched_params_t  *sched_params);
 259
 260
 261 // frsh_get_local_thread_sched_params: this function stores the
 262 // local scheduling parameters of the specified thread in the variable
 263 // pointed to by sched_params
 264 /*
 265     [ERR@RETURNED:
 266      FRSH_ERR_BAD_ARGUMENT : if sched_params is NULL or the thread does
 267         not exist
 268      FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
 269        under the FRSH
 270     ]
 271 */
 272
 273 int
 274 frsh_get_local_thread_sched_params
 275   (pthread_t            thread,
 276    frsh_sched_params_t  *sched_params);
 277
 278
 279 #endif // _FRSH_HIERARCHICAL_H_